===================
ETTM version 2025
===================

--------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------SOFTWARE DESCRIPTION---------------------------------------------------
The Geomagnetic Disturbance (GMD) is one of the most detrimental natural events that can affect the power system and cause the unidirectional saturation of the system transformers due to the flow of Geomagnetically Induced Current (GIC). Past GMD events have proven that the transformers are vulnerable elements of power systems and subjected to failure mainly due to the incurred hotspot heating in the transformer winding and the core/tank metallic structural parts. To address the issue, NERC standard TPL-007 requires vulnerability assessments and transformer thermal analysis, under GMD conditions. In spite of the existing transformer thermal models, except one, none of these models is suitable for GIC hotspot heating assessments as such models have been strictly developed for transformer loading conditions.   
In this project, an accurate thermal transformer model for the estimation of the hotspot heating in the transformer during GMDs has been developed. Hereinafter in this report, this tool is referred to as EPRI Transformer Thermal Model (ETTM). The thermal model is based on the transfer function approach which does not require detailed information about the studied transformers. To obtain the model parameters, the model step response is fitted to the GIC test data. The detailed technical bases have been presented and the model immunity to the measurement and numerical noise has been demonstrated. Furthermore, the simulation results of the transformers with available GIC test data have been presented which reveal the high accuracy of the developed model in duplication of the measurements. A user-friendly Graphical User Interface (GUI) has been developed for the model and the required instructions have been explained through the step-by-step demonstrations.


--------------------------------------------------------------------------------------------------------------------------
------------------------------------------------------Acknowledgments-----------------------------------------------------

We acknowledge the foundational work and contributions of the original development 
team behind EPRI Transformer Thermal Modeling Tool (ETTM) Version 1.0. Their efforts laid the groundwork 
for the advancements presented in this version. 
Thanks to developers of ETTM Version 1.0:
    ⁃ Aboutaleb Haddadi, Electric Power Research Institute (EPRI)
    ⁃ Afshin Rezaei-Zare, York University, Toronto, Ontario, Canada
    ⁃ Jean Mahseredjian, Montréal Polytechnique, Montréal, Québec, Canada
Their expertise and collaboration were instrumental in the development and validation of the ETTM tool.


--------------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------Requirements-------------------------------------------------------
The ETTM executable requires Windows 10 (64-Bit) or Windows 11 (64-Bit). The Python package additionally requires Python 3.9, Python libraries numpy, pandas, scipy, matplotlib
The following items are required to use ETTM executable and python package:
	Windows 10 (64-bit) or Windows 11 (64-bit)
	At least 100 MB of free hard disk space.
	At least 2 GB of RAM. Performance improves with more memory.
	Installing the ETTM python package additionally requires:
o	Python 3.9 
o	Python libraries: 
		•	numpy (version 2.0.2)
		•	pandas (version 2.3.2)
		•	scipy (version 1.13.1)
		•	matplotlib (version 3.9.2)


--------------------------------------------------------------------------------------------------------------------------
-------------------------------------------Installation (ETTM Python Package)------------------------------------------
Installation of EPRI Software at Client Site:
This software uses third party software products, operating systems, and hardware platforms. Over time, security issues may be uncovered in these third party products. You should review your use of this software with your Information Technology (IT) department to ensure that all recommended security updates and patches are installed to all third party products when needed.

If you experience difficulties accessing the application:
If you experience difficulties accessing the application after standard installation, please consult your IT department personnel to have proper access permissions setup for your use. If the problem cannot be resolved, please call the EPRI Customer Assistance Center (CAC) at 1-800-313-3774 (or email askepri@epri.com).

The ETTM executable contains all the required python libraries and the ETTM package bundled together in one folder. The executable is located at ..\ettm-master\ettm-gui\ettm_gui\ettm_gui.exe
Double click this file to run the program. No installation is required.


Follow steps below to install the python package:
Step 1: Install Python 3.9 and pip. Use instructions indicated here: https://www.python.org/downloads/
Step 2: Installing dependencies. Use module installation instructions: https://docs.python.org/3/installing/index.html, to install the following python modules.
	•	numpy (version 2.0.2)
	•	pandas (version 2.3.2)
	•	scipy (version 1.13.1)
	•	matplotlib (version 3.9.2)
	Install the above packages in one step using the pip command below:                              
		$ pip install numpy==2.0.2 pandas==2.3.2 scipy==1.13.1 matplotlib==3.9.2
	OR
	Use the requirements.txt file (located here: \ettm-master\ettm-python\requirements.txt). cd into the directory where requirements.txt is located and run the following pip command.                
		$ pip install -r requirements.txt
	Check out versions of all the installed modules and packages using:
		$ pip list
Step 3: To install the ETTM python package, open the command line or terminal window. It is recommended to perform the installation inside a Python virtual environment to avoid dependency conflicts with other packages.
	•	Check the python version (needs to be python 3.9):                                                
		$ python3 --version
	•	Update setuptools:
		$ python -m pip install --upgrade setuptools
	•	cd into the directory where setup.py is located. (setup.py is located at \ettm-master\ettm-python\setup.py)
	•	Install the ETTM package using:
		$ $ pip install .
	•	Check out versions of all the installed modules and packages using:
		$ pip list

Uninstallation (ETTM Python Package)
To uninstall the ETTM python package, open the command line or terminal window and execute the following command:                                             
$ pip uninstall ettm


--------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------Python Package usage---------------------------------------------------
ETTM Package
Apart from the GUI, the tool functionality can also be accessed using the ETTM python package. Use the installation instructions indicated in the MANDATORY SOFTWARE INSTALLATION INFORMATION section. 
The ETTM functions are described in the subsequent sections.


Single transformer ETTM analysis functions:
•	Initialize ETTM output result dictionary:
	Generates and empty “ETTM output dictionary” (described in a later section).
	$ import ettm
	$ ettmdat = ettm.initializeUserData()
•	Winding asymptotic response and temperature rise curve fitting and plotting function. This function is equivalent to the curve fit function of the GUI winding model panel:
	$ ettmdat = ettm.windingdat_curvefit(inputdat, ettmdat)
	Arguments:
	⁃	inputdat {dict}: ETTM input data dictionary
	⁃	ettmdat {dict}: ETTM output dictionary
•	Structural parts asymptotic response and temperature rise curve fitting and plotting function. This function is equivalent to the curve fit function of the GUI structural parts model panel:
	$ ettmdat = ettm.structdat_curvefit(inputdat, ettmdat)
	Arguments:
	⁃	inputdat {dict}: ETTM input data dictionary
	⁃	ettmdat {dict}: ETTM output dictionary
•	GIC signature loading and plotting function. This function is equivalent to the load GIC function of the GUI GIC panel:
	$ ettmdat = ettm.load_gic(inputdat, ettmdat)
	Arguments:
	⁃	inputdat {dict}: ETTM input data dictionary
	⁃	ettmdat {dict}: ETTM output dictionary
•	Winding temperature rise calculation and plotting function. This function is equivalent to the winding temperature calculation action of the GUI simulation panel:
	$ ettmdat = ettm.windtemp_sim(inputdat, ettmdat)
	Arguments:
	⁃	inputdat {dict}: ETTM input data dictionary
	⁃	ettmdat {dict}: ETTM output dictionary
•	Structural parts temperature rise calculation and plotting function. This function is equivalent to the structural temperature calculation action of the GUI simulation panel::
	$ ettmdat = ettm.structtemp_sim(inputdat, ettmdat)
	Arguments:
	⁃	inputdat {dict}: ETTM input data dictionary
	⁃	ettmdat {dict}: ETTM output dictionary
	
Multiple transformer ETTM analysis functions (Batch process):
This functionality is very similar to single transformer function. The only difference is that in these functions the input and output data variable are list of dictionaries. i.e: 
o	inputdat_multi {list}: list of ETTM input data dictionary. Such that each element of the list contains the input data for ETTM analysis of a single transformer. 
o	ettmdat_multi {list}: list of ETTM output dictionary. Such that each element of the list contains the output data of the ETTM analysis for a single transformer. 

The functions include:
•	Initialize ETTM output result dictionary:
	Generates and empty “ETTM output dictionary”.
	$ import ettm
	$ for _ in input_multi:
	    ettmdat_single = ettm.initializeUserData()
	    ettmdat_multi.append(ettmdat_single)
•	Winding asymptotic response and temperature rise curve fitting and plotting function:
	$ ettmdat_multi = ettm.windingdat_curvefit_multi(input_multi,ettmdat_multi)
	Arguments: 
	⁃	inputdat_multi {list}: list of ETTM input data dictionary.
	⁃	ettmdat_multi {list}: list of ETTM output dictionary
•	Structural parts asymptotic response and temperature rise curve fitting and plotting function:
	$ ettmdat_multi = ettm.structdat_curvefit_multi(input_multi, ettmdat_multi) 
	Arguments: 
	⁃	inputdat_multi {list}: list of ETTM input data dictionary.
	⁃	ettmdat_multi {list}: list of ETTM output dictionary
•	GIC signature loading and plotting function:
	$ ettmdat_multi = ettm.load_gic_multi(input_multi, ettmdat_multi) 
	Arguments: 
	⁃	inputdat_multi {list}: list of ETTM input data dictionary.
	⁃	ettmdat_multi {list}: list of ETTM output dictionary
•	Winding temperature rise calculation and plotting function:
	$ ettmdat_multi = ettm.windtemp_sim_multi(input_multi, ettmdat_multi) 
	Arguments: 
	⁃	inputdat_multi {list}: list of ETTM input data dictionary.
	⁃	ettmdat_multi {list}: list of ETTM output dictionary
•	Structural parts temperature rise calculation and plotting function:
	$ ettmdat_multi = ettm.structtemp_sim_multi(input_multi, ettmdat_multi) 
	Arguments: 
	⁃	inputdat_multi {list}: list of ETTM input data dictionary.
	⁃	ettmdat_multi {list}: list of ETTM output dictionary

ETTM input data dictionary
All the user information is stored in a python dictionary. 
For ease of understanding, refer to: ..\ettm-master\ettm-python\examples\userinput_single_xmer.py python file. This python file contains an example of the input dictionary. 
Users need to refer to GUI sections to see the correct input data file formats.
user_input (dict): ETTM input dictionary
├── fullpath_WAR_Table_Data: string - File path for winding asymptotic response data. 
├── GIC_val_wind: float - Reference GIC for winding temperature rise data.
├── fullpath_WTR_Table_Data: string - File path for winding temperature rise test data. 
├── fullpath_SAR_Table_Data: string - File path for structural asymptotic response data.
├── GIC_val_struct: float - Reference GIC for structural temperature rise data.
├── fullpath_STR_Table_Data: string - File path for structural parts temperature rise data. 
├── fullpath_GIC_Data: string - GIC time series data (1 min sampling rate).
├── init_wind_temp: float - Initial winding temperature in degree Celsius.
├── init_oil_temp: float - Initial oil temperature in degree Celsius.
├── results_folder: string - Folder path to save the results. Leave empty to skip.
└── pltfig: list - Plot configuration flags.
    ├── wind_plot: 1/0 - Winding response curve fit plot. Set 1 to generate.
    ├── struct_plot: 1/0 - Structural part response curve fit plot. Set 1 to generate.
    ├── gic_plot: 1/0 - Input GIC time series plot. Set 1 to generate.
    ├── trw_plot: 1/0 - Winding temperature rise plot. Set 1 to generate.
    └── trs_plot: 1/0 - Structural part temperature rise plot. Set to 1 to generate.
In the above description pltfig{list} is given by: 
$ pltfig =  [wind_plot, struct_plot, gic_plot, trw_plot, trs_plot]


ETTM output result dictionary
This dictionary contains the results from the ETTM python functions.
ettmdat(dict): ETTM output dictionary
├── WAR_data: ndarray: User provided winding asymptotic response test data.
├── GIC_WTR: float: Reference GIC for winding temperature rise.
├── WTR_data: ndarray: Winding temperature rise test data.
├── SAR_data: ndarray: Structural part asymptotic response test data.
├── GIC_STR: float: Reference GIC for structural temperature rise.
├── STR_data: ndarray: Structural temperature rise test data.
├── GIC_dt: float: GIC sampling rate (in minutes).
├── GIC_time: ndarray: Time values of the input GIC time series (in minutes).
├── GIC_current: ndarray: GIC time series data.
├── Oil_Temperature_due_to_Loading: float: Oil temperature value in degree Celsius.
├── Import_WAR_Table_Data: ndarray: Imported winding asymptotic response test data.
├── Import_WTR_Table_Data: ndarray: Imported winding temperature rise test data.
├── Import_SAR_Table_Data: ndarray: Imported structural part asymptotic response data.
├── Import_STR_Table_Data: ndarray: Imported structural temperature rise test data.
├── t: ndarray: Time values for winding temperature rise time series (in minutes).
├── y: ndarray: Winding temperature rise output (in degree Celsius).
├── t1: ndarray: Time values for structural part temperature rise (in minutes).
├── y1: ndarray: Structural part temperature rise output (in degree Celsius).
├── Idc_test_winding_ref: float: Reference GIC for winding temperature rise.
├── Idc_test_structural_ref: float: Reference GIC for structural temperature rise,
├── WAR_plot: tuple: Contains the Matplotlib figure and axes of the winding asymptotic response curve fit plot.
│   └── (matplotlib_figure, matplotlib_axes)
├── WTR_plot: tuple: Contains the Matplotlib figure and axes of the winding temperature rise response curve fit plot.
│   └── (matplotlib_figure, matplotlib_axes)
├── SAR_plot: tuple: Contains the Matplotlib figure and axes of the structural part response curve fit plot.
│   └── (matplotlib_figure, matplotlib_axes)
├── STR_plot: tuple: Contains the Matplotlib figure and axes of the structural part temperature rise response curve fit plot.
│   └── (matplotlib_figure, matplotlib_axes)
├── GIC_plot: tuple: Contains the Matplotlib figure and axes of the input GIC time series plot.
│   └── (matplotlib_figure, matplotlib_axes)
├── TRW_plot: tuple: Contains the Matplotlib figure and axes of the winding temperature rise plot.
│   └── (matplotlib_figure, matplotlib_axes)
└── TRS_plot: tuple: Contains the Matplotlib figure and axes of the structural part temperature rise plot.
    └── (matplotlib_figure, matplotlib_axes)

 
--------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------Examples--------------------------------------------------------
There are example python files in \ettm-master\ettm-python\examples folder.