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.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.register_new_updatable_parameter Module Contents --------------- .. 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) Bases: :py:obj:`dict`\ [\ :py:obj:`str`\ , :py:obj:`float`\ ] .. autoapi-inheritance-diagram:: firecrown.parameters.ParamsMap :parts: 1 A specialized dict 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:: lower_case :type: bool :value: False .. 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_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: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`