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
DefaultWindingSpecifications	The default specifications for a single winding of a transformer.
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.

DefaultWindingSpecifications

Bases: BaseModel

The default specifications for a single winding of a transformer.

WindingSpecifications

Bases: DefaultWindingSpecifications

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

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

This method performs a merge of the defaults and user specifications. The merge behavior is as follows: - For top-level keys, values from user will overwrite those in defaults. - For nested dictionaries (e.g., WindingSpecifications), the merge is shallow: - Keys in the nested dictionary from user will overwrite or add to the corresponding keys in defaults. - Deeper levels of nesting are not recursively merged. Entire nested values are replaced.

This implementation assumes that only two levels of nesting are required. If deeper recursive merging is needed, the logic will need to be updated.

Parameters:

Name	Type	Description	Default
defaults	ThreeWindingTransformerDefaultSpecifications	The default transformer specifications.	required
user	UserThreeWindingTransformerSpecifications	The user-provided transformer specifications.	required

Returns:

Name	Type	Description
ThreeWindingTransformerSpecifications	Self	A new instance with merged specifications.

Source code in transformer_thermal_model/schemas/specifications/transformer.py

@classmethod
def create(
    cls, defaults: ThreeWindingTransformerDefaultSpecifications, user: UserThreeWindingTransformerSpecifications
) -> Self:
    """Create a ThreeWindingTransformerSpecifications instance by merging defaults with user specifications.

    This method performs a merge of the `defaults` and `user` specifications. The merge behavior is as follows:
    - For top-level keys, values from `user` will overwrite those in `defaults`.
    - For nested dictionaries (e.g., `WindingSpecifications`), the merge is shallow:
        - Keys in the nested dictionary from `user` will overwrite or add to the corresponding keys in `defaults`.
        - Deeper levels of nesting are not recursively merged. Entire nested values are replaced.

    This implementation assumes that only two levels of nesting are required. If deeper recursive merging is needed,
    the logic will need to be updated.

    Args:
        defaults (ThreeWindingTransformerDefaultSpecifications): The default transformer specifications.
        user (UserThreeWindingTransformerSpecifications): The user-provided transformer specifications.

    Returns:
        ThreeWindingTransformerSpecifications: A new instance with merged specifications.
    """
    # Perform a shallow merge of defaults and user specifications (up to two levels)
    data = deepcopy(defaults.model_dump())
    user_specs = user.model_dump(exclude_none=True)
    for key, value in user_specs.items():
        # Check for nested dictionaries (e.g., WindingSpecifications)
        if key in data and isinstance(data[key], dict) and isinstance(value, dict):
            # Perform a shallow merge at the second level
            for sub_key, sub_value in value.items():
                data[key][sub_key] = sub_value
        else:
            # Overwrite or add top-level keys
            data[key] = value

    logger.info("Complete three-winding transformer specifications: %s", data)

    # Add load_loss_total_user if provided in user specifications
    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}