Skip to content

model_soil

ModelSoil 

ModelSoil(static_env: StaticEnvSoil)

Bases: Model[ModelSoilRunOptions, StateSoil, ScenarioModelSoil, StaticEnvSoil, CableSoil]

ModelSoil computes temperatures for underground power cables using the finite difference method.

In most cases the model is instantiated with a StaticEnvSoil and executed with a scenario via run().

Class Attributes

_run_options_class: Run-options schema class. _state_class: State schema class. _scenario_model_class: Scenario model class.

Internal Runtime State

_cables_with_soil: Per-run cable representations extended with soil layers and updated during simulation. _mirror_cables_with_soil: Per-run mirrored soil cable representations for image-source calculations. _measurement_point_temperature_result: Per-run cache of measurement-point temperatures.

Configuration Parameters

logarithmic_soil_gridpoint_density: Soil-grid point density factor used for discretization. Default is 20. minimal_soil_radius: Minimum soil radius around each cable in meters. Default is 5.0. The effective soil radius is max(minimal_soil_radius, 2.5 * abs(cable depth)).

Parameters:

Name Type Description Default
static_env StaticEnvSoil

A StaticEnvSoil instance containing the soil thermal parameters and cable layout.

 required
Source code in cable_thermal_model/model/model_soil.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def __init__(self, static_env: StaticEnvSoil):
    """Initialize the ModelSoil instance with a static environment.

    Args:
        static_env: A StaticEnvSoil instance containing the soil thermal parameters and cable layout.

    """
    if not isinstance(static_env, StaticEnvSoil):
        raise ValueError(
            f"Can not use model {self.__class__.__name__} if static "
            "environment is not an environment in soil. Please use "
            "ModelAir instead."
        )

    # Set up cables
    self._cables_with_soil: dict[CableKey, PosCable[CableSoil]] = {}
    self._mirror_cables_with_soil: dict[CableKey, PosCable[CableSoil]] = {}

    self.logarithmic_soil_gridpoint_density: float = 20
    self.minimal_soil_radius: float = 5.0

    self._measurement_point_temperature_result: dict[MeasurementPointKey, np.ndarray] = {}

    super().__init__(static_env=static_env)

cables_in_environment property 

cables_in_environment: dict[CableKey, PosCable[CableSoil]]

Return per-run soil-extended cable instances for the model.

Runtime cable properties may deviate from their static baseline defaults. For soil cables, this concerns: - updated soil thermal resistivity and capacity from the active scenario (optionally with soil-drying behavior); - temperature-dependent pipe-fill resistivity where a pipe layer exists.

get_measurement_point_temp 

get_measurement_point_temp(state: StateSoil, measurement_point: MeasurementPoint) -> float

Compute the temperature at a point in the environment given the state.

Parameters:

Name Type Description Default
measurement_point MeasurementPoint

The measurement point object containing coordinates and distances to cables.

 required
state StateSoil

The state of the soil model containing time and self-heating contributions.

 required

Returns:

Name Type Description
float float

Temperature in degrees Celsius.
Source code in cable_thermal_model/model/model_soil.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def get_measurement_point_temp(
    self,
    state: StateSoil,
    measurement_point: MeasurementPoint,
) -> float:
    """Compute the temperature at a point in the environment given the state.

    Args:
        measurement_point: The measurement point object containing coordinates and distances to cables.
        state: The state of the soil model containing time and self-heating contributions.

    Returns:
        float: Temperature in degrees Celsius.

    """
    measurement_point_temp = state.ambient_temperature

    for cable_key, cable in self._cables_with_soil.items():
        distance_to_cable = measurement_point.distances_to_cables[cable_key]
        measurement_point_temp += cable.cable.get_heating_contribution_at_radius(
            radius=distance_to_cable, self_heating_contribution=state.self_heating_contribution[cable_key]
        )
    for cable_key, mirror_cable in self._mirror_cables_with_soil.items():
        distance_to_mirror_cable = measurement_point.distances_to_mirror_cables[cable_key]
        measurement_point_temp -= mirror_cable.cable.get_heating_contribution_at_radius(
            radius=distance_to_mirror_cable, self_heating_contribution=state.self_heating_contribution[cable_key]
        )

    return measurement_point_temp