Feature/cooling switch temperature based #100

Harm1995 · 2025-10-06T12:30:17Z

This PR introduces the ability to configure the switch between ONAN (Oil Natural Air Natural) and ONAF (Oil Natural Air Forced) cooling modes for transformer calculations. This enhancement allows users to:

Define historical profiles for fan operation (on/off states)
Set threshold temperatures that trigger automatic fan switching.
Handle dynamic specification changes when transformers switch between cooling modes

Created a CoolingSwitchController class that encapsulates all logic associated with switching between ONAN and ONAF states. The controller preserves original ONAF specifications and dynamically alters the specs with the user provided ONAN parameters when the fans turn off. It supports both two-winding and three-winding transformers.

Calculation Method Changes:

Moved temperature calculations (top-oil and hot-spot) from vectorized operations to loop-based processing. We can no longer do a lot of calculations before the for-loop, since parameters can change along the way.
Specifications are now checked and potentially updated at the end of each timestep, after temperature calculations.

New Schema Components:

ONAFSwitch and ThreeWindingONAFSwitch: Configuration classes for switch settings.
ONANParameters and ThreeWindingONANParameters : Defines the transformer specifications to use when in ONAN mode.
FanSwitchConfig: Contains activation and deactivation temperature thresholds for temperature-based switching

Performance Trade-offs

The move from vectorized calculations to loop-based processing increases computation time. However, this trade-off is justified because current use cases rarely require high-performance computation. Additionally, in future versions we may want to add time dependant parameters, that would also require, this new method of calculating.

Example Usage
To model with the switch between ONAN and ONAF, create a Transformer with the additional parameter cooling_switch_settings:

from transformer_thermal_model.schemas.thermal_model import ONAFSwitch, FanSwitchConfig, ONANParameters

onaf_switch = ONAFSwitch(
    temperature_threshold=FanSwitchConfig(
        activation_temp=70,  # Fans turn on at 70°C
        deactivation_temp=60  # Fans turn off at 60°C
    ),
    onan_parameters=ONANParameters(
        nom_load_sec_side=1200,
        top_oil_temp_rise=65,
        # ... other ONAN specifications
    )
)

transformer = PowerTransformer(
    user_specs=user_specs,
    cooling_type=CoolerType.ONAF,
    cooling_switch_settings=onaf_switch
)

Signed-off-by: Harm <harm.van.leijen@alliander.com>

…or temperature dependant changes in the time constants Signed-off-by: Harm <harm.van.leijen@alliander.com>

Signed-off-by: Harm <harm.van.leijen@alliander.com>

… in transformers Signed-off-by: Harm <harm.van.leijen@alliander.com>

Signed-off-by: Harm <harm.van.leijen@alliander.com>

…dates during calculations Signed-off-by: Harm <harm.van.leijen@alliander.com>

Signed-off-by: Harm <harm.van.leijen@alliander.com>

anna-van-velsen

The new feature you added is quite complex at first sight.
The readability of the code could be improved with some more documentation in the code by more elaborate docstrings or online comments.

transformer_thermal_model/transformer/base.py

transformer_thermal_model/transformer/distribution.py

transformer_thermal_model/transformer/power.py

transformer_thermal_model/transformer/threewinding.py

- Updated pre-commit hooks to latest versions. - Modified example notebook to include ONAN parameters and adjust execution counts. - Refactored test cases to utilize ONAN parameters for ONAF switch. - Introduced CoolingSwitchController to encapsulate ONAN/ONAF switching logic. - Enhanced Model class to validate transformer and input profile compatibility. - Updated transformer base class to support cooling controller. - Added ONAN and ThreeWindingONAN parameters for detailed cooling specifications. - Refactored ONAFSwitch to include ONAN parameters and ensure proper validation. - Adjusted PowerTransformer and ThreeWindingTransformer to utilize the new cooling controller. - Implemented logic to handle cooling type switching based on fan status and temperature thresholds. Signed-off-by: Harm <harm.van.leijen@alliander.com>

Signed-off-by: Harm <harm.van.leijen@alliander.com>

…ulations Signed-off-by: Harm <harm.van.leijen@alliander.com>

Signed-off-by: Harm <harm.van.leijen@alliander.com>

Copilot

Pull Request Overview

This PR introduces dynamic cooling mode switching between ONAN (Oil Natural Air Natural) and ONAF (Oil Natural Air Forced) for transformer thermal calculations, allowing users to model transformers with fan-controlled cooling.

Key changes:

Introduced CoolingSwitchController to manage cooling mode transitions based on fan schedules or temperature thresholds
Refactored thermal calculations from vectorized to loop-based processing to support dynamic parameter changes
Added schema classes ONAFSwitch, ONANParameters, and related three-winding variants for configuration

Reviewed Changes

Copilot reviewed 17 out of 19 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
transformer_thermal_model/transformer/cooling_switch_controller.py	New controller class managing ONAN/ONAF switching logic and specification updates
transformer_thermal_model/schemas/thermal_model/onaf_switch.py	New schema classes for switch configuration and ONAN parameters
transformer_thermal_model/transformer/base.py	Added cooling controller support and delegation methods for switching
transformer_thermal_model/transformer/power.py	Integrated cooling controller and updated temperature calculation signature
transformer_thermal_model/transformer/threewinding.py	Integrated cooling controller for three-winding transformers
transformer_thermal_model/transformer/distribution.py	Updated to pass None for cooling controller
transformer_thermal_model/model/thermal_model.py	Refactored to loop-based calculations with per-timestep specification updates
transformer_thermal_model/schemas/specifications/transformer.py	Fixed array construction to remove unnecessary nested brackets
tests/model/test_onan_onaf_switch.py	Comprehensive test suite for switching functionality
docs/get_started/about.md	Added extensive documentation with examples
mkdocs.yml	Added documentation references for new feature

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-22T14:39:50Z

transformer_thermal_model/transformer/base.py

+            )
+
+    def check_switch_and_get_new_specs(
+        self, top_oil_temp: int, previous_top_oil_temp: int, index: int


The top_oil_temp and previous_top_oil_temp parameters are typed as int, but they should be float since they represent temperature values that can have decimal precision.

Suggested change

self, top_oil_temp: int, previous_top_oil_temp: int, index: int

self, top_oil_temp: float, previous_top_oil_temp: float, index: int

Copilot · 2025-10-22T14:39:50Z

transformer_thermal_model/schemas/thermal_model/onaf_switch.py

+class BaseONANParameters(BaseModel):
+    """Base class representing common ONAN (Oil Natural Air Natural) cooling parameters.
+
+    THis is used when an ONAF transformer switches to ONAN cooling.


Corrected spelling of 'THis' to 'This'.

Suggested change

THis is used when an ONAF transformer switches to ONAN cooling.

This is used when an ONAF transformer switches to ONAN cooling.

anna-van-velsen

Already looking very good!
My major suggestion is to change the naming of the onaf_switch schemas to something like cooling_switch/ CoolingSwitch.
Furthermore, you have introduced two functions with the same name. One in the transformer and one in the coolingswitch controller. please reconsider this.

anna-van-velsen · 2025-10-23T07:58:48Z

docs/get_started/about.md

 Note, how the top oil temperature we receive as the output `results.top_oil_temp_profile` exactly matches
 the top oil temperature we provided as the input.

+### Use a transformer that switches between ONAN and ONAF


Suggested change

### Use a transformer that switches between ONAN and ONAF

### Model a transformer that switches between ONAN and ONAF

anna-van-velsen · 2025-10-23T08:07:28Z

transformer_thermal_model/model/thermal_model.py

+        """Check if the configuration is valid.
+
+        If the transformer is a ThreeWindingTransformer, the input profile must be a ThreeWindingInputProfile.
+        """


Ik zou de docstring iets simpeler houden. je hoeft niet de if statements in de docstring te benoemen.

Suggested change

"""Check if the configuration is valid.

If the transformer is a ThreeWindingTransformer, the input profile must be a ThreeWindingInputProfile.

"""

"""Check if the combination of the transformer and input profile the is valid.

"""

anna-van-velsen · 2025-10-23T08:14:41Z

transformer_thermal_model/transformer/base.py

+                initial_top_oil_temperature=init_top_oil_temp
+            )
+
+    def check_switch_and_get_new_specs(


This does not follow the "single purpose" rule according to the function name. The name of the function gives this away: def do_this_AND_do_that()..
But looking into the function it seems to be quite simple.
maybe change the name to something like: " set_cooling_switch_controller_specs"?

anna-van-velsen · 2025-10-23T08:52:01Z

transformer_thermal_model/schemas/thermal_model/onaf_switch.py

+from transformer_thermal_model.schemas.specifications.transformer import WindingSpecifications
+

 class FanSwitchConfig(BaseModel):


To make these schemas correspondent better with functions and classes in the cooling_switch_controller.py please consider to use coolingcontroller instead of onafswitch in the naming.

Suggested change

class FanSwitchConfig(BaseModel):

class CoolingSwitchConfig(BaseModel):

anna-van-velsen · 2025-10-23T08:53:22Z

transformer_thermal_model/schemas/thermal_model/onaf_switch.py

+    load_loss_hv_mv: float
+
+
+class ONAFSwitchBase(BaseModel):


Suggested change

class ONAFSwitchBase(BaseModel):

class CoolingSwitchBase(BaseModel):

anna-van-velsen · 2025-10-23T08:54:16Z

transformer_thermal_model/schemas/thermal_model/onaf_switch.py

        return self
+
+
+class ONAFSwitch(ONAFSwitchBase):


Suggested change

class ONAFSwitch(ONAFSwitchBase):

class CoolingSwitchSettings(CoolingSwitchBase):

anna-van-velsen · 2025-10-23T08:55:15Z

transformer_thermal_model/schemas/thermal_model/onaf_switch.py

+    )
+
+
+class ThreeWindingONAFSwitch(ONAFSwitchBase):


This name will become very long... so please consider if you have any other creative naming options

Suggested change

class ThreeWindingONAFSwitch(ONAFSwitchBase):

class ThreeWindingCoolingSwitchSettings(CoolingSwitchBase):

anna-van-velsen · 2025-10-23T09:00:55Z

transformer_thermal_model/transformer/cooling_switch_controller.py

+
+    def __init__(
+        self,
+        onaf_switch: ONAFSwitch | ThreeWindingONAFSwitch,


This attributes name could be changed to cooling_switch

Suggested change

onaf_switch: ONAFSwitch | ThreeWindingONAFSwitch,

cooling_switch: CoolingSwitch | ThreeWindingCoolingSwitch,

anna-van-velsen · 2025-10-23T09:03:06Z

transformer_thermal_model/transformer/cooling_switch_controller.py

+
+        return transformer_specs
+
+    def check_switch_and_get_new_specs(


There is a function in the base transformer with exact the same name. please reconsider if this is intentionally and otherwise change the naming.

transformer-thermal-model/transformer_thermal_model/transformer/base.py

Line 53 in 9b46226

def check_switch_and_get_new_specs(

Harm1995 added 12 commits October 6, 2025 14:42

chore: bump project version to 0.2.1

2ce22ab

Signed-off-by: Harm <harm.van.leijen@alliander.com>

refactor: move f1 and f2 calculations back to the for-loop to allow f…

e877d79

…or temperature dependant changes in the time constants Signed-off-by: Harm <harm.van.leijen@alliander.com>

feature: add the option for ONAF_switch

927337c

Signed-off-by: Harm <harm.van.leijen@alliander.com>

feat: implement temperature dependent time constants for ONAF cooling…

f0b25d8

… in transformers Signed-off-by: Harm <harm.van.leijen@alliander.com>

first split introduced

22b7401

Signed-off-by: Harm <harm.van.leijen@alliander.com>

refactor: move all calculations to for-loop to allow for parameter up…

6f443a5

…dates during calculations Signed-off-by: Harm <harm.van.leijen@alliander.com>

feature: implement the basis for switching between ONAN and ONAF

7e97e54

Signed-off-by: Harm <harm.van.leijen@alliander.com>

refactor: switch to ONAF as default for ONAN/ONAF

a767a74

Signed-off-by: Harm <harm.van.leijen@alliander.com>

feature: implement fan_status option for ONAn/ONAF

4d8eb71

Signed-off-by: Harm <harm.van.leijen@alliander.com>

fix: move hotspot calculations to the for loop

302e4fa

Signed-off-by: Harm <harm.van.leijen@alliander.com>

tests: add first basic tests

0e16eeb

Signed-off-by: Harm <harm.van.leijen@alliander.com>

fix: fix style issues

2b9f742

Signed-off-by: Harm <harm.van.leijen@alliander.com>

Harm1995 force-pushed the feature/cooling_switch_temperature_based branch from d62633d to 2b9f742 Compare October 6, 2025 12:42

anna-van-velsen requested changes Oct 7, 2025

View reviewed changes

Harm1995 added 16 commits October 9, 2025 15:10

fix: make sure parameter names match regular expressions

9519874

Signed-off-by: Harm <harm.van.leijen@alliander.com>

fix: make sure the onan onaf switch also happens for the hotspot calc…

1091465

…ulations Signed-off-by: Harm <harm.van.leijen@alliander.com>

fix: add comments and fix bug with deep copy

5ed3dba

Signed-off-by: Harm <harm.van.leijen@alliander.com>

Merge branch 'main' into feature/cooling_switch_temperature_based

63a9348

docs: update test

c8ec520

Signed-off-by: Harm <harm.van.leijen@alliander.com>

docs: update onan onaf example with three winding transformer

c676755

Signed-off-by: Harm <harm.van.leijen@alliander.com>

fix: fixed some minor inconsistancies in the model

b2ac192

Signed-off-by: Harm <harm.van.leijen@alliander.com>

fix: replace duplicate strings with constant

5fd9f8c

Signed-off-by: Harm <harm.van.leijen@alliander.com>

fix: add tests and use clearer naming

0b38acd

Signed-off-by: Harm <harm.van.leijen@alliander.com>

docs: add extra comments in the example

5a28ec2

Signed-off-by: Harm <harm.van.leijen@alliander.com>

docs: add documentation for cooler attribute

5f68107

Signed-off-by: Harm <harm.van.leijen@alliander.com>

add documentation in about.md

9ff6780

Signed-off-by: Harm <harm.van.leijen@alliander.com>

docs: add extra documentation

2328446

Signed-off-by: Harm <harm.van.leijen@alliander.com>

info: add warning for outdated architecture

4bca54b

Signed-off-by: Harm <harm.van.leijen@alliander.com>

tests: add an ONAN/ONAF test with given top_oil_temp

e3c057e

Signed-off-by: Harm <harm.van.leijen@alliander.com>

Harm1995 added 3 commits October 22, 2025 11:58

fix: prevent duplication and add test

bc65cb5

Signed-off-by: Harm <harm.van.leijen@alliander.com>

fix: prevent duplication of ONAN parameters

eab98b9

Signed-off-by: Harm <harm.van.leijen@alliander.com>

merge main

9b46226

Signed-off-by: Harm <harm.van.leijen@alliander.com>

Harm1995 marked this pull request as ready for review October 22, 2025 14:38

Harm1995 requested a review from a team as a code owner October 22, 2025 14:38

Harm1995 requested review from GroenteLepel and Copilot October 22, 2025 14:38

Copilot AI reviewed Oct 22, 2025

View reviewed changes

anna-van-velsen reviewed Oct 23, 2025

View reviewed changes

Harm1995 added the enhancement New feature or request label Oct 23, 2025

	self, top_oil_temp: int, previous_top_oil_temp: int, index: int
	self, top_oil_temp: float, previous_top_oil_temp: float, index: int

	THis is used when an ONAF transformer switches to ONAN cooling.
	This is used when an ONAF transformer switches to ONAN cooling.

	### Use a transformer that switches between ONAN and ONAF
	### Model a transformer that switches between ONAN and ONAF

		from transformer_thermal_model.schemas.specifications.transformer import WindingSpecifications


		class FanSwitchConfig(BaseModel):

	class FanSwitchConfig(BaseModel):
	class CoolingSwitchConfig(BaseModel):

	class ONAFSwitchBase(BaseModel):
	class CoolingSwitchBase(BaseModel):

	class ONAFSwitch(ONAFSwitchBase):
	class CoolingSwitchSettings(CoolingSwitchBase):

	class ThreeWindingONAFSwitch(ONAFSwitchBase):
	class ThreeWindingCoolingSwitchSettings(CoolingSwitchBase):

	onaf_switch: ONAFSwitch \| ThreeWindingONAFSwitch,
	cooling_switch: CoolingSwitch \| ThreeWindingCoolingSwitch,

Feature/cooling switch temperature based #100

Are you sure you want to change the base?

Feature/cooling switch temperature based #100

Uh oh!

Conversation

Harm1995 commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anna-van-velsen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 22, 2025

Choose a reason for hiding this comment

Uh oh!

anna-van-velsen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Harm1995 commented Oct 6, 2025 •

edited

Loading