Skip to content

openscm_calibration.parameter_handling#

Handling of parameters

In particular, helping to ensure that we use the correct parameter order and units in the many places where the order and units are not checked by the receiving function (e.g. all of scipy's optimisation routines, which work on bare arrays).

Classes:

Name Description
BoundDefinition

Definition of bounds for a parameter
ParameterDefinition

Definition of a parameter
ParameterOrder

Parameter order definition

BoundDefinition #

Bases: Generic[BoundsValue]

Definition of bounds for a parameter

Methods:

Name Description
check_greather_than_lower

Check that the value is greater than the lower bound

Attributes:

Name Type Description
lower BoundsValue

Lower bound
upper BoundsValue

Upper bound
Source code in src/openscm_calibration/parameter_handling.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
@define
class BoundDefinition(Generic[BoundsValue]):
    """Definition of bounds for a parameter"""

    lower: BoundsValue = field()
    """Lower bound"""

    upper: BoundsValue = field()
    """Upper bound"""

    @upper.validator
    def check_greather_than_lower(
        instance: BoundDefinition[BoundsValue],
        attribute: attr.Attribute[pint.registry.UnitRegistry.Quantity],
        value: pint.registry.UnitRegistry.Quantity,
    ) -> None:
        """Check that the value is greater than the lower bound"""
        if value <= instance.lower:
            msg = (
                "`upper` must be greater than `lower`. "
                f"Received {instance.lower=}, instance.upper={value=}`."
            )
            raise ValueError(msg)

lower class-attribute instance-attribute #

lower: BoundsValue = field()

Lower bound

upper class-attribute instance-attribute #

upper: BoundsValue = field()

Upper bound

check_greather_than_lower #

check_greather_than_lower(
    instance: BoundDefinition[BoundsValue],
    attribute: Attribute[Quantity],
    value: Quantity,
) -> None

Check that the value is greater than the lower bound

Source code in src/openscm_calibration/parameter_handling.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
@upper.validator
def check_greather_than_lower(
    instance: BoundDefinition[BoundsValue],
    attribute: attr.Attribute[pint.registry.UnitRegistry.Quantity],
    value: pint.registry.UnitRegistry.Quantity,
) -> None:
    """Check that the value is greater than the lower bound"""
    if value <= instance.lower:
        msg = (
            "`upper` must be greater than `lower`. "
            f"Received {instance.lower=}, instance.upper={value=}`."
        )
        raise ValueError(msg)

ParameterDefinition #

Bases: Generic[BoundsValue]

Definition of a parameter

Methods:

Name Description
bounds_m

Get the magnitude of self.bounds

Attributes:

Name Type Description
bounds BoundDefinition[BoundsValue] | None

The bounds for the parameter
name str

The parameter's name
unit str | None

The parameter's default unit for usage that isn't unit-aware
Source code in src/openscm_calibration/parameter_handling.py 
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
@define
class ParameterDefinition(Generic[BoundsValue]):
    """Definition of a parameter"""

    name: str
    """The parameter's name"""

    unit: str | None
    """
    The parameter's default unit for usage that isn't unit-aware

    If this is `None`, we assume that no units apply to the parameter.
    """

    bounds: BoundDefinition[BoundsValue] | None = None
    """The bounds for the parameter"""

    @overload
    def bounds_m(self, unit: None = None) -> tuple[BoundsValue, BoundsValue]: ...

    @overload
    def bounds_m(self, unit: str) -> tuple[float, float]: ...

    def bounds_m(
        self, unit: str | None = None
    ) -> tuple[BoundsValue, BoundsValue] | tuple[float, float]:
        """
        Get the magnitude of `self.bounds`

        Parameters
        ----------
        unit
            Unit in which to return the magnitude.

            Only applies if `self.unit` is not `None`.

            If `self.unit` is not `None` and `unit` is not supplied,
            we use `self.unit` instead
            (i.e. `self.unit` functions as a default).

        Returns
        -------
        :
            Magnitude of the bounds (lower, upper).
        """
        if self.bounds is None:
            msg = (
                f"No bounds provided for {self.name}. "
                "Please re-initialise this parameter definition."
            )
            raise ValueError(msg)

        if self.unit is None:
            return (self.bounds.lower, self.bounds.upper)

        unit_h = unit if unit is not None else self.unit

        return (
            # Use type ignores because pint's error message is clear enough
            self.bounds.lower.to(unit_h).m,  # type: ignore[union-attr]
            self.bounds.upper.to(unit_h).m,  # type: ignore[union-attr]
        )

bounds class-attribute instance-attribute #

bounds: BoundDefinition[BoundsValue] | None = None

The bounds for the parameter

name instance-attribute #

name: str

The parameter's name

unit instance-attribute #

unit: str | None

The parameter's default unit for usage that isn't unit-aware

If this is None, we assume that no units apply to the parameter.

bounds_m #

bounds_m(
    unit: None = None,
) -> tuple[BoundsValue, BoundsValue]

bounds_m(unit: str) -> tuple[float, float]

bounds_m(
    unit: str | None = None,
) -> tuple[BoundsValue, BoundsValue] | tuple[float, float]

Get the magnitude of self.bounds

Parameters:

Name Type Description Default
unit str | None

Unit in which to return the magnitude.

Only applies if self.unit is not None.

If self.unit is not None and unit is not supplied, we use self.unit instead (i.e. self.unit functions as a default).

 None

Returns:

Type Description
tuple[BoundsValue, BoundsValue] | tuple[float, float]

Magnitude of the bounds (lower, upper).
Source code in src/openscm_calibration/parameter_handling.py 
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
def bounds_m(
    self, unit: str | None = None
) -> tuple[BoundsValue, BoundsValue] | tuple[float, float]:
    """
    Get the magnitude of `self.bounds`

    Parameters
    ----------
    unit
        Unit in which to return the magnitude.

        Only applies if `self.unit` is not `None`.

        If `self.unit` is not `None` and `unit` is not supplied,
        we use `self.unit` instead
        (i.e. `self.unit` functions as a default).

    Returns
    -------
    :
        Magnitude of the bounds (lower, upper).
    """
    if self.bounds is None:
        msg = (
            f"No bounds provided for {self.name}. "
            "Please re-initialise this parameter definition."
        )
        raise ValueError(msg)

    if self.unit is None:
        return (self.bounds.lower, self.bounds.upper)

    unit_h = unit if unit is not None else self.unit

    return (
        # Use type ignores because pint's error message is clear enough
        self.bounds.lower.to(unit_h).m,  # type: ignore[union-attr]
        self.bounds.upper.to(unit_h).m,  # type: ignore[union-attr]
    )

ParameterOrder #

Parameter order definition

Methods:

Name Description
bounds_m

Get the magnitude of the bounds of the parameters

Attributes:

Name Type Description
names tuple[str, ...]

Get the names of the parameters
parameters tuple[ParameterDefinition[SupportedBoundsTypes], ...]

Parameters
Source code in src/openscm_calibration/parameter_handling.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
@define
class ParameterOrder:
    """Parameter order definition"""

    parameters: tuple[ParameterDefinition[SupportedBoundsTypes], ...]
    """
    Parameters

    These are stored in a tuple, hence order is preserved.
    """

    def bounds_m(
        self, units: dict[str, str] | None = None
    ) -> nptype.NDArray[np.float64]:
        """
        Get the magnitude of the bounds of the parameters

        Parameters
        ----------
        units
            Units to use for the parameters.

            Keys are parameter names,
            values are the units to use for the parameter's bounds.

            If not supplied at all,
            we simply use the default unit for each parameter
            i.e. the default behaviour of
            [`ParameterDefinition.bounds_m`][openscm_calibration.parameter_handling.ParameterDefinition.bounds_m].

            If not supplied for a given parameter,
            we simply use the parameter's default unit
            i.e. the default behaviour of
            [`ParameterDefinition.bounds_m`][openscm_calibration.parameter_handling.ParameterDefinition.bounds_m].

        Returns
        -------
        :
            Magnitude of the bounds of the parameters (in order)
        """
        out_l = []
        for parameter in self.parameters:
            if units is not None and parameter.name in units:
                unit = units[parameter.name]

            else:
                unit = None

            out_l.append(parameter.bounds_m(unit))

        return np.array(out_l)

    @property
    def names(self) -> tuple[str, ...]:
        """
        Get the names of the parameters

        Returns
        -------
        :
            Names of the parameters (in order)
        """
        return tuple([v.name for v in self.parameters])

names property #

names: tuple[str, ...]

Get the names of the parameters

Returns:

Type Description
tuple[str, ...]

Names of the parameters (in order)

parameters instance-attribute #

parameters: tuple[
    ParameterDefinition[SupportedBoundsTypes], ...
]

Parameters

These are stored in a tuple, hence order is preserved.

bounds_m #

bounds_m(
    units: dict[str, str] | None = None,
) -> NDArray[float64]

Get the magnitude of the bounds of the parameters

Parameters:

Name Type Description Default
units dict[str, str] | None

Units to use for the parameters.

Keys are parameter names, values are the units to use for the parameter's bounds.

If not supplied at all, we simply use the default unit for each parameter i.e. the default behaviour of ParameterDefinition.bounds_m.

If not supplied for a given parameter, we simply use the parameter's default unit i.e. the default behaviour of ParameterDefinition.bounds_m.

 None

Returns:

Type Description
NDArray[float64]

Magnitude of the bounds of the parameters (in order)
Source code in src/openscm_calibration/parameter_handling.py 
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def bounds_m(
    self, units: dict[str, str] | None = None
) -> nptype.NDArray[np.float64]:
    """
    Get the magnitude of the bounds of the parameters

    Parameters
    ----------
    units
        Units to use for the parameters.

        Keys are parameter names,
        values are the units to use for the parameter's bounds.

        If not supplied at all,
        we simply use the default unit for each parameter
        i.e. the default behaviour of
        [`ParameterDefinition.bounds_m`][openscm_calibration.parameter_handling.ParameterDefinition.bounds_m].

        If not supplied for a given parameter,
        we simply use the parameter's default unit
        i.e. the default behaviour of
        [`ParameterDefinition.bounds_m`][openscm_calibration.parameter_handling.ParameterDefinition.bounds_m].

    Returns
    -------
    :
        Magnitude of the bounds of the parameters (in order)
    """
    out_l = []
    for parameter in self.parameters:
        if units is not None and parameter.name in units:
            unit = units[parameter.name]

        else:
            unit = None

        out_l.append(parameter.bounds_m(unit))

    return np.array(out_l)