Python wrapper

Python wrapper

hi_class ships with classy, the Cython wrapper inherited from CLASS, extended with methods to inspect modified-gravity quantities such as the effective Newton constant and the gravitational slip. Everything the C code computes is available from Python: spectra, background tables, transfer functions, and the smg-specific diagnostics described below.

Building the wrapper

The wrapper is built from the repository root, where setup.py and pyproject.toml live (the older python/setup.py is still present but the root files are the maintained entry point). The default make target already includes it:

make            # builds the class executable, libclass.a, and installs classy via pip

or, to (re)install only the Python module:

make classy     # runs `pip install .` in the repository root

Both use whatever python resolves to; select an interpreter with PYTHON=python3 make classy. You can equivalently run pip install . in the repository root yourself — the custom build step in setup.py calls make libclass.a for you before compiling the extension, so a separate make is not strictly required (though you do need gcc and the usual build environment; see Installation). The build requirements (setuptools, wheel, numpy, cython) are fetched automatically by pip. At runtime the module needs numpy and scipy.

Check the installation with:

python -c "from classy import Class; import classy; print(classy.__version__)"

Installing from PyPI: hiclassy

If you do not need to modify the C code, a separately packaged build of the wrapper is on PyPI as hiclassy (currently versioned 3.3.4.x, tracking the hi_class version):

pip install hiclassy numpy scipy

Its import name differs from the locally built wrapper: from hiclassy import HiClass. The HiClass object exposes the same methods as the Class object documented here. The rest of this page uses the locally built from classy import Class.

Basic usage

Parameters are passed to set() as a dictionary with exactly the same keys as an .ini file (see Running hi_class). A minimal run with the propto_omega parametrization on a ΛCDM expansion history:

from classy import Class

cosmo = Class()
cosmo.set({
    'output': 'tCl,pCl,lCl,mPk',
    'lensing': 'yes',
    'Omega_Lambda': 0,
    'Omega_fld': 0,
    'Omega_smg': -1,          # closure: Omega_smg fixed by the other densities
    'gravity_model': 'propto_omega',
    'parameters_smg': '1., 0.1, 0.1, 0., 1.',   # x_k, x_b, x_m, x_t, M*^2_ini
    'expansion_model': 'lcdm',
    'expansion_smg': 0.5,     # overwritten by the closure equation
})
cosmo.compute()

cls = cosmo.lensed_cl(2500)          # dict with 'ell', 'tt', 'ee', 'te', 'bb', 'pp', 'tp'
pk  = cosmo.pk(0.1, 0.)              # P_m(k,z) in Mpc³, k in 1/Mpc

cosmo.struct_cleanup()               # free the C structures before the next .set()/.compute()

The meaning of Omega_smg = -1 and of each parametrization's parameters_smg vector is documented in hi_class.ini and on Models: Parametrized alphas; covariant theories set gravity_model and parameters_smg as in the gravity_models/ examples (Models: Covariant theories), with no expansion_model line. If a model is rejected as unstable, compute() raises a CosmoComputationError — see Stability and precision.

All the standard CLASS methods work unchanged: raw_cl(), density_cl(), pk_lin(), get_transfer(), get_current_derived_parameters(), angular_distance(), and so on.

hi_class-specific methods

The wrapper adds accessors for the effective gravitational couplings. Conventions (from the docstrings in python/classy.pyx): with metric perturbations δg₀₀ = −2Ψ and δgᵢⱼ = −2Φ δᵢⱼ,

• G_eff = −2 k²/a² Φ/δρ (sourcing of the curvature potential Φ),
• G_matter = −2 k²/a² Ψ/δρ (felt by non-relativistic matter, i.e. structure growth),
• G_light = −2 k²/a² (Φ+Ψ)/2/δρ (felt by light, i.e. lensing),
• slip = Φ/Ψ,

all in units of Newton's constant (→ 1 in GR).

Background (quasi-static, k → ∞ limit). These read the analytic expressions stored in the background module and need no perturbation output:

Method	Arguments	Returns	Meaning
G_eff_back_smg(z)	redshift	float	G_eff in the k → ∞ limit
slip_eff_back_smg(z)	redshift	float	slip Φ/Ψ in the k → ∞ limit
G_matter_back_smg(z)	redshift	float	G_eff/slip
G_light_back_smg(z)	redshift	float	(slip + 1) G_eff / (2 slip)

Scale-dependent (from the actual perturbations). These reconstruct the couplings from the transfer functions, so output must include mTk (and vTk for the G_eff-based ones — the gauge-invariant δρ needs the velocity transfers); otherwise they raise an error. The ..._at_z_smg variants return the pair (k_range, quantity) as arrays, with k in 1/Mpc; the ..._at_k_and_z_smg variants interpolate to a single k (in 1/Mpc) and return a float:

Method	Arguments	Returns	Meaning
G_eff_at_z_smg(z)	redshift	(k array, G_eff array)	G_eff(k) at fixed z
G_eff_at_k_and_z_smg(k, z)	k [1/Mpc], redshift	float	G_eff at (k, z)
slip_eff_at_z_smg(z)	redshift	(k array, slip array)	Φ/Ψ (k) at fixed z
slip_eff_at_k_and_z_smg(k, z)	k [1/Mpc], redshift	float	Φ/Ψ at (k, z)
G_matter_at_z_smg(z)	redshift	(k array, G_matter array)	G_matter(k) at fixed z
G_matter_at_k_and_z_smg(k, z)	k [1/Mpc], redshift	float	G_matter at (k, z)
G_light_at_z_smg(z)	redshift	(k array, G_light array)	G_light(k) at fixed z
G_light_at_k_and_z_smg(k, z)	k [1/Mpc], redshift	float	G_light at (k, z)

Quasi-static diagnostics. For inspecting the automatic quasi-static approximation scheme (see Stability and precision):

Method	Arguments	Returns	Meaning
get_qs_functions_at_k_and_z_qs_smg(k, z)	k, redshift	(mass2_qs, mass2_qs_p, rad2_qs, friction_qs, slope_qs)	the functions the QS algorithm uses to decide where the full scalar-field dynamics can be replaced by its quasi-static limit

Related, and useful in modified gravity where growth becomes scale-dependent: scale_dependent_growth_factor_at_z(z), scale_dependent_growth_factor_at_k_and_z(k, z), and scale_dependent_growth_factor_f_at_z(z) for D(k, z) and f(k, z) = d ln D/d ln a.

smg quantities in get_background()

get_background() returns the same columns as the background.dat output file, as a dictionary of arrays over the full time sampling. In a hi_class run this always includes (.)rho_smg and (.)p_smg, and — at the default verbosity output_background_smg = 1 — the α-functions and stability quantities: M*^2_smg, D_M*^2_smg, kineticity_smg, braiding_smg, tensor_excess_smg, M2_running_smg, beyond_horndeski_smg, c_s^2, kin (D) (plus Current and Shift for covariant theories). Raising output_background_smg (to 2, 3, …) adds the scalar-field trajectory φ, φ′, φ″, the G_eff_smg/slip_eff_smg columns, and the internal perturbation coefficients — see Output files for the full list.

bg = cosmo.get_background()
z, alpha_B = bg['z'], bg['braiding_smg']

Parameter samplers

The wrapper is what MontePython, Cobaya, and CosmoSIS talk to; links to the maintained interfaces for each sampler are collected in the Interfaces table at hiclass-code.net/#download.