Contributing

dkx is maintained as scientific software: code, tests, benchmarks, and documentation are expected to evolve together.

Repository layout

  • dkx/: Python package code

  • tests/: unit tests and frozen reference fixtures (including some PETSc binaries)

  • examples/: pedagogic scripts organized by workflow category

  • docs/: Sphinx docs (Read the Docs compatible)

Development workflow

  1. Implement or refactor one coherent capability.

  2. Add or update tests with stable fixtures.

  3. Update the docs if public behavior, physics scope, or workflow changed.

  4. Keep changes focused and keep validation reproducible.

Reference fixtures

Some validation tests use PETSc binary matrices/vectors or HDF5 outputs generated by an established Fortran reference executable. To regenerate those fixtures locally, you must have a working build and set:

export SFINCS_FORTRAN_EXE=/path/to/sfincs/fortran/version3/sfincs

Then run an example input with saveMatricesAndVectorsInBinary = .true. enabled.

Required checks before shipping

At minimum, contributors should run:

pytest -q
sphinx-build -W -b html docs docs/_build/html

If a change touches performance-sensitive logic, also run the relevant benchmark or example-case gate and update the documented results when needed.