> 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/hypersim/library-blocks-reference/network-switches-and-breakers/fault-3-phase.md).

# Fault, 3-Phase

## Description

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-7c4d38e09dbd25fcb0bf51ce14b8998f500b457d%2Fimage%20(1086).png?alt=media" alt="" width="70"><figcaption></figcaption></figure>

The **Fault, 3-Phase** block, located in the **Network Switches and Breakers** library, simulates a 3‑phase fault using a 3‑phase circuit breaker connected to ground on its second terminal. The block models a variable resistance: very low when closed and very high when open.

You can control it using internal timing or an external source via the schematic input or simulator digital inputs.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-1c76fcc349b3c26d1db59012ad0126149c8a6d00%2Fimage%20(445).png?alt=media" alt=""><figcaption></figcaption></figure>

The circuit breaker can be controlled with the external pin.

<details>

<summary><strong>Using the Input Pin</strong></summary>

The input signal is of integer type and is internally converted to a logic value for all phases. The following tables show how to use the inputs:\
Input=0 -> State open ; Input=1 -> State close

Bit order from least to most significant is A, B, C, G. Examples: 1 closes A only; 3 closes A and B; 12 closes C and G; 15 closes A, B, C, and G.

<table><thead><tr><th width="102.39996337890625">Input</th><th width="101.60003662109375">G</th><th width="104">C</th><th width="100.79998779296875">B</th><th width="102">A</th><th></th></tr></thead><tbody><tr><td>0</td><td>0</td><td>0</td><td>0</td><td>0</td><td></td></tr><tr><td>1</td><td>0</td><td>0</td><td>0</td><td>1</td><td>A</td></tr><tr><td>2</td><td>0</td><td>0</td><td>1</td><td>0</td><td>B</td></tr><tr><td>3</td><td>0</td><td>0</td><td>1</td><td>1</td><td>AB</td></tr><tr><td>4</td><td>0</td><td>1</td><td>0</td><td>0</td><td>C</td></tr><tr><td>5</td><td>0</td><td>1</td><td>0</td><td>1</td><td>AC</td></tr><tr><td>6</td><td>0</td><td>1</td><td>1</td><td>0</td><td>BC</td></tr><tr><td>7</td><td>0</td><td>1</td><td>1</td><td>1</td><td>ABC</td></tr><tr><td>8</td><td>1</td><td>0</td><td>0</td><td>0</td><td>G</td></tr><tr><td>9</td><td>1</td><td>0</td><td>0</td><td>1</td><td>AG</td></tr><tr><td>10</td><td>1</td><td>0</td><td>1</td><td>0</td><td>BG</td></tr><tr><td>11</td><td>1</td><td>0</td><td>1</td><td>1</td><td>ABG</td></tr><tr><td>12</td><td>1</td><td>1</td><td>0</td><td>0</td><td>CG</td></tr><tr><td>13</td><td>1</td><td>1</td><td>0</td><td>1</td><td>ACG</td></tr><tr><td>14</td><td>1</td><td>1</td><td>1</td><td>0</td><td>BCG</td></tr><tr><td>15</td><td>1</td><td>1</td><td>1</td><td>1</td><td>ABCG</td></tr></tbody></table>

</details>

## Mask parameters

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-1f33289f3e0c12422bb7b910ee864e293dafe839%2Ffault%203.jpg?alt=media" alt=""><figcaption></figcaption></figure>

{% tabs %}
{% tab title="Timing" %}

<table><thead><tr><th width="209.79998779296875" valign="top">Parameter</th><th>Description</th></tr></thead><tbody><tr><td valign="top"><strong>Time units</strong></td><td>Units applied to programmed state-transition operations Ut Options:<br>- Second (s): all T<sub>n</sub> values in seconds.<br>- Millisecond (ms): all T<sub>n</sub> values in milliseconds.<br>- Cycle (c): all T<sub>n</sub> values in electrical cycles (requires frequency).</td></tr><tr><td valign="top"><strong>General operation</strong></td><td>Master switch to enable/disable programmed operations at acquisition trigger EnaGen.<br>- Disable (0): programmed operations are disabled.<br>- Enable (1): programmed operations are enabled.</td></tr><tr><td valign="top"><strong>Steady-state condition</strong></td><td>Initial state of phase and ground breakers EtatIniA, EtatIniB, EtatIniC , EtatIniN .<br>colored = closed (0), grey = open (1)</td></tr><tr><td valign="top"><strong>Network frequency</strong></td><td>Legacy. Set frequency using Base frequency instead (Hz) Freq [45, 70]).</td></tr><tr><td valign="top"><strong>Model type</strong></td><td>Per phase, select Switch or Breaker behavior (TypeA/TypeB/TypeC/TypeN.<br>- Breaker (0): after the time condition is met, waits for current to cross breaking capacity before changing state.<br>- Switch (1): changes state immediately when the time condition is met.</td></tr><tr><td valign="top"><strong>Enable (per step)</strong></td><td>Enable/disable the state-transition operation for each line/step (EnaT1, EnaT2, ... ).<br>- Disable (0): transition on that line is disabled.<br>- Enable (1): transition on that line is enabled. If enabled but no data is provided, the operation is ignored.</td></tr><tr><td valign="top"><strong>Time</strong></td><td><p>Relative time (with respect to <a href="https://www.opal-rt.com/docs/hypersim/library-blocks-reference/network-tools/point-on-wave-synchronization.md">POW synchronization</a>) when the command is sent to change state. Enter as a single string; timing type and values are combined (T1, T2, ... ). There are four formats:</p><ul><li><strong>Fixed</strong>: <em>f: fixed time</em> T<sub>n</sub> is constant across acquisitions.</li><li><strong>Incremental</strong>: <em>i: initial/final/increment</em> T<sub>n</sub> starts at initial, increases by increment each acquisition, and resets after reaching final</li><li><strong>Uniform</strong>: <em>u: min/max</em> T<sub>n</sub> is uniformly random within [min, max] each acquisition.</li><li><strong>Uniform gaussian</strong>: <em>ug: min/max/dispersion</em> T<sub>n</sub> is random with a gaussian distribution within [min, max].</li></ul><p><br>Important notes:</p><ul><li>Programmed operation times must satisfy: T<sub>n</sub> > T<sub>n-1</sub></li><li>If a field is blank or contains “-”, no switching occurs on that line.</li><li>No alias exists for timing type in the API; enter timing type and values as a single string.</li><li>With referenced operations, the calculated time is applied after the command is received from the other component. See Referenced operations.</li></ul></td></tr><tr><td valign="top"><strong>Referenced operations</strong></td><td>Trigger T<sub>n</sub> by referencing another breaker’s programmed transition. All fields must be filled to activate referencing. See <a href="https://opal-rt.atlassian.net/wiki/spaces/PDOCHS/pages/20193179/Circuit+Breaker%2C+3-Phase#ReferencedOperations">Referenced Operations</a>.<br>- Component: name or path of the breaker to reference (Eref1, Eref2, ... = 'path.name').<br>- Time: T<sub>n</sub> ID of the referenced breaker’s step (Tref1, Tref2, ... = T<sub>n</sub>).<br>- Phase/Command: activate (Phase) or deactivate (Command) the reference dependency (T1RPh, T2RPh, ... = 0 or1).</td></tr><tr><td valign="top"><strong>Phase operated</strong></td><td>Select which phases (or ground) change state when this step triggers. The selection toggles the current state. Variables (per step): T1Pa, T1Pb, T1Pc, T1Pg = {0, 1}; T2Pa, T2Pb, T2Pc, T2Pg = {0, 1}.<br>- ON (1): a state transition occurs (colored).<br>- OFF (0): no state transition (grayed out).</td></tr></tbody></table>
{% endtab %}

{% tab title="General" %}

<table><thead><tr><th width="199.5999755859375">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Description</strong></td><td>Free-text field to document the block</td></tr><tr><td><strong>Control type</strong></td><td>Select the command source for the breakers’ state CmdBlockSelect Options:<br>- Internal (0): control defined in the Timing parameters tab.<br>- External (input sensors) (1): simulator digital inputs on CMD(a,b,c,n).<br>- External (input pins) (3): schematic control via input P; the received integer is converted to a binary string where each digit corresponds to a phase (or ground).</td></tr><tr><td><strong>Ropen</strong></td><td>Open-state resistance of phase breakers (Ω), ROpen [0, 1e12].</td></tr><tr><td><strong>Rclosed</strong></td><td>Closed-state resistance of phase breakers (Ω), RClose [0, 1e12].</td></tr><tr><td><strong>Current chopping current</strong></td><td>Threshold for the absolute current below which the breaker is forced to open (simulates current chopping) (A) IMargin = [0, 1e64].<br>Applies only when Model type = Breaker .</td></tr><tr><td><strong>Base power</strong></td><td>Base value for per‑unit conversion (MVA total) pBase [1, 1e64].</td></tr><tr><td><strong>Base voltage</strong></td><td>Base value for per‑unit conversion (kV rms LL) vBase [1, 1e64].</td></tr><tr><td><strong>Base frequency</strong></td><td>Base value for per‑unit conversion (Hz) fbase [1, 1e64].</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## Conserving ports

<table><thead><tr><th width="199.60003662109375">Port</th><th>Description</th></tr></thead><tbody><tr><td><strong>Net_1</strong></td><td>Network connection (3‑phase only).</td></tr></tbody></table>

## Inputs

<table><thead><tr><th width="199.5999755859375">Input</th><th>Description</th></tr></thead><tbody><tr><td><strong>P</strong></td><td>Control input for all phase and ground breaker commands. The received integer is converted to a binary string where each digit corresponds to a phase (or ground).</td></tr></tbody></table>

## Outputs

This block has no outputs.

## Signals available for monitoring and external I/O connections (via sensors form)

All block inputs and outputs are available as signals for monitoring and for external I/O connections.

Additional signals are also available and are listed below with their descriptions.

<table><thead><tr><th width="199.60003662109375">Signal</th><th>Description</th></tr></thead><tbody><tr><td><strong>CMD(a,b,c,n)</strong></td><td>Phase and ground breaker commands (unitless). Can be mapped to simulator digital inputs.</td></tr><tr><td><strong>I(a,b,c,n)</strong></td><td>Phase and ground breaker currents (A).</td></tr><tr><td><strong>Psw(a,b,c,n)</strong></td><td>Instantaneous apparent power measured at the positive port of the breaker for each phase (VA).</td></tr><tr><td><strong>STATE(a,b,c,n)</strong></td><td>Phase and ground breaker states (unitless). May differ from commands depending on the Model type parameter.</td></tr><tr><td><strong>V(a,b,c,n)</strong></td><td>Phase breaker voltages (V).</td></tr></tbody></table>


---

# 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/hypersim/library-blocks-reference/network-switches-and-breakers/fault-3-phase.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.
