Contributing to COCAL#

Thanks for your interest in improving COCAL. This is a numerical-relativity solver where a silent change in the last digits can mean wrong physics, so the workflow is built around not breaking the numbers.

Golden rules#

  1. Keep the regression gates green. Every change must pass:

    • the fast numerics gate — ctest --test-dir build -L fast, and

    • the end-to-end physics gate — bash tests/e2e/run_e2e.sh (or sbatch ci/slurm_e2e_gpu.sbatch on GPU), which compares physics scalars to the checked-in baseline at 1e-12.

  2. Never refactor without the e2e gate. A behavior-preserving change must not move the baseline. If it does, that is a regression — investigate, don’t refresh the baseline.

  3. Format as you touch. Run .clang-format on files you edit; do not reformat unrelated code in the same change.

  4. No build on the login node. See COCAL — Compact Object CALculator; submit builds to a compute node.

Setup#

  • Backend and dependency configuration is centralized in scripts/cocal_build_env.sh; select a backend with COCAL_KOKKOS_VARIANT (cpu | ada89 | hopper90).

  • Install the pre-commit hooks with pre-commit install; the configuration is in .pre-commit-config.yaml.

Pull requests#

  • Branch from main (or the active yuxi/** work branch).

  • Keep pull requests focused; describe what changed and how you verified the gates.

  • Conventional-commit-style subjects are appreciated (build:, test:, docs:, refactor: and similar).

  • CI runs the fast gate on every push; run the e2e gate yourself for anything touching solver logic.

Reporting issues#

Use the issue templates under .github/ISSUE_TEMPLATE/. For numerical

discrepancies, include the run configuration (parameter flag, EOS, thread count, and COCAL_KOKKOS_VARIANT) and the failing scalar(s) with got/want/rel.