Contributing

Contributing#

Useful contributions are small enough to review and strong enough to reproduce. You can improve core numerics, add an analytical invariant, port a representative FDTD example, sharpen documentation, or reproduce a published case on different hardware.

Development setup#

uv sync --extra gpu --extra dev --extra docs
uv run python scripts/gpu_smoke.py
uv run fdtdx-bench smoke

Work primarily in solver/src/fdtdx/. Keep comparison adapters and external-reference reductions in benchmarks/.

Change workflow#

  1. Read the case YAML and its last structured result.

  2. Reproduce the failure without changing tolerances.

  3. Decide whether the cause is numerical physics, an adapter convention, or an untrustworthy reference.

  4. Make the smallest coherent correction.

  5. Run the target case, then the complete smoke suite.

  6. Refresh fdtdx-bench report and public docs when the capability boundary changes.

Add a benchmark#

A new case needs a catalog entry, local YAML, runner, declared metrics, and a defensible reference. If it is coarser than a golden, document the resolution scaling formula in YAML. A Tidy3D-backed inverse-design case must declare objective, reference FOM/iterations, multiplier, and FOM ratio.

Never delete an inconvenient benchmark or loosen a threshold simply to pass. If the question cannot be answered after sustained work, preserve the case as blocked with a specific reason.

Documentation#

Generate the case atlas and figures, then build strictly:

uv run python scripts/generate_public_docs.py
uv run --extra docs sphinx-build -W --keep-going -b html docs/site build/docs-site

Add conceptual explanation only where it is supported by implementation or a cited physical identity. Keep validation numbers generated from progress.json when possible.

Style#

  • Python 3.12+, type annotations for new public code;

  • ruff for formatting/lint checks;

  • one logical change per commit;

  • commit message format: case=<id> metric=<name> before=.. after=...

Research reproducibility#

When reporting a result, include the repository commit, accelerator/JAX versions, grid, boundary condition, runtime/termination, material model, source/detector convention, and output artifact hash. “Ran with FDTDX” is not enough to reproduce a full-wave result.