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
UserTransformerSpecifications	The transformer specifications that the user must and can provide.
DefaultTransformerSpecifications	The default transformer specifications that will be defined when the user does not provide them.
TransformerSpecifications	Class containing transformer specifications.

UserTransformerSpecifications

Bases: BaseModel

The 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.

DefaultTransformerSpecifications

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.

TransformerSpecifications

Bases: BaseModel

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.

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

@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)

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}