Energy System Engines

Complete reference for all energy system classes.

Energy, Entropy, and Exergy Analysis Engine.

This module contains classes for modeling various energy systems including: - Domestic hot water systems (electric boiler, gas boiler, heat pump boiler) - Air source heat pumps (cooling and heating modes) - Ground source heat pumps (cooling and heating modes) - Solar-assisted systems - Electric heaters

Domestic Hot Water Systems

ElectricBoiler

GasBoiler

GasBoilerTank

class enex_analysis.gas_boiler_tank.GasBoilerTank(eta_comb=0.9, T_exh=70.0, burner_capacity=15000.0, r0=0.2, H=0.8, x_shell=0.01, x_ins=0.1, k_shell=25, k_ins=0.03, h_o=15, T_tank_w_upper_bound=65.0, T_tank_w_lower_bound=60.0, T_mix_w_out=45.0, T_sup_w=10.0, dV_mix_w_out_max=0.001, tank_always_full=True, tank_level_lower_bound=0.5, tank_level_upper_bound=1.0, dV_tank_w_in_refill=0.001, prevent_simultaneous_flow=False, on_schedule=None, stc=None, uv=None)[source]

Bases: object

Gas-fired boiler with storage tank.

Combustion chamber heats water which is stored in an insulated tank. Service water is delivered via a 3-way mixing valve.

Parameters:

  • eta_comb (float)

  • T_exh (float)

  • burner_capacity (float)

  • r0 (float)

  • H (float)

  • x_shell (float)

  • x_ins (float)

  • k_shell (float)

  • k_ins (float)

  • h_o (float)

  • T_tank_w_upper_bound (float)

  • T_tank_w_lower_bound (float)

  • T_mix_w_out (float)

  • T_sup_w (float)

  • dV_mix_w_out_max (float)

  • tank_always_full (bool)

  • tank_level_lower_bound (float)

  • tank_level_upper_bound (float)

  • dV_tank_w_in_refill (float)

  • prevent_simultaneous_flow (bool)

  • on_schedule (list[tuple[float, float]] | None)

__init__(eta_comb=0.9, T_exh=70.0, burner_capacity=15000.0, r0=0.2, H=0.8, x_shell=0.01, x_ins=0.1, k_shell=25, k_ins=0.03, h_o=15, T_tank_w_upper_bound=65.0, T_tank_w_lower_bound=60.0, T_mix_w_out=45.0, T_sup_w=10.0, dV_mix_w_out_max=0.001, tank_always_full=True, tank_level_lower_bound=0.5, tank_level_upper_bound=1.0, dV_tank_w_in_refill=0.001, prevent_simultaneous_flow=False, on_schedule=None, stc=None, uv=None)[source]
Parameters:

  • eta_comb (float)

  • T_exh (float)

  • burner_capacity (float)

  • r0 (float)

  • H (float)

  • x_shell (float)

  • x_ins (float)

  • k_shell (float)

  • k_ins (float)

  • h_o (float)

  • T_tank_w_upper_bound (float)

  • T_tank_w_lower_bound (float)

  • T_mix_w_out (float)

  • T_sup_w (float)

  • dV_mix_w_out_max (float)

  • tank_always_full (bool)

  • tank_level_lower_bound (float)

  • tank_level_upper_bound (float)

  • dV_tank_w_in_refill (float)

  • prevent_simultaneous_flow (bool)

  • on_schedule (list[tuple[float, float]] | None)

analyze_steady(T_tank_w, T0, dV_mix_w_out=0.0, return_dict=True)[source]

Run a steady-state analysis.

Parameters:

  • T_tank_w (float) – Tank water temperature [°C].

  • T0 (float) – Dead-state temperature [°C].

  • dV_mix_w_out (float) – Service water flow rate [m³/s].

  • return_dict (bool) – If True return dict; else single-row DataFrame.

Return type:

dict | pd.DataFrame

analyze_dynamic(simulation_period_sec, dt_s, T_tank_w_init_C, dhw_usage_schedule, T0_schedule, tank_level_init=1.0, result_save_csv_path=None)[source]

Run a time-stepping dynamic simulation.

Parameters:

  • simulation_period_sec (int) – Total simulation duration [s].

  • dt_s (int) – Time step size [s].

  • T_tank_w_init_C (float) – Initial tank temperature [°C].

  • dhw_usage_schedule (array-like) – DHW usage schedule.

  • T0_schedule (array-like) – Outdoor temperature per step [°C].

  • tank_level_init (float) – Initial fractional tank level (0–1).

  • result_save_csv_path (str | None) – Optional CSV output path.

Returns:

Per-timestep result DataFrame.

Return type:

pd.DataFrame

postprocess_exergy(df)[source]

Compute gas-boiler exergy variables.

Exergy topology (4 components):

  1. NG chemical exergy, exhaust exergy

  2. Water exergy (tank inlet/outlet, mixing valve)

  3. Heat loss exergy, tank stored exergy

  4. Component-level exergy destruction

  5. Exergetic efficiency metrics

Parameters:

df (pd.DataFrame) – Result DataFrame from analyze_dynamic().

Returns:

DataFrame with exergy columns appended.

Return type:

pd.DataFrame

HeatPumpBoiler

enex_analysis_engine.enex_engine.HeatPumpBoiler

alias of AirSourceHeatPumpBoiler

SolarAssistedGasBoiler

GroundSourceHeatPumpBoiler

Heat Pump Systems

AirSourceHeatPump_cooling

class enex_analysis_engine.enex_engine.AirSourceHeatPump_cooling[source]

Bases: object

Air source heat pump model for cooling mode.

Simulates a single-step refrigerant cycle with indoor/outdoor heat exchangers and fans. Call system_update() after setting operating conditions to compute COP, capacities, and component powers.

system_update()[source]
__init__()

AirSourceHeatPump_heating

class enex_analysis_engine.enex_engine.AirSourceHeatPump_heating[source]

Bases: object

Air source heat pump model for heating mode.

Mirror of AirSourceHeatPump_cooling configured for space heating. The condenser rejects heat to the indoor side while the evaporator absorbs from outdoor air.

system_update()[source]
__init__()

ASHPB_PV_ESS

class enex_analysis.ashpb_pv_ess.ASHPB_PV_ESS(*, pv, ess=None, eta_inv=0.95, T_inv_K=313.15, **kwargs)[source]

Bases: AirSourceHeatPumpBoiler

ASHPB scenario where the heat pump is supplied by PV + ESS + Grid.

The PV/ESS routing is resolved synchronously inside _augment_results after the HP compressor load is known. No 1-step lag: the PV energy is allocated to the exact HP load produced in the same timestep.

Parameters:

  • pv (PhotovoltaicSystem) – Pure-physics PV + charge-controller model.

  • ess (EnergyStorageSystem) – Pure-physics battery model with charge() / discharge().

  • eta_inv (float) – Inverter DC→AC efficiency [–].

  • T_inv_K (float) – Inverter temperature for entropy calculation [K].

  • **kwargs – Forwarded to AirSourceHeatPumpBoiler.

__init__(*, pv, ess=None, eta_inv=0.95, T_inv_K=313.15, **kwargs)[source]
Parameters:

  • pv (PhotovoltaicSystem)

  • ess (EnergyStorageSystem | None)

  • eta_inv (float)

  • T_inv_K (float)

ASHPB_STC_preheat

class enex_analysis.ashpb_stc_preheat.ASHPB_STC_preheat(*, stc, **kwargs)[source]

Bases: AirSourceHeatPumpBoiler

ASHPB + SolarThermalCollector in mains_preheat placement.

Physical configuration

The STC preheats mains cold water before it enters the storage tank. The raised inlet temperature (T_tank_w_in_override_K) reduces the thermal load on the heat pump compressor.

Orchestration responsibility

This class owns all simulation logic for the STC:

  • _run_subsystems: activation probe + calc_performance() → sets T_tank_w_in_override_K when active

  • _augment_results: result column assembly (uses pump outlet temperature directly; no re-evaluation at solved tank temp)

  • _postprocess: STC exergy calculation. Tank boundary corrections are not applied because the preheated inlet temperature is already reflected in the core X_tank_w_in [W] column (X_in_tank_add = 0).

type stc:

SolarThermalCollector

param stc:

Pure physics engine. No mode constraint required.

type stc:

SolarThermalCollector

type **kwargs:

param **kwargs:

Forwarded to AirSourceHeatPumpBoiler.

raises TypeError:

If stc is not a SolarThermalCollector instance.

__init__(*, stc, **kwargs)[source]
Parameters:

stc (SolarThermalCollector)

ASHPB_STC_tank

class enex_analysis.ashpb_stc_tank.ASHPB_STC_tank(*, stc, **kwargs)[source]

Bases: AirSourceHeatPumpBoiler

ASHPB + SolarThermalCollector in tank_circuit placement.

Physical configuration

The STC collector loop is connected directly to the storage tank. The STC draws water from the tank, heats it via solar energy, and returns it through the pump. The STC is activated only when the collector outlet temperature exceeds the current tank temperature.

Orchestration responsibility

This class owns all simulation logic for the STC:

  • _run_subsystems: activation probe + calc_performance()

  • _augment_results: result column assembly (re-evaluates at solved tank temperature for accuracy)

  • _postprocess: STC exergy calculation and tank boundary correction (X_tot, Xc_tank)

type stc:

SolarThermalCollector

param stc:

Pure physics engine. No mode constraint required.

type stc:

SolarThermalCollector

type **kwargs:

param **kwargs:

Forwarded to AirSourceHeatPumpBoiler.

raises TypeError:

If stc is not a SolarThermalCollector instance.

__init__(*, stc, **kwargs)[source]
Parameters:

stc (SolarThermalCollector)

GroundSourceHeatPump_cooling

class enex_analysis_engine.enex_engine.GroundSourceHeatPump_cooling[source]

Bases: object

Ground source heat pump model for cooling mode.

Uses borehole heat exchangers with finite-line-source g-functions for soil thermal response. Call system_update() each time step to advance the ground temperature history.

system_update()[source]
__init__()

GroundSourceHeatPump_heating

class enex_analysis_engine.enex_engine.GroundSourceHeatPump_heating[source]

Bases: object

Ground source heat pump model for heating mode.

Mirror of GroundSourceHeatPump_cooling configured for space heating. The evaporator absorbs heat from the ground loop while the condenser supplies heat indoors.

system_update()[source]
__init__()

Dynamic Systems

ElectricHeater

Auxiliary Components

Fan

class enex_analysis_engine.enex_engine.Fan[source]

Bases: object

get_efficiency(fan, dV_fan)[source]
get_pressure(fan, dV_fan)[source]
get_power(fan, dV_fan)[source]
show_graph()[source]

Plot flow-rate vs pressure and efficiency curves for all fans.

Raw datapoints are shown as dots; cubic curve fits as lines.

Raises:

ImportError – If dartwork_mpl is not installed.

__init__()

Pump