CLASSpp Manual
Cosmology reference and developer manual
Loading...
Searching...
No Matches
BaseSpecies Class Referenceabstract

#include <base_species.h>

+ Inheritance diagram for BaseSpecies:

Data Structures

struct  PerturbLayout
 
struct  PerturbScratch
 
struct  StressEnergyContribution
 

Public Types

enum class  EnergyType
 

Public Member Functions

virtual std::unique_ptr< PerturbLayout > CreatePerturbLayout () const
 
virtual void SetBackgroundModule (const BackgroundModule *)
 
virtual void SetThermodynamicsModule (const ThermodynamicsModule *)
 
virtual void SetPerturbs (const perturbs *)
 
virtual std::optional< double > GetParam (const std::string &) const
 
virtual void RegisterBackgroundIndices (int &index_bg)=0
 
virtual void RegisterIntegrationIndices (int &index_bi)
 
virtual void SetBackgroundInitialConditions (const BackgroundICContext &ctx)
 
virtual void ComputeBackground (double a, const double *pvecback_B, double *pvecback)=0
 
virtual void BackgroundDerivs (double tau, const double *y, double *dy, const double *pvecback)
 
virtual void BackgroundDerivsDiagonal (double tau, const double *y, double *diag, const double *pvecback)
 
virtual double Rho (const double *pvecback) const =0
 
virtual double P (const double *pvecback) const =0
 
virtual double PPrime (double a, double H, const double *pvecback_B, const double *pvecback) const
 
virtual void FinalizeBackground (double a, double H, const double *pvecback_B, double *pvecback)
 
virtual bool IsFreestreaming () const
 
virtual double FreestreamingRho (const double *pvecback) const
 
bool IsPresent () const
 
int bg_rho_index () const
 
virtual void WriteBackgroundColumnTitles (BackgroundColumnWriter &) const
 
virtual void WriteBackgroundData (const double *, BackgroundColumnWriter &) const
 
virtual void ProcessBackgroundTable (const double *, int, int, const double *)
 
virtual void RegisterTransferSourceIndices (int &, const SourceRequestContext &)
 
virtual void PerturbDerivs (const PerturbLayout &layout, double tau, const double *y, double *dy, const perturb_parameters_and_workspace &ppaw) const =0
 
virtual void PerturbDerivsDiagonal (const PerturbLayout &, double, const double *, double *, const perturb_parameters_and_workspace &) const
 
virtual void PerturbVectorDerivs (const PerturbLayout &, double, const double *, double *, const perturb_parameters_and_workspace &) const
 
virtual void PerturbTensorDerivs (const PerturbLayout &, double, const double *, double *, const perturb_parameters_and_workspace &) const
 
virtual void ApplyTensorInitialConditions (const PerturbLayout &, double *, double, const double *) const
 
virtual void WriteTensorOutputColumnTitles (std::string &) const
 
virtual void ContributeTensorGwSource (const PerturbLayout &, double, const double *, perturb_workspace *) const
 
virtual StressEnergyContribution StressEnergy (const PerturbLayout &layout, const perturb_vector *pv, const double *y, const double *pvecback, const perturb_workspace *ppw) const =0
 
virtual void WriteOutputColumns (PerturbColumnWriter &, const PerturbationsModule &, file_format, TransferColumnSection=TransferColumnSection::all) const
 
virtual void PrintVariables (PerturbColumnWriter &, const PerturbLayout *, double, const double *, const PerturbationsModule &, const perturb_workspace *) const
 
virtual void FillSources (const PerturbLayout &, const double *, const double *, PerturbSourceContext &) const
 
virtual void ApplyInitialConditions (const PerturbLayout &, double *, const PerturbIcContext &)
 
virtual int ApproximationCount () const
 
virtual int ApproximationRegimeAt (int, double, const double *) const
 
int ApproximationRegime (const perturb_workspace *ppw, int which=0) const
 
int ApproximationRegimeBefore (const PerturbSwitchContext &ctx, int which=0) const
 
virtual void CopyPerturbationsAcrossSwitch (const PerturbLayout &, const PerturbLayout &, const double *, double *, const PerturbSwitchContext &) const
 
virtual bool SupportsNewtonianGauge () const
 
virtual bool SupportsIsocurvatureInitialConditions () const
 
virtual double RhoPrimeOverRho (const double *pvecback, double a_prime_over_a) const
 
virtual void PerturbSynchronousToNewtonian (const PerturbLayout &, double *, const PerturbIcContext &)
 
virtual void MarkUsedInSources (const PerturbLayout &, const perturb_workspace *, int *) const
 
virtual double GetOmega0 () const =0
 
virtual double BackgroundDensityOverH0Sq (double a, double H0) const
 
virtual double GetRadiationOmega0 () const
 
virtual double DarkRadiationRhoToday (const double *) const
 
virtual double NeutrinoOmega0 () const
 
virtual double NeffContribution (double) const
 
virtual void PrintNeffInfo () const
 
virtual void PrintMassInfo () const
 
virtual void PrintBackgroundDetails (const double *, double) const
 
virtual double TensorMasslessRelativisticRho (const double *) const
 
virtual double DeviationFromRadiation (const double *) const
 
virtual std::vector< double > FreeStreamingWavenumbers () const
 
virtual void WarnIfNonlinearUnreliable (double) const
 
virtual std::optional< double > ChildOmega0 (const std::string &) const
 
virtual double BackgroundAIni (double a_proposed, double) const
 
bool ClustersAsMatterCached () const
 
virtual void FinalizeMatterClassification ()
 
virtual bool ClustersAsMatter () const
 
virtual bool IsColdMatterSpecies () const
 
virtual bool HasWarmMatter () const
 
virtual double NonClusteringOmega0 () const
 
virtual double ColdMatterRho (const double *pvecback) const
 
virtual double ColdMatterOmega0 () const
 
virtual bool HasNcdm () const
 
virtual double SourceSamplingRate (const double *) const
 
virtual int MaxMultipole (const precision *, bool) const
 
virtual bool SupportsExplicitPerturbationEvolver () const
 
virtual bool PrefersExponentialPerturbationEvolver () const
 
virtual bool SupportsExponentialPerturbationEvolver () const
 

Protected Member Functions

void ApplyFluidLikeNewtonianShift (double *y, int idx_delta, int idx_theta, const double *pvecback, const PerturbIcContext &ctx) const
 

Friends

class SpeciesCollection
 

Detailed Description

Abstract base class for all cosmological species.

Each species:

  • claims slots in the background vector (pvecback) and integration vector (y) by implementing Register*Indices()
  • computes its background density/pressure in ComputeBackground()
  • optionally provides ODE contributions in BackgroundDerivs()
  • provides perturbation equations in PerturbDerivs()
  • exposes StressEnergy for the Einstein equations

The collection in BaseModule is a const SpeciesCollection&. Use .at("CDM") (throws if absent) or .find("CDM") (returns pointer-or-nullptr); iterate with for (auto& sp : all_species_) and use sp.key / sp->name() as needed.

Member Enumeration Documentation

◆ EnergyType

enum class BaseSpecies::EnergyType
strong

Classification used by background_functions() to accumulate rho_r, rho_m and the dark energy (Omega_de, w_de). Other is split by its pressure at each time: radiation (3p) and matter (rho - 3p) while p >= 0, dark energy while p < 0 (since 2026-10-27; a quintessence field near w = -1 used to put 4 rho into rho_m).

Member Function Documentation

◆ CreatePerturbLayout()

virtual std::unique_ptr< PerturbLayout > BaseSpecies::CreatePerturbLayout ( ) const
inlinevirtual

Produce a fresh layout for this species. Called once per pv during perturb_vector_init, before Register*PerturbationIndices. Default: empty base PerturbLayout (suitable for species with no perturbation slots, or as a placeholder during migration).

Reimplemented in BaryonsSpecies, CDMSpecies, CompositeSpecies, DarkRadiationSpecies, DCDMSpecies, FluidSpecies, IDM_DRSpecies, IDM_DRMDSpecies, IDRSpecies, IDR_DRMDSpecies, LambdaSpecies, NCDMBaseSpecies, NEDESpecies, PhotonsSpecies, PpfFluid, ScalarFieldSpecies, ScalarTensorSpecies, UltraRelativisticSpecies, and WdmDecayProductSpecies.

◆ SetBackgroundModule()

virtual void BaseSpecies::SetBackgroundModule ( const BackgroundModule *  )
inlinevirtual

Called by BackgroundModule after construction to provide access to its indices (index_bg_a_, index_bg_H_, etc.) and background state. Species that need it override this; default is no-op.

Reimplemented in AxionEDEFluid, CompositeSpecies, DarkRadiationSpecies, DCDMSpecies, DCDM_DR_Species, DCDM_WDM_Species, DNCDM_DR_Species, DNCDMInvSpecies, DNCDMProxySpecies, FluidSpecies, NCDMBaseSpecies, NEDESpecies, ScalarFieldSpecies, and ScalarTensorSpecies.

◆ SetThermodynamicsModule()

virtual void BaseSpecies::SetThermodynamicsModule ( const ThermodynamicsModule *  )
inlinevirtual

Called by PerturbationsModule during construction to provide access to the thermodynamics module (pvecthermo indices, etc.). Default: no-op.

Reimplemented in BaryonsSpecies, CompositeSpecies, IDRSpecies, and PhotonsSpecies.

◆ SetPerturbs()

virtual void BaseSpecies::SetPerturbs ( const perturbs *  )
inlinevirtual

Called by PerturbationsModule during construction to provide access to the perturbs struct (alpha_idm_dr, gauge, etc.). Default: no-op.

Reimplemented in BaryonsSpecies, CompositeSpecies, IDM_DR_IDR_Species, IDRSpecies, NCDMBaseSpecies, and PhotonsSpecies.

◆ GetParam()

virtual std::optional< double > BaseSpecies::GetParam ( const std::string &  ) const
inlinevirtual

Generic species-param accessor for the Python wrapper layer and cross-module readers that don't want to downcast. Each species may opt in by overriding this and returning the named param; default is std::nullopt.

Reimplemented in AxionEDEFluid, GreyBodyNCDMSpecies, IDM_DR_IDR_Species, NEDESpecies, and ScalarTensorSpecies.

◆ RegisterBackgroundIndices()

virtual void BaseSpecies::RegisterBackgroundIndices ( int &  index_bg)
pure virtual

Claim consecutive slots in pvecback. Called once during background_indices(). Implementation must assign index_bg_rho_ (and any other needed indices) and increment index_bg accordingly.

Implemented in BaryonsSpecies, CDMSpecies, CompositeSpecies, DarkRadiationSpecies, DCDMSpecies, DNCDMProxySpecies, DNCDMSpecies, DrPsdSpecies, FluidSpecies, IDM_DRSpecies, IDM_DRMDSpecies, IDRSpecies, IDR_DRMDSpecies, LambdaSpecies, MajoronSpecies, NEDESpecies, PhotonsSpecies, ScalarFieldSpecies, ScalarTensorSpecies, UltraRelativisticSpecies, and WdmDecayProductSpecies.

◆ RegisterIntegrationIndices()

virtual void BaseSpecies::RegisterIntegrationIndices ( int &  index_bi)
inlinevirtual

Claim slots in the ODE integration vector y. Called during background_indices(). Default: no integrated variables (analytic species do not need this).

Reimplemented in CompositeSpecies, DarkRadiationSpecies, DCDMSpecies, DNCDMProxySpecies, DNCDMSpecies, DrPsdSpecies, NEDESpecies, ScalarFieldSpecies, ScalarTensorSpecies, and WdmDecayProductSpecies.

◆ SetBackgroundInitialConditions()

virtual void BaseSpecies::SetBackgroundInitialConditions ( const BackgroundICContext &  ctx)
inlinevirtual

Set initial conditions for ODE-integrated background variables.

Parameters
ctxBackground initial-condition context (a_ini, rho_rad, and the integration vector to fill).

Reimplemented in CompositeSpecies, DCDMSpecies, DCDM_DR_Species, DNCDM_DR_Species, DNCDMProxySpecies, DNCDMSpecies, DrPsdSpecies, NEDESpecies, ScalarFieldSpecies, ScalarTensorSpecies, and WdmDecayProductSpecies.

◆ ComputeBackground()

virtual void BaseSpecies::ComputeBackground ( double  a,
const double *  pvecback_B,
double *  pvecback 
)
pure virtual

Compute species background quantities at scale factor a. pvecback_B is the current ODE integration vector. Write density (and any other owned quantities) into pvecback.

Implemented in BaryonsSpecies, IDM_DRSpecies, IDM_DRMDSpecies, IDRSpecies, IDR_DRMDSpecies, PhotonsSpecies, CDMSpecies, CompositeSpecies, DarkRadiationSpecies, DCDMSpecies, DCDM_WDM_Species, DNCDMProxySpecies, DNCDMSpecies, DrPsdSpecies, FluidSpecies, LambdaSpecies, MajoronSpecies, NEDESpecies, ScalarFieldSpecies, ScalarTensorSpecies, UltraRelativisticSpecies, and WdmDecayProductSpecies.

◆ BackgroundDerivs()

virtual void BaseSpecies::BackgroundDerivs ( double  tau,
const double *  y,
double *  dy,
const double *  pvecback 
)
inlinevirtual

Contribute to dy/dtau for species with ODE-integrated background variables. pvecback already contains all evaluated background quantities. Default: nothing (species with analytic rho(a) don't override this).

Reimplemented in CompositeSpecies, DarkRadiationSpecies, DCDMSpecies, DCDM_DR_Species, DCDM_WDM_Species, DNCDM_DR_Species, DNCDMInvSpecies, DNCDMProxySpecies, DNCDMSpecies, NEDESpecies, ScalarFieldSpecies, and ScalarTensorSpecies.

◆ BackgroundDerivsDiagonal()

virtual void BaseSpecies::BackgroundDerivsDiagonal ( double  tau,
const double *  y,
double *  diag,
const double *  pvecback 
)
inlinevirtual

Contribute d(dy_i)/d(y_i) — the DIAGONAL of this species' background Jacobian — for the slots it owns, in the same units and layout as BackgroundDerivs.

For the exponential evolver, which integrates the diagonal exactly and carries the remainder explicitly. ACCUMULATE (+=): the caller zeroes the buffer once, and a composite's rungs each add their own slots.

Default: nothing. That is the correct answer for a species without a stiff self-coupling, not a fallback — at diag = 0 the exponential step degenerates smoothly to its explicit counterpart.

A diagonal that is not the true one costs efficiency and conditioning, never correctness (the evolver forms N = f - Ly, so the fixed point is exact for any L). A wrong SIGN is the dangerous case; pin any implementation against finite differences of BackgroundDerivs.

Reimplemented in CompositeSpecies, DNCDMInvSpecies, and DNCDMProxySpecies.

◆ Rho()

◆ P()

◆ PPrime()

virtual double BaseSpecies::PPrime ( double  a,
double  H,
const double *  pvecback_B,
const double *  pvecback 
) const
inlinevirtual

Post-Friedmann. This species' conformal-time pressure derivative p' (a' / a = a*H). pvecback_B is the ODE state (IN); pvecback is fully populated through H. Default 0 (matter / Lambda).

Reimplemented in DarkRadiationSpecies, DNCDMSpecies, IDRSpecies, IDR_DRMDSpecies, PhotonsSpecies, CompositeSpecies, DrPsdSpecies, FluidSpecies, MajoronSpecies, NEDESpecies, ScalarFieldSpecies, ScalarTensorSpecies, UltraRelativisticSpecies, and WdmDecayProductSpecies.

◆ FinalizeBackground()

virtual void BaseSpecies::FinalizeBackground ( double  a,
double  H,
const double *  pvecback_B,
double *  pvecback 
)
inlinevirtual

Post-Friedmann. Write this species' H-dependent owned output slots. H passed explicitly so the hook need not re-read it. Default no-op.

Reimplemented in CompositeSpecies, and ScalarFieldSpecies.

◆ IsFreestreaming()

virtual bool BaseSpecies::IsFreestreaming ( ) const
inlinevirtual

True for species that are free-streaming and massless at IC time (deep radiation domination). Used to accumulate rho_nu / fracnu in perturbation IC setup. Static at construction time. Default: false.

Reimplemented in DarkRadiationSpecies, DNCDMSpecies, DrPsdSpecies, IDRSpecies, IDR_DRMDSpecies, UltraRelativisticSpecies, and WdmDecayProductSpecies.

◆ FreestreamingRho()

virtual double BaseSpecies::FreestreamingRho ( const double *  pvecback) const
inlinevirtual

Free-streaming radiation density contributed by this species at the current background state. Plain species derive this from IsFreestreaming(); composites override it to sum over their children.

Reimplemented in CompositeSpecies.

◆ IsPresent()

bool BaseSpecies::IsPresent ( ) const
inline

Returns true if this species is present (has registered its background indices). For top-level species use all_species_.contains(); IsPresent() is for sub-components of composites where all_species_.contains() is unavailable.

◆ bg_rho_index()

int BaseSpecies::bg_rho_index ( ) const
inline

Where this species' energy density sits in pvecback. Rho() is the way to read it; the index itself is for callers that must address the slot directly.

◆ WriteBackgroundColumnTitles()

virtual void BaseSpecies::WriteBackgroundColumnTitles ( BackgroundColumnWriter &  ) const
inlinevirtual

Write this species' background column titles into writer. Called by BackgroundModule::background_output_titles(). Default: no-op (species with no background output need not override).

Reimplemented in BaryonsSpecies, CDMSpecies, DCDM_DR_Species, DCDM_WDM_Species, DNCDM_DR_Species, DNCDMInvSpecies, DNCDMProxySpecies, DNCDMSpecies, DrPsdSpecies, FluidSpecies, IDM_DR_IDR_Species, LambdaSpecies, NEDESpecies, PhotonsSpecies, ScalarFieldSpecies, ScalarTensorSpecies, Type3Species, UltraRelativisticSpecies, and WdmDecayProductSpecies.

◆ WriteBackgroundData()

virtual void BaseSpecies::WriteBackgroundData ( const double *  ,
BackgroundColumnWriter &   
) const
inlinevirtual

Write this species' background data values into writer. pvecback is the full background vector at the current time step. Called by BackgroundModule::background_output_data(). Default: no-op.

Reimplemented in BaryonsSpecies, CDMSpecies, DCDM_DR_Species, DCDM_WDM_Species, DNCDM_DR_Species, DNCDMInvSpecies, DNCDMProxySpecies, DNCDMSpecies, DrPsdSpecies, FluidSpecies, IDM_DR_IDR_Species, LambdaSpecies, NEDESpecies, PhotonsSpecies, ScalarFieldSpecies, ScalarTensorSpecies, Type3Species, UltraRelativisticSpecies, and WdmDecayProductSpecies.

◆ ProcessBackgroundTable()

virtual void BaseSpecies::ProcessBackgroundTable ( const double *  ,
int  ,
int  ,
const double *   
)
inlinevirtual

Called once after the full background table is built. Lets a species run table-scope analysis over its own columns. Default no-op.

Reimplemented in DNCDMInvSpecies, and ScalarTensorSpecies.

◆ RegisterTransferSourceIndices()

virtual void BaseSpecies::RegisterTransferSourceIndices ( int &  ,
const SourceRequestContext &   
)
inlinevirtual

Register this species' transfer-source (index_tp) slots. Set once in perturb_indices_of_perturbs() before the k-loop; mirrors RegisterBackgroundIndices (k-independent, cached in a plain species member). Takes no PerturbLayout — that absence marks it as non-per-k state. Default: no-op (species that emit no transfer functions).

Reimplemented in BaryonsSpecies, CDMSpecies, CompositeSpecies, DarkRadiationSpecies, DCDMSpecies, FluidSpecies, IDM_DR_IDR_Species, NCDMBaseSpecies, PhotonsSpecies, ScalarFieldSpecies, and UltraRelativisticSpecies.

◆ PerturbDerivs()

virtual void BaseSpecies::PerturbDerivs ( const PerturbLayout &  layout,
double  tau,
const double *  y,
double *  dy,
const perturb_parameters_and_workspace &  ppaw 
) const
pure virtual

Contribute to dy for the scalar perturbation ODE at conformal time tau. The PerturbScalarContext inside ppaw->ppw has pre-computed metric terms, cross-species state (delta_g, theta_g, theta_b, ...), and approximation flags. The layout is this species' PerturbLayout slot (ppw->pv->species_layouts[i]); composites receive their own layout and pass nested sub-layouts to children.

Implemented in LambdaSpecies, BaryonsSpecies, CDMSpecies, CompositeSpecies, DarkRadiationSpecies, DCDMSpecies, DNCDMSpecies, DrPsdSpecies, FluidSpecies, IDM_DRSpecies, IDM_DRMDSpecies, IDRSpecies, IDR_DRMDSpecies, MajoronSpecies, NEDESpecies, PhotonsSpecies, PpfFluid, ScalarFieldSpecies, ScalarTensorSpecies, UltraRelativisticSpecies, and WdmDecayProductSpecies.

◆ PerturbDerivsDiagonal()

virtual void BaseSpecies::PerturbDerivsDiagonal ( const PerturbLayout &  ,
double  ,
const double *  ,
double *  ,
const perturb_parameters_and_workspace &   
) const
inlinevirtual

The same for the scalar perturbation ODE; see BackgroundDerivsDiagonal for the accumulate contract, the zero default and the wrong-sign warning, which apply verbatim here.

Reimplemented in CompositeSpecies, DNCDMProxySpecies, and DNCDMInvSpecies.

◆ PerturbVectorDerivs()

virtual void BaseSpecies::PerturbVectorDerivs ( const PerturbLayout &  ,
double  ,
const double *  ,
double *  ,
const perturb_parameters_and_workspace &   
) const
inlinevirtual

Contribute to dy for the vector perturbation ODE. Default: no-op.

Reimplemented in PhotonsSpecies.

◆ PerturbTensorDerivs()

virtual void BaseSpecies::PerturbTensorDerivs ( const PerturbLayout &  ,
double  ,
const double *  ,
double *  ,
const perturb_parameters_and_workspace &   
) const
inlinevirtual

Contribute to dy for the tensor perturbation ODE. Default: no-op.

Reimplemented in DNCDM_DR_Species, NCDMBaseSpecies, and PhotonsSpecies.

◆ ApplyTensorInitialConditions()

virtual void BaseSpecies::ApplyTensorInitialConditions ( const PerturbLayout &  ,
double *  ,
double  ,
const double *   
) const
inlinevirtual

Tensor modes: set the monopole of this species' own hierarchy at the initial time. f0 is its value for a massless free-streaming species, $ F_0 = \sqrt{6}\,\delta h $, where $ \delta h $ is the term of order $ (k\tau)^2 $ of the gravitational wave (see PerturbationsModule::perturb_initial_conditions). Default: no-op, for a species without a tensor hierarchy of its own.

Reimplemented in NCDMBaseSpecies.

◆ WriteTensorOutputColumnTitles()

virtual void BaseSpecies::WriteTensorOutputColumnTitles ( std::string &  ) const
inlinevirtual

Write this species' tensor-mode output column titles. Default: no-op.

◆ ContributeTensorGwSource()

virtual void BaseSpecies::ContributeTensorGwSource ( const PerturbLayout &  ,
double  ,
const double *  ,
perturb_workspace *   
) const
inlinevirtual

Contribute to the gravitational-wave source term (anisotropic stress) for tensor mode. Called after perturb_workspace::gw_source is reset to zero. Default: no-op. The layout is this species' PerturbLayout slot (ppw->pv->species_layouts[i]).

Reimplemented in NCDMBaseSpecies.

◆ StressEnergy()

virtual StressEnergyContribution BaseSpecies::StressEnergy ( const PerturbLayout &  layout,
const perturb_vector *  pv,
const double *  y,
const double *  pvecback,
const perturb_workspace *  ppw 
) const
pure virtual

◆ WriteOutputColumns()

virtual void BaseSpecies::WriteOutputColumns ( PerturbColumnWriter &  ,
const PerturbationsModule &  ,
file_format  ,
TransferColumnSection  = TransferColumnSection::all 
) const
inlinevirtual

Append this species' output columns (delta, theta) to writer. Called from perturb_output_titles (title mode) and perturb_output_data (data mode). In class_format, the module may call this separately for density and velocity sections to preserve the historical transfer-column ordering. Use writer.Add(title, mod.index_tp_XXX_, active) — writer looks up tk[tp_index].

Reimplemented in BaryonsSpecies, CDMSpecies, CompositeSpecies, DarkRadiationSpecies, DCDMSpecies, DNCDMSpecies, DrPsdSpecies, FluidSpecies, IDM_DR_IDR_Species, PhotonsSpecies, ScalarFieldSpecies, UltraRelativisticSpecies, and WdmDecayProductSpecies.

◆ PrintVariables()

virtual void BaseSpecies::PrintVariables ( PerturbColumnWriter &  ,
const PerturbLayout *  ,
double  ,
const double *  ,
const PerturbationsModule &  ,
const perturb_workspace *   
) const
inlinevirtual

Append this species' time-evolution variables to writer. Called from perturb_prepare_k_output (title mode, tau=0/y=nullptr/ppw=nullptr) and perturb_print_variables (data mode). Guard computation behind: if (!writer.IsTitleMode()) { ... compute ... } Use writer.Add(title, computed_value, active).

layout is NULL in title mode (there is no perturb_vector yet) and is the species' own sub-layout otherwise — passed in rather than resolved from collection_index_ so that CompositeSpecies can chain this to children, which are not registered in the collection and have no valid collection_index_.

Reimplemented in BaryonsSpecies, CDMSpecies, CompositeSpecies, DCDMSpecies, DNCDMInvSpecies, DNCDMProxySpecies, FluidSpecies, IDM_DR_IDR_Species, PhotonsSpecies, PpfFluid, ScalarFieldSpecies, ScalarTensorSpecies, and UltraRelativisticSpecies.

◆ FillSources()

virtual void BaseSpecies::FillSources ( const PerturbLayout &  ,
const double *  ,
const double *  ,
PerturbSourceContext &   
) const
inlinevirtual

Write per-k, per-tau source values for this species into the source table. Called in perturb_sources() after metric/temperature sources are set. Use ctx.p_mod->SetSourceValue(ctx.index_md, ctx.index_ic, ctx.p_mod->index_tp_XXX_, ctx.index_tau, ctx.index_k, value). All addressing (index_md, index_ic, index_k, index_tau) is in ctx. Default: no-op.

Reimplemented in BaryonsSpecies, CDMSpecies, CompositeSpecies, DarkRadiationSpecies, DCDMSpecies, DrPsdSpecies, FluidSpecies, IDM_DR_IDR_Species, PhotonsSpecies, ScalarFieldSpecies, UltraRelativisticSpecies, WdmDecayProductSpecies, DNCDMSpecies, and PpfFluid.

◆ ApplyInitialConditions()

virtual void BaseSpecies::ApplyInitialConditions ( const PerturbLayout &  ,
double *  ,
const PerturbIcContext &   
)
inlinevirtual

Write synchronous-gauge initial conditions for this species into y[]. y[] == ppw->pv->y. The module pre-computes ctx.delta_g_ic, ctx.delta_ur, etc. Guard each IC type: if (ctx.index_ic == ctx.p_mod->index_ic_ad_) { ... } Newtonian gauge transformation is handled by the module after this loop. Default: no-op.

Reimplemented in AxionEDEFluid, BaryonsSpecies, CDMSpecies, CompositeSpecies, DarkRadiationSpecies, DCDMSpecies, DNCDMSpecies, DrPsdSpecies, FluidSpecies, IDM_DR_IDR_Species, PhotonsSpecies, ScalarFieldSpecies, ScalarTensorSpecies, UltraRelativisticSpecies, and WdmDecayProductSpecies.

◆ ApproximationCount()

virtual int BaseSpecies::ApproximationCount ( ) const
inlinevirtual

How many approximations this species owns. Default 0.

Reimplemented in NEDESpecies.

◆ ApproximationRegimeAt()

virtual int BaseSpecies::ApproximationRegimeAt ( int  ,
double  ,
const double *   
) const
inlinevirtual

The regime of approximation which for wavenumber k at the time of pvecback.

Reimplemented in NEDESpecies.

◆ ApproximationRegime()

int BaseSpecies::ApproximationRegime ( const perturb_workspace *  ppw,
int  which = 0 
) const

The regime of approximation which that the workspace is integrating in.

◆ ApproximationRegimeBefore()

int BaseSpecies::ApproximationRegimeBefore ( const PerturbSwitchContext &  ctx,
int  which = 0 
) const

The regime of approximation which before the switch that ctx describes. A switch that leaves a species' variables in place (a tight coupling ending) is told apart from the switches of other approximations only by this.

◆ CopyPerturbationsAcrossSwitch()

virtual void BaseSpecies::CopyPerturbationsAcrossSwitch ( const PerturbLayout &  ,
const PerturbLayout &  ,
const double *  ,
double *  ,
const PerturbSwitchContext &   
) const
inlinevirtual

Copy perturbation state from one layout to another across an approximation switch. Called when the perturbation vector is reallocated (e.g., NCDM FA collapse from full Boltzmann hierarchy to fluid variables delta/theta/shear). Default: no-op. Most species have no approximation switches.

Reimplemented in BaryonsSpecies, CDMSpecies, CompositeSpecies, DarkRadiationSpecies, DCDMSpecies, FluidSpecies, IDM_DRSpecies, IDM_DRMDSpecies, IDRSpecies, IDR_DRMDSpecies, NCDMBaseSpecies, NEDESpecies, PhotonsSpecies, PpfFluid, ScalarFieldSpecies, ScalarTensorSpecies, and UltraRelativisticSpecies.

◆ SupportsNewtonianGauge()

virtual bool BaseSpecies::SupportsNewtonianGauge ( ) const
inlinevirtual

False if this species' perturbations are coded in synchronous gauge only. Default true.

Reimplemented in NEDESpecies, and Type3Species.

◆ SupportsIsocurvatureInitialConditions()

virtual bool BaseSpecies::SupportsIsocurvatureInitialConditions ( ) const
inlinevirtual

False if this species has adiabatic initial conditions only (no cdi, bi, nid or niv). Default true.

Reimplemented in DCDM_DR_Species, DNCDM_DR_Species, and IDM_DR_IDR_Species.

◆ RhoPrimeOverRho()

virtual double BaseSpecies::RhoPrimeOverRho ( const double *  pvecback,
double  a_prime_over_a 
) const
inlinevirtual

Log conformal-time derivative of the background density, ρ'/ρ (ρ' ≡ dρ̄/dτ). Single source of truth for the density-contrast gauge shift. Default: ρ'/ρ = -3ℋ(Rho+P)/Rho.

A species reports ONLY its own equation of motion — exactly the terms in its own BackgroundDerivs. A species with an intrinsic sink overrides (DCDM decays whatever receives the energy: -3ℋ - aΓ). A species that is SOURCED from outside does not: DarkRadiationSpecies and WdmDecayProductSpecies are fed by their parent composite's BackgroundDerivs, so they report pure dilution and it is the composite's job to correct for the coupling.

Parameters
pvecbackCurrent background-quantity vector.
a_prime_over_aℋ = a'/a (base does not store H/a indices).

Reimplemented in DCDMSpecies, and WdmDecayProductSpecies.

◆ PerturbSynchronousToNewtonian()

virtual void BaseSpecies::PerturbSynchronousToNewtonian ( const PerturbLayout &  ,
double *  ,
const PerturbIcContext &   
)
inlinevirtual

Transform this species' own perturbation variables from synchronous to Newtonian gauge, in place in y[]. Called by the module after alpha is known (ctx.alpha / ctx.alpha_prime filled). The synchronous IC is already in y[] (ApplyInitialConditions runs in both gauges), so this is a pure shift/re-seed. Default: no-op (species with no perturbed variables, e.g. cosmological constant).

Reimplemented in DrPsdSpecies, WdmDecayProductSpecies, BaryonsSpecies, CDMSpecies, CompositeSpecies, DCDMSpecies, DCDM_DR_Species, DNCDM_DR_Species, FluidSpecies, IDM_DRSpecies, IDM_DRMDSpecies, IDRSpecies, IDR_DRMDSpecies, NCDMBaseSpecies, PhotonsSpecies, ScalarFieldSpecies, and UltraRelativisticSpecies.

◆ MarkUsedInSources()

virtual void BaseSpecies::MarkUsedInSources ( const PerturbLayout &  ,
const perturb_workspace *  ,
int *   
) const
inlinevirtual

Mark which source slots this species writes during FillSources. Called to build the used_in_sources bitmask/index list. ppw is supplied so species can consult their approximation flags. Default: no-op. Sources-writing species override to flag their tp indices.

Reimplemented in IDM_DR_IDR_Species, NCDMBaseSpecies, PhotonsSpecies, and UltraRelativisticSpecies.

◆ GetOmega0()

virtual double BaseSpecies::GetOmega0 ( ) const
pure virtual

Returns the species' contribution to Omega0 (used for budget closure during construction). For composites, this defaults to summing children. For decay-product species starting at zero, override returning 0.

Implemented in BaryonsSpecies, CDMSpecies, CompositeSpecies, DarkRadiationSpecies, DCDMSpecies, DCDM_WDM_Species, DNCDMSector, DrPsdSpecies, FluidSpecies, IDM_DRSpecies, IDM_DRMDSpecies, IDRSpecies, IDR_DRMDSpecies, LambdaSpecies, MajoronSpecies, NCDMBaseSpecies, NEDESpecies, PhotonsSpecies, ScalarFieldSpecies, ScalarTensorSpecies, UltraRelativisticSpecies, and WdmDecayProductSpecies.

◆ BackgroundDensityOverH0Sq()

double BaseSpecies::BackgroundDensityOverH0Sq ( double  a,
double  H0 
) const
virtual

This species' density at scale factor a in units of H0^2, without a background table, for events that must be located before the background is solved. The default scales GetOmega0() by the energy type, which is exact for a constant equation of state, and refuses EnergyType::Other; NCDM overrides it.

Reimplemented in MajoronSpecies, NCDMBaseSpecies, and ScalarTensorSpecies.

◆ GetRadiationOmega0()

virtual double BaseSpecies::GetRadiationOmega0 ( ) const
inlinevirtual

Relativistic (radiation-like) Omega0 contribution at early times. Default 0; ultra-relativistic and interacting-dark-radiation species override.

Reimplemented in CompositeSpecies, IDRSpecies, IDR_DRMDSpecies, MajoronSpecies, and UltraRelativisticSpecies.

◆ DarkRadiationRhoToday()

virtual double BaseSpecies::DarkRadiationRhoToday ( const double *  ) const
inlinevirtual

Dark-radiation energy density today, read from the integrated background vector. Default 0; DarkRadiationSpecies returns its own; composites sum.

Reimplemented in CompositeSpecies, and DarkRadiationSpecies.

◆ NeutrinoOmega0()

virtual double BaseSpecies::NeutrinoOmega0 ( ) const
inlinevirtual

This species' contribution to Omega0 of the neutrino/NCDM sector (fnu). Default 0; NCDM returns GetOmega0(); composites sum children.

Reimplemented in CompositeSpecies, DrPsdSpecies, NCDMBaseSpecies, and WdmDecayProductSpecies.

◆ NeffContribution()

virtual double BaseSpecies::NeffContribution ( double  ) const
inlinevirtual

Contribution to N_eff at redshift z. Default 0; NCDM returns GetNeff(z); composites sum children.

Reimplemented in CompositeSpecies, NCDMBaseSpecies, DrPsdSpecies, IDRSpecies, and WdmDecayProductSpecies.

◆ PrintNeffInfo()

virtual void BaseSpecies::PrintNeffInfo ( ) const
inlinevirtual

Verbose N_eff line (background_verbose). Default no-op; NCDM prints; composites forward to children.

Reimplemented in CompositeSpecies, IDRSpecies, NCDMBaseSpecies, and WdmDecayProductSpecies.

◆ PrintMassInfo()

virtual void BaseSpecies::PrintMassInfo ( ) const
inlinevirtual

Verbose mass/omega line (background_verbose). Default no-op; NCDM prints; composites forward to children.

Reimplemented in CompositeSpecies, NCDMBaseSpecies, and WdmDecayProductSpecies.

◆ PrintBackgroundDetails()

virtual void BaseSpecies::PrintBackgroundDetails ( const double *  ,
double   
) const
inlinevirtual

Details printed once the background table is built (background_verbose > 2). pvecback_today is today's row of the table, rho_crit_today the critical density in it. Default no-op; the scalar field prints its Omega and potential parameters; composites forward to children.

Reimplemented in CompositeSpecies, and ScalarFieldSpecies.

◆ TensorMasslessRelativisticRho()

virtual double BaseSpecies::TensorMasslessRelativisticRho ( const double *  ) const
inlinevirtual

Contribution to the tensor-mode "relativistic" density in the massless approximation. Default 0; NCDM returns 3*P; composites sum.

Reimplemented in CompositeSpecies, and NCDMBaseSpecies.

◆ DeviationFromRadiation()

virtual double BaseSpecies::DeviationFromRadiation ( const double *  ) const
inlinevirtual

|w - 1/3|: how far this species is from ultra-relativistic, for the perturbations' initial time, which must come while every non-cold relic is still relativistic. Default 0 (no such constraint); NCDM computes it; composites take the max over their children.

Reimplemented in DrPsdSpecies, WdmDecayProductSpecies, CompositeSpecies, and NCDMBaseSpecies.

◆ FreeStreamingWavenumbers()

virtual std::vector< double > BaseSpecies::FreeStreamingWavenumbers ( ) const
inlinevirtual

The free-streaming wavenumbers of this species, 1/lambda_fs in 1/Mpc, with lambda_fs the comoving distance its particles have travelled since the big bang at their rms velocity: one for a massive species that free-streams, none for the others. Below that k it clusters like cold matter; above, its free streaming cuts off the matter source, which the continuation past the last perturbation mode (AsymptoticExtrapolation) does not know about. Read after the background is computed. Default: none. NCDM integrates sqrt(3 P/rho); composites gather their children's.

Reimplemented in CompositeSpecies, and NCDMBaseSpecies.

◆ WarnIfNonlinearUnreliable()

virtual void BaseSpecies::WarnIfNonlinearUnreliable ( double  ) const
inlinevirtual

Warn (stdout) if Halofit/HMcode are unreliable with this species. The mass threshold for NCDM is passed by the nonlinear module. Default no-op; NCDM compares its mass; IDM_DR_IDR warns about interacting dark matter; composites forward.

Reimplemented in CompositeSpecies, IDM_DR_IDR_Species, and NCDMBaseSpecies.

◆ ChildOmega0()

virtual std::optional< double > BaseSpecies::ChildOmega0 ( const std::string &  ) const
inlinevirtual

Today's density fraction of the child called name of a composite, or nothing. Lets a caller ask for a sub-species (IDR inside IDM_DR_IDR) by the name it reports. Default: no children.

Reimplemented in CompositeSpecies.

◆ BackgroundAIni()

virtual double BaseSpecies::BackgroundAIni ( double  a_proposed,
double   
) const
inlinevirtual

Earliest scale factor this species needs integration to start from. Default: returns a_proposed unchanged. NCDM species may pull it earlier.

Reimplemented in CompositeSpecies, NCDMBaseSpecies, DrPsdSpecies, and WdmDecayProductSpecies.

◆ ClustersAsMatterCached()

bool BaseSpecies::ClustersAsMatterCached ( ) const
inline

Cached counterparts of ClustersAsMatter()/IsColdMatterSpecies(), valid after FinalizeMatterClassification(). The hot-path tally reads these.

◆ FinalizeMatterClassification()

virtual void BaseSpecies::FinalizeMatterClassification ( )
inlinevirtual

Stamp the cached classification from the (virtual) predicates. Called once by SpeciesCollection::freeze() after every species and its children are built. CompositeSpecies overrides to also recurse into children.

Reimplemented in CompositeSpecies.

◆ ClustersAsMatter()

virtual bool BaseSpecies::ClustersAsMatter ( ) const
inlinevirtual

True iff this species' clustering participates in the total matter tally (delta_m / theta_m and the P_m(k) source). This is the axis-2 (perturbation) counterpart to EnergyType, which only drives the axis-1 background rho_r/rho_m split: a quintessence scalar field is EnergyType::Other (radiation-like early, so the background needs its rho-3P split; dark energy once its pressure is negative) yet does NOT cluster as matter, so it must stay out of P_m(k). A member's contribution is computed generically (its matter density is rho-3P and its density perturbation is delta_rho-3*delta_p), so this predicate only governs membership, not the value. Default: cold matter (energy_type==Matter). Overrides: NCDM/DNCDM (warm matter) return true; composites scan children; a clustering scalar-field dark-matter model would override to true.

Reimplemented in CompositeSpecies, and NCDMBaseSpecies.

◆ IsColdMatterSpecies()

virtual bool BaseSpecies::IsColdMatterSpecies ( ) const
inlinevirtual

True iff this sector participates in the cold-matter tally (delta_cb, theta_cb). Cold matter excludes NCDM/DNCDM (which are "warm" matter). Default: energy_type_ == EnergyType::Matter. Overrides: NCDMBaseSpecies returns false; composites scan children.

Reimplemented in CompositeSpecies, and NCDMBaseSpecies.

◆ HasWarmMatter()

virtual bool BaseSpecies::HasWarmMatter ( ) const
inlinevirtual

True iff this species contributes WARM matter: it clusters in the total matter tally (delta_m / P_m) but stays out of the cold tally (delta_cb / P_cb). This is exactly the condition under which P_cb differs from P_m, so it gates the cb sources and spectra (has_source_delta_cb, has_pk_cb_). Default: derived from the two predicates above. Override: composites scan children (their own two predicates OR over children, so e.g. a cold parent + warm daughter composite would wrongly read as cold).

Reimplemented in CompositeSpecies.

◆ NonClusteringOmega0()

virtual double BaseSpecies::NonClusteringOmega0 ( ) const
inlinevirtual

Today's density fraction in components that neither cluster as matter nor are radiation or dark energy: a quintessence-like field. HMcode 2020 integrates its growth in a cosmology of matter, Lambda and a w0-wa fluid, and refuses these. Default: GetOmega0() for an EnergyType::Other species that does not cluster as matter, else 0. Override: composites sum over children.

Reimplemented in CompositeSpecies.

◆ ColdMatterRho()

virtual double BaseSpecies::ColdMatterRho ( const double *  pvecback) const
inlinevirtual

This species' density in cold matter: Rho for a cold species, else 0. Summed over the species it is the rho_M of the growth factor, and without the baryons the dark matter that annihilates or decays into the plasma. Override: composites sum over children, so IDM_DR_IDR gives its dark matter and not its dark radiation.

Reimplemented in CompositeSpecies.

◆ ColdMatterOmega0()

virtual double BaseSpecies::ColdMatterOmega0 ( ) const
inlinevirtual

The same today, as a density fraction known before the background is integrated (where the EDE fluid places matter-radiation equality). Default: GetOmega0() for a cold species, else 0. Overrides: composites sum over children; DCDM refuses, its density today being an output of the background.

Reimplemented in CompositeSpecies, and DCDMSpecies.

◆ HasNcdm()

virtual bool BaseSpecies::HasNcdm ( ) const
inlinevirtual

Does this species present a momentum-resolved NCDM hierarchy to the module? Gates the ncdm-shaped machinery (the fluid-approximation index, the ncdm initial conditions, several radiation-streaming branches) through SpeciesCollection::has_ncdm.

A virtual rather than a dynamic_cast in the collection: the answer belongs to the class that knows it, and a chain of downcasts silently omits whatever was added last. That is not a missed optimisation — answering false skips DeviationFromRadiation, so the tau_ini bisection stops requiring a massive parent to be relativistic at its initial conditions, and two representations of one model start at different initial times for no physical reason.

COMPOSITES ANSWER FOR THEMSELVES and deliberately do NOT scan children. A generic "any child is NCDM" rule would also flip dcdm_wdm, whose daughter is an NCDMBaseSpecies, changing a merged model's gating for reasons unrelated to it.

Reimplemented in DNCDM_DR_Species, DNCDMInvSpecies, DNCDMProxySpecies, and NCDMBaseSpecies.

◆ SourceSamplingRate()

virtual double BaseSpecies::SourceSamplingRate ( const double *  ) const
inlinevirtual

The rate, in 1/Mpc of conformal time, at which this species makes the source functions vary, or 0 for the default rates only.

perturb_timesampling_for_sources samples the sources at the fastest of the visibility, late-ISW and species rates, taking perturb_sampling_stepsize / rate steps. A field that oscillates faster than aH makes the metric ring at its own frequency; sampled at the default rates, that ringing aliases into the late ISW (an oscillating Early Modified Gravity field put a factor 2.9 into TT at l = 30). Report omega / pi for a field oscillating at omega: twenty samples per period at the default step, which brings that TT back within 0.4% of the converged spectrum (ten samples left 1.2%). Design: docs/superpowers/specs/2026-09-24-scalar-tensor-gravity-design.md

Reimplemented in ScalarTensorSpecies.

◆ MaxMultipole()

virtual int BaseSpecies::MaxMultipole ( const precision *  ,
bool   
) const
inlinevirtual

Highest multipole index this species' hierarchy will address in this mode, or 0 if it carries none.

Consumed by PerturbationsModule::perturb_workspace_init to size ppw->s_l, which the free-streaming loops index up to s_l[l_max] (they read s_l[l+1] for l < l_max). That sizing used to be a hard-coded list of species KEYS, which silently missed the DarkRadiationSpecies daughter inside a DNCDM composite – keyed by its instance name, not "DCDM_DR" – so its hierarchy read past the end of s_l (#421). A species answers for its own storage; a module cannot know.

Over-reporting is safe (s_l is merely longer, and the unused entries are never read); under-reporting is a heap overflow. When in doubt, report more.

Reimplemented in CompositeSpecies, DarkRadiationSpecies, IDRSpecies, PhotonsSpecies, NCDMBaseSpecies, and UltraRelativisticSpecies.

◆ SupportsExplicitPerturbationEvolver()

virtual bool BaseSpecies::SupportsExplicitPerturbationEvolver ( ) const
inlinevirtual

Whether this species' PERTURBATION sector is known to integrate efficiently with an explicit evolver (rkdp45).

Default false, deliberately: stiffness is parameter dependent, and an explicit method degrades without bound on a stiff sector rather than merely getting slower. A species opts in only after its perturbation equations have been benchmarked against ndf15 over the parameter range it supports.

Consumed by InputModule::SelectPerturbationEvolver(), which upgrades the default perturbations evolver from ndf15 to rkdp45 only when EVERY species present opts in (and nothing else in the run adds stiffness). An explicit evolver / evolver_perturbations in the input always wins.

NOTE for subclass authors: this is inherited like any virtual. If you derive from a species that opts in and your sector adds stiffness – an interaction rate, a decay channel, a collision term – override it back to false.

Reimplemented in AxionNCDMSpecies, BaryonsSpecies, CDMSpecies, CompositeSpecies, FluidSpecies, GreyBodyNCDMSpecies, LambdaSpecies, MajoronSpecies, PhotonsSpecies, and UltraRelativisticSpecies.

◆ PrefersExponentialPerturbationEvolver()

virtual bool BaseSpecies::PrefersExponentialPerturbationEvolver ( ) const
inlinevirtual

Does this species carry a stiff Jacobian DIAGONAL that it reports through PerturbDerivsDiagonal, so the exponential evolver (etd) integrates that stiffness EXACTLY rather than resolving it?

This is deliberately independent of SupportsExplicitPerturbationEvolver(). A species can be unsafe under a plain explicit method and still be best served by etd, which is the self-interacting-neutrino case: its collision term is a pure relaxation -alpha_l * taudot * Psi_l reaching 1e7 * aH, so rkdp45 and tsit5 do not complete at ANY tolerance (measured: >380x, and loosening the tolerance 30x changes nothing because the limit is stability, not accuracy), while etd is 1.8-2.5x FASTER than ndf15.

Answering true is a claim that the diagonal is both reported and correct. Pin it against finite differences of PerturbDerivs before setting it – a wrong diagonal costs efficiency and conditioning silently rather than producing a visibly wrong answer.

Reimplemented in CompositeSpecies.

◆ SupportsExponentialPerturbationEvolver()

virtual bool BaseSpecies::SupportsExponentialPerturbationEvolver ( ) const
inlinevirtual

Is this species well-conditioned under etd? A species is, if either it is safe under any explicit method, or its stiffness is the diagonal etd integrates exactly.

Separate from the two above because a COMPOSITE cannot answer it by combining their answers: a composite that merely reports "some child prefers etd" and "not every child is explicit-safe" would hide a child that is neither. CompositeSpecies therefore overrides this to scan its children, exactly as it does for the explicit gate.

Reimplemented in CompositeSpecies.

◆ ApplyFluidLikeNewtonianShift()

void BaseSpecies::ApplyFluidLikeNewtonianShift ( double *  y,
int  idx_delta,
int  idx_theta,
const double *  pvecback,
const PerturbIcContext &  ctx 
) const
inlineprotected

Universal fluid-like gauge shift: delta += (ρ̇/ρ)·alpha ; theta += k²·alpha (shear, l3 and higher moments are gauge-invariant). Fluid-like species call this from PerturbSynchronousToNewtonian, supplying their own delta/theta slots.


The documentation for this class was generated from the following files: