ieee738 module

Module: ieee738.py

Description

Thermal rating calculations for overhead transmission lines performed in accordance with the IEEE Standard for Calculating the Current-Temperature Relationship of Bare Overhead Conductors.

License

SPDX-License-Identifier: GPL-3.0-only

Notes

This module is part of the PyPacity project.

References

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

class pypacity.ieee738.ieee738.IEEE738

Bases: object

Implementation of the IEEE 738 standard.

Implements the thermal rating calculations for bare overhead conductors as defined in the IEEE Standard for Calculating the Current-Temperature Relationship of Bare Overhead Conductors.

Attributes

Attribute

Type

Description

Cable1

Cable

Conductor physical and electrical properties.

Case1

Case

Environmental and operational inputs.

Debug

int

Debug output level. 0 disables output; 1 prints intermediate calculation values. Defaults to 0.

Debug_Dec

int

Number of decimal places used in debug output. Defaults to 3.
set_cable(Cable)

Set the conductor parameters for the IEEE 738 analysis.

Parameters:

Cable (Cable) – Object of class Cable containing the conductor physical and electrical characteristics (diameter, resistance, emissivity, etc.).

set_case(Case)

Set the environmental and operational conditions for the IEEE 738 analysis.

Parameters:

Case (Case) – Object of class Case containing the analysis mode, weather conditions, simulation parameters, and geographic data.

ieee_738(out=False)

Execute the IEEE 738 thermal rating calculation.

Main entry point of the module. Computes the solar heat gain and the thermal resistance coefficients, then performs the selected analysis according to Case1.NSELECT:

  • NSELECT = 1: steady-state conductor temperature for a given

    current (XIPRELOAD). Result stored in Case1.TCDRPRELOAD.

  • NSELECT = 2: steady-state ampacity for a given conductor

    temperature (TCDRPRELOAD). Result stored in Case1.TR.

  • NSELECT = 3: transient conductor temperature following a step

    change in current from XIPRELOAD to XISTEP. Results stored in Case1.ATCDR and Case1.TIME.

  • NSELECT = 4: transient thermal rating — the current XISTEP

    that raises the conductor to TCDRMAX in time TT. Result stored in Case1.XISTEP.

Parameters:

out (bool) – If True, prints a short summary of results by calling output() at the end of the calculation. Defaults to False.

Note

Results are stored in Case1 attributes rather than returned. Requires Cable1 and Case1 to be set beforehand via set_cable() and set_case().

_solar()

Compute the solar heat gain rate of the conductor (QS).

Calculates the solar heat input per unit length of conductor based on geographic location, time of day, day of the year, and atmospheric conditions, following Section 4.4 of IEEE 738-2012.

Note

The result is stored in Case1.QS (float, W/m) rather than returned directly.

Uses the following attributes from Cable1:

  • ABSORP: solar absorptivity coefficient.

  • D: outside diameter of the conductor (mm).

Uses the following attributes from Case1:

  • CDR_LAT_DEG: conductor latitude (degrees).

  • NDAY: day of the year [1, 365].

  • SUN_TIME: solar hour angle (e.g. 14 = 2 PM; 99 = no sun).

  • CDR_ELEV: conductor elevation above sea level (m).

  • Z1_DEG: conductor direction clockwise relative to north (degrees).

  • A3: atmospheric clarity. 0 for clear air; 1 for industrial atmosphere.

  • SolarRadiation: measured solar radiation (W/m²), used when SUN_TIME >= 24 or SUN_TIME == 99.

Sets:

  • Case1.QS (float): solar heat gain rate per unit length (W/m).

_thermal()

Compute the thermal resistance coefficient, heat capacity, and wind correction factor.

Calculates the linear resistance equation coefficients of the conductor as a function of temperature, the effective wind angle relative to the conductor axis, and the wind correction factor (YC) for non-perpendicular wind, following Section 4.6 of IEEE 738-2012.

Note

All results are stored directly in Cable1 and Case1 attributes rather than returned.

Sets the following attributes in Cable1:

  • B (float): Slope of the linear resistance equation (Ohm/m·°C).

  • B1 (float): Intercept of the linear resistance equation (Ohm/m).

Sets the following attributes in Case1:

  • WINDANG_DEG (float): Effective angle between wind direction and conductor axis (degrees).

  • WINDANG_RAD (float): Effective angle between wind direction and conductor axis (radians).

  • YC (float): Wind correction factor for non-perpendicular wind.

Uses the following attributes from Cable1:

  • RLO, RHI: conductor resistance at minimum and maximum temperature (Ohm/m).

  • TLO, THI: minimum and maximum temperature for resistance computation (°C).

Uses the following attributes from Case1:

  • DWIND_DEG: wind direction (degrees).

  • Z1_DEG: conductor direction clockwise relative to north (degrees).

_mueller()

Find the conductor current using Mueller’s iterative method.

Implements Mueller’s root-finding algorithm (a combination of bisection and inverse parabolic interpolation) to determine the current XISTEP that raises the conductor temperature to its maximum allowable value TCDRMAX in the simulation time TT.

The algorithm iterates by calling find_TCDR() repeatedly, comparing the resulting conductor temperature against TCDRMAX, and narrowing the current search interval until convergence. The maximum number of iterations is controlled by Case1.IEND (default: 20). If no convergence is reached, the program halts with an error message.

Note

Results are stored in Case1 attributes rather than returned. The program will call sys.exit() if the solution does not converge or if the temperature is out of range (IER = 1 or IER = 2).

Uses the following attributes from Case1:

  • XLO, XHI: initial lower and upper current bounds (A).

  • TT: simulation time (s).

  • EPS: convergence tolerance (default: 0.049).

  • IEND: maximum number of iterations (default: 20).

Uses the following attributes from Cable1:

  • TCDRMAX: maximum allowable conductor temperature (°C).

Sets the following attributes in Case1:

  • X (float): converged current value (A).

  • IER (int): convergence status code. 0 for success; 1 for no convergence; 2 for temperature out of range.

_initial_bounds()

Determine the initial search interval for Mueller’s iteration.

Scans the search domain by dividing it into Case1.DIV equal subintervals and evaluating find_TCDR() at each point until a sign change is detected. The subinterval containing the sign change becomes the initial bracket [XLI, XRI] passed to mueller().

The search domain depends on Case1.NFLAG:
  • NFLAG = 0: searches for conductor temperature in the range

    [TAMB, 1000] °C.

  • NFLAG = 1: searches for conductor current in the range

    [0, 10 * AT] A.

If no sign change is found, the full domain [XLO, XHI] is used as the initial bracket.

Note

Results are stored in Case1 attributes rather than returned.

Sets the following attributes in Case1:

  • XLI (float): lower bound of the initial search interval.

  • XRI (float): upper bound of the initial search interval.

_find_TCDR()

Evaluate the residual function for the current iteration step.

Computes the difference between the target value and the value obtained for a trial input Case1.X. The result is stored in Case1.TEMP and used by mueller() and initial_bounds() to detect sign changes and drive the iteration toward convergence.

The behaviour depends on Case1.NFLAG:
  • NFLAG = 0: Case1.X is a trial conductor temperature (°C).

    Calls thermal_rating() and stores in Case1.TEMP the difference between the target current XIDUMMY and the computed steady-state current TR.

  • NFLAG = 1: Case1.X is a trial conductor current (A).

    Calls _TCDR_vs_TIME() and stores in Case1.TEMP the difference between the maximum allowable temperature TCDRMAX and the computed conductor temperature TCDR at time TT.

Note

The result is stored in Case1.TEMP rather than returned.

Uses the following attributes from Case1:

  • NFLAG: operation mode flag.

  • X: trial value (temperature in °C or current in A).

  • XIDUMMY: target current (A), used when NFLAG = 0.

Uses the following attribute from Cable1:

  • TCDRMAX: maximum allowable conductor temperature (°C), used when NFLAG = 1.

Sets:

  • Case1.TEMP (float): residual value for the current iteration step.

_thermal_rating()

Compute the steady-state ampacity of the conductor at a given temperature.

Calculates the maximum allowable current (ampacity) TR that produces a steady-state conductor temperature equal to Case1.TCDR, based on the heat balance equation of IEEE 738-2012 (Section 4.3):

I² · R(Tc) = QR + QC - QS

where QR is the radiated heat loss, QC is the convective heat loss (natural or forced, whichever is greater), and QS is the solar heat gain computed by solar().

Note

The result is stored in Case1.TR rather than returned. If the heat balance is negative or zero (R5 <= 0), TR is set to 0 and the function returns immediately.

Uses the following attributes from Case1:

  • TCDR: conductor temperature (°C).

  • TAMB: ambient temperature (°C).

  • VWIND: wind speed (m/s).

  • CDR_ELEV: conductor elevation above sea level (m).

  • QS: solar heat gain rate (W/m), set by solar().

  • YC: wind correction factor, set by thermal().

Uses the following attributes from Cable1:

  • EMISS: emissivity coefficient.

  • D: outside diameter of conductor (mm).

  • B, B1: linear resistance coefficients (Ohm/m·°C, Ohm/m), set by thermal().

Sets:

  • Case1.TR (float): steady-state ampacity (A).

_TCDR_vs_TIME()

Simulate the transient evolution of conductor temperature over time.

Computes the conductor temperature at each time step DELTIME following a step change in current from XIPRELOAD to XISTEP, using the transient heat balance equation of IEEE 738-2012 (Section 4.5):

Tc(t + Δt) = Tc(t) + (I² · R(Tc) + QS - QR - QC) · Δt / mCp

where mCp (HEATCAP) is the total heat capacity of the conductor per unit length. thermal_rating() is called at each step to update the heat loss terms.

For short-duration fault currents (TT < 60 s), only the heat capacity of the outer aluminium layer (HEATOUT) is used.

The simulation stops when the elapsed time reaches TT or, in mode NSELECT = 3, when TCDR exceeds TCDRMAX. The maximum number of time steps is 3000; the program halts with an error if exceeded.

Note

Results are stored in Case1 attributes rather than returned.

Uses the following attributes from Case1:

  • TCDRPRELOAD: initial conductor temperature (°C).

  • XISTEP: step current after the transient (A).

  • DELTIME: simulation time step (s).

  • TT: total simulation time (s).

  • NSELECT: analysis mode (3 = transient temperature, 4 = transient rating).

  • QS, QR, QC: heat gain and loss terms (W/m), updated each step.

Uses the following attributes from Cable1:

  • TCDRMAX: maximum allowable conductor temperature (°C).

  • HEATCAP: total heat capacity per unit length (W·s/m·°C).

  • HEATOUT: heat capacity of the aluminium layer only (W·s/m·°C).

Sets:

  • Case1.ATCDR (list): conductor temperature at each time step (°C).

  • Case1.TIME (list): elapsed time at each time step (s).

  • Case1.KTIMEMAX (int): total number of time steps computed.

_starting_ci()

Compute the initial current estimate for the transient iteration.

Estimates a starting value for the current AT by assuming adiabatic heating of the conductor during the simulation time TT. This estimate is used by initial_bounds() to define the search interval in transient thermal rating calculations (NSELECT = 4).

For short-duration events (TT < 60 s), only the heat capacity of the aluminium layer is used. Otherwise, the combined heat capacity of the aluminium and steel core is used.

Note

Results are stored in Case1 and Cable1 attributes rather than returned.

Uses the following attributes from Case1:

  • TAMB: ambient temperature (°C).

  • TT: simulation time (s).

  • TCDRPRELOAD: initial conductor temperature (°C).

Uses the following attributes from Cable1:

  • TCDRMAX: maximum allowable conductor temperature (°C).

  • HEATOUT: heat capacity of the aluminium layer (W·s/m·°C).

  • HEATCORE: heat capacity of the steel core (W·s/m·°C).

Sets:

  • Cable1.HEATCAP (float): total heat capacity per unit length used in the simulation (W·s/m·°C).

  • Case1.AT (float): adiabatic current estimate as starting point for iteration (A).

  • Case1.NFLAG (int): set to 1 to indicate transient current iteration mode.

outputs()

Print a detailed report of the IEEE 738-2013 calculation results.

Prints to the console a full summary including conductor and environmental parameters, heat balance terms, and the main result depending on the analysis mode (Case1.NSELECT):

  • NSELECT = 1: prints the steady-state conductor temperature for the given current.

  • NSELECT = 2: prints the steady-state ampacity for the given conductor temperature.

Note

This function only prints to the console. It does not return any value and does not modify any attributes.

See also

output() for a compact summary.

_str_round(valuex)

Round a numeric value and return it as a string.

Utility function used for printing debug information. The number of decimal places is controlled by Debug_Dec.

Parameters:

valuex (float) – Value to be rounded.

Returns:

Rounded value converted to string.

Return type:

str

output()

Print a short summary of the main inputs, outputs, and heat balance terms.

Prints to the console a compact summary including the wind angle, the main input/output pair depending on the analysis mode (Case1.NSELECT):

  • NSELECT = 1: input current (A) → output temperature (°C).

  • NSELECT = 2: input temperature (°C) → output current (A).

Note

This function only prints to the console. It does not return any value and does not modify any attributes.

See also

outputs() for the full detailed report.

ampacidad()

Compute the ampacity of the conductor.

Note

Not yet implemented.

print_ver()

Print the current version of the IEEE738 module.

Note

This function only prints to the console. It does not return any value and does not modify any attributes.