Skip to content

Model input and output schemas

Modules:

Name Description
input_profile
output_profile

Classes:

Name Description
InputProfile

Class containing the temperature and load profiles of two winding transformers for the thermal model Model().
ThreeWindingInputProfile

Class for three-winding transformer input profiles.
OutputProfile

Class containing the output data for the hot-spot and top-oil temperature calculations.

InputProfile

Bases: BaseInputProfile

Class containing the temperature and load profiles of two winding transformers for the thermal model Model().

This class is also capable of converting the results to a single dataframe with the timestamp as the index for convenience.

Attributes:

Name Type Description
datetime_index NDArray[datetime64]

A 1d array with the datetime index for the profiles.
load_profile NDArray[float64]

A 1d array with the load profile for the transformer.
ambient_temperature_profile NDArray[float64]

A 1d array with the ambient temperature profile for the transformer.

Methods:

Name Description
create

Create an InputProfile.
from_dataframe

Create an InputProfile from a dataframe.

load_profile_array property 

load_profile_array: NDArray[float64]

Return the single load profile for the transformer.

create classmethod 

create(
    datetime_index: Collection[datetime],
    load_profile: Collection[float],
    ambient_temperature_profile: Collection[float],
    top_oil_temperature_profile: Collection[float]
    | None = None,
) -> Self

Create an InputProfile.

Parameters:

Name Type Description Default
datetime_index Collection[datetime]

The datetime index for the profiles.

 required
load_profile Collection[float]

The load profile for the transformer.

 required
ambient_temperature_profile Collection[float]

The ambient temperature profile for the transformer.

 required
top_oil_temperature_profile Collection[float] | None

The top oil temperature profile for the transformer (optional).

 None

Returns:

Type Description
Self

An InputProfile object.
Creating an InputProfile from collections. 
>>> from datetime import datetime
>>> from transformer_thermal_model.schemas import InputProfile

>>> 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,
... )
>>> input_profile
InputProfile(datetime_index=array(['2023-01-01T00:00:00.000000',
'2023-01-01T01:00:00.000000', '2023-01-01T02:00:00.000000'],
dtype='datetime64[us]'), ambient_temperature_profile=array([25. , 24.5, 24. ]),
top_oil_temperature_profile=None, load_profile=array([0.8, 0.9, 1. ]))

Example: Directly creating an InputProfile object using numpy arrays. 

>>> import numpy as np
>>> from datetime import datetime
>>> from transformer_thermal_model.schemas import InputProfile

>>> input_profile = InputProfile(
...     datetime_index=np.array(
...         [
...             datetime(2023, 1, 1, 0, 0),
...             datetime(2023, 1, 1, 1, 0),
...             datetime(2023, 1, 1, 2, 0)
...         ],
...         dtype=np.datetime64,
...     ),
...     load_profile=np.array([0.8, 0.9, 1.0], dtype=float),
...     ambient_temperature_profile=np.array([25.0, 24.5, 24.0], dtype=float)
... )
>>> input_profile
InputProfile(datetime_index=array(['2023-01-01T00:00:00.000000',
'2023-01-01T01:00:00.000000', '2023-01-01T02:00:00.000000'],
dtype='datetime64[us]'), ambient_temperature_profile=array([25. , 24.5, 24. ]),
top_oil_temperature_profile=None, load_profile=array([0.8, 0.9, 1. ]))
Example: Creating an InputProfile including the top oil temperature. 
>>> from datetime import datetime
>>> from transformer_thermal_model.schemas import InputProfile

>>> 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]
>>> top_oil_temperature = [37.0, 36.5, 36.0]
>>> input_profile = InputProfile.create(
...     datetime_index=datetime_index,
...     load_profile=load_profile,
...     ambient_temperature_profile=ambient_temperature_profile,
...     top_oil_temperature_profile=top_oil_temperature,
... )
>>> input_profile
InputProfile(datetime_index=array(['2023-01-01T00:00:00.000000', '2023-01-01T01:00:00.000000',
'2023-01-01T02:00:00.000000'], dtype='datetime64[us]'),
ambient_temperature_profile=array([25. , 24.5, 24. ]),
top_oil_temperature_profile=array([37. , 36.5, 36. ]), load_profile=array([0.8, 0.9, 1. ]))

Source code in transformer_thermal_model/schemas/thermal_model/input_profile.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
@classmethod
def create(
    cls,
    datetime_index: Collection[datetime],
    load_profile: Collection[float],
    ambient_temperature_profile: Collection[float],
    top_oil_temperature_profile: Collection[float] | None = None,
) -> Self:
    """Create an InputProfile.

    Args:
        datetime_index: The datetime index for the profiles.
        load_profile: The load profile for the transformer.
        ambient_temperature_profile: The ambient temperature profile for the transformer.
        top_oil_temperature_profile: The top oil temperature profile for the transformer (optional).

    Returns:
        An InputProfile object.

    Example: Creating an InputProfile from collections.
        ```python
        >>> from datetime import datetime
        >>> from transformer_thermal_model.schemas import InputProfile

        >>> 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,
        ... )
        >>> input_profile
        InputProfile(datetime_index=array(['2023-01-01T00:00:00.000000',
        '2023-01-01T01:00:00.000000', '2023-01-01T02:00:00.000000'],
        dtype='datetime64[us]'), ambient_temperature_profile=array([25. , 24.5, 24. ]),
        top_oil_temperature_profile=None, load_profile=array([0.8, 0.9, 1. ]))

        ```
    Example: Directly creating an InputProfile object using numpy arrays.
        ```python
        >>> import numpy as np
        >>> from datetime import datetime
        >>> from transformer_thermal_model.schemas import InputProfile

        >>> input_profile = InputProfile(
        ...     datetime_index=np.array(
        ...         [
        ...             datetime(2023, 1, 1, 0, 0),
        ...             datetime(2023, 1, 1, 1, 0),
        ...             datetime(2023, 1, 1, 2, 0)
        ...         ],
        ...         dtype=np.datetime64,
        ...     ),
        ...     load_profile=np.array([0.8, 0.9, 1.0], dtype=float),
        ...     ambient_temperature_profile=np.array([25.0, 24.5, 24.0], dtype=float)
        ... )
        >>> input_profile
        InputProfile(datetime_index=array(['2023-01-01T00:00:00.000000',
        '2023-01-01T01:00:00.000000', '2023-01-01T02:00:00.000000'],
        dtype='datetime64[us]'), ambient_temperature_profile=array([25. , 24.5, 24. ]),
        top_oil_temperature_profile=None, load_profile=array([0.8, 0.9, 1. ]))

        ```
    Example: Creating an InputProfile including the top oil temperature.
        ```python
        >>> from datetime import datetime
        >>> from transformer_thermal_model.schemas import InputProfile

        >>> 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]
        >>> top_oil_temperature = [37.0, 36.5, 36.0]
        >>> input_profile = InputProfile.create(
        ...     datetime_index=datetime_index,
        ...     load_profile=load_profile,
        ...     ambient_temperature_profile=ambient_temperature_profile,
        ...     top_oil_temperature_profile=top_oil_temperature,
        ... )
        >>> input_profile
        InputProfile(datetime_index=array(['2023-01-01T00:00:00.000000', '2023-01-01T01:00:00.000000',
        '2023-01-01T02:00:00.000000'], dtype='datetime64[us]'),
        ambient_temperature_profile=array([25. , 24.5, 24. ]),
        top_oil_temperature_profile=array([37. , 36.5, 36. ]), load_profile=array([0.8, 0.9, 1. ]))

        ```
    """
    return cls(
        datetime_index=np.array(datetime_index, dtype=np.datetime64),
        load_profile=np.array(load_profile, dtype=float),
        ambient_temperature_profile=np.array(ambient_temperature_profile, dtype=float),
        top_oil_temperature_profile=(
            np.array(top_oil_temperature_profile, dtype=float) if top_oil_temperature_profile is not None else None
        ),
    )

from_dataframe classmethod 

from_dataframe(df: DataFrame) -> Self

Create an InputProfile from a dataframe.

Parameters:

Name Type Description Default
df DataFrame

The dataframe containing the profiles. The dataframe should have a datetime index and three columns: - 'datetime_index': The datetime index for the profiles. - 'load_profile': The load profile for the transformer. - 'ambient_temperature_profile': The ambient temperature profile for the transformer.

 required

Returns:

Type Description
Self

An InputProfile object.
Source code in transformer_thermal_model/schemas/thermal_model/input_profile.py 
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
@classmethod
def from_dataframe(cls, df: pd.DataFrame) -> Self:
    """Create an InputProfile from a dataframe.

    Args:
        df: The dataframe containing the profiles. The dataframe should have a datetime index and three columns:
            - 'datetime_index': The datetime index for the profiles.
            - 'load_profile': The load profile for the transformer.
            - 'ambient_temperature_profile': The ambient temperature profile for the transformer.

    Returns:
        An InputProfile object.

    """
    required_columns = {"datetime_index", "load_profile", "ambient_temperature_profile"}
    missing_columns = required_columns - set(df.columns)
    if missing_columns:
        raise ValueError(f"The dataframe is missing the following required columns: {', '.join(missing_columns)}")

    return cls(
        datetime_index=df["datetime_index"].to_numpy(),
        load_profile=df["load_profile"].to_numpy(),
        ambient_temperature_profile=df["ambient_temperature_profile"].to_numpy(),
        top_oil_temperature_profile=df["top_oil_temperature_profile"].to_numpy()
        if "top_oil_temperature_profile" in df.columns
        else None,
    )

ThreeWindingInputProfile

Bases: BaseInputProfile

Class for three-winding transformer input profiles.

This class extends InputProfile to include three load profiles for three-winding transformers. It ensures that all three load profiles are provided and have the same length as the ambient temperature profile.

Methods:

Name Description
create

Create a ThreeWindingInputProfile from datetime index, ambient temperature profile, and three load profiles.

Attributes:

Name Type Description
load_profile_array NDArray[float64]

Return an array with shape (3,n) of the three load profiles (high, middle, low voltage sides).

load_profile_array property 

load_profile_array: NDArray[float64]

Return an array with shape (3,n) of the three load profiles (high, middle, low voltage sides).

create classmethod 

create(
    datetime_index: Collection[datetime],
    ambient_temperature_profile: Collection[float],
    load_profile_high_voltage_side: Collection[float],
    load_profile_middle_voltage_side: Collection[float],
    load_profile_low_voltage_side: Collection[float],
    top_oil_temperature_profile: Collection[float]
    | None = None,
) -> Self

Create a ThreeWindingInputProfile from datetime index, ambient temperature profile, and three load profiles.

Parameters:

Name Type Description Default
datetime_index Collection[datetime]

The datetime index for the profiles.

 required
ambient_temperature_profile Collection[float]

The ambient temperature profile for the transformer.

 required
load_profile_high_voltage_side Collection[float]

Load profile for the high voltage side.

 required
load_profile_middle_voltage_side Collection[float]

Load profile for the middle voltage side.

 required
load_profile_low_voltage_side Collection[float]

Load profile for the low voltage side.

 required
top_oil_temperature_profile Collection[float] | None

The top oil temperature profile for the transformer (optional).

 None

Returns:

Type Description
Self

A ThreeWindingInputProfile object.
Creating a ThreeWindingInputProfile from collections. 
>>> import numpy as np
>>> from datetime import datetime
>>> from transformer_thermal_model.schemas import ThreeWindingInputProfile

>>> input_profile = ThreeWindingInputProfile.create(
...     datetime_index=np.array(
...         [
...             datetime(2023, 1, 1, 0, 0),
...             datetime(2023, 1, 1, 1, 0),
...             datetime(2023, 1, 1, 2, 0)
...         ],
...         dtype=np.datetime64,
...     ),
...     load_profile_high_voltage_side=np.array([0.8, 0.9, 1.0], dtype=float),
...     load_profile_middle_voltage_side=np.array([0.7, 0.8, 0.9], dtype=float),
...     load_profile_low_voltage_side=np.array([0.6, 0.7, 0.8], dtype=float),
...     ambient_temperature_profile=np.array([25.0, 24.5, 24.0], dtype=float)
... )
>>> input_profile
ThreeWindingInputProfile(datetime_index=array(['2023-01-01T00:00:00.000000', '2023-01-01T01:00:00.000000',
'2023-01-01T02:00:00.000000'], dtype='datetime64[us]'),
ambient_temperature_profile=array([25. , 24.5, 24. ]),
top_oil_temperature_profile=None,
load_profile_high_voltage_side=array([0.8, 0.9, 1. ]),
load_profile_middle_voltage_side=array([0.7, 0.8, 0.9]),
load_profile_low_voltage_side=array([0.6, 0.7, 0.8]))
Source code in transformer_thermal_model/schemas/thermal_model/input_profile.py 
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
@classmethod
def create(
    cls,
    datetime_index: Collection[datetime],
    ambient_temperature_profile: Collection[float],
    load_profile_high_voltage_side: Collection[float],
    load_profile_middle_voltage_side: Collection[float],
    load_profile_low_voltage_side: Collection[float],
    top_oil_temperature_profile: Collection[float] | None = None,
) -> Self:
    """Create a ThreeWindingInputProfile from datetime index, ambient temperature profile, and three load profiles.

    Args:
        datetime_index: The datetime index for the profiles.
        ambient_temperature_profile: The ambient temperature profile for the transformer.
        load_profile_high_voltage_side: Load profile for the high voltage side.
        load_profile_middle_voltage_side: Load profile for the middle voltage side.
        load_profile_low_voltage_side: Load profile for the low voltage side.
        top_oil_temperature_profile: The top oil temperature profile for the transformer (optional).

    Returns:
        A ThreeWindingInputProfile object.

    Example: Creating a ThreeWindingInputProfile from collections.
        ```python
        >>> import numpy as np
        >>> from datetime import datetime
        >>> from transformer_thermal_model.schemas import ThreeWindingInputProfile

        >>> input_profile = ThreeWindingInputProfile.create(
        ...     datetime_index=np.array(
        ...         [
        ...             datetime(2023, 1, 1, 0, 0),
        ...             datetime(2023, 1, 1, 1, 0),
        ...             datetime(2023, 1, 1, 2, 0)
        ...         ],
        ...         dtype=np.datetime64,
        ...     ),
        ...     load_profile_high_voltage_side=np.array([0.8, 0.9, 1.0], dtype=float),
        ...     load_profile_middle_voltage_side=np.array([0.7, 0.8, 0.9], dtype=float),
        ...     load_profile_low_voltage_side=np.array([0.6, 0.7, 0.8], dtype=float),
        ...     ambient_temperature_profile=np.array([25.0, 24.5, 24.0], dtype=float)
        ... )
        >>> input_profile
        ThreeWindingInputProfile(datetime_index=array(['2023-01-01T00:00:00.000000', '2023-01-01T01:00:00.000000',
        '2023-01-01T02:00:00.000000'], dtype='datetime64[us]'),
        ambient_temperature_profile=array([25. , 24.5, 24. ]),
        top_oil_temperature_profile=None,
        load_profile_high_voltage_side=array([0.8, 0.9, 1. ]),
        load_profile_middle_voltage_side=array([0.7, 0.8, 0.9]),
        load_profile_low_voltage_side=array([0.6, 0.7, 0.8]))

        ```
    """
    return cls(
        datetime_index=np.array(datetime_index, dtype=np.datetime64),
        ambient_temperature_profile=np.array(ambient_temperature_profile, dtype=float),
        load_profile_high_voltage_side=np.array(load_profile_high_voltage_side, dtype=float),
        load_profile_middle_voltage_side=np.array(load_profile_middle_voltage_side, dtype=float),
        load_profile_low_voltage_side=np.array(load_profile_low_voltage_side, dtype=float),
        top_oil_temperature_profile=np.array(top_oil_temperature_profile, dtype=float)
        if top_oil_temperature_profile is not None
        else None,
    )

OutputProfile

Bases: BaseModel

Class containing the output data for the hot-spot and top-oil temperature calculations.

The class consists of the top-oil and hot-spot temperature profiles. These have the datetime index as the timestamp that link both of these series together.

Additionally, this class has a helper function to convert the output to a single dataframe for convenience.

Methods:

Name Description
convert_to_dataframe

Process the two pandas Series and convert them to a single dataframe, linked by the timestamp.

convert_to_dataframe 

convert_to_dataframe() -> DataFrame

Process the two pandas Series and convert them to a single dataframe, linked by the timestamp.

Source code in transformer_thermal_model/schemas/thermal_model/output_profile.py 
21
22
23
24
25
26
27
28
29
30
def convert_to_dataframe(self) -> pd.DataFrame:
    """Process the two pandas Series and convert them to a single dataframe, linked by the timestamp."""
    df = pd.DataFrame(
        {
            "timestamp": self.top_oil_temp_profile.index,
            "top_oil_temperature": self.top_oil_temp_profile,
            "hot_spot_temperature": self.hot_spot_temp_profile,
        }
    )
    return df