Solver3TL

Solver3TL

Solver3TL(
    dic: Optional[dict[str, Any]] = None,
    joule: Type[PowerTerm] = PowerTerm,
    solar: Type[PowerTerm] = PowerTerm,
    convective: Type[PowerTerm] = PowerTerm,
    radiative: Type[PowerTerm] = PowerTerm,
    precipitation: Type[PowerTerm] = PowerTerm,
)

Bases: Solver3T

Source code in src/thermohl/solver/slv3t_legacy.py

def __init__(
    self,
    dic: Optional[dict[str, Any]] = None,
    joule: Type[PowerTerm] = PowerTerm,
    solar: Type[PowerTerm] = PowerTerm,
    convective: Type[PowerTerm] = PowerTerm,
    radiative: Type[PowerTerm] = PowerTerm,
    precipitation: Type[PowerTerm] = PowerTerm,
):
    super().__init__(dic, joule, solar, convective, radiative, precipitation)
    self.update()

average

average(surface_temperature, core_temperature)

Compute average temperature given surface and core temperature.

Unlike Solver3T, always use a regular mean even for non-homogeneous conductors.

Parameters:

Name	Type	Description	Default
surface_temperature	ndarray	Array of surface temperatures.	required
core_temperature	ndarray	Array of core temperatures.	required

Source code in src/thermohl/solver/slv3t_legacy.py

def average(self, surface_temperature, core_temperature):
    """
    Compute average temperature given surface and core temperature.

    Unlike Solver3T, always use a regular mean even for non-homogeneous
    conductors.

    Args:
        surface_temperature (numpy.ndarray): Array of surface temperatures.
        core_temperature (numpy.ndarray): Array of core temperatures.
    """
    return 0.5 * (surface_temperature + core_temperature)

balance_3t

balance_3t(
    surface_temperature: floatArray,
    core_temperature: floatArray,
    joule_value: Optional[floatArrayLike] = None,
) -> floatArrayLike

Calculate the thermal balance.

This method computes the thermal balance by summing the joule heating, specific heat, and subtracting the contributions from the cooling components (convection, radiation, and conduction).

Parameters:

Name	Type	Description	Default
surface_temperature	ndarray	Array of surface temperatures.	required
core_temperature	ndarray	Array of core temperatures.	required
joule_value	float | ndarray	Precomputed joule heating value. If None, it will be computed from the given temperatures.	None

Returns:

Type	Description
floatArrayLike	float | numpy.ndarray: The resulting thermal balance.

Source code in src/thermohl/solver/slv3t.py

def balance_3t(
    self,
    surface_temperature: floatArray,
    core_temperature: floatArray,
    joule_value: Optional[floatArrayLike] = None,
) -> floatArrayLike:
    """
    Calculate the thermal balance.

    This method computes the thermal balance by summing the joule heating,
    specific heat, and subtracting the contributions from the cooling
    components (convection, radiation, and conduction).

    Args:
        surface_temperature (numpy.ndarray): Array of surface temperatures.
        core_temperature (numpy.ndarray): Array of core temperatures.
        joule_value (float | numpy.ndarray, optional): Precomputed joule heating value.
            If None, it will be computed from the given temperatures.

    Returns:
        float | numpy.ndarray: The resulting thermal balance.
    """
    if joule_value is None:
        joule_value = self.joule(surface_temperature, core_temperature)
    return (
        joule_value
        + self.solar_heating.value(surface_temperature)
        - self.convective_cooling.value(surface_temperature)
        - self.radiative_cooling.value(surface_temperature)
        - self.precipitation_cooling.value(surface_temperature)
    )

balance_and_morgan

balance_and_morgan(
    surface_temperature: floatArray,
    core_temperature: floatArray,
) -> tuple[floatArrayLike, floatArray]

Compute both balance and morgan efficiently by sharing computations.

This is the optimized version used by steady-state solvers to avoid redundant joule heating calculations.

Parameters:

Name	Type	Description	Default
surface_temperature	ndarray	Array of surface temperatures.	required
core_temperature	ndarray	Array of core temperatures.	required

Returns:

Type	Description
tuple[floatArrayLike, floatArray]	tuple[float | numpy.ndarray, numpy.ndarray]: The thermal balance and the Morgan function result.

Source code in src/thermohl/solver/slv3t.py

def balance_and_morgan(
    self, surface_temperature: floatArray, core_temperature: floatArray
) -> tuple[floatArrayLike, floatArray]:
    """
    Compute both balance and morgan efficiently by sharing computations.

    This is the optimized version used by steady-state solvers to avoid
    redundant joule heating calculations.

    Args:
        surface_temperature (numpy.ndarray): Array of surface temperatures.
        core_temperature (numpy.ndarray): Array of core temperatures.

    Returns:
        tuple[float | numpy.ndarray, numpy.ndarray]:
            The thermal balance and the Morgan function result.
    """
    # Compute joule once and reuse for both functions
    joule_value = self.joule(surface_temperature, core_temperature)

    balance_value = self.balance_3t(
        surface_temperature, core_temperature, joule_value=joule_value
    )
    morgan_value = self.morgan_3t(
        surface_temperature, core_temperature, joule_value=joule_value
    )
    return balance_value, morgan_value

joule

joule(
    surface_temperature: floatArray,
    core_temperature: floatArray,
) -> floatArrayLike

Calculate the Joule heating effect.

Parameters:

Name	Type	Description	Default
surface_temperature	ndarray	Array of surface temperatures.	required
core_temperature	ndarray	Array of core temperatures.	required

Returns:

Type	Description
floatArrayLike	float | numpy.ndarray: The calculated Joule heating values.

Notes: - The function computes the average temperature temperature. - Returns the Joule heating values based on the adjusted temperatures.

Source code in src/thermohl/solver/slv3t.py

def joule(
    self, surface_temperature: floatArray, core_temperature: floatArray
) -> floatArrayLike:
    """
    Calculate the Joule heating effect.

    Args:
        surface_temperature (numpy.ndarray): Array of surface temperatures.
        core_temperature (numpy.ndarray): Array of core temperatures.

    Returns:
        float | numpy.ndarray: The calculated Joule heating values.

    Notes:
    - The function computes the average temperature `temperature`.
    - Returns the Joule heating values based on the adjusted temperatures.
    """
    average_temperature = self.average(surface_temperature, core_temperature)
    return self.joule_heating.value(average_temperature)

morgan_3t

morgan_3t(
    surface_temperature: floatArray,
    core_temperature: floatArray,
    joule_value: Optional[floatArrayLike] = None,
) -> floatArray

Computes the Morgan function for given temperature arrays.

Parameters:

Name	Type	Description	Default
surface_temperature	ndarray	Array of surface temperatures.	required
core_temperature	ndarray	Array of core temperatures.	required
joule_value	float | ndarray	Precomputed joule heating value.	None

Returns:

Type	Description
floatArray	numpy.ndarray: Resulting array after applying the Morgan function.

Source code in src/thermohl/solver/slv3t_legacy.py

def morgan_3t(
    self,
    surface_temperature: floatArray,
    core_temperature: floatArray,
    joule_value: Optional[floatArrayLike] = None,
) -> floatArray:
    """
    Computes the Morgan function for given temperature arrays.

    Args:
        surface_temperature (numpy.ndarray): Array of surface temperatures.
        core_temperature (numpy.ndarray): Array of core temperatures.
        joule_value (float | numpy.ndarray, optional): Precomputed joule heating value.

    Returns:
        numpy.ndarray: Resulting array after applying the Morgan function.
    """
    if joule_value is None:
        joule_value = self.joule(surface_temperature, core_temperature)

    heat_flux_coefficient = self.morgan_coefficients[0]
    return (
        core_temperature - surface_temperature
    ) - heat_flux_coefficient * joule_value

steady_intensity

steady_intensity(
    max_conductor_temperature: floatArrayLike = np.array(
        []
    ),
    target: CableLocationListLike = None,
    cable_type: CableTypeListLike = None,
    tol: float = default.tol,
    maxiter: int = default.maxiter,
    return_err: bool = False,
    return_temp: bool = True,
    return_power: bool = True,
) -> dict[str, np.ndarray]

Compute the steady-state intensity for a given temperature profile.

Parameters:

Name	Type	Description	Default
max_conductor_temperature	float | ndarray	Initial temperature profile. Default is an empty numpy array.	array([])
target	TargetType | list[CableLocation]	Target specification for the solver. Default is None.	None
cable_type	CableType | list[CableType]	Cable type specification for the solver. Default is None. If provided, it overrides the target specification.	None
tol	float	Tolerance for the solver. Default is DP.tol.	tol
maxiter	int	Maximum number of iterations for the solver. Default is DP.maxiter.	maxiter
return_err	bool	If True, return the error in the output DataFrame. Default is False.	False
return_temp	bool	If True, return the temperature profiles in the output DataFrame. Default is True.	True
return_power	bool	If True, return the power profiles in the output DataFrame. Default is True.	True

Returns:

Type	Description
dict[str, ndarray]	dict[str, np.ndarray]: Dictionary containing the steady-state intensity and optionally the error, temperature profiles, and power profiles,
dict[str, ndarray]	along with input data.

Source code in src/thermohl/solver/slv3t.py

def steady_intensity(
    self,
    max_conductor_temperature: floatArrayLike = np.array([]),
    target: CableLocationListLike = None,
    cable_type: CableTypeListLike = None,
    tol: float = default.tol,
    maxiter: int = default.maxiter,
    return_err: bool = False,
    return_temp: bool = True,
    return_power: bool = True,
) -> dict[str, np.ndarray]:
    """
    Compute the steady-state intensity for a given temperature profile.

    Args:
        max_conductor_temperature (float | numpy.ndarray): Initial temperature profile. Default is an empty numpy array.
        target (TargetType | list[CableLocation]): Target specification for the solver. Default is None.
        cable_type (CableType | list[CableType]): Cable type specification for the solver. Default is None. If provided, it overrides the target specification.
        tol (float): Tolerance for the solver. Default is DP.tol.
        maxiter (int): Maximum number of iterations for the solver. Default is DP.maxiter.
        return_err (bool): If True, return the error in the output DataFrame. Default is False.
        return_temp (bool): If True, return the temperature profiles in the output DataFrame. Default is True.
        return_power (bool): If True, return the power profiles in the output DataFrame. Default is True.

    Returns:
        dict[str, np.ndarray]: Dictionary containing the steady-state intensity and optionally the error, temperature profiles, and power profiles,
        along with input data.
    """
    target = _infer_target_from_cable_type(cable_type, target)

    Tmax, newtheader = self._steady_intensity_header(
        max_conductor_temperature, target
    )

    def balance_and_morgan(
        i: floatArray, tg: floatArray
    ) -> Tuple[floatArrayLike, floatArray]:
        surface_temperature, core_temperature = newtheader(i, tg)
        return self.balance_and_morgan(surface_temperature, core_temperature)

    # solve system
    s = Solver1T(
        self.args.__dict__,
        type(self.joule_heating),
        type(self.solar_heating),
        type(self.convective_cooling),
        type(self.radiative_cooling),
        type(self.precipitation_cooling),
    )
    r = s.steady_intensity(Tmax, tol=1.0, return_power=False)
    x, y, iterations, err = quasi_newton_2d(
        balance_and_morgan,
        r[VariableType.TRANSIT.value],
        Tmax,
        relative_tolerance=tol,
        max_iterations=maxiter,
        delta_x=1.0e-03,
        delta_y=1.0e-03,
    )
    if np.max(err) > tol or iterations == maxiter:
        logger.debug(
            f"rstat_analytic max err is {np.max(err):.3E} in {iterations:d} iterations"
        )

    # format output
    result = {VariableType.TRANSIT.value: x}

    self.add_error_if_needed(err, result, return_err)

    if return_temp or return_power:
        surface_temperature, core_temperature = newtheader(x, y)
        average_temperature = self.average(surface_temperature, core_temperature)

        if return_temp:
            result[TemperatureType.SURFACE.value] = surface_temperature
            result[TemperatureType.AVERAGE.value] = average_temperature
            result[TemperatureType.CORE.value] = core_temperature

        if return_power:
            result[PowerType.JOULE.value] = self.joule_heating.value(
                average_temperature
            )
            result[PowerType.SOLAR.value] = self.solar_heating.value(
                surface_temperature
            )
            result[PowerType.CONVECTION.value] = self.convective_cooling.value(
                surface_temperature
            )
            result[PowerType.RADIATION.value] = self.radiative_cooling.value(
                surface_temperature
            )
            result[PowerType.RAIN.value] = self.precipitation_cooling.value(
                surface_temperature
            )

    result = self._add_input_data_to_result(result)

    return result

steady_temperature

steady_temperature(return_uncertainty=False, **kwargs)

Compute the steady-state temperature distribution.

Parameters:

Name	Type	Description	Default
surface_temperature_guess	float | ndarray | None	Initial guess for the surface temperature. If None, ambient temperature is used.	required
core_temperature_guess	float | ndarray | None	Initial guess for the core temperature. If None, 1.5 times the absolute value of ambient temperature is used.	required
tol	float	Tolerance for the quasi-Newton solver.	required
maxiter	int	Maximum number of iterations for the quasi-Newton solver.	required
return_err	bool	If True, the error of the solution is included in the returned dict.	required
return_power	bool	If True, power-related values are included in the returned dict.	required
return_uncertainty	bool	If True, the uncertainty on computed average temperature is included in the returned dict. This is the uncertainty due to uncertainties on transit, ambient temperature, wind speed and direction, and solar irradiance. Uncertainties on other parameters (e.g. albedo) are ignored.	False

Returns:

Type	Description
	dict[str, np.ndarray]: Dictionary containing the steady-state temperatures and optionally the error and power-related values and uncertainty, along with input data.

Source code in src/thermohl/solver/slv3t_legacy.py

def steady_temperature(
    self,
    return_uncertainty=False,
    **kwargs,
):
    """
    Compute the steady-state temperature distribution.

    Args:
        surface_temperature_guess (float | numpy.ndarray | None): Initial guess for the surface temperature. If
            None, ambient temperature is used.
        core_temperature_guess (float | numpy.ndarray | None): Initial guess for the core temperature. If None, 1.5
            times the absolute value of ambient temperature is used.
        tol (float): Tolerance for the quasi-Newton solver.
        maxiter (int): Maximum number of iterations for the quasi-Newton solver.
        return_err (bool): If True, the error of the solution is included in the returned dict.
        return_power (bool): If True, power-related values are included in the returned dict.
        return_uncertainty (bool): If True, the uncertainty on computed average temperature is included in the
            returned dict. This is the uncertainty due to uncertainties on transit, ambient temperature, wind speed
            and direction, and solar irradiance. Uncertainties on other parameters (e.g. albedo) are ignored.

    Returns:
        dict[str, np.ndarray]: Dictionary containing the steady-state temperatures and optionally the error and
            power-related values and uncertainty,
            along with input data.
    """
    result = super().steady_temperature(**kwargs)
    if not return_uncertainty:
        return result

    average_temperature = result[TemperatureType.AVERAGE.value]
    uncertainty = self._compute_temperature_uncertainty(
        average_temperature, **kwargs
    )
    result["uncertainty"] = uncertainty

    return result

transient_temperature

transient_temperature(
    offset: floatArray = np.array([]),
    surface_temperature_0: Optional[floatArrayLike] = None,
    core_temperature_0: Optional[floatArrayLike] = None,
    return_power: bool = False,
) -> Dict[str, Any]

Compute transient-state temperature.

Parameters:

Name	Type	Description	Default
offset	ndarray	A 1D array with times (in seconds) when the temperature needs to be computed. The array must contain increasing values (undefined behaviour otherwise).	array([])
surface_temperature_0	float | ndarray | None	Initial surface temperature. If None, the ambient temperature from the internal dict will be used. The default is None.	None
core_temperature_0	float | ndarray | None	Initial core temperature. If None, the ambient temperature from the internal dict will be used. The default is None.	None
return_power	bool	Return power term values. The default is False.	False

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: A dictionary with temperature and other results (depending on inputs) in the keys,
Dict[str, Any]	along with input data.

Source code in src/thermohl/solver/slv3t.py

def transient_temperature(
    self,
    offset: floatArray = np.array([]),
    surface_temperature_0: Optional[floatArrayLike] = None,
    core_temperature_0: Optional[floatArrayLike] = None,
    return_power: bool = False,
) -> Dict[str, Any]:
    """
    Compute transient-state temperature.

    Args:
        offset (numpy.ndarray): A 1D array with times (in seconds) when the temperature needs to be computed. The array must contain increasing values (undefined behaviour otherwise).
        surface_temperature_0 (float | numpy.ndarray | None): Initial surface temperature. If None, the ambient temperature from the internal dict will be used. The default is None.
        core_temperature_0 (float | numpy.ndarray | None): Initial core temperature. If None, the ambient temperature from the internal dict will be used. The default is None.
        return_power (bool, optional): Return power term values. The default is False.

    Returns:
        Dict[str, Any]: A dictionary with temperature and other results (depending on inputs) in the keys,
        along with input data.

    """
    # get sizes (n for input dict entries, N for time)
    n = self.args.get_number_of_computations()
    N = len(offset)
    if N < 2:
        raise ValueError()

    # get initial temperature
    surface_temperature_0 = (
        surface_temperature_0
        if surface_temperature_0 is not None
        else self.args.ambient_temperature
    )
    core_temperature_0 = (
        core_temperature_0
        if core_temperature_0 is not None
        else 1.0 + surface_temperature_0
    )
    time_changing_parameters = get_time_changing_parameters(self.args, offset, N, n)
    c1, c2 = self._morgan_transient()
    # inverse of m*C : shortcuts for time-loop
    imc = 1.0 / (self.args.linear_mass * self.args.heat_capacity)

    # init
    surface_temperature = np.zeros((N, n))
    average_temperature = np.zeros((N, n))
    core_temperature = np.zeros((N, n))
    surface_temperature[0, :] = surface_temperature_0
    core_temperature[0, :] = core_temperature_0
    average_temperature[0, :] = self.average(
        surface_temperature[0, :], core_temperature[0, :]
    )

    # main time loop
    for i in range(1, len(offset)):
        for k in time_changing_parameters.keys():
            self.args[k] = time_changing_parameters[k][i, :]
        self.update()
        bal = self.balance_3t(
            surface_temperature[i - 1, :], core_temperature[i - 1, :]
        )
        average_temperature[i, :] = (
            average_temperature[i - 1, :] + (offset[i] - offset[i - 1]) * bal * imc
        )
        mrg = c1 * (self.joule_heating.value(average_temperature[i, :]) - bal)
        core_temperature[i, :] = average_temperature[i, :] + c2 * mrg
        surface_temperature[i, :] = core_temperature[i, :] - mrg

    result = self._transient_temperature_results(
        offset,
        surface_temperature,
        average_temperature,
        core_temperature,
        return_power,
        n,
    )
    result = self._add_input_data_to_result(result)
    return result

transient_temperature_legacy

transient_temperature_legacy(
    offset: floatArray = np.array([]),
    surface_temperature_0: Optional[floatArrayLike] = None,
    core_temperature_0: Optional[floatArrayLike] = None,
    time_constant: float = 600.0,
    return_power: bool = False,
) -> Dict[str, Any]

Compute transient-state temperature with legacy method.

Parameters:

Name	Type	Description	Default
offset	ndarray	A 1D array with times (in seconds) when the temperature needs to be computed. The array must contain increasing values (undefined behaviour otherwise).	array([])
surface_temperature_0	float	Initial surface temperature. If set to None, the ambient temperature from internal dict will be used. The default is None.	None
core_temperature_0	float	Initial core temperature. If set to None, the ambient temperature from internal dict will be used. The default is None.	None
time_constant	float	A time-constant to add some inertia. The default is 600.	600.0
return_power	bool	Return power term values. The default is False.	False

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: A dictionary with temperature and other results (depending on inputs) in the keys, along with input data.

Source code in src/thermohl/solver/slv3t_legacy.py

def transient_temperature_legacy(
    self,
    offset: floatArray = np.array([]),
    surface_temperature_0: Optional[floatArrayLike] = None,
    core_temperature_0: Optional[floatArrayLike] = None,
    time_constant: float = 600.0,
    return_power: bool = False,
) -> Dict[str, Any]:
    """
    Compute transient-state temperature with legacy method.

    Args:
        offset (numpy.ndarray): A 1D array with times (in seconds) when the temperature needs to be
            computed. The array must contain increasing values (undefined behaviour otherwise).
        surface_temperature_0 (float): Initial surface temperature. If set to None, the ambient temperature from
            internal dict will be used. The default is None.
        core_temperature_0 (float): Initial core temperature. If set to None, the ambient temperature from
            internal dict will be used. The default is None.
        time_constant (float): A time-constant to add some inertia. The default is 600.
        return_power (bool, optional): Return power term values. The default is False.

    Returns:
        Dict[str, Any]: A dictionary with temperature and other results (depending on inputs)
            in the keys, along with input data.

    """

    # get sizes (n for input dict entries, N for offsets)
    n = self.args.get_number_of_computations()
    N = len(offset)
    if N < 2:
        raise ValueError()

    # get initial temperature
    surface_temperature_0 = (
        surface_temperature_0
        if surface_temperature_0 is not None
        else self.args.ambient_temperature
    )
    core_temperature_0 = (
        core_temperature_0
        if core_temperature_0 is not None
        else 1.0 + surface_temperature_0
    )

    # inverse of m*C : shortcuts for time-loop
    imc = 1.0 / (self.args.linear_mass * self.args.heat_capacity)

    # define temperature data 2D arrays
    surface_temperature = np.zeros((N, n))
    average_temperature = np.zeros((N, n))
    core_temperature = np.zeros((N, n))
    temperature_difference = np.zeros((N, n))
    # set initial values in first row
    surface_temperature[0, :] = surface_temperature_0
    core_temperature[0, :] = core_temperature_0
    average_temperature[0, :] = self.average(
        surface_temperature[0, :], core_temperature[0, :]
    )
    temperature_difference[0, :] = (
        core_temperature[0, :] - surface_temperature[0, :]
    )

    # compute transient temperatures for each row after the first.
    for i in range(1, len(offset)):
        balance = self.balance_3t(
            surface_temperature[i - 1, :], core_temperature[i - 1, :]
        )
        time_difference = offset[i] - offset[i - 1]
        average_temperature[i, :] = (
            average_temperature[i - 1, :] + time_difference * imc * balance
        )
        temperature_difference[i, :] = temperature_difference[i - 1, :] * (
            1.0 - time_difference / time_constant
        ) + (
            time_difference
            / time_constant
            * self.morgan_coefficients[0]
            * self.joule_heating.value(average_temperature[i, :])
        )
        core_temperature[i, :] = (
            average_temperature[i, :] + 0.5 * temperature_difference[i, :]
        )
        surface_temperature[i, :] = (
            average_temperature[i, :] - 0.5 * temperature_difference[i, :]
        )

    result = self._transient_temperature_results(
        offset,
        surface_temperature,
        average_temperature,
        core_temperature,
        return_power,
        n,
    )

    result = self._add_input_data_to_result(result)

    return result

update

update() -> None

Updates the solver's internal state by reinitializing several components and recalculating the Morgan coefficients. This method performs the following steps: 1. Extends the arguments to their maximum length. 2. Reinitializes the joule_heating, solar_heating, convective_cooling, radiative_cooling, and precipitation_cooling components using the updated arguments. 3. Recalculates the Morgan coefficients using the updated dimensions. 4. Compresses the arguments. Returns: None

Source code in src/thermohl/solver/slv3t.py

def update(self) -> None:
    """
    Updates the solver's internal state by reinitializing several components
    and recalculating the Morgan coefficients.
    This method performs the following steps:
    1. Extends the arguments to their maximum length.
    2. Reinitializes the `joule_heating`, `solar_heating`, `convective_cooling`, `radiative_cooling`, and `precipitation_cooling` components using the updated arguments.
    3. Recalculates the Morgan coefficients using the updated dimensions.
    4. Compresses the arguments.
    Returns:
        None
    """
    self.args.extend()
    self.joule_heating.__init__(**self.args.__dict__)
    self.solar_heating.__init__(**self.args.__dict__)
    self.convective_cooling.__init__(**self.args.__dict__)
    self.radiative_cooling.__init__(**self.args.__dict__)
    self.precipitation_cooling.__init__(**self.args.__dict__)
    self.morgan_coefficients = self._morgan_coefficients()
    self.args.compress()