Initial conditions and particles

See also the initial-condition overview.

Generator selection

Parameter	Default	Behaviour
IC generator	basic	Selects basic, read from disk, or express. Recognition is case-insensitive and based on the leading characters.
initial redshift	required	Simulation starting redshift.
relaxation redshift	initial redshift	Above this redshift the frame-dragging force on particles is ignored.
seed	0	Random seed used by generated perturbations and compatible CLASS-based linear species.
correct displacement	no	A leading y/Y enables template-aware displacement correction.
k-domain	cube	A leading s/S selects the largest sphere fitting inside the Fourier cube; other modes are zero.

prevolution and FalconIC are rejected explicitly. RELIC is available only in builds with ICGEN_RELIC and is not a default production-supported workflow.

For a fixed seed and boxsize, the basic generator creates the same realisation for Fourier modes shared by different resolutions. This is useful for resolution studies with reduced cosmic-variance differences.

correct displacement requires a compatible template

The particle template must be invariant under the relevant simulation lattice symmetries. An incompatible template can produce incorrect initial data or fail during generation.

Templates and particle ensembles

Parameter	Required for	Behaviour
template file	Generated particle ICs	Gadget-2 homogeneous template files. Missing later entries repeat the last filename.
tiling factor	Generated particle ICs	Repetitions per direction. Missing later entries repeat the last value; default is 1.
particle file	read from disk and express	Particle inputs. At least one is required; missing later entries become /dev/null.
metric file	Optional disk input; required by some specialised generators	Up to three metric files used by disk/restart-style input.
density file, velocity file	Optional specialised generators	Inputs for workflows such as RELIC, when compiled.

The assignment order is CDM, separate baryons when baryon treatment = sample, then non-CDM species. For a template containing \(N_\mathrm{template}\) particles,

\[ N_\mathrm{particles} = N_\mathrm{template}(\mathtt{tiling\ factor})^3. \]

The CDM tiling factor must be positive. A zero tiling factor is allowed for a non-CDM species and suppresses its particle ensemble, allowing a linear-only treatment. Negative values are corrected to 1.

The supplied v1.3-style crystals include body-centred cubic (bcc, 16 particles), face-centred cubic (fcc, 32), and two simple-cubic templates (sc0 and sc1, 64). sc0 and sc1 differ in their alignment relative to the simulation lattice.

Transfer-function inputs

Parameter	Behaviour
Tk file	CLASS-format synchronous-gauge transfer functions at the initial redshift. The table must cover all simulation modes.
mPk file	CLASS-format synchronous-gauge matter power spectrum. It takes precedence over Tk file.
A_s, n_s, k_pivot	Primordial amplitude, scalar index, and pivot scale; needed when generating perturbations from transfer functions or CLASS.

If neither mPk file nor Tk file is supplied, a build with HAVE_CLASS calls CLASS directly. Without CLASS, omission is fatal.

mPk file is a backwards-compatible but less informative input: it cannot assign species-dependent perturbation amplitudes, initial velocities use the matter-era Zel'dovich approximation, and baryon treatment is forced to ignore. Calling CLASS directly is preferred when possible.

The basic generator transforms synchronous-gauge transfer functions to the simulation gauge. For Newtonian runs, supplying a standalone Tk file only permits the position transformation to N-body gauge; transforming velocities requires time derivatives of transfer functions. Calling CLASS directly avoids this limitation.

Baryon treatment

Value	Particle representation and initial perturbations
ignore	Baryons behave as CDM; no separate baryon ensemble or baryon transfer functions.
sample	A separate baryon particle ensemble uses its own transfer functions.
blend	Default for generated ICs. One cold ensemble uses a density-weighted blend of CDM and baryon transfer functions.
hybrid	One cold ensemble uses an ID-dependent mixture; one particle in eight is maximally baryon-like.

For read from disk, the default is ignore. A supplied mPk file always forces ignore.

Reading from disk

particle file inputs use Poisson-gauge phase-space coordinates for GR runs and N-body-gauge coordinates for Newtonian runs. The current GPU reader supports Gadget-2 CDM/baryon input and specialised express input; HDF5 CDM/baryon input paths remain disabled in the reader.

If no initial metric file is supplied, the code derives the initial \(\phi\) from a particle-mesh projection using a linearised constraint. For a disk read with CLASS radiation or fluid perturbations, consistency of the linear realisation is not guaranteed unless the input carries compatible restart-style metadata.

For ordinary disk input, the first metric file is the optional \(\phi\) field. When cycle marks restart-style input, GR expects the legacy ordering \(\phi\), \(\chi\), \(B\); Newtonian restart-style input uses the first entry for \(B\). Missing files required by that restart-style path fail during loading.

Disk input is not a supported checkpoint workflow

The parser and reader retain fields such as cycle, tau, dtau, and multiple metric files. GPU hibernation writes are disabled, so these interfaces should be treated as specialised initial-data input rather than a fault-tolerant restart guarantee.