Developer guide

This page documents the internal organisation of GASM-or for contributors.

Architecture

The package is split into a platform-agnostic core and two back-ends:

  • gasm.api – input validation, attribute assembly and platform dispatch for gasm.match().

  • gasm.graph – conversion of a networkx.Graph into the sparse incidence structures R (undirected) or S and T (directed), density and diameter computations, and the complement procedure.

  • gasm.attributes – the vertex distance matrix V and edge distance matrix E (eq. 6-10).

  • gasm.convergence – the adaptive convergence criterion.

  • gasm.metrics – the accuracy and structural-quality metrics.

  • gasm.matching – the gasm.Matching result object.

  • gasm.cpu.core – the reference CPU iterations (eq. 15-31).

  • gasm.gpu.core – the OpenCL iterations, with the kernels in gasm/gpu/kernels/gasm.cl.

  • gasm.lap – the extensible registry of LAP solvers.

The notations follow the reference article; equation numbers are quoted in the source where relevant.

Running the tests

The test suite lives in benchmark/tests and uses pytest:

pip install -e ".[dev]"
pytest benchmark/tests

The GPU tests are skipped automatically when no OpenCL device is available.

Benchmarks

The benchmark scripts in benchmark import the local package and offer a quick mode (fast, indicative results) and a full mode (paper-scale results):

python benchmark/accuracy_quality.py --mode quick
python benchmark/speed.py --mode full --platforms CPU GPU

Building the documentation

The documentation is built with Sphinx:

sphinx-build doc/source doc/build

Before each build, check that the version (release in doc/source/conf.py) is consistent with the package version in pyproject.toml; conf.py reads it from the installed package.

Releasing

Releases are published to PyPI automatically by the GitHub Actions workflow .github/workflows/publish.yml when a GitHub release is published, using PyPI Trusted Publishing (OIDC). The release flow is:

  1. bump the version in pyproject.toml;

  2. create a GitHub release/tag;

  3. the workflow builds the distributions and uploads them to PyPI.