Skip to content

Specifications

Transformer specifications

A transformer object in our package needs to be initiated using a set of specifications. A user will typically only interact with UserTransformerSpecifications. The DefaultTransformerSpecifications are used to set the Transformer.defaults values. The TransformerSpecifications is created to make sure the UserTransformerSpecifications and the DefaultTransformerSpecifications are neatly combined.

Classes:

Name Description
WindingSpecifications

The specifications for a single winding of a transformer.
BaseUserTransformerSpecifications

The base transformer specifications that the user must and can provide.
UserTransformerSpecifications

An extended version of the base transformer specifications for power and distribution transformers.
UserThreeWindingTransformerSpecifications

An extended version of the base transformer specifications for three-winding transformers.
BaseDefaultTransformerSpecifications

The default transformer specifications that will be defined when the user does not provide them.
DefaultTransformerSpecifications

The default specifications that are specific to a power or distribution transformer.
ThreeWindingTransformerDefaultSpecifications

The default specifications that are specific to a three-winding transformer.
BaseTransformerSpecifications

Base Class containing transformer specifications.
TransformerSpecifications

Class containing transformer specifications.
ThreeWindingTransformerSpecifications

The transformer specifications that are specific to a three-winding transformer.

WindingSpecifications

Bases: BaseModel

The specifications for a single winding of a transformer.

BaseUserTransformerSpecifications

Bases: BaseModel

The base transformer specifications that the user must and can provide.

If any of the optional values are provided, they will overwrite the defaults that are set in the respective Transformer class.

UserTransformerSpecifications

Bases: BaseUserTransformerSpecifications

An extended version of the base transformer specifications for power and distribution transformers.

If any of the optional values are provided, they will overwrite the defaults that are set in the respective Transformer class.

UserThreeWindingTransformerSpecifications

Bases: BaseUserTransformerSpecifications

An extended version of the base transformer specifications for three-winding transformers.

BaseDefaultTransformerSpecifications

Bases: BaseModel

The default transformer specifications that will be defined when the user does not provide them.

Each Transformer object has a class variable defaults that contains the default transformer specifications.

DefaultTransformerSpecifications

Bases: BaseDefaultTransformerSpecifications

The default specifications that are specific to a power or distribution transformer.

ThreeWindingTransformerDefaultSpecifications

Bases: BaseDefaultTransformerSpecifications

The default specifications that are specific to a three-winding transformer.

For now this contains no additional elements, this is for future expansion.

BaseTransformerSpecifications

Bases: BaseModel

Base Class containing transformer specifications.

Attributes:

Name Type Description
nominal_load_array ndarray

Return the nominal loads as a numpy array.
winding_oil_gradient_array ndarray

Return the winding oil gradient as a numpy array.
time_const_windings_array ndarray

Return the winding time constant as a numpy array.
hot_spot_fac_array ndarray

Return the hotspot factor as a numpy array.

nominal_load_array property 

nominal_load_array: ndarray

Return the nominal loads as a numpy array.

winding_oil_gradient_array property 

winding_oil_gradient_array: ndarray

Return the winding oil gradient as a numpy array.

time_const_windings_array property 

time_const_windings_array: ndarray

Return the winding time constant as a numpy array.

hot_spot_fac_array property 

hot_spot_fac_array: ndarray

Return the hotspot factor as a numpy array.

TransformerSpecifications

Bases: BaseTransformerSpecifications

Class containing transformer specifications.

This class is a combination of the mandatory user-provided specifications and the default transformer specifications. Should the user provide any of the optional specifications, they will override the default specifications, via the create class method.

Methods:

Name Description
create

Create the transformer specifications from the defaults and the user specifications.

Attributes:

Name Type Description
nominal_load_array ndarray

Return the nominal loads as a numpy array.
winding_oil_gradient_array ndarray

Return the winding oil gradient as a numpy array.
time_const_windings_array ndarray

Return the winding time constant as a numpy array.
hot_spot_fac_array ndarray

Return the hotspot factor as a numpy array.

nominal_load_array property 

nominal_load_array: ndarray

Return the nominal loads as a numpy array.

winding_oil_gradient_array property 

winding_oil_gradient_array: ndarray

Return the winding oil gradient as a numpy array.

time_const_windings_array property 

time_const_windings_array: ndarray

Return the winding time constant as a numpy array.

hot_spot_fac_array property 

hot_spot_fac_array: ndarray

Return the hotspot factor as a numpy array.

create classmethod 

create(
    defaults: DefaultTransformerSpecifications,
    user: UserTransformerSpecifications,
) -> TransformerSpecifications

Create the transformer specifications from the defaults and the user specifications.

Source code in transformer_thermal_model/schemas/specifications/transformer.py 
202
203
204
205
206
207
208
209
210
@classmethod
def create(
    cls, defaults: DefaultTransformerSpecifications, user: UserTransformerSpecifications
) -> "TransformerSpecifications":
    """Create the transformer specifications from the defaults and the user specifications."""
    data = defaults.model_dump()
    data.update(user.model_dump(exclude_none=True))
    logger.info("Complete transformer specifications: %s", data)
    return cls(**data)

ThreeWindingTransformerSpecifications

Bases: BaseTransformerSpecifications

The transformer specifications that are specific to a three-winding transformer.

For all three windings the specs should be provided. Note that we use the following abbreviations: * Low voltage: lv * Medium voltage: mv * High voltage: hv

Methods:

Name Description
create

Create a ThreeWindingTransformerSpecifications instance by merging defaults with user specifications.

Attributes:

Name Type Description
load_loss_total float

Calculate the total load loss for the three-winding transformer.
nominal_load_array ndarray

Return the nominal loads as a numpy array.
winding_oil_gradient_array ndarray

Return the winding oil gradient as a numpy array.
time_const_windings_array ndarray

Return the winding oil gradient as a numpy array.
hot_spot_fac_array ndarray

Return the winding oil gradient as a numpy array.

load_loss_total property 

load_loss_total: float

Calculate the total load loss for the three-winding transformer.

nominal_load_array property 

nominal_load_array: ndarray

Return the nominal loads as a numpy array.

winding_oil_gradient_array property 

winding_oil_gradient_array: ndarray

Return the winding oil gradient as a numpy array.

time_const_windings_array property 

time_const_windings_array: ndarray

Return the winding oil gradient as a numpy array.

hot_spot_fac_array property 

hot_spot_fac_array: ndarray

Return the winding oil gradient as a numpy array.

create classmethod 

create(
    defaults: ThreeWindingTransformerDefaultSpecifications,
    user: UserThreeWindingTransformerSpecifications,
) -> Self

Create a ThreeWindingTransformerSpecifications instance by merging defaults with user specifications.

Source code in transformer_thermal_model/schemas/specifications/transformer.py 
250
251
252
253
254
255
256
257
258
259
260
@classmethod
def create(
    cls, defaults: ThreeWindingTransformerDefaultSpecifications, user: UserThreeWindingTransformerSpecifications
) -> Self:
    """Create a ThreeWindingTransformerSpecifications instance by merging defaults with user specifications."""
    data = defaults.model_dump()
    data.update(user.model_dump(exclude_none=True))
    logger.info("Complete three-winding transformer specifications: %s", data)

    data["load_loss_total_user"] = user.load_loss_total if user.load_loss_total is not None else None
    return cls(**data)

Transformer component specifications

Classes:

Name Description
TransformerComponentSpecifications

Component specifications for internal components of the power transformer.

TransformerComponentSpecifications

Bases: BaseModel

Component specifications for internal components of the power transformer.

These specifications are used to calculate the limiting component in a PowerTransformer, which is optional entirely. It is used to define the components in the PowerTransformer, to then determine the limiting component.

Attributes:

Name Type Description
nom_load_prim_side float

Nominal current on the primary side of the transformer [A].
tap_chang_capacity float | None

Tap changer nominal current [A].
tap_chang_conf VectorConfig | None

Tap Changer configuration.
tap_chang_side TransformerSide | None

Tap changer side.
prim_bush_capacity float | None

Primary bushing nominal current [A].
prim_bush_conf BushingConfig | None

Primary bushing configuration.
sec_bush_capacity float | None

Secondary bushing nominal current [A].
sec_bush_conf BushingConfig | None

Secondary bushing configuration.
cur_trans_capacity float | None

Current transformer nominal current [A].
cur_trans_conf VectorConfig | None

Current transformer configuration.
cur_trans_side TransformerSide | None

Current transformer side.
Initialising a power transformer with component specifications. 
>>> from transformer_thermal_model.cooler import CoolerType
>>> from transformer_thermal_model.components import VectorConfig, TransformerSide
>>> from transformer_thermal_model.schemas import (
...     TransformerComponentSpecifications,
...     UserTransformerSpecifications
... )
>>> from transformer_thermal_model.transformer import PowerTransformer

>>> 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]
... )
>>> comp_specs = TransformerComponentSpecifications(
...     tap_chang_capacity=600,
...     nom_load_prim_side=550,
...     tap_chang_conf=VectorConfig.STAR,
...     tap_chang_side=TransformerSide.PRIMARY
... )
>>> tr = PowerTransformer(
...     user_specs=tr_specs,
...     cooling_type=CoolerType.ONAF,
...     internal_component_specs=comp_specs
... )
>>> tr.component_capacities
{'tap_changer': 1.0909090909090908, 'primary_bushings': None,
'secondary_bushings': None, 'current_transformer': None}