Skip to content

Transformer

The Transformer is the main object that needs to be defined to work with our thermal model.

Transformer 

Transformer(
    cooling_type: CoolerType,
    cooling_controller: CoolingSwitchController
    | None = None,
)

Bases: ABC

Abstract class to define the transformer object.

Depending on the type of transformer (either PowerTransformer or DistributionTransformer), the transformer attains certain default attributes. These attributes can be overwritten by using the TR_Specs dictionary.

Attributes:

Name Type Description
cooling_type CoolerType

The cooling type. Can be CoolerType.ONAN or CoolerType.ONAF.

(TransformerSpecifications): The transformer specifications that you need to provide to build the transformer. Any optional specifications not provided will be taken from the default specifications.

Parameters:

Name Type Description Default
cooling_type CoolerType

The cooling type. Can be ONAN, ONAF.

 required
cooling_controller CoolingSwitchController | None

The cooling controller that handles the ONAN/ONAF switching logic.

 None
Source code in transformer_thermal_model/transformer/base.py 
33
34
35
36
37
38
39
40
41
42
43
44
def __init__(self, cooling_type: CoolerType, cooling_controller: CoolingSwitchController | None = None):
    """Initialize the Transformer object.

    Args:
        cooling_type (CoolerType): The cooling type. Can be ONAN, ONAF.
        cooling_controller (CoolingSwitchController | None): The cooling controller that handles the ONAN/ONAF
            switching logic.
    """
    self.cooling_type: CoolerType = cooling_type
    if cooling_type == CoolerType.ONAN and cooling_controller is not None:
        raise ValueError("ONAF switch only works when the cooling type is ONAF.")
    self.cooling_controller = cooling_controller

defaults abstractmethod property 

defaults: BaseDefaultTransformerSpecifications

The default transformer specifications.

set_ONAN_ONAF_first_timestamp 

set_ONAN_ONAF_first_timestamp(
    init_top_oil_temp: float,
) -> None

Delegate initial cooling type logic to CoolingSwitchController.

Source code in transformer_thermal_model/transformer/base.py 
46
47
48
49
50
51
def set_ONAN_ONAF_first_timestamp(self, init_top_oil_temp: float) -> None:
    """Delegate initial cooling type logic to CoolingSwitchController."""
    if self.cooling_controller:
        self.specs = self.cooling_controller.determine_initial_specifications(
            initial_top_oil_temperature=init_top_oil_temp
        )

set_cooling_switch_controller_specs 

set_cooling_switch_controller_specs(
    top_oil_temp: float,
    previous_top_oil_temp: float,
    index: int,
) -> BaseTransformerSpecifications | None

Delegate ONAN/ONAF switch logic to CoolingSwitchController.

Source code in transformer_thermal_model/transformer/base.py 
53
54
55
56
57
58
59
def set_cooling_switch_controller_specs(
    self, top_oil_temp: float, previous_top_oil_temp: float, index: int
) -> BaseTransformerSpecifications | None:
    """Delegate ONAN/ONAF switch logic to CoolingSwitchController."""
    if self.cooling_controller:
        return self.cooling_controller.get_new_specs(top_oil_temp, previous_top_oil_temp, index)
    return None

PowerTransformer 

PowerTransformer(
    user_specs: UserTransformerSpecifications,
    cooling_type: CoolerType,
    internal_component_specs: TransformerComponentSpecifications
    | None = None,
    cooling_switch_settings: CoolingSwitchSettings
    | None = None,
)

Bases: Transformer

A power transformer.

This class represents a power transformer. This class inherits from the Transformer class.

Example: initialise a power transformer: 

>>> from transformer_thermal_model.schemas import UserTransformerSpecifications
>>> from transformer_thermal_model.cooler import CoolerType
>>> from transformer_thermal_model.transformer import PowerTransformer

>>> user_specs = UserTransformerSpecifications(
...     load_loss=1000,
...     nom_load_sec_side=1500,
...     no_load_loss=200,
... )
>>> cooling_type = CoolerType.ONAN
>>> transformer = PowerTransformer(
...     user_specs=user_specs,
...     cooling_type=cooling_type
... )

Parameters:

Name Type Description Default
user_specs UserTransformerSpecifications

The transformer specifications that you need to provide to build the transformer. Any optional specifications not provided will be taken from the default specifications.

 required
cooling_type CoolerType

The cooling type. Can be ONAN or ONAF.

 required
internal_component_specs TransformerComponentSpecifications

The internal component specifications, which are used to calculate the limiting component. Defaults to None.

 None
cooling_switch_settings CoolingSwitchSettings

The ONAF switch settings. Only used when the cooling type is ONAF.

 None
Source code in transformer_thermal_model/transformer/power.py 
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
def __init__(
    self,
    user_specs: UserTransformerSpecifications,
    cooling_type: CoolerType,
    internal_component_specs: TransformerComponentSpecifications | None = None,
    cooling_switch_settings: CoolingSwitchSettings | None = None,
):
    """Initialize the transformer object.

    Args:
        user_specs (UserTransformerSpecifications): The transformer specifications that you need to
            provide to build the transformer. Any optional specifications not provided will be taken from the
            default specifications.
        cooling_type (CoolerType): The cooling type. Can be ONAN or ONAF.
        internal_component_specs (TransformerComponentSpecifications, optional): The internal component
            specifications, which are used to calculate the limiting component. Defaults to None.
        cooling_switch_settings (CoolingSwitchSettings, optional): The ONAF switch settings.
            Only used when the cooling type is ONAF.

    """
    logger.info("Creating a power transformer object.")
    logger.info("User transformer specifications: %s", user_specs)
    logger.info("Cooling type: %s", cooling_type)

    self.cooling_type: CoolerType = cooling_type

    if internal_component_specs is not None:
        logger.info("Internal component specifications: %s", internal_component_specs)
        warnings.warn(
            "PowerTransformerComponents was deprecated in version v0.4.0 and will be removed in v1.0.0.",
            category=DeprecationWarning,
            stacklevel=3,
        )
        self.internal_component_specs = internal_component_specs

    self.specs = TransformerSpecifications.create(self.defaults, user_specs)

    # Use CoolingSwitchController if cooling_switch_settings is provided
    self.cooling_controller = (
        CoolingSwitchController(onaf_switch=cooling_switch_settings, specs=self.specs)
        if cooling_switch_settings
        else None
    )

    super().__init__(cooling_type=cooling_type, cooling_controller=self.cooling_controller)

defaults property 

defaults: DefaultTransformerSpecifications

The ClassVar for default TransformerSpecifications.

If PowerTransformer is not initialised, uses the ONAF specifications.

tap_changer_capacity_ratio property 

tap_changer_capacity_ratio: float | None

The ratio between the tap changer capacity and the nominal load of the transformer.

primary_bushing_capacity_ratio property 

primary_bushing_capacity_ratio: float | None

The ratio between the primary bushing capacity and the nominal load of the transformer.

secondary_bushing_capacity_ratio property 

secondary_bushing_capacity_ratio: float | None

The ratio between the secondary bushing capacity and the nominal load of the transformer.

int_cur_trans_capacity_ratio property 

int_cur_trans_capacity_ratio: float | None

The ratio between the internal current transformer capacity and the nominal load of the transformer.

component_capacities property 

component_capacities: dict

Puts the limits of all transformer components in a single dictionary.

DistributionTransformer 

DistributionTransformer(
    user_specs: UserTransformerSpecifications,
)

Bases: Transformer

A distribution transformer.

The DistributionTransformer class represents a distribution transformer. This class inherits from the Transformer class. This transformer can only be used with ONAN (Oil Natural Air Natural) cooling type.

Initialising a distribution transformer. 
>>> from transformer_thermal_model.schemas import UserTransformerSpecifications
>>> from transformer_thermal_model.transformer import DistributionTransformer

>>> transformer_specifications = UserTransformerSpecifications(
...     load_loss=5200,  # Transformer load loss [W]
...     nom_load_sec_side=900,  # Transformer nominal current secondary side [A]
...     no_load_loss=800,  # Transformer no-load loss [W]
... )
>>> # note that no cooling type can be specified here, as this is a distribution transformer
>>> my_transformer = DistributionTransformer(user_specs=transformer_specifications)
>>> # the default specifications that will be used when not provided
>>> print(my_transformer.defaults)
time_const_oil=180.0 top_oil_temp_rise=60.0 oil_const_k11=1.0
winding_const_k21=1 winding_const_k22=2 oil_exp_x=0.8 winding_exp_y=1.6 end_temp_reduction=0.0
amb_temp_surcharge=10.0 time_const_windings=4.0 winding_oil_gradient=23.0 hot_spot_fac=1.2
>>> # the combination of the user specifications and the default specifications
>>> print(my_transformer.specs)
no_load_loss=800.0 amb_temp_surcharge=10.0 time_const_oil=180.0 top_oil_temp_rise=60.0
oil_const_k11=1.0 winding_const_k21=1 winding_const_k22=2
oil_exp_x=0.8 winding_exp_y=1.6 end_temp_reduction=0.0 load_loss=5200.0
nom_load_sec_side=900.0 winding_oil_gradient=23.0 time_const_windings=4.0 hot_spot_fac=1.2

Parameters:

Name Type Description Default
user_specs UserTransformerSpecifications

The transformer specifications that you need to provide to build the transformer. Any optional specifications not provided will be taken from the default specifications.

 required
Source code in transformer_thermal_model/transformer/distribution.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def __init__(
    self,
    user_specs: UserTransformerSpecifications,
):
    """Initialize the transformer object.

    Args:
        user_specs (UserTransformerSpecifications): The transformer specifications that you need to
            provide to build the transformer. Any optional specifications not provided will be taken from the
            default specifications.

    """
    logger.info("Creating a distribution transformer object.")
    logger.info("User transformer specifications: %s", user_specs)

    super().__init__(
        cooling_type=CoolerType.ONAN,
        cooling_controller=None,
    )
    self.specs = TransformerSpecifications.create(self.defaults, user_specs)

defaults property 

defaults: DefaultTransformerSpecifications

Return the default transformer specifications.

ThreeWindingTransformer 

ThreeWindingTransformer(
    user_specs: UserThreeWindingTransformerSpecifications,
    cooling_type: CoolerType,
    cooling_switch_settings: ThreeWindingCoolingSwitchSettings
    | None = None,
)

Bases: Transformer

A three-winding transformer.

This class represents a Three winding transformer. This class inherits from the Transformer class.

Example: initialise a three winding transformer: 

>>> from transformer_thermal_model.schemas import UserThreeWindingTransformerSpecifications, WindingSpecifications
>>> from transformer_thermal_model.transformer import ThreeWindingTransformer

>>> user_specs = UserThreeWindingTransformerSpecifications(
...     no_load_loss=20,
...     amb_temp_surcharge=10,
...     lv_winding=WindingSpecifications(nom_load=1000, winding_oil_gradient=20, hot_spot_fac=1.2,
...                                      time_const_winding=1, nom_power=1000),
...     mv_winding=WindingSpecifications(nom_load=1000, winding_oil_gradient=20, hot_spot_fac=1.2,
...                                      time_const_winding=1, nom_power=1000),
...     hv_winding=WindingSpecifications(nom_load=1000, winding_oil_gradient=20, hot_spot_fac=1.2,
...                                      time_const_winding=1000000, nom_power=1000),
...     load_loss_hv_lv=100,
...     load_loss_hv_mv=100,
...     load_loss_mv_lv=100,
... )
>>> transformer = ThreeWindingTransformer(user_specs=user_specs, cooling_type=CoolerType.ONAN)
>>> # the combination of the user specifications and the default specifications
>>> print(transformer.specs)
no_load_loss=20.0 amb_temp_surcharge=10.0 time_const_oil=210.0 top_oil_temp_rise=60.0
oil_const_k11=0.5 winding_const_k21=2 winding_const_k22=2 oil_exp_x=0.8 winding_exp_y=1.3
end_temp_reduction=0.0
lv_winding=WindingSpecifications(winding_oil_gradient=20.0, time_const_winding=1.0, hot_spot_fac=1.2,
  nom_load=1000.0, nom_power=1000.0)
mv_winding=WindingSpecifications(winding_oil_gradient=20.0, time_const_winding=1.0, hot_spot_fac=1.2,
  nom_load=1000.0, nom_power=1000.0)
hv_winding=WindingSpecifications(winding_oil_gradient=20.0, time_const_winding=1000000.0, hot_spot_fac=1.2,
  nom_load=1000.0, nom_power=1000.0)
load_loss_hv_lv=100.0 load_loss_hv_mv=100.0 load_loss_mv_lv=100.0 load_loss_total_user=None

Source code in transformer_thermal_model/transformer/threewinding.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
def __init__(
    self,
    user_specs: UserThreeWindingTransformerSpecifications,
    cooling_type: CoolerType,
    cooling_switch_settings: ThreeWindingCoolingSwitchSettings | None = None,
):
    """Initialize the ThreeWindingTransformer object."""
    logger.debug("Initialized ThreeWindingTransformer with specifications: %s", user_specs)

    self.cooling_type: CoolerType = cooling_type
    self.specs = ThreeWindingTransformerSpecifications.create(self.defaults, user_specs)

    # Use CoolingSwitchController if onaf_switch is provided
    self.cooling_controller = (
        CoolingSwitchController(onaf_switch=cooling_switch_settings, specs=self.specs)
        if cooling_switch_settings
        else None
    )

    super().__init__(
        cooling_type=cooling_type,
        cooling_controller=self.cooling_controller,
    )

defaults property 

defaults: ThreeWindingTransformerDefaultSpecifications

The ClassVar for default TransformerSpecifications.