Skip to content

Line

Lines dataclass 

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

Bases: Components

Lines components class.

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

See Also

pypsa.Components

Examples:

>>> n.components.lines
'Line' Components
-----------------
Attached to PyPSA Network 'AC-DC-Meshed'
Components: 7

Methods:

pypsa.components.Lines.add 

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

Add new lines.

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 branch is attached.

  • bus1 (str or SeriesLike[str]) –

    Name of destination bus to which branch is attached.

  • type (str or SeriesLike[str]) –

    Name of line standard type. If this is not an empty string "", the line standard type impedance parameters are multiplied with the length and divided/multiplied by num_parallel to compute x, r, etc. This will override any values set in r, x, andb. If the string is empty, values manually provided forr,x`, etc. are taken.

  • x (float or SeriesLike[float]) –

    Series reactance, must be non-zero for AC branch for linearised power flow equations. If the line has series inductance \(L\) in Henries then \(x = 2\\pi f L\) where \(f\) is the frequency in Hertz. Series impedance \(z = r + jx\) must be non-zero for non-linear power flow calculations. Ignored if type defined.

  • r (float or SeriesLike[float]) –

    Series resistance, must be non-zero for DC branch for linearised power flow equations. Series impedance \(z = r + jx\) must be non-zero for the non-linear power flow. Ignored if type defined.

  • g (float or SeriesLike[float]) –

    Shunt conductivity. Shunt admittance is \(y = g + jb\).

  • b (float or SeriesLike[float]) –

    Shunt susceptance. If the line has shunt capacitance \(C\) in Farads then \(b = 2\\pi f C\) where \(f\) is the frequency in Hertz. Shunt admittance is \(y = g + jb\). Ignored if type defined.

  • s_nom (float or SeriesLike[float]) –

    Limit of apparent power which can pass through branch in either direction. Ignored if s_nom_extendable=True.

  • s_nom_mod (float or SeriesLike[float]) –

    Modular unit size of line expansion of s_nom (e.g. fixed rating of added circuit). Introduces integer variables.

  • s_nom_extendable (bool or SeriesLike[bool]) –

    Switch to allow capacity s_nom to be extended in optimisation.

  • s_nom_min (float or SeriesLike[float]) –

    If s_nom_extendable=True, set the minimum value of s_nom_opt.

  • s_nom_max (float or SeriesLike[float]) –

    If s_nom_extendable=True, set the maximum value of s_nom_opt.

  • s_nom_set (float or SeriesLike[float]) –

    If s_nom is extendable in optimization, set the value of s_nom_opt.

  • s_max_pu (float or Series or SeriesLike[float or Series]) –

    The maximum allowed absolute apparent power flow per unit of s_nom for the optimisation (e.g. can set s_max_pu<1 to approximate \(N-1\) contingency factor, or can be time-varying to represent weather-dependent dynamic line rating for overhead lines).

  • capital_cost (float or SeriesLike[float]) –

    Fixed period costs of extending s_nom by 1 MVA, including periodized investment costs and periodic fixed O&M costs (e.g. annuitized investment costs). Any length factor must already be included here.

  • active (bool or SeriesLike[bool]) –

    Whether to consider the component in optimisation or not

  • build_year (int or SeriesLike[int]) –

    Build year of line.

  • lifetime (float or SeriesLike[float]) –

    Lifetime of line.

  • length (float or SeriesLike[float]) –

    Length of line used when type is set. Also useful for calculating capital_cost.

  • carrier (str or SeriesLike[str]) –

    Type of current. "AC" is the only valid value for lines.

  • terrain_factor (float or SeriesLike[float]) –

    Terrain factor for increasing length for capital_cost calculation.

  • num_parallel (float or SeriesLike[float]) –

    When type is set, this is the number of parallel circuits. Can also be fractional. If type is empty "" this value is ignored.

  • v_ang_min (float or SeriesLike[float]) –

    Minimum voltage angle difference across the line. Placeholder attribute not currently used.

  • v_ang_max (float or SeriesLike[float]) –

    Maximum voltage angle difference across the line. Placeholder attribute not currently used.

  • sub_network (str or SeriesLike[str]) –

    Name of sub-network to which lines belongs, as calculated by n.determine_network_topology(). Do not set by hand.

  • p0 (Series or SeriesLike[Series] or ArrayLike[Series]) –

    Active power at bus0 (positive if branch is withdrawing power from bus0).

  • q0 (Series or SeriesLike[Series] or ArrayLike[Series]) –

    Reactive power at bus0 (positive if branch is withdrawing power from bus0).

  • p1 (Series or SeriesLike[Series] or ArrayLike[Series]) –

    Active power at bus1 (positive if branch is withdrawing power from bus1).

  • q1 (Series or SeriesLike[Series] or ArrayLike[Series]) –

    Reactive power at bus1 (positive if branch is withdrawing power from bus1).

  • x_pu (float or SeriesLike[float]) –

    Per unit series reactance calculated by n.calculate_dependent_values() from x and n.buses.v_nom.

  • r_pu (float or SeriesLike[float]) –

    Per unit series resistance calculated by n.calculate_dependent_values() from r and n.buses.v_nom.

  • g_pu (float or SeriesLike[float]) –

    Per unit shunt conductivity calculated by n.calculate_dependent_values() from g and n.buses.v_nom.

  • b_pu (float or SeriesLike[float]) –

    Per unit shunt susceptance calculated by n.calculate_dependent_values() from b and n.buses.v_nom.

  • x_pu_eff (float or SeriesLike[float]) –

    Effective per unit series reactance for linear power flow, calculated by n.calculate_dependent_values() from x and n.buses.v_nom

  • r_pu_eff (float or SeriesLike[float]) –

    Effective per unit series resistance for linear power flow, calculated by n.calculate_dependent_values() from r and n.buses.v_nom

  • s_nom_opt (float or SeriesLike[float]) –

    Optimised nominal capacity for apparent power.

  • mu_lower (Series or SeriesLike[Series] or ArrayLike[Series]) –

    Shadow price of lower s_nom limit \(-F \\leq f\). Always non-negative.

  • mu_upper (Series or SeriesLike[Series] or ArrayLike[Series]) –

    Shadow price of upper s_nom limit \(f \\leq F\). Always non-negative.

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.Lines.calculate_line_length 

calculate_line_length() -> Series

Get length of the lines in meters.

Based on coordinates of attached buses. Buses must have 'x' and 'y' attributes, otherwise no line length can be calculated. By default the haversine formula is used to calculate the distance between two points.

Returns:

  • Series –

    Length of the lines.

See Also

pypsa.geo.haversine

Examples:

>>> c = pypsa.examples.scigrid_de().c.lines
>>> ds = c.calculate_line_length()
>>> ds.head()
0    34432.796096
1    59701.666027
2    32242.741010
3    30559.154647
4    21574.543367
dtype: float64

pypsa.components.Lines.get_bounds_pu 

get_bounds_pu(
    attr: str = "s",
) -> tuple[DataArray, DataArray]

Get per unit bounds for lines.

v1.0.0

For passive branch components, min_pu is the negative of max_pu.

Parameters:

  • attr (string, default: 's' ) –

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

Returns:

  • tuple[DataArray, DataArray] –

    Tuple of (min_pu, max_pu) DataArrays.

LineTypes dataclass 

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

Bases: Components

Line types components class.

This class is used for line type components. All functionality specific to line types is implemented here. Functionality for all components is implemented in the abstract base class.

See Also

pypsa.Components

Examples:

>>> n.components.line_types
'LineType' Components
---------------------
Attached to PyPSA Network 'AC-DC-Meshed'
Components: 59

Methods:

  • add –

    Wrap Components.add() and docstring is patched via decorator.

pypsa.components.LineTypes.add 

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

Wrap Components.add() and docstring is patched via decorator.