monee.model.extension

All public names are re-exported at top level (monee.*) and from monee.model; the sections below document each submodule under its canonical path.

Base

class monee.model.extension.core.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

Gas linepack

Gas linepack extension.

Pipelines act as distributed storage: \(\text{linepack\_kg} = V_{pipe} \cdot \rho_{avg}\) with \(\rho = p \cdot M / (R \cdot T)\). Between timesteps, \(\text{net\_pack\_kgs}(t) \cdot \Delta t = \text{linepack\_kg}(t) - \text{linepack\_kg}(t-1)\) - positive = charging. Each endpoint junction sees \(+0.5 \cdot \text{net\_pack\_kgs}\) (outflow-positive convention).

Single-step solves pin net_pack_kgs = 0; timeseries activates the temporal coupling.

class monee.model.extension.linepack.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

Lumped thermal capacitance

Lumped Thermal Capacitance (LTC) extension for water junctions.

Each junction gets thermal mass \(\rho \cdot \sum V_{pipe}/2\) from connected pipes. The inertia equation:

\[\rho \cdot V \cdot (T_{pu}(t) - T_{pu}(t-1))/\Delta t = \text{net\_convective\_heat\_in}\]

replaces the degenerate \(T_n \cdot \text{mass\_balance} = 0\) heat balance at LTC nodes. No-op in single-step solves.

class monee.model.extension.ltc.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

Islanding

Islanding system for multi-carrier grid restoration.

IslandingMode is the per-carrier base (implements NetworkAspect); NetworkIslandingConfig bundles modes for registration via network.add_extension().

class monee.model.extension.islanding.core.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.extension.islanding.core.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

Electricity

Electricity-carrier islanding mode and grid-forming generator model.

class monee.model.extension.islanding.el.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.extension.islanding.el.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

Gas

Gas-carrier islanding mode and grid-forming source model.

class monee.model.extension.islanding.gas.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.extension.islanding.gas.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

Water

Water-carrier islanding mode (structurally identical to GasIslandingMode).

class monee.model.extension.islanding.water.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'