Skip to content

Model

A thermal model to calculate transformer temperatures under specified load and ambient temperature profiles.

Initialising a transformer model with a temperature simulation profile 
>>> from datetime import datetime
>>> from transformer_thermal_model.cooler import CoolerType
>>> from transformer_thermal_model.schemas import InputProfile, UserTransformerSpecifications
>>> from transformer_thermal_model.transformer import PowerTransformer
>>> from transformer_thermal_model.model import Model

>>> # First, we create the input profile
>>> datetime_index = [
...     datetime(2023, 1, 1, 0, 0),
...     datetime(2023, 1, 1, 1, 0),
...     datetime(2023, 1, 1, 2, 0),
... ]
>>> load_profile = [0.8, 0.9, 1.0]
>>> ambient_temperature_profile = [25.0, 24.5, 24.0]
>>> input_profile = InputProfile.create(
...     datetime_index=datetime_index,
...     load_profile=load_profile,
...     ambient_temperature_profile=ambient_temperature_profile,
... )
>>> # Then, we create the transformer with some basic specifications
>>> tr_specs = UserTransformerSpecifications(
...     load_loss=1000,  # Transformer load loss [W]
...     nom_load_sec_side=1500,  # Transformer nominal current secondary side [A]
...     no_load_loss=200,  # Transformer no-load loss [W]
...     amb_temp_surcharge=20,  # Ambient temperature surcharge [K]
... )
>>> tr = PowerTransformer(
...     user_specs=tr_specs,
...     cooling_type=CoolerType.ONAN
... )
>>> # Finally, we can use the input profile in the transformer model
>>> model = Model(temperature_profile=input_profile, transformer=tr)

Attributes:

Name Type Description
transformer Transformer

The transformer that the model will use to calculate the temperatures.
data DataFrame

The data that the model will use to calculate the top-oil and hot-spottemperatures.
init_top_oil_temp float | None

The initial top-oil temperature. Defaults to None. If this is provided, will start the calculation with this temperature. If not provided, will start the calculation with the first value of the ambient temperature profile. will start the calculation with this temperature. If not provided, will start the calculation with the first value of the ambient temperature profile.
hot_spot_temp_profile Series

The modeled hot-spot temperature profile.
top_oil_temp_profile Series

The modeled top-oil temperature profile.

Parameters:

Name Type Description Default
temperature_profile InputProfile

The temperature profile for the model.

 required
transformer Transformer

The transformer object.

 required
init_top_oil_temp float | None

The initial top-oil temperature. Defaults to None. If this is provided, will start the calculation with this temperature. If not provided, will start the calculation with the first value of the ambient temperature profile. will start the calculation with this temperature. If not provided, will start the calculation with the first value of the ambient temperature profile.

 None
Source code in transformer_thermal_model/model/thermal_model.py 
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def __init__(
    self,
    temperature_profile: BaseInputProfile,
    transformer: Transformer,
    init_top_oil_temp: float | None = None,
) -> None:
    """Initialize the thermal model.

    Args:
        temperature_profile (InputProfile): The temperature profile for the model.
        transformer (Transformer): The transformer object.
        init_top_oil_temp (float | None): The initial top-oil temperature. Defaults to None. If this is provided,
            will start the calculation with this temperature. If not provided, will start the calculation
            with the first value of the ambient temperature profile.
            will start the calculation with this temperature. If not provided, will start the calculation
            with the first value of the ambient temperature profile.

    """
    logger.info("Initializing the thermal model.")
    logger.info(f"First timestamp: {temperature_profile.datetime_index[0]}")
    logger.info(f"Last timestamp: {temperature_profile.datetime_index[-1]}")
    logger.info(f"Amount of data points: {len(temperature_profile)}")
    logger.info(f"Max load: {np.max(temperature_profile.load_profile_array)}")
    self.transformer = transformer
    self.data = temperature_profile
    self.init_top_oil_temp = init_top_oil_temp

run 

run(
    force_use_ambient_temperature: bool = False,
) -> OutputProfile

Calculate the top-oil and hot-spot temperatures for the provided Transformer object.

This method prepares the calculation inputs, calculates intermediate factors, and computes the top-oil and hot-spot temperature profiles for the transformer based on the provided load and internal parameters. If the top oil temperature is provided in the temperature_profile it gets priority over the ambient temperature. The ambient temperature is then ignored. You can change this behaviour using the force_use_ambient_temperature parameter.

Parameters:

Name Type Description Default
force_use_ambient_temperature bool

Use the ambient temperature to perform the calculation, even if the top oil temperature is given (optional, False by default)

 False

Returns:

Name Type Description
OutputProfile OutputProfile

Object containing the top-oil and hot-spot temperature profiles.
Source code in transformer_thermal_model/model/thermal_model.py 
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
def run(self, force_use_ambient_temperature: bool = False) -> OutputProfile:
    """Calculate the top-oil and hot-spot temperatures for the provided Transformer object.

    This method prepares the calculation inputs, calculates intermediate factors, and computes
    the top-oil and hot-spot temperature profiles for the transformer based on the provided
    load and internal parameters. If the top oil temperature is provided in the `temperature_profile` it gets
    priority over the ambient temperature. The ambient temperature is then ignored. You can change this behaviour
    using the `force_use_ambient_temperature` parameter.

    Args:
        force_use_ambient_temperature:
            Use the ambient temperature to perform the calculation,
            even if the top oil temperature is given (optional, False by default)

    Returns:
        OutputProfile: Object containing the top-oil and hot-spot temperature profiles.

    """
    logger.info("Running the thermal model.")

    # decide if we use the top oil or ambient temperature as input and perform basic validation
    use_top_oil = not force_use_ambient_temperature and self.data.top_oil_temperature_profile is not None

    dt = self._get_time_step()
    load = self.data.load_profile_array
    t_internal = self._get_internal_temp()

    f1 = self._calculate_f1(dt)
    f2_windings = self._calculate_f2_winding(dt)
    f2_oil = self._calculate_f2_oil(dt)
    top_k = self.transformer._end_temperature_top_oil(load)
    static_hot_spot_incr = self._calculate_static_hot_spot_increase(load)

    if use_top_oil and self.data.top_oil_temperature_profile is not None:
        top_oil_temp_profile = self.data.top_oil_temperature_profile
    else:
        top_oil_temp_profile = self._calculate_top_oil_temp_profile(t_internal, f1, top_k)
    hot_spot_temp_profile = self._calculate_hot_spot_temp_profile(
        load, top_oil_temp_profile, static_hot_spot_incr, f2_windings, f2_oil
    )
    logger.info("The calculation with the Thermal model is completed.")
    logger.info(f"Max top-oil temperature: {np.max(top_oil_temp_profile)}")
    logger.info(f"Max hot-spot temperature: {np.max(hot_spot_temp_profile)}")

    if type(self.transformer) is ThreeWindingTransformer:
        return OutputProfile(
            top_oil_temp_profile=pd.Series(top_oil_temp_profile, index=self.data.datetime_index),
            hot_spot_temp_profile=pd.DataFrame(
                hot_spot_temp_profile.transpose(),
                columns=["low_voltage_side", "middle_voltage_side", "high_voltage_side"],
                index=self.data.datetime_index,
            ),
        )
    else:
        # For a two winding transformer, hot_spot_temp_profile is a Series
        return OutputProfile(
            top_oil_temp_profile=pd.Series(top_oil_temp_profile, index=self.data.datetime_index),
            hot_spot_temp_profile=pd.Series(hot_spot_temp_profile, index=self.data.datetime_index),
        )