API Reference¶

Quantity¶

class energyunits.Quantity(value, unit, substance=None, basis=None, reference_year=None)[source]¶

Bases: object

Physical quantity with value, unit, and optional metadata.

Supports: - Unit conversions (e.g., MWh to GJ) - Substance-based conversions (e.g., coal mass to CO2 emissions) - Heating value basis conversions (HHV/LHV) - Inflation adjustments for cost quantities - Arithmetic operations with dimensional analysis

Parameters:

value (float | int | List[float] | ndarray)
unit (str)
substance (str | None)
basis (str | None)
reference_year (int | None)

classmethod list_units(dimension=None)[source]¶

List all available units, optionally filtered by dimension.

Parameters:: dimension – Filter by dimension (e.g., “ENERGY”, “POWER”, “MASS”).
Returns:: Sorted list of unit strings.

Examples

Quantity.list_units() # All units Quantity.list_units(“ENERGY”) # Energy units only

classmethod list_dimensions()[source]¶

List all available dimensions.

Returns:: Sorted list of dimension strings.

classmethod list_substances(has_property=None)[source]¶

List all available substances.

Parameters:: has_property – Filter to substances with this property (e.g., “hhv”).
Returns:: Sorted list of substance names.

Examples

Quantity.list_substances() # All substances Quantity.list_substances(“density”) # Substances with density

classmethod list_currencies()[source]¶

List all available currencies.

Returns:: List of currency codes.

to(target_unit=None, basis=None, substance=None, reference_year=None)[source]¶

Convert to another unit, basis, substance, and/or reference year.

This is the unified conversion method. Conversions are applied in sequence: substance → basis → unit → inflation.

Special case: When combining currency conversion with year change: - Order becomes: substance → basis → inflation → unit - Uses “inflate first, then convert” convention - Issues warning about economic assumptions

Examples

energy = Quantity(100, “MWh”) energy.to(“GJ”) # → 360 GJ

coal = Quantity(1000, “kg”, “coal”) coal.to(“MWh”) # Coal mass → energy content coal.to(“kg”, substance=”CO2”) # Coal mass → CO2 emissions

capex_2020 = Quantity(1000, “USD/kW”, reference_year=2020) capex_2025 = capex_2020.to(reference_year=2025)

cost_eur_2015 = Quantity(50, “EUR/MWh”, reference_year=2015) cost_usd_2024 = cost_eur_2015.to(“USD/MWh”, reference_year=2024) # Inflates EUR 2015→2024, then converts using 2024 exchange rate

Parameters:

target_unit (str | None)
basis (str | None)
substance (str | None)
reference_year (int | None)

Return type:

Quantity

Unit Registry¶

class energyunits.registry.UnitRegistry[source]¶

Bases: object

Registry of units, dimensions, and conversion factors.

load_units(file_path)[source]¶

Load custom units from JSON file.

Parameters:: file_path (str)

get_dimension(unit)[source]¶

Get dimension of a unit (cached for performance).

Parameters:: unit (str)
Return type:: str

get_conversion_factor(from_unit, to_unit)[source]¶

Get conversion factor between compatible units (cached for performance).

Parameters:

from_unit (str)
to_unit (str)

Return type:

float

are_dimensions_compatible(from_dim, to_dim)[source]¶

Check if dimensions can be converted.

Parameters:

from_dim (str)
to_dim (str)

Return type:

bool

convert_between_dimensions(value, from_unit, to_unit, substance=None, **kwargs)[source]¶

Convert between related dimensions.

Parameters:

value (float)
from_unit (str)
to_unit (str)
substance (str | None)

Return type:

float

get_corresponding_unit(unit, target_dimension)[source]¶

Get corresponding unit in another dimension (e.g., MW → MWh).

Parameters:

unit (str)
target_dimension (str)

Return type:

str

get_multiplication_result(dim1, dim2)[source]¶

Get result dimension and source dimension from multiplying two dimensions.

Returns: (result_dimension, source_dimension) or None Example: (POWER, TIME) -> (“ENERGY”, “POWER”)

Parameters:

dim1 (str)
dim2 (str)

Return type:

tuple | None

get_division_result(numerator_dim, denominator_dim)[source]¶

Get result dimension from dividing two dimensions.

Returns: result_dimension or None Example: (ENERGY, TIME) -> “POWER”

Parameters:

numerator_dim (str)
denominator_dim (str)

Return type:

str | None

list_units(dimension=None)[source]¶

List all available units, optionally filtered by dimension.

Parameters:: dimension (str | None) – Filter by dimension (e.g., “ENERGY”, “POWER”, “MASS”). If None, returns all units.
Returns:: Sorted list of unit strings.
Return type:: list

list_dimensions()[source]¶

List all available dimensions.

Returns:: Sorted list of unique dimension strings.
Return type:: list

Substance Registry¶

class energyunits.substance.SubstanceRegistry[source]¶

Bases: object

Registry of substances and their properties.

load_substances(file_path)[source]¶

Load custom substances from JSON file.

Parameters:: file_path (str)

hhv(substance_id)[source]¶: Get higher heating value in MJ/kg.

lhv(substance_id)[source]¶: Get lower heating value in MJ/kg.

density(substance_id)[source]¶: Get density in kg/m3.

list_substances(has_property=None)[source]¶

List all available substances, optionally filtered by property.

Parameters:: has_property – Filter to substances that have this property defined (e.g., “hhv”, “density”, “carbon_content”).
Returns:: Sorted list of substance names.

get_properties(substance_id)[source]¶

Get all properties for a substance as a dict.

Parameters:: substance_id – Substance identifier.
Returns:: Dict of property name to value.

lhv_hhv_ratio(substance_id)[source]¶: Get the ratio of LHV to HHV.

calculate_combustion_product(fuel_quantity, target_substance)[source]¶: Calculate combustion products from fuel based on stoichiometry.

Inflation¶

class energyunits.inflation.InflationRegistry[source]¶

Bases: object

Registry for inflation data with historical rates.

load_inflation(file_path)[source]¶

Load custom inflation data from JSON file.

Parameters:: file_path (str)

get_cumulative_inflation_factor(currency, from_year, to_year)[source]¶

Calculate cumulative inflation factor between two years.

Parameters:

currency (str)
from_year (int)
to_year (int)

Return type:

float

get_supported_currencies()[source]¶: Get list of supported currencies.

detect_currency_from_unit(unit)[source]¶

Detect currency from unit string.

Parameters:: unit (str)
Return type:: str | None

Exchange Rates¶

class energyunits.exchange_rate.ExchangeRateRegistry[source]¶

Bases: object

Registry for historical exchange rate data.

Provides year-dependent exchange rates for currency conversions. All rates are expressed as: 1 unit of currency = X USD.

load_exchange_rates(file_path)[source]¶

Load custom exchange rate data from JSON file.

Parameters:: file_path (str)

get_exchange_rate(currency, year=None)[source]¶

Get exchange rate for a currency in a specific year.

Parameters:

currency (str) – Currency code (EUR, GBP, JPY, CNY)
year (int | None) – Year for exchange rate. If None, uses most recent available.

Returns:

Exchange rate (1 currency unit = X USD)

Raises:

ValueError – If currency not supported or year not available

Return type:

float

convert_currency(value, from_currency, to_currency, year=None)[source]¶

Convert amount from one currency to another using rates from a specific year.

Parameters:

value (float) – Amount to convert
from_currency (str) – Source currency code
to_currency (str) – Target currency code
year (int | None) – Year for exchange rate. If None, uses most recent available.

Returns:

Converted amount

Return type:

float

get_conversion_factor(from_currency, to_currency, year=None)[source]¶

Get conversion factor between two currencies for a specific year.

Returns the factor such that: amount_to = amount_from * factor

Parameters:

from_currency (str)
to_currency (str)
year (int | None)

Return type:

float

get_supported_currencies()[source]¶: Get list of supported currencies.

detect_currency_from_unit(unit)[source]¶

Detect currency from unit string.

Parameters:: unit (str) – Unit string (e.g., “USD”, “EUR/MWh”, “USD/kW”)
Returns:: Currency code if detected, None otherwise
Return type:: str | None

is_currency(unit)[source]¶

Check if a unit is a pure currency (not compound like USD/MWh).

Parameters:: unit (str)
Return type:: bool

warn_currency_inflation_combination()[source]¶: Issue warning about currency conversion + inflation adjustment path dependency.

Unit Constants¶

Unit constants for IDE-friendly autocompletion.

Instead of using raw strings, you can import unit constants for better IDE support and typo prevention:

from energyunits.units import MWh, GJ, MW, USD, EUR

energy = Quantity(100, MWh) energy.to(GJ)

These are simple string constants — they work identically to passing the string directly.