Page Content

1 Introduction
2 API Outline
3 Component Types and Tags for API
4 Example

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.

# from opal.ephasorsim import Network
class Network:

	def list_models():
		...

	def Network('model_name'):
		...

	def component_list([include], [exclude]):
		...

	def types_of(tag):
		...

	def get(comp_name, param_name):
		...

	def get(comp_name, param_name, time):
		...

	def get((comp_name, param_name, time), ...):
		...

	def get_simulation_time():
		...

	def set(comp_name, param_name, value):
		...

	def set(comp_name, param_name, time, value):
		...

	def set((comp_name, param_name, time, value), ...):
		...

# from opal.ephasorsim import Test
class Test:

	def Test('Network_obj_name'):
		...

	def set(comp_name, param_name, value):
		...

	def set(comp_name, param_name, time, value):
		...

	def set((comp_name, param_name, time, value), ...):
		...

	def get(comp_name, param_name, time):
		...

	def get((comp_name, param_name, time), ...):
		...

	def execute([time = 0]):
		...

	def execute_at([my_time]):
		...

Notes

my_time is an absolute time.
time is relative to Now

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)

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`	`controller, pss`
EX_T1	`ex_t1`	`controller, exciter`
EX_T2	`ex_t2`	`controller, exciter`
TG_T1	`tg_t1`	`controller, turbine_governor`
TG_T2	`tg_t2`	`controller, turbine_governor`
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`	`branch, transformer`
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 examples phasor13_AUTOMATE and phasor15_IEEE_EURO_LV.

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 the 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 simulations.json does not exist in the directory: %LOCALAPPDATA%\ePHASORSIM

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()