> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/rt-lab/example-models/ephasorsim-example-models/python-api-to-define-event-sequences.md).

# Python API to Define Event Sequences

## Description

The **Python API to Define Event Sequences** example can be created by starting a new RT‑LAB project. From the menu bar, select **File > New > RT‑LAB Project**. Enter a name and location for your project, then click **Next**. From the available templates list, navigate to **ePHASORsim** and select **phasor12\_api**, then click **Finish**.

A Python-based API is available to interact with power system objects of an existing ePHASORSIM model. This API replaces the incoming and outgoing pins with predefined set() & get() routines. The script that includes the API routines can run in off-line and real-time simulation modes to automate the test sequences. Moreover, the API routines can also be called through the RT-LAB's Python console interactively after loading the model, to send a control command (an incoming instruction) or acquire measurements (e.g. Vmag of a bus).

To run API routines, "Use post-init script" must be checked in "Scripting" tab in the mask of ePHASORSIM solver and a script must be defined in the corresponding editor box.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-f9bb3fcfdb05c4d3e0f64d1038e2d345090e8618%2FePHASORsim_block.jpg?alt=media" alt=""><figcaption></figcaption></figure>

This script can include API routines to be initialized at the beginning of the simulations, or it can be left blank if the user wants to apply API routines later on in an interactive mode through RT-LAB Python console.

{% hint style="danger" %}
The `get` routine cannot be used inside the post-init script. However, it can be called in RT-LAB console after loading the model.
{% endhint %}

## Simulation and results

The present demo is a copy of **phasor01 example** except that it uses API routines to replace all the incoming pins to run exactly the same scenario. The Python script for this demo is called **test\_sequence.py**.

{% code overflow="wrap" lineNumbers="true" %}

```python
from opal.ephasorsim import Network, Test
MODEL_NAME = "phasor12_api"
def event_sequence(test):
    # Apply fault on bus 30, at t = t0 + 1 seconds
    test.set("30", "active3PGFault", 1.0, 1)
    # Remove fault on bus 30, at t= t0 + 1.08 seconds
    test.set("30", "active3PGFault", 1.08, 0)
    # Change primary winding ratio of 'xf1' to 0.9 p.u., at t = t0 + 5 seconds
    test.set("xf1", "rW1", 5.0, 0.9)
    # Disconnect load 'ld7', at t = t0 + 9 seconds
    test.set("ld7", "status", 9.0, 0)
def main():
    # Create network instance for 'phasor12_api'
    network = Network(MODEL_NAME)
    # Create test instance for network_object
    test = Test(network)
    # Call event_sequence function
    event_sequence(test)
    # Execution time of the test_object
    t0 = 0
    # Execute test_object, t0 seconds after starting of the simulation
    test.execute_at(t0)
# This Python module gets imported by ePHASORSIM.
# Hence, we just call the main function here directly.
main()
```

{% endcode %}

* In **line 1**, two classes, Network and Test, are imported from opal.ephasorsim module. Network is the main class to define network objects and it includes all API functions. On the other hand, Test class is used to define test objects, in which a list of test sequences are defined and can be executed later on.
* In **line 23**, a network object, called network, is created for phasor12\_api.slx.
* Afterwards, in **line 10**, a test object, called test, is created for the network object network.
* In **line 7**, a user defined function, event\_sequence, is called in which a list of events are set for test\_object. As can be seen in this function, set routine is used to set a specific parameter of a component to a new value at a certain time. For example, in line 4, for the bus component '30', the parameter 'active3PGFault' is set to 1 at 1 seconds after execution of the test object, test\_object. The same parameter is set back to 0 at 1.08 seconds after execution of the test.
* Finally, in **line 35**, the test object test is executed at t0 = 0 seconds using execute\_at() function.

{% hint style="info" %}
The time input for execute\_at(t0) function, is the absolute time. i.e. the test object executes t0 seconds after starting of the simulation. On the other hand, the time value, te used as an input for set and get routines are relative to t0, i.e. the event will be in effect t0 + te seconds after starting of the simulation.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/rt-lab/example-models/ephasorsim-example-models/python-api-to-define-event-sequences.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
