pypsa-custom-constraints

PyPSA Custom Constraints (linopy)

Three steps, in order: 0. native GlobalConstraint type covers it? -> component, ZERO linopy (list below). 1. else express in linopy. 2. PROVE it landed. ! Never deliver without verification checklist. Silently-ignored constraint -> plausible wrong results.

Step 0 - native first (zero linopy)

• GlobalConstraint types: "primary_energy" (CO2/byproduct cap) | "operational_limit" (carrier net production, e.g. gas/biomass budget) | "transmission_volume_expansion_limit" (MWkm) | "transmission_expansion_cost_limit" (EUR) | "tech_capacity_expansion_limit" (cap per carrier, optional per bus + investment_period; replaces deprecated per-bus-carrier nominal constraints). ! Don't hand-roll these — CCL-style caps = tech_capacity_expansion_limit. ! 1.0.x: tech_capacity_expansion_limit NotImplemented on stochastic (set_scenarios) networks
• Carrier growth limits (max_growth | max_relative_growth) = component attributes, also zero linopy -> pypsa-network-modeling/references/multi-period.md

Attachment patterns

# Pattern A - callback (works with n.optimize)
def extra_functionality(n, snapshots):
    m = n.model
    p = m.variables["Generator-p"]          # dims: (snapshot, name)
    m.add_constraints(..., name="my-constraint")

n.optimize(extra_functionality=extra_functionality, solver_name="highs")

# Pattern B - explicit (better for debugging)
n.optimize.create_model()
m = n.model
m.add_constraints(..., name="my-constraint")
n.optimize.solve_model(solver_name="highs")

Variable name map (linopy labels)

• Generator-p | Generator-p_nom | Link-p | Link-p_nom | Line-s | Line-s_nom | Store-e | Store-p | StorageUnit-state_of_charge | StorageUnit-p_dispatch | StorageUnit-p_store
• ! component dimension in linopy vars = name (NOT the class): select subsets via .sel(name=index). Capacity vars exist only for *_nom_extendable=True
• ! coefficient alignment: pandas Series w/ mismatched indices -> silent all-NaN. Per-component coefficients = xr.DataArray(..., coords={"name": idx}) | per-snapshot = DataArray on dim snapshot (references/generic-patterns.md)
• ! fixed-capacity components = CONSTANTS, not variables -> mixed fleets: ADD constant part to constraint RHS/LHS explicitly