-
+
Figure 1: Needs to be changed to represent current balance instead of power
balance.
@@ -28,3 +28,27 @@ sign.
**Other Parameters**
Buses are uniquely defined by their ID (number or name). Besides, each bus
should have associated Nominal Voltage value.
+
+## Actions
+
+This component accepts the following runtime events via `apply(Action)`. See
+[EVENTS.md](../EVENTS.md) for the dispatch model and JSON schema.
+
+JSON | Params | Effect
+----------------|----------|--------------------------------------------------------------------
+`"fault"` | `R`, `X` | Stores the fault impedance and engages the fault ($U = 1$).
+`"clear"` | none | Disengages the fault ($U = 0$). Stored impedance is unchanged.
+
+While the fault is engaged, the bus current balance gains the contributions:
+
+``` math
+\begin{aligned}
+ G_f &= \dfrac{R}{R^2 + X^2}, \quad B_f = -\dfrac{X}{R^2 + X^2} \\
+ \Delta I_{rk} &= U(-G_f V_{rk} + B_f V_{ik}) \\
+ \Delta I_{ik} &= U(-B_f V_{rk} - G_f V_{ik})
+\end{aligned}
+```
+
+The `percent` parameter of `Fault` is ignored by `Bus`. The fault gate $U$
+is implemented as a mask (0 or 1) on the fault residual term,
+so the Jacobian sparsity pattern is fixed across `Fault`/`Clear` cycles.
diff --git a/GridKit/Model/PhasorDynamics/EVENTS.md b/GridKit/Model/PhasorDynamics/EVENTS.md
new file mode 100644
index 000000000..91dec8518
--- /dev/null
+++ b/GridKit/Model/PhasorDynamics/EVENTS.md
@@ -0,0 +1,115 @@
+# Phasor Dynamics Events
+
+## Overview
+
+This document describes the runtime event system for PhasorDynamics
+components. A runtime event mutates the state of a single component during simulation. Events are scheduled in a solver file
+(see [PDSim](../../../application/PhasorDynamics/README.md)) and delivered to components by `SystemModel` at their scheduled times. Buses are addressed for events by their existing `number`; devices by their
+existing `id`.
+
+## Event
+
+An event is a triple of fields:
+
+Name | Description
+---------|------------------------------------------------------
+`time` | Simulation time at which the event fires, in seconds
+`target` | Routing key for the component receiving the event
+`action` | The mutation to perform, drawn from the action vocabulary
+
+For buses, the `target` is the bus's `number` rendered as a string
+(e.g. `"1001"`). For devices, it is the device's `id` field from the case
+file (e.g. `"BR_1001_1064_1"`). Buses and devices share a single routing
+namespace; collisions between a bus number and a device id are an error at registration.
+
+
+```cpp
+struct Event {
+ double time;
+ std::string target;
+ Action action;
+};
+```
+
+## Action vocabulary
+
+`Action` is a `std::variant` of action structs in
+`GridKit::PhasorDynamics::Actions`. Each struct has a canonical name string
+exposed as `static constexpr std::string_view name`.
+
+C++ type | JSON name | Params | Applies to
+-----------------|-----------|---------------------|----------------
+`Actions::Open` | `open` | none | `Branch`
+`Actions::Close` | `close` | none | `Branch`
+`Actions::Fault` | `fault` | `R`, `X`, `percent` | `Bus`, `Branch`
+`Actions::Clear` | `clear` | none | `Bus`, `Branch`
+
+The semantics of each action are documented in the receiving component's
+README. For `fault`, the `percent` parameter (position along the line as a
+percent in `[0, 100]`) is used by `Branch` and ignored by `Bus`.
+
+## Dispatch
+
+`Component::apply(const Action&)` is virtual on the base class. The default
+throws. Components that handle events override it with a `std::visit` over
+the variant, dispatching to per-action handlers and falling through to a
+generic catch-all for unhandled action types:
+
+```cpp
+void Bus::apply(const Action& a) override {
+ std::visit(overloaded{
+ [this](const Actions::Fault& f) {},
+ [this](const Actions::Clear&) {},
+ [this](const auto& other) {
+ using A = std::decay_t
-
-
+
+
Figure 2: Branch equivalent circuit