Running hi_class

Running hi_class

How to execute hi_class from the command line and how to structure an input file: the scalar-field (_smg) keys, the Ω_smg budget convention, the automatic tuning of theory parameters, the shipped example models, and a worked example reproducing a figure of the hi_class paper.

Running the code

hi_class runs exactly like CLASS: compile it (see Installation), then pass it an input file with extension .ini:

./class hi_class.ini
./class gravity_models/brans_dicke.ini

You can optionally append a precision file (.pre), e.g. ./class hi_class.ini cl_ref.pre.

hi_class.ini is the reference input file: it lists and documents every hi_class-specific parameter (standard CLASS parameters are documented in explanatory.ini). The files in gravity_models/ are ready-to-run examples for each implemented covariant theory (see the table below).

Where the output goes

All output files share a common prefix set by the root key, e.g.

root = output/test
overwrite_root = yes

produces output/test_cl.dat, output/test_pk.dat, and so on (an underscore is appended to the root). The behavior of the prefix depends on overwrite_root:

• overwrite_root = yes — files are written to <root>_... and overwrite previous runs.
• overwrite_root = no (the default) — the code appends the first free two-digit number, writing <root>00_cl.dat, then <root>01_cl.dat on the next run, and so on, so nothing is overwritten.
• If root is not given at all, the default is output/<name-of-your-ini-file> with the same numbering behavior.

The output directory must already exist. hi_class does not create directories: if output/ (or whatever directory your root points into) is missing, the run stops with an error like could not open ... with name output/test_cl.dat and mode "w". A fresh clone does not ship an output/ directory, so create it once with mkdir output before your first run.

Useful companions to root (all verified in this release; the older spelling with spaces, e.g. write parameters, is still accepted but deprecated):

• write_parameters = yes — writes <root>_parameters.ini (every parameter actually used, including tuned values — invaluable for reproducibility) and <root>_unused_parameters (keys the code did not recognize: check this file if a parameter seems to have no effect, a typo lands it here silently).
• write_background = yes — writes <root>_background.dat with the background table. The amount of scalar-field information in it is controlled by output_background_smg (0: ρ_smg, p_smg; 1: adds the α functions and stability variables c_s², D; 2: adds φ, φ′, φ″ and the Friedmann constraint, covariant theories only; 3: adds internal perturbation-related functions; higher values include all lower levels — the examples use output_background_smg = 10 to get everything). See Output files for the column-by-column description.

Anatomy of a hi_class input file

On top of the standard CLASS parameters (cosmological parameters, output, verbosity, ...), a hi_class run is specified by five _smg keys. hi_class distinguishes two families of models, which use these keys differently:

Key	Covariant theories	Parametrized models (EFT of dark energy)
gravity_model	Lagrangian-based theory, e.g. brans_dicke, galileon	parametrization of the α functions, e.g. propto_omega, constant_alphas
gravity_submodel	variant of the theory, when it has any (galileon → cubic, quartic, quintic; cccg_exp → normal_branch, canonical)	not used
parameters_smg	parameters of the Lagrangian; they fix both the expansion history and the perturbations	parameters of the α functions; they affect the perturbations only
expansion_model	not used — the expansion follows from solving the theory	required: lcdm, wowa (aka w0wa, cpl), wowa_w, or wede
expansion_smg	not used	required: the parameter values of the chosen expansion history (for lcdm a single number, Ω_smg itself; for wowa/wowa_w: Ω_smg, w₀, w_a; for wede: Ω_smg, w₀, Ω_ede)

In short: a covariant theory is a full scalar-tensor Lagrangian whose background is solved self-consistently, so parameters_smg is all it needs. A parametrized model instead specifies the linear-perturbation functions (α_K, α_B, α_M, α_T, M*²) on top of an expansion history that you must supply separately with expansion_model/expansion_smg. Both parameters_smg and expansion_smg are hard requirements where indicated: a missing vector stops the run with Entry 'expansion_smg' is required but not found! (and similarly for parameters_smg).

The catalogs of available models, with the meaning and ordering of every entry of parameters_smg, live on their own pages:

• Models: Covariant theories — brans_dicke, quintessence_monomial, quintessence_tracker, alpha_attractor_canonical, galileon (cubic/quartic/quintic), nkgb, cccg_exp.
• Models: Parametrized alphas — propto_omega, propto_scale, constant_alphas, eft_alphas_power_law, eft_gammas_power_law, eft_gammas_exponential.
• Models: Expansion history — lcdm, wowa, wowa_w, wede.

A minimal parametrized run therefore looks like

Omega_Lambda = 0
Omega_fld = 0
Omega_smg = -1

gravity_model = propto_omega
parameters_smg = 1., 0., 0., 0., 1.     # ĉ_K, ĉ_B, ĉ_M, ĉ_T, M*²_ini
expansion_model = lcdm
expansion_smg = 0.5                     # overwritten by the closure equation

output = tCl,pCl,lCl,mPk
root = output/test
overwrite_root = yes

The first three lines are explained next.

The Ω_smg closure convention

Omega_smg is the fractional energy density of the scalar today, and its value selects how the budget equation Σᵢ Ωᵢ = 1 + Ω_k is closed (section 1a of hi_class.ini):

• Omega_smg unspecified or 0 — the scalar field is switched off entirely; hi_class behaves as standard CLASS.
• 0 < Omega_smg < 1 — the scalar field is on with that density, and you must leave either Omega_Lambda or Omega_fld unspecified; the unspecified one is then inferred from the closure equation. This lets you run mixed scenarios (scalar field + Λ or + fluid dark energy).
• Omega_smg < 0 (e.g. -1, the most common choice) — the scalar field is the dark energy: you must set both Omega_Lambda = 0 and Omega_fld = 0 explicitly, and Ω_smg itself is inferred from the closure equation. With input_verbose ≥ 1 the code reports the value it needs: -> budget equations require Omega_smg = 6.8e-01.

In the last two cases hi_class must make the theory actually produce the required Ω_smg today, which it does by tuning one of the model parameters — see the next section.

Omega_smg_debug: running without tuning

For debugging and exploration you can bypass the tuning machinery (section 1b of hi_class.ini). Replace Omega_smg by Omega_smg_debug with a negative value, and leave Omega_smg, Omega_Lambda and Omega_fld all unspecified:

# Omega_Lambda, Omega_fld, Omega_smg: all unspecified
Omega_smg_debug = -1.

Omega_smg_debug is only read when Omega_smg is absent. The scalar field equations are used, but the code runs your parameters_smg exactly as given, with no shooting: the closure equation will not be satisfied unless your guess happens to be right (the budget is formally closed with Ω_Λ instead). This is the fastest way to explore how a theory's background behaves as you vary its raw parameters, and the recommended first step when the shooting fails to converge.

Tuning and shooting

For any model with Omega_smg set and nonzero, hi_class runs a shooting algorithm at input time: it repeatedly solves the background, comparing the resulting scalar density today with the required Ω_smg, and adjusts one entry of the tuned parameter vector until they match. Two keys control this (section 2d of hi_class.ini):

• tuning_index_smg — which entry (0-based) of the tuned vector is varied. For covariant theories this is an entry of parameters_smg; for parametrized models it is an entry of expansion_smg (for expansion_model = lcdm the default index 0 is Ω_smg itself, so the "tuning" is trivial).
• tuning_dxdy_guess_smg — the initial guess for how much the parameter moves per unit change of Ω_smg (a dx/dy for the first Newton step; default 1).

You rarely need to set these by hand: every covariant theory ships a sensible default tuning index and guess (e.g. quintessence_monomial tunes V₀, the cubic Galileon tunes c₃; the per-model defaults are listed in Models: Covariant theories), and each example .ini documents its choice. If you do override tuning_dxdy_guess_smg for a Galileon model you must also give tuning_index_smg explicitly — the code stops otherwise.

Some models additionally tune the effective Planck mass today: with M2_tuning_smg = yes a second target M2_today_smg is enforced by varying the parameter selected with tuning_index_2_smg (see gravity_models/brans_dicke.ini and gravity_models/cccg_exp_canonical.ini for worked configurations).

Reading the shooting output

Turn up the verbosity to watch the tuning converge:

• input_verbose = 3 (or higher) prints one line per shooting iteration:

   param[3] = -5.478327e+00, Omega_smg = 6.879e-01, 6.879e-01, target = -1.13e-04
  

  i.e. the current value of the tuned parameter (here entry 3 of parameters_smg), the Ω_smg it produced (measured relative to the critical density and relative to H₀², which differ if the closure is not yet satisfied), and the residual still to be shot away.

• background_verbose = 1 (or higher) makes each background run report the achieved versus requested density, -> Omega_smg = 0.687872, wanted 0.687872, followed by a model-specific printout of the final (tuned) parameter values. At background_verbose = 4 and above you also get the scalar-field initial conditions and the minimal values of the stability variables encountered during the evolution.

If you use write_parameters = yes, the tuned parameter values are recorded in <root>_parameters.ini (as parameters_smg and as shooting_parameter_smg), so a converged run can be reproduced later without repeating the search.

The shipped examples

The gravity_models/ directory contains 13 ready-made input files, one per covariant-theory configuration. All of them run out of the box with this release:

File	Model	What it demonstrates
alpha_attractor_canonical.ini	canonical α-attractor quintessence	best-fit parameters from García-García+18 (1803.00661); model-specific flag log_10_param_alpha; custom tuning_index_smg
brans_dicke.ini	Brans–Dicke	radiation-era attractor initial conditions (phi_prime_ini = 0); Planck-mass tuning with M2_tuning_smg, M2_today_smg, normalize_G_NR (Avilez+13 1303.4330, Bellini+17 1709.09135)
cccg_exp.ini	conformally coupled cubic Galileon, normal branch	gravity_submodel selection; imperfect dark energy at equality (Zumalacárregui 20 2003.06396); a_min_stability_test_smg to skip early-time numerical noise
cccg_exp_canonical.ini	conformally coupled cubic Galileon, canonical branch	canonical kinetic term + Λ; simultaneous Ω_smg and M*² tuning via tuning_index_2_smg
galileon_3.ini	cubic Galileon (tracker)	fully fixed by Ω_smg and the tracker condition — empty parameters_smg; best fit of Barreira+14 (1406.0485)
galileon_3nu.ini	cubic Galileon + massive ν	same theory with three degenerate massive neutrinos, best fit of Renk+17 (1707.02263)
galileon_4.ini	quartic Galileon	one extra parameter ξ ~ (H φ′)/(a H₀²); Barreira+14 best fit
galileon_4nu.ini	quartic Galileon + massive ν	Renk+17 best fit with massive neutrinos
galileon_5.ini	quintic Galileon	two parameters (ξ, c₃); Barreira+14 best fit
galileon_5nu.ini	quintic Galileon + massive ν	Renk+17 best fit with massive neutrinos
nkgb.ini	kinetic gravity braiding (nKGB)	shift-symmetric braiding model g(X/Λ⁴)ⁿ with "off-trackerness" parameter Rshift0 (Kimura+11 1110.3598, Deffayet+10 1008.0048)
quintessence_monomial.ini	monomial quintessence, V ∝ φᴺ	simplest covariant example; a_min_stability_test_smg to avoid the artificial α_K → 0 instability at φ′ → 0 (Marsh+14 1406.2301)
quintessence_tracker.ini	tracker quintessence, V ∝ φ⁻ⁿ e^{λφᵐ}	early-dark-energy-style tracker with initial kinetic/potential energies set relative to radiation

There is no separate example file for the parametrized models: hi_class.ini itself is the parametrized example (propto_omega with α_K = Ω_smg, all other αs zero — a ΛCDM-like baseline).

Worked example: reproducing Fig. 2 of the hi_class paper

Figure 2 of the hi_class paper (1605.06102) shows the effect of increasing the braiding α_B on the CMB temperature spectrum and the matter power spectrum, relative to ΛCDM. The setup is propto_omega (each αᵢ = ĉᵢ · Ω_smg(a)) on a ΛCDM expansion history, with ĉ_K = 1, ĉ_M = ĉ_T = 0, M*²_ini = 1, and ĉ_B stepped through {0, 0.625, 1.25, 1.875, 2.5}.

Create the output directory and an input file:

mkdir -p output/fig2

# fig2_b0625.ini
Omega_Lambda = 0
Omega_fld = 0
Omega_smg = -1

gravity_model = propto_omega
#                ĉ_K,   ĉ_B, ĉ_M, ĉ_T, M*²_ini
parameters_smg = 1., 0.625,  0.,  0.,  1.

expansion_model = lcdm
expansion_smg = 0.5          # overwritten by the closure equation

output = tCl,pCl,lCl,mPk
root = output/fig2/b0625
overwrite_root = yes
write_parameters = yes

Run it, then repeat with ĉ_B (the second entry of parameters_smg) set to each of the five values, changing root accordingly (b0000, b0625, b1250, b1875, b2500):

./class fig2_b0625.ini

Each run writes output/fig2/b0625_cl.dat, ..._pk.dat and ..._parameters.ini. Finally compute the ΛCDM reference with a minimal input file (no _smg keys at all — the scalar field is off when Omega_smg is unspecified):

# fig2_lcdm.ini
output = tCl,pCl,lCl,mPk
root = output/fig2/lcdm
overwrite_root = yes
write_parameters = yes

Plotting the ratio of each b*_cl.dat (column ℓ(ℓ+1)C_ℓ^TT/2π) and b*_pk.dat (P(k)) to the ΛCDM files reproduces the figure: increasing braiding suppresses the large-scale (ISW) temperature anisotropies and modifies the power spectrum on large scales, while leaving the acoustic peaks and small scales untouched — the file formats are described in Output files. The same computation takes a few lines with the Python interface, where the loop over ĉ_B becomes a loop over cosmo.set(...) calls — see Python wrapper.

Troubleshooting

The run is rejected by the stability tests. hi_class checks every model for ghost and gradient instabilities at the background level and stops with a message like

Ghost instability for scalar field perturbations with minimum D=-2.1e-13 at a=1.2e-14
Gradient instability for scalar field perturbations with minimum c_s^2=-3.4e-05 at a=2.1e-03

(and analogously M*^2 and c_t^2 for tensors). This is physics, not a bug: that corner of parameter space is unstable — but numerically noisy borderline cases can be handled by relaxing the thresholds (cs2_safe_smg, D_safe_smg, ct2_safe_smg, M2_safe_smg), skipping the tests before some scale factor (a_min_stability_test_smg, as the cccg and quintessence examples do), or disabling them entirely (skip_stability_tests_smg = yes). Read Stability and precision before touching these.

One known borderline case: parameter scans that set an explicit Omega_smg value (rather than -1) for the cubic Galileon can occasionally trip the ghost test with a minimum D of order −10⁻¹⁰⁴ — that is rounding noise around zero, not an instability. Setting D_safe_smg = 1e-40 (far above underflow noise, far below any physical value of D) clears such cases.

The shooting fails to converge. If the tuning cannot find a parameter value matching the requested Ω_smg (the error is raised in the background module), first switch to Omega_smg_debug mode (above) and scan the raw parameters to see what Ω_smg the theory can actually reach — the target may not be attainable in that region of parameter space. If it is attainable, help the shooting with a better starting point in parameters_smg and a better tuning_dxdy_guess_smg (roughly ∂x/∂Ω_smg for the tuned parameter x), or tune a different parameter via tuning_index_smg.

Where to ask. Open an issue on GitHub for suspected bugs, and use the hi_class forum on Google Groups for usage questions (searching past threads often helps). General CLASS questions are covered on the CLASS code site; see Home for an overview of the documentation and Physics and papers for the papers to cite.