Links `dataclass` ¶

Links(ctype: ComponentType, n: Network | None = None, names: str | int | Sequence[int | str] | None = None, suffix: str = '')

Bases: _Multiport


              flowchart TD
              pypsa.components.Links[Links]
              pypsa.components._types.mixin.multiports._Multiport[_Multiport]
              pypsa.components.components.Components[Components]
              pypsa.components.components.ComponentsData[ComponentsData]
              pypsa.components.descriptors.ComponentsDescriptorsMixin[ComponentsDescriptorsMixin]
              pypsa.components.transform.ComponentsTransformMixin[ComponentsTransformMixin]
              pypsa.components.index.ComponentsIndexMixin[ComponentsIndexMixin]
              pypsa.components.array.ComponentsArrayMixin[ComponentsArrayMixin]
              pypsa.components.abstract._ComponentsABC[_ComponentsABC]

                              pypsa.components._types.mixin.multiports._Multiport --> pypsa.components.Links
                                pypsa.components.components.Components --> pypsa.components._types.mixin.multiports._Multiport
                                pypsa.components.components.ComponentsData --> pypsa.components.components.Components
                
                pypsa.components.descriptors.ComponentsDescriptorsMixin --> pypsa.components.components.Components
                                pypsa.components.abstract._ComponentsABC --> pypsa.components.descriptors.ComponentsDescriptorsMixin
                

                pypsa.components.transform.ComponentsTransformMixin --> pypsa.components.components.Components
                
                pypsa.components.index.ComponentsIndexMixin --> pypsa.components.components.Components
                                pypsa.components.abstract._ComponentsABC --> pypsa.components.index.ComponentsIndexMixin
                

                pypsa.components.array.ComponentsArrayMixin --> pypsa.components.components.Components
                                pypsa.components.abstract._ComponentsABC --> pypsa.components.array.ComponentsArrayMixin
                





              click pypsa.components.Links href "" "pypsa.components.Links"
              click pypsa.components._types.mixin.multiports._Multiport href "" "pypsa.components._types.mixin.multiports._Multiport"
              click pypsa.components.components.Components href "" "pypsa.components.components.Components"
              click pypsa.components.components.ComponentsData href "" "pypsa.components.components.ComponentsData"
              click pypsa.components.descriptors.ComponentsDescriptorsMixin href "" "pypsa.components.descriptors.ComponentsDescriptorsMixin"
              click pypsa.components.transform.ComponentsTransformMixin href "" "pypsa.components.transform.ComponentsTransformMixin"
              click pypsa.components.index.ComponentsIndexMixin href "" "pypsa.components.index.ComponentsIndexMixin"
              click pypsa.components.array.ComponentsArrayMixin href "" "pypsa.components.array.ComponentsArrayMixin"
              click pypsa.components.abstract._ComponentsABC href "" "pypsa.components.abstract._ComponentsABC"

Links components class.

This class is used for link components. All functionality specific to links is implemented here. Functionality for all components is implemented in the abstract base class.

pypsa.components.Links.additional_ports `property` ¶

additional_ports: list[str]

Identify additional component ports (bus connections) beyond predefined ones.

Returns:

list of strings –

List of additional ports. E.g. ["2", "3"] for bus2, bus3.

Also see

pypsa.Components.ports

Examples:

>>> n = pypsa.Network()
>>> _ = n.add("Link", "link1", bus0="bus1", bus1="bus2", bus2="bus3")
>>> n.components.links.additional_ports
['2']

pypsa.components.Links.add ¶

add(name: str | int | Sequence[int | str], suffix: str = '', overwrite: bool = False, return_names: bool | None = None, **kwargs: Any) -> Index | None

Add new links.

v0.33.0

Handles addition of single and multiple components along with their attributes. Pass a list of names to add multiple components at once or pass a single name to add a single component.

When a single component is added, all non-scalar attributes are assumed to be time-varying and indexed by snapshots. When multiple components are added, all non-scalar attributes are assumed to be static and indexed by names. A single value sequence is treated as scalar and broadcasted to all components. It is recommended to explicitly pass a scalar instead. If you want to add time-varying attributes to multiple components, you can pass a 2D array/ DataFrame where the first dimension is snapshots and the second dimension is names.

Any attributes which are not specified will be given the default value from Components.

Parameters:

name (str or int or list of str or list of int) –

Component name(s)
suffix (str, default: "" ) –

All components are named after name with this added suffix.
overwrite (bool, default: False ) –

If True, existing components with the same names as in name will be overwritten. Otherwise only new components will be added and others will be ignored.
return_names (bool | None, default: None ) –

Whether to return the names of the new components. Defaults to module wide option (default: False). See https://go.pypsa.org/options-params for more information.
kwargs (Any, default: {} ) –

Component attributes to add. See Other Parameters for list of default attributes but any attribute could be added.

Other Parameters:

bus0 (str or SeriesLike[str]) –

Name of origin bus to which link is attached.
bus1 (str or SeriesLike[str]) –

Name of first destination bus to which link is attached. Further destination buses (bus2, bus3, etc.) are automatically expanded as needed.
type (str or SeriesLike[str]) –

Placeholder for link type. Not implemented.
carrier (str or SeriesLike[str]) –

Carrier of the link describing its technology (e.g. gas boiler, electrolyser, HVDC link).
efficiency (float or Series or SeriesLike[float or Series]) –

Efficiency of energy transfer from bus0 to bus1. Can be time-dependent (e.g. to represent temperature-dependent heat pump COP). Further efficiency attributes for further buses (e.g. bus2, bus3, etc.) are automatically expanded as needed (e.g. efficiency2, efficiency3, etc.).
active (bool or SeriesLike[bool]) –

Whether to consider the component in basic functionality or not
build_year (int or SeriesLike[int]) –

Build year
lifetime (float or SeriesLike[float]) –

Lifetime
p_nom (float or SeriesLike[float]) –

Limit of power which can pass through link (in units of bus0). Ignored if p_nom_extendable=True.
p_nom_mod (float or SeriesLike[float]) –

Unit size of link module (e.g. fixed blocks of 100 MW).
p_nom_extendable (bool or SeriesLike[bool]) –

Switch to allow capacity p_nom to be extended.
p_nom_min (float or SeriesLike[float]) –

If p_nom_extendable=True, set its minimum value.
p_nom_max (float or SeriesLike[float]) –

If p_nom_extendable=True, set its maximum value.
p_nom_set (float or SeriesLike[float]) –

If p_nom is extendable in optimization, set its value.
p_set (float or Series or SeriesLike[float or Series]) –

The dispatch set point for p0 of the link (for optimisation and power flow).
p_init (static or SeriesLike[static]) –

Active power used as a starting point for limiting the ramp in the very first snapshot (for optimisation)
p_min_pu (float or Series or SeriesLike[float or Series]) –

Minimal dispatch per unit of p_nom for the link. Can also be negative.
p_max_pu (float or Series or SeriesLike[float or Series]) –

Maximal dispatch per unit of p_nom for the link. Can also be negative.
capital_cost (float or SeriesLike[float]) –

Fixed period costs of extending p_nom by 1 MW (unit of bus0, e.g. annuitized investment costs). Used directly unless overnight_cost is specified. Any length factor must already be included.
overnight_cost (float or SeriesLike[float]) –

Overnight (upfront) investment cost per MW (unit of bus0). If specified, PyPSA calculates annuity using discount_rate and lifetime. Takes precedence over capital_cost.
discount_rate (float or SeriesLike[float]) –

Discount rate for annuity calculation when using overnight_cost. Supports 0% rate (simple depreciation).
fom_cost (float or SeriesLike[float]) –

Fixed period operation and maintenance costs per MW (unit of bus0), added to annuitized investment cost.
marginal_cost (float or Series or SeriesLike[float or Series]) –

Marginal cost of 1 MWh consumption from bus0 (e.g. including variable operation and maintenance costs of an electrolyser but excluding electricity costs).
marginal_cost_quadratic (float or Series or SeriesLike[float or Series]) –

Quadratic marginal cost for 1 MWh of consumption from bus0.
stand_by_cost (float or Series or SeriesLike[float or Series]) –

Stand-by cost for operating the link. This cost is incurred whenever the status is 1 (including when dispatch decision is zero).
length (float or SeriesLike[float]) –

Length of the link. Useful for calculating capital_cost for HVDC connections.
terrain_factor (float or SeriesLike[float]) –

Terrain factor for increasing capital_cost calculated from length.
committable (bool or SeriesLike[bool]) –

Apply unit commitment constraints.
start_up_cost (float or SeriesLike[float]) –

Cost to start up the link. Only used if committable=True.
shut_down_cost (float or SeriesLike[float]) –

Cost to shut down the link. Only used if committable=True.
min_up_time (int or SeriesLike[int]) –

Minimum number of snapshots for status to be 1. Only used if committable=True. Does not consider snapshot weightings.
min_down_time (int or SeriesLike[int]) –

Minimum number of snapshots for status to be 0. Only used if committable=True. Does not consider snapshot weightings.
up_time_before (int or SeriesLike[int]) –

Number of snapshots that the link was online before network.snapshots start. Only read if committable=True and min_up_time>0. Does not consider snapshot weightings.
down_time_before (int or SeriesLike[int]) –

Number of snapshots that the link was offline before network.snapshots start. Only read if committable=True and min_down_time>0. Does not consider snapshot weightings.
ramp_limit_up (float or Series or SeriesLike[float or Series]) –

Maximum increase from one snapshot to the next, per unit of p_nom. Ignored if NaN. Does not consider snapshot weightings.
ramp_limit_down (float or Series or SeriesLike[float or Series]) –

Maximum decrease from one snapshot to the next, per unit of p_nom. Ignored if NaN. Does not consider snapshot weightings.
ramp_limit_start_up (float or SeriesLike[float]) –

Maximum increase at start up, per unit of p_nom. Only used if committable=True. Ignored if NaN.
ramp_limit_shut_down (float or SeriesLike[float]) –

Maximum decrease at shut down, per unit of p_nom. Only used if committable=True. Ignored if NaN.
delay (int or SeriesLike[int]) –

Delay of energy delivery to bus1 in units of n.snapshot_weightings.generators. Energy withdrawn from bus0 at snapshot t arrives at the first snapshot whose cumulative generator weighting start is at least delay units later. Auto-expanded as delay2, delay3, etc. for additional ports.
cyclic_delay (bool or SeriesLike[bool]) –

Whether delayed energy wraps cyclically from end to start of the optimization period. If False, energy is lost at the tail and first snapshots receive nothing from delayed links. Auto-expanded as cyclic_delay2, cyclic_delay3, etc. for additional ports.
p (Series or SeriesLike[Series] or ArrayLike[Series]) –

Internal power (positive if link is withdrawing from bus0).
p0 (Series or SeriesLike[Series] or ArrayLike[Series]) –

Power at bus0 (positive if link is withdrawing from bus0).
p1 (Series or SeriesLike[Series] or ArrayLike[Series]) –

Power at bus1 (positive if link is withdrawing from bus1).
p_nom_opt (float or SeriesLike[float]) –

Optimised nominal capacity.
status (Series or SeriesLike[Series] or ArrayLike[Series]) –

Status in the snapshot (1 is on, 0 is off). Only returned if committable=True.
start_up (Series or SeriesLike[Series] or ArrayLike[Series]) –

Whether the unit was started in the snapshot (1 is yes, 0 is no). Only returned if committable=True.
shut_down (Series or SeriesLike[Series] or ArrayLike[Series]) –

Whether the unit was shut down in the snapshot (1 is yes, 0 is no). Only returned if committable=True.
mu_lower (Series or SeriesLike[Series] or ArrayLike[Series]) –

Shadow price of lower p_nom limit \(-F \\leq f\). Always non-negative.
mu_upper (Series or SeriesLike[Series] or ArrayLike[Series]) –

Shadow price of upper p_nom limit \(f \\leq F\). Always non-negative.
mu_p_set (Series or SeriesLike[Series] or ArrayLike[Series]) –

Shadow price of fixed dispatch p_set
mu_ramp_limit_up (Series or SeriesLike[Series] or ArrayLike[Series]) –

Shadow price of upper ramp up limit
mu_ramp_limit_down (Series or SeriesLike[Series] or ArrayLike[Series]) –

Shadow price of lower ramp down limit

Returns:

new_names ( index or None ) –

Names of new components (including suffix) if return_names is True, otherwise None.

Examples:

The example is shown for Generator component, but the same applies to all component types.

>>> n = pypsa.Network()
>>> c = n.components.generators
>>> c
Empty 'Generator' Components

Add a single component:

>>> c.add("my-generator-1", carrier="AC")

A new generator is added to the components instance:

>>> c
'Generator' Components
----------------------
Attached to PyPSA Network 'Unnamed Network'
Components: 1

With static data (and default values for all attributes):

>>> c.static[["carrier", "p_nom"]]
               carrier  p_nom
name
my-generator-1      AC    0.0

Add multiple components with static attributes:

>>> c.add(["my-generator-2", "my-generator-3"],
...       carrier=["AC", "DC"],
...       p_nom=10)

A new generator is added to the components instance:

>>> c
'Generator' Components
----------------------
Attached to PyPSA Network 'Unnamed Network'
Components: 3

With static data:

>>> c.static[["carrier", "p_nom"]]
           carrier  p_nom
name
my-generator-1      AC    0.0
my-generator-2      AC   10.0
my-generator-3      DC   10.0

The single value for p_nom is broadcasted to all components. So you could also pass [10, 10] instead of 10.

pypsa.components.Links.get_bounds_pu ¶

get_bounds_pu(attr: str = 'p') -> tuple[DataArray, DataArray]

Get per unit bounds for links.

v1.0.0

Parameters:

attr (string, default: 'p' ) –

Attribute name for the bounds, e.g. "p"

Returns:

tuple[DataArray, DataArray] –

Tuple of (min_pu, max_pu) DataArrays.

pypsa.components.Links.get_delay_source_indexer `staticmethod` ¶

get_delay_source_indexer(snapshots: Index, weightings: Series, delay: int, is_cyclic: bool) -> tuple[ndarray, ndarray]

Get per-snapshot source positions for component delays.

Delay is interpreted in elapsed time units. For each target snapshot t, the source is the latest snapshot s such that tau[s] <= tau[t] - delay, where tau are cumulative weighting starts. In cyclic mode, source times wrap around the horizon. In non-cyclic mode, targets without a valid source are marked invalid.

For multi-investment period snapshots (MultiIndex), delays are applied independently per period since investment periods are not temporally adjacent.

Parameters:

snapshots (Index) –

Snapshot index of the optimization horizon.
weightings (Series) –

Generator snapshot weightings (n.snapshot_weightings.generators), defining the duration of each snapshot in time units.
delay (int) –

Delivery delay in the same time units as weightings.
is_cyclic (bool) –

If True, delayed times wrap around the horizon. If False, snapshots without a valid source are marked invalid.

Returns:

src_positions ( np.ndarray of int ) –

Index position of the source snapshot for each target snapshot.
valid ( np.ndarray of bool ) –

False for target snapshots that have no valid source (non-cyclic mode only).

Examples:

>>> snapshots = pd.RangeIndex(6)
>>> weightings = pd.Series(1.0, index=snapshots)
>>> from pypsa.components import Links
>>> src, valid = Links.get_delay_source_indexer(snapshots, weightings, delay=2, is_cyclic=True)
>>> src
array([4, 5, 0, 1, 2, 3])
>>> valid
array([ True,  True,  True,  True,  True,  True])
>>> src, valid = Links.get_delay_source_indexer(snapshots, weightings, delay=2, is_cyclic=False)
>>> src
array([0, 0, 0, 1, 2, 3])
>>> valid
array([False, False,  True,  True,  True,  True])

Links dataclass ¶

pypsa.components.Links.additional_ports property ¶

pypsa.components.Links.add ¶

pypsa.components.Links.get_bounds_pu ¶

pypsa.components.Links.get_delay_source_indexer staticmethod ¶

Links `dataclass` ¶

pypsa.components.Links.additional_ports `property` ¶

pypsa.components.Links.get_delay_source_indexer `staticmethod` ¶