Rapidly Rotating Neutron Star#

The rapidly rotating neutron star (RNS) gallery is the canonical compact-object validation case for KCOCAL. It covers the stationary, axisymmetric stellar sequence problem in the Waveless (WL) and conformally flat (CF) formulations, with the WL family being the primary working path for the modernized C++ solver.

The examples in this page are intended to be self-contained: they show the supported module layout, the runtime knobs that choose physics, and the exact commands used to launch a local or SLURM run.

Quick start#

Start from the normal KCOCAL setup flow in Setting up COCAL and Running on a Cluster. For a standard RNS run, configure the backend, choose a rotation law, and submit one sequence:

cp config.template.sh config.sh
export COCAL_KOKKOS_VARIANT=hopper90
export COCAL_ROT_LAW=DR
export COCAL_PARAM_FLAG=H3
export COCAL_NUM_SOL_SEQ=35
./scripts/submit.sh run

This is the shortest path to a production-quality sequence. If you are working on an ordinary workstation without SLURM, the same physical choices can be driven by an unmapped Riemann runner instead of submit.sh.

RNS modules and runners#

The repository exposes three solver modules, but the RNS gallery is built from the RNS family specifically:

RNS-WL: rotating neutron star, waveless - executable: pRNS_WL - local runner: scripts/riemann_rns_wl.sh - SLURM runner: scripts/delta_rns_wl.sbatch
RNS-CF: rotating neutron star, conformally flat - executable: pRNS_CF - local runner: scripts/riemann_rns_cf.sh - SLURM runner: scripts/delta_rns_cf.sbatch

The working leg is the RNS-WL path. The Delta RNS scripts are thin wrappers that reuse the proven cocal_run.sbatch body, but the main validated path to date is still the Riemann runner or the established build/run scripts from the quick start guide.

Choosing the physics#

Run-time physics are chosen with environment variables. The main ones are:

COCAL_ROT_LAW (default UR): UR for uniform rotation or DR for
type-0 differential rotation.
COCAL_NUM_SOL_SEQ (default 1): number of solutions in the sequence.
COCAL_ITER_MAX (default 2000): iteration cap per solution.
COCAL_PARAM_FLAG (default H3): parameter set from
parameter_sample/RNS_CF/.
COCAL_KEEP_RUN_DIR (default 1): whether to keep the run directory.
COCAL_EPS (unset by default): convergence tolerance; otherwise the value
from rnspar.dat is used.

The available values are a physics choice, not a performance switch. The supported behavior is:

RNS-WL accepts both UR and DR.
RNS-CF is UR-only and aborts loudly if DR is requested.

This is an important guardrail: the conformally flat formulation is not expected to solve the same differential-rotation parameter set as the waveless branch.

The usual sequence commands are therefore:

export COCAL_ROT_LAW=UR
export COCAL_ROT_LAW=DR

and for a direct single-sequence test:

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

Parameter families and EOS choices#

The RNS tests are parameterized by both the parameter family and the EOS sample. The main runtime variables are:

COCAL_PARAM_FLAG: chooses the parameter set, commonly H2, H3 or H4. The default is H3.
COCAL_NUM_SOL_SEQ: number of solutions in the sequence.
COCAL_ITER_MAX: iteration cap for a single solution; if unset, the default value from the solver deck is used.
COCAL_EPS: convergence tolerance override if you want to supersede the deck value.

Typical examples:

export COCAL_PARAM_FLAG=H2 COCAL_ROT_LAW=UR COCAL_NUM_SOL_SEQ=27
export COCAL_PARAM_FLAG=H3 COCAL_ROT_LAW=DR COCAL_NUM_SOL_SEQ=35
export COCAL_PARAM_FLAG=H4 COCAL_ROT_LAW=UR COCAL_NUM_SOL_SEQ=3

Local execution (Riemann runners)#

On a shared machine without SLURM, launch the Riemann runner detached and let it log to a file. These are the standard examples in the repo:

nohup scripts/riemann_rns_wl.sh parallel 8 > /tmp/rns-wl.log 2>&1 &
nohup scripts/riemann_rns_cf.sh serial > /tmp/rns-cf.log 2>&1 &

The parity between the script helpers and the SLURM launchers is intentional: Riemann is the plain-script path for local development, while Delta routes the same physics through the cluster-aware scheduler.

Delta / SLURM execution#

Delta uses the submit.sh wrapper, which turns your local config.sh into SLURM flags. The module is selected through the environment variable COCAL_MODULE:

export COCAL_MODULE=rns-wl    # default for the RNS family
export COCAL_KOKKOS_VARIANT=hopper90
export COCAL_ROT_LAW=DR
export COCAL_NUM_SOL_SEQ=35
./scripts/submit.sh run

You can also force specifically:

export COCAL_MODULE=rns-cf
export COCAL_KOKKOS_VARIANT=mi100
export COCAL_ROT_LAW=UR
export COCAL_NUM_SOL_SEQ=27
./scripts/submit.sh run

The exact backend and build tree are controlled by COCAL_KOKKOS_VARIANT; common values are cpu, cpu<N>, hopper90, and mi100.

Where outputs go#

The run directory is created under the build tree and contains the staged inputs, output directories, and per-solution files. The log output is captured in logs/ at the repository root as a <job-name>_<job-id> pair.

A typical layout is:

logs/cocal-DR-hopper90_20253856.out
logs/cocal-DR-hopper90_20253856.err
build-hopper90/RNSH3_K180.7_run_20253856/
      run.log -> ../../logs/cocal-DR-hopper90_20253856.out
      work_area_RNS_seq/sol_01/ ... sol_35/

The main validation object is the final sequence of solution files, typically .las field data under each sol_NN directory.

Reproducing validated tests#

The validated test matrix used for regression checks is reproduced here for convenience. Use the matching COCAL_KOKKOS_VARIANT, rotation law, and COCAL_NUM_SOL_SEQ to recreate these runs.

Validation workflow#

Use the standard project gates to compare the result against the checked-in physical baseline:

Run the fast unit tests with ctest --test-dir build -L fast.
Run the end-to-end host/GPU physics test with bash tests/e2e/run_e2e.sh.
Run the SLURM GPU gate with sbatch ci/slurm_e2e_gpu.sbatch.

The RNS examples are expected to reproduce the reference star equilibrium and sequence structure to machine precision in the gated validation suite.