Contributing

Contributing#

A good pull request answers three questions: what biological or computational behavior changes, where that behavior lives in the package, and how the change is verified.

Development setup#

git clone https://github.com/Computational-Morphogenomics-Group/waxmorph.git
cd waxmorph
pip install -e ".[all]"
pre-commit install

Running tests#

pytest tests/

The default pytest configuration writes terminal and XML coverage reports for the waxmorph package. The full suite exercises both the PyTorch and JAX backends, so a development environment should install .[all], or at minimum .[learning,simulation,jax], before running it.

Code style#

This project uses ruff for linting and black for formatting. Pre-commit hooks enforce style automatically:

pre-commit run --all-files

Pull requests#

  1. Create a feature branch from main.

  2. Make the changes and add tests.

  3. Run pytest, ruff check waxmorph tests, and black --check waxmorph tests locally.

  4. Open a pull request against main.

When Torch and JAX share a behavioral contract, update both implementations and their agreement tests. Preserve documented differences in graph tuples, distance stabilization, loss families, PRNG, checkpoints, and Warp bridges.

Documentation expectations#

Public functions should state which biological object they represent, the array shapes they expect, and whether gradients flow through the operation. Use the concrete state variables and shapes catalogued in Cells as spheroidal agents, together with the contact edges induced by spatial proximity. By convention, the per-cell molecular state is denoted c and the predicted increments are dX, dP, and dc.

When a modelling choice is an approximation, say so directly. For example, the contact graph is rebuilt from a detached state snapshot and treated as fixed within a rollout step, while the continuous node and edge features remain differentiable. That distinction matters when interpreting the learned biophysical update rules.

Docstring conventions#

Docstrings follow the Google style that Napoleon renders:

  • Open with an imperative one-line summary. Use “Build the contact graph …”. Focus the summary on the cell-state transition.

  • Let type hints carry types. Argument descriptions name the biological role and array shape, such as X (shape [N, 3]); autodoc_typehints = "description" renders the type.

  • Express physics with .. math:: blocks. When a function implements a governing equation (the soft-sphere force, the graph Laplacian, a reaction term, a Hill function), include that equation in a .. math:: block so the rendered docs match the notation X, P, R, c, dX, dP, dc.

  • Cross-link backend counterparts with See Also. A docstring on waxmorph.torch.<thing> should point to waxmorph.jax.<thing> and vice versa when both exist. State relevant interface or gradient differences.