Input Reference

This page collects technical reference information for users providing data to the KPI Calculator. For explanations of what each KPI means and how to interpret results, see KPI Guide. For usage instructions, see Getting Started.

Time Series Keys

The calculators search for time series data on each asset using specific key names. The first matching key is used; if none match, the asset contributes zero to that metric.

Energy calculator:

Metric	Asset types	Keys searched (in order)
Consumption	Consumer	ThermalConsumption, Consumption, Energy, heat_power_primary (simulator-core: primary side of heat pump / heat exchanger)
Production	Producer, Geothermal	ThermalProduction, Production, heat_supplied, Energy, heat_power_secondary (simulator-core: secondary side of heat pump / heat exchanger)
Demand	Consumer	ThermalDemand, Demand, heat_demand (falls back to consumption keys)

Emission calculator:

Asset type	Keys searched (in order)	Notes
Producer, Geothermal	ThermalProduction, Production, heat_supplied, Energy, heat_power_secondary	Same keys as energy production
Consumer	ThermalConsumption, Consumption, Energy, heat_power_primary	Same keys as energy consumption
Conversion	ElectricalConsumption, electricity_consumption, ThermalProduction	Only used for emission calculation. electricity_consumption is the field name used by simulator-core for heat pump assets.

Time series values are in Watts (power). The calculator integrates over the time step to get energy in Joules and annualizes based on the series duration. If no matching key is found, the asset contributes zero to that metric (logged at DEBUG level). If the time series has a non-positive duration (time_step × number_of_values ≤ 0), the asset is skipped with a WARNING log.

KPI elements whose computed value is zero — because no matching time series or cost attributes were found — are omitted entirely from the ESDL output rather than written as zero-value elements. This is consistent with mesido’s behavior and avoids pyESDL’s serialization quirk where float(0.0) is emitted as a <stringItem> with no value attribute.

Cost calculator: Variable operational and maintenance costs in EUR/kWh or EUR/MWh use the first time series available on the asset (regardless of key name). For geothermal assets with COP > 0, the energy is divided by COP before applying the cost rate.

Asset Categories

Cost KPIs (CAPEX, OPEX) are broken down by category. Each ESDL asset type maps to one category:

Category	Asset types
Production	Producer, Geothermal
Consumption	Consumer
Storage	Storage
Transport	Transport, Pipe, Pump
Conversion	Conversion

The All category is the sum across all asset types.

Cost Units

The calculator accepts cost values in the units specified in the ESDL costInformation element. Built-in conversion factors (defined in COST_UNIT_FACTORS in constants.py) handle the conversion automatically.

Investment and installation costs:

Unit	Conversion
EUR	Used directly (no conversion factor needed)
EUR/kW	value x asset power (W) x 0.001
EUR/MW	value x asset power (W) x 1e-6
EUR/m	value x asset length (m)
EUR/km	value x asset length (m) x 0.001
EUR/m3	value x asset volume (m3), no factor needed

Fixed operational and fixed maintenance costs:

Unit	Conversion
EUR, EUR/yr	Used directly as annual cost
EUR/MW	value x asset power (W) x 1e-6
% OF CAPEX	value x (investment + installation) x 0.01

Variable operational and variable maintenance costs:

Unit	Conversion
EUR, EUR/yr	Used directly as annual cost
EUR/kWh	value x annual energy (J) x 2.78e-7
EUR/MWh	value x annual energy (J) x 2.78e-10

Geothermal COP adjustment: For geothermal assets with a COP (Coefficient of Performance) greater than zero, variable operational and maintenance costs in EUR/kWh or EUR/MWh are applied to energy / COP rather than energy directly. This reflects that geothermal plants deliver more heat than they consume as input energy.

If a cost field uses a unit not listed above, the cost is ignored and a WARNING is logged with the asset name and the unsupported unit string. Check the log output when cost KPIs seem unexpectedly low.