stepsic

Initial condition generator for stereographic cosmological simulations

---

Overview

stepsic is both a universal cosmological initial condition generator and the dedicated IC generator for StePS. Its central purpose is geometry: StePS is the only existing cosmological simulation code that supports open spherical and open-plus-periodic cylindrical simulation volumes, and stepsic is the corresponding IC generator for those domains. This is the reason the codebase exists.

For ordinary periodic work, stepsic can also generate cubical or rectangular periodic boxes. For StePS, it constructs particle loads and perturbations in stereographically projected spherical and cylindrical geometries that conventional IC generators (2lptic, music, monofonic) do not cover.

The code implements Lagrangian perturbation theory through first and second order, includes a glass-making mode with no perturbations, and propagates displacement fields across the radially varying mass resolution intrinsic to stereographic projections. A constraint-field interface allows bitwise white-noise interoperability with monofonic for cross-validation.

Supported geometry families:

• Cubical/cuboid: standard boxes with arbitrary aspect ratios and configurable periodic axes.
• Spherical: open StePS $\mathbb{R}^3$ geometry for observer-centric, true zoom-in simulations.
• Cylindrical: StePS $S^1 \times \mathbb{R}^2$ geometry, periodic along the cylinder axis and open in the stereographic radial directions.

Installation

Conda source checkout

git clone https://github.com/eltevo/stepsic.git
cd stepsic
conda env create -f environment.yml
conda activate stepsic

The conda environment is intended for working from the repository root: running stepsic.py, opening the notebooks, and using the validation scripts without an additional editable install step.

Run the generator directly from the checkout:

python stepsic.py <config.toml>

Minimal Python install

If you only need the Python package and core runtime dependencies, use a Python 3.10+ environment and install from the repository:

pip install -e .

Core dependencies are numpy, scipy, astropy, h5py, CAMB, and colossus. Optional GADGET output requires glio.

Quick start

stepsic is a Python library with a repository-level driver. The importable package under stepsic/ contains the geometry, cosmology, field, LPT, IO, and parameter-validation machinery. The top-level stepsic.py script wires those library pieces into a complete initial-condition generator: it reads one TOML configuration, validates it, builds the particle load, applies perturbations when requested, and writes the output files.

Currently, this is the intended working behaviour. Use the library modules when you need individual building blocks, and use stepsic.py when you want the full, reproducible IC-generation workflow.

The configuration file is part of that interface. Start from Template-config.toml, and keep each run as a small, reviewable TOML file. A useful first run is a cubical grid IC. It does not require a pre-built glass, so it is the quickest way to check if your environment is working.

cp Template-config.toml my-ic.toml

In my-ic.toml, set at least the following values. The comments show the same contract that the code enforces at startup:

# Use the ordinary periodic-box path for a first smoke test.
GEOMETRY = "cubical"
TYPE = "grid"

# Build a small regular particle load, and use a modest FFT mesh for the
# displacement and velocity fields.
NGRID = 128
NMESH = 64

# Apply second-order Lagrangian perturbation theory. This is trivially
# preferred over Zel'dovich for any production run.
LPTORDER = 2

# Grid particles already sit on mesh points, so interpolation compensation is
# not necessary for this run.
COMPENSATE = false

# Keep the output directory easy to identify. Most important parameters
# of the run will be encoded in the output name after the prefix.
IC_PREFIX = "quickstart"

Then run the full application driver:

python stepsic.py my-ic.toml

During startup, stepsic.py delegates the TOML parsing and compatibility checks to the library parameter layer, then prints the resolved run parameters. The output directory is built from those parameters under output/; the main snapshot is written as ic.hdf5, together with the generated white-noise and Fourier-space density fields when perturbations are enabled. To inspect an HDF5 snapshot:

python validation/hdf5inspect.py output/<run-name>/ic.hdf5

For a production StePS run, the usual path is:

1. Generate an unperturbed pre-glass with GEOMETRY = "spherical" or "cylindrical", TYPE = "shell", and LPTORDER = 0.
2. Relax that load into a glass with StePS.
3. Run stepsic again with TYPE = "glass" and INPUT_GLASS pointing to the relaxed glass.
4. Use NMESH = 0 for adaptive multiscale displacements, or a positive NMESH for a single FFT mesh.
5. Run the StePS simulation with the generated initial conditions.

Configuration

All runtime settings live in one TOML file. The starting point is Template-config.toml, which is intentionally self-documenting; the notes below explain the decisions that most often affect whether a run is physically and numerically sensible.

Geometry and volume

GEOMETRY selects the domain. Use cubical for conventional boxes, spherical for open StePS spheres, and cylindrical for StePS cylinders. LBOX, PERIODIC, and COI define the box dimensions, boundary conditions, and center of interest. In StePS geometries, R_3D, D_4D, BIN_MODE, and NRBINS additionally define the stereographic projection and its radial mass-resolution bins.

For spherical runs, PERIODIC is effectively non-periodic in all directions. For cylindrical runs, the axial direction is periodic while the stereographic radial directions are open.

Particle load

TYPE controls the unperturbed particle distribution. grid and random are for cubical runs. shell builds stereographic spherical or cylindrical pre-glass loads and is mainly used with LPTORDER = 0. glass reads a pre-relaxed load from INPUT_GLASS; this is the normal starting point for science ICs in StePS geometries.

The particle-count controls depend on TYPE: NGRID for a regular cubical grid, NPART for a cubical random load, and NSHELL with NRBINS for shell loads. The template documents the valid combinations and the code validates them at startup.

Perturbations and resolution

LPTORDER = 0 writes the unperturbed particle load for glass-making. LPTORDER = 1 applies Zel'dovich displacements, and LPTORDER = 2 applies 2LPT. REDSHIFT sets the target initial redshift.

NMESH > 0 uses one FFT mesh for the displacement and velocity fields. NMESH = 0 activates the adaptive multiscale mode used for variable-resolution StePS glass ICs. The NMESHSAMPLES parameter sets the number of sampled mesh levels. INTERPOLATION chooses the grid-to-particle assignment kernel (ngp, cic, or tsc), and COMPENSATE applies the corresponding compensation kernel (Cloud-in-Cell does not need compensation).

SEED, PAIRED, and PHASE_SHIFT control random phases and paired ICs for variance-reduction tests.

Cosmology, spectrum, units, and output

COSMOLOGY selects a built-in parameter set from stepsic/config/cosmology.toml; any explicitly set cosmological parameter in the run config overrides the selected baseline. SPECTRUM = "camb" computes the linear power spectrum internally, while SPECTRUM = "input" reads a tabulated spectrum from INPUT_SPECTRUM.

COMOVING, HINDEPENDENT, and the UNIT_* parameters define the unit conventions. The defaults are chosen for StePS-compatible internal units.

IC_DIR, IC_PREFIX, IC_FORMAT, and USE_DOUBLE control where outputs are written and in which precision/format. The run directory name encodes the geometry, resolution, redshift, and LPT settings so multiple runs can share one base output directory.

Validation

The validation/ directory contains end-to-end pipelines that reproduce every figure in the paper:

Pipeline	What it tests
grid/	P(k) recovery vs. resolution, redshift, LPT order, MAS
squish/	Sub-percent P(k) recovery in anisotropic boxes up to 10:1
cylinder/	Full StePS N-body 1LPT vs. 2LPT in cylindrical $S^1 \times \mathbb{R}^2$ geometry
monofonic/	Cross-validation against monofonic using identical white noise
shell-mass/	Radial particle-mass profile across binning modes
particle-load/	All four particle-load configurations visualised
field/	Displacement / velocity field histograms (including slab anisotropy)

Run all pipelines at minimal resolution to verify your install:

bash validation/smoke-test.sh

Citation

If you use stepsic in published work, please cite:

@article{Pal2026stepsic,
    author        = {P{\'a}l, Bal{\'a}zs and R{\'a}cz, G{\'a}bor and Csabai, Istv{\'a}n and Szapudi, Istv{\'a}n},
    title         = {{stepsic}: {Initial} condition generator for stereographic cosmological simulations},
    year          = {2026},
    eprint        = {2605.10354},
    archivePrefix = {arXiv},
    primaryClass  = {astro-ph.CO},
}

Acknowledgements

Supported by the Hungarian NRDI Office (OTKA NN147550, NKKP-153428, 2025-1.1.5-NEMZ_KI-2025-0005), the KDP-2021 program, the Research Council of Finland (354905), the European Research Council (KETJU, No. 818930), and NASA ROSES (80NSSC24K1489, 24-ADAP24-0074). Computational resources were provided by CSC — IT Center for Science (Finland) and the Wigner Scientific Computing Laboratory (Hungary).