### ESA Quick Start Example

Source: https://github.com/mzy2240/esa/blob/master/docs/html/_sources/snippets.rst.txt

A basic example demonstrating the initial setup and usage of ESA, also found in the quick-start guide.

```python
from esa.utils.file_utils import load_case

case = load_case("case14.py")
print(case)
```

--------------------------------

### Install ESA via Pip (Recommended)

Source: https://github.com/mzy2240/esa/blob/master/docs/html/installation.html

Use this command to install ESA using pip. It's recommended to install pywin32 separately first, especially with the --only-binary flag, to ensure proper installation.

```bash
python -m pip install --only-binary pywin32,pypiwin32 pywin32 pypiwin32 esa
```

--------------------------------

### Install ESA with Documentation Dependencies

Source: https://github.com/mzy2240/esa/blob/master/docs/html/installation.html

Install ESA from source along with dependencies required for building documentation.

```bash
python -m pip install .[doc]
```

--------------------------------

### Install ESA with Testing and Documentation Dependencies

Source: https://github.com/mzy2240/esa/blob/master/docs/html/installation.html

Install ESA from source with dependencies for both running tests and building documentation.

```bash
python -m pip install .[test,doc]
```

--------------------------------

### Install ESA from Source

Source: https://github.com/mzy2240/esa/blob/master/docs/html/installation.html

Install ESA from a local source copy after obtaining the repository. Activate your virtual environment before running this command.

```bash
cd C:\Users\myuser\git\ESA
python -m pip install .
```

--------------------------------

### Install ESA with Testing Dependencies

Source: https://github.com/mzy2240/esa/blob/master/docs/html/installation.html

Install ESA from source along with dependencies required for running tests.

```bash
python -m pip install .[test]
```

--------------------------------

### Increase Loading Example

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/welcome/what.rst

This example demonstrates how to increase the loading on the system using ESA. It requires importing the 'esa' library.

```python
import esa

# Load the PowerWorld Simulator
case = esa.Case("case.pwb")

# Increase the loading on the system
case.increase_loading()

# Save the modified case
case.save_case("case_modified.pwb")
```

--------------------------------

### Install Specific Binary Distributions for Dependencies

Source: https://github.com/mzy2240/esa/blob/master/docs/html/common_issues.html

If the general binary distribution install fails, try specifying binary distributions for only certain packages like pandas and numpy. This allows for more granular control over dependency installation.

```bash
python -m pip install --upgrade --only-binary pandas,numpy pandas numpy pywin32 pypiwin32
```

--------------------------------

### Install ESA using pip

Source: https://github.com/mzy2240/esa/blob/master/README.rst

Install the Easy SimAuto (ESA) package using pip. This command is typically used for general installation.

```bat
python -m pip install esa
```

--------------------------------

### Install NetworkX

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets/simple_graph_2000.rst

Install the NetworkX library using pip. Ensure your virtual environment is activated before running this command.

```bat
python -m pip install networkx
```

--------------------------------

### Install ESA Dependencies with Binary Distributions

Source: https://github.com/mzy2240/esa/blob/master/docs/html/common_issues.html

Install ESA's core dependencies, prioritizing binary distributions to avoid compiler issues. This command ensures compatibility and smoother installation.

```bash
python -m pip install --upgrade --only-binary :all: pandas numpy pywin32 pypiwin32
```

--------------------------------

### Install Matplotlib

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets/line_loading_matplotlib_2000.rst

Install the Matplotlib library into your Python environment. This is a prerequisite for creating visualizations.

```bat
python -m pip install -U matplotlib
```

--------------------------------

### Upgrade Pip and Setuptools

Source: https://github.com/mzy2240/esa/blob/master/docs/html/common_issues.html

Use this command to ensure you have the latest versions of pip and setuptools, which can resolve installation conflicts. Run this within your activated virtual environment.

```bash
python -m pip install --upgrade --force-reinstall pip setuptools
```

--------------------------------

### Create Simple Graph Model

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets.rst

Constructs a basic graph model from a case. This example uses a case with 2000 elements.

```python
from esa.utils.file_utils import load_case
from esa.utils.file_utils import save_case

case = load_case("case_2000.py")
case.simple_graph()
save_case(case, "case_2000_simple_graph.py")
```

--------------------------------

### Verify ESA Installation with Python Import

Source: https://github.com/mzy2240/esa/blob/master/docs/html/installation.html

Execute this command in a Command Prompt with your virtual environment activated to check if ESA can be imported successfully. Any errors indicate an installation problem.

```python
python -c "import esa; print('Success!')"
```

--------------------------------

### Initialize SAW and Get Branch Data

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets/simple_graph_2000.rst

Import necessary libraries, initialize the SAW instance with the case path, and retrieve branch parameters. This prepares the data for graph conversion.

```python
>>> from esa import SAW
>>> import pandas as pd
>>> import networkx as nx
>>> saw = SAW(CASE_PATH, early_bind=True)
>>> kf = saw.get_key_field_list('branch')
>>> kf
['BusNum', 'BusNum:1', 'LineCircuit']
>>> branch_df = saw.GetParametersMultipleElement('branch', kf)
>>> branch_df
      BusNum  BusNum:1 LineCircuit
0       1001      1064           1
1       1001      1064           2
2       1001      1071           1
3       1001      1071           2
4       1002      1007           1
...      ...       ...         ...
3199    8157      5124           1
3200    8157      8156           1
3201    8158      8030           1
3202    8159      8158           1
3203    8160      8159           1
<BLANKLINE>
[3204 rows x 3 columns]
```

--------------------------------

### Install pywin32 using Conda

Source: https://github.com/mzy2240/esa/blob/master/docs/html/installation.html

If you are using a conda environment, you can install pywin32 using the conda command.

```bash
conda install pywin32
```

--------------------------------

### Install ESA in Editable Mode

Source: https://github.com/mzy2240/esa/blob/master/RELEASE_PROCESS.rst

Install the ESA package in editable mode with test and documentation dependencies. This allows for local development and testing without copying files.

```bash
python -m pip install -e .[test,doc]
```

--------------------------------

### Increase Loading in ESA Case

Source: https://github.com/mzy2240/esa/blob/master/docs/html/_sources/snippets.rst.txt

Example showing how to increase the loading in an existing ESA case. This is useful for simulating overloaded scenarios.

```python
from esa.utils.file_utils import load_case

case = load_case("case14.py")
case.increase_loading(1.5)
print(case)
```

--------------------------------

### Install Prerequisite pywin32 Package

Source: https://github.com/mzy2240/esa/blob/master/docs/html/installation.html

Manually install the pywin32 package using pip with the --only-binary flag. This is often necessary for pywin32 to find required libraries.

```bash
python -m pip install --only-binary :all: pypiwin32 pywin32
```

--------------------------------

### Add Lines to Case

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets.rst

Shows how to add lines to an existing case. This example uses a case with a larger number of elements.

```python
from esa.utils.file_utils import load_case
from esa.utils.file_utils import save_case

case = load_case("case_2000.py")
case.add_lines(case.lines)
save_case(case, "case_2000_with_added_lines.py")
```

--------------------------------

### ESA Quick Start with Power System Analysis

Source: https://github.com/mzy2240/esa/blob/master/docs/html/snippets.html

Illustrates basic ESA usage for power flow analysis and data retrieval from a PowerWorld case file. Requires a PowerWorld case file path.

```python
from esa import SAW

CASE_PATH = r"C:\Users\myuser\git\ESA\tests\cases\ieee_14\IEEE 14 bus_pws_version_21.pwb"
saw = SAW(FileName=CASE_PATH)
saw.SolvePowerFlow()
bus_data = saw.get_power_flow_results('bus')
print(bus_data)
gen_data = saw.get_power_flow_results('gen')
print(gen_data)
gen_key_fields = saw.get_key_field_list('gen')
print(gen_key_fields)
```

--------------------------------

### Retrieve Key Fields for Loads

Source: https://github.com/mzy2240/esa/blob/master/docs/html/welcome.html

Get a list of key fields for the 'load' element.

```python
kf = saw.get_key_field_list('load')
kf
```

--------------------------------

### Run ESA Unit Tests from Source

Source: https://github.com/mzy2240/esa/blob/master/docs/html/installation.html

This sequence of commands is used to run ESA's unit tests when installed from source. Ensure your virtual environment is activated and you are in the ESA repository directory. Expected failures are normal.

```bash
cd C:\Users\myuser\git\ESA
my-venv\Scripts\activate.bat
python -m unittest discover tests
```

--------------------------------

### Docstring and Type Hinting Example

Source: https://github.com/mzy2240/esa/blob/master/contributing.md

Demonstrates a function with type hinting and a detailed reStructuredText (rst) docstring, including parameter descriptions, potential exceptions, and a link to PowerWorld documentation.

```python
def OpenCase(self, FileName: Union[str, None] = None) -> None:
    """Load PowerWorld case into the automation server.

    :param FileName: Full path to the case file to be loaded. If
        None, this method will attempt to use the last FileName
        used to open a case.

    :raises TypeError: if FileName is None, and OpenCase has never
        been called before.

    `PowerWorld documentation
    <https://www.powerworld.com/WebHelp/Content/MainDocumentation_HTML/OpenCase_Function.htm>`_
    """
```

--------------------------------

### Assess ESA Testing Coverage with Coverage.py

Source: https://github.com/mzy2240/esa/blob/master/docs/html/installation.html

After installing testing dependencies, use these commands to measure ESA's testing coverage. Run these from the top-level of the ESA repository after activating your virtual environment.

```bash
coverage run
coverage report -m
```

--------------------------------

### Transient Stability Analysis in ESA

Source: https://github.com/mzy2240/esa/blob/master/docs/html/_sources/snippets.rst.txt

Example for performing a transient stability analysis on a given contingency. Requires a case file and contingency definition.

```python
from esa.utils.file_utils import load_case
from esa.analysis.tsa import tsa

case = load_case("200.py")
result = tsa(case, "mycontingency")
print(result)
```

--------------------------------

### Create Graph Model with Weighted Edges

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets.rst

Builds a graph model where edges are weighted by branch impedance. This example uses a case with 14 elements.

```python
from esa.utils.file_utils import load_case
from esa.utils.file_utils import save_case

case = load_case("case_14.py")
case.weighted_graph()
save_case(case, "case_14_weighted_graph.py")
```

--------------------------------

### Function Naming Convention Example

Source: https://github.com/mzy2240/esa/blob/master/contributing.md

Functions and their input variables should match PowerWorld's documentation naming conventions. Internal variables should follow PEP-8.

```python
def ChangeParametersMultipleElement(self, ObjectType: str, ParamList: list,
                                    ValueList: list):
...
```

--------------------------------

### Get Line Loading Percentages

Source: https://github.com/mzy2240/esa/blob/master/docs/html/snippets.html

Fetches line loading percentages for all branches. This involves combining key fields with the 'LinePercent' parameter and using the SimAuto function.

```python
>>> params = branch_key_fields + ['LinePercent']
>>> branch_data = saw.GetParametersMultipleElement(ObjectType='Branch', ParamList=params)
>>> branch_data
      BusNum  BusNum:1 LineCircuit  LinePercent
0       1001      1064           1    30.879348
1       1001      1064           2    30.879348
2       1001      1071           1    35.731801
3       1001      1071           2    35.731801
4       1002      1007           1     5.342946
...      ...       ...         ...          ...
3199    8157      5124           1    36.371236
3200    8157      8156           1    46.769588
3201    8158      8030           1    25.982494
3202    8159      8158           1    43.641971
3203    8160      8159           1    57.452701

[3204 rows x 4 columns]
```

--------------------------------

### Create a Virtual Environment

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/installation/virtualenv.rst

Use this command to create a new virtual environment within your project directory. Adapt the paths to your Python installation and desired environment name.

```bat
cd C:\path\to\my\project
C:\path\to\python.exe -m venv my-venv
```

--------------------------------

### Plot Line Flow Histogram with Matplotlib

Source: https://github.com/mzy2240/esa/blob/master/docs/html/snippets.html

Demonstrates how to create a histogram of percent line loading using SimAuto, ESA, and Matplotlib. Requires Matplotlib to be installed.

```python
import matplotlib.pyplot as plt

# Assuming saw instance is already initialized and power flow solved
# ... code to extract line loading data ...
# plt.hist(line_loadings, bins=10)
# plt.xlabel('Percent Line Loading')
# plt.ylabel('Frequency')
# plt.title('Histogram of Line Flows')
# plt.show()
```

--------------------------------

### Create Graph Model with Edges Weighted by Branch Impedance

Source: https://github.com/mzy2240/esa/blob/master/docs/html/_sources/snippets.rst.txt

Example of creating a graph model where edges are weighted by branch impedance. This is useful for power flow and stability studies.

```python
from esa.utils.file_utils import load_case
from esa.graph.graph import Graph

case = load_case("14.py")
graph = Graph()
for line in case.lines:
    graph.add_edge(line.from_bus, line.to_bus, {"impedance": line.impedance})
print(graph)
```

--------------------------------

### Get Branch Key Fields and Parameters

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets/line_loading_matplotlib_2000.rst

Retrieve the key fields required to identify branches and then fetch multiple branch parameters, including line loading percentages.

```python
branch_key_fields = saw.get_key_field_list('Branch')
params = branch_key_fields + ['LinePercent']
branch_data = saw.GetParametersMultipleElement(ObjectType='Branch', ParamList=params)
```

--------------------------------

### Attempt to Change Generator Voltage Setpoints and Handle Error

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets/quick_start_14.rst

Attempt to change generator voltage setpoints using `change_and_confirm_params_multiple_element`. This example demonstrates how the helper function raises a `CommandNotRespectedError` if PowerWorld does not update the parameters, guiding the user to try different parameters.

```python
>>> saw.change_and_confirm_params_multiple_element('gen', gen_v)
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/mzy2240/esa/blob/master/docs/html/installation.html

Set up a Python virtual environment and activate it. This is a recommended practice for managing project dependencies.

```bash
cd C:\path\to\my\project
C:\path\to\python.exe -m venv my-venv
my-venv\Scripts\activate.bat
```

--------------------------------

### Initialize SimAuto Wrapper

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets/increase_loading_14.rst

Import the SAW class and create an instance, passing the defined CASE_PATH. This sets up the connection to the PowerWorld simulation.

```python
>>> from esa import SAW
>>> saw = SAW(CASE_PATH)
```

--------------------------------

### Initialize SAW for Power Flow Simulation

Source: https://github.com/mzy2240/esa/blob/master/docs/html/snippets.html

Initializes the SAW instance with a specified case file for power flow simulation.

```python
from esa import SAW

CASE_PATH = r"C:\Users\myuser\git\ESA\tests\cases\tx2000\tx2000_base_pws_version_21.pwb"
saw = SAW(FileName=CASE_PATH)
```

--------------------------------

### Upgrade Setuptools and Wheel

Source: https://github.com/mzy2240/esa/blob/master/RELEASE_PROCESS.rst

Ensure that setuptools and wheel are updated to their latest versions. This is a prerequisite for generating distribution archives.

```bash
python -m pip install --upgrade setuptools wheel
```

--------------------------------

### Initialize SAW and Load Case

Source: https://github.com/mzy2240/esa/blob/master/docs/html/snippets.html

Initializes the SAW instance with a specified case file path and enables early binding.

```python
from esa import SAW

CASE_PATH = r"C:\Users\myuser\git\ESA\tests\cases\ieee_14\IEEE 14 bus_pws_version_21.pwb"
saw = SAW(CASE_PATH, early_bind=True)
```

--------------------------------

### Import Libraries and Initialize SAW

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets/weighted_graph_14.rst

Import necessary libraries including NetworkX and ESA's SAW. Initialize the SAW object with the PowerWorld case file path.

```python
import networkx as nx
from esa import SAW
import re
import os
saw = SAW(CASE_PATH, early_bind=True)
g = nx.Graph()
```

--------------------------------

### Import and Initialize SAW

Source: https://github.com/mzy2240/esa/blob/master/docs/html/quick_start.html

Import the SAW class and initialize an instance using the defined case file path.

```python
from esa import SAW

saw = SAW(FileName=CASE_PATH)
```

--------------------------------

### Generate Distribution Archives

Source: https://github.com/mzy2240/esa/blob/master/RELEASE_PROCESS.rst

Create source distribution (sdist) and wheel binary distribution archives. This command should be run from the directory containing setup.py.

```bash
python setup.py sdist bdist_wheel
```

--------------------------------

### Internal Variable Naming Example

Source: https://github.com/mzy2240/esa/blob/master/contributing.md

Internal variables should conform to PEP-8, even if function names match external documentation. This example shows casting an input to lowercase for internal use.

```python
# Cast ObjectType to lower case so it matches dictionary keys. 
object_type = ObjectType.lower()
```

--------------------------------

### Get Key Fields and Single Element Parameters from PowerWorld

Source: https://github.com/mzy2240/esa/blob/master/docs/html/snippets.html

Retrieves a list of key fields for a 'branch' object and then attempts to get parameters for a single branch element using those fields. This can raise a PowerWorldError if the object is not found.

```python
line_key_fields = saw.get_key_field_list('branch')
first_line = saw.GetParametersSingleElement('branch', line_key_fields, line_df.loc[0, line_key_fields].tolist())
```

--------------------------------

### DeterminePathDistance

Source: https://github.com/mzy2240/esa/blob/master/docs/html/esa.html

Calculates a distance measure at each bus from a specified starting location.

```APIDOC
## DeterminePathDistance

### Description
Powerworld’s built-in function to calculate a distance measure at each bus in the entire model. The distance measure will represent how far each bus is from the starting group specified. The distance measure can be related to impedance, geographical distance, or simply the number of nodes.

### Parameters
#### Query Parameters
- **start** (str) - Required - The starting location. String only. Follow the powerworld auxilliary file document.
- **BranchDistMeas** (str) - Optional - is either X, Z, Length, Nodes, or a field variable name for a branch. Defaults to 'X'.
- **BranchFilter** (str) - Optional - is either ALL, Selected, Closed, or the name of a branch Advanced Filter. Defaults to 'ALL'.
- **BusField** (str) - Optional - Optional. Only need to change if the CustomFloat:1 column has been used. Defaults to 'CustomFloat:1'.

### Returns
A dataframe with bus number and distance measurements.
```

--------------------------------

### Import Libraries and Initialize SimAuto

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets/line_loading_matplotlib_2000.rst

Import necessary libraries (SAW from esa, matplotlib.pyplot) and initialize a SAW instance with the specified case file.

```python
from esa import SAW
import matplotlib.pyplot as plt

saw = SAW(FileName=CASE_PATH)
```

--------------------------------

### Transient Stability Analysis

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets.rst

Performs a transient stability analysis on a specified contingency. This example is for a case with 200 elements.

```python
from esa.utils.file_utils import load_case
from esa.utils.file_utils import save_case

case = load_case("case_200.py")
case.ts_mycontingency(case.contingencies[0])
save_case(case, "case_200_ts_mycontingency.py")
```

--------------------------------

### Initialize ESA and Process Auxiliary File for Built-in Contingency Analysis

Source: https://github.com/mzy2240/esa/blob/master/docs/html/snippets.html

Initializes ESA, loads an auxiliary file containing contingencies, and prepares for PowerWorld's built-in contingency analysis. Ensure the case has valid operating states.

```python
CASE_PATH = r"C:\Users\myuser\git\ESA\tests\cases\tx2000\tx2000_base_pws_version_21.pwb"
from esa import SAW
saw = SAW(CASE_PATH, CreateIfNotFound=True)
saw.pw_order = True
saw.SolvePowerFlow()
filepath_aux = r"C:\Users\myuser\git\ESA\tests\cases\tx2000\tx2000_contingency_auxfile.aux"
saw.ProcessAuxFile(filepath_aux)
```

--------------------------------

### Initialize PowerWorld and Load Case

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets/pw_contingency_analysis_2000.rst

Initializes the PowerWorld simulation environment and loads a specified case file. Ensure the CASE_PATH is correctly set.

```python
CASE_PATH = r"C:\Users\myuser\git\ESA\tests\cases\tx2000\tx2000_base_pws_version_21.pwb"
from esa import SAW
saw = SAW(CASE_PATH, CreateIfNotFound=True)
saw.pw_order = True
```

--------------------------------

### Initialize ESA with Case Path

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets/fast_contingency_analysis_2000.rst

Initializes the ESA SAW object with the path to the power system case file. Ensure the case file path is correct.

```python
CASE_PATH = r"C:\Users\myuser\git\ESA\tests\cases\tx2000\tx2000_base_pws_version_21.pwb"
from esa import SAW
saw = SAW(CASE_PATH)
```

--------------------------------

### Initialize SAW Instance

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets/quick_start_14.rst

Initialize the SAW instance using the specified PowerWorld case file path.

```python
saw = SAW(FileName=CASE_PATH)
```

--------------------------------

### Get Generator Parameters

Source: https://github.com/mzy2240/esa/blob/master/docs/html/snippets.html

Retrieve active power injection data for generators. This is useful for verifying changes made to generator parameters.

```python
params = gen_key_fields + ['GenMW']
new_gen_data = saw.GetParametersMultipleElement(ObjectType='gen', ParamList=params)
print(new_gen_data)
```

--------------------------------

### Get Load Parameters

Source: https://github.com/mzy2240/esa/blob/master/docs/html/welcome.html

Retrieve load data including active and reactive power demand using specified key fields.

```python
load_frame = saw.GetParametersMultipleElement('load', kf + ['LoadSMW', 'LoadSMVR'])
load_frame
```

--------------------------------

### SAW.OpenOneLine

Source: https://github.com/mzy2240/esa/blob/master/docs/html/esa.html

Opens a one-line diagram associated with a PWB file, with options to control its display and linking behavior.

```APIDOC
## SAW.OpenOneLine

### Description
Opens a one-line diagram and can be used to associate onelines with a PWB file.

### Method
```
OpenOneLine(_filename: str_, _view: str = ''_, _FullScreen: str = 'NO'_, _ShowFull: str = 'NO'_, _LinkMethod: str = 'LABELS'_, _Left: float = 0.0_, _Top: float = 0.0_, _Width: float = 0.0_, _Height: float = 0.0_) -> None
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
*   **filename** (str) - The file name of the oneline diagram to open.
*   **view** (str) - The view name to open. An empty string means no specific view.
*   **FullScreen** (str) - Set to 'YES' or 'NO' to open in full screen mode. Defaults to 'NO'.
*   **ShowFull** (str) - Set to 'YES' to apply the Show Full option, 'NO' to leave as is. Defaults to 'NO'.
*   **LinkMethod** (str) - Controls oneline linking. Options: 'LABELS', 'NAMENOMKV', 'NUMBER'. Defaults to 'LABELS'.
*   **Left** (float) - Location of the left edge as a percentage of window width (0-100). Defaults to 0.0.
*   **Top** (float) - Location of the top edge as a percentage of window height (0-100). Defaults to 0.0.
*   **Width** (float) - Width of the oneline as a percentage of window width (0-100). Defaults to 0.0.
*   **Height** (float) - Height of the oneline as a percentage of window height (0-100). Defaults to 0.0.
```

--------------------------------

### Solve Power Flow and Get Results

Source: https://github.com/mzy2240/esa/blob/master/docs/html/quick_start.html

Solve the power flow simulation and retrieve the updated generator data after parameter changes.

```python
saw.SolvePowerFlow()
new_gen_data = saw.get_power_flow_results('gen')
```

--------------------------------

### Import SimAuto Wrapper (SAW)

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets/quick_start_14.rst

Import the SimAuto Wrapper (SAW) class from the esa library to interact with PowerWorld.

```python
from esa import SAW
```

--------------------------------

### Get Generator Key Fields

Source: https://github.com/mzy2240/esa/blob/master/docs/html/quick_start.html

Identify the key fields required by PowerWorld to uniquely identify generators. These are typically 'BusNum' and 'GenID'.

```python
gen_key_fields = saw.get_key_field_list('gen')
```

--------------------------------

### Plot Histogram of Line Flows with Matplotlib

Source: https://github.com/mzy2240/esa/blob/master/docs/html/_sources/snippets.rst.txt

Shows how to plot a histogram of line flows using Matplotlib. This requires the `matplotlib` library to be installed.

```python
from esa.utils.file_utils import load_case
from esa.analysis.plot import plot_line_loading

case = load_case("2000.py")
plot_line_loading(case)
```

--------------------------------

### Initialize ESA and Run Fast N-1 Contingency Analysis

Source: https://github.com/mzy2240/esa/blob/master/docs/html/snippets.html

Initializes the ESA SAW object and performs a fast N-1 contingency analysis. Ensure the case has valid operating states; run power flow if necessary.

```python
CASE_PATH = r"C:\Users\myuser\git\ESA\tests\cases\tx2000\tx2000_base_pws_version_21.pwb"
from esa import SAW
saw = SAW(CASE_PATH)
saw.SolvePowerFlow()
saw.run_contingency_analysis('N-1')
```

--------------------------------

### SAW.get_ybus

Source: https://github.com/mzy2240/esa/blob/master/docs/html/esa.html

Retrieves the YBus matrix from PowerWorld, converting it to a scipy csr_matrix by default. Options to get the full matrix or load from a file are available.

```APIDOC
## SAW.get_ybus

### Description
Helper to obtain the YBus matrix from PowerWorld (in Matlab sparse matrix format) and then convert to scipy csr_matrix by default.

### Method
GET (Assumed based on data retrieval)

### Endpoint
Not applicable (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **full** (bool) - Optional - Convert the csr_matrix to the numpy array (full matrix).
* **file** (str | None) - Optional - Path to the external Ybus file.

### Returns
ndarray | csr_matrix

### Request Example
None provided in source.

### Response
#### Success Response (200)
Scipy csr_matrix or numpy ndarray representing the YBus matrix.

#### Response Example
None provided in source.
```

--------------------------------

### Retrieve and Modify Generator Voltage Setpoints

Source: https://github.com/mzy2240/esa/blob/master/docs/html/quick_start.html

Get the current generator voltage setpoints, modify them to 1.0 per unit, and attempt to apply these changes.

```python
gen_v = saw.GetParametersMultipleElement('gen', gen_key_fields + ['GenRegPUVolt'])
gen_v['GenRegPUVolt'] = 1.0
saw.change_and_confirm_params_multiple_element('gen', gen_v)
```

--------------------------------

### Initialize ESA and NetworkX for Graph Model Creation

Source: https://github.com/mzy2240/esa/blob/master/docs/html/snippets.html

Initializes the ESA SAW object and imports necessary libraries (pandas, networkx) for transforming a grid model into a NetworkX graph.

```python
CASE_PATH = r"C:\Users\myuser\git\ESA\tests\cases\tx2000\tx2000_base_pws_version_21.pwb"
from esa import SAW
import pandas as pd
import networkx as nx
saw = SAW(CASE_PATH, early_bind=True)
```

--------------------------------

### Perform pywin32 Post-Installation

Source: https://github.com/mzy2240/esa/blob/master/docs/html/installation.html

This command must be run from an elevated (administrator) command prompt if you intend to use pywin32 for system-wide features like COM object registration or Windows Services.

```python
python Scripts/pywin32_postinstall.py -install
```

--------------------------------

### Instantiate SAW Object

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets/add_lines_2000.rst

Create an instance of the SAW class, providing the case file path. Set CreateIfNotFound to True to allow the creation of new lines.

```python
>>> saw=SAW(FileName=CASE_PATH, CreateIfNotFound=True, early_bind=True)
```

--------------------------------

### Contingency Analysis using PW Built-in Capability

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets.rst

Utilizes the built-in PW capability for contingency analysis on a large case. This example is for a case with 2000 elements.

```python
from esa.utils.file_utils import load_case
from esa.utils.file_utils import save_case

case = load_case("case_2000.py")
case.pw_contingency_analysis(case.contingencies)
save_case(case, "case_2000_pw_contingency_analysis.py")
```

--------------------------------

### OpenOneLine()

Source: https://github.com/mzy2240/esa/blob/master/docs/html/genindex.html

Opens a one-line diagram.

```APIDOC
## OpenOneLine()

### Description
Opens a one-line diagram.

### Method
N/A (Python method)

### Endpoint
N/A (Python method)

### Parameters
None

### Request Example
```python
esa.saw.SAW.OpenOneLine()
```

### Response
Indicates successful opening of the one-line diagram.
```

--------------------------------

### Get Branch Key Fields

Source: https://github.com/mzy2240/esa/blob/master/docs/html/snippets.html

Retrieves the list of key fields required by PowerWorld to identify branches. These fields are essential for subsequent data retrieval operations.

```python
>>> branch_key_fields = saw.get_key_field_list('Branch')
>>> branch_key_fields
['BusNum', 'BusNum:1', 'LineCircuit']
```

--------------------------------

### ListOfDevicesFlatOutput()

Source: https://github.com/mzy2240/esa/blob/master/docs/html/genindex.html

Retrieves a list of devices with a flat output format.

```APIDOC
## ListOfDevicesFlatOutput()

### Description
Retrieves a list of devices with a flat output format.

### Method
N/A (Python method)

### Endpoint
N/A (Python method)

### Parameters
None

### Request Example
```python
esa.saw.SAW.ListOfDevicesFlatOutput()
```

### Response
Returns a list of devices in a flat format.
```

--------------------------------

### Get and Update Generator Voltage Setpoints

Source: https://github.com/mzy2240/esa/blob/master/docs/html/snippets.html

Retrieve and modify generator voltage setpoints. The `change_and_confirm_params_multiple_element` function is used to ensure the command is respected, raising an error if not.

```python
gen_v = saw.GetParametersMultipleElement('gen', gen_key_fields + ['GenRegPUVolt'])
print(gen_v)
gen_v['GenRegPUVolt'] = 1.0
print(gen_v)
saw.change_and_confirm_params_multiple_element('gen', gen_v)
```

--------------------------------

### esa.saw.SAW Class Initialization

Source: https://github.com/mzy2240/esa/blob/master/docs/html/esa.html

Initializes the SimAuto Wrapper (SAW) class, which interfaces with PowerWorld's SimAuto. This involves opening a PowerWorld case and optionally looking up object fields.

```APIDOC
## Class: esa.saw.SAW

### Description
Initializes the SimAuto wrapper. The PowerWorld case will be opened, and specified object fields will be retrieved. This class is the primary interface for interacting with SimAuto.

### Parameters
*   **FileName** (string) - Required - Full file path to the .pwb file to open.
*   **early_bind** (bool) - Optional - Whether to connect to SimAuto via early binding (default: False).
*   **UIVisible** (bool) - Optional - Whether to display the PowerWorld UI (default: False).
*   **CreateIfNotFound** (bool) - Optional - If True, objects updated via ChangeParameters will be created if they don't exist. If False, only existing objects are updated (default: False).
*   **object_field_lookup** (list of strings) - Optional - Listing of PowerWorld objects to initially look up available fields for (default: ('bus', 'gen', 'load', 'shunt', 'branch')).
*   **UseDefinedNamesInVariables** (bool) - Optional - If True, allows custom fields with custom headers (default: False).
*   **pw_order** (bool) - Optional - If True, maintains the exact order as shown in PW Simulator. If False, data is generally sorted in ascending order (default: False).

### Notes
Microsoft recommends early binding in most cases.
```

--------------------------------

### Initialize SAW and Solve Power Flow

Source: https://github.com/mzy2240/esa/blob/master/docs/rst/snippets/ts_mycontingency_200.rst

Initializes the SAW object with the case path and optionally solves the power flow. This is a prerequisite for TS analysis.

```python
from esa import SAW
saw = SAW(CASE_PATH)
saw.SolvePowerFlow()
```

--------------------------------

### Clone ESA Repository with Git LFS

Source: https://github.com/mzy2240/esa/blob/master/docs/html/installation.html

Clone the ESA repository using Git and Git Large File Storage. Ensure Git LFS is installed first.

```bash
cd C:\Users\myuser\git\ESA
git lfs install
git pull
git lfs pull
```

--------------------------------

### Change Generator Injections

Source: https://github.com/mzy2240/esa/blob/master/docs/html/quick_start.html

Modify the active power injection (GenMW) for specific generators using their key fields. This example changes injections at buses 3 and 8.

```python
params = gen_key_fields + ['GenMW']
values = [[3, '1', 30], [8, '1', 50]]
saw.ChangeParametersMultipleElement(ObjectType='gen', ParamList=params, ValueList=values)
```

--------------------------------

### Contingency Analysis using PW Built-in Capability

Source: https://github.com/mzy2240/esa/blob/master/docs/html/_sources/snippets.rst.txt

Example of using the Power World (PW) built-in capability for contingency analysis. This leverages external tools for analysis.

```python
from esa.utils.file_utils import load_case
from esa.analysis.pw import pw_contingency_analysis

case = load_case("2000.py")
result = pw_contingency_analysis(case)
print(result)
```

--------------------------------

### Create Simple Graph Model in ESA

Source: https://github.com/mzy2240/esa/blob/master/docs/html/_sources/snippets.rst.txt

Demonstrates the creation of a simple graph model. This is a foundational step for network analysis and visualization.

```python
from esa.graph.graph import Graph

graph = Graph()
graph.add_node(1)
graph.add_node(2)
graph.add_edge(1, 2)
print(graph)
```

--------------------------------

### Get Branch Data for Graph Model

Source: https://github.com/mzy2240/esa/blob/master/docs/html/snippets.html

Retrieves a list of key fields for branches and then fetches all branch parameters into a Pandas DataFrame, which will be used to build the graph model.

```python
kf = saw.get_key_field_list('branch')
branch_df = saw.GetParametersMultipleElement('branch', kf)
```