Python wrapper

Python wrapper

hi_class ships with hiclassy, the Cython wrapper inherited from CLASS (where it is called classy), 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 hiclassy via pip

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

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

Both use whatever python resolves to; select an interpreter with PYTHON=python3 make hiclassy. 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 hiclassy import HiClass; import hiclassy; print(hiclassy.__version__)"

Installing from PyPI: hiclassy

If you do not need to modify the C code, the wrapper is on PyPI as hiclassy, versioned to track the code (3.3.4.4 at the time of writing):

pip install hiclassy

It gives you the same from hiclassy import HiClass as the local build. Note that PyPI carries a source distribution, not a wheel: pip compiles the C code on your machine, so gcc and make must be available and the install takes a few minutes. From 3.3.4.3 on, numpy and scipy are declared as dependencies and pip installs them for you; earlier versions require pip install hiclassy numpy scipy.

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 hiclassy import HiClass

cosmo = HiClass()
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/hiclassy.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 — note that samplers written against CLASS import classy, which this release no longer provides, so they need the import pointed at hiclassy; links to the maintained interfaces for each sampler are collected in the Interfaces table at hiclass-code.net/#download.