Formulation Library

Introduction

A PowerOperationsModels problem is assembled from three kinds of formulation choices:

• one network formulation (NetworkModel{N}) for the whole problem — how the transmission system is represented,
• a device formulation (DeviceModel{D, F}) per device type — how each component type is modelled,
• a service formulation (ServiceModel{S, F}) per service — how each service is modelled.

Every formulation implements construct_device! (or construct_service! / construct_network!) for two dispatch stages, and the split matters when reading the tables below:

Expressions must be wired before the constraints that consume them, which is why the balance expressions (ActivePowerBalance, ReactivePowerBalance) are populated during the argument stage and only closed with an == 0 constraint during the model stage.

Not every (device formulation, network formulation) pair is valid. Pairs that are rejected are caught by template validation, which throws IS.ConflictingInputsError rather than failing deep in the build. The tables mark unsupported pairs explicitly.

How to read these tables

• Variables are the JuMP variables the formulation creates.
• Constraints are the constraint containers it creates.
• Expressions are written as Target ← Source, meaning the source variable is added into the target balance expression.
• meta lists the meta strings used to slice a single key type into several containers (see When to use meta versus a new key type below).
• no-op means a method exists and returns without emitting anything — the pair is legal but contributes nothing. This is distinct from unsupported, where no method exists.

Network Formulations

Network model type hierarchy

The abstract bounds that drive dispatch:

IOM.AbstractNetworkModel
├── AbstractActivePowerModel
│   ├── AbstractDCPNetworkModel
│   │   ├── DCPNetworkModel
│   │   ├── AbstractPTDFNetworkModel
│   │   │   ├── PTDFNetworkModel
│   │   │   └── AreaPTDFNetworkModel
│   │   ├── AbstractNFANetworkModel   → NFANetworkModel
│   │   └── AbstractDCPLLNetworkModel → DCPLLNetworkModel
│   ├── CopperPlateNetworkModel
│   └── AreaBalanceNetworkModel
└── AbstractReactivePowerNetworkModel
    ├── AbstractACPModel          → ACPNetworkModel
    ├── AbstractACRNetworkModel   → ACRNetworkModel
    ├── AbstractLPACCNetworkModel → LPACCNetworkModel
    └── AbstractIVRNetworkModel   → IVRNetworkModel

Note that AbstractPTDFNetworkModel <: AbstractDCPNetworkModel, so any method bound to <:AbstractDCPNetworkModel also matches the PTDF models. CopperPlateNetworkModel and AreaBalanceNetworkModel are not DCP subtypes.

The shorthands used throughout these tables:

• ACP — AC power flow in polar coordinates (voltage magnitude and angle),
• ACR — AC power flow in rectangular coordinates (voltage real and imaginary),
• IVR — AC current-voltage rectangular formulation,
• LPACC — linear-programming AC approximation (cold-start),
• DCP — DC power flow; DCPLL — DC power flow with line losses,
• NFA — network flow approximation (no voltage angles),
• PTDF / AreaPTDF — power-transfer-distribution-factor transport, nodal / area-keyed.

What each network model adds

The balance expression containers themselves are allocated up front by initialize_system_expressions!, before any construct_*! runs. A network model does not create them; it wires the system slacks into them (argument stage) and closes them with a balance constraint (model stage).

All network variables, including the slacks, are created in the argument stage. System slacks are only added when use_slacks = true on the NetworkModel, and they are penalized in the objective at BALANCE_SLACK_COST during the model stage.

System slack containers

The slack container's key and axis depend on the network model, and the AC models are the only ones that use a meta:

The AC models split SystemBalanceSlackUp / SystemBalanceSlackDown into two containers — one for active power ("P") and one for reactive ("Q") — because a single bus axis has to carry both. These metas are passed positionally, not as a meta = keyword.

Reference bus constraint

ReferenceBusConstraint pins the slack bus of each subnetwork, and what it pins depends on the voltage coordinates:

The AC models additionally error if the reference-bus setpoint falls outside the bus voltage limits.

Branch Formulations

AC branch formulations

The branch constructors delegate to shared helpers, so a constructor body that looks short still emits several containers. The helpers expand as follows:

Note the asymmetry: _add_flow_slacks! adds an upper and lower slack, while _add_static_branch_balance_arguments! — the path taken by StaticBranch on the AC network models — adds only the upper slack.

StaticBranch support matrix

DCPLLNetworkModel enforces the rating either with slacks or with hard JuMP bounds on the directional flow variables, never both: when use_slacks = false the FlowRateConstraint builder returns without emitting anything and the rating lives entirely in the variable bounds.

StaticBranchBounds

Rating enforcement per network model, StaticBranch vs StaticBranchBounds side by side:

StaticBranchBounds supports use_slacks on every network model except NFANetworkModel — the NFA rating has no equality or constraint row for a slack to relax. Which pairs have slack machinery is declared once, per (formulation, network) pair, by the slack_spec trait (core/branch_slack_specs.jl); the supports_flow_slacks gate derives from it, so any pair whose constructors build no slack containers (StaticBranchBounds × NFA, StaticBranchUnbounded × anything) is rejected at template validation with IS.ConflictingInputsError rather than left to silently ignore the request; a construct-time backstop (_check_flow_slack_support) throws ArgumentError for any direct-construct path that bypasses template validation. On CopperPlateNetworkModel/AreaBalanceNetworkModel the branch model is a no-op, so use_slacks is accepted but inert — validation emits a warning instead of erroring so templates stay reusable on aggregated networks.

Slack mechanisms

StaticBranch and StaticBranchBounds relax the rating through structurally different mechanisms, following directly from where each formulation puts its rating:

On IVRNetworkModel both mechanisms are present at once, on different equations:

• StaticBranch relaxes the terminal CurrentLimitConstraint quadratic (cr² + ci² ≤ c_rating²) with one-sided metaed slacks "c_from"/"c_to".
• StaticBranchBounds leaves CurrentLimitConstraint hard and instead relaxes the four terminal KCL current-defining equalities with their own metaed pairs — "cr_fr", "ci_fr", "cr_to", "ci_to" — one pair per definition because the from-side row scales the current by tm² while the to-side row does not, so a shared pair would relax the two ends unequally under off-nominal taps.

StaticBranchUnbounded

A no-op on every network model except PTDF, where the model stage still builds the PTDFBranchFlow expression (so flows are reportable, but unconstrained).

SecurityConstrainedStaticBranch

N-1 security constraints are built with Modified Outage Distribution Factors (PNM VirtualMODF).

Transformer tap control

Tap control is not a separate formulation. It is an opt-in attribute on the ordinary StaticBranch / StaticBranchBounds transformer models, driven by the component data:

DeviceModel(
    PSY.TwoWindingTransformer,
    StaticBranch;
    attributes = Dict(POM.ENABLE_CONTROLS_KEY => true),   # "enable_controls"
)

With the attribute set, each PSY.TransformerCircuit whose control_objective POM models gets a continuous TapRatioVariable bounded by the circuit's tap_ratio_limits, which enters the AC flow equations in place of the fixed tap. Control is per circuit, so each winding of a ThreeWindingTransformer is controlled independently.

Every other TransformerControlObjective is inert. UNDEFINED (the field default), FIXED and the *_DISABLED codes are treated as "no control block" and pass silently; the positive objectives POM does not yet model (ACTIVE_POWER_FLOW, CONTROL_OF_DC_LINE, ASYMMETRIC_ACTIVE_POWER_FLOW) emit a @warn and are ignored.

regulated_bus_number must name a bus that exists in the system; a VOLTAGE-controlled circuit whose regulated bus cannot be resolved is rejected at template validation.

A controlled circuit and its regulated bus are pinned irreducible, so a network reduction cannot absorb them. A controlled circuit that would be merged into a parallel-branch equivalent is a hard error rather than a silent demotion.

HVDC formulations

Two-terminal HVDC

The apparent-power limit on the VSC formulations depends on the "bilinear_approximation" device attribute. With the default "none" it is an exact quadratic disk ("from"/"to"); with a linearizing scheme it becomes a box of eight half-planes, plus eight more octagon cuts when "use_octagon" is true (the default).

AreaInterchange tie-line metering

AreaInterchange (StaticBranch/StaticBranchUnbounded) builds one LineFlowBoundConstraint per interchange, summing the measured export of every tie crossing its area boundary at the terminal on the interchange's from_area side. Each tie formulation resolves to a different container variable and sign, converted to a common "export at the measured terminal" convention:

On PTDF/AreaPTDF networks the same table applies on top of each tie's own PTDFBranchFlow nodal-injection response, so the metering coefficient surfaces as the difference between the constraint's coefficient on a tie variable and that tie's own PTDF row.

Multi-terminal HVDC (PSY.InterconnectingConverter, PSY.TModelHVDCLine)

LinearLossConverter models the loss b·|I| + c from the converter loss_function proportional/constant terms, approximating |I| by |P| at nominal DC voltage; a non-zero quadratic term is rejected at build.

The HVDC network model is a separate template slot from the AC network model:

ThermalGen Formulations

Nine concrete thermal formulations, under three abstract branches:

The standard family dispatches ActivePowerVariable directly. The compact family instead dispatches PowerAboveMinimumVariable and reconstructs total power as $p = P_{min} u + \hat{p}$, wiring both the above-minimum variable and the commitment status into ActivePowerBalance.

All nine implement both a <:AbstractNetworkModel and a <:AbstractActivePowerModel method, so all eleven network models are supported. The active-power method simply omits ReactivePowerVariable, the ReactivePowerBalance wiring, and ReactivePowerVariableLimitsConstraint.

Metas on thermal keys: "lb"/"ub" (range limits), "up"/"dn" (ramp and duration), "aux" (the CommitmentConstraint start+stop ≤ 1 container), "hot"/"warm" (startup temperature), and "ubon"/"uboff" on the MultiStart range limits.

FixedOutput supports AC networks: for thermal devices its ArgumentConstructStage wires both ActivePowerTimeSeriesParameter and ReactivePowerTimeSeriesParameter into their respective balances under any <:AbstractNetworkModel.

RenewableGen Formulations

Both dispatch formulations support all eleven network models. Renewable injection carries a negative objective multiplier, and the renewable cost expressions include a CurtailmentCostExpression (populated only for a CostCurve{LinearCurve}).

Note that RenewableConstantPowerFactor emits no ReactivePowerVariableLimitsConstraint at all — the power-factor equality replaces it.

Hydro Formulations

Hydro is the largest family. It splits by which PSY device the formulation attaches to.

On PSY.HydroGen

On PSY.HydroReservoir

On PSY.HydroTurbine / PSY.HydroPumpTurbine

ActivePowerPumpVariable enters ActivePowerBalance with multiplier -1.0 — pumping is a withdrawal. The three water-flow turbine formulations are collected by the union alias HydroTurbineWaterFormulation.

All hydro constructors are bound <:AbstractNetworkModel as well as <:AbstractActivePowerModel, so every formulation in this section supports AC networks: HydroCommitmentRunOfRiver, HydroPumpEnergyDispatch, and HydroPumpEnergyCommitment add the reactive-power variable and constraint on their <:AbstractNetworkModel path, and the turbine water-flow formulations (HydroTurbineBilinearDispatch, HydroTurbineWaterLinearDispatch, and HydroWaterFactorModel on a turbine) have their own HydroTurbine-specific methods for both stages, so they no longer fall through to the generic HydroDispatchRunOfRiver methods under an AC template.

Storage and Hybrid Formulations

There is exactly one concrete storage formulation and one concrete hybrid formulation.

StorageDispatchWithReserves

Attributes: "reservation", "reserve_coverage" (default true; reserve_coverage = false DECOUPLES energy and AS for day-ahead-style clearing: no SOC deployment-coverage constraints, reserve bands bounded by capability instead of the reservation binary's dispatch side, and complete_coverage ignored with a warning - the binary still governs energy exclusivity), "cycling_limits", "energy_target", "complete_coverage", "regularization" (all default false).

HybridDispatchWithReserves

A single PCC with optional thermal, renewable, storage and load subcomponents. Attributes: "reservation", "storage_reservation" (both default true), "energy_target", "regularization" (default false). One constructor pair covers all eleven network models; the reactive-power pieces are added conditionally.

The reserve trait axes

Storage and hybrid reserve expressions are parametrized on three axes rather than duplicated as sibling singletons:

• Direction — PSY.ReserveUp / PSY.ReserveDown
• Scale — UnscaledReserve (raw multiplier) / DeployedReserve (scaled by deployed_fraction). Attach a "deployed_fraction" profile to the reserve to make the fraction vary over the horizon; the scalar field then scales that profile, and the profile alone applies no scaling until the scalar is set. The profile is a left-hand-side parameter (DeployedFractionParameter), written into constraints as fixed coefficients, so a simulation rebuilds the model every step: rebuild_model is switched to true with a warning.
• Side — DischargeSide / ChargeSide

giving eight instantiations each of StorageReserveBalanceExpression{D,S,Sd} and HybridPCCReserveExpression{D,S,Sd}. Unscaled is used for assignment constraints (what may be offered); Deployed for energy-affecting constraints (state-of-charge balance, cycling, regularization).

The load-bearing rule is that the sides swap: on the discharge side an up-reserve raises effective power, but on the charge side the roles reverse, because a charging battery's net consumption is increased by downward reserve.

Load, Source and Shunt Formulations

ShuntSusceptanceDispatch is supported on ACPNetworkModel, ACRNetworkModel and IVRNetworkModel only: it is dropped from active-power templates by the models_reactive_power gate and rejected on LPACCNetworkModel by template validation. FixedShuntAdmittance injects a non-dispatched $q = b_\text{nominal} V^2$ (SwitchedAdmittance: $\operatorname{imag}(Y)$; FACTSControlDevice: the reactive-power setpoint) and builds on all four reactive networks — it is the only shunt formulation available under LPACCNetworkModel.

The ActivePowerBalance ← RealizedShiftedLoad wiring for PowerLoadShift is implemented for any <:AbstractNetworkModel, via the same _balance_expression_targets dispatch every other injection uses to reach its nodal, area, or system target.

Only PowerLoadDispatch and PowerLoadInterruption may contribute to reserves. When a load under either formulation carries a service model, its active-power limits move onto ActivePowerRangeExpressionLB/UB: an up award consumes shed headroom ($P - \sum r_\text{up} \ge 0$) and a down award consumes forecast headroom ($P + \sum r_\text{down} \le \bar{P}$), summed across every service at once. A template that wires a load into a reserve under any other formulation is rejected by name, because the award would otherwise be bounded only by the device's nameplate rating — uncoupled from its dispatch and uncoupled across services. StaticPowerLoad creates no variables and no cost expressions, so the capacity it sold would also be free in the objective; PowerLoadShift is priced and dispatchable, but its headroom is shift capability carrying an energy-recovery balance, which the range expression cannot express. The trait is supports_reserve_provision, and a load formulation added later must opt in.

SynchronousCondenserBasicDispatch is gated by models_reactive_power, so on an active-power network it is dropped from the template (with an @info message) rather than being built as a no-op.

Outage events

Attaching an EventModel for a PSY.Contingency supplemental attribute (e.g. FixedForcedOutage) to a DeviceModel in the template adds availability parameters and outage constraints to every device of that type carrying the attribute, on top of whatever variables and constraints its device formulation already contributes.

Parameters (per device and time step): AvailableStatusParameter (1 = available, initialized to 1) and AvailableStatusChangeCountdownParameter; loads and FixedOutput devices also get the balance offsets ActivePowerOffsetParameter / ReactivePowerOffsetParameter.

ActivePowerOutageConstraint bounds active power by available capacity, $p_t \le P^\text{max} \cdot \text{status}_t$, with the left-hand side depending on the device family: the range-expression upper bound for thermal and hydro generators, the active-power variable for loads and for renewables without a service model, the charge and discharge variables together for PSY.EnergyReservoirStorage, and, for PSY.HydroPumpTurbine, both the generation variable (ActivePowerOutageConstraint) and the pump variable (ActivePowerPumpOutageConstraint). Under reactive-power-capable networks, ReactivePowerOutageConstraint additionally bounds $q_t^2 \le \max\left((Q^\text{max})^2, (Q^\text{min})^2\right) \cdot \text{status}_t$.

The parameter values are constant within a single build; updating them across solves (outage sampling, countdown projection) is simulation-runtime functionality that lives outside this package.

Service Formulations

The group formulations are deliberately constructed last in both stages, because they aggregate the other services' award variables. A PSY.GroupReserve accepts only the group formulations (and vice versa); a mis-paired ServiceModel fails at declaration. A service whose demand driver is degenerate (zero requirement under the requirement formulations, no demand curve under the stepwise ones) is skipped as demand and built as supply only, so it can serve a group.

Reserve contributions reach a device through get_expression_type_for_reserve: for thermal, renewable and hydro an up-reserve enters ActivePowerRangeExpressionUB (+1) and a down-reserve ActivePowerRangeExpressionLB (−1); a controllable load is the inverse (an up-reserve is committed shed, entering ActivePowerRangeExpressionLB with −1, and a down-reserve is committed extra consumption, entering ActivePowerRangeExpressionUB with +1); storage and hybrid instead route everything into TotalReserveOffering. Any other device type hits an error — sources, condensers and shunts cannot contribute to a reserve.

Service meta strings are per-instance, not a fixed vocabulary: every reserve container is keyed by the service's own name (meta = get_service_name(model)). The only fixed metas here are "ub"/"lb" on InterfaceFlowLimit.

Offline reserves

For thermal unit commitment and HydroCommitmentRunOfRiver, OfflineReserve awards stay out of ActivePowerRangeExpressionUB and enter OfflineReserveBandConstraint, so a unit that is off supplies them up to the time step's available maximum $\bar{P}_t$: the ActivePowerTimeSeriesParameter when the DeviceModel maps it and the device has that series, the static $P^\text{max}$ otherwise. Two OfflineReserve ServiceModel attributes, both false by default, tighten an off-line award $r_t$:

Every right-hand side is non-negative, so zero off-line awards always satisfy the rows. Must-run thermal units never go off and get no shutdown-step row; HydroCommitmentRunOfRiver carries a DeviceStatus initial condition only under "exclude_shutdown_step". Other formulations book OfflineReserve awards against their headroom and get none of these rows.

Feedforward Formulations

A feedforward binds a model's variables to a quantity recorded in the system state — it is a model-to-state relationship, not a link between two models. See Feedforwards for what the system state is, how the semicontinuous substitution works, and when to use each type.

POM builds them in two stages: add_feedforward_arguments! (ArgumentConstructStage) allocates the VariableValueParameter container that carries the state quantity plus any slack variables, and add_feedforward_constraints! (ModelConstructStage) builds the constraints that read it. Populating those parameters between executions is PowerSimulations' job — it needs simulation state, which POM does not have.

Attach one to a device model with attach_feedforward!:

device_model = DeviceModel(ThermalStandard, ThermalStandardDispatch)
attach_feedforward!(
    device_model,
    SemiContinuousFeedforward(;
        component_type = ThermalStandard,
        source = OnVariable,
        affected_values = [ActivePowerVariable],
    ),
)

UpperBoundFeedforward and LowerBoundFeedforward accept add_slacks = true, which relaxes the bound with a non-negative UpperBoundFeedForwardSlack / LowerBoundFeedForwardSlack penalized at BALANCE_SLACK_COST.

SemiContinuousFeedforward suppresses the affected formulation's own range constraints — has_semicontinuous_feedforward gates them — because the commitment status arrives as a parameter in the ActivePowerRangeExpressionUB / …LB expressions instead. Must-run thermal units are excluded throughout: they are never turned off, so they carry no OnStatusParameter entry and get no semicontinuous constraints.

ReservoirTargetFeedforward and EnergyTargetFeedforward build the same FeedforwardEnergyTargetConstraint container, distinguished by meta; unlike EnergyTargetFeedforward, ReservoirTargetFeedforward does not require target_period to be the horizon's last step. ReservoirLimitFeedforward and EnergyLimitFeedforward likewise share one FeedforwardIntegralLimitConstraint container, again separated by meta, and differ only in the parameter they read. ReservoirLimitFeedforward dispatches on any PSY.Component, not only hydro reservoirs, despite its name. HydroUsageLimitFeedforward reads ActivePowerVariable directly rather than an entry from affected_values; when the device model carries a service model, the sum nets in served regulation reserves (HydroServedReserveUpExpression / …DownExpression) before comparing to the limit.

Piecewise-linear cost

There are two piecewise-linear cost formulations, and which one you get is decided by the shape of the cost data, not by a flag:

The lambda normalization couples to the commitment status: its right-hand side is 1.0 with no commitment, the OnStatusParameter for a compact dispatch, or the OnVariable for a unit commitment.

Offer direction selects the delta family: generation is an IncrementalOffer; the charging side of storage, the import side of a Source, and controllable loads are DecrementalOffer (negative objective sign). Operating reserve demand curves are also decremental, because a willingness-to-pay curve is concave.

When to use meta versus a new key type

Every container key (VariableKey, ConstraintKey, ExpressionKey, ParameterKey) carries a meta::String field, defaulting to IOM.CONTAINER_KEY_EMPTY_META (""). The choice between adding a meta and defining a new key type is a modelling decision, not a naming one:

• Use meta when you are slicing one conceptual object along an orthogonal axis. The slices share a name because they are the same constraint viewed from different sides — for example a single FlowRateConstraint sliced into "lb" and "ub", or a single NetworkFlowConstraint sliced into "p_ft", "q_ft", "p_tf", "q_tf". Reserving a new type for each slice would multiply near-identical types and make it impossible to ask for "the flow-rate constraints" as a group.

• Use a distinct key type when the constraint is semantically different — it expresses a different physical or economic relationship. NetworkFlowConstraint (Ohm's law) and FlowRateConstraint (a thermal rating) both act on branch flows, but they are different statements about the system and so are different types.

A useful test: if you would ever want to enable, disable, dualize, or report the two things independently as concepts, they are different types. If you would always want them together and are only separating them because a single container cannot hold both, that is a meta.

Two mechanical consequences worth knowing:

• add_variable_container! has an extra method taking meta::String positionally as its fourth argument; add_constraints_container! accepts meta as a keyword only. The AC network slacks ("P" / "Q") use the positional form, so a grep for meta = will not find them.
• meta must not contain the component-name delimiter; check_meta_chars enforces this.

Meta vocabulary

Most metas fall into a small number of families: