firecrown.parameters

Classes and functions to support groups of named parameters.

These are used in Firecrown in preference to the Python dictionary in order to provide better type safety.

Classes

`ParamsMap`	A dict-like object in which all keys are strings and values are floats.
`RequiredParameters`	Represents a sequence of parameter names.
`DerivedParameter`	Represents a derived scalar parameter generated by an Updatable object.
`DerivedParameterCollection`	Represents a list of DerivedParameter objects.
`SamplerParameter`	Class to represent a sampler defined parameter.
`InternalParameter`	Class to represent an internally defined parameter.

Functions

`parameter_get_full_name`(prefix, param)	Form a full parameter name from the given (optional) prefix and name.
`handle_unused_params`(params[, raise_on_unused])	Check for unused keys in the parameters map.
`register_new_updatable_parameter`([value])	Create a new parameter, either a SamplerParameter or an InternalParameter.

Module Contents

firecrown.parameters.parameter_get_full_name(prefix, param)[source]

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.parameters.ParamsMap(*args, **kwargs)[source]

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)[source]

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)[source]

Set the value for the given key.

Parameters:

key (str) – key
value (float) – value

Return type:

None

__contains__(key)[source]

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()[source]

Return a shallow copy of the ParamsMap.

Return type:: ParamsMap

items()[source]

Return an iterator over the items in the dictionary.

Returns:: an iterator over the items in the dictionary

union(other)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

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()[source]

Return the set of keys in the map.

Returns:: set of keys
Return type:: set[str]

firecrown.parameters.handle_unused_params(params, raise_on_unused=False)[source]

Check for unused keys in the parameters map.

Parameters:

params (ParamsMap)
raise_on_unused (bool)

class firecrown.parameters.RequiredParameters(params)[source]

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[SamplerParameter])

params_set: set[SamplerParameter]

__len__()[source]: Return the number of parameters contained.

__add__(other)[source]

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)[source]

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)[source]

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()[source]

Implement lazy iteration through the contained parameter names.

Return type:: collections.abc.Iterator[str]

get_default_values()[source]

Return a dictionary with the default values of the parameters.

Return type:: dict[str, float]

class firecrown.parameters.DerivedParameter(section, name, val)[source]

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()[source]

Return the value of this parameter.

Return type:: float

__eq__(other)[source]

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()[source]: Constructs the full name using section–name.

class firecrown.parameters.DerivedParameterCollection(derived_parameters)[source]

Represents a list of DerivedParameter objects.

Parameters:: derived_parameters (collections.abc.Sequence[DerivedParameter])

derived_parameters: dict[str, DerivedParameter]

__len__()[source]

Return the number of parameters contained.

Return type:: int

__add__(other)[source]

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)[source]

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__()[source]

Implementation of lazy iteration through the collection.

Return type:: collections.abc.Iterator[tuple[str, str, float]]

add_required_parameter(derived_parameter)[source]

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()[source]

Implement lazy iteration through the contained parameter names.

Return type:: list[DerivedParameter]

class firecrown.parameters.SamplerParameter(*, default_value, name=None, prefix=None)[source]

Class to represent a sampler defined parameter.

Parameters:

default_value (float)
name (None | str)
prefix (None | str)

default_value

get_default_value()[source]

Get the default value of this parameter.

Return type:: float

set_fullname(prefix, name)[source]

Set the prefix of this parameter.

Parameters:

prefix (str | None) – new prefix
name (str)

property prefix: str | None[source]

Get the prefix of this parameter.

Return type:: str | None

property name: str[source]

Get the name of this parameter.

Return type:: str

property fullname: str[source]

Get the full name of this parameter.

Return type:: str

__hash__()[source]

Return the hash of the full name of this parameter.

Return type:: int

__eq__(other)[source]

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

class firecrown.parameters.InternalParameter(value)[source]

Class to represent an internally defined parameter.

Parameters:: value (float)

value

set_value(value)[source]

Set the value of this parameter.

Parameters:: value (float) – new value

get_value()[source]

Return the current value of this parameter.

Return type:: float

firecrown.parameters.register_new_updatable_parameter(value=None, *, default_value)[source]

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

Returns:

a SamplerParameter if value is None, otherwise an InternalParameter

Raises:

TypeError – if value is not None and not a float