This directory contains a proof-of-concept hardware accelerator generator for a simple GFA query. This section contains some guides for trying out this generator.
Running the hardware generator is easy if you use our Docker image:
docker run -it --rm ghcr.io/cucapra/pollen:latest
If you prefer to install locally, we point you to the somewhat more involved instructions below.
If you want to compute the depth of all the nodes in the graph, the following command will generate and run a node depth accelerator:
exine depth -a -r <filename.og>
This will automatically generate a node depth accelerator whose dimensions match the input data, compute the node depth, and remove the accelerator once the computation is done.
To save the files generated from the previous command in <path>, use the --tmp-dir flag:
exine depth -a -r <filename.og> --tmpdir <path>
The node depth accelerator will be saved at <path>/<filename.futil> and the input data will be saved at <path>/<filename.data>.
Take depth as an example. To generate and run a node depth accelerator for the graph k.og, first navigate to the root directory of this repository. Then run
make fetch
make test/k.og
exine depth -o depth.futil
exine depth -d test/k.og -o depth.data
exine depth -r depth.data --accelerator depth.futil
What just happened? Below, we walk through the five commands we issued above, pointing out the other options that we could have used.
First, make fetch downloads some GFA data files into the ./test directory.
Second, make test/*.og builds the odgi graph files from those GFA files.
Third, we generate the hardware accelerator and write it to a file named depth.futil. The commands to generate a node depth hardware accelerator in Calyx include:
exine depth -o depth.futilexine depth -a <filename.og> -o depth.futilexine depth -n=MAX_NODES -e=MAX_STEPS -p=MAX_PATHS -o depth.futil
The commands use the hardware parameters as follows:
- Uses default hardware parameters.
- Automatically infers the hardware parameters from a
.ogfile. - Takes the hardware parameters as input.
Parameters that are specified manually take precedence over those that are inferred automatically, and it is legal to specify just a subset of parameters. For example, exine depth -a test/k.og -n=1 will infer MAX_STEPS and MAX_PATHS from test/k.og, but the resulting accelerator will only handle one node.
Fourth, we need to generate some input from our odgi file. This is what we will feed to the hardware accelerator. The following variations all accomplish this:
exine depth -d <filename.og> -o depth.dataexine depth -d <filename.og> -a <filename2.og> -o depth.dataexine depth -d <filename.og> -n=MAX_NODES -e=MAX_STEPS -p=MAX_PATHS -o depth.dataexine depth -d <filename.og> -a -o depth.data
The flags work as before, except that if no argument is passed to the -a flag, the dimensions are inferred from the input file. The dimensions of the input must be the same as that of the hardware accelerator.
Fifth, we run our hardware accelerator. The following code simulates the Calyx code for the hardware accelerator and outputs the node depth table:
exine depth -r depth.data -x depth.futil
You will need Flit version 3.7.1 and Turnt version 1.11.0. We will guide you through the installation of our major dependencies, Calyx and odgi, and then show you how to install Pollen itself.
Below we show you how to build Calyx from source and set it up for our use. If you are curious, this tracks the "installing from source" and "installing the command-line driver" sections of the Calyx documentation.
git clone https://github.com/cucapra/calyx.gitcd calyxcargo buildflit -f fud/pyproject.toml install -s --deps productionfud config --create global.root $(pwd)cargo build -p interpfud config stages.calyx.exec $(pwd)/target/debug/calyxfud config stages.interpreter.exec $(pwd)/target/debug/interpflit -f calyx-py/pyproject.toml install -sfud check
You will be warned that synth-verilog and vivado-hls were not installed correctly; this is fine for our purposes.
We recommend that you build odgi from source, as described here.
To check that this worked, run odgi from the command line.
Some parts of Pollen presently use odgi's Python bindings.
You will need to edit your PYTHONPATH, as explained here, to enable this.
To verify that this worked, open up a Python shell and try import odgi.
If it succeeds quietly, great!
If it segfaults, try the preload step explained here.
Clone this repository:
git clone https://github.com/cucapra/pollen.git
And then install the Python tools using uv:
$ uv venv
$ uv pip install -r requirements.txt
$ source .venv/bin/activate