Theory codes


Theory is a base class for theory codes and likelihoods.

Both likelihoods and theories calculate something. Likelihoods are distinguished because they calculate a log likelihood. Both theory codes and likelihoods can calculate other things, and they may have complex dependencies between them: e.g. the likelihood depends on observable A that is computed by theory code B than in turn requires calculation of input calculation by code C.

This module contains the base class for all of these calculation components. It handles caching of results, so that calculations do not need to be redone when the parameters on which a component directly (or indirectly) depends have not changed.

Subclasses generally provide the Theory.get_requirements(), Theory.calculate() and initialization methods as required. The Theory.must_provide() method is used to tell a code which requirements are actually needed by other components, and may return a dictionary of additional conditional requirements based on those passed.

The Theory.calculate() method saves all needed results in the state dictionary (which is cached and reused as needed). Subclasses define get_X or get_result(X) methods to return the actual result of the calculation for X for the current cache state. The Theory.get_param() method returns the value of a derived parameter for the current state.

For details and examples of how to handle multiple theory codes with complex dependencies see Creating theory classes and dependencies.

Theory class

class theory.Theory(info=mappingproxy({}), name=None, timing=None, packages_path=None, initialize=True, standalone=True)

Bases: CobayaComponent

Base class theory that can calculate something.


Get a dictionary of requirements (or a list of requirement name, option tuples) that are always needed (e.g. must be calculated by another component or provided as input parameters).

Return type:

Union[Dict[str, Any], Sequence[str], Sequence[Tuple[str, Dict[str, Any]]]]


dictionary or list of tuples of requirement names and options (or iterable of requirement names if no optional parameters are needed)


Function called by Cobaya with the actual products that this component needs to compute (i.e. the things this component can provide that are actually used by other components). The function can return conditional requirements that this component needs from other components in order to compute those things.

The requirements argument is a requirement name with any optional parameters. This function may be called more than once with different requirements.

Return type:

Union[None, Dict[str, Any], Sequence[str], Sequence[Tuple[str, Dict[str, Any]]]]


optional dictionary (or list of requirement name, option tuples) of conditional requirements for the ones requested.

calculate(state, want_derived=True, **params_values_dict)

Do the actual calculation and store results in state dict

  • state – dictionary to store results

  • want_derived – whether to set state[‘derived’] derived parameters

  • params_values_dict – parameter values


None or True if success, False for fail


Additional initialization after requirements called and input_params and output_params have been assigned (but provider and assigned requirements not yet set).


Final initialization after parameters, provider and assigned requirements set. The provider is used to get the requirements of this theory using provider.get_X() and provider.get_param(‘Y’).


provider (Provider) – the theory.Provider instance that should be used by this component to get computed requirements


Interface function for likelihoods and other theory components to get derived parameters.

Return type:


get_result(result_name, **kwargs)

Interface function for likelihood and other theory components to get quantities calculated by this component. By default assumes the quantity is just directly saved into the current state (i.e. returns state[result_name]).

  • result_name – name of quantity

  • kwargs – options specific to X or this component




Get a dictionary of quantities X that can be retrieved using get_X methods.


dictionary of the form {X: get_X method}


Get a list of names of quantities that can be retrieved using the general get_result(X) method.

Return type:



iterable of quantity names


Get a list of derived parameters that this component can calculate. The default implementation returns the result based on the params attribute set via the .yaml file or class params (with derived:True for derived parameters).

Return type:



iterable of parameter names


Get a list of parameters supported by this component, can be used to support parameters that don’t explicitly appear in the .yaml or class params attribute or are otherwise explicitly supported (e.g. via requirements)

Return type:



iterable of names of parameters


Whether it is allowed to pass all unassigned input parameters to this component (True) or whether parameters must be explicitly specified (False).


True or False

property input_params_extra

Parameters required from other components, to be passed as input parameters.


Set how many states to cache

check_cache_and_compute(params_values_dict, dependency_params=None, want_derived=False, cached=True)

Takes a dictionary of parameter values and computes the products needed by the likelihood, or uses the cached value if that exists for these parameters. If want_derived, the derived parameters are saved in the computed state (retrieved using current_derived).

params_values_dict can be safely modified and stored.


Return object containing get_X, get_param, get_result methods to get computed results. This defaults to self, but can change to delegate provision to another object


object instance


Return dictionary of optional names and helper Theory instances that should be used in conjunction with this component. The helpers can be created here as only called once, and before any other use of helpers.

Return type:

Dict[str, Theory]


dictionary of names and Theory instances


Get combined list of self.attr and helper.attr for all helper theories


attr – attr name


combined list


Finalizes the class, if something needs to be cleaned up.

classmethod compare_versions(version_a, version_b, equal=True)

Checks whether version_a is equal or higher than version_b.

For strictly higher, pass equal=False (default: True).



classmethod get_associated_file_content(ext, file_root=None)

Return the content of the associated file, if it exists.

This function handles extracting package files when they may be inside a zipped package and thus not directly accessible.

Return type:



The content of the file as a string, if it exists and can be read. None otherwise.

classmethod get_bibtex()

Get the content of .bibtex file for this component. If no specific bibtex from this class, it will return the result from an inherited class if that provides bibtex.

Return type:


classmethod get_class_options(input_options=mappingproxy({}))

Returns dictionary of names and values for class variables that can also be input and output in yaml files, by default it takes all the (non-inherited and non-private) attributes of the class excluding known specials.

Could be overridden using input_options to dynamically generate defaults, e.g. a set of input parameters generated depending on the input_options.


input_options – optional dictionary of input parameters

Return type:

Dict[str, Any]


dict of names and values

classmethod get_class_path()

Get the file path for the class.

Return type:


classmethod get_defaults(return_yaml=False, yaml_expand_defaults=True, input_options=mappingproxy({}))

Return defaults for this component_or_class, with syntax:

option: value

  [...]  # if required

  [...]  # if required

If keyword return_yaml is set to True, it returns literally that, whereas if False (default), it returns the corresponding Python dict.

Note that in external components installed as zip_safe=True packages files cannot be accessed directly. In this case using !default .yaml includes currently does not work.

Also note that if you return a dictionary it may be modified (return a deep copy if you want to keep it).

if yaml_expand_defaults then !default: file includes will be expanded

input_options may be a dictionary of input options, e.g. in case default params are dynamically dependent on an input variable


Returns a short description of the class. By default, returns the class’ docstring.

You can redefine this method to dynamically generate the description based on the class initialisation info (see e.g. the source code of MCMC’s class method _get_desc()).

classmethod get_file_base_name()

Gets the string used as the name for .yaml, .bib files, typically the class name or an un-CamelCased class name

Return type:


classmethod get_kind()

Return, as a string, the kind of this component.


Get the name. This is usually set by the name used in the input .yaml, but otherwise defaults to the fully-qualified class name.

Return type:



name string

classmethod get_qualified_class_name()

Get the distinct shortest reference name for the class of the form module.ClassName or module.submodule.ClassName etc. For Cobaya components the name is relative to subpackage for the relevant kind of class (e.g. Likelihood names are relative to cobaya.likelihoods).

For external classes it loads the shortest fully qualified name of the form package.ClassName or package.module.ClassName or package.subpackage.module.ClassName, etc.

Return type:


classmethod get_text_file_content(file_name)

Return the content of a file in the directory of the module, if it exists.

Return type:



Get version information for this component.

Return type:

Union[None, str, Dict[str, Any]]


string or dict of values or None

classmethod get_yaml_file()

Gets the file name of the .yaml file for this component if it exists on file (otherwise None).

Return type:



Whether to track version information for this component


Initializes the class (called from __init__, before other initializations).


Can use this to define any default instance attributes before setting to the input dictionary (from inputs or defaults)

validate_info(k, value, annotations)

Does any validation on parameter k read from an input dictionary or yaml file, before setting the corresponding class attribute. You could enforce consistency with annotations here, but does not by default.

  • k (str) – name of parameter

  • value (Any) – value

  • annotations (dict) – resolved inherited dictionary of attributes for this class