> 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-for-test-automation.md).

# Python API for Test Automation

## Description

The **Python API for Test Automation** 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 **phasor13\_AUTOMATE**, then click **Finish**.

In this demo both the RT-LAB and ePHASORSIM API are used to automate running of a predefined test scenario.

* The **RT-LAB API routines** control the start/stop of the simulation and collect and save the results.
* The **ePHASORSIM API routines** are used to apply the changes to the power system under-test during each round of simulation.

The recorded results are in MAT file format that later on can be used for several types of analysis. The combination of these two APIs is an automated dynamic contingency study.

The **test\_dynamic\_contingency.py** is the file that contains the RT-LAB API routines and the ePHASORSIM API routines needed for the automation of running a contingency test. To run this demo, the model needs to be complied in the RT-LAB first.

{% file src="/files/XFCRMZS7YMMJpCmiAMEr" %}

In test\_dynamic\_contingency.py besides the main part of the script there are five functions. find\_lpp(), sm\_folder\_directory() and copy\_file() are to set up the required simulation parameters in RT-LAB. The other two functions, i.e. n\_minus\_one() and n\_minus\_two(), are using ePHASORSIM API routines to mimic contingency studies in power system.

In the main part of the script, after loading the model through RT-LAB API, the ePHASORSIM API routine component\_list(object1, object2...) is used to list all the machine and line types in the network. There are 10 machines and 34 transmission lines in this test case. Then two groups of test-sequence to study the impact of disconnecting the listed components are provided as N-1 and N-2 contingency tests.

In N-1 contingency scenario the transmission lines in the network are successively tripped, one per simulation and at t = 1s. This scenario runs automatically for 34 times.

In N-2 contingency scenario the lines and generators are tripped, one line and one generator per simulation and at time t = 1s. This scenario runs automatically for 340 times.

Although the default test in this demo is set for N-1 contingency test, the switching between the two groups of tests is enabled by the following line of code:

```
CONTINGENCY_TYPE = "minus_one" # or "minus_two"
```

**Additional notes:**

* To speedup the simulation at each run, RT-LAB is set to run in 'simulation mode' instead of 'software synchronized'. This can be revised at this line of script:

```python
REAL_TIME_MODE = RtlabApi.SIM_MODE
```

* The simulation time for the two groups of the test is set to 10s. This can be revised at this line of script:

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

```python
RtlabApi.SetStopTime(10)
```

{% endcode %}

## Requirements

* MATLAB R2019b and later
* A Python IDE can be configured to ease the use of Python such as PyCharm \[1].

## Simulation and results

The following measurements are set to be saved per each test:

* Voltage magnitude at buses *2, 4, 9, 11, 16, 26, 29, 30, 31, 32, 34, 39*
* Each machine's relative rotor angle (Machine 39 is selected as the reference machine.)
* Each Machine's speed

At each run, these data are recorded in results\_of\_test\_ID.mat, in which the ID is adjusted dynamically changes from 1 to 34 (for N-1) and from 1 to 340 (for N-2).

Some of the results for N-1 and N-2 contingency tests are shown here:

Figure below shows the following figure shows the relative rotor angle between generator 30 and 39 for 5 cases in the N-1 contingency scenario.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-3d1cfbf4ed3276d4d9e939786b505b42c0df1eaf%2Fphasor13_test_automation_n-1.png?alt=media" alt=""><figcaption><p>Relative rotor angle between generator 30 and 39.</p></figcaption></figure>

Following figure shows some sample results of N-2 contingency scenario. Specifically in this case, it is the relative rotor angle between generator 30 and 39 for 5 cases in the N-2. In this case generator 31 is tripped along with the lines mentioned in the legend.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-ff681102d6be03e98a2c94b197af2757b4d1cbfb%2Fphasor13_test_automation_n-2.png?alt=media" alt=""><figcaption><p>Relative rotor angle between generator 30 and 39 for N-2 contingency scenario.</p></figcaption></figure>

## References

\[1] *PyCharm Community Edition* is a Python IDE, which can be downloaded from [JetBrains](https://www.jetbrains.com/pycharm/).


---

# 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-for-test-automation.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.
