monee models

Package-level re-exports

Most model classes are re-exported directly from monee.model, so import monee.model as mm gives access to everything listed below. The per-module sections that follow document each submodule under its canonical path (e.g. Var, Bus).

class monee.model.Branch(model, from_node_id, to_node_id, formulation=None, constraints=None, grid=None, name=None, active=True, independent=True)

Bases: Component

equations(grid, from_node_model, to_node_model, **kwargs)

minimize(grid, from_node_model, to_node_model, **kwargs)

property tid

class monee.model.BranchModel(**kwargs)

Bases: GenericModel

Abstract base class for network branches (lines, pipes). Subclasses define branch equations.

abstractmethod equations(grid, from_node_model, to_node_model, **kwargs)

init(grid)

is_cp()

loss_percent()

minimize(grid, from_node_model, to_node_model, **kwargs)

class monee.model.Bus(base_kv)

Bases: NodeModel

calc_signed_power_values(from_branch_models, to_branch_models, child_models)

equations(grid, from_branch_models, to_branch_models, child_models, **kwargs)

Return nodal equations (e.g. flow conservation, voltage balance).

p_mw_equation(child_models)

q_mvar_equation(child_models)

class monee.model.CHP(diameter_m: float, efficiency_power: float, efficiency_heat: float, mass_flow_setpoint_kgs: float, q_mvar_setpoint: float = 0, temperature_ext_k: float = 293, regulation=1)

Bases: MultiGridCompoundModel

create(network: monee.model.network.Network, gas_node: monee.model.core.Node, heat_node: monee.model.core.Node, heat_return_node: monee.model.core.Node, power_node: monee.model.core.Node)

Add sub-components (nodes, branches, children) to network.

set_active(activation_flag)

class monee.model.CHPControlNode(mass_flow_capacity_kgs, efficiency_power, efficiency_heat, hhv, q_mvar=0, regulation=1, **kwargs)

Bases: MultiGridNodeModel, Junction, Bus

Control node for a CHP unit; couples power, heat, and gas domains.

equations(grid, from_branch_models, to_branch_models, childs, **kwargs)

Return nodal equations (e.g. flow conservation, voltage balance).

class monee.model.CHPHG(efficiency_power: float, efficiency_heat: float, mass_flow_setpoint_kgs: float, q_mvar_setpoint: float = 0, regulation=1)

Bases: MultiGridCompoundModel

HeatGenerator-based CHP variant: heat is injected via a SubHG child at heat_node instead of via an HX branch. No heat_return_node / diameter_m required.

create(network: monee.model.network.Network, gas_node: monee.model.core.Node, heat_node: monee.model.core.Node, power_node: monee.model.core.Node)

Add sub-components (nodes, branches, children) to network.

class monee.model.CHPHGControlNode(mass_flow_capacity_kgs, efficiency_power, efficiency_heat, hhv, sub_hg, q_mvar=0, regulation=1, **kwargs)

Bases: MultiGridNodeModel, Junction, Bus

CHP control node using a node-based HeatGenerator (no HX branch).

Like CHPControlNode but only on power+gas; heat goes through a SubHG child attached at the heat node by CHPHG.

equations(grid, from_branch_models, to_branch_models, childs, **kwargs)

Return nodal equations (e.g. flow conservation, voltage balance).

class monee.model.Child(child_id, model, formulation=None, constraints=None, grid=None, name=None, active=True, independent=True)

Bases: Component

equations(grid, node_model, **kwargs)

minimize(grid, node_model, **kwargs)

class monee.model.ChildModel(regulation: float = 1.0, **kwargs)

Bases: GenericModel

Leaf component attached to a single node (loads, generators, ext-grids).

Load convention: positive = consumption, negative = generation. Generator subclasses negate the user-supplied magnitude so the public API takes positive numbers.

regulation in [0.0, 1.0] scales the setpoint; used by multi-energy couplers (P2H, CHP) for partial dispatch.

abstractmethod equations(grid, node_model, **kwargs)

minimize(grid, node_model, **kwargs)

overwrite(node_model, grid)

Pin node variables to fixed setpoints (grid-forming children). Default: no-op.

class monee.model.Component(id, model, formulation=None, constraints=None, grid=None, name=None, active=True, independent=True)

Bases: ABC

property nid

property tid

class monee.model.Compound(compound_id, model: monee.model.core.CompoundModel, connected_to, subcomponents, formulation=None, constraints=None, grid=None, name=None, active=True)

Bases: Component

component_of_type(comp_type)

equations(network, **kwargs)

minimize(network, **kwargs)

class monee.model.CompoundModel(**kwargs)

Bases: GenericModel

Composite component spanning multiple nodes/carriers (e.g. P2H unit).

Subclasses implement create() to add sub-components to the network, and may override equations() for coupling constraints.

abstractmethod create(network)

Add sub-components (nodes, branches, children) to network.

equations(network, **kwargs)

minimize(network, **kwargs)

class monee.model.Const(value)

Bases: object

A fixed (non-optimised) constant that participates in the model attribute protocol.

Used in overwrite() to pin a node variable to a fixed setpoint instead of turning it into a free decision variable.

class monee.model.ConsumeHydrGrid(mass_flow_kgs=0.1, pressure_pu=1, t_k=293, **kwargs)

Bases: NoVarChildModel

Hydraulic demand point: fixed pressure setpoint plus a free mass_flow_kgs Var.

class monee.model.ElectricStorage(e_mwh_initial, e_mwh_max, p_max_mw, p_mw_initial=0.0, efficiency_charge=1.0, efficiency_discharge=1.0, regulation=1, **kwargs)

Bases: ChildModel

Battery/electric storage attached to a power bus.

SoC update: e_mwh(t) = e_mwh(t-1) + dt_h * p_mw(t). With efficiency losses, p_mw = p_charge_mw - p_discharge_mw (both \(\ge\) 0) and SoC uses \(\eta_c \cdot p_{charge} - p_{discharge} / \eta_d\).

equations(grid, node, **kwargs)

inter_temporal_equations(temporal_state: monee.solver.core.InterStepState, component_id, **kwargs)

make_controllable()

Promote p_mw (and loss-split vars if lossy) into solver Vars.

class monee.model.ElectricityIslandingMode(angle_bound: float = 3.15, big_m_conn: int = 200)

Bases: IslandingMode

Electricity islanding: connectivity flow plus \(\theta=0\) at GF buses and energisation-gated angle bounds elsewhere.

add_physical_constraints(network, gf_nodes, regular_nodes, e_vars)

Carrier-specific physics (override in subclasses). Empty by default.

Return type:

list

carrier_grid_type

alias of PowerGrid

prepare(network: monee.model.network.Network)

Add Var placeholders before solver variable injection.

Return type:

None

var_prefix: str = 'el'

class monee.model.ExtHydrGrid(mass_flow_kgs=-1, pressure_pu=1, t_k=356, max_import_kgs=None, max_export_kgs=None, pin_temperature=True, **kwargs)

Bases: NoVarChildModel, GridFormingMixin

External hydraulic slack source. Pins pressure (and optionally temperature), leaves mass_flow_kgs as a free Var. Load convention: negative mass_flow_kgs = injection.

overwrite(node_model, grid)

Pin pressure; pin temperature only if pin_temperature (default True). Set False on return-side slacks so T emerges from upstream heat balance.

class monee.model.ExtPowerGrid(p_mw, q_mvar, vm_pu=1, va_degree=0, max_import_mw=None, max_export_mw=None, **kwargs)

Bases: NoVarChildModel, GridFormingMixin

External slack-bus connection. Pins vm_pu and va_degree, leaves p_mw/q_mvar as free Vars absorbing the island’s imbalance. Load convention: positive p_mw = import.

overwrite(node_model, grid)

Pin the bus voltage magnitude and angle to the configured setpoints.

class monee.model.GasCompressor(compression_ratio=1.5, max_flow_kgs=10.0)

Bases: BranchModel

Ideal compressor - fixed pressure ratio, unidirectional (suction → discharge). Forward flow lives in mass_flow_neg_kgs to match GasPipe’s Weymouth convention.

equations(grid: monee.model.grid.GasGrid, from_node_model, to_node_model, **kwargs)

class monee.model.GasGrid(name: str, molar_mass: float, dynamic_visc_pas: float, higher_heating_value_kwh_per_kg: float, universal_gas_constant: float, t_k: float, t_ref_k: float, pressure_ref_pa: float, nominal_pressure_pu: float, max_mass_flow_kgs: float, pressure_squared_pu_max: float, pressure_squared_pu_min: float, compressibility: float = None, pressure_ambient_pa: float = 0.0)

Bases: Grid

Gas grid domain. Construct via create_gas_grid() for defaults.

compressibility defaults to None and is then derived from the reference pressure (pressure_ref_pa), temperature (t_k) and molar_mass via the Papay real-gas correlation (see monee.model.phys.core.properties), so Z reflects the grid’s declared operating pressure rather than a fixed ideal-gas 1. Pass an explicit value to override (e.g. to force ideal gas with compressibility=1).

compressibility: float = None

dynamic_visc_pas: float

higher_heating_value_kwh_per_kg: float

max_mass_flow_kgs: float

molar_mass: float

nominal_pressure_pu: float

pressure_ambient_pa: float = 0.0

pressure_ref_pa: float

pressure_squared_pu_max: float

pressure_squared_pu_min: float

t_k: float

t_ref_k: float

universal_gas_constant: float

class monee.model.GasIslandingMode(big_m_conn: int = 200)

Bases: IslandingMode

Gas islanding: connectivity flow plus \(pressure_{pu} \le 2 \cdot e\) on regular junctions (GF junctions already pin pressure via overwrite()).

add_physical_constraints(network, gf_nodes, regular_nodes, e_vars)

Carrier-specific physics (override in subclasses). Empty by default.

Return type:

list

carrier_grid_type

alias of GasGrid

prepare(network: monee.model.network.Network)

Add Var placeholders before solver variable injection.

Return type:

None

var_prefix: str = 'gas'

class monee.model.GasLinepack(overrides: dict[int, dict] | None = None)

Bases: NetworkAspect

Linepack extension. Injects linepack_kg and net_pack_kgs on every GasPipe; auto-sizes initial/max from grid params. Per-pipe overrides via the overrides {branch_id: {"linepack_kg_initial": ..., "linepack_kg_max": ...}}.

activate_timeseries(network, ignored_nodes: set, step_state=None)

Mark timeseries so equations() stops pinning net_pack_kgs=0; warm-start linepack_kg from step_state when available.

Return type:

None

equations(network, ignored_nodes: set)

\(\text{linepack\_kg} = V_{pipe} \cdot \text{gas\_density\_kg\_per\_m3}\); pin net_pack_kgs = 0 in steady-state mode.

Return type:

list

inter_temporal_equations(network, ignored_nodes: set, temporal_state)

\(\text{net\_pack\_kgs}(t) \cdot \Delta t = \text{linepack\_kg}(t) - \text{linepack\_kg}(t-1)\).

Return type:

list

prepare(network)

Add Var placeholders before variable injection (no-op by default).

Return type:

None

class monee.model.GasPipe(diameter_m, length_m, temperature_ext_k=296.15, roughness_m=0.0001, on_off=1, friction=None)

Bases: BranchModel

equations(grid: monee.model.grid.GasGrid, from_node_model, to_node_model, **kwargs)

class monee.model.GasStorage(m_stored_kg_initial, m_stored_kg_max, flow_max_kgs, mass_flow_initial_kgs=0.0, efficiency_charge=1.0, efficiency_discharge=1.0, regulation=1, **kwargs)

Bases: ChildModel

Pressurised gas storage at a gas junction.

SoC update: m_stored_kg(t) = m_stored_kg(t-1) + dt_s * mass_flow_kgs(t). Lossy: mass_flow_kgs = flow_charge_kgs - flow_discharge_kgs with η_c * charge - discharge / η_d in the SoC update.

equations(grid, node, **kwargs)

inter_temporal_equations(temporal_state: monee.solver.core.InterStepState, component_id, **kwargs)

make_controllable()

Promote mass_flow_kgs (and loss-split vars if lossy) into solver Vars.

class monee.model.GasToHeat(heat_energy_mw, diameter_m, temperature_ext_k, efficiency, regulation=1)

Bases: MultiGridCompoundModel

create(network: monee.model.network.Network, gas_node: monee.model.core.Node, heat_node: monee.model.core.Node, heat_return_node: monee.model.core.Node)

Add sub-components (nodes, branches, children) to network.

set_active(activation_flag)

class monee.model.GasToHeatControlNode(gas_mass_flow_kgs, efficiency_heat, hhv, regulation=1, **kwargs)

Bases: MultiGridNodeModel, Junction

equations(grid, from_branch_models, to_branch_models, childs, **kwargs)

Return nodal equations (e.g. flow conservation, voltage balance).

class monee.model.GasToHeatHG(heat_energy_mw, efficiency, regulation=1)

Bases: MultiGridBranchModel

Two-endpoint Gas→Heat coupling (gas withdrawal at from-end, q_mw_heat injection at to-end). Junction heat balance picks up q_mw_heat directly.

equations(grids, from_node_model, to_node_model, **kwargs)

init(grids)

loss_percent()

class monee.model.GasToPower(efficiency, p_mw_setpoint, q_mvar_setpoint=0, regulation=1)

Bases: MultiGridBranchModel

equations(grids, from_node_model, to_node_model, **kwargs)

loss_percent()

class monee.model.GenericModel(**kwargs)

Bases: ABC

Base class for all component models (nodes, branches, children, compounds).

Public attributes (no leading _) form the solver-visible state. Use Var for decision variables, Const for pinned setpoints, plain scalars for parameters.

is_cp()

property values

property vars

class monee.model.GenericPowerBranch(tap, shift, br_r_pu, br_x_pu, g_fr_pu, b_fr_pu, g_to_pu, b_to_pu, max_i_ka=3.19, backup=False, on_off=1, **kwargs)

Bases: BranchModel

equations(grid: monee.model.grid.PowerGrid, from_node_model, to_node_model, **kwargs)

property loading_pu

loss_percent()

class monee.model.GenericTransferBranch(flow_init_kgs: float = 1.0, p_init_mw: float = 1.0, **kwargs)

Bases: MultiGridBranchModel

equations(grids, from_node_model, to_node_model, **kwargs)

init(grids)

is_cp()

class monee.model.Grid(name: str)

Bases: object

Marker/base for a resource domain (electrical, gas, heat).

name: str

class monee.model.GridFormingGenerator(p_mw_max: float, q_mvar_max: float, vm_pu: float = 1.0, **kwargs)

Bases: NoVarChildModel, GridFormingMixin

Grid-forming generator: variable p_mw/q_mvar (absorbs island imbalance) with a pinned vm_pu. Angle is pinned by ElectricityIslandingMode.

overwrite(node_model, grid)

Pin node variables to fixed setpoints (grid-forming children). Default: no-op.

Return type:

None

class monee.model.GridFormingMixin

Bases: object

Marker: this child can serve as the slack/reference for an islanded sub-network.

Carriers must implement overwrite() to pin their reference variable. Islanding keeps components containing a GridFormingMixin child in the solve.

class monee.model.GridFormingSource(pressure_pu: float = 1.0, t_k: float = 356.0, mass_flow_max_kgs: float = 1000000.0)

Bases: ChildModel, GridFormingMixin

Grid-forming source: pins pressure (and t_pu/t_k) on the junction, leaves mass_flow_kgs as a Var to absorb island imbalance.

equations(grid, node_model, **kwargs)

overwrite(node_model, grid)

Pin node variables to fixed setpoints (grid-forming children). Default: no-op.

Return type:

None

class monee.model.HeatExchanger(q_mw, mass_flow_design_kgs=None, T_delta_design_K=30, regulation=1)

Bases: BranchModel

equations(grid: monee.model.grid.WaterGrid, from_node_model, to_node_model, **kwargs)

class monee.model.HeatExchangerGenerator(q_mw, mass_flow_design_kgs=None, regulation=1)

Bases: HeatExchanger

class monee.model.HeatExchangerLoad(q_mw, mass_flow_design_kgs=None, regulation=1)

Bases: HeatExchanger

class monee.model.HeatGenerator(q_mw, **kwargs)

Bases: NoVarChildModel

Node-based heat injection (H_G,i). Takes positive magnitude; sign is internal.

class monee.model.HeatLoad(q_mw, **kwargs)

Bases: NoVarChildModel

Node-based heat withdrawal (H_L,i). Positive q_mw = consumption.

class monee.model.Intermediate(value=0)

Bases: object

A computed (derived) quantity, not a decision variable.

The solver evaluates the matching IntermediateEq and writes the result back to .value after each solve.

class monee.model.IntermediateEq(attr, eq)

Bases: object

Declares how to compute an Intermediate attribute from other variables.

Return an IntermediateEq from a model’s equations() to register a derived quantity; the solver evaluates eq and stores the result on the attribute named by attr.

class monee.model.IslandingMode

Bases: NetworkAspect, ABC

Per-carrier islanding base. Subclasses set carrier_grid_type and var_prefix, and may override add_physical_constraints() to add e.g. angle pinning / pressure bounds.

add_physical_constraints(*_)

Carrier-specific physics (override in subclasses). Empty by default.

Return type:

list

carrier_grid_type: type

equations(network: monee.model.network.Network, ignored_nodes: set)

Return solver-agnostic relational expressions (empty by default).

Return type:

list

is_grid_forming(child)

Return type:

bool

abstractmethod prepare(network: monee.model.network.Network)

Add Var placeholders before solver variable injection.

Return type:

None

var_prefix: str

class monee.model.Junction

Bases: NodeModel

calc_signed_heat_flow(from_branch_models, to_branch_models, child_models, grid)

calc_signed_mass_flow(from_branch_models, to_branch_models, child_models)

equations(grid, from_branch_models, to_branch_models, child_models, **kwargs)

Return nodal equations (e.g. flow conservation, voltage balance).

class monee.model.LumpedThermalCapacitance(default_t_init: float | None = None, t_init_overrides: dict | None = None, first_step_steady_state: bool = False)

Bases: NetworkAspect

LTC extension. Nodes with a GridFormingMixin child are excluded.

First-step anchor precedence (anchored mode, the default - required for NLP solvers like GEKKO/IPOPT): t_init_overrides[node_id] → default_t_init → the junction’s own t_pu Var initialiser. Pass default_t_init near the operating mean to skip the warm-up transient.

first_step_steady_state=True drops the first-step inertia term (emits net_heat == 0); MIP backends only.

activate_timeseries(network, ignored_nodes: set, step_state=None)

Mark LTC junctions _ltc_active so the default degenerate heat balance is skipped (avoids a near-singular Jacobian); warm-start t_pu.

Return type:

None

equations(network, ignored_nodes: set)

Return solver-agnostic relational expressions (empty by default).

Return type:

list

inter_temporal_equations(network, ignored_nodes: set, temporal_state)

\(\rho \cdot V \cdot (T_{pu}(t) - T_{pu}(t-1))/\Delta t = \text{net\_convective\_heat\_in}\) per LTC junction. T_prev falls back to the first-step anchor (see class docstring) when temporal_state.get returns None.

Return type:

list

prepare(network)

Add Var placeholders before variable injection (no-op by default).

Return type:

None

class monee.model.MultiGridBranchModel(**kwargs)

Bases: BranchModel

Branch that couples multiple grid domains (e.g. CHP, P2H). Always a control point.

abstractmethod equations(grids, from_node_model, to_node_model, **kwargs)

init(grids)

is_cp()

class monee.model.MultiGridCompoundModel(**kwargs)

Bases: CompoundModel

is_cp()

class monee.model.Network(active_grid=None, el_model=None, water_model=None, gas_model=None)

Bases: object

activate(component)

activate_by_id(cls, id)

activate_grid(grid)

add_extension(ext: monee.model.extension.core.NetworkAspect)

Register a NetworkAspect extension on this network.

Return type:

None

all_components()

all_models()

all_models_with_grid()

apply_formulation(network_formulation)

Record network_formulation as the network-level default.

Accepts the same spec as the solver’s formulation argument (resolve_formulation()): a registry key string ("smooth_nlp"), a NetworkFormulation, or a sequence of either (merged left to right).

Side-effect free: only the network’s formulation map is updated - components and their models are untouched. The choice materialises when a solver runs attach_formulations on its solve-time copy. A formulation argument passed to the solver overrides this choice; per-component formulations passed to the builder methods override both. Repeated calls merge: later registrations win per type key.

as_dataframe_dict()

as_dataframe_dict_str()

as_result_dataframe_dict()

as_result_dataframe_dict_str()

branch(model, from_node_id, to_node_id, formulation=None, constraints=None, grid=None, name=None, auto_node_creator=None, auto_grid_key=None, **kwargs)

branch_by_id(branch_id)

property branches: list[Branch]

branches_by_ids(branch_ids)

Return type:

list[monee.model.core.Branch]

branches_by_type(cls)

branches_connected_to(node_id)

Return type:

list[monee.model.core.Branch]

child(model, attach_to_node_id=None, formulation=None, constraints=None, overwrite_id=None, name=None, auto_node_creator=None, auto_grid_key=None)

child_by_id(child_id)

child_to(model, node_id, formulation=None, constraints=None, overwrite_id=None, name=None, auto_node_creator=None, auto_grid_key=None)

property childs: list[Child]

childs_by_ids(child_ids)

Return type:

list[monee.model.core.Child]

childs_by_type(cls)

clear_childs()

components_connected_to(node_id)

Return type:

list[monee.model.core.Component]

compound(model: monee.model.core.CompoundModel, formulation=None, constraints=None, overwrite_id=None, **connected_node_ids)

compound_by_id(compound_id)

compound_of(subcomponent_component_id)

Return type:

list[monee.model.core.Component]

compound_of_node(node_id)

property compounds: list[Compound]

compounds_by_type(cls)

compounds_connected_to(node_id)

Return type:

list[monee.model.core.Component]

constraint(constraint_equation)

property constraints

copy()

property cps: list[GenericModel]

deactivate(component)

deactivate_by_id(cls, id)

property extensions: list[NetworkAspect]

Solver-agnostic network-level extensions.

first_node()

get_branch_between(node_id_one, node_id_two, bid=0)

get_childs_by_type(branch, cls)

Return type:

list[monee.model.core.Child]

property graph

property grids

has_any_child_of_type(branch, cls)

Return type:

bool

has_branch(branch_id)

has_branch_between(node_id_one, node_id_two)

has_child(child_id)

has_node(node_id)

is_blacklisted(obj)

lookup_formulation(model, grid)

The network-level formulation for model (and grid) accumulated from apply_formulation calls, or None. Last matching registration wins, mirroring NetworkFormulation.lookup().

Return type:

monee.model.formulation.core.Formulation | None

move_branch(branch_id, new_from_id, new_to_id)

node(model, grid=None, formulation=None, child_ids=None, constraints=None, overwrite_id=None, name=None, position=None)

node_by_id(node_id)

Return type:

monee.model.core.Node

node_by_id_or_create(node_id, auto_node_creator, auto_grid_key)

property nodes: list[Node]

nodes_by_type(cls)

objective(objective_function)

property objectives

remove_branch(branch_id)

remove_branch_between(node_one, node_two, key=0)

remove_child(child_id)

remove_compound(compound_id)

remove_node(node_id)

set_default_grid(key, grid)

statistics()

class monee.model.NetworkAspect

Bases: object

Solver-agnostic network-level extension.

Analogous to BranchFormulation / NodeFormulation but spanning the entire network. Register with network.add_extension(aspect).

Phase 1 - prepare(network): called before variable injection; add Var placeholders to model objects so the injection loop picks them up.

Phase 2 - equations(network, ignored_nodes) → list: called after variable injection; return relational expressions (==, <=, >=) built from injected model attributes. The solver registers them with m.Equations(eqs) / pm.cons.add without inspecting their content - exactly like branch/node equations.

activate_timeseries(network, ignored_nodes: set, step_state=None)

Called after prepare() and variable injection, before node equations are assembled, when a timeseries or multi-period solve begins.

Override to set flags on model objects that modify equation assembly for coupled solves - for example, suppressing a degenerate algebraic equation whose role is taken over by an inter-step constraint.

step_state is provided so extensions can warm-start solver variable initializations from the previous step’s solved values. No-op by default.

Return type:

None

equations(network, ignored_nodes: set)

Return solver-agnostic relational expressions (empty by default).

Return type:

list

inter_period_equations(network, ignored_nodes: set, period_state)

Return expressions coupling current variables to other period values (multi-period only). Empty by default.

Return type:

list

inter_step_equations(network, ignored_nodes: set, step_state)

Return expressions coupling current variables to previous-step values (timeseries only). Empty by default.

Return type:

list

inter_temporal_equations(network, ignored_nodes: set, temporal_state)

Return expressions coupling current variables to previous values (both timeseries and multi-period). Empty by default.

Return type:

list

prepare(network)

Add Var placeholders before variable injection (no-op by default).

Return type:

None

class monee.model.NetworkIslandingConfig(electricity: monee.model.extension.islanding.core.IslandingMode | None = None, gas: monee.model.extension.islanding.core.IslandingMode | None = None, water: monee.model.extension.islanding.core.IslandingMode | None = None)

Bases: NetworkAspect

Bundle per-carrier IslandingMode instances; register via network.add_extension or enable_islanding().

equations(network: monee.model.network.Network, ignored_nodes: set)

Return solver-agnostic relational expressions (empty by default).

Return type:

list

modes()

Return type:

list[monee.model.extension.islanding.core.IslandingMode]

prepare(network: monee.model.network.Network)

Add Var placeholders before variable injection (no-op by default).

Return type:

None

class monee.model.Node(node_id, model, child_ids=None, formulation=None, constraints=None, grid=None, name=None, position=None, active=True, independent=True)

Bases: Component

Network node tracking attached child components and incoming/outgoing branches.

add_from_branch_id(branch_id)

add_to_branch_id(branch_id)

equations(grid, in_branch_models, out_branch_models, childs, **kwargs)

minimize(grid, in_branch_models, out_branch_models, childs, **kwargs)

remove_branch(branch_id)

Remove branch_id and its reversed counterpart from both branch lists.

class monee.model.NodeModel(**kwargs)

Bases: GenericModel

Abstract base class for node models (buses, junctions). Subclasses define nodal equations.

abstractmethod equations(grid, in_branch_models, out_branch_models, childs, **kwargs)

Return nodal equations (e.g. flow conservation, voltage balance).

minimize(grid, in_branch_models, out_branch_models, childs, **kwargs)

Optional objective contribution (e.g. slack penalties). Default: none.

class monee.model.PassiveHeatExchanger(q_mw, diameter_m, roughness_m=0.0001, length_m=2.5, temperature_ext_k=293, regulation=1, friction=None, loss_coefficient=None)

Bases: BranchModel

Passive heat exchanger injecting/extracting fixed q_mw into a free-flowing water branch. Mass flow is determined by surrounding hydraulics; temperature change follows from q_mw and actual mass flow.

Sign: positive q_mw = load, negative = generator.

Hydraulics: by default the pressure drop is Darcy-Weisbach friction over length_m. Passing loss_coefficient (zeta) instead switches to the pandapipes heat_exchanger model - a zero-length minor loss \(\Delta p = \zeta \cdot \tfrac{\rho}{2} v^2\) (length_m / friction are then ignored; loss_coefficient=0 is a lossless heat injector).

equations(grid: monee.model.grid.WaterGrid, from_node_model, to_node_model, **kwargs)

class monee.model.PassiveHeatExchangerGenerator(q_mw, diameter_m, temperature_ext_k=293, loss_coefficient=None)

Bases: PassiveHeatExchanger

Passive heat exchanger that injects heat (generator, q_mw < 0).

class monee.model.PassiveHeatExchangerLoad(q_mw, diameter_m, temperature_ext_k=293, loss_coefficient=None)

Bases: PassiveHeatExchanger

Passive heat exchanger that consumes heat (load, q_mw > 0).

class monee.model.PostProcess(fn, value=0)

Bases: object

A report-only quantity computed after the solve, outside the solver, from the solved model values via fn(values), where values is a namespace of the model’s solved fields (read as values.vm_pu).

Unlike Intermediate, it is never injected as a solver variable nor referenced by any equation - it carries no degrees of freedom and cannot affect convergence or squareness. The clean home for derived reports (e.g. vm_pu_squared = vm_pu^2): physics stays in the solver, reporting outside.

class monee.model.PowerBranch(tap, shift, backup=False, on_off=1, **kwargs)

Bases: GenericPowerBranch, ABC

abstractmethod calc_r_x(grid, from_node_model, to_node_model)

equations(grid: monee.model.grid.PowerGrid, from_node_model, to_node_model, **kwargs)

class monee.model.PowerGenerator(p_mw, q_mvar, **kwargs)

Bases: NoVarChildModel

Fixed-setpoint active/reactive generator. Constructor takes positive magnitudes; sign is internal.

class monee.model.PowerGrid(name: str, sn_mva: float = 1, vm_pu_max: float = 1.5, vm_pu_min: float = 0.5)

Bases: Grid

Electrical grid domain.

sn_mva: float = 1

vm_pu_max: float = 1.5

vm_pu_min: float = 0.5

class monee.model.PowerLine(length_m, r_ohm_per_m, x_ohm_per_m, parallel, backup=False, on_off=1, **kwargs)

Bases: PowerBranch

calc_r_x(grid: monee.model.grid.PowerGrid, from_node_model, to_node_model)

class monee.model.PowerLoad(p_mw, q_mvar, **kwargs)

Bases: NoVarChildModel

Fixed-setpoint power load. Load convention: positive = consumption.

class monee.model.PowerToGas(efficiency, mass_flow_setpoint_kgs, consume_q_mvar_setpoint=0, regulation=1)

Bases: MultiGridBranchModel

equations(grids, from_node_model, to_node_model, **kwargs)

loss_percent()

class monee.model.PowerToHeat(heat_energy_mw, diameter_m, temperature_ext_k, efficiency, q_mvar_setpoint=0, regulation=1)

Bases: MultiGridCompoundModel

create(network: monee.model.network.Network, power_node: monee.model.core.Node, heat_node: monee.model.core.Node, heat_return_node: monee.model.core.Node)

Add sub-components (nodes, branches, children) to network.

set_active(activation_flag)

class monee.model.PowerToHeatControlNode(load_p_mw, load_q_mvar, efficiency, regulation=1, **kwargs)

Bases: MultiGridNodeModel, Junction, Bus

equations(grid, from_branch_models, to_branch_models, childs, **kwargs)

Return nodal equations (e.g. flow conservation, voltage balance).

class monee.model.PowerToHeatHG(heat_energy_mw, efficiency, q_mvar_setpoint=0, regulation=1)

Bases: MultiGridBranchModel

Two-endpoint Power→Heat coupling (p_from_mw at from-end, q_mw_heat at to-end). Junction heat balance picks up q_mw_heat directly.

equations(grids, from_node_model, to_node_model, **kwargs)

loss_percent()

class monee.model.Sink(mass_flow_kgs, **kwargs)

Bases: NoVarChildModel

Fixed-setpoint mass-flow sink. Positive = consumption (load convention).

class monee.model.Source(mass_flow_kgs, t_k=None, **kwargs)

Bases: NoVarChildModel

Fixed-setpoint mass-flow source. Constructor takes positive magnitude; sign is internal.

t_k (optional) is the temperature of the injected stream. Without it the injection is credited at the junction’s own (mixed) temperature.

class monee.model.SubHG(**kwargs)

Bases: NoVarChildModel

Subordinate node-based heat generator used inside CHPHG.

Like HeatGenerator but with q_mw_heat as a Var constrained by the parent compound’s control-node equations. Two-endpoint HG variants (GasToHeatHG / PowerToHeatHG) don’t use this - they carry q_mw_heat directly on the branch.

class monee.model.ThermalStorage(m_stored_kg_initial, m_stored_kg_max, flow_max_kgs, mass_flow_initial_kgs=0.0, loss_factor_per_h=0.0, regulation=1, **kwargs)

Bases: ChildModel

Thermal storage (e.g. hot-water tank) at a water junction.

SoC update: m_stored_kg(t) = m_stored_kg(t-1) - loss*dt_h*m_stored_kg(t-1) + dt_s*mass_flow_kgs(t).

equations(grid, node, **kwargs)

inter_temporal_equations(temporal_state: monee.solver.core.InterStepState, component_id, **kwargs)

make_controllable()

Promote mass_flow_kgs into a solver Var.

class monee.model.Trafo(vk_percent=12.2, vkr_percent=0.25, sn_trafo_mva=160, shift=0)

Bases: PowerBranch

calc_r_x(grid: monee.model.grid.PowerGrid, lv_model, hv_model)

equations(grid: monee.model.grid.PowerGrid, from_node_model, to_node_model, **kwargs)

class monee.model.Var(value, max=None, min=None, integer=False, name=None)

Bases: object

A decision variable (or mutable parameter) in the optimisation model.

Sign convention for child components: positive = consumption (load), negative = generation. PowerGenerator(p_mw=5) stores p_mw=-5.

Comparison operators compare against the bound, not the value, and return False if the relevant bound is None.

class monee.model.WaterGrid(name: str, t_ref_k: float = 356, pressure_ref_pa: float = 1000000, max_mass_flow_kgs: float = 200, v_max_mps: float = 5.0, fluid_density_kg_per_m3: float = None, dynamic_visc_pas: float = None)

Bases: Grid

Water/heat grid domain.

fluid_density_kg_per_m3 and dynamic_visc_pas default to None and are then derived from t_ref_k via the standard water correlations (see monee.model.phys.core.properties), so the transport properties always match the grid’s declared operating temperature. Pass explicit values to override (e.g. to model a non-water fluid or a different reference).

dynamic_visc_pas: float = None

fluid_density_kg_per_m3: float = None

max_mass_flow_kgs: float = 200

pressure_ref_pa: float = 1000000

t_ref_k: float = 356

v_max_mps: float = 5.0

class monee.model.WaterIslandingMode(big_m_conn: int = 200)

Bases: IslandingMode

Water/heat islanding. Use GridFormingSource from the gas module.

add_physical_constraints(network, gf_nodes, regular_nodes, e_vars)

Carrier-specific physics (override in subclasses). Empty by default.

Return type:

list

carrier_grid_type

alias of WaterGrid

prepare(network: monee.model.network.Network)

Add Var placeholders before solver variable injection.

Return type:

None

var_prefix: str = 'water'

class monee.model.WaterPipe(diameter_m, length_m, temperature_ext_k=283.15, roughness_m=4.5e-05, lambda_insulation_w_per_m_k=0.025, insulation_thickness_m=0.12, on_off=1, friction=None, unidirectional=False)

Bases: BranchModel

equations(grid: monee.model.grid.WaterGrid, from_node_model, to_node_model, **kwargs)

loss_percent()

monee.model.calc_coordinates(network: monee.model.network.Network, component: monee.model.core.Component)

monee.model.create_gas_grid(name, type='lgas', t_ref_k=None, pressure_ref_pa=None)

Return a GasGrid populated from GAS_GRID_ATTRS[type].

t_ref_k / pressure_ref_pa override the reference condition so the derived compressibility tracks the grid’s actual operating pressure. Pass them here rather than mutating the grid afterwards, so __post_init__ derives Z from the final values (a post-construction assignment leaves the already-derived Z stale).

monee.model.create_power_grid(name, sn_mva=1)

monee.model.create_water_grid(name, t_ref_k=356, pressure_ref_pa=1000000)

Return a WaterGrid whose density/viscosity are derived from t_ref_k (see WaterGrid). Pass t_ref_k here rather than mutating the grid afterwards, so the derived properties match the final reference temperature.

monee.model.lower(var_or_const)

Return the lower bound of a Var (or its value if unbounded); pass through otherwise.

monee.model.make_heat_convex_milp_formulation(num_partitions: int = 1, include_heat_exchangers: bool = True)

McCormick district-heating relaxation: LP for num_partitions == 1, piecewise MILP above. Raise the partition count only when mccormick_dhs_gap_bound_k() shows the LP corner is non-physical on the network at hand.

include_heat_exchangers also maps the active/passive heat exchangers to their convex variants so the sector has no non-convex fallback; disable it to reproduce the legacy pipes-only McCormick apply.

Return type:

monee.model.formulation.core.NetworkFormulation

monee.model.model(cls)

Register a model class in the global component_list registry.

monee.model.to_spanning_tree(network: monee.model.network.Network)

monee.model.tracked

alias of Var

monee.model.transform_network(network: monee.model.network.Network, graph_transform)

monee.model.upper(var_or_const)

Return the upper bound of a Var (or its value if unbounded); pass through otherwise.

monee.model.value(var_or_const)

Extract .value from a Var/Const/Intermediate/PostProcess; pass through plain scalars.

Core protocol

Attribute types (Var, Const, Intermediate, PostProcess), abstract model bases and the component containers.

class monee.model.core.Branch(model, from_node_id, to_node_id, formulation=None, constraints=None, grid=None, name=None, active=True, independent=True)

Bases: Component

equations(grid, from_node_model, to_node_model, **kwargs)

minimize(grid, from_node_model, to_node_model, **kwargs)

property tid

class monee.model.core.BranchModel(**kwargs)

Bases: GenericModel

Abstract base class for network branches (lines, pipes). Subclasses define branch equations.

abstractmethod equations(grid, from_node_model, to_node_model, **kwargs)

init(grid)

is_cp()

loss_percent()

minimize(grid, from_node_model, to_node_model, **kwargs)

class monee.model.core.Child(child_id, model, formulation=None, constraints=None, grid=None, name=None, active=True, independent=True)

Bases: Component

equations(grid, node_model, **kwargs)

minimize(grid, node_model, **kwargs)

class monee.model.core.ChildModel(regulation: float = 1.0, **kwargs)

Bases: GenericModel

Leaf component attached to a single node (loads, generators, ext-grids).

Load convention: positive = consumption, negative = generation. Generator subclasses negate the user-supplied magnitude so the public API takes positive numbers.

regulation in [0.0, 1.0] scales the setpoint; used by multi-energy couplers (P2H, CHP) for partial dispatch.

abstractmethod equations(grid, node_model, **kwargs)

minimize(grid, node_model, **kwargs)

overwrite(node_model, grid)

Pin node variables to fixed setpoints (grid-forming children). Default: no-op.

class monee.model.core.Component(id, model, formulation=None, constraints=None, grid=None, name=None, active=True, independent=True)

Bases: ABC

property nid

property tid

class monee.model.core.Compound(compound_id, model: monee.model.core.CompoundModel, connected_to, subcomponents, formulation=None, constraints=None, grid=None, name=None, active=True)

Bases: Component

component_of_type(comp_type)

equations(network, **kwargs)

minimize(network, **kwargs)

class monee.model.core.CompoundModel(**kwargs)

Bases: GenericModel

Composite component spanning multiple nodes/carriers (e.g. P2H unit).

Subclasses implement create() to add sub-components to the network, and may override equations() for coupling constraints.

abstractmethod create(network)

Add sub-components (nodes, branches, children) to network.

equations(network, **kwargs)

minimize(network, **kwargs)

class monee.model.core.Const(value)

Bases: object

A fixed (non-optimised) constant that participates in the model attribute protocol.

Used in overwrite() to pin a node variable to a fixed setpoint instead of turning it into a free decision variable.

class monee.model.core.GenericModel(**kwargs)

Bases: ABC

Base class for all component models (nodes, branches, children, compounds).

Public attributes (no leading _) form the solver-visible state. Use Var for decision variables, Const for pinned setpoints, plain scalars for parameters.

is_cp()

property values

property vars

class monee.model.core.Intermediate(value=0)

Bases: object

A computed (derived) quantity, not a decision variable.

The solver evaluates the matching IntermediateEq and writes the result back to .value after each solve.

class monee.model.core.IntermediateEq(attr, eq)

Bases: object

Declares how to compute an Intermediate attribute from other variables.

Return an IntermediateEq from a model’s equations() to register a derived quantity; the solver evaluates eq and stores the result on the attribute named by attr.

class monee.model.core.MultiGridBranchModel(**kwargs)

Bases: BranchModel

Branch that couples multiple grid domains (e.g. CHP, P2H). Always a control point.

abstractmethod equations(grids, from_node_model, to_node_model, **kwargs)

init(grids)

is_cp()

class monee.model.core.MultiGridCompoundModel(**kwargs)

Bases: CompoundModel

is_cp()

class monee.model.core.MultiGridNodeModel(**kwargs)

Bases: NodeModel

Node that participates in multiple grid domains. Always a control point.

is_cp()

class monee.model.core.Node(node_id, model, child_ids=None, formulation=None, constraints=None, grid=None, name=None, position=None, active=True, independent=True)

Bases: Component

Network node tracking attached child components and incoming/outgoing branches.

add_from_branch_id(branch_id)

add_to_branch_id(branch_id)

equations(grid, in_branch_models, out_branch_models, childs, **kwargs)

minimize(grid, in_branch_models, out_branch_models, childs, **kwargs)

remove_branch(branch_id)

Remove branch_id and its reversed counterpart from both branch lists.

class monee.model.core.NodeModel(**kwargs)

Bases: GenericModel

Abstract base class for node models (buses, junctions). Subclasses define nodal equations.

abstractmethod equations(grid, in_branch_models, out_branch_models, childs, **kwargs)

Return nodal equations (e.g. flow conservation, voltage balance).

minimize(grid, in_branch_models, out_branch_models, childs, **kwargs)

Optional objective contribution (e.g. slack penalties). Default: none.

class monee.model.core.PostProcess(fn, value=0)

Bases: object

A report-only quantity computed after the solve, outside the solver, from the solved model values via fn(values), where values is a namespace of the model’s solved fields (read as values.vm_pu).

Unlike Intermediate, it is never injected as a solver variable nor referenced by any equation - it carries no degrees of freedom and cannot affect convergence or squareness. The clean home for derived reports (e.g. vm_pu_squared = vm_pu^2): physics stays in the solver, reporting outside.

class monee.model.core.Var(value, max=None, min=None, integer=False, name=None)

Bases: object

A decision variable (or mutable parameter) in the optimisation model.

Sign convention for child components: positive = consumption (load), negative = generation. PowerGenerator(p_mw=5) stores p_mw=-5.

Comparison operators compare against the bound, not the value, and return False if the relevant bound is None.

monee.model.core.lower(var_or_const)

Return the lower bound of a Var (or its value if unbounded); pass through otherwise.

monee.model.core.model(cls)

Register a model class in the global component_list registry.

monee.model.core.set_initial_value(var, value)

Seed a variable’s initial guess / warm start, backend-agnostically.

A model attribute may be a monee Var or, once a backend has run inject_vars (e.g. in activate_timeseries), the backend’s own variable object. monee Var / GEKKO GKVariable / Pyomo Var all expose a settable value; gurobipy Var instead carries its warm start in Start (and has no value, so var.value = ... raises). Duck-type on the available attribute so callers in the model layer never need to know which solver backend is active.

A backend symbol that seeds its warm start elsewhere (e.g. the CasADi CasSym, which captures x0 at inject_vars time and exposes neither attribute) is deliberately a silent no-op. A plain scalar/string target is never a valid warm-start sink, so reject it loudly to catch the wrong-target programming error the no-op would otherwise mask.

Return type:

None

monee.model.core.tracked

alias of Var

monee.model.core.upper(var_or_const)

Return the upper bound of a Var (or its value if unbounded); pass through otherwise.

monee.model.core.value(var_or_const)

Extract .value from a Var/Const/Intermediate/PostProcess; pass through plain scalars.

Network container

class monee.model.network.Network(active_grid=None, el_model=None, water_model=None, gas_model=None)

Bases: object

activate(component)

activate_by_id(cls, id)

activate_grid(grid)

add_extension(ext: monee.model.extension.core.NetworkAspect)

Register a NetworkAspect extension on this network.

Return type:

None

all_components()

all_models()

all_models_with_grid()

apply_formulation(network_formulation)

Record network_formulation as the network-level default.

Accepts the same spec as the solver’s formulation argument (resolve_formulation()): a registry key string ("smooth_nlp"), a NetworkFormulation, or a sequence of either (merged left to right).

Side-effect free: only the network’s formulation map is updated - components and their models are untouched. The choice materialises when a solver runs attach_formulations on its solve-time copy. A formulation argument passed to the solver overrides this choice; per-component formulations passed to the builder methods override both. Repeated calls merge: later registrations win per type key.

as_dataframe_dict()

as_dataframe_dict_str()

as_result_dataframe_dict()

as_result_dataframe_dict_str()

branch(model, from_node_id, to_node_id, formulation=None, constraints=None, grid=None, name=None, auto_node_creator=None, auto_grid_key=None, **kwargs)

branch_by_id(branch_id)

property branches: list[Branch]

branches_by_ids(branch_ids)

Return type:

list[monee.model.core.Branch]

branches_by_type(cls)

branches_connected_to(node_id)

Return type:

list[monee.model.core.Branch]

child(model, attach_to_node_id=None, formulation=None, constraints=None, overwrite_id=None, name=None, auto_node_creator=None, auto_grid_key=None)

child_by_id(child_id)

child_to(model, node_id, formulation=None, constraints=None, overwrite_id=None, name=None, auto_node_creator=None, auto_grid_key=None)

property childs: list[Child]

childs_by_ids(child_ids)

Return type:

list[monee.model.core.Child]

childs_by_type(cls)

clear_childs()

components_connected_to(node_id)

Return type:

list[monee.model.core.Component]

compound(model: monee.model.core.CompoundModel, formulation=None, constraints=None, overwrite_id=None, **connected_node_ids)

compound_by_id(compound_id)

compound_of(subcomponent_component_id)

Return type:

list[monee.model.core.Component]

compound_of_node(node_id)

property compounds: list[Compound]

compounds_by_type(cls)

compounds_connected_to(node_id)

Return type:

list[monee.model.core.Component]

constraint(constraint_equation)

property constraints

copy()

property cps: list[GenericModel]

deactivate(component)

deactivate_by_id(cls, id)

property extensions: list[NetworkAspect]

Solver-agnostic network-level extensions.

first_node()

get_branch_between(node_id_one, node_id_two, bid=0)

get_childs_by_type(branch, cls)

Return type:

list[monee.model.core.Child]

property graph

property grids

has_any_child_of_type(branch, cls)

Return type:

bool

has_branch(branch_id)

has_branch_between(node_id_one, node_id_two)

has_child(child_id)

has_node(node_id)

is_blacklisted(obj)

lookup_formulation(model, grid)

The network-level formulation for model (and grid) accumulated from apply_formulation calls, or None. Last matching registration wins, mirroring NetworkFormulation.lookup().

Return type:

monee.model.formulation.core.Formulation | None

move_branch(branch_id, new_from_id, new_to_id)

node(model, grid=None, formulation=None, child_ids=None, constraints=None, overwrite_id=None, name=None, position=None)

node_by_id(node_id)

Return type:

monee.model.core.Node

node_by_id_or_create(node_id, auto_node_creator, auto_grid_key)

property nodes: list[Node]

nodes_by_type(cls)

objective(objective_function)

property objectives

remove_branch(branch_id)

remove_branch_between(node_one, node_two, key=0)

remove_child(child_id)

remove_compound(compound_id)

remove_node(node_id)

set_default_grid(key, grid)

statistics()

monee.model.network.calc_coordinates(network: monee.model.network.Network, component: monee.model.core.Component)

monee.model.network.to_spanning_tree(network: monee.model.network.Network)

monee.model.network.transform_network(network: monee.model.network.Network, graph_transform)

Grids

Per-carrier physical constants and bounds.

class monee.model.grid.GasGrid(name: str, molar_mass: float, dynamic_visc_pas: float, higher_heating_value_kwh_per_kg: float, universal_gas_constant: float, t_k: float, t_ref_k: float, pressure_ref_pa: float, nominal_pressure_pu: float, max_mass_flow_kgs: float, pressure_squared_pu_max: float, pressure_squared_pu_min: float, compressibility: float = None, pressure_ambient_pa: float = 0.0)

Bases: Grid

Gas grid domain. Construct via create_gas_grid() for defaults.

compressibility defaults to None and is then derived from the reference pressure (pressure_ref_pa), temperature (t_k) and molar_mass via the Papay real-gas correlation (see monee.model.phys.core.properties), so Z reflects the grid’s declared operating pressure rather than a fixed ideal-gas 1. Pass an explicit value to override (e.g. to force ideal gas with compressibility=1).

compressibility: float = None

dynamic_visc_pas: float

higher_heating_value_kwh_per_kg: float

max_mass_flow_kgs: float

molar_mass: float

nominal_pressure_pu: float

pressure_ambient_pa: float = 0.0

pressure_ref_pa: float

pressure_squared_pu_max: float

pressure_squared_pu_min: float

t_k: float

t_ref_k: float

universal_gas_constant: float

class monee.model.grid.Grid(name: str)

Bases: object

Marker/base for a resource domain (electrical, gas, heat).

name: str

class monee.model.grid.NoGrid(name: str)

Bases: Grid

Marker for components not bound to any grid.

class monee.model.grid.PowerGrid(name: str, sn_mva: float = 1, vm_pu_max: float = 1.5, vm_pu_min: float = 0.5)

Bases: Grid

Electrical grid domain.

sn_mva: float = 1

vm_pu_max: float = 1.5

vm_pu_min: float = 0.5

class monee.model.grid.WaterGrid(name: str, t_ref_k: float = 356, pressure_ref_pa: float = 1000000, max_mass_flow_kgs: float = 200, v_max_mps: float = 5.0, fluid_density_kg_per_m3: float = None, dynamic_visc_pas: float = None)

Bases: Grid

Water/heat grid domain.

fluid_density_kg_per_m3 and dynamic_visc_pas default to None and are then derived from t_ref_k via the standard water correlations (see monee.model.phys.core.properties), so the transport properties always match the grid’s declared operating temperature. Pass explicit values to override (e.g. to model a non-water fluid or a different reference).

dynamic_visc_pas: float = None

fluid_density_kg_per_m3: float = None

max_mass_flow_kgs: float = 200

pressure_ref_pa: float = 1000000

t_ref_k: float = 356

v_max_mps: float = 5.0

monee.model.grid.create_gas_grid(name, type='lgas', t_ref_k=None, pressure_ref_pa=None)

Return a GasGrid populated from GAS_GRID_ATTRS[type].

t_ref_k / pressure_ref_pa override the reference condition so the derived compressibility tracks the grid’s actual operating pressure. Pass them here rather than mutating the grid afterwards, so __post_init__ derives Z from the final values (a post-construction assignment leaves the already-derived Z stale).

monee.model.grid.create_power_grid(name, sn_mva=1)

monee.model.grid.create_water_grid(name, t_ref_k=356, pressure_ref_pa=1000000)

Return a WaterGrid whose density/viscosity are derived from t_ref_k (see WaterGrid). Pass t_ref_k here rather than mutating the grid afterwards, so the derived properties match the final reference temperature.

Node models

class monee.model.node.Bus(base_kv)

Bases: NodeModel

calc_signed_power_values(from_branch_models, to_branch_models, child_models)

equations(grid, from_branch_models, to_branch_models, child_models, **kwargs)

Return nodal equations (e.g. flow conservation, voltage balance).

p_mw_equation(child_models)

q_mvar_equation(child_models)

class monee.model.node.Junction

Bases: NodeModel

calc_signed_heat_flow(from_branch_models, to_branch_models, child_models, grid)

calc_signed_mass_flow(from_branch_models, to_branch_models, child_models)

equations(grid, from_branch_models, to_branch_models, child_models, **kwargs)

Return nodal equations (e.g. flow conservation, voltage balance).

Branch models

class monee.model.branch.GasCompressor(compression_ratio=1.5, max_flow_kgs=10.0)

Bases: BranchModel

Ideal compressor - fixed pressure ratio, unidirectional (suction → discharge). Forward flow lives in mass_flow_neg_kgs to match GasPipe’s Weymouth convention.

equations(grid: monee.model.grid.GasGrid, from_node_model, to_node_model, **kwargs)

class monee.model.branch.GasPipe(diameter_m, length_m, temperature_ext_k=296.15, roughness_m=0.0001, on_off=1, friction=None)

Bases: BranchModel

equations(grid: monee.model.grid.GasGrid, from_node_model, to_node_model, **kwargs)

class monee.model.branch.GenericPowerBranch(tap, shift, br_r_pu, br_x_pu, g_fr_pu, b_fr_pu, g_to_pu, b_to_pu, max_i_ka=3.19, backup=False, on_off=1, **kwargs)

Bases: BranchModel

equations(grid: monee.model.grid.PowerGrid, from_node_model, to_node_model, **kwargs)

property loading_pu

loss_percent()

class monee.model.branch.HeatExchanger(q_mw, mass_flow_design_kgs=None, T_delta_design_K=30, regulation=1)

Bases: BranchModel

equations(grid: monee.model.grid.WaterGrid, from_node_model, to_node_model, **kwargs)

class monee.model.branch.HeatExchangerGenerator(q_mw, mass_flow_design_kgs=None, regulation=1)

Bases: HeatExchanger

class monee.model.branch.HeatExchangerLoad(q_mw, mass_flow_design_kgs=None, regulation=1)

Bases: HeatExchanger

class monee.model.branch.PassiveHeatExchanger(q_mw, diameter_m, roughness_m=0.0001, length_m=2.5, temperature_ext_k=293, regulation=1, friction=None, loss_coefficient=None)

Bases: BranchModel

Passive heat exchanger injecting/extracting fixed q_mw into a free-flowing water branch. Mass flow is determined by surrounding hydraulics; temperature change follows from q_mw and actual mass flow.

Sign: positive q_mw = load, negative = generator.

Hydraulics: by default the pressure drop is Darcy-Weisbach friction over length_m. Passing loss_coefficient (zeta) instead switches to the pandapipes heat_exchanger model - a zero-length minor loss \(\Delta p = \zeta \cdot \tfrac{\rho}{2} v^2\) (length_m / friction are then ignored; loss_coefficient=0 is a lossless heat injector).

equations(grid: monee.model.grid.WaterGrid, from_node_model, to_node_model, **kwargs)

class monee.model.branch.PassiveHeatExchangerGenerator(q_mw, diameter_m, temperature_ext_k=293, loss_coefficient=None)

Bases: PassiveHeatExchanger

Passive heat exchanger that injects heat (generator, q_mw < 0).

class monee.model.branch.PassiveHeatExchangerLoad(q_mw, diameter_m, temperature_ext_k=293, loss_coefficient=None)

Bases: PassiveHeatExchanger

Passive heat exchanger that consumes heat (load, q_mw > 0).

class monee.model.branch.PowerBranch(tap, shift, backup=False, on_off=1, **kwargs)

Bases: GenericPowerBranch, ABC

abstractmethod calc_r_x(grid, from_node_model, to_node_model)

equations(grid: monee.model.grid.PowerGrid, from_node_model, to_node_model, **kwargs)

class monee.model.branch.PowerLine(length_m, r_ohm_per_m, x_ohm_per_m, parallel, backup=False, on_off=1, **kwargs)

Bases: PowerBranch

calc_r_x(grid: monee.model.grid.PowerGrid, from_node_model, to_node_model)

class monee.model.branch.Trafo(vk_percent=12.2, vkr_percent=0.25, sn_trafo_mva=160, shift=0)

Bases: PowerBranch

calc_r_x(grid: monee.model.grid.PowerGrid, lv_model, hv_model)

equations(grid: monee.model.grid.PowerGrid, from_node_model, to_node_model, **kwargs)

class monee.model.branch.WaterPipe(diameter_m, length_m, temperature_ext_k=283.15, roughness_m=4.5e-05, lambda_insulation_w_per_m_k=0.025, insulation_thickness_m=0.12, on_off=1, friction=None, unidirectional=False)

Bases: BranchModel

equations(grid: monee.model.grid.WaterGrid, from_node_model, to_node_model, **kwargs)

loss_percent()

monee.model.branch.sign(v)

Child models

class monee.model.child.ConsumeHydrGrid(mass_flow_kgs=0.1, pressure_pu=1, t_k=293, **kwargs)

Bases: NoVarChildModel

Hydraulic demand point: fixed pressure setpoint plus a free mass_flow_kgs Var.

class monee.model.child.ExtHydrGrid(mass_flow_kgs=-1, pressure_pu=1, t_k=356, max_import_kgs=None, max_export_kgs=None, pin_temperature=True, **kwargs)

Bases: NoVarChildModel, GridFormingMixin

External hydraulic slack source. Pins pressure (and optionally temperature), leaves mass_flow_kgs as a free Var. Load convention: negative mass_flow_kgs = injection.

overwrite(node_model, grid)

Pin pressure; pin temperature only if pin_temperature (default True). Set False on return-side slacks so T emerges from upstream heat balance.

class monee.model.child.ExtPowerGrid(p_mw, q_mvar, vm_pu=1, va_degree=0, max_import_mw=None, max_export_mw=None, **kwargs)

Bases: NoVarChildModel, GridFormingMixin

External slack-bus connection. Pins vm_pu and va_degree, leaves p_mw/q_mvar as free Vars absorbing the island’s imbalance. Load convention: positive p_mw = import.

overwrite(node_model, grid)

Pin the bus voltage magnitude and angle to the configured setpoints.

class monee.model.child.GridFormingMixin

Bases: object

Marker: this child can serve as the slack/reference for an islanded sub-network.

Carriers must implement overwrite() to pin their reference variable. Islanding keeps components containing a GridFormingMixin child in the solve.

class monee.model.child.HeatGenerator(q_mw, **kwargs)

Bases: NoVarChildModel

Node-based heat injection (H_G,i). Takes positive magnitude; sign is internal.

class monee.model.child.HeatLoad(q_mw, **kwargs)

Bases: NoVarChildModel

Node-based heat withdrawal (H_L,i). Positive q_mw = consumption.

class monee.model.child.NoVarChildModel(regulation: float = 1.0, **kwargs)

Bases: ChildModel

ChildModel with only scalar parameters and no equations of its own.

equations(grid, node, **kwargs)

class monee.model.child.PowerGenerator(p_mw, q_mvar, **kwargs)

Bases: NoVarChildModel

Fixed-setpoint active/reactive generator. Constructor takes positive magnitudes; sign is internal.

class monee.model.child.PowerLoad(p_mw, q_mvar, **kwargs)

Bases: NoVarChildModel

Fixed-setpoint power load. Load convention: positive = consumption.

class monee.model.child.Sink(mass_flow_kgs, **kwargs)

Bases: NoVarChildModel

Fixed-setpoint mass-flow sink. Positive = consumption (load convention).

class monee.model.child.Source(mass_flow_kgs, t_k=None, **kwargs)

Bases: NoVarChildModel

Fixed-setpoint mass-flow source. Constructor takes positive magnitude; sign is internal.

t_k (optional) is the temperature of the injected stream. Without it the injection is credited at the junction’s own (mixed) temperature.

Storage models

Storage child models for multi-energy timeseries simulation.

Each model exposes a tracked SoC variable persisted to StepState between timesteps; inter_step_equations couples it to the previous step.

Load convention: positive = charging (consume from network), negative = discharging.

Dispatch (p_mw / mass_flow_kgs) is a plain float by default - fixed setpoint in energy-flow solves. Call make_controllable() (or OptimizationProblem.controllable_storages()) to promote it to a Var.

class monee.model.storage.ElectricStorage(e_mwh_initial, e_mwh_max, p_max_mw, p_mw_initial=0.0, efficiency_charge=1.0, efficiency_discharge=1.0, regulation=1, **kwargs)

Bases: ChildModel

Battery/electric storage attached to a power bus.

SoC update: e_mwh(t) = e_mwh(t-1) + dt_h * p_mw(t). With efficiency losses, p_mw = p_charge_mw - p_discharge_mw (both \(\ge\) 0) and SoC uses \(\eta_c \cdot p_{charge} - p_{discharge} / \eta_d\).

equations(grid, node, **kwargs)

inter_temporal_equations(temporal_state: monee.solver.core.InterStepState, component_id, **kwargs)

make_controllable()

Promote p_mw (and loss-split vars if lossy) into solver Vars.

class monee.model.storage.GasStorage(m_stored_kg_initial, m_stored_kg_max, flow_max_kgs, mass_flow_initial_kgs=0.0, efficiency_charge=1.0, efficiency_discharge=1.0, regulation=1, **kwargs)

Bases: ChildModel

Pressurised gas storage at a gas junction.

SoC update: m_stored_kg(t) = m_stored_kg(t-1) + dt_s * mass_flow_kgs(t). Lossy: mass_flow_kgs = flow_charge_kgs - flow_discharge_kgs with η_c * charge - discharge / η_d in the SoC update.

equations(grid, node, **kwargs)

inter_temporal_equations(temporal_state: monee.solver.core.InterStepState, component_id, **kwargs)

make_controllable()

Promote mass_flow_kgs (and loss-split vars if lossy) into solver Vars.

class monee.model.storage.ThermalStorage(m_stored_kg_initial, m_stored_kg_max, flow_max_kgs, mass_flow_initial_kgs=0.0, loss_factor_per_h=0.0, regulation=1, **kwargs)

Bases: ChildModel

Thermal storage (e.g. hot-water tank) at a water junction.

SoC update: m_stored_kg(t) = m_stored_kg(t-1) - loss*dt_h*m_stored_kg(t-1) + dt_s*mass_flow_kgs(t).

equations(grid, node, **kwargs)

inter_temporal_equations(temporal_state: monee.solver.core.InterStepState, component_id, **kwargs)

make_controllable()

Promote mass_flow_kgs into a solver Var.

Multi-energy couplers

class monee.model.multi.CHP(diameter_m: float, efficiency_power: float, efficiency_heat: float, mass_flow_setpoint_kgs: float, q_mvar_setpoint: float = 0, temperature_ext_k: float = 293, regulation=1)

Bases: MultiGridCompoundModel

create(network: monee.model.network.Network, gas_node: monee.model.core.Node, heat_node: monee.model.core.Node, heat_return_node: monee.model.core.Node, power_node: monee.model.core.Node)

Add sub-components (nodes, branches, children) to network.

set_active(activation_flag)

class monee.model.multi.CHPControlNode(mass_flow_capacity_kgs, efficiency_power, efficiency_heat, hhv, q_mvar=0, regulation=1, **kwargs)

Bases: MultiGridNodeModel, Junction, Bus

Control node for a CHP unit; couples power, heat, and gas domains.

equations(grid, from_branch_models, to_branch_models, childs, **kwargs)

Return nodal equations (e.g. flow conservation, voltage balance).

class monee.model.multi.CHPHG(efficiency_power: float, efficiency_heat: float, mass_flow_setpoint_kgs: float, q_mvar_setpoint: float = 0, regulation=1)

Bases: MultiGridCompoundModel

HeatGenerator-based CHP variant: heat is injected via a SubHG child at heat_node instead of via an HX branch. No heat_return_node / diameter_m required.

create(network: monee.model.network.Network, gas_node: monee.model.core.Node, heat_node: monee.model.core.Node, power_node: monee.model.core.Node)

Add sub-components (nodes, branches, children) to network.

class monee.model.multi.CHPHGControlNode(mass_flow_capacity_kgs, efficiency_power, efficiency_heat, hhv, sub_hg, q_mvar=0, regulation=1, **kwargs)

Bases: MultiGridNodeModel, Junction, Bus

CHP control node using a node-based HeatGenerator (no HX branch).

Like CHPControlNode but only on power+gas; heat goes through a SubHG child attached at the heat node by CHPHG.

equations(grid, from_branch_models, to_branch_models, childs, **kwargs)

Return nodal equations (e.g. flow conservation, voltage balance).

class monee.model.multi.GasToHeat(heat_energy_mw, diameter_m, temperature_ext_k, efficiency, regulation=1)

Bases: MultiGridCompoundModel

create(network: monee.model.network.Network, gas_node: monee.model.core.Node, heat_node: monee.model.core.Node, heat_return_node: monee.model.core.Node)

Add sub-components (nodes, branches, children) to network.

set_active(activation_flag)

class monee.model.multi.GasToHeatControlNode(gas_mass_flow_kgs, efficiency_heat, hhv, regulation=1, **kwargs)

Bases: MultiGridNodeModel, Junction

equations(grid, from_branch_models, to_branch_models, childs, **kwargs)

Return nodal equations (e.g. flow conservation, voltage balance).

class monee.model.multi.GasToHeatHG(heat_energy_mw, efficiency, regulation=1)

Bases: MultiGridBranchModel

Two-endpoint Gas→Heat coupling (gas withdrawal at from-end, q_mw_heat injection at to-end). Junction heat balance picks up q_mw_heat directly.

equations(grids, from_node_model, to_node_model, **kwargs)

init(grids)

loss_percent()

class monee.model.multi.GasToPower(efficiency, p_mw_setpoint, q_mvar_setpoint=0, regulation=1)

Bases: MultiGridBranchModel

equations(grids, from_node_model, to_node_model, **kwargs)

loss_percent()

class monee.model.multi.GenericTransferBranch(flow_init_kgs: float = 1.0, p_init_mw: float = 1.0, **kwargs)

Bases: MultiGridBranchModel

equations(grids, from_node_model, to_node_model, **kwargs)

init(grids)

is_cp()

class monee.model.multi.PowerToGas(efficiency, mass_flow_setpoint_kgs, consume_q_mvar_setpoint=0, regulation=1)

Bases: MultiGridBranchModel

equations(grids, from_node_model, to_node_model, **kwargs)

loss_percent()

class monee.model.multi.PowerToHeat(heat_energy_mw, diameter_m, temperature_ext_k, efficiency, q_mvar_setpoint=0, regulation=1)

Bases: MultiGridCompoundModel

create(network: monee.model.network.Network, power_node: monee.model.core.Node, heat_node: monee.model.core.Node, heat_return_node: monee.model.core.Node)

Add sub-components (nodes, branches, children) to network.

set_active(activation_flag)

class monee.model.multi.PowerToHeatControlNode(load_p_mw, load_q_mvar, efficiency, regulation=1, **kwargs)

Bases: MultiGridNodeModel, Junction, Bus

equations(grid, from_branch_models, to_branch_models, childs, **kwargs)

Return nodal equations (e.g. flow conservation, voltage balance).

class monee.model.multi.PowerToHeatHG(heat_energy_mw, efficiency, q_mvar_setpoint=0, regulation=1)

Bases: MultiGridBranchModel

Two-endpoint Power→Heat coupling (p_from_mw at from-end, q_mw_heat at to-end). Junction heat balance picks up q_mw_heat directly.

equations(grids, from_node_model, to_node_model, **kwargs)

loss_percent()

class monee.model.multi.SubHE(q_mw, mass_flow_design_kgs=None, T_delta_design_K=30, regulation=1)

Bases: HeatExchanger

Subordinate heat exchanger used inside compound models (CHP, G2H, P2H).

class monee.model.multi.SubHG(**kwargs)

Bases: NoVarChildModel

Subordinate node-based heat generator used inside CHPHG.

Like HeatGenerator but with q_mw_heat as a Var constrained by the parent compound’s control-node equations. Two-endpoint HG variants (GasToHeatHG / PowerToHeatHG) don’t use this - they carry q_mw_heat directly on the branch.