> 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/smart-power-simulation-software-sps/blocks-functions-tools/power-transmission-and-distribution/power_loadflow.md).

# power\_loadflow

## Description

The **power\_loadflow** function performs positive-sequence load flow or unbalanced load flow and initialize models containing load flow blocks.

## Syntax

{% code lineNumbers="true" %}

```matlab
LF = power_loadflow(sys,'solve')
LF = power_loadflow(sys,'noupdate')
power_loadflow(sys,'solve','report')
power_loadflow(sys,'solve','report',fname)
power_loadflow(sys,'solve','ExcelReport',fname)
power_loadflow(sys,'AddBuses')
```

{% endcode %}

**LF = power\_loadflow(sys,'solve')** computes the load flow of sys. The model is initialized with the load flow solution.

{% hint style="info" %}
Before release R2021a, this function provided access to the machine tool initialization. Although this is still possible, use this function in release R2021a and later to initialize models containing electric machines.

Although this function continues to support the -v2 option, this option is no longer required to perform load flows. You can remove this option from your scripts and M functions.
{% endhint %}

**LF = power\_loadflow(sys,'noupdate'**) computes the load flow but does not initialize the model with the load flow solution.

**power\_loadflow(sys,'solve','report')** computes the load flow and opens the editor to save the load flow report.

**power\_loadflow(sys,'solve','report',fname)** computes the load flow and saves detailed information in the fname file.

**power\_loadflow(sys,'solve','ExcelReport',fname)** computes the load flow and saves detailed information in the fname Excel® file. This capability is available only for the positive-sequence load flow.

**power\_loadflow(sys,'AddBuses')** adds Load Flow Busblocks to the model sys. The added blocks are single-connector Load Flow Bus blocks, which specify bus parameters for a positive-sequence load flow.

## Input Arguments

| <p><strong>sys</strong> — Model for computing and initialization of loadflow<br>Model</p> | Model of which you want to compute the load flow and initialize the load flow solution.                                  |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| <p><strong>fname</strong> — File name<br>Character vector</p>                             | File name on which you want to save the detailed information of the load flow solution, specified as a character vector. |

## Output Arguments

**LF** — Load flow parameters and solutions (structure) : Load flow parameters and solutions, returned as a structure with these fields:

<table data-header-hidden><thead><tr><th width="201.422119140625">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Description</strong></td></tr><tr><td>model</td><td>The name of the model.</td></tr><tr><td>frequency</td><td>The load flow frequency, in hertz. This value corresponds to the <strong>Load flow frequency</strong> parameter of the powergui block.</td></tr><tr><td>basePower</td><td><p>The base power used by the <strong>Load Flow Analyzer</strong>.</p><p>This value corresponds to the <strong>Base power Pbase</strong> parameter of the powergui block.</p></td></tr><tr><td>tolerance</td><td><p>The tolerance used by the <strong>Load Flow Analyzer</strong>.</p><p>This value corresponds to the <strong>PQ Tolerance</strong> parameter of the powergui block.</p></td></tr><tr><td>bus</td><td><p>[1 x Nbus] structure with fields defining the bus parameters.</p><p>For a positive-sequence load flow, Nbus is the number of three-phase buses in the model. For an unbalanced load flow, Nbus is the total number of single-phase buses in the model.</p></td></tr><tr><td>sm</td><td><p>[1 x Nsm] structure with fields defining the load flow parameters of the Synchronous Machine blocks.</p><p>Nsm is the number of Synchronous Machine blocks in the model.</p></td></tr><tr><td>asm</td><td><p>[1 x Nasm] structure with fields defining the load flow parameters of the Asynchronous Machine blocks.</p><p>Nasm is the number of Asynchronous Machine blocks in the model.</p></td></tr><tr><td>vsrc</td><td><p>[1 x Nsrc] structure with fields defining the load flow parameters of the Three-Phase Source, Three-Phase Programmable Voltage Source, and AC Voltage Source blocks.</p><p>Nsrc is the number of single-phase and three-phase voltage source blocks in the model.</p></td></tr><tr><td>pqload</td><td><p>[1 x Npq] structure with fields defining the load flow parameters of the Three-Phase Dynamic Load blocks.</p><p>Npq is the number of Three-Phase Dynamic Load blocks in the model.</p></td></tr><tr><td>rlcload</td><td><p>[1 x Nrlc] structure with fields defining the load flow parameters of the Three-Phase Parallel RLC Load, Three-Phase Series RLC Load, Parallel RLC Load, and Series RLC Load blocks.</p><p>Nrlc is the number of three-phase and single-phase blocks in the model.</p></td></tr><tr><td>Ybus1</td><td>[Nbus x Nbus] positive-sequence complex admittance matrix in pu/Pbase used for positive-sequence load flow solution.</td></tr><tr><td>Ybus</td><td>[Nbus x Nbus] complex admittance matrix in pu/Pbase used for unbalanced load flow solution.</td></tr><tr><td>Networks</td><td>The bus numbers of each independent network.</td></tr><tr><td>status</td><td>Returns 1 when a solution is found, and -1 when no solution is found.</td></tr><tr><td>iterations</td><td>The number of iterations that the solver took to solve the load flow.</td></tr><tr><td>error</td><td>Displays an error message when no solution is found.</td></tr><tr><td>LoadFlowSolver</td><td>The type of load flow solver: 'PositiveSequence' or 'Unbalanced'</td></tr></tbody></table>

## Algorithms

The power\_loadflow function computes the positive-sequence load flow or the unbalanced load flow of a SPS model and initializes the load flow blocks to start simulation in steady-state. Load flow blocks are SPS blocks in which you can specify active power (P) and reactive power (Q) to solve the positive-sequence load flow.

The power\_loadflow function uses the Newton-Raphson method to provide a robust and fast convergence solution and offers most of the functionality of other load flow software available in the power utility industry.

The power\_loadflow function applies the load flow solution to the model by initializing these block parameters:

* The **Phase-to-phase voltage** and **Phase angle of phase A** parameters of Three-Phase Source blocks
* The **Positive-sequence: \[Amplitude Phase]** parameter of Three-Phase Programmable Voltage Source blocks
* The **Nominal phase-to-phase voltage** parameter of Three-Phase Parallel RLC Load and Three-Phase Series RLC Load blocks
* The **Active and reactive power at initial voltage \[Po Qo]** parameter and **Initial positive-sequence voltage Vo \[Mag(pu) Phase (deg.)]** parameter of Three-Phase Dynamic Load blocks
* The **Initial Conditions \[slip, th, ia,ib,ic, pha,phb,phc]** parameter of Asynchronous Machine blocks
* The **Initial conditions \[dw th ia,ib,ic pha,phb,phc Vf ]** parameter of Synchronous Machine and Simplified Synchronous Machine blocks

The function also initializes the following parameters of the blocks that are connected to the **Pm**, **Vf**, and **Tm** inputs of the Synchronous Machine and Asynchronous Machine blocks:

* The **Constant value** parameter of Constant blocks
* The **Initial Value** parameter of Step blocks
* The **Initial mechanical power** parameter of Hydraulic Turbine and Governor blocks
* The **Initial power and generator rotor angle** of the Steam Turbine and Governor blocks

The type of load flow solution (positive-sequence or unbalanced) is determined by the Load Flow Bus blocks present in the model. For more information on how to use the Load Flow Bus blocks in your model, see Load Flow Bus Preview.

## Examples - Performing Load Flow Analysis at the Command Line

As an alternative to using the **Load Flow Analyzer** to perform a load flow, you can use this function at the command line. For example, to perform the positive-sequence load flow on the[ Initializing a 5-Bus Network with the Load Flow Tool of Powergu](https://www.opal-rt.com/docs/smart-power-simulation-software-sps/example-models/simulation-and-analysis/initializing-a-5-bus-network-with-the-load-flow-tool-of-powergui.md)i (power\_LFnetwork\_5bus) model, enter:

```matlab
LF = power_loadflow('-v2','power_LFnetwork_5bus','solve')
```

Example returned structure:

{% code lineNumbers="true" %}

```matlab
LF =
             model: 'power_LFnetwork_5bus'
          frequency: 60
          basePower: 100000000
          tolerance: 0.0001
               Ybus1: [5x5 double]
                 bus: [1x7 struct]
                  sm: [1x1 struct]
                 asm: [1x1 struct]
                vsrc: [1x1 struct]
               pqload: [1x1 struct]
              rlcload: [1x2 struct]
            Networks: [1x1 struct]
               status: 1
           iterations: 2
                 error: ''
        LoadFlowSolver: 'PositiveSequence'
```

{% endcode %}

To obtain a detailed load flow report and prompt to save it in the MATLAB Editor:

{% code lineNumbers="true" %}

```matlab
LF = power_loadflow('-v2','power_LFnetwork_5bus','solve','report');
```

{% endcode %}

To perform an unbalanced load flow on the power\_13NodeTestFeeder model:

```matlab
LF = power_loadflow('-v2','power_13NodeTestFeeder','solve')
```

Example returned structure:

{% code lineNumbers="true" %}

```matlab
LF =
             model: 'power_13NodeTestFeeder'
          frequency: 60
          basePower: 100000
          tolerance: 0.0001
               Ybus: [29x29 double]
                 bus: [1x29 struct]
                  sm: [1x1 struct]
                 asm: [1x1 struct]
                vsrc: [1x1 struct]
               pqload: [1x1 struct]
              rlcload: [1x1 struct]
            Networks: [1x1 struct]
               status: 1
           iterations: 3
                 error: ''
        LoadFlowSolver: 'Unbalanced'
```

{% endcode %}


---

# 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/smart-power-simulation-software-sps/blocks-functions-tools/power-transmission-and-distribution/power_loadflow.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.
