Skip to content

Parameter 

Parameter(**data: float | str | list[str] | SourceCollection | None)

Bases: BaseModel


              flowchart TD
              technologydata.parameter.Parameter[Parameter]

              

              click technologydata.parameter.Parameter href "" "technologydata.parameter.Parameter"

Encapsulate a value with its unit, provenance, notes, sources, and more optional attributes required to describe technology parameters, like carrier, and heating value.

Attributes:

  • magnitude (int | float) –

    The numerical value of the parameter.

  • units (Optional[str]) –

    The unit of the parameter.

  • carrier (Optional[str]) –

    The energy carrier.

  • heating_value (Optional[str]) –

    The heating value type.

  • provenance (Optional[list[str]]) –

    Ordered history of human-readable descriptions of the data's provenance.

  • note (Optional[str]) –

    Additional notes about the parameter.

  • sources (Optional[SourceCollection]) –

    List of sources for the parameter.

Methods:

  • __add__ –

    Add this Parameter to another Parameter.

  • __eq__ –

    Check for equality with another Parameter object.

  • __mul__ –

    Multiply two Parameter instances.

  • __pow__ –

    Raise the parameter's value to a specified power.

  • __str__ –

    Render magnitude, units, carrier, and heating value as one human-readable string.

  • __sub__ –

    Subtract another Parameter from this Parameter.

  • __truediv__ –

    Divide this Parameter by another Parameter.

  • change_heating_value –

    Change the heating value of the parameter.

  • isclose –

    Check whether another parameter is numerically and contextually consistent.

  • to –

    Convert the parameter's quantity to new units.

  • to_currency –

    Change the currency of the parameter.

carrier class-attribute instance-attribute 

carrier: Annotated[str | None, Field(description="Carriers of the units, e.g. 'H2', 'el', 'H2O'.")] = None

heating_value class-attribute instance-attribute 

heating_value: Annotated[str | None, Field(description="Heating value type for energy carriers ('LHV' or 'HHV').")] = None

magnitude instance-attribute 

magnitude: Annotated[int | float, Field(description='The numerical value of the parameter.')]

note class-attribute instance-attribute 

note: Annotated[str | None, Field(description='Additional notes.')] = None

provenance class-attribute instance-attribute 

provenance: Annotated[list[str] | None, Field(description="Ordered history of human-readable descriptions of how this parameter's value was derived, e.g. sourced from literature, parsed from a file, or calculated from a formula.")] = None

sources class-attribute instance-attribute 

sources: Annotated[SourceCollection, Field(description='List of sources for this parameter.')] = SourceCollection(sources=[])

units class-attribute instance-attribute 

units: Annotated[str | None, Field(description='The unit of the parameter.')] = None

__add__ 

__add__(other: Self) -> Self

Add this Parameter to another Parameter.

Parameters:

  • other (Parameter) –

    The Parameter instance to add.

Returns:

  • Parameter –

    A new Parameter instance representing the sum of the two parameters.

Notes

This method checks for parameter compatibility before performing the addition. The resulting Parameter retains the carrier, heating value, and combines provenance, notes, and sources from both operands. Preserves the provenance of both parameters and adds a provenance entry for the operation.

__eq__ 

__eq__(other: object) -> bool

Check for equality with another Parameter object.

Compares all attributes of the current instance with those of the other object.

Parameters:

  • other (object) –

    The object to compare with. Expected to be an instance of Parameter.

Returns:

  • bool –

    True if all attributes are equal between self and other, False otherwise. Returns False if other is not a Parameter instance.

__mul__ 

__mul__(other: int | float | Self) -> Self

Multiply two Parameter instances.

Parameters:

  • other (int | float | Parameter) –

    A scalar or a Parameter instance to multiply with.

Returns:

  • Parameter –

    A new Parameter instance representing the product of the two parameters.

Raises:

  • ValueError –

    If the heating values of the two parameters are not compatible (i.e., not equal).

Notes
  • Multiplication is only performed if the heating values are compatible.
  • The method multiplies the underlying quantities and carriers (if present).
  • The heating value of the resulting parameter is the product of the input heating values.
  • Provenance, notes, and sources are combined from both parameters, and a provenance entry describing the multiplication is appended.
  • Multiplying by a scalar appends a provenance entry recording the factor.
  • Compatibility checks beyond heating values are not performed.

__pow__ 

__pow__(exponent: float | int) -> Self

Raise the parameter's value to a specified power.

Parameters:

  • exponent (float or int) –

    The exponent to raise the parameter's value to.

Returns:

  • Parameter –

    A new Parameter instance with the value raised to the specified power.

Notes

This method updates the internal pint attributes before applying the power operation. If the parameter has a carrier, it is also raised to the specified power. A provenance entry recording the exponent is appended.

__str__ 

__str__() -> str

Render magnitude, units, carrier, and heating value as one human-readable string.

__sub__ 

__sub__(other: Self) -> Self

Subtract another Parameter from this Parameter.

Parameters:

  • other (Parameter) –

    The Parameter instance to subtract.

Returns:

  • Parameter –

    A new Parameter instance representing the result of the subtraction.

Notes

This method checks for parameter compatibility before performing the subtraction. The resulting Parameter retains the carrier, heating value, and combines provenance, notes, and sources. Preserves the provenance of both parameters and adds a provenance entry for the operation.

__truediv__ 

__truediv__(other: int | float | Self) -> Self

Divide this Parameter by another Parameter.

Parameters:

  • other (float | Parameter) –

    A scalar or a Parameter instance to divide by.

Returns:

  • Parameter –

    A new Parameter instance representing the division result.

Raises:

  • ValueError –

    If the heating values of the two parameters are different. Preserves the provenance of both parameters and adds a provenance entry for the operation.

Notes

The method divides the quantities of the parameters and constructs a new Parameter. It also handles the division of carriers and heating values if present.

change_heating_value 

change_heating_value(to_heating_value: str) -> Self

Change the heating value of the parameter.

This converts the parameter's heating value to another heating value, e.g. from "LHV" to "HHV", by taking into account the parameter's carrier.

Parameters:

  • to_heating_value (str) –

    The target heating value to convert to, e.g. "LHV", "HHV".

Returns:

  • Parameter –

    A new Parameter object with the converted heating value. Records a provenance entry for the conversion.

Raises:

  • ValueError –

    If the current parameter does not have a carrier or a heating value set,

Examples:

>>> Parameter(magnitude=1, units="kWh", carrier="H2", heating_value="LHV").change_heating_value("HHV")
<Parameter magnitude=1.5, units='kWh', carrier='H2', heating_value='HHV'>

isclose 

isclose(other: Self, rtol: float = 1e-06, atol: float = 1e-09) -> bool

Check whether another parameter is numerically and contextually consistent.

Consistency means: - same carrier - same heating value - compatible units (or both unitless) - numerically close magnitudes after unit harmonization

to 

to(units: str) -> Self

Convert the parameter's quantity to new units.

A provenance entry recording the conversion is appended, unless the units are unchanged.

Parameters:

  • units (str) –

    The target units, which must not change the currency.

Returns:

  • Parameter –

    A new Parameter object in the target units.

to_currency 

to_currency(target_currency: str, country: str, source: str = 'worldbank') -> Self

Change the currency of the parameter.

This allows for conversion to a different currency as well as for inflation adjustments. To properly adjust for inflation, the function requires the country for which the inflation adjustment should be applied for.

Note that this will harmonise all currencies used in the parameter's units, i.e. if the parameter units contains multiple different currencies, all of them will be converted to the target currency.

Parameters:

  • target_currency (str) –

    The target currency unit to convert to, e.g. "USD_2020", "EUR_2024", "CNY_2022".

  • country (str) –

    The country for which the inflation adjustment should be made for. Must be the official ISO 3166-1 alpha-3 country code, e.g. "USA", "DEU", "CHN".

  • source (str, default: 'worldbank' ) –

    The source of the inflation data, either "worldbank"/"wb" or "international_monetary_fund"/"imf". Defaults to "worldbank". Depending on the source, different years to adjust for inflation may be available.

Returns:

  • Parameter –

    A new Parameter object with the converted currency. Records a provenance entry for the conversion.

Examples:

>>> param.to_currency("USD_2024", "USA")
>>> param.to_currency("EUR_2020", "DEU", source="imf")
>>> param.to_currency("EUR_2023", "USA", source="worldbank")