COCAL — Compact Object CALculator#

COCAL is a numerical-relativity solver for stationary, axisymmetric and triaxial compact objects — here, rapidly rotating neutron stars computed in the Waveless (WL) formulation of Einstein’s equations with a piecewise-polytropic equation of state (peos), solved by self-consistent field (SCF) iteration on multi-domain spherical-coordinate patches.

This repository is a C++/ Kokkos port and modernization of the original Fortran COCAL code, targeting host (OpenMP), NVIDIA GPU (CUDA) and AMD GPU (HIP) execution from a single source. The original Fortran lives under reference/legacy-fortran/ as a frozen reference.

Layout#

Path

What

src/cocal/, include/cocal/

The C++/Kokkos solver library, grouped by module

apps/pRNS_WL/

The solver executable (main.cpp)

tests/

Unit (smoke) + end-to-end gates

scripts/

Build + run helpers (Kokkos installs, compute-node builds)

ci/

SLURM GPU regression gate

parameter_sample/

Sample parameter / EOS inputs (RNS_CF, EOS)

reference/legacy-fortran/

Frozen original Fortran (Cocal/, COCAL_reader/)

docs/

Design spec, testing guide, architecture notes

Building and running#

You are given an sw-build (the prebuilt Kokkos installs); you point your config.sh at your copy of it and compile COCAL. See Installing KCOCAL for the full guide. The short version:

cp config.template.sh config.sh        # once: then set COCAL_KOKKOS_ROOT + account
export COCAL_KOKKOS_VARIANT=hopper90   # cpu | cpu35 | hopper90 | mi100
./scripts/submit.sh build              # compile pRNS_WL against the Kokkos install
# wait for that job to finish -- they share a build tree (SETUP.md)
./scripts/submit.sh run                # recompile incrementally and solve

The backend is chosen entirely by which Kokkos install you build against — there is no separate CUDA switch:

Variant

Backend

Hardware

cpu

Serial + OpenMP

any host

cpu<N>

Serial + OpenMP, N threads

any host — cpu1, cpu35 (same build as cpu)

ada89

CUDA sm_89

RTX 4080 / L40S / Ada

hopper90

CUDA sm_90

H100 / H200 / Hopper

mi100

HIP gfx908

AMD Instinct MI100

config.sh is the one file you edit — copy it from the tracked config.template.sh template, then set COCAL_KOKKOS_ROOT to your copy of sw-build and COCAL_SLURM_ACCOUNT to your allocation; every field has a comment showing the command to find its value on your cluster. Your config.sh is gitignored, so your paths never get committed and a pull never clobbers them. (The compiler and Kokkos arch flags per backend live in scripts/cocal_build_env.sh; you only touch that to add a new GPU arch.)

The physics of a run is set with plain env vars — COCAL_ROT_LAW (UR/DR) and COCAL_NUM_SOL_SEQ:

export COCAL_ROT_LAW=DR COCAL_NUM_SOL_SEQ=35
./scripts/submit.sh run

Warning

Do not compile on a login node — the heavy Kokkos translation units exhaust its per-user memory and the compiler is killed. submit.sh always builds on a compute node.

Regression gates#

Three gates, fastest first — see Testing and regression gates.

  1. Fast unit — numerics golden tests: ctest --test-dir build -L fast.

  2. End-to-end (host/GPU) — full bar-C run vs the checked-in physics baseline at 1e-12: bash tests/e2e/run_e2e.sh.

  3. GPU e2e via SLURM — sbatch ci/slurm_e2e_gpu.sbatch.

Host CI (.github/workflows/ci.yml) runs gate 1 on every push.

License#

MIT © The COCAL Collaboration. The physics and original algorithms originate with Kōji Uryū and collaborators; please cite the COCAL papers when using this code (see Citation).

Contributing#

See Contributing to COCAL. In short: keep the regression gates green, format-as-you-touch (.clang-format), and never refactor without the e2e gate.

Quick Start Guide

Gallery Examples

Development