cable module

Module: cable.py

Description

Cable data structures and cable database loading helpers for PyPacity ampacity studies.

Copyright

Copyright (c) 2026 Group of Advanced Electro-Technologies (GTEA). Universidad de Cantabria. All rights reserved.

License

SPDX-License-Identifier: GPL-3.0-only

Notes

This module is part of the PyPacity project.

References

• IEEE Std 738-2012, IEEE Standard for Calculating the Current-Temperature Relationship of Bare Overhead Conductors

• CIGRE Technical Brochure 601, Guide for Thermal Rating Calculations of Overhead Lines

• CIGRE Technical Brochure 207, Thermal Rating of Overhead Lines

class pypacity.cable.cable.Cable

Bases: object

Electrical and thermal data for an overhead conductor.

Stores the physical, electrical, and thermal properties of a bare overhead conductor. Properties are loaded from the built-in cable database via set_cable() or assigned directly by the caller.

Attributes

Attribute	Type	Description
ID	str	Conductor identifier.
D	float	Outside conductor diameter in millimeters.
D1	float	Equivalent steel-core tube diameter in millimeters.
d	float	Wire diameter in the outermost layer in millimeters.
TLO	float	Low reference temperature for resistance in deg C.
THI	float	High reference temperature for resistance in deg C.
TCDRMAX	float	Maximum allowable conductor temperature in deg C.
RLO	float	Conductor resistance at TLO in ohm/m.
RHI	float	Conductor resistance at THI in ohm/m.
B	float	Slope of the linear resistance-temperature equation in ohm/(m.deg C). Computed as (RHI - RLO) / (THI - TLO).
B1	float	Intercept of the linear resistance-temperature equation in ohm/m. Computed as RLO - B * TLO.
EMISS	float	Surface emissivity coefficient.
ABSORP	float	Solar absorptivity coefficient.
HNH	int	Number of aluminum layers.
Stranded	int	1 for stranded conductors, 0 for smooth conductors.
CrossSection	float	Conductor cross-sectional area in mm².
MASSCORE	float	Steel core mass per unit length in kg/m.
MASSOUT	float	Aluminum outer layer mass per unit length in kg/m.
HEATOUT	float	Aluminum heat capacity contribution in W.s/(m.deg C).
HEATCORE	float	Steel-core heat capacity contribution in W.s/(m.deg C).
HEATCAP	float	Total heat capacity per unit length in W.s/(m.deg C), equal to HEATOUT + HEATCORE. Set by set_cable().
deltaTcTs_value	float	Temperature difference between conductor core and surface in deg C.
CSteel20	float	Steel specific heat at 20 deg C in J/(kg.K).
CAlum20	float	Aluminum specific heat at 20 deg C in J/(kg.K).
BetaSteel20	float	Steel specific-heat temperature coefficient.
BetaAlum20	float	Aluminum specific-heat temperature coefficient.
mSteel	float	Steel mass per unit length in kg/m.
mAlum	float	Aluminum mass per unit length in kg/m.
lambda_ertc	float	Effective radial thermal conductivity in W/(m.K).

load_cable_db()

Load the cable database distributed with this package.

Reads cable_db.csv from the same directory as this module. The file uses a semicolon separator and contains one row per conductor with the columns: ID, D, D1, d, TLO, THI, TCDRMAX, RLO, RHI, HNH, HEATOUT, HEATCORE.

Returns:

A tuple (cable_db, error) where cable_db is a pandas.DataFrame with one row per conductor, and error is 0 if at least one conductor was loaded or 1 if the database file is empty.

Return type:

tuple

Raises:

FileNotFoundError – If cable_db.csv is not found in the package directory.

set_cable(NSELECT, conductor='DRAKE')

Load one conductor definition from the cable database.

Reads the conductor identified by conductor from cable_db.csv, applies default material and surface properties, and then adjusts temperature limits and heat capacity values according to the analysis mode NSELECT. Conductor matching is case-insensitive.

Parameters:

• NSELECT (int) –

  Analysis mode selector:

  • 1: steady-state conductor temperature.

  • 2: steady-state ampacity; sets TCDRPRELOAD to 101.1 deg C.

  • 3: high-temperature transient; overrides HEATOUT, HEATCORE, and TCDRMAX.

  • 4: limited-temperature transient; overrides TCDRMAX, HEATOUT, and HEATCORE.

• conductor (str) – Conductor identifier as listed in cable_db.csv. Defaults to 'DRAKE'.

Raises:

ValueError – If the cable database is empty or conductor is not found in cable_db.csv.

Note

Results are stored directly in the instance attributes (see class docstring) rather than returned. After this call, HEATCAP is set to HEATOUT + HEATCORE.

_get_cable_data(conductor)

Return the database row that matches a conductor ID.

Strips leading and trailing whitespace from conductor before matching. Matching is case-insensitive, so drake, DRAKE, and Drake all select the same conductor.

Parameters:

conductor (str) – Conductor identifier to look up in cable_db.csv.

Returns:

Row from cable_db.csv corresponding to the requested conductor.

Return type:

pandas.Series

Raises:

ValueError – If the cable database is empty, or if conductor is not found in cable_db.csv. The error message lists the available conductor IDs when the conductor is unknown.

_apply_cable_data(data)

Copy conductor-specific database values to this cable object.

Assigns the values from a single database row to the corresponding instance attributes. RLO and RHI are converted from ohm/km (as stored in cable_db.csv) to ohm/m by dividing by 1000.

Parameters:

data (pandas.Series) – Row from cable_db.csv for one conductor, as returned by _get_cable_data().

Note

Sets the following attributes: ID, D, D1, d, TLO, THI, TCDRMAX, HEATOUT, HEATCORE, HNH, RLO, RHI.

_set_common_properties()

Set default material, surface, and thermal properties.

Assigns the default values used by the built-in standard examples. These assumptions follow the IEEE 738 and CIGRE TB 601 reference cases and may be overwritten after set_cable() if a study requires different conductor properties.

Note

Sets the following attributes with their default values: EMISS = 0.5, ABSORP = 0.5, CSteel20 = 481.0 J/(kg.K), CAlum20 = 897.0 J/(kg.K), BetaSteel20 = 1.00e-4, BetaAlum20 = 3.80e-4, mSteel = 0.5119 kg/m, mAlum = 1.116 kg/m, lambda_ertc = 0.7 W/(m.K).

_apply_analysis_mode_overrides(NSELECT)

Apply mode-specific overrides for built-in ampacity examples.

Adjusts conductor temperature limits and heat capacity values according to the analysis mode before the solver runs. Values not covered by a given mode are left unchanged.

Parameters:

NSELECT (int) –

Analysis mode selector. Recognised values:

• 2: steady-state ampacity; sets TCDRPRELOAD to 101.1 deg C.

• 3: high-temperature transient; sets HEATOUT = 1066 W.s/(m.deg C), HEATCORE = 243 W.s/(m.deg C), and TCDRMAX = 1000 deg C.

• 4: limited-temperature transient; sets TCDRMAX = 150 deg C, HEATOUT = 1066 W.s/(m.deg C), and HEATCORE = 243 W.s/(m.deg C).

• Any other value: no overrides are applied.

Note

For NSELECT = 3 and NSELECT = 4, the HEATOUT and HEATCORE values loaded from the database are replaced by fixed values from the IEEE 738 standard examples.

print_ver()

Print the module name and release date to standard output.