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.

Attributes

GeneralUpdatable
T

Exceptions

MissingSamplerParameterError

Error for when a required parameter is missing.

Classes

Updatable	Abstract class Updatable is the base class for Updatable objects in Firecrown.
UpdatableCollection	Class that represents a collection of updatable objects.

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.

Module Contents

type firecrown.updatable.GeneralUpdatable = 'Updatable' | 'UpdatableCollection'

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.parameters.InternalParameter | firecrown.parameters.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.parameters.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.parameters.SamplerParameter) – value for the attribute

Return type:

None

update(params)

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.parameters.ParamsMap) – new parameter values

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 reseting 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.parameters.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.parameters.DerivedParameterCollection

firecrown.updatable.T

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)

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

Parameters:

params (firecrown.parameters.ParamsMap) – new parameter values for each contained item

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.parameters.RequiredParameters

get_derived_parameters()

Get all derived parameters if any.

Return type:

None | firecrown.parameters.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 (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 (Updatable) – updatables to get the default parameters from

Returns:

a ParamsMap with the default values of all parameters

Return type:

firecrown.parameters.ParamsMap