firecrown.updatable

Parameters that can be updated, and collections of them.

Abstract class Updatable is the base class from which any class in Firecrown that supports updating from a ParamsMap should inherit. Such classes are expected to change state only in through their implementation of _update() (including any other private methods used to implement _update()). Other functions should not change the data of Updatable objects.

UpdatableCollection is a subclass of the built-in list. It implements the Updatable interface by calling update() on each element it contains. The append() method is overridden to make sure that only objects which are of a type that implements Updatable can be appended to the list.

Exceptions

MissingSamplerParameterError

Error for when a required parameter is missing.

Classes

Updatable	Abstract class Updatable is the base class for Updatable objects in Firecrown.
UpdatableUsageRecord	Dataclass to record the usage of parameters by an Updatable object.
UpdatableProtocol	Protocol defining the interface for updatable objects.
UpdatableCollection	Class that represents a collection of updatable objects.
DerivedParameter	Represents a derived scalar parameter generated by an Updatable object.
DerivedParameterCollection	Represents a list of DerivedParameter objects.
ParamsMap	A dict-like object in which all keys are strings and values are floats.
RequiredParameters	Represents a sequence of parameter names.
InternalParameter	Class to represent an internally defined parameter.
SamplerParameter	Class to represent a sampler defined parameter.

Functions

get_default_params(*args)	Get a ParamsMap with the default values of all parameters in the updatables.
get_default_params_map(*args)	Get a ParamsMap with the default values of all parameters in the updatables.
assert_updatable_interface(obj[, recursive, ...])	Asserts that all final methods were not overridden.
handle_unused_params(params, updated_records[, ...])	Check for unused keys in the parameters map.
parameter_get_full_name(prefix, param)	Form a full parameter name from the given (optional) prefix and name.
register_new_updatable_parameter([value, shared])	Create a new parameter, either a SamplerParameter or an InternalParameter.

Package Contents

exception firecrown.updatable.MissingSamplerParameterError(parameter)

Bases: RuntimeError

Error for when a required parameter is missing.

Raised when an Updatable fails to be updated because the ParamsMap supplied for the update is missing a parameter that should have been provided by the sampler.

Parameters:

parameter (str)

parameter

class firecrown.updatable.Updatable(parameter_prefix=None)

Bases: abc.ABC

Abstract class Updatable is the base class for Updatable objects in Firecrown.

Any class in Firecrown that supports updating from a ParamsMap should inherit from Updatable. Such classes are expected to change state only in through their implementation of _update (including any other private methods used to implement _update). Other functions should not change the data of Updatable objects.

Parameters:

parameter_prefix (None | str)

parameter_prefix: None | str = None

__setattr__(key, value)

Set the attribute named key to the supplied value.

There is special handling for two types: SamplerParameter and InternalParameter.

We also keep track of all Updatable instance variables added, appending a reference to each to self._updatables as well as storing the attribute directly.

Parameters:

• key (str) – name of the attribute

• value (Any) – value for the attribute

Return type:

None

set_parameter(key, value)

Sets the parameter to the given value.

Assure this InternalParameter or SamplerParameter has not already been set, and then set it.

Parameters:

• key (str) – name of the attribute

• value (firecrown.updatable._parameters_types.InternalParameter | firecrown.updatable._parameters_types.SamplerParameter) – value for the attribute

Return type:

None

set_internal_parameter(key, value)

Assure this InternalParameter has not already been set, and then set it.

Parameters:

• key (str) – name of the attribute

• value (firecrown.updatable._parameters_types.InternalParameter) – value for the attribute

Return type:

None

set_sampler_parameter(value)

Assure this SamplerParameter has not already been set, and then set it.

Parameters:

value (firecrown.updatable._parameters_types.SamplerParameter) – value for the attribute

Return type:

None

update(params, updated_record=None)

Update self by calling to prepare for the next MCMC sample.

We first update the values of sampler parameters from the values in params. An error will be raised if any of self’s sampler parameters can not be found in params or if any internal parameters are provided in params.

We then use the params to update each contained Updatable or UpdatableCollection object. The method _update() is called to give subclasses an opportunity to do any other preparation for the next MCMC sample.

Parameters:

• params (firecrown.updatable._parameters_map.ParamsMap) – new parameter values

• updated_record (list[firecrown.updatable._records.UpdatableUsageRecord] | None)

Return type:

None

is_updated()

Determine if the object has been updated.

A default-constructed Updatable has not been updated. After update, but before reset, has been called the object is updated. After reset has been called, the object is not currently updated.

Returns:

True if the object is currently updated, and False if not.

Return type:

bool

reset()

Reset the updatable.

Clean up self by clearing the _updated status and resetting all internals. We call the abstract method _reset to allow derived classes to clean up any additional internals.

Each MCMC framework connector should call this after handling an MCMC sample.

Return type:

None

required_parameters()

Returns all information about parameters required by this object.

This object returned contains the information for all parameters defined in the implementing class, and any additional parameters.

Returns:

a RequiredParameters object containing all relevant parameters

Return type:

firecrown.updatable._parameters_required.RequiredParameters

get_params_names()

Return the names of the parameters required by this object.

The order of the returned names is arbitrary.

Returns:

a list of parameter names

Return type:

list[str]

get_derived_parameters()

Returns a collection of derived parameters.

This occurs once per iteration of the statistical analysis. First call returns the DerivedParameterCollection, further calls return None.

Returns:

a collection of derived parameters, or None

Return type:

None | firecrown.updatable._parameters_derived.DerivedParameterCollection

class firecrown.updatable.UpdatableUsageRecord

Dataclass to record the usage of parameters by an Updatable object.

cls: str

prefix: str | None

obj_id: int

sampler_params: list[str]

internal_params: list[str]

child_records: list[UpdatableUsageRecord]

already_updated: bool = False

property is_empty: bool

Check if the record is empty.

Return True if the record has no sampler parameters, internal parameters, or child records.

Return type:

bool

property is_empty_parent: bool

Check if the record is an empty parent.

Return True if the record has no sampler or internal parameters and exactly one child record.

Return type:

bool

get_log_lines(level=0, parent=None, print_empty=False)

Print the usage record.

Parameters:

• level (int)

• parent (str | None)

• print_empty (bool)

Return type:

list[str]

class firecrown.updatable.UpdatableProtocol

Bases: Protocol

Protocol defining the interface for updatable objects.

Both Updatable and UpdatableCollection implement this interface. The @runtime_checkable decorator allows isinstance() checks.

update(params, updated_record=None)

Update the object with new parameters.

Parameters:

• params (firecrown.updatable._parameters_map.ParamsMap)

• updated_record (list[firecrown.updatable._records.UpdatableUsageRecord] | None)

Return type:

None

reset()

Reset the object to its initial state.

Return type:

None

is_updated()

Check if the object has been updated.

Return type:

bool

required_parameters()

Return the required parameters for this object.

Return type:

firecrown.updatable._parameters_required.RequiredParameters

get_derived_parameters()

Get the derived parameters for this object.

Return type:

None | firecrown.updatable._parameters_derived.DerivedParameterCollection

class firecrown.updatable.UpdatableCollection(iterable=None)

Bases: collections.UserList[T], Generic[T]

Class that represents a collection of updatable objects.

UpdatableCollection is a list of Updatable objects and is itself supports update() and reset() (although it does not inherit from Updatable).

Every item in an UpdatableCollection must itself be Updatable. Calling update() on the collection results in every item in the collection being updated.

Parameters:

iterable (None | collections.abc.Iterable[T])

update(params, updated_record=None)

Update self by calling update() on each contained item.

Parameters:

• params (firecrown.updatable._parameters_map.ParamsMap) – new parameter values for each contained item

• updated_record (list[firecrown.updatable._records.UpdatableUsageRecord] | None)

Return type:

None

is_updated()

Returns whether this updatable has been updated.

Return True if the object is currently updated, and False if not. A default-constructed Updatable has not been updated. After update, but before reset, has been called the object is updated. After reset has been called, the object is not currently updated.

Return type:

bool

reset()

Resets self by calling reset() on each contained item.

Return type:

None

required_parameters()

Return a RequiredParameters object.

The RequiredParameters object is formed by concatenating the RequiredParameters of each contained item.

Return type:

firecrown.updatable._parameters_required.RequiredParameters

get_derived_parameters()

Get all derived parameters if any.

Return type:

None | firecrown.updatable._parameters_derived.DerivedParameterCollection

append(item)

Append the given item to self.

If the item is not Updatable a TypeError is raised.

Parameters:

item (T) – new item to be appended to the list

Return type:

None

__setitem__(key, value)

Set self[key] to value; raise TypeError if Value is not Updatable.

firecrown.updatable.get_default_params(*args)

Get a ParamsMap with the default values of all parameters in the updatables.

Parameters:

args (firecrown.updatable._base.Updatable) – updatables to get the default parameters from

Returns:

a ParamsMap with the default values of all parameters

Return type:

dict[str, float]

firecrown.updatable.get_default_params_map(*args)

Get a ParamsMap with the default values of all parameters in the updatables.

Parameters:

args (firecrown.updatable._base.Updatable) – updatables to get the default parameters from

Returns:

a ParamsMap with the default values of all parameters

Return type:

firecrown.updatable._parameters_map.ParamsMap

firecrown.updatable.assert_updatable_interface(obj, recursive=True, raise_on_override=False)

Asserts that all final methods were not overridden.

The methods:

• update()

• reset()

• is_updated()

• required_parameters()

• get_derived_parameters()

Are final and should not be overridden. If any of these methods are overridden a TypeError is raised.

Parameters:

• obj (firecrown.updatable._types.UpdatableProtocol)

• recursive (bool)

• raise_on_override (bool)

class firecrown.updatable.DerivedParameter(section, name, val)

Represents a derived scalar parameter generated by an Updatable object.

This class provide the type that encapsulate a derived scalar quantity (represented

by a float) computed by an Updatable object during a statistical analysis.

Parameters:

• section (str)

• name (str)

• val (float)

section: str

name: str

val: float

get_val()

Return the value of this parameter.

Return type:

float

__eq__(other)

Compare two DerivedParameter objects for equality.

This implementation raises a NotImplemented exception unless both objects are DerivedParameter objects.

Two DerivedParameter objects are equal if they have the same section, name and value.

Parameters:

other (object)

Return type:

bool

get_full_name()

Constructs the full name using section–name.

class firecrown.updatable.DerivedParameterCollection(derived_parameters)

Represents a list of DerivedParameter objects.

Parameters:

derived_parameters (collections.abc.Sequence[DerivedParameter])

derived_parameters: dict[str, DerivedParameter]

__len__()

Return the number of parameters contained.

Return type:

int

__add__(other)

Add two DerivedParameterCollection objects.

Return a new DerivedParameterCollection with the lists of DerivedParameter objects.

If other is none return self. Otherwise, constructs a new object representing the addition.

Note that this function returns a new object that does not share state with either argument to the addition operator.

Parameters:

other (None | DerivedParameterCollection)

__eq__(other)

Compare two DerivedParameterCollection objects for equality.

This implementation raises a NotImplemented exception unless both objects are DerivedParameterCollection objects.

Two DerivedParameterCollection objects are equal if they contain the same DerivedParameter objects.

Parameters:

other (object)

__iter__()

Implementation of lazy iteration through the collection.

Return type:

collections.abc.Iterator[tuple[str, str, float]]

add_required_parameter(derived_parameter)

Adds derived_parameter to the collection.

We raises an ValueError if a required parameter with the same name is already present in the collection.

Parameters:

derived_parameter (DerivedParameter)

get_derived_list()

Implement lazy iteration through the contained parameter names.

Return type:

list[DerivedParameter]

class firecrown.updatable.ParamsMap(*args, **kwargs)

A dict-like object in which all keys are strings and values are floats.

The recommended access method is get_from_prefix_param, rather than indexing with square brackets like x[].

params: dict[str, float]

lower_case: bool = False

used_keys: set[str]

__getitem__(key)

Return the value for the given key.

If the key has not been used, add it to the set of used keys.

Parameters:

key (str) – key

Returns:

value

Return type:

float

__setitem__(key, value)

Set the value for the given key.

Parameters:

• key (str) – key

• value (float) – value

Return type:

None

__contains__(key)

Return True if the key is in the map, False otherwise.

Parameters:

key (str) – key

Returns:

True if the key is in the map, False otherwise

Return type:

bool

copy()

Return a shallow copy of the ParamsMap.

Return type:

ParamsMap

items()

Return an iterator over the items in the dictionary.

Returns:

an iterator over the items in the dictionary

union(other)

Return a new ParamsMap that is the union of self and other.

If the same key is used in both self and other, the values in both self and other must be equal.

Parameters:

other (ParamsMap) – other ParamsMap

Returns:

a new ParamsMap that is the union of self and other

Return type:

ParamsMap

update(d)

Update self with the values from d.

This will raise an error if any of the keys in d are already in self.

Parameters:

d (dict[str, float]) – dictionary

Return type:

None

use_lower_case_keys(enable)

Control whether keys will be translated into lower case.

If enable is True, such translation will be done. This can help make sure code works with CosmoSIS, because such translation is done inside CosmoSIS itself.

Parameters:

enable (bool) – whether to enable or disable this option

Return type:

None

get(key, default=None)

Return the value for the given key, or default if the key is not found.

Parameters:

• key (str) – key

• default (float | None) – default value, used if the key is not found

Returns:

value

Return type:

float

get_from_full_name(full_name)

Return the parameter identified by the full name.

Raises a KeyError if the parameter is not found.

Parameters:

full_name (str)

Return type:

float

get_from_prefix_param(prefix, param)

Return the parameter identified by the optional prefix and parameter name.

See parameter_get_full_name for rules on the forming of prefix and name. Raises a KeyError if the parameter is not found.

Parameters:

• prefix (None | str)

• param (str)

Return type:

float

get_unused_keys()

Return the set of keys that have not been used.

This is the set of keys that are not in self.used_keys.

Return type:

set[str]

keys()

Return the set of keys in the map.

Returns:

set of keys

Return type:

set[str]

firecrown.updatable.handle_unused_params(params, updated_records, raise_on_unused=False)

Check for unused keys in the parameters map.

Parameters:

• params (ParamsMap)

• updated_records (list)

• raise_on_unused (bool)

firecrown.updatable.parameter_get_full_name(prefix, param)

Form a full parameter name from the given (optional) prefix and name.

Parameter names, as stored in SACC, for example, contain an optional prefix; if a prefix is present, it will be separated from the name by an underscore.

Prefixes and names should avoid containing embedded underscores. This is currently not enforced in the code.

The parameter name can not be empty, even if accompanied by a prefix; this is enforced in the code.

Parameters:

• prefix (None | str) – optional prefix

• param (str) – name

Returns:

full name

Raises:

ValueError – if the parameter name is empty

Return type:

str

class firecrown.updatable.RequiredParameters(params)

Represents a sequence of parameter names.

This class provides some type safety to distinguish between an arbitrary list of strings, and one intended to be a list of required parameter names.

An instance can be created from a list of strings. Instances can be concatenated using +, and compared for equality using ==.

To iterate through the names (which are strings), use get+params_names, which implements lazy evaluation.

Parameters:

params (collections.abc.Iterable[firecrown.updatable._parameters_types.SamplerParameter])

params_set: set[firecrown.updatable._parameters_types.SamplerParameter]

__len__()

Return the number of parameters contained.

__add__(other)

Return a new RequiredParameters with the concatenated names.

Note that this function returns a new object that does not share state with either argument to the addition operator.

Parameters:

other (RequiredParameters)

Return type:

RequiredParameters

__sub__(other)

Return a new RequiredParameters with the names in self but not in other.

Note that this function returns a new object that does not share state with either argument to the subtraction operator.

Parameters:

other (RequiredParameters)

Return type:

RequiredParameters

__eq__(other)

Compare two RequiredParameters objects for equality.

This implementation raises a NotImplemented exception unless both objects are RequireParameters objects.

Two RequireParameters objects are equal if their contained names are equal (including appearing in the same order).

Parameters:

other (object)

get_params_names()

Implement lazy iteration through the contained parameter names.

Return type:

collections.abc.Iterator[str]

get_default_values()

Return a dictionary with the default values of the parameters.

Return type:

dict[str, float]

class firecrown.updatable.InternalParameter(value)

Class to represent an internally defined parameter.

Parameters:

value (float)

value

set_value(value)

Set the value of this parameter.

Parameters:

value (float) – new value

get_value()

Return the current value of this parameter.

Return type:

float

class firecrown.updatable.SamplerParameter(*, default_value, name=None, prefix=None, shared=False)

Class to represent a sampler defined parameter.

Parameters:

• default_value (float)

• name (None | str)

• prefix (None | str)

• shared (bool)

default_value

get_default_value()

Get the default value of this parameter.

Return type:

float

set_fullname(prefix, name)

Set the prefix and name of this parameter.

If the parameter is shared (shared=True), the prefix will be ignored and the parameter will have the same name across all instances.

Parameters:

• prefix (str | None) – new prefix (ignored if shared=True)

• name (str) – the name of the parameter

property shared: bool

Get whether this parameter is shared across instances.

Return type:

bool

property prefix: str | None

Get the prefix of this parameter.

Return type:

str | None

property name: str

Get the name of this parameter.

Return type:

str

property fullname: str

Get the full name of this parameter.

Return type:

str

__hash__()

Return the hash of the full name of this parameter.

Return type:

int

__eq__(other)

Return whether this parameter is equal to another.

Two SamplerParameter objects are equal if they have the same full name.

Parameters:

other (object)

Return type:

bool

firecrown.updatable.register_new_updatable_parameter(value=None, *, default_value, shared=False)

Create a new parameter, either a SamplerParameter or an InternalParameter.

If value is None, the result will be a SamplerParameter; Firecrown will expect this value to be supplied by the sampling framework. If value is a float quantity, then Firecrown will expect this parameter to not be supplied by the sampling framework, and instead the provided value will be used for every sample.

Only None or a float value is allowed.

Parameters:

• value (None | float) – the value of the parameter

• default_value (float) – the default value of the parameter to be used if value is None

• shared (bool) – if True, the parameter will not receive a prefix, making it shared across all instances (only applies when value is None)

Returns:

a SamplerParameter if value is None, otherwise an InternalParameter

Raises:

TypeError – if value is not None and not a float