Skip to content

cable_thermal_model

CableKey

Bases: BaseModel

Immutable identifier for a cable within a named circuit.

CablePosition

Bases: StrEnum

Enumeration of cable positions within a circuit.

BondingType

Bases: StrEnum

Bonding type of a cable circuit.

CircuitType

Bases: StrEnum

Circuit type of cable configuration.

CircuitYReference

Bases: StrEnum

Y-axis reference position for circuit placement.

PipeInputSchema

Bases: BaseModel

Input schema defining pipe geometry and fill material.

StaticEnvAir 

StaticEnvAir()

Bases: StaticEnv[CableAir, CircuitInAirFromCableInputSchema, CircuitInAirFromCableConstructionalInputSchema, CircuitInAirFromCableIdInputSchema, CircuitInAirFromCableSpecsInputSchema]

Class that builds a static environment for circuits in air.

Source code in cable_thermal_model/environment/static_env.py 
62
63
64
65
66
67
68
69
70
71
def __init__(self) -> None:
    """Initialize the static environment with empty circuit and cable containers."""
    self.circuits: dict[str, CableCircuit] = {}
    self.circuit_cable_indices: dict[str, list[int]] = {}
    self.cables: dict[CableKey, PosCable[CableT]] = {}
    self.number_of_cables: int = 0

    self.crossing_cables: bool = False

    self.n_phases: int = 3

add_circuit_from_cable 

add_circuit_from_cable(circuit_input: CircuitInAirFromCableInputSchema)

Add the circuit to the environment based on a cable instance.

Convection parameters are added to the circuit.

Parameters:

Name Type Description Default
circuit_input CircuitInAirFromCableInputSchema

CircuitInputSchema containing the input parameters for the circuit in air, including a Cable instance.

 required
References
  • NEN-IEC 60287-2-1 (2023) - [table 3]
Source code in cable_thermal_model/environment/static_env_air.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
def add_circuit_from_cable(
    self,
    circuit_input: CircuitInAirFromCableInputSchema,
):
    """Add the circuit to the environment based on a cable instance.

    Convection parameters are added to the circuit.

    Args:
        circuit_input: CircuitInputSchema containing the input parameters
            for the circuit in air, including a Cable instance.

    References:
        - NEN-IEC 60287-2-1 (2023) - [table 3]

    """
    if self.circuits:
        raise ValueError(
            "Environment already contains circuit(s). Cannot add multiple circuits to an air environment"
        )

    self.set_environment_convection_parameters(
        circuit_type=circuit_input.circuit_type,
        dist=circuit_input.dist,
        cable=circuit_input.cable,
        clipped_to_wall=circuit_input.clipped_to_wall,
    )

    return super().add_circuit_from_cable(circuit_input)

set_environment_convection_parameters 

set_environment_convection_parameters(circuit_type: CircuitType | None, dist: float | None, cable: CableAir, clipped_to_wall: bool)

Adds convection parameters to the cables.

Parameters:

Name Type Description Default
circuit_type CircuitType | None

Type of circuit, one of 'single', 'trefoil', 'linear'

 required
dist float | None

Distance between cables, relevant for 'linear' circuits

 required
cable CableAir

CableAir instance

 required
clipped_to_wall bool

Indicator if the circuit is clipped to a wall

 required
References
  • NEN-IEC 60287-2-1 (2023) - [table 3]
Source code in cable_thermal_model/environment/static_env_air.py 
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def set_environment_convection_parameters(
    self,
    circuit_type: CircuitType | None,
    dist: float | None,
    cable: CableAir,
    clipped_to_wall: bool,
):
    """Adds convection parameters to the cables.

    Args:
        circuit_type: Type of circuit, one of 'single', 'trefoil', 'linear'
        dist: Distance between cables, relevant for 'linear' circuits
        cable: CableAir instance
        clipped_to_wall: Indicator if the circuit is clipped to a wall

    References:
        - NEN-IEC 60287-2-1 (2023) - [table 3]

    """
    Z, E, Cg = self._get_convection_parameters(circuit_type, dist, cable, clipped_to_wall)

    cable.set_convection_parameters(Z=Z, E=E, Cg=Cg)

StaticEnvSoil 

StaticEnvSoil()

Bases: StaticEnv[CableSoil, CircuitInSoilFromCableInputSchema, CircuitInSoilFromCableConstructionalInputSchema, CircuitInSoilFromCableIdInputSchema, CircuitInSoilFromCableSpecsInputSchema]

Class that builds a static environment for circuits in soil.

Source code in cable_thermal_model/environment/static_env_soil.py 
40
41
42
43
def __init__(self):
    """Initialize the StaticEnvSoil instance."""
    super().__init__()
    self._measurement_point_registry = MeasurementPointRegistry()

add_measurement_point 

add_measurement_point(x: float, y: float, ndigits: int = 3) -> MeasurementPointKey

Add a measurement point to the environment.

Parameters:

Name Type Description Default
x float

x-coordinate of the measurement point.

 required
y float

y-coordinate of the measurement point.

 required
ndigits int

Number of decimal places to round the coordinates for key generation.

 3

Returns:

Name Type Description
MeasurementPointKey MeasurementPointKey

The identifier of the added measurement point.
Source code in cable_thermal_model/environment/static_env_soil.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def add_measurement_point(self, x: float, y: float, ndigits: int = 3) -> MeasurementPointKey:
    """Add a measurement point to the environment.

    Args:
        x: x-coordinate of the measurement point.
        y: y-coordinate of the measurement point.

        ndigits: Number of decimal places to round the coordinates for key generation.

    Returns:
        MeasurementPointKey: The identifier of the added measurement point.

    """
    return self._measurement_point_registry.add_measurement_point(
        x=x,
        y=y,
        ndigits=ndigits,
    )

CableLayer

Bases: StrEnum

Enum class for possible cable layer types. Values derived from those used in the old Cable init.

soil_layers classmethod 

soil_layers() -> list[CableLayer]

Return a list of all soil layers.

Source code in cable_thermal_model/model/cables/enum_classes_cable.py 
210
211
212
213
@classmethod
def soil_layers(cls) -> list[CableLayer]:
    """Return a list of all soil layers."""
    return [layer for layer in cls if layer.name.startswith("Soil")]

PipeFillType

Bases: StrEnum

Enum class for possible types of material filling the pipe surrounding a cable.

StateAir

Bases: State

StateAir has no added attributes on top of State.

However, we want to make sure there is only one circuit (check for a unique circuit_name).

validate_single_circuit 

validate_single_circuit()

Ensure that all cable keys in StateAir belong to the same circuit.

Source code in cable_thermal_model/model/schemas/state_schemas.py 
 94
 95
 96
 97
 98
 99
100
101
@model_validator(mode="after")
def validate_single_circuit(self):
    """Ensure that all cable keys in StateAir belong to the same circuit."""
    cable_keys = self.temperature.keys()
    circuit_names = {cable_key.circuit_name for cable_key in cable_keys}
    if len(circuit_names) > 1:
        raise ValueError(f"StateAir should only contain one circuit, but found multiple: {circuit_names}")
    return self

ModelFactory

Factory class for creating model instances based on the environment.

create_model staticmethod 

create_model(static_env: StaticEnvAir) -> ModelAir

create_model(static_env: StaticEnvSoil) -> ModelSoil

create_model(static_env: StaticEnv) -> Model

create_model(static_env: StaticEnvT) -> Model

Create a model instance based on the environment type.

Parameters:

Name Type Description Default
static_env StaticEnvT

Static environment configuration for the model.

 required

Returns:

Name Type Description
Model Model

An instance of ModelAir or ModelSoil, depending on the type of static_env.

Raises:

Type Description
ValueError

If static_env is not a supported environment type.
Source code in cable_thermal_model/model/model_factory.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
@staticmethod
def create_model(
    static_env: StaticEnvT,
) -> Model:
    """Create a model instance based on the environment type.

    Args:
        static_env (StaticEnvT): Static environment configuration for the model.

    Returns:
        Model: An instance of ModelAir or ModelSoil, depending on the type of static_env.

    Raises:
        ValueError: If static_env is not a supported environment type.
    """
    if isinstance(static_env, StaticEnvAir):
        return ModelAir(static_env=static_env)
    elif isinstance(static_env, StaticEnvSoil):
        return ModelSoil(static_env=static_env)
    else:
        raise ValueError(
            f"Unsupported static environment type: {type(static_env).__name__}. "
            f"Expected {StaticEnvAir.__name__} or {StaticEnvSoil.__name__}."
        )

StateSoil

Bases: State

Extends upon the base State class. Includes additional attribute mutual_heating_contribution and its validation.

Attributes:

Name Type Description
mutual_heating_contribution dict[CableKey, ndarray]

dict[CableKey, np.ndarray]: A dictionary containing the temperature increase inside a cable due to mutual heating from other cables in the environment. This is stored as a dict with CableKey as key and an array of temperature increases per grid point as value.

validate_mutual_heating_contribution 

validate_mutual_heating_contribution()

Validate that mutual_heating_contribution keys match cable keys.

Source code in cable_thermal_model/model/schemas/state_schemas.py 
75
76
77
78
79
80
81
82
83
84
85
@model_validator(mode="after")
def validate_mutual_heating_contribution(self):
    """Validate that mutual_heating_contribution keys match cable keys."""
    found_keys = set(self.mutual_heating_contribution.keys())
    expected_keys = set(self.temperature.keys())
    if found_keys != expected_keys:
        raise ValueError(
            "CableKeys of mutual_heating_contribution should match with cable_keys of temperature."
            f"Found keys: {found_keys}, expected keys: {expected_keys}"
        )
    return self