Introduction
The ePHASORSIM provides a Python Application Programming Interface (API) which facilitates interacting with the solver. This chapter outlines the functionality included in the API and presents a number of example use cases.
API Outline
The API aims to provide a simple and accessible way to programmatically interact with a running ePHASORSIM simulation. Two key actions, namely setting a component’s parameter, and getting a computed result, are made possible by the API. In this way, the API provides functionality similar to that of the ePHASORSIM Solver block’s Pins.
All interaction is routed through the two Python classes: 'Network' and 'Test'. The classes are located in the “opal.ephasorsim” package, inside the network and test modules respectively. The following outline lists the functionality of each class.
class opal.ephasorsim.Network list_models() Network(‘model_name’) component_list([include], [exclude]) types_of(tag) get(comp_name, param_name) get(comp_name, param_name, time) get((comp_name, param_name, time), ...) get_simulation_time() set(comp_name, param_name, value) set(comp_name, param_name, time, value) set((comp_name, param_name, time, value), ...) Note: time is relative to Now class opal.ephasorsim.Test Test(‘Network_obj_name’) set(comp_name, param_name, value) set(comp_name, param_name, time, value) set((comp_name, param_name, time, value), ...) get(comp_name, param_name, time) get((comp_name, param_name, time), ...) execute([time=0]) execute_at([my_time])
Note: my_time is an absolute time.
Component Types and Tags for API
The table below shows the list of all native components and the corresponding component type name used in python API and also the group that they belong to which is defined as a tag. These python type names and group tags can be used as an input for 'component_list()' routine to include or exclude them for listing.
List of Component Types and Their Group Tag
Native Component | Python type names | Tags (group of components) |
Bus | bus | node |
|---|---|---|
SM_T1 | sm_t1 | machine |
SM_T2 | sm_t2 | |
SM_T3 | sm_t3 | |
PSS_T1 | pss_t1 | controller, pss |
PSS_T2 | pss_t2 | |
EX_T1 | ex_t1 | controller, exciter |
EX_T2 | ex_t2 | |
TG_T1 | tg_t1 | controller, turbine_governor |
TG_T2 | tg_t2 | |
LD_CZ | ld_cz | load |
LD_CI | ld_ci | |
LD_CP | ld_cp | |
LN_PI | ln_pi | branch, line |
XF_OLTC | xf_oltc | branch, transformer |
XF_2W | xf_2w | |
XF_3W | xf_3w | |
Switch | sw | branch, switch |
Fixed Shunt | sh_fixed | shunt |
Current Injector | i_inj | source |
Multiphase Load (Single Phase) | ld_zip_1p | load |
Multiphase Load (Two Phase) | ld_zip_2p | |
Multiphase Load (Three Phase) | ld_zip_3p | |
Multiphase Shunt (Single Phase) | sh_1p | shunt |
Multiphase Shunt (Two Phase) | sh_2p | |
Multiphase Shunt (Three Phase) | sh_3p | |
Transformer 3-phase | xf_3p | branch, transformer |
Transformer 3-phase Mutual | xfm_3p | |
Multiphase Line (Single Phase) | ln_pi_1p | branch, line |
Multiphase Line (Two Phase) | ln_pi_2p | |
Multiphase Line (Three Phase) | ln_pi_3p_ | |
Multiphase Fault (Single Phase) | flt_1p | fault |
Multiphase Fault (Two Phase) | flt_2p | |
Multiphase Fault (Three Phase) | flt_3p |
Example
See demo ‘PHASOR-13’ and ‘PHASOR-15’.
The following script demonstrates some of the API routines in action. First, select the Use post-init script checkbox in the Scripting tab of the Solver block and provide the '.py' script file containing the API routines. Then, when the simulation runs, the API commands in the '.py. file are executed. Alternatively, these commands can be executed step by step while the simulation is running using the RT-LAB python console. For example, load ‘phasor01_IEEE39’ example model on a target using RT-LAB and open the RT-LAB python console (under Tools/Python/Open Console). Finally, run the model and enter the commands one by one, while inspecting the results on a Simulink scope.
Note: Before running the simulations, make sure that the file “simulation.json” does not exist in the directory: C:\Users\[User Name]\AppData\Local\ePHASORSIM
file: my_first_script.py ======================== from opal.ephasorsim import Network,Test my_network = Network(‘phasor01_IEEE39’) # Set up a test sequence where a fault is applied to bus 30, 1 second into the # test execution. The fault is cleared 0.08s thereafter. my_test = Test(my_network) my_test.set( (“30”, “active3PGFault”, 1, True), (“30”, “active3PGFault”, 1.08, False)) my_test.execute()