thermal

SteadyIntensityResults

SteadyIntensityResults(input_data: dict | DataFrame)

Bases: ThermalSteadyResults

Parser for thermal steady-state intensity computation.

Parameters:

Name	Type	Description	Default
input_data	dict | DataFrame	Raw steady-state thermal results data.	required

Source code in src/mechaphlowers/core/models/cable/thermal.py

def __init__(self, input_data: dict | pd.DataFrame):
    """Initialize steady-state thermal results.

    Args:
        input_data (dict | pd.DataFrame): Raw steady-state thermal results data.
    """
    super().__init__(input_data)

parse_results staticmethod

parse_results(data: dict | DataFrame) -> DataFrame

Parse steady-state thermal results into a DataFrame.

Converts raw steady-state thermal output into standardized DataFrame format. If input is already a DataFrame, returns it as-is. Otherwise converts dict to DataFrame.

Parameters:

Name	Type	Description	Default
data	dict | DataFrame	Raw steady-state results as dictionary or DataFrame.	required

Returns:

Type	Description
DataFrame	Parsed results as a pandas DataFrame.

Source code in src/mechaphlowers/core/models/cable/thermal.py

@staticmethod
def parse_results(
    data: dict | pd.DataFrame,
) -> pd.DataFrame:
    """Parse steady-state thermal results into a DataFrame.

    Converts raw steady-state thermal output into standardized DataFrame format.
    If input is already a DataFrame, returns it as-is. Otherwise converts dict to DataFrame.

    Args:
        data: Raw steady-state results as dictionary or DataFrame.

    Returns:
        Parsed results as a pandas DataFrame.
    """
    if isinstance(data, pd.DataFrame):
        return data.copy()
    return pd.DataFrame(data)

SteadyTemperatureResults

SteadyTemperatureResults(input_data: dict | DataFrame)

Bases: ThermalSteadyResults

Parser for thermal steady-state temperature computation.

Parameters:

Name	Type	Description	Default
input_data	dict | DataFrame	Raw steady-state thermal results data.	required

Source code in src/mechaphlowers/core/models/cable/thermal.py

def __init__(self, input_data: dict | pd.DataFrame):
    """Initialize steady-state thermal results.

    Args:
        input_data (dict | pd.DataFrame): Raw steady-state thermal results data.
    """
    super().__init__(input_data)

parse_results staticmethod

parse_results(data: dict | DataFrame) -> DataFrame

Parse steady-state thermal results into a DataFrame.

Converts raw steady-state thermal output into standardized DataFrame format. If input is already a DataFrame, returns it as-is. Otherwise converts dict to DataFrame.

Parameters:

Name	Type	Description	Default
data	dict | DataFrame	Raw steady-state results as dictionary or DataFrame.	required

Returns:

Type	Description
DataFrame	Parsed results as a pandas DataFrame.

Source code in src/mechaphlowers/core/models/cable/thermal.py

@staticmethod
def parse_results(
    data: dict | pd.DataFrame,
) -> pd.DataFrame:
    """Parse steady-state thermal results into a DataFrame.

    Converts raw steady-state thermal output into standardized DataFrame format.
    If input is already a DataFrame, returns it as-is. Otherwise converts dict to DataFrame.

    Args:
        data: Raw steady-state results as dictionary or DataFrame.

    Returns:
        Parsed results as a pandas DataFrame.
    """
    if isinstance(data, pd.DataFrame):
        return data.copy()
    return pd.DataFrame(data)

ThermalEngine

ThermalEngine()

Thermal engine is a wrapper for cable thermal modeling.

Attributes:

Name	Type	Description
power_model		The power model used for thermal calculations.
heateq		The heat equation model used.
dict_input		Dictionary to store input parameters.
forecast		An instance of ThermalForecastArray for time series data.
target_temperature		Target temperature for steady-state calculations in celsius.

Source code in src/mechaphlowers/core/models/cable/thermal.py

def __init__(self):
    """Initialize ThermalEngine.

    Attributes:
        power_model: The power model used for thermal calculations.
        heateq: The heat equation model used.
        dict_input: Dictionary to store input parameters.
        forecast: An instance of ThermalForecastArray for time series data.
        target_temperature: Target temperature for steady-state calculations in celsius.
    """
    self.power_model = self.available_power_model.get("rte", ValueError)
    self.heateq = self.available_heat_equation.get("3tl", ValueError)
    self.dict_input = {}
    self.forecast = ThermalForecastArray()
    self.target_temperature = 65

normal_wind_mode property writable

normal_wind_mode

Get normal wind mode status.

Triggers normal_wind mode in models. Not implemented yet.

Raises:

Type	Description
NotImplementedError	This feature is not yet implemented.

wind_cable_angle property

wind_cable_angle: ndarray

Compute the angle between wind and cable direction.

Triggers ambient_wind_speed mode in models.

Returns:

Type	Description
ndarray	Angle in degrees between wind direction and cable azimuth.

compute_wind_attack_angle staticmethod

compute_wind_attack_angle(
    cable_azimuth: ndarray, wind_azimuth: ndarray
) -> ndarray

Compute the angle between wind and cable.

Parameters:

Name	Type	Description	Default
cable_azimuth	ndarray	azimuth of the cable, in degrees	required
wind_azimuth	ndarray	azimuth of the wind, in degrees	required

Returns:

Type	Description
ndarray	Angle in degrees between wind direction and cable azimuth.

Source code in src/mechaphlowers/core/models/cable/thermal.py

@staticmethod
def compute_wind_attack_angle(
    cable_azimuth: np.ndarray, wind_azimuth: np.ndarray
) -> np.ndarray:
    """Compute the angle between wind and cable.

    Args:
        cable_azimuth (np.ndarray): azimuth of the cable, in degrees
        wind_azimuth (np.ndarray): azimuth of the wind, in degrees

    Returns:
        Angle in degrees between wind direction and cable azimuth.
    """
    return np.rad2deg(
        np.arcsin(
            np.sin(
                np.deg2rad(np.abs(cable_azimuth - wind_azimuth) % 180.0)
            )
        )
    )

load

load()

Load or reload the thermal model, and checks the shape of the input parameters. Can be used if the input parameters are modified without using set().

Source code in src/mechaphlowers/core/models/cable/thermal.py

def load(self):
    """Load or reload the thermal model, and checks the shape of the input parameters.
    Can be used if the input parameters are modified without using set()."""
    check_inputs(**self.dict_input)
    self._load()

set

set(
    cable_array: CableArray,
    latitude: ndarray,
    longitude: ndarray,
    altitude: ndarray,
    azimuth: ndarray,
    month: ndarray,
    day: ndarray,
    hour: ndarray,
    intensity: ndarray,
    ambient_temp: ndarray,
    wind_speed: ndarray,
    wind_angle: ndarray,
    nebulosity: ndarray,
    solar_irradiance: ndarray | None = None,
)

Set input parameters for thermal calculations.

Parameters:

Name	Type	Description	Default
cable_array	CableArray	An instance of CableArray containing cable properties.	required
latitude	ndarray	Latitude values.	required
longitude	ndarray	Longitude values.	required
altitude	ndarray	Altitude values.	required
azimuth	ndarray	Azimuth values.	required
month	ndarray	Month values.	required
day	ndarray	Day values.	required
hour	ndarray	Hour values.	required
intensity	ndarray	Current intensity values.	required
ambient_temp	ndarray	Ambient temperature values.	required
wind_speed	ndarray	Wind speed values in m/s	required
wind_angle	ndarray	Wind angle values in degrees, clockwise from North.	required
nebulosity	ndarray	Nebulosity level (int from 0 to 8).	required
solar_irradiance	ndarray | None	Solar irradiance values (optional). Defaults to None.	None

Source code in src/mechaphlowers/core/models/cable/thermal.py

def set(
    self,
    cable_array: CableArray,
    latitude: np.ndarray,
    longitude: np.ndarray,
    altitude: np.ndarray,
    azimuth: np.ndarray,
    month: np.ndarray,
    day: np.ndarray,
    hour: np.ndarray,
    intensity: np.ndarray,
    ambient_temp: np.ndarray,
    wind_speed: np.ndarray,
    wind_angle: np.ndarray,
    nebulosity: np.ndarray,
    solar_irradiance: np.ndarray | None = None,
):
    """Set input parameters for thermal calculations.

    Args:
        cable_array (CableArray): An instance of CableArray containing cable properties.
        latitude (np.ndarray): Latitude values.
        longitude (np.ndarray): Longitude values.
        altitude (np.ndarray): Altitude values.
        azimuth (np.ndarray): Azimuth values.
        month (np.ndarray): Month values.
        day (np.ndarray): Day values.
        hour (np.ndarray): Hour values.
        intensity (np.ndarray): Current intensity values.
        ambient_temp (np.ndarray): Ambient temperature values.
        wind_speed (np.ndarray): Wind speed values in m/s
        wind_angle (np.ndarray): Wind angle values in degrees, clockwise from North.
        nebulosity (np.ndarray): Nebulosity level (int from 0 to 8).
        solar_irradiance (np.ndarray | None): Solar irradiance values (optional). Defaults to None.
    """
    # Handle optional solar_irradiance - create NaN array if not provided
    if solar_irradiance is None:
        solar_irradiance = np.full_like(latitude, np.nan, dtype=np.float64)

    # Normalize and validate all input parameters
    inputs, self._len = check_inputs(
        latitude=latitude,
        longitude=longitude,
        altitude=altitude,
        azimuth=azimuth,
        month=month,
        day=day,
        hour=hour,
        intensity=intensity,
        ambient_temp=ambient_temp,
        wind_speed=wind_speed,
        wind_angle=wind_angle,
        nebulosity=nebulosity,
        solar_irradiance=solar_irradiance,
    )

    if inputs.get("datetime_utc") is None:
        datetime_utc = [
            to_datetime(month, day, hour)
            for month, day, hour in zip(
                inputs["month"], inputs["day"], inputs["hour"]
            )
        ]
    else:
        datetime_utc = inputs.get("datetime_utc")  # type: ignore

    self.dict_input = {
        "measured_global_radiation": inputs["solar_irradiance"],
        "latitude": inputs["latitude"],
        "longitude": inputs["longitude"],
        "altitude": inputs["altitude"],
        "cable_azimuth": inputs["azimuth"],
        "datetime_utc": datetime_utc,
        "ambient_temperature": inputs["ambient_temp"],
        "wind_speed": inputs["wind_speed"],  # wind speed (m.s**-1)
        "wind_azimuth": inputs[
            "wind_angle"
        ],  # wind angle (deg, 0 means north)
        "nebulosity": inputs["nebulosity"],
        "transit": inputs["intensity"],
        "linear_mass": np.full(
            self._len, cable_array.data.linear_mass.iloc[0]
        ),
        "core_diameter": np.full(
            self._len, cable_array.data.diameter_heart.iloc[0]
        ),
        "outer_diameter": np.full(
            self._len, cable_array.data.diameter.iloc[0]
        ),
        "core_area": np.full(
            self._len, cable_array.data.section_heart.iloc[0]
        ),
        "outer_area": np.full(
            self._len, cable_array.data.section_conductor.iloc[0]
        ),
        "radial_thermal_conductivity": np.full(
            self._len, cable_array.data.radial_thermal_conductivity.iloc[0]
        ),
        "solar_absorptivity": np.full(
            self._len, cable_array.data.solar_absorption.iloc[0]
        ),
        "emissivity": np.full(
            self._len, cable_array.data.emissivity.iloc[0]
        ),
        "linear_resistance_dc_20c": np.full(
            self._len, cable_array.data.electric_resistance_20.iloc[0]
        ),
        "temperature_coeff_linear": np.full(
            self._len,
            cable_array.data.linear_resistance_temperature_coef.iloc[0],
        ),
        "magnetic_coeff": np.full(
            self._len,
            1.006 if cable_array.data.has_magnetic_heart.iloc[0] else 1.0,
        ),
        "magnetic_coeff_per_a": np.full(
            self._len,
            0.016 if cable_array.data.has_magnetic_heart.iloc[0] else 0.0,
        ),
    }
    self._load()
    logger.debug("Thermal attribute set")

steady_intensity

steady_intensity(
    target_temperature: ndarray | None = None,
) -> SteadyIntensityResults

Compute steady-state intensity results.

Returns:

Name	Type	Description
SteadyIntensityResults	SteadyIntensityResults	An instance containing steady-state intensity data.

Source code in src/mechaphlowers/core/models/cable/thermal.py

def steady_intensity(
    self, target_temperature: np.ndarray | None = None
) -> SteadyIntensityResults:
    """Compute steady-state intensity results.

    Returns:
        SteadyIntensityResults: An instance containing steady-state intensity data.
    """
    if target_temperature is not None:
        self.target_temperature = target_temperature

    return SteadyIntensityResults(
        self.thermal_model.steady_intensity(self.target_temperature)
    )

steady_temperature

steady_temperature(
    intensity: ndarray | None = None,
    return_uncertainty: bool = False,
) -> SteadyTemperatureResults

Compute steady-state temperature results.

Returns:

Name	Type	Description
SteadyTemperatureResults	SteadyTemperatureResults	An instance containing steady-state temperature data.

Source code in src/mechaphlowers/core/models/cable/thermal.py

def steady_temperature(
    self,
    intensity: np.ndarray | None = None,
    return_uncertainty: bool = False,
) -> SteadyTemperatureResults:
    """Compute steady-state temperature results.

    Returns:
        SteadyTemperatureResults: An instance containing steady-state temperature data.
    """
    logger.debug("Get steady_temperature()")
    if intensity is not None:
        self.dict_input["transit"] = intensity
        self.load()
    return SteadyTemperatureResults(
        self.thermal_model.steady_temperature(
            return_uncertainty=return_uncertainty
        )
    )

transient_temperature

transient_temperature(
    forecast_control: ThermalForecastArray | None = None,
) -> ThermalTransientResults

Compute transient temperature results.

Returns:

Name	Type	Description
ThermalTransientResults	ThermalTransientResults	An instance containing time-varying temperature data.

Source code in src/mechaphlowers/core/models/cable/thermal.py

def transient_temperature(
    self, forecast_control: ThermalForecastArray | None = None
) -> ThermalTransientResults:
    """Compute transient temperature results.

    Returns:
        ThermalTransientResults: An instance containing time-varying temperature data.
    """
    if forecast_control is not None:
        self.forecast = forecast_control

    return ThermalTransientResults(
        self.thermal_model.transient_temperature(offset=self.forecast.time)
    )

ThermalForecastArray

Array for input thermal forecast parameters.

ThermalResults

ThermalResults(input_data: dict | DataFrame)

Bases: ABC

Thermal results base class.

Source code in src/mechaphlowers/core/models/cable/thermal.py

def __init__(self, input_data: dict | pd.DataFrame):
    self.data = self.parse_results(input_data)

parse_results abstractmethod staticmethod

parse_results(data: dict | DataFrame) -> DataFrame

Parse raw thermal results into a standardized DataFrame format.

Parameters:

Name	Type	Description	Default
data	dict | DataFrame	Raw thermal results as dictionary or DataFrame.	required

Returns:

Type	Description
DataFrame	pd.DataFrame: Parsed results as a pandas DataFrame.

Source code in src/mechaphlowers/core/models/cable/thermal.py

@staticmethod
@abstractmethod
def parse_results(data: dict | pd.DataFrame) -> pd.DataFrame:
    """Parse raw thermal results into a standardized DataFrame format.

    Args:
        data (dict | pd.DataFrame): Raw thermal results as dictionary or DataFrame.

    Returns:
        pd.DataFrame: Parsed results as a pandas DataFrame.
    """
    pass

ThermalSteadyResults

ThermalSteadyResults(input_data: dict | DataFrame)

Bases: ThermalResults

Thermal steady-state results parser.

Parameters:

Name	Type	Description	Default
input_data	dict | DataFrame	Raw steady-state thermal results data.	required

Source code in src/mechaphlowers/core/models/cable/thermal.py

def __init__(self, input_data: dict | pd.DataFrame):
    """Initialize steady-state thermal results.

    Args:
        input_data (dict | pd.DataFrame): Raw steady-state thermal results data.
    """
    super().__init__(input_data)

parse_results staticmethod

parse_results(data: dict | DataFrame) -> DataFrame

Parse steady-state thermal results into a DataFrame.

Converts raw steady-state thermal output into standardized DataFrame format. If input is already a DataFrame, returns it as-is. Otherwise converts dict to DataFrame.

Parameters:

Name	Type	Description	Default
data	dict | DataFrame	Raw steady-state results as dictionary or DataFrame.	required

Returns:

Type	Description
DataFrame	Parsed results as a pandas DataFrame.

Source code in src/mechaphlowers/core/models/cable/thermal.py

@staticmethod
def parse_results(
    data: dict | pd.DataFrame,
) -> pd.DataFrame:
    """Parse steady-state thermal results into a DataFrame.

    Converts raw steady-state thermal output into standardized DataFrame format.
    If input is already a DataFrame, returns it as-is. Otherwise converts dict to DataFrame.

    Args:
        data: Raw steady-state results as dictionary or DataFrame.

    Returns:
        Parsed results as a pandas DataFrame.
    """
    if isinstance(data, pd.DataFrame):
        return data.copy()
    return pd.DataFrame(data)

ThermalTransientResults

ThermalTransientResults(input_data: dict | DataFrame)

Bases: ThermalResults

Thermal transient results class for transient temperature calculations.

Parameters:

Name	Type	Description	Default
input_data	dict | DataFrame	Raw transient thermal results data.	required

Source code in src/mechaphlowers/core/models/cable/thermal.py

def __init__(self, input_data: dict | pd.DataFrame):
    """Initialize transient thermal results.

    Args:
        input_data (dict | pd.DataFrame): Raw transient thermal results data.
    """
    super().__init__(input_data)

parse_results staticmethod

parse_results(data: dict | DataFrame) -> DataFrame

Parse transient thermal results into a time-series DataFrame.

Converts raw transient thermal output into a DataFrame with columns for time, cable ID, average temperature, surface temperature, and core temperature.

Parameters:

Name	Type	Description	Default
data	dict | DataFrame	Raw transient results dictionary or DataFrame.	required

Returns:

Type	Description
DataFrame	pd.DataFrame: DataFrame with columns: time, id, average_temperature, surface_temperature, core_temperature.

Raises:

Type	Description
TypeError	If input is a DataFrame (only dict format is supported).

Source code in src/mechaphlowers/core/models/cable/thermal.py

@staticmethod
def parse_results(data: dict | pd.DataFrame) -> pd.DataFrame:
    """Parse transient thermal results into a time-series DataFrame.

    Converts raw transient thermal output into a DataFrame with columns for
    time, cable ID, average temperature, surface temperature, and core temperature.

    Args:
        data (dict | pd.DataFrame): Raw transient results dictionary or DataFrame.

    Returns:
        pd.DataFrame: DataFrame with columns: time, id, average_temperature,
            surface_temperature, core_temperature.

    Raises:
        TypeError: If input is a DataFrame (only dict format is supported).
    """
    if isinstance(data, pd.DataFrame):
        raise TypeError(
            "DataFrame input not supported for transient results parsing."
        )
    input_size = data["average_temperature"].shape
    return pd.DataFrame(
        {
            "time": np.tile(data["time"], input_size[1]),
            "id": np.tile(
                np.arange(input_size[1]), (input_size[0], 1)
            ).T.flatten(),
            "average_temperature": data["average_temperature"].T.flatten(),
            "surface_temperature": data["surface_temperature"].T.flatten(),
            "core_temperature": data["core_temperature"].T.flatten(),
        }
    )

check_inputs

check_inputs(
    month: ndarray[Any, dtype[integer]] | None = None,
    day: ndarray[Any, dtype[integer]] | None = None,
    hour: ndarray[Any, dtype[integer] | dtype[floating]]
    | None = None,
    datetime_utc: list[datetime] | None = None,
    nebulosity: ndarray[
        Any, dtype[integer] | dtype[floating]
    ]
    | None = None,
    **kwargs: ndarray[Any, Any] | list[datetime],
) -> tuple[
    dict[str, ndarray[Any, Any] | list[datetime]], int
]

Validate input parameters.

Ensures all inputs are numpy arrays with the same size and that datetime-related inputs have the right type. Also ensures that month, day and hour, if given, are in the right range.

Parameters:

Name	Type	Description	Default
**kwargs	ndarray[Any, Any] | list[datetime]	Input parameters as numpy arrays.	{}

Returns:

Name	Type	Description
tuple	tuple[dict[str, ndarray[Any, Any] | list[datetime]], int]	A tuple containing: - dict: Dictionary with the input numpy arrays. - int: The common length of all arrays.

Raises:

Type	Description
ValueError	If array inputs have incompatible sizes.
TypeError	If any input is not a numpy array.

Source code in src/mechaphlowers/core/models/cable/thermal.py

def check_inputs(
    month: np.ndarray[Any, np.dtype[np.integer]] | None = None,
    day: np.ndarray[Any, np.dtype[np.integer]] | None = None,
    hour: np.ndarray[Any, np.dtype[np.integer] | np.dtype[np.floating]]
    | None = None,
    datetime_utc: list[datetime] | None = None,
    nebulosity: np.ndarray[Any, np.dtype[np.integer] | np.dtype[np.floating]]
    | None = None,
    **kwargs: np.ndarray[Any, Any] | list[datetime],
) -> tuple[dict[str, np.ndarray[Any, Any] | list[datetime]], int]:
    """Validate input parameters.

    Ensures all inputs are numpy arrays with the same size and that
    datetime-related inputs have the right type. Also ensures that
    month, day and hour, if given, are in the right range.

    Args:
        **kwargs: Input parameters as numpy arrays.

    Returns:
        tuple: A tuple containing:
            - dict: Dictionary with the input numpy arrays.
            - int: The common length of all arrays.

    Raises:
        ValueError: If array inputs have incompatible sizes.
        TypeError: If any input is not a numpy array.
    """

    array_length: int | None = None

    if nebulosity is not None:
        kwargs["nebulosity"] = nebulosity

    for key, value in kwargs.items():
        if not isinstance(value, np.ndarray):
            raise TypeError(
                f"Expected numpy array for '{key}', got {type(value).__name__}."
            )

        # Track and validate the length of array inputs
        if array_length is None:
            array_length = value.size
        elif value.size != array_length:
            raise ValueError(
                f"All array inputs must have the same length. "
                f"Expected {array_length}, got {value.size} for {key}."
            )

    array_length = check_datetime_arguments(
        array_length,
        month=month,
        day=day,
        hour=hour,
        datetime_utc=datetime_utc,
    )

    check_nebulosity_range(nebulosity)

    if month is not None:
        kwargs["month"] = month
    if day is not None:
        kwargs["day"] = day
    if hour is not None:
        kwargs["hour"] = hour
    if datetime_utc is not None:
        kwargs["datetime_utc"] = datetime_utc

    return kwargs, array_length

to_datetime

to_datetime(
    month: integer, day: integer, hour: floating
) -> datetime

Convert month, day, hour to a datetime object.

Parameters:

Name	Type	Description	Default
month	integer	Month value ([1-12]).	required
day	integer	Day value ([1-31]).	required
hour	floating	Hour value ([0-24[). Can include non-integer hours (e.g. 14.5 for 2:30 PM).	required

Returns:

Name	Type	Description
datetime	datetime	A datetime object representing the given month, day, and hour.

Source code in src/mechaphlowers/core/models/cable/thermal.py

def to_datetime(
    month: np.integer,
    day: np.integer,
    hour: np.floating,
) -> datetime:
    """Convert month, day, hour to a datetime object.

    Args:
        month (np.integer): Month value ([1-12]).
        day (np.integer): Day value ([1-31]).
        hour (np.floating): Hour value ([0-24[). Can include non-integer hours (e.g. 14.5 for 2:30 PM).

    Returns:
        datetime: A datetime object representing the given month, day, and hour.
    """
    return datetime(
        1970,  # Arbitrary year since it's not used in calculations
        month,
        day,
        hour=floor(hour),
        minute=floor((hour % 1) * 60),
        second=floor(((hour % 1) * 60) % 1 * 60),
        microsecond=floor((((hour % 1) * 60) % 1 * 60) % 1 * 1000000),
    )