RNS Documentation

RNS Documentation#

This page is a markdown adaptation of the bundled RNS manual included with the ACME-RNS materials as rns_build/manual.pdf and rns_build/manual.tex. It is intended to complement the existing tutorial notebook, not replace it.

RNS constructs equilibrium models of rapidly rotating relativistic compact stars with uniform rotation. The code follows the KEH method with the modifications introduced by Cook, Shapiro, and Teukolsky, and it supports both individual models and sequences of models.

What RNS Does#

RNS computes uniformly rotating relativistic stellar configurations using either:

  • a tabulated zero-temperature equation of state, or

  • a polytropic equation of state.

It can build:

  • single models at fixed central energy density plus one additional parameter,

  • nonrotating and Keplerian limit models,

  • sequences of models over a range of central energy densities.

The ACME notebook drives the compiled C executables from Python through rns_helpers.py, but the underlying physical solver is still the original RNS code in rns_build/.

Repository Layout In This Tutorial#

The relevant local files are:

rns/
  intro.md
  RNS_Tutorial.ipynb
  rns_helpers.py
  rns_build/
    rns.c
    rns
    rns_high
    rns_vh
    rns_xh
    hng
    HnG.c
    manual.pdf
    manual.tex
    examples.test
    eos/

rns_build/#

This directory contains the original C solver, multiple compiled binaries at different resolutions, the EOS tools, and the original manual.

rns_helpers.py#

This is the Python bridge used by the notebook. It wraps the command-line executable, parses printed output, and exposes single-model and sequence computations in Python-friendly form.

Build And Installation#

Create the conda environment used by the tutorial:

conda env create -f environment.yml
conda activate acme-rns

Then build the RNS executables:

cd rns_build
make

This produces the standard executable and higher-resolution variants:

  • rns

  • rns_high

  • rns_vh

  • rns_xh

  • hng

The notebook wrapper expects those binaries and the eos/ directory to live under rns_build/.

Equations Of State#

RNS supports two EOS modes.

Tabulated EOS#

For a tabulated EOS, the file format described in the manual is:

  • first line: number of tabulated points,

  • remaining lines: four columns containing

    • energy density in g/cm\(^3\),

    • pressure in dyn/cm\(^2\),

    • enthalpy in cm\(^2\)/s\(^2\),

    • baryon number density in cm\(^{-3}\).

The enthalpy is defined in the manual as

\[ H(P)=\int_0^P \frac{c^2\, dP}{\epsilon + P} . \]

Example EOS tables such as eosC are included in rns_build/eos/.

Use a tabulated EOS with:

./rns -f eos/eosC

Polytropic EOS#

RNS can also construct polytropic stars. The manual gives the EOS as

\[ p = K \rho_0^{1 + 1/n} . \]

To request a polytropic model, use:

./rns -q poly -N 1.0

For polytropes, the program uses the dimensionless units described by Cook, Shapiro, and Teukolsky, and the reported quantities are correspondingly dimensionless.

EOS Conversion Utility#

The bundled HnG.c program converts a pressure-versus-energy-density EOS table into the four-column format required by RNS. The compiled helper binary is hng.

Model Parameters And Command-Line Options#

RNS defines a model with two parameters:

  1. the central energy density,

  2. one additional quantity such as axes ratio, mass, rest mass, angular velocity, or angular momentum.

The main parameter flags from the manual are:

Flag

Meaning

Units

-e

central energy density

g/cm\(^3\)

-r

axes ratio \(r_p/r_e\)

dimensionless

-m

gravitational mass

\(M_\odot\)

-z

rest mass

\(M_\odot\)

-o

angular velocity

\(10^4\) s\(^{-1}\)

-j

angular momentum

\(G M_\odot^2 / c\)

-b

tolerance for matching the second parameter

relative error

-a

iteration accuracy

relative error

-c

relaxation factor

dimensionless

-d 0

suppress iteration progress printout

n/a

`-p 1

2

3`

The manual notes that specifying the axes ratio with -r is the fastest way to obtain a model, because the code directly constructs that case. If a different target quantity is specified, RNS iterates over candidate models until it finds one within the requested tolerance.

Tasks#

The manual lists eight supported tasks.

Task flag

Purpose

Required parameters

-t model

fixed central density and axes ratio

-e, -r

-t gmass

fixed central density and gravitational mass

-e, -m

-t rmass

fixed central density and rest mass

-e, -z

-t omega

fixed central density and angular velocity

-e, -o

-t jmoment

fixed central density and angular momentum

-e, -j

-t static

nonrotating model for a given central density

-e

-t kepler

mass-shedding model for a given central density

-e

-t test

built-in test model

EOS only

Example Commands#

Single model at fixed axes ratio:

./rns -f eos/eosC -t model -e 2e15 -r 0.59 -d 0

Built-in test case:

./rns -f eos/eosC -t test

Nonrotating model:

./rns -f eos/eosC -t static -e 2e15

Keplerian model:

./rns -f eos/eosC -t kepler -e 2e15

Sequences#

RNS can compute sequences by specifying:

  • a starting central energy density,

  • an ending central energy density,

  • the number of models.

The manual example is:

./rns -f eos/eosC -t model -e 1e15 -l 3e15 -n 10 -r 0.7

Here the models are equally spaced in \(\log \epsilon_c\).

The manual also warns that not every requested sequence exists over every density interval. For example, constant-rest-mass sequences should be chosen only after checking that the desired rest mass exists across the requested density range.

Output Quantities#

The manual states that RNS prints 17 physical quantities for a successfully computed model. The most important are:

  • central energy density \(\epsilon_c\),

  • gravitational mass \(M\),

  • rest mass \(M_0\),

  • circumferential equatorial radius \(R_e\),

  • angular velocity \(\Omega\),

  • equatorial test-particle orbital angular velocity \(\Omega_p\),

  • rotational-to-gravitational energy ratio \(T/W\),

  • dimensionless angular momentum \(cJ/(G M_\odot^2)\),

  • moment of inertia \(I\),

  • quadrupole moment \(\Phi_2\),

  • co-rotating and counter-rotating ISCO heights \(h_+\) and \(h_-\),

  • polar and equatorial redshifts \(Z_p\), \(Z_b\), and \(Z_f\),

  • central frame-dragging ratio \(\omega_c / \Omega\),

  • coordinate equatorial radius \(r_e\),

  • axes ratio \(r_p / r_e\).

The manual also gives the stationary axisymmetric metric used by the code:

\[ ds^2 = -e^{\gamma+\rho} dt^2 + e^{2\alpha}(dr^2 + r^2 d\theta^2) + e^{\gamma-\rho} r^2 \sin^2\theta\, (d\phi - \omega dt)^2 . \]

Printing Formats#

RNS supports three print modes.

Flag

Format

Use

-p 1

detailed vertical list

default for single models

-p 2

compact horizontal table

useful for sequences

-p 3

full grid dump of metric potentials and pressure

for detailed inspection or post-processing

For -p 3, the output columns are:

  • \(s = r / (r + r_e)\),

  • \(\cos\theta\),

  • \(\rho\),

  • \(\gamma\),

  • \(\alpha\),

  • \(\omega\),

  • pressure.

Because -p 3 is large, it is best redirected to a file.

Numerical Grid#

The manual describes a uniform 2D grid in the variables

\[ s = \frac{r}{r + r_e}, \qquad \mu = \cos\theta . \]

The default grid size is:

\[ MDIV \times SDIV = 65 \times 129 . \]

The manual notes that these values can be changed in the Makefile. Larger grids may require increasing the stack size on Unix-like systems.

In the local ACME build directory, the precompiled variants rns_high, rns_vh, and rns_xh provide higher-resolution runs for cases where the standard resolution is not sufficient.

Python Wrapper In This Tutorial#

The notebook does not call the C executable manually. It uses rns_helpers.py, which provides a thin wrapper around the RNS binaries.

The wrapper exposes:

  • run_rns(...) for a single computation,

  • run_sequence(...) for sequence computations,

  • convenience helpers for common sequence types,

  • parse_metric_grid(...) for -p 3 output,

  • load_eos(...) for EOS plotting.

The wrapper assumes:

  • the build directory is rns_build/,

  • binaries such as rns, rns_high, and rns_vh already exist,

  • EOS files live in rns_build/eos/.

Short API Reference#

Helper

Signature

Key arguments

run_rns

run_rns(task="static", eos=None, *, polytrope_N=None, e=None, e_max=None, n=1, r=None, M=None, M0=None, Omega=None, J=None, p_format=1, accuracy=None, fix_error=None, cf=None, grid="std", timeout=300.0, quiet=True)

task: RNS task; eos: EOS name or path; e: central density; r, M, M0, Omega, J: second model parameter; p_format: 1, 2, or 3; grid: std, high, vh, xh

run_sequence

run_sequence(...)

same physical parameters as run_rns, but with e_max and n for sequences

parse_metric_grid

parse_metric_grid(...)

parse -p 3 output into structured arrays or tables

load_eos

load_eos(file)

EOS filename or path for plotting and inspection

set_build_dir

set_build_dir(path)

override the default rns_build/ location

Relationship To The Existing Tutorial#

The existing notebook remains the interactive guide:

This page is the manual-derived reference layer that explains:

  • what the RNS executable expects,

  • what the command-line flags mean,

  • what physical quantities it outputs,

  • how the local Python wrapper maps those command-line runs into notebook-friendly objects.

References#

  • Bundled RNS manual: rns_build/manual.pdf

  • ACME-RNS repository: niksterg/acme-rns

  • Stergioulas, N. and Friedman, J. L. 1995, ApJ 444, 306

  • Komatsu, H., Eriguchi, Y., and Hachisu, I. 1989, MNRAS 237, 355

  • Cook, G. B., Shapiro, S. L., and Teukolsky, S. A. 1994, ApJ 422, 227

Contents