We welcome contributions to Finch, and follow the Julia contributing guidelines. If you use or want to use Finch and have a question or bug, please do file a Github issue! If you want to contribute to Finch, please first file an issue to double check that there is interest from a contributor in the feature.

Versions

Finch is currently in a pre-release state. The API is not yet stable, and breaking changes may occur between minor versions. We follow semantic versioning and will release 1.0 when the API is stable. The main branch of the Finch repo is the most up-to-date development branch. While it is not stable, it should always pass tests.

Contributors will develop and test Finch from a local directory. Please see the Package documentation for more info, particularly the section on developing.

To determine which version of Finch you have, run Pkg.status("Finch") in the Julia REPL. If the installed version of Finch tracks a local path, the output will include the path like so:

Status `~/.julia/environments/v1.9/Project.toml`
  [9177782c] Finch v0.5.4 `~/Projects/Finch.jl`

If the installed version of Finch tracks a particular version (probably not what you want since it will not reflect local changes), the output will look like this:

Status `~/.julia/environments/v1.8/Project.toml`
  [9177782c] Finch v0.5.4

Utilities

Finch include several scripts that can be executed directly, e.g. runtests.jl. These scripts are all have local Pkg environments. The scripts include convenience headers to automatically use their respective environments, so you won't need to worry about --project=. flags, etc.

Testing

All pull requests should pass continuous integration testing before merging. The test suite has a few options, which are accessible through running the test suite directly as ./test/runtests.jl.

Finch compares compiler output against reference versions.

If you have the appropriate permissions, you can run the FixBot github action on your PR branch to automatically generate output for both 32-bit and 64-bit builds.

If you run the test suite directly you can pass the --overwrite flag to tell the test suite to overwrite the reference. Because the reference output depends on the system word size, you'll need to generate reference output for 32-bit and 64-bit builds of Julia to get Finch to pass tests. The easiest way to do this is to run each 32-bit or 64-bit build of Julia on a system that supports it. You can Download multiple builds yourself or use juliaup to manage multiple versions. Using juliaup, it might look like this:

julia +release~x86 test/runtests.jl --overwrite
julia +release~x64 test/runtests.jl --overwrite

The test suite takes a while to run. You can filter to only run a selection of test suites by specifying them as positional arguments, e.g.

./test/runtests.jl constructors conversions representation

This information is summarized with ./test/runtests.jl --help

Python test suite

finch-tensor contains a separate Array API compatible test suite written in Python. It requires Python 3.10 or later and Poetry installed.

It can be run with:

git clone https://github.com/willow-ahrens/finch-tensor.git
cd finch-tensor
poetry install --with test
FINCH_REPO_PATH=<PATH_TO_FINCH_REPO> poetry run pytest tests/

Benchmarking

The Finch test suite includes a benchmarking script that measures Finch performance on a variety of kernels. It also includes some scripts to help compare Finch performance on the feature branch to the main branch. To run the benchmarking script, run ./benchmarks/runbenchmarks.jl. To run the comparison script, run ./benchmarks/runjudge.jl. Both scripts take a while to run and generate a report at the end.

Documentation

The /docs directory includes Finch documentation in /src, and a built website in /build. You can build the website with ./docs/make.jl. You can run doctests with ./docs/test.jl, and fix doctests with ./docs/fix.jl, though both are included as part of the test suite.