firecrown.parameters ==================== .. py:module:: firecrown.parameters .. autoapi-nested-parse:: 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 ------- .. autoapisummary:: firecrown.parameters.UpdatableUsageRecord firecrown.parameters.ParamsMap firecrown.parameters.RequiredParameters firecrown.parameters.DerivedParameter firecrown.parameters.DerivedParameterCollection firecrown.parameters.SamplerParameter firecrown.parameters.InternalParameter Functions --------- .. autoapisummary:: firecrown.parameters.parameter_get_full_name firecrown.parameters.handle_unused_params firecrown.parameters.register_new_updatable_parameter Module Contents --------------- .. py:class:: UpdatableUsageRecord Dataclass to record the usage of parameters by an Updatable object. .. py:attribute:: cls :type: str .. py:attribute:: prefix :type: str | None .. py:attribute:: sampler_params :type: list[str] .. py:attribute:: internal_params :type: list[str] .. py:function:: 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. :param prefix: optional prefix :param param: name :return: full name :raises ValueError: if the parameter name is empty .. py:class:: 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[]. .. py:attribute:: params :type: dict[str, float] .. py:attribute:: lower_case :type: bool :value: False .. py:attribute:: used_keys :type: set[str] .. py:attribute:: usages :type: list[UpdatableUsageRecord] :value: [] .. py:method:: __getitem__(key) Return the value for the given key. If the key has not been used, add it to the set of used keys. :param key: key :return: value .. py:method:: __setitem__(key, value) Set the value for the given key. :param key: key :param value: value .. py:method:: __contains__(key) Return True if the key is in the map, False otherwise. :param key: key :return: True if the key is in the map, False otherwise .. py:method:: copy() Return a shallow copy of the ParamsMap. .. py:method:: items() Return an iterator over the items in the dictionary. :return: an iterator over the items in the dictionary .. py:method:: 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. :param other: other ParamsMap :return: a new ParamsMap that is the union of self and other .. py:method:: 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. :param d: dictionary .. py:method:: 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. :param enable: whether to enable or disable this option .. py:method:: get(key, default = None) Return the value for the given key, or default if the key is not found. :param key: key :param default: default value, used if the key is not found :return: value .. py:method:: get_from_full_name(full_name) Return the parameter identified by the full name. Raises a KeyError if the parameter is not found. .. py:method:: 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. .. py:method:: 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. .. py:method:: keys() Return the set of keys in the map. :return: set of keys .. py:method:: record_usage(cls, prefix, sampler_params, internal_params) Record the usage of parameters based on the provided lists. This method marks parameters as used based on the provided lists of sampler and internal parameters. :param cls: type of the updatable being recorded. :param prefix: optional prefix for the parameters :param sampler_params: list of sampler parameter names :param internal_params: list of internal parameter names .. py:method:: report_usages() Generate a report of parameter usages by Updatable objects. :return: A formatted string report of parameter usages. .. py:function:: handle_unused_params(params, raise_on_unused = False) Check for unused keys in the parameters map. .. py:class:: 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. .. py:attribute:: params_set :type: set[SamplerParameter] .. py:method:: __len__() Return the number of parameters contained. .. py:method:: __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. .. py:method:: __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. .. py:method:: __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). .. py:method:: get_params_names() Implement lazy iteration through the contained parameter names. .. py:method:: get_default_values() Return a dictionary with the default values of the parameters. .. py:class:: 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. .. py:attribute:: section :type: str .. py:attribute:: name :type: str .. py:attribute:: val :type: float .. py:method:: get_val() Return the value of this parameter. .. py:method:: __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. .. py:method:: get_full_name() Constructs the full name using section--name. .. py:class:: DerivedParameterCollection(derived_parameters) Represents a list of DerivedParameter objects. .. py:attribute:: derived_parameters :type: dict[str, DerivedParameter] .. py:method:: __len__() Return the number of parameters contained. .. py:method:: __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. .. py:method:: __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. .. py:method:: __iter__() Implementation of lazy iteration through the collection. .. py:method:: 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. .. py:method:: get_derived_list() Implement lazy iteration through the contained parameter names. .. py:class:: SamplerParameter(*, default_value, name = None, prefix = None) Class to represent a sampler defined parameter. .. py:attribute:: default_value .. py:method:: get_default_value() Get the default value of this parameter. .. py:method:: set_fullname(prefix, name) Set the prefix of this parameter. :param prefix: new prefix .. py:property:: prefix :type: str | None Get the prefix of this parameter. .. py:property:: name :type: str Get the name of this parameter. .. py:property:: fullname :type: str Get the full name of this parameter. .. py:method:: __hash__() Return the hash of the full name of this parameter. .. py:method:: __eq__(other) Return whether this parameter is equal to another. Two SamplerParameter objects are equal if they have the same full name. .. py:class:: InternalParameter(value) Class to represent an internally defined parameter. .. py:attribute:: value .. py:method:: set_value(value) Set the value of this parameter. :param value: new value .. py:method:: get_value() Return the current value of this parameter. .. py:function:: register_new_updatable_parameter(value = None, *, default_value) 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. :param value: the value of the parameter :param default_value: the default value of the parameter to be used if `value` is `None` :return: a `SamplerParameter` if `value` is `None`, otherwise an `InternalParameter` :raises TypeError: if `value` is not `None` and not a `float`