Skip to content

Links dataclass 

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

Bases: Components

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.

See Also

pypsa.Components

Examples:

>>> n.components.links
'Link' Components
-----------------
Attached to PyPSA Network 'AC-DC-Meshed'
Components: 4

Methods:

Attributes:

  • additional_ports (list[str]) –

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

pypsa.components.Links.additional_ports property 

additional_ports: list[str]

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

Returns:

  • list of strings –

    List of additional link 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")
Index(['link1'], dtype='object')
>>> 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_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), including periodized investment costs and periodic fixed O&M costs (e.g. annuitized investment costs). Any length factor must already be included here.

  • 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. This is only possible with p_nom_extendable=False.

  • 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.

  • ramp_limit_shut_down (float or SeriesLike[float]) –

    Maximum decrease at shut down, per unit of p_nom. Only used if committable=True.

  • 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.

See Also

pypsa.Network.add

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.