# attribute_validation_rules

component_type: BUS
attribute_name: x
display_name: Longitude
data_type: float
unit: n/a
default_value: 0
allowed_storage_types: static
group_name: basic
description:
Longitude; A measurement of angular distance, expressed in degrees, east or west of the Prime Meridian.


component_type: BUS
attribute_name: unit
display_name: Unit
data_type: string
unit: n/a
default_value: None
allowed_storage_types: static
group_name: basic
description:
Unit of the bus' carrier if the implicitly assumed unit ("MW") is inappropriate (e.g. "t/h", "MWh_th/h"). Only descriptive. Does not influence any functions.


component_type: BUS
attribute_name: v_mag_pu_min
display_name: Min Voltage Magnitude
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
Minimum desired voltage, per unit of the nominal voltage (v_nom). This is a placeholder attribute and is not currently used by any functions.


component_type: BUS
attribute_name: v_mag_pu_max
display_name: Max Voltage Magnitude
data_type: float
unit: per unit
default_value: inf
allowed_storage_types: static
group_name: electrical
description:
Maximum desired voltage, per unit of the nominal voltage (v_nom). This is a placeholder attribute and is not currently used by any functions.


component_type: BUS
attribute_name: control
display_name: Control Strategy
data_type: string
unit: n/a
default_value: PQ
allowed_storage_types: static
group_name: electrical
description:
P,Q,V control strategy for PF, must be "PQ", "PV" or "Slack". Note that this attribute is an output inherited from the controls of the generators attached to the bus; setting it directly on the bus will not have any effect.


component_type: BUS
attribute_name: sub_network
display_name: Sub-Network
data_type: string
unit: n/a
default_value: n/a
allowed_storage_types: static
group_name: basic
description:
Name of connected sub-network to which bus belongs. This attribute is set by PyPSA in the function network.determine_network_topology(); do not set it directly by hand.


component_type: BUS
attribute_name: marginal_price
display_name: Marginal Price
data_type: float
unit: currency/MWh
default_value: 0
allowed_storage_types: timeseries
group_name: costs
description:
Locational marginal price from LOPF from power balance constraint (shadow price). Includes effects of UC constraints, ramping limits, and other binding constraints.


component_type: BUS
attribute_name: clearing_price
display_name: Clearing Price
data_type: float
unit: currency/MWh
default_value: 0
allowed_storage_types: timeseries
group_name: costs
description:
Pay-as-clear price: marginal cost of the cheapest available source (generator, storage, or import via uncongested link) with spare capacity. Calculated as min of: (1) local generators/storage with spare capacity, (2) adjacent bus local marginal + link cost adjusted for efficiency, for uncongested links, (3) unmet load price in scarcity. Differs from marginal_price which is the LP shadow price.


component_type: GENERATOR
attribute_name: control
display_name: Control Strategy
data_type: string
unit: n/a
default_value: PQ
allowed_storage_types: static
group_name: electrical
description:
Power flow control mode: "PQ" (fixed active and reactive power), "PV" (fixed active power and voltage magnitude), or "Slack" (balances system power, typically one per network).


component_type: GENERATOR
attribute_name: p_nom
display_name: Nominal Power
data_type: float
unit: MW
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The maximum rated capacity of the generator in MW. This sets the upper limit for power output in all calculations.


component_type: GENERATOR
attribute_name: p_nom_mod
display_name: Nominal Power Module
data_type: float
unit: MW
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The unit size for capacity expansion. When extending the nominal power (p_nom), it can only be increased in multiples of this module size.


component_type: GENERATOR
attribute_name: p_nom_max
display_name: Max Nominal Power
data_type: float
unit: MW
default_value: inf
allowed_storage_types: static
group_name: capacity
description:
If the nominal power (p_nom) is extendable in optimization, set its maximum value (e.g. limited by technical potential).


component_type: GENERATOR
attribute_name: p_min_pu
display_name: Min Capacity Factor
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
The minimum output for each snapshot per unit of the nominal power (p_nom) for the optimization (e.g. for variable renewable generators this can change due to weather conditions and compulsory feed-in; for conventional generators it represents a minimal dispatch). Note that if committable is False and the min capacity factor (p_min_pu) > 0, this represents a must-run condition.


component_type: GENERATOR
attribute_name: p_max_pu
display_name: Max Capacity Factor
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
The maximum output for each snapshot per unit of the nominal power (p_nom) for the optimization (e.g. for variable renewable generators this can change due to weather conditions; for conventional generators it represents a maximum dispatch).


component_type: GENERATOR
attribute_name: p_set
display_name: Active Power Setpoint
data_type: float
unit: MW
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
Fixed active power output that the generator must produce. Used when the generator output is predetermined rather than optimized.


component_type: GENERATOR
attribute_name: e_sum_min
display_name: Min Energy Sum
data_type: float
unit: MWh
default_value: -inf
allowed_storage_types: static
group_name: energy
description:
The minimum total energy that must be produced over the entire time period being optimized (the optimization horizon).


component_type: GENERATOR
attribute_name: e_sum_max
display_name: Max Energy Sum
data_type: float
unit: MWh
default_value: inf
allowed_storage_types: static
group_name: energy
description:
The maximum total energy that can be produced over the entire time period being optimized (the optimization horizon).


component_type: GENERATOR
attribute_name: q_set
display_name: Reactive Power Setpoint
data_type: float
unit: MVar
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
Fixed reactive power output that the generator must produce. Used when the reactive power output is predetermined rather than optimized.


component_type: GENERATOR
attribute_name: sign
display_name: Power Sign
data_type: float
unit: n/a
default_value: 1
allowed_storage_types: static
group_name: power_limits
description:
Power flow direction convention: 1 for generation (positive power flows into the network), -1 for consumption (positive power flows out of the network).


component_type: GENERATOR
attribute_name: carrier
display_name: Carrier
data_type: string
unit: n/a
default_value: n/a
allowed_storage_types: static
group_name: basic
description:
Prime mover Carrier (e.g. coal, gas, wind, solar); required for global constraints on primary energy in optimization


component_type: GENERATOR
attribute_name: marginal_cost
display_name: Marginal Cost
data_type: float
unit: currency/MWh
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: costs
description:
The variable cost of producing one additional MWh of electricity. Used by the optimizer to determine the economic dispatch order of generators (lower cost generators are dispatched first).


component_type: GENERATOR
attribute_name: marginal_cost_quadratic
display_name: Quadratic Marginal Cost
data_type: float
unit: currency/MWh
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: costs
description:
Quadratic term for non-linear cost curves. When set, the total cost includes a quadratic component that increases with the square of output, modeling increasing marginal costs at higher generation levels.


component_type: GENERATOR
attribute_name: capital_cost
display_name: Capital Cost
data_type: float
unit: currency/MW
default_value: 0
allowed_storage_types: static
group_name: costs
description:
The cost per MW of adding new capacity. Includes investment costs (spread over the planning period) and fixed operations & maintenance costs. Only relevant when extendable capacity (p_nom_extendable) is True.


component_type: GENERATOR
attribute_name: active
display_name: Active
data_type: boolean
unit: n/a
default_value: True
allowed_storage_types: static
group_name: basic
description:
Whether this generator is active and should be included in network calculations. Set to False to temporarily disable the generator without deleting it.


component_type: GENERATOR
attribute_name: build_year
display_name: Build Year
data_type: int
unit: year
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The year when the generator can be built or commissioned. Essential for multi-year capacity expansion planning models, which determine optimal investment timing and generator retirement schedules.


component_type: GENERATOR
attribute_name: lifetime
display_name: Lifetime
data_type: float
unit: years
default_value: inf
allowed_storage_types: static
group_name: capacity
description:
The operational lifetime of the generator in years. Essential for multi-year capacity expansion planning models, which use this to determine when generators retire (build year (build_year) + lifetime). Set to "inf" for generators that never retire.


component_type: GENERATOR
attribute_name: efficiency
display_name: Efficiency
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static_or_timeseries
group_name: energy
description:
Ratio between primary energy and electrical energy, e.g. takes value 0.4 MWh_elec/MWh_thermal for gas. This is required for global constraints on primary energy in optimization.


component_type: GENERATOR
attribute_name: committable
display_name: Committable
data_type: boolean
unit: n/a
default_value: False
allowed_storage_types: static
group_name: unit_commitment
description:
Enable unit commitment, allowing the generator to be turned on or off with associated start-up and shutdown costs. Only available when the nominal power (p_nom) is not extendable.


component_type: GENERATOR
attribute_name: up_time_before
display_name: Up Time Before
data_type: int
unit: snapshots
default_value: 1
allowed_storage_types: static
group_name: unit_commitment
description:
Number of snapshots that the generator was online before network.snapshots start. Only read if committable (committable) is True and min up time (min_up_time) is non-zero.


component_type: GENERATOR
attribute_name: down_time_before
display_name: Down Time Before
data_type: int
unit: snapshots
default_value: 0
allowed_storage_types: static
group_name: unit_commitment
description:
Number of snapshots that the generator was offline before network.snapshots start. Only read if committable (committable) is True and min down time (min_down_time) is non-zero.


component_type: GENERATOR
attribute_name: ramp_limit_up
display_name: Ramp Up Limit
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static_or_timeseries
group_name: ramping
description:
Maximum active power increase from one snapshot to the next, per unit of the nominal power (p_nom). Ignored if 1.


component_type: GENERATOR
attribute_name: ramp_limit_down
display_name: Ramp Down Limit
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static_or_timeseries
group_name: ramping
description:
Maximum active power decrease from one snapshot to the next, per unit of the nominal power (p_nom). Ignored if 1.


component_type: GENERATOR
attribute_name: ramp_limit_start_up
display_name: Ramp Up at Start
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static
group_name: ramping
description:
Maximum active power increase at start up, per unit of the nominal power (p_nom). Only read if committable (committable) is True.


component_type: GENERATOR
attribute_name: ramp_limit_shut_down
display_name: Ramp Down at Shutdown
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static
group_name: ramping
description:
Maximum active power decrease at shut down, per unit of the nominal power (p_nom). Only read if committable (committable) is True.


component_type: GENERATOR
attribute_name: weight
display_name: Weight
data_type: float
unit: n/a
default_value: 1
allowed_storage_types: static
group_name: basic
description:
Weighting factor used when aggregating or clustering multiple generators into representative units. Higher weights indicate generators that should be prioritized in clustering algorithms.


component_type: LOAD
attribute_name: carrier
display_name: Carrier
data_type: string
unit: n/a
default_value: n/a
allowed_storage_types: static
group_name: basic
description:
Carrier type for the load: "AC" or "DC" for electrical loads, or "heat" or "gas" for thermal loads. Used for categorization and energy balance constraints.


component_type: LOAD
attribute_name: p_set
display_name: Active Power Demand
data_type: float
unit: MW
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
The active power demand of the load in MW. This is the real power that the load consumes from the network. Can be static or time-varying.


component_type: LOAD
attribute_name: q_set
display_name: Reactive Power Demand
data_type: float
unit: MVar
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
The reactive power demand of the load in MVar. Positive values indicate inductive loads (lagging power factor), negative values indicate capacitive loads (leading power factor). Can be static or time-varying.


component_type: LOAD
attribute_name: sign
display_name: Power Sign
data_type: float
unit: n/a
default_value: -1
allowed_storage_types: static
group_name: power_limits
description:
Power flow direction convention: -1 for loads (positive power flows out of the network), 1 for generation (positive power flows into the network). Typically -1 for loads.


component_type: LOAD
attribute_name: active
display_name: Active
data_type: boolean
unit: n/a
default_value: True
allowed_storage_types: static
group_name: basic
description:
Whether this load is active and should be included in network calculations. Set to False to temporarily disable the load without deleting it.


component_type: LINE
attribute_name: type
display_name: Type
data_type: string
unit: n/a
allowed_storage_types: static
group_name: basic
description:
Name of a predefined line standard type. If set, the line standard impedance parameters are automatically calculated from the line length (length) and number of parallel lines (num_parallel), overriding any manually set values for series reactance (x), series resistance (r), and shunt susceptance (b). Leave empty to manually specify impedance parameters.


component_type: LINE
attribute_name: x
display_name: Series Reactance
data_type: float
unit: Ohm
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
The series reactance of the line in Ohms. Must be non-zero for AC lines in power flow calculations. If the line has series inductance L in Henries, then x = 2πfL where f is the frequency in Hertz. The series impedance is z = r + jx. Ignored if line type (type) is set.


component_type: LINE
attribute_name: r
display_name: Series Resistance
data_type: float
unit: Ohm
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
The series resistance of the line in Ohms. Must be non-zero for DC lines in power flow calculations. The series impedance is z = r + jx. Ignored if line type (type) is set.


component_type: LINE
attribute_name: g
display_name: Shunt Conductance
data_type: float
unit: Siemens
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
The shunt conductance of the line in Siemens. The shunt admittance is y = g + jb, where b is the shunt susceptance (b).


component_type: LINE
attribute_name: b
display_name: Shunt Susceptance
data_type: float
unit: Siemens
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
The shunt susceptance of the line in Siemens. If the line has shunt capacitance C in Farads, then b = 2πfC where f is the frequency in Hertz. The shunt admittance is y = g + jb, where g is the shunt conductance (g). Ignored if line type (type) is set.


component_type: LINE
attribute_name: s_nom
display_name: Nominal Apparent Power
data_type: float
unit: MVA
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The maximum apparent power capacity of the line in MVA. This sets the thermal limit for power flow through the line.


component_type: LINE
attribute_name: s_nom_mod
display_name: Nominal Power Module
data_type: float
unit: MVA
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The unit size for capacity expansion. When extending the nominal apparent power (s_nom), it can only be increased in multiples of this module size.


component_type: LINE
attribute_name: s_nom_max
display_name: Max Nominal Power
data_type: float
unit: MVA
default_value: inf
allowed_storage_types: static
group_name: capacity
description:
If the nominal apparent power (s_nom) is extendable in optimization, set its maximum value (e.g. limited by technical potential or right-of-way constraints).


component_type: LINE
attribute_name: s_max_pu
display_name: Max Power Factor
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
The maximum allowed absolute flow per unit of the nominal apparent power (s_nom). Can be set less than 1 to account for security margins (e.g., n-1 contingency), or can be time-varying to represent weather-dependent dynamic line rating for overhead lines.


component_type: LINE
attribute_name: capital_cost
display_name: Capital Cost
data_type: float
unit: currency/MVA
default_value: 0
allowed_storage_types: static
group_name: costs
description:
The cost per MVA of adding new line capacity. Includes investment costs (spread over the planning period) and fixed operations & maintenance costs. Only relevant when extendable capacity (s_nom_extendable) is True.


component_type: LINE
attribute_name: active
display_name: Active
data_type: boolean
unit: n/a
default_value: True
allowed_storage_types: static
group_name: basic
description:
Whether this line is active and should be included in network calculations. Set to False to temporarily disable the line without deleting it.


component_type: LINE
attribute_name: build_year
display_name: Build Year
data_type: int
unit: year
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The year when the line can be built or commissioned. Essential for multi-year capacity expansion planning models, which determine optimal investment timing and line retirement schedules.


component_type: LINE
attribute_name: lifetime
display_name: Lifetime
data_type: float
unit: years
default_value: inf
allowed_storage_types: static
group_name: capacity
description:
The operational lifetime of the line in years. Essential for multi-year capacity expansion planning models, which use this to determine when lines retire (build year (build_year) + lifetime). Set to "inf" for lines that never retire.


component_type: LINE
attribute_name: length
display_name: Line Length
data_type: float
unit: km
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
The physical length of the line in kilometers. Required when line type (type) is set to calculate impedance parameters automatically. Also used for calculating capital costs.


component_type: LINE
attribute_name: carrier
display_name: Carrier
data_type: string
unit: n/a
allowed_storage_types: static
group_name: basic
description:
Carrier type for the line. Must be "AC" (alternating current) as lines only support AC transmission.


component_type: LINE
attribute_name: terrain_factor
display_name: Terrain Factor
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static
group_name: electrical
description:
Multiplier for capital cost to account for difficult terrain. Values greater than 1 increase the capital cost (capital_cost) to reflect higher construction costs in challenging terrain (e.g., mountains, water crossings).


component_type: LINE
attribute_name: num_parallel
display_name: Number of Parallel Lines
data_type: float
unit: n/a
default_value: 1
allowed_storage_types: static
group_name: electrical
description:
The number of parallel transmission circuits (can be fractional). When line type (type) is set, this is used to calculate the total impedance (more parallel lines reduce effective impedance). If line type (type) is empty, this value is ignored.


component_type: LINE
attribute_name: v_ang_min
display_name: Min Voltage Angle Diff
data_type: float
unit: Degrees
default_value: -inf
allowed_storage_types: static
group_name: electrical
description:
Minimum voltage angle difference across the line in degrees. This is a placeholder attribute and is not currently used by any functions.


component_type: LINE
attribute_name: v_ang_max
display_name: Max Voltage Angle Diff
data_type: float
unit: Degrees
default_value: inf
allowed_storage_types: static
group_name: electrical
description:
Maximum voltage angle difference across the line in degrees. This is a placeholder attribute and is not currently used by any functions.


component_type: LINE
attribute_name: x_pu
display_name: Per Unit Reactance
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
Per unit series reactance calculated from the series reactance (x) and the nominal voltage (v_nom) of the connected buses.


component_type: LINE
attribute_name: r_pu
display_name: Per Unit Resistance
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
Per unit series resistance calculated from the series resistance (r) and the nominal voltage (v_nom) of the connected buses.


component_type: LINE
attribute_name: g_pu
display_name: Per Unit Conductance
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
Per unit shunt conductance calculated from the shunt conductance (g) and the nominal voltage (v_nom) of the connected buses.


component_type: LINE
attribute_name: b_pu
display_name: Per Unit Susceptance
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
Per unit shunt susceptance calculated from the shunt susceptance (b) and the nominal voltage (v_nom) of the connected buses.


component_type: LINK
attribute_name: carrier
display_name: Carrier
data_type: string
unit: n/a
allowed_storage_types: static
group_name: basic
description:
Carrier type transported by the link: "DC" for electrical HVDC links, or "heat" or "gas" for thermal links. Used for categorization and energy balance constraints.


component_type: LINK
attribute_name: efficiency
display_name: Transfer Efficiency
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static_or_timeseries
group_name: energy
description:
The efficiency of power transfer from bus0 to bus1. A value of 1.0 means no losses, while lower values represent transmission losses. Can be time-varying to model temperature-dependent performance (e.g., heat pump Coefficient of Performance).


component_type: LINK
attribute_name: active
display_name: Active
data_type: boolean
unit: n/a
default_value: True
allowed_storage_types: static
group_name: basic
description:
Whether this link is active and should be included in network calculations. Set to False to temporarily disable the link without deleting it.


component_type: LINK
attribute_name: build_year
display_name: Build Year
data_type: int
unit: year
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The year when the link can be built or commissioned. Essential for multi-year capacity expansion planning models, which determine optimal investment timing and link retirement schedules.


component_type: LINK
attribute_name: lifetime
display_name: Lifetime
data_type: float
unit: years
default_value: inf
allowed_storage_types: static
group_name: capacity
description:
The operational lifetime of the link in years. Essential for multi-year capacity expansion planning models, which use this to determine when links retire (build year (build_year) + lifetime). Set to "inf" for links that never retire.


component_type: LINK
attribute_name: p_nom
display_name: Nominal Power
data_type: float
unit: MW
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The maximum active power capacity of the link in MW. This sets the limit for power flow through the link.


component_type: LINK
attribute_name: p_nom_max
display_name: Max Nominal Power
data_type: float
unit: MW
default_value: inf
allowed_storage_types: static
group_name: capacity
description:
If the nominal power (p_nom) is extendable in optimization, set its maximum value (e.g. limited by technical potential or right-of-way constraints).


component_type: LINK
attribute_name: p_set
display_name: Power Setpoint
data_type: float
unit: MW
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
Fixed active power flow that the link must transfer from bus0 to bus1. Used when the link power flow is predetermined rather than optimized.


component_type: LINK
attribute_name: p_min_pu
display_name: Min Capacity Factor
data_type: float
unit: per unit of p_nom
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
The minimum power flow per unit of the nominal power (p_nom). Negative values allow reverse flow (from bus1 to bus0). Can be static or time-varying.


component_type: LINK
attribute_name: p_max_pu
display_name: Max Capacity Factor
data_type: float
unit: per unit of p_nom
default_value: 1
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
The maximum power flow per unit of the nominal power (p_nom). Negative values allow reverse flow (from bus1 to bus0). Can be static or time-varying.


component_type: LINK
attribute_name: capital_cost
display_name: Capital Cost
data_type: float
unit: currency/MW
default_value: 0
allowed_storage_types: static
group_name: costs
description:
The cost per MW of adding new link capacity. Includes investment costs (spread over the planning period) and fixed operations & maintenance costs. Only relevant when extendable capacity (p_nom_extendable) is True.


component_type: LINK
attribute_name: marginal_cost
display_name: Marginal Cost
data_type: float
unit: currency/MWh
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: costs
description:
The variable cost of transferring 1 MWh from bus0 to bus1 (before efficiency losses). Used by the optimizer to determine economic dispatch. Only meaningful if the max capacity factor (p_max_pu) >= 0 (unidirectional flow).


component_type: LINK
attribute_name: marginal_cost_quadratic
display_name: Quadratic Marginal Cost
data_type: float
unit: currency/MWh
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: costs
description:
Quadratic term for non-linear cost curves. When set, the total cost includes a quadratic component that increases with the square of power flow, modeling increasing marginal costs at higher transfer levels.


component_type: LINK
attribute_name: length
display_name: Link Length
data_type: float
unit: km
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
The physical length of the link in kilometers. Used for calculating capital costs, especially for transmission lines or pipelines.


component_type: LINK
attribute_name: committable
display_name: Committable
data_type: boolean
unit: n/a
default_value: False
allowed_storage_types: static
group_name: unit_commitment
description:
Enable unit commitment, allowing the link to be turned on or off with associated start-up and shutdown costs. Only available when the nominal power (p_nom) is not extendable.


component_type: LINK
attribute_name: up_time_before
display_name: Up Time Before
data_type: int
unit: snapshots
default_value: 1
allowed_storage_types: static
group_name: unit_commitment
description:
Number of snapshots that the link was online before network.snapshots start. Only read if committable (committable) is True and min up time (min_up_time) is non-zero.


component_type: LINK
attribute_name: down_time_before
display_name: Down Time Before
data_type: int
unit: snapshots
default_value: 0
allowed_storage_types: static
group_name: unit_commitment
description:
Number of snapshots that the link was offline before network.snapshots start. Only read if committable (committable) is True and min down time (min_down_time) is non-zero.


component_type: LINK
attribute_name: ramp_limit_up
display_name: Ramp Up Limit
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static_or_timeseries
group_name: ramping
description:
Maximum power flow increase from one snapshot to the next, per unit of the nominal power (p_nom). Ignored if 1.


component_type: LINK
attribute_name: ramp_limit_down
display_name: Ramp Down Limit
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static_or_timeseries
group_name: ramping
description:
Maximum power flow decrease from one snapshot to the next, per unit of the nominal power (p_nom). Ignored if 1.


component_type: LINK
attribute_name: ramp_limit_start_up
display_name: Ramp Up at Start
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static
group_name: ramping
description:
Maximum power flow increase at start up, per unit of the nominal power (p_nom). Only read if committable (committable) is True.


component_type: UNMET_LOAD
attribute_name: p_nom
display_name: Nominal Power
data_type: float
unit: MW
default_value: 10000000
allowed_storage_types: static
group_name: capacity
description:
The maximum rated capacity in MW. For unmet load, this is typically set very high (e.g., 10000000 MW) to allow the optimizer to serve any unmet demand. This sets the upper limit for power output in all calculations.


component_type: UNMET_LOAD
attribute_name: p_min_pu
display_name: Min Capacity Factor
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
The minimum output for each snapshot per unit of the nominal power (p_nom) for the optimization. Note that if committable (committable) is False and the min capacity factor (p_min_pu) > 0, this represents a must-run condition.


component_type: UNMET_LOAD
attribute_name: p_set
display_name: Active Power Setpoint
data_type: float
unit: MW
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
Fixed active power output that the unmet load generator must produce. Used when the output is predetermined rather than optimized.


component_type: UNMET_LOAD
attribute_name: q_set
display_name: Reactive Power Setpoint
data_type: float
unit: MVar
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
Fixed reactive power output that the unmet load generator must produce. Used when the reactive power output is predetermined rather than optimized.


component_type: UNMET_LOAD
attribute_name: marginal_cost
display_name: Marginal Cost (Penalty)
data_type: float
unit: currency/MWh
default_value: 100000000
allowed_storage_types: static_or_timeseries
group_name: costs
description:
The variable cost of producing one additional MWh of electricity. For unmet load, this is typically set very high (e.g., 100000000 currency/MWh) as a penalty cost to discourage the optimizer from using this generator unless absolutely necessary. Used by the optimizer to determine the economic dispatch order (lower cost generators are dispatched first).


component_type: UNMET_LOAD
attribute_name: build_year
display_name: Build Year
data_type: int
unit: year
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The year when the unmet load generator can be built or commissioned. Essential for multi-year capacity expansion planning models, which determine optimal investment timing and generator retirement schedules.


component_type: UNMET_LOAD
attribute_name: lifetime
display_name: Lifetime
data_type: float
unit: years
default_value: inf
allowed_storage_types: static
group_name: capacity
description:
The operational lifetime of the unmet load generator in years. Essential for multi-year capacity expansion planning models, which use this to determine when generators retire (build year (build_year) + lifetime). Set to "inf" for generators that never retire.


component_type: UNMET_LOAD
attribute_name: committable
display_name: Committable
data_type: boolean
unit: n/a
default_value: False
allowed_storage_types: static
group_name: unit_commitment
description:
Enable unit commitment, allowing the unmet load generator to be turned on or off with associated start-up and shutdown costs. Only available when the nominal power (p_nom) is not extendable.


component_type: UNMET_LOAD
attribute_name: up_time_before
display_name: Up Time Before
data_type: int
unit: snapshots
default_value: 1
allowed_storage_types: static
group_name: unit_commitment
description:
Number of snapshots that the unmet load generator was online before network.snapshots start. Only read if committable (committable) is True and min up time (min_up_time) is non-zero.


component_type: UNMET_LOAD
attribute_name: down_time_before
display_name: Down Time Before
data_type: int
unit: snapshots
default_value: 0
allowed_storage_types: static
group_name: unit_commitment
description:
Number of snapshots that the unmet load generator was offline before network.snapshots start. Only read if committable (committable) is True and min down time (min_down_time) is non-zero.


component_type: UNMET_LOAD
attribute_name: active
display_name: Active
data_type: boolean
unit: n/a
default_value: True
allowed_storage_types: static
group_name: basic
description:
Whether this unmet load generator is active and should be included in network calculations. Set to False to temporarily disable the generator without deleting it.


component_type: STORAGE_UNIT
attribute_name: p_nom
display_name: Nominal Power
data_type: float
unit: MW
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The maximum rated power capacity of the storage unit in MW. This sets the limit for both charging (negative power) and discharging (positive power) in all calculations.


component_type: STORAGE_UNIT
attribute_name: p_min_pu
display_name: Min Capacity Factor
data_type: float
unit: per unit
default_value: -1
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
The minimum power flow per unit of the nominal power (p_nom). Negative values represent charging (withdrawing power from the bus), positive values represent discharging. Can be static or time-varying.


component_type: STORAGE_UNIT
attribute_name: p_max_pu
display_name: Max Capacity Factor
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
The maximum power flow per unit of the nominal power (p_nom). Positive values represent discharging (injecting power into the bus), negative values represent charging. Can be static or time-varying.


component_type: STORAGE_UNIT
attribute_name: p_set
display_name: Active Power Setpoint
data_type: float
unit: MW
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
Fixed active power output that the storage unit must produce (positive for discharging, negative for charging). Used when the power output is predetermined rather than optimized.


component_type: STORAGE_UNIT
attribute_name: q_set
display_name: Reactive Power Setpoint
data_type: float
unit: MVar
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
Fixed reactive power output that the storage unit must produce. Used when the reactive power output is predetermined rather than optimized.


component_type: STORAGE_UNIT
attribute_name: sign
display_name: Power Sign
data_type: float
unit: n/a
default_value: 1
allowed_storage_types: static
group_name: power_limits
description:
Power flow direction convention: 1 for generation/discharging (positive power flows into the network), -1 for consumption/charging (positive power flows out of the network).


component_type: STORAGE_UNIT
attribute_name: carrier
display_name: Carrier
data_type: string
unit: n/a
default_value: n/a
allowed_storage_types: static
group_name: basic
description:
Carrier type for the storage unit (e.g. battery, hydro, hydrogen); required for global constraints on primary energy in optimization


component_type: STORAGE_UNIT
attribute_name: spill_cost
display_name: Spill Cost
data_type: float
unit: currency/MWh
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: costs
description:
The cost of spilling 1 MWh of energy that cannot be stored (e.g., water spillage from a hydro reservoir when the reservoir is full).


component_type: STORAGE_UNIT
attribute_name: marginal_cost
display_name: Marginal Cost
data_type: float
unit: currency/MWh
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: costs
description:
The variable cost of discharging one additional MWh of electricity. Used by the optimizer to determine the economic dispatch order (lower cost storage units are dispatched first).


component_type: STORAGE_UNIT
attribute_name: marginal_cost_quadratic
display_name: Quadratic Marginal Cost
data_type: float
unit: currency/MWh
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: costs
description:
Quadratic term for non-linear cost curves. When set, the total discharge cost includes a quadratic component that increases with the square of discharge power, modeling increasing marginal costs at higher discharge levels.


component_type: STORAGE_UNIT
attribute_name: marginal_cost_storage
display_name: Storage Marginal Cost
data_type: float
unit: currency/MWh/h
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: costs
description:
The variable cost of storing 1 MWh of energy for one hour. This represents the opportunity cost or wear-and-tear cost associated with storing energy in the storage unit.


component_type: STORAGE_UNIT
attribute_name: capital_cost
display_name: Capital Cost
data_type: float
unit: currency/MW
default_value: 0
allowed_storage_types: static
group_name: costs
description:
The cost per MW of adding new storage capacity. Includes investment costs (spread over the planning period) and fixed operations & maintenance costs. Only relevant when extendable capacity (p_nom_extendable) is True.


component_type: STORAGE_UNIT
attribute_name: active
display_name: Active
data_type: boolean
unit: n/a
default_value: True
allowed_storage_types: static
group_name: basic
description:
Whether this storage unit is active and should be included in network calculations. Set to False to temporarily disable the storage unit without deleting it.


component_type: STORAGE_UNIT
attribute_name: build_year
display_name: Build Year
data_type: int
unit: year
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The year when the storage unit can be built or commissioned. Essential for multi-year capacity expansion planning models, which determine optimal investment timing and storage unit retirement schedules.


component_type: STORAGE_UNIT
attribute_name: lifetime
display_name: Lifetime
data_type: float
unit: years
default_value: inf
allowed_storage_types: static
group_name: capacity
description:
The operational lifetime of the storage unit in years. Essential for multi-year capacity expansion planning models, which use this to determine when storage units retire (build year (build_year) + lifetime). Set to "inf" for storage units that never retire.


component_type: STORAGE_UNIT
attribute_name: state_of_charge_initial
display_name: Initial State of Charge
data_type: float
unit: MWh
default_value: 0
allowed_storage_types: static
group_name: energy
description:
The state of charge (energy stored) at the beginning of the optimization period, before the first snapshot. Ignored if cyclic state of charge (cyclic_state_of_charge) is True.


component_type: STORAGE_UNIT
attribute_name: state_of_charge_initial_per_period
display_name: Initial SOC per Period
data_type: boolean
unit: n/a
default_value: False
allowed_storage_types: static
group_name: energy
description:
If True, the initial state of charge (state_of_charge_initial) is applied at the beginning of each investment period separately, rather than only at the start of the entire optimization horizon.


component_type: STORAGE_UNIT
attribute_name: state_of_charge_set
display_name: State of Charge Setpoint
data_type: float
unit: MWh
default_value: 1
allowed_storage_types: static_or_timeseries
group_name: energy
description:
Fixed state of charge values that the storage unit must maintain at specific snapshots. Used when the state of charge is predetermined rather than optimized. Can be static or time-varying.


component_type: STORAGE_UNIT
attribute_name: cyclic_state_of_charge
display_name: Cyclic State of Charge
data_type: boolean
unit: n/a
default_value: False
allowed_storage_types: static
group_name: energy
description:
If True, the initial state of charge (state_of_charge_initial) is ignored and the storage unit must end with the same state of charge as it started (cyclic constraint). This ensures the storage unit returns to its initial state at the end of the optimization period.


component_type: STORAGE_UNIT
attribute_name: cyclic_state_of_charge_per_period
display_name: Cyclic SOC per Period
data_type: boolean
unit: n/a
default_value: True
allowed_storage_types: static
group_name: energy
description:
If True, the cyclic state of charge constraint (cyclic_state_of_charge) is applied to each investment period separately, rather than only to the entire optimization horizon.


component_type: STORAGE_UNIT
attribute_name: max_hours
display_name: Max Storage Hours
data_type: float
unit: hours
default_value: 1
allowed_storage_types: static
group_name: energy
description:
The maximum energy storage capacity expressed as the number of hours the storage unit can discharge at full nominal power (p_nom). The maximum state of charge in MWh equals max hours (max_hours) × nominal power (p_nom).


component_type: STORAGE_UNIT
attribute_name: efficiency_store
display_name: Storage Efficiency
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static_or_timeseries
group_name: energy
description:
The round-trip efficiency for charging (storing energy). A value of 1.0 means no losses, while lower values represent energy losses during charging. Can be time-varying to model temperature-dependent performance.


component_type: STORAGE_UNIT
attribute_name: efficiency_dispatch
display_name: Dispatch Efficiency
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static_or_timeseries
group_name: energy
description:
The round-trip efficiency for discharging (releasing stored energy). A value of 1.0 means no losses, while lower values represent energy losses during discharging. Can be time-varying to model temperature-dependent performance.


component_type: STORAGE_UNIT
attribute_name: standing_loss
display_name: Standing Loss
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: energy
description:
The self-discharge rate per hour, expressed as a fraction of the current state of charge. Represents energy losses that occur even when the storage unit is idle (e.g., battery self-discharge, reservoir evaporation). Can be time-varying.


component_type: STORAGE_UNIT
attribute_name: inflow
display_name: Inflow
data_type: float
unit: MW
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: energy
description:
Natural inflow of energy to the state of charge (e.g., river inflow to a hydro reservoir, solar charging for a battery). Positive values increase the stored energy without drawing power from the bus. Can be static or time-varying.


component_type: STORE
attribute_name: carrier
display_name: Carrier
data_type: string
unit: n/a
allowed_storage_types: static
group_name: basic
description:
Carrier type for the store (e.g. heat, gas, hydrogen). Used for categorization and energy balance constraints.


component_type: STORE
attribute_name: e_nom
display_name: Nominal Energy Capacity
data_type: float
unit: MWh
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The maximum energy storage capacity of the store in MWh. This sets the upper limit for the amount of energy that can be stored.


component_type: STORE
attribute_name: e_nom_mod
display_name: Nominal Energy Module
data_type: float
unit: MWh
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The unit size for capacity expansion. When extending the nominal energy capacity (e_nom), it can only be increased in multiples of this module size.


component_type: STORE
attribute_name: e_nom_max
display_name: Max Energy Capacity
data_type: float
unit: MWh
default_value: inf
allowed_storage_types: static
group_name: capacity
description:
If the nominal energy capacity (e_nom) is extendable in optimization, set its maximum value (e.g. limited by technical potential).


component_type: STORE
attribute_name: e_min_pu
display_name: Min Energy Factor
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: energy
description:
The minimum stored energy per unit of the nominal energy capacity (e_nom). Can be static or time-varying.


component_type: STORE
attribute_name: e_max_pu
display_name: Max Energy Factor
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static_or_timeseries
group_name: energy
description:
The maximum stored energy per unit of the nominal energy capacity (e_nom). Can be static or time-varying.


component_type: STORE
attribute_name: e_initial
display_name: Initial Energy
data_type: float
unit: MWh
default_value: 0
allowed_storage_types: static
group_name: energy
description:
The energy stored at the beginning of the optimization period, before the first snapshot. Ignored if cyclic energy (e_cyclic) is True.


component_type: STORE
attribute_name: e_initial_per_period
display_name: Initial Energy per Period
data_type: boolean
unit: n/a
default_value: False
allowed_storage_types: static
group_name: energy
description:
If True, the initial energy (e_initial) is applied at the beginning of each investment period separately, rather than only at the start of the entire optimization horizon.


component_type: STORE
attribute_name: e_cyclic
display_name: Cyclic Energy
data_type: boolean
unit: n/a
default_value: False
allowed_storage_types: static
group_name: energy
description:
If True, the initial energy (e_initial) is ignored and the store must end with the same energy as it started (cyclic constraint). This ensures the store returns to its initial state at the end of the optimization period.


component_type: STORE
attribute_name: e_cyclic_per_period
display_name: Cyclic Energy per Period
data_type: boolean
unit: n/a
default_value: True
allowed_storage_types: static
group_name: energy
description:
If True, the cyclic energy constraint (e_cyclic) is applied to each investment period separately, rather than only to the entire optimization horizon.


component_type: STORE
attribute_name: p_set
display_name: Active Power Setpoint
data_type: float
unit: MW
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
Fixed active power flow that the store must maintain (positive for withdrawing energy from the bus, negative for injecting energy into the bus). Used when the power flow is predetermined rather than optimized.


component_type: STORE
attribute_name: q_set
display_name: Reactive Power Setpoint
data_type: float
unit: MVar
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
Fixed reactive power flow that the store must maintain. Used when the reactive power flow is predetermined rather than optimized.


component_type: STORE
attribute_name: marginal_cost
display_name: Marginal Cost
data_type: float
unit: currency/MWh
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: costs
description:
The variable cost applied to both charging and discharging 1 MWh of energy. Used by the optimizer to determine the economic dispatch order.


component_type: STORE
attribute_name: marginal_cost_quadratic
display_name: Quadratic Marginal Cost
data_type: float
unit: currency/MWh
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: costs
description:
Quadratic term for non-linear cost curves. When set, the total cost includes a quadratic component that increases with the square of energy flow, modeling increasing marginal costs at higher flow levels.


component_type: STORE
attribute_name: marginal_cost_storage
display_name: Storage Marginal Cost
data_type: float
unit: currency/MWh/h
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: costs
description:
The variable cost of storing 1 MWh of energy for one hour. This represents the opportunity cost or wear-and-tear cost associated with storing energy in the store.


component_type: STORE
attribute_name: capital_cost
display_name: Capital Cost
data_type: float
unit: currency/MWh
default_value: 0
allowed_storage_types: static
group_name: costs
description:
The cost per MWh of adding new storage capacity. Includes investment costs (spread over the planning period) and fixed operations & maintenance costs. Only relevant when extendable capacity (e_nom_extendable) is True.


component_type: STORE
attribute_name: standing_loss
display_name: Standing Loss
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static_or_timeseries
group_name: energy
description:
The self-discharge rate per hour, expressed as a fraction of the current stored energy. Represents energy losses that occur even when the store is idle (e.g., thermal losses, leakage). Can be time-varying.


component_type: STORE
attribute_name: active
display_name: Active
data_type: boolean
unit: n/a
default_value: True
allowed_storage_types: static
group_name: basic
description:
Whether this store is active and should be included in network calculations. Set to False to temporarily disable the store without deleting it.


component_type: STORE
attribute_name: build_year
display_name: Build Year
data_type: int
unit: year
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The year when the store can be built or commissioned. Essential for multi-year capacity expansion planning models, which determine optimal investment timing and store retirement schedules.


component_type: STORE
attribute_name: lifetime
display_name: Lifetime
data_type: float
unit: years
default_value: inf
allowed_storage_types: static
group_name: capacity
description:
The operational lifetime of the store in years. Essential for multi-year capacity expansion planning models, which use this to determine when stores retire (build year (build_year) + lifetime). Set to "inf" for stores that never retire.


component_type: TRANSFORMER
attribute_name: type
display_name: Type
data_type: string
unit: n/a
default_value: n/a
allowed_storage_types: static
group_name: basic
description:
Name of a predefined transformer standard type. If set, the transformer type impedance parameters are automatically calculated, overriding any manually set values for series reactance (x), series resistance (r), shunt susceptance (b), nominal apparent power (s_nom), tap ratio (tap_ratio), tap side (tap_side), and phase shift (phase_shift). Leave empty to manually specify impedance parameters.


component_type: TRANSFORMER
attribute_name: model
display_name: Transformer Model
data_type: string
unit: n/a
default_value: t
allowed_storage_types: static
group_name: basic
description:
Model used for admittance matrix: "t" or "pi". Defaults to "t" following physics and DIgSILENT PowerFactory conventions.


component_type: TRANSFORMER
attribute_name: x
display_name: Series Reactance
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
The series reactance in per unit (using nominal apparent power (s_nom) as base power). Must be non-zero for AC transformers in linear power flow. The series impedance is z = r + jx. Ignored if transformer type (type) is set.


component_type: TRANSFORMER
attribute_name: r
display_name: Series Resistance
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
The series resistance in per unit (using nominal apparent power (s_nom) as base power). Must be non-zero for DC transformers in linear power flow. The series impedance is z = r + jx. Ignored if transformer type (type) is set.


component_type: TRANSFORMER
attribute_name: g
display_name: Shunt Conductance
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
The shunt conductance in per unit (using nominal apparent power (s_nom) as base power). The shunt admittance is y = g + jb, where b is the shunt susceptance (b). Ignored if transformer type (type) is set.


component_type: TRANSFORMER
attribute_name: b
display_name: Shunt Susceptance
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
The shunt susceptance in per unit (using nominal apparent power (s_nom) as base power). The shunt admittance is y = g + jb, where g is the shunt conductance (g). Ignored if transformer type (type) is set.


component_type: TRANSFORMER
attribute_name: s_nom
display_name: Nominal Apparent Power
data_type: float
unit: MVA
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The maximum apparent power capacity of the transformer in MVA. This sets the limit for power flow through the transformer in either direction. Ignored if extendable capacity (s_nom_extendable) is True.


component_type: TRANSFORMER
attribute_name: s_nom_mod
display_name: Nominal Apparent Power Module
data_type: float
unit: MVA
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The unit size for capacity expansion. When extending the nominal apparent power (s_nom), it can only be increased in multiples of this module size. Introduces integer variables in optimization.


component_type: TRANSFORMER
attribute_name: s_nom_max
display_name: Max Nominal Apparent Power
data_type: float
unit: MVA
default_value: inf
allowed_storage_types: static
group_name: capacity
description:
If the nominal apparent power (s_nom) is extendable in optimization, set its maximum value (e.g. limited by technical potential).


component_type: TRANSFORMER
attribute_name: s_nom_set
display_name: Nominal Apparent Power Setpoint
data_type: float
unit: MVA
default_value: n/a
allowed_storage_types: static
group_name: capacity
description:
If the nominal apparent power (s_nom) is extendable in optimization, set the value of the optimized nominal apparent power (s_nom_opt).


component_type: TRANSFORMER
attribute_name: s_max_pu
display_name: Max Capacity Factor
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static_or_timeseries
group_name: power_limits
description:
The maximum allowed absolute flow per unit of the nominal apparent power (s_nom). Can be set less than 1 to account for security margins (e.g., n-1 contingency), or can be time-varying to represent weather-dependent dynamic rating.


component_type: TRANSFORMER
attribute_name: capital_cost
display_name: Capital Cost
data_type: float
unit: currency/MVA
default_value: 0
allowed_storage_types: static
group_name: costs
description:
The cost per MVA of adding new transformer capacity. Includes investment costs (spread over the planning period) and fixed operations & maintenance costs. Only relevant when extendable capacity (s_nom_extendable) is True.


component_type: TRANSFORMER
attribute_name: num_parallel
display_name: Number of Parallel Transformers
data_type: float
unit: n/a
default_value: 1
allowed_storage_types: static
group_name: electrical
description:
The number of parallel transformers (can be fractional). When transformer type (type) is set, this is used to calculate the total impedance (more parallel transformers reduce effective impedance). If transformer type (type) is empty, this value is ignored.


component_type: TRANSFORMER
attribute_name: tap_ratio
display_name: Tap Ratio
data_type: float
unit: per unit
default_value: 1
allowed_storage_types: static
group_name: electrical
description:
Ratio of per unit voltages at each bus for tap changer. A value of 1.0 means no voltage transformation. Ignored if transformer type (type) is set.


component_type: TRANSFORMER
attribute_name: tap_side
display_name: Tap Side
data_type: int
unit: n/a
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
Defines if the tap changer is modeled at the primary side (bus0, usually high-voltage, value 0) or the secondary side (bus1, usually low-voltage, value 1). Must be 0 or 1. Ignored if transformer type (type) is set.


component_type: TRANSFORMER
attribute_name: tap_position
display_name: Tap Position
data_type: int
unit: n/a
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
If the transformer has a transformer type (type), determines the tap position relative to the neutral tap position.


component_type: TRANSFORMER
attribute_name: phase_shift
display_name: Phase Shift
data_type: float
unit: Degrees
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
Voltage phase angle shift in degrees. Used to model phase-shifting transformers. Ignored if transformer type (type) is set.


component_type: TRANSFORMER
attribute_name: active
display_name: Active
data_type: boolean
unit: n/a
default_value: True
allowed_storage_types: static
group_name: basic
description:
Whether this transformer is active and should be included in network calculations. Set to False to temporarily disable the transformer without deleting it.


component_type: TRANSFORMER
attribute_name: build_year
display_name: Build Year
data_type: int
unit: year
default_value: 0
allowed_storage_types: static
group_name: capacity
description:
The year when the transformer can be built or commissioned. Essential for multi-year capacity expansion planning models, which determine optimal investment timing and transformer retirement schedules.


component_type: TRANSFORMER
attribute_name: lifetime
display_name: Lifetime
data_type: float
unit: years
default_value: inf
allowed_storage_types: static
group_name: capacity
description:
The operational lifetime of the transformer in years. Essential for multi-year capacity expansion planning models, which use this to determine when transformers retire (build year (build_year) + lifetime). Set to "inf" for transformers that never retire.


component_type: TRANSFORMER
attribute_name: v_ang_min
display_name: Min Voltage Angle Difference
data_type: float
unit: Degrees
default_value: -inf
allowed_storage_types: static
group_name: electrical
description:
Minimum voltage angle difference across the transformer in degrees. This is a placeholder attribute and is not currently used by any functions.


component_type: TRANSFORMER
attribute_name: v_ang_max
display_name: Max Voltage Angle Difference
data_type: float
unit: Degrees
default_value: inf
allowed_storage_types: static
group_name: electrical
description:
Maximum voltage angle difference across the transformer in degrees. This is a placeholder attribute and is not currently used by any functions.


component_type: TRANSFORMER
attribute_name: sub_network
display_name: Sub Network
data_type: string
unit: n/a
default_value: n/a
allowed_storage_types: static
group_name: basic
description:
Name of connected sub-network to which transformer belongs, as calculated by network topology analysis. Do not set manually.


component_type: TRANSFORMER
attribute_name: x_pu_eff
display_name: Effective Per Unit Series Reactance
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
Effective per unit series reactance for linear power flow, calculated from the series reactance (x), tap ratio (tap_ratio), and the nominal voltage (v_nom) of the connected buses.


component_type: TRANSFORMER
attribute_name: r_pu_eff
display_name: Effective Per Unit Series Resistance
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
Effective per unit series resistance for linear power flow, calculated from the series resistance (r), tap ratio (tap_ratio), and the nominal voltage (v_nom) of the connected buses.


component_type: SHUNT_IMPEDANCE
attribute_name: g
display_name: Shunt Conductance
data_type: float
unit: Siemens
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
The shunt conductance in Siemens. Positive values withdraw active power from the bus. The shunt admittance is y = g + jb, where b is the shunt susceptance (b).


component_type: SHUNT_IMPEDANCE
attribute_name: b
display_name: Shunt Susceptance
data_type: float
unit: Siemens
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
The shunt susceptance in Siemens. Positive values withdraw reactive power from the bus (inductive). The shunt admittance is y = g + jb, where g is the shunt conductance (g).


component_type: SHUNT_IMPEDANCE
attribute_name: sign
display_name: Power Sign
data_type: float
unit: n/a
default_value: -1
allowed_storage_types: static
group_name: power_limits
description:
Power flow direction convention: -1 means positive conductance (g) withdraws active power (p) from the bus, 1 means positive conductance (g) injects active power (p) into the bus.


component_type: SHUNT_IMPEDANCE
attribute_name: active
display_name: Active
data_type: boolean
unit: n/a
default_value: True
allowed_storage_types: static
group_name: basic
description:
Whether this shunt impedance is active and should be included in network calculations. Set to False to temporarily disable the shunt impedance without deleting it.


component_type: SHUNT_IMPEDANCE
attribute_name: g_pu
display_name: Per Unit Shunt Conductance
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
Per unit shunt conductance calculated from the shunt conductance (g) and the nominal voltage (v_nom) of the connected bus.


component_type: SHUNT_IMPEDANCE
attribute_name: b_pu
display_name: Per Unit Shunt Susceptance
data_type: float
unit: per unit
default_value: 0
allowed_storage_types: static
group_name: electrical
description:
Per unit shunt susceptance calculated from the shunt susceptance (b) and the nominal voltage (v_nom) of the connected bus.


# component_attributes

attribute_name: constraint_code
storage_type: static
data_type: string
unit: n/a
created_at: 2026-02-03 15:50:02
updated_at: 2026-02-03 15:50:02
static_value:
"# Primary Energy Limit - Limit total CO2 emissions\n# Linearly reduce emissions from 2358382 tCO2 in 2020 to 0 tCO2 in 2024\n\nimport numpy as np\nimport pandas as pd\n\nyears = np.arange(2020, 2025)\nemissions = np.linspace(2358382, 0, len(years))\n\ndf = pd.DataFrame(\n    {\n        'year' : years,\n        'emissions' : emissions\n    }\n)\n\nfor i, row in df.iterrows():\n    n.add(\n        \"GlobalConstraint\",\n        \"co2_limit_\" + str(int(row.year)),\n        type=\"primary_energy\",\n        carrier_attribute=\"co2_emissions\",\n        investment_period=int(row.year),\n        sense=\"<=\",\n        constant=float(row.emissions),\n    )\n\nprint(\"Added CO2 emissions limit constraint: linearly reducing from 2358382 tCO2 (2020) to 0 tCO2 (2024)\")"


# network_solve_results

solved_at: 2026-02-03 15:57:19
solver_name: highs
solve_type: pypsa_optimization
solve_status: optimal
results_json:
{"success": true, "status": "optimal", "solve_time": 432.7315273284912, "objective_value": 36730888147.9864, "solver_name": "highs", "run_id": "596c9164-2e7d-4257-a74f-e8c6fbb90a2e", "network_statistics": {"core_summary": {"total_generation_mwh": 110686821.39521568, "total_demand_mwh": 109920724.269104, "total_cost": 36730888147.9864, "load_factor": 0.9930786961224837, "unserved_energy_mwh": 0.0}, "custom_statistics": {"dispatch_by_carrier": {"AC": 620538.6721504536, "biomass": 79036939.55570002, "gas": 14739887.500000361, "hydro": 16289455.66736484, "Unmet Load": 0.0}, "power_capacity_by_carrier": {"AC": 910.513212924636, "biomass": 2919.1283061402864, "gas": 1327.1452487640815, "hydro": 371.49825915354955, "Unmet Load": 0.0}, "energy_capacity_by_carrier": {"AC": 2213.069542826981, "biomass": 0.0, "gas": 0.0, "hydro": 0.0, "Unmet Load": 0.0}, "emissions_by_carrier": {"AC": 0.0, "biomass": 0.0, "gas": 5895955.000000145, "hydro": 0.0, "Unmet Load": 0.0}, "capital_cost_by_carrier": {"AC": 1608488451.6179476, "biomass": 19718842005.619194, "gas": 5308580995.056326, "hydro": 5572473887.303244, "Unmet Load": 0.0}, "operational_cost_by_carrier": {"AC": 0.0, "biomass": 3556662280.006501, "gas": 884393250.0000217, "hydro": 81447278.3368242, "Unmet Load": 0.0}, "total_system_cost_by_carrier": {"AC": 1608488451.6179476, "biomass": 23275504285.625694, "gas": 6192974245.056347, "hydro": 5653921165.640068, "Unmet Load": 0.0}, "total_capital_cost": 32208385339.59671, "total_operational_cost": 4522502808.343348, "total_currency_cost": 36730888147.940056, "total_emissions_tons_co2": 5895955.000000145, "average_price_per_mwh": 331.84517980500414, "unmet_load_percentage": 0.0, "max_unmet_load_hour_mw": 0.0}, "runtime_info": {"component_count": 39, "bus_count": 2, "generator_count": 34, "load_count": 2, "snapshot_count": 7308}}, "pypsa_result": {}}

metadata_json:
{"solver_name": "highs", "run_id": "596c9164-2e7d-4257-a74f-e8c6fbb90a2e", "multi_period": true, "years": [2020, 2021, 2022, 2023, 2024], "network_name": "Ghana-Togo Capacity Expansion 2020-2024", "num_snapshots": 7308}


# network_solve_results_by_year

metadata_json: {"year": 2020, "scenario_id": null}
created_at: 2026-02-03 15:57:19
results_json:
{"success": true, "year": 2020, "network_statistics": {"core_summary": {"total_generation_mwh": 20821469.179011565, "total_demand_mwh": 20803867.85357666, "total_cost": null, "load_factor": 0.9991546549724913, "unserved_energy_mwh": 0.0}, "custom_statistics": {"unmet_load_percentage": 0.0, "year": 2020, "dispatch_by_carrier": {"AC": 75037.22948563838, "biomass": 11662273.470606722, "gas": 5895955.000000063, "hydro": 3263240.7084047785, "Unmet Load": 0.0}, "capacity_by_carrier": {}, "emissions_by_carrier": {"AC": 0.0, "biomass": 0.0, "gas": 2358382.0000000256, "hydro": 0.0, "Unmet Load": 0.0}, "capital_cost_by_carrier": {"AC": 274476276.64623874, "biomass": 2692217073.5200005, "gas": 1061716199.0112653, "hydro": 1114494777.4606488, "Unmet Load": 0.0}, "operational_cost_by_carrier": {"AC": 0.0, "biomass": 524802306.1773025, "gas": 353757300.0000038, "hydro": 16316203.542023893, "Unmet Load": 0.0}, "total_system_cost_by_carrier": {"AC": 274476276.64623874, "biomass": 3217019379.697303, "gas": 1415473499.011269, "hydro": 1130810981.0026727, "Unmet Load": 0.0}, "power_capacity_by_carrier": {"AC": 517.0014322800464, "biomass": 1346.1085367600003, "gas": 1327.1452487640815, "hydro": 371.49825915354955, "Unmet Load": 0.0}, "energy_capacity_by_carrier": {"AC": 639.0224202486223, "biomass": 0.0, "gas": 0.0, "hydro": 0.0, "Unmet Load": 0.0}}, "runtime_info": {"solve_time_seconds": 432.7315273284912, "year": 2020, "snapshot_count": 1464}, "solver_info": {"solver_name": "highs", "year": 2020}}}


metadata_json: {"year": 2021, "scenario_id": null}
created_at: 2026-02-03 15:57:19
results_json:
{"success": true, "year": 2021, "network_statistics": {"core_summary": {"total_generation_mwh": 21298891.10243424, "total_demand_mwh": 21271958.32269287, "total_cost": null, "load_factor": 0.9987354844149944, "unserved_energy_mwh": 0.0}, "custom_statistics": {"unmet_load_percentage": 0.0, "year": 2021, "dispatch_by_carrier": {"AC": 114818.69258163412, "biomass": 13622600.102249058, "gas": 4421966.250000091, "hydro": 3254324.750185094, "Unmet Load": 0.0}, "capacity_by_carrier": {}, "emissions_by_carrier": {"AC": 0.0, "biomass": 0.0, "gas": 1768786.5000000366, "hydro": 0.0, "Unmet Load": 0.0}, "capital_cost_by_carrier": {"AC": 274476276.64623874, "biomass": 3150093204.792328, "gas": 1061716199.0112653, "hydro": 1114494777.4606488, "Unmet Load": 0.0}, "operational_cost_by_carrier": {"AC": 0.0, "biomass": 613017004.6012076, "gas": 265317975.00000548, "hydro": 16271623.75092547, "Unmet Load": 0.0}, "total_system_cost_by_carrier": {"AC": 274476276.64623874, "biomass": 3763110209.3935356, "gas": 1327034174.0112708, "hydro": 1130766401.2115743, "Unmet Load": 0.0}, "power_capacity_by_carrier": {"AC": 517.0014322800464, "biomass": 1575.0466023961642, "gas": 1327.1452487640815, "hydro": 371.49825915354955, "Unmet Load": 0.0}, "energy_capacity_by_carrier": {"AC": 639.0224202486223, "biomass": 0.0, "gas": 0.0, "hydro": 0.0, "Unmet Load": 0.0}}, "runtime_info": {"solve_time_seconds": 432.7315273284912, "year": 2021, "snapshot_count": 1460}, "solver_info": {"solver_name": "highs", "year": 2021}}}


metadata_json: {"year": 2022, "scenario_id": null}
created_at: 2026-02-03 15:57:19
results_json:
{"success": true, "year": 2022, "network_statistics": {"core_summary": {"total_generation_mwh": 21907937.745247092, "total_demand_mwh": 21868146.39871216, "total_cost": null, "load_factor": 0.998183701861917, "unserved_energy_mwh": 0.0}, "custom_statistics": {"unmet_load_percentage": 0.0, "year": 2022, "dispatch_by_carrier": {"AC": 169636.7931226221, "biomass": 15705635.495061876, "gas": 2947977.500000125, "hydro": 3254324.750185094, "Unmet Load": 0.0}, "capacity_by_carrier": {}, "emissions_by_carrier": {"AC": 0.0, "biomass": 0.0, "gas": 1179191.00000005, "hydro": 0.0, "Unmet Load": 0.0}, "capital_cost_by_carrier": {"AC": 274476276.64623874, "biomass": 3683871241.1658783, "gas": 1061716199.0112653, "hydro": 1114494777.4606488, "Unmet Load": 0.0}, "operational_cost_by_carrier": {"AC": 0.0, "biomass": 706753597.2777845, "gas": 176878650.00000748, "hydro": 16271623.75092547, "Unmet Load": 0.0}, "total_system_cost_by_carrier": {"AC": 274476276.64623874, "biomass": 4390624838.443663, "gas": 1238594849.0112727, "hydro": 1130766401.2115743, "Unmet Load": 0.0}, "power_capacity_by_carrier": {"AC": 517.0014322800464, "biomass": 1841.9356205829392, "gas": 1327.1452487640815, "hydro": 371.49825915354955, "Unmet Load": 0.0}, "energy_capacity_by_carrier": {"AC": 639.0224202486223, "biomass": 0.0, "gas": 0.0, "hydro": 0.0, "Unmet Load": 0.0}}, "runtime_info": {"solve_time_seconds": 432.7315273284912, "year": 2022, "snapshot_count": 1460}, "solver_info": {"solver_name": "highs", "year": 2022}}}


metadata_json: {"year": 2023, "scenario_id": null}
created_at: 2026-02-03 15:57:19
results_json:
{"success": true, "year": 2023, "network_statistics": {"core_summary": {"total_generation_mwh": 22623124.636576, "total_demand_mwh": 22577529.101898193, "total_cost": null, "load_factor": 0.9979845606912722, "unserved_energy_mwh": 0.0}, "custom_statistics": {"unmet_load_percentage": 0.0, "year": 2023, "dispatch_by_carrier": {"AC": 194380.96362644108, "biomass": 17894811.136390824, "gas": 1473988.7500000815, "hydro": 3254324.750185094, "Unmet Load": 0.0}, "capacity_by_carrier": {}, "emissions_by_carrier": {"AC": 0.0, "biomass": 0.0, "gas": 589595.5000000326, "hydro": 0.0, "Unmet Load": 0.0}, "capital_cost_by_carrier": {"AC": 274476276.64623874, "biomass": 4354403873.860415, "gas": 1061716199.0112653, "hydro": 1114494777.4606488, "Unmet Load": 0.0}, "operational_cost_by_carrier": {"AC": 0.0, "biomass": 805266501.1375871, "gas": 88439325.00000489, "hydro": 16271623.75092547, "Unmet Load": 0.0}, "total_system_cost_by_carrier": {"AC": 274476276.64623874, "biomass": 5159670374.998003, "gas": 1150155524.01127, "hydro": 1130766401.2115743, "Unmet Load": 0.0}, "power_capacity_by_carrier": {"AC": 517.0014322800464, "biomass": 2177.201936930208, "gas": 1327.1452487640815, "hydro": 371.49825915354955, "Unmet Load": 0.0}, "energy_capacity_by_carrier": {"AC": 639.0224202486223, "biomass": 0.0, "gas": 0.0, "hydro": 0.0, "Unmet Load": 0.0}}, "runtime_info": {"solve_time_seconds": 432.7315273284912, "year": 2023, "snapshot_count": 1460}, "solver_info": {"solver_name": "highs", "year": 2023}}}


metadata_json: {"year": 2024, "scenario_id": null}
created_at: 2026-02-03 15:57:19
results_json:
{"success": true, "year": 2024, "network_statistics": {"core_summary": {"total_generation_mwh": 23414860.059796322, "total_demand_mwh": 23399222.59222412, "total_cost": null, "load_factor": 0.9993321562660096, "unserved_energy_mwh": 0.0}, "custom_statistics": {"unmet_load_percentage": 0.0, "year": 2024, "dispatch_by_carrier": {"AC": 66664.99333411784, "biomass": 20151619.35139154, "gas": 0.0, "hydro": 3263240.7084047785, "Unmet Load": 0.0}, "capacity_by_carrier": {}, "emissions_by_carrier": {"AC": 0.0, "biomass": 0.0, "gas": 0.0, "hydro": 0.0, "Unmet Load": 0.0}, "capital_cost_by_carrier": {"AC": 510583345.0329925, "biomass": 5838256612.280572, "gas": 1061716199.0112653, "hydro": 1114494777.4606488, "Unmet Load": 0.0}, "operational_cost_by_carrier": {"AC": 0.0, "biomass": 906822870.8126194, "gas": 0.0, "hydro": 16316203.542023893, "Unmet Load": 0.0}, "total_system_cost_by_carrier": {"AC": 510583345.0329925, "biomass": 6745079483.093191, "gas": 1061716199.0112653, "hydro": 1130810981.0026727, "Unmet Load": 0.0}, "power_capacity_by_carrier": {"AC": 910.513212924636, "biomass": 2919.1283061402864, "gas": 1327.1452487640815, "hydro": 371.49825915354955, "Unmet Load": 0.0}, "energy_capacity_by_carrier": {"AC": 2213.069542826981, "biomass": 0.0, "gas": 0.0, "hydro": 0.0, "Unmet Load": 0.0}}, "runtime_info": {"solve_time_seconds": 432.7315273284912, "year": 2024, "snapshot_count": 1464}, "solver_info": {"solver_name": "highs", "year": 2024}}}


