Skip to content

Cooling switch controller

CoolingSwitchController 

CoolingSwitchController(
    onaf_switch: CoolingSwitchBase,
    specs: BaseTransformerSpecifications,
)

Encapsulates ONAN/ONAF cooling switch logic for transformers.

This class manages the automatic switching between ONAN (Oil Natural Air Natural) and ONAF (Oil Natural Air Forced) cooling modes based on either: - A predefined fan status schedule (list of boolean values) - Temperature thresholds (activation and deactivation temperatures)

The controller is used internally by transformer classes and handles the logic for determining when to switch cooling modes and what specifications to apply for each mode.

Using CoolingSwitchController with temperature-based switching 
>>> import numpy as np
>>> from transformer_thermal_model.transformer import PowerTransformer
>>> from transformer_thermal_model.schemas import UserTransformerSpecifications
>>> from transformer_thermal_model.schemas.thermal_model import (
...     CoolingSwitchSettings,
...     CoolingSwitchConfig,
...     ONANParameters,
... )
>>> from transformer_thermal_model.cooler import CoolerType

>>> # Define the transformer specifications for ONAF mode
>>> user_specs = UserTransformerSpecifications(
...     load_loss=1000,
...     nom_load_sec_side=1500,
...     no_load_loss=200,
...     amb_temp_surcharge=20,
... )
>>> # Define ONAN parameters (for when fans are off)
>>> onan_params = ONANParameters(
...     nom_load_sec_side=1200,
...     top_oil_temp_rise=65,
...     winding_oil_gradient=20,
...     hot_spot_fac=1.3,
...     time_const_oil=210,
...     time_const_windings=10,
...     load_loss=800,
... )
>>> # Create switch configuration with temperature thresholds
>>> # Fans activate at 70°C, deactivate at 60°C
>>> onaf_switch = CoolingSwitchSettings(
...     temperature_threshold=CoolingSwitchConfig(activation_temp=70, deactivation_temp=60),
...     onan_parameters=onan_params
... )
>>> # Create transformer with automatic switching capability
>>> transformer = PowerTransformer(
...     user_specs=user_specs,
...     cooling_type=CoolerType.ONAF,
...     cooling_switch_settings=onaf_switch
... )
>>> # The CoolingSwitchController is now managing the cooling mode switches automatically
Using CoolingSwitchController with predefined fan status 
>>> from transformer_thermal_model.transformer import PowerTransformer
>>> from transformer_thermal_model.schemas.thermal_model import CoolingSwitchSettings, ONANParameters

>>> # Create a fan status schedule: True = ONAF (fans on), False = ONAN (fans off)
>>> # This represents 5 time steps with fans on, then off, then on again
>>> fan_schedule = np.array([True, True, True, True, True, False, False, False, True, True])
>>> # Define ONAN parameters for when fans are off
>>> onan_params = ONANParameters(
...     nom_load_sec_side=1200,
...     top_oil_temp_rise=65,
...     winding_oil_gradient=20,
...     hot_spot_fac=1.3,
...     time_const_oil=210,
...     time_const_windings=10,
...     load_loss=800,
... )
>>> onaf_switch = CoolingSwitchSettings(
...     fan_on=fan_schedule,
...     onan_parameters=onan_params
... )
>>> transformer = PowerTransformer(
...     user_specs=user_specs,
...     cooling_type=CoolerType.ONAF,
...     cooling_switch_settings=onaf_switch
... )
>>> # The controller will switch modes according to the predefined schedule

Attributes:

Name Type Description
onaf_switch CoolingSwitchSettings | ThreeWindingCoolingSwitchSettings

The switch configuration containing either fan status schedule or temperature thresholds, plus ONAN parameters.
original_onaf_specs BaseTransformerSpecifications

Deep copy of the original ONAF specifications, used as reference when switching back to ONAF mode.
Source code in transformer_thermal_model/transformer/cooling_switch_controller.py 
113
114
115
116
117
118
119
120
def __init__(
    self,
    onaf_switch: CoolingSwitchBase,
    specs: BaseTransformerSpecifications,
):
    """Initialize the controller with the given ONAF switch settings and transformer specifications."""
    self.onaf_switch = onaf_switch
    self.original_onaf_specs = specs.model_copy(deep=True)

determine_initial_specifications 

determine_initial_specifications(
    initial_top_oil_temperature: float,
) -> BaseTransformerSpecifications

Get the initial specifications based on the ONAF switch settings.

If the fans are off at the start or if a temperature threshold is set, the transformer starts with ONAN specifications. Otherwise, it starts with ONAF specifications.

Source code in transformer_thermal_model/transformer/cooling_switch_controller.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
def determine_initial_specifications(
    self,
    initial_top_oil_temperature: float,
) -> BaseTransformerSpecifications:
    """Get the initial specifications based on the ONAF switch settings.

    If the fans are off at the start or if a temperature threshold is set,
    the transformer starts with ONAN specifications. Otherwise, it starts with ONAF specifications.
    """
    if self.onaf_switch.fan_on is not None:
        if not self.onaf_switch.fan_on[0]:
            return self.create_onan_specifications()
    elif (
        self.onaf_switch.temperature_threshold is not None
        and initial_top_oil_temperature < self.onaf_switch.temperature_threshold.activation_temp
    ):
        return self.create_onan_specifications()
    return self.original_onaf_specs

create_onan_specifications 

create_onan_specifications() -> (
    BaseTransformerSpecifications
)

Create ONAN specifications by merging ONAN parameters into the original ONAF specifications.

This method returns a deep copy of the original ONAF specifications with fields overridden by the ONAN parameters provided in the switch configuration. Only fields present in the ONAN parameters are updated; all other fields remain unchanged. The method automatically selects the correct specification type (standard or three-winding) based on the input objects.

Source code in transformer_thermal_model/transformer/cooling_switch_controller.py 
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
def create_onan_specifications(self) -> BaseTransformerSpecifications:
    """Create ONAN specifications by merging ONAN parameters into the original ONAF specifications.

    This method returns a deep copy of the original ONAF specifications with fields overridden by the
    ONAN parameters provided in the switch configuration. Only fields present in the ONAN parameters
    are updated; all other fields remain unchanged. The method automatically selects the correct
    specification type (standard or three-winding) based on the input objects.
    """
    transformer_specs = self.original_onaf_specs.model_copy(deep=True)

    if isinstance(transformer_specs, TransformerSpecifications) and isinstance(
        self.onaf_switch, CoolingSwitchSettings
    ):
        specs_dict = transformer_specs.model_dump()
        specs_dict.update(self.onaf_switch.onan_parameters.model_dump(exclude_none=True))
        transformer_specs = TransformerSpecifications(**specs_dict)

    elif isinstance(transformer_specs, ThreeWindingTransformerSpecifications) and isinstance(
        self.onaf_switch, ThreeWindingCoolingSwitchSettings
    ):
        specs_dict = transformer_specs.model_dump()
        specs_dict.update(self.onaf_switch.onan_parameters.model_dump(exclude_none=True))
        transformer_specs = ThreeWindingTransformerSpecifications(**specs_dict)

    return transformer_specs

get_new_specs 

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

Check and handle the ONAF/ONAN switch based on the top-oil temperature and the switch settings.

This method evaluates the current and previous top-oil temperatures, along with the fan status and temperature thresholds, to determine the appropriate transformer specifications to use.

Parameters:

Name Type Description Default
top_oil_temp float

Current top-oil temperature.

 required
previous_top_oil_temp float

Previous top-oil temperature.

 required
index int

Index for fan status or threshold evaluation.

 required
Source code in transformer_thermal_model/transformer/cooling_switch_controller.py 
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
def get_new_specs(
    self, top_oil_temp: float, previous_top_oil_temp: float, index: int
) -> BaseTransformerSpecifications | None:
    """Check and handle the ONAF/ONAN switch based on the top-oil temperature and the switch settings.

    This method evaluates the current and previous top-oil temperatures, along with the fan status
    and temperature thresholds, to determine the appropriate transformer specifications to use.

    Args:
        top_oil_temp (float): Current top-oil temperature.
        previous_top_oil_temp (float): Previous top-oil temperature.
        index (int): Index for fan status or threshold evaluation.
    """
    fan_on = self.onaf_switch.fan_on
    temp_threshold = self.onaf_switch.temperature_threshold

    if fan_on is not None and index < len(fan_on) - 1:
        return self._handle_fan_status_switch(fan_on, index)
    elif temp_threshold is not None:
        return self._handle_temp_threshold_switch(temp_threshold, top_oil_temp, previous_top_oil_temp)
    return None