Jb/documentation updates

docs/make.jl

@@ -42,8 +42,13 @@ pages = OrderedDict(
                 "Save and read data with a JSON" => "how_to/serialize_data.md",
             ],
             "...add a component using natural units (MW)" => "how_to/add_component_natural_units.md",
+            "...use subsystems" => "how_to/use_subsystems.md",
             "...use context managers for bulk operations" => "how_to/use_context_managers.md",
-            "...add additional data to a component" => "how_to/adding_additional_fields.md",
+            "...add additional data to a component" => Any[
+                "Add Supplemental Attributes to a System" => "how_to/add_supplemental_attributes.md",
+                "Use Supplemental Attributes" => "how_to/use_supplemental_attributes.md",
+                "Add additional fields to a component" => "how_to/adding_additional_fields.md",
+            ],
             "...add time-series data" => Any[
                 "Parse time series data from .csv files" => "how_to/parse_ts_from_csvs.md",
                 "Improve performance with time series data" => "how_to/improve_ts_performance.md",
@@ -75,7 +80,7 @@ pages = OrderedDict(
             "explanation/transformer_per_unit_models.md",
             "explanation/time_series.md",
             "explanation/dynamic_data.md",
-            "explanation/supplemental_attributes.md",
+            "explanation/supplemental_attributes_2.md",
             "explanation/plant_attributes.md",
             ],
         "Model Library" => Any[],

docs/src/api/enumerated_types.md

@@ -92,7 +92,7 @@ EIA Annual Energy Review. `ThermalFuels` has the options:
 | `BLACK_LIQUOR`                                                                                                                     | BLQ           | Black Liquor                                                                                                                        |
 | `WOOD_WASTE_LIQUIDS`                                                                                                               | WDL           | Wood Waste Liquids excluding Black Liquor (includes red liquor, sludge wood, spent sulfite liquor, and other wood-based liquids)    |
 | `LANDFILL_GAS`                                                                                                                     | LFG           | Landfill Gas                                                                                                                        |
-| `OTHEHR_BIOMASS_GAS`                                                                                                               | OBG           | Other Biomass Gas (includes digester gas, methane, and other biomass gasses)                                                        |
+| `OTHER_BIOMASS_GAS`                                                                                                                | OBG           | Other Biomass Gas (includes digester gas, methane, and other biomass gasses)                                                        |
 | `NUCLEAR`                                                                                                                          | NUC           | Nuclear Uranium, Plutonium, Thorium                                                                                                 |
 | `WASTE_HEAT`                                                                                                                       | WH            | Waste heat not directly attributed to a fuel source                                                                                 |
 | `TIREDERIVED_FUEL`                                                                                                                 | TDF           | Tire-derived Fuels                                                                                                                  |
@@ -159,7 +159,7 @@ the different alternatives of `ReservoirDataType`, which has the options:
 | `CONFORMING`     | Conforming load                                                   |
 | `UNDEFINED`      | Undefined or unknown whether load is conforming or non-conforming |
 
-## [Tranformer Control Objectives](@id xtf_crtl)
+## [Transformer Control Objectives](@id xtf_crtl)
 
 `TransformerControlObjective` is used to select the control objective for a transformer's
 tap changer, which can be used to determine the tap position during power flow calculations.

docs/src/api/glossary.md

@@ -1,7 +1,7 @@
 # Glossary and Acronyms
 
-[A](@ref) | [D](@ref) | [E](@ref) | [F](@ref) | [H](@ref) | [I](@ref) | [O](@ref) | [P](@ref) | [R](@ref) |
-[S](@ref) | [V](@ref) | [W](@ref) | [Z](@ref)
+[A](@ref) | [C](@ref) | [D](@ref) | [E](@ref) | [F](@ref) | [H](@ref) | [I](@ref) | [O](@ref) | [P](@ref) | [R](@ref) |
+[S](@ref) | [U](@ref) | [V](@ref) | [W](@ref) | [Z](@ref)
 
 ### A
 
@@ -13,19 +13,26 @@
 
   - *AVR*: Automatic Voltage Regulator
 
+### C
+
+  - *CAISO*: California Independent System Operator
+
 ### D
 
   - *DC*: Direct current
 
   - *DERA1*:
 
+  - *Deterministic*: mathematical model in which the outcomes are precisely determined through known relationships among states and events. For contrast, see the definition of [Probabilistic](@ref P).
+
   - *Dynamic*: Refers to data and simulations for power system transient simulations using differential
     equations. Common examples include signal stability analysis to verify the power system will
     maintain stability in the few seconds following an unexpected fault or generator trip. For contrast,
     see the definition for [Static](@ref S) data.
 
 ### E
 
+  - *EIM*: Energy Imbalance Market
   - *EMF*: Electromotive force
   - *ESAC*: IEEE Type AC Excitation System model
   - *ESDC*: IEEE Type DC Excitation System model
@@ -91,6 +98,8 @@
 
   - *PPA*: Power purchase agreement
 
+  - *Probabilistic*: mathematical model in which the outcomes represent random phenomenon. For contrast, see the definition of [Deterministic](@ref D).
+
   - *PSI*: [`PowerSimulations.jl`](https://nrel-sienna.github.io/PowerSimulations.jl/latest/)
 
   - *PSID*: [`PowerSimulationsDynamics.jl`](https://nrel-sienna.github.io/PowerSimulationsDynamics.jl/stable/)
@@ -133,6 +142,15 @@
 
   - *STAB*: Speed Sensitive Stabilizing PSS Model
 
+  - *Struct*: A composite data type in Julia that can store multiple values in a single object.
+    See the Julia documentation on [`struct`](https://docs.julialang.org/en/v1/base/base/#struct)
+    and [Composite Types](https://docs.julialang.org/en/v1/manual/types/#Composite-Types).
+
+### U
+
+  - *UUID*: Universally Unique Identifier. A 128-bit identifier formatted as a 32-character
+    hexadecimal string (e.g. `5f180c4c-cd81-4b80-8c60-627c28aef8b0`).
+
 ### V
 
   - *VSCLine*: Voltage-Source Converter HVDC Line
@@ -141,6 +159,8 @@
 
 ### W
 
+  - *WECC*: Western Electricity Coordinating Council
+
   - *Window*: A forecast window is one forecast run that starts at one [initial time](@ref I)
     and extends through the forecast [horizon](@ref H). Typically, a forecast data set
     contains multiple forecast windows, with sequential initial times. For example, a

docs/src/api/static_injection_subtypes.md

@@ -41,7 +41,7 @@ This document summarizes the similarities and differences between [`StaticInject
 
 ² EnergyReservoirStorage uses `input_active_power_limits` and `output_active_power_limits` instead
 
-Here, "`MinMax` (optional)" means `Union{MinMax, Nothing}`, with `nothing` repesenting "no limits" and being the default.
+Here, "`MinMax` (optional)" means `Union{MinMax, Nothing}`, with `nothing` representing "no limits" and being the default.
 
 ⊕ = Split across 3 ZIP fields: `*_constant_*`, `*_impedance_*`, `*_current_*`
 

docs/src/explanation/buses_type_explanation.md

@@ -1,45 +1,98 @@
 # [Understanding ACBusTypes](@id bustypes)
 
-`PowerSystems.jl` supports multiple types of AC buses, [listed here](@ref acbustypes_list).
-When creating nodal datasets, the definitions for AC Buses can have a significant impact on the
-topology logic for the network.
+In AC power flow analysis, every bus in the network has four associated quantities: real
+power injection ($P$), reactive power injection ($Q$), voltage magnitude ($|V|$), and
+voltage angle ($\delta$). The power flow problem is solvable only when exactly two of
+these four quantities are specified at each bus — the other two are determined by the
+solver. The `ACBusType` of a bus declares which two quantities are known, and therefore
+shapes how the power flow problem is formulated across the whole network.
 
-## Voltage Control Types
+`PowerSystems.jl` supports five `ACBusType`s, [listed here](@ref acbustypes_list). The
+choice of bus type for each bus in a dataset has a direct effect on solver behavior,
+convergence, and the interpretation of results.
+
+## [Voltage Control Types](https://en.wikipedia.org/wiki/Voltage_control_and_reactive_power_management)
+
+Most buses in a network fall into one of two voltage control categories, depending on
+whether the equipment connected can actively regulate its terminal voltage.
 
   - `PQ`:
 
-      + **Known:** Real Power Injection ($P$) and Reactive Power Injection ($Q$). These are typically the loads at that bus or fixed power factor generators.
-      + **Unknown:** Voltage Magnitude ($|V|$) and Voltage Angle ($\delta$).
-      + Represents a bus where the voltage magnitude and angle are free to vary based on the system conditions.
+      + **Known:** Real power injection ($P$) and reactive power injection ($Q$). These
+        are typically fixed loads or generators operating at a fixed power factor.
+      + **Unknown:** Voltage magnitude ($|V|$) and voltage angle ($\delta$), which are
+        determined by the power flow solution.
+      + This is the most common bus type. Because $|V|$ is unconstrained, the voltage at
+        a `PQ` bus reflects the state of the surrounding network rather than any local
+        control action.
 
   - `PV`:
 
-      + **Known:** Real Power Injection ($P$) and Voltage Magnitude ($|V|$).
-      + **Unknown:** Reactive Power Injection ($Q$) and Voltage Angle ($\delta$).
-      + Typically represents a bus with an injector connected, where the injector controls the reactive power output and regulates the bus voltage magnitude to a setpoint.
+      + **Known:** Real power injection ($P$) and voltage magnitude ($|V|$).
+      + **Unknown:** Reactive power injection ($Q$) and voltage angle ($\delta$).
+      + Represents a bus with a generator or other device actively regulating its
+        terminal voltage to a setpoint. The reactive power output floats to whatever
+        value is needed to hold that voltage. This is the typical representation of a
+        synchronous generator with an automatic voltage regulator (AVR).
+
+The distinction matters because placing a generator on a `PV` bus rather than a `PQ` bus
+allows the power flow solver to use the voltage setpoint as a constraint, which is closer
+to how real generators operate and tends to produce more physically meaningful results.
 
 ## Reference and Slack Buses
 
-There is a nuanced distinction between a slack bus and a reference bus. In most small test sytems and academic discussions, the system has a single slack bus which is also the reference bus. However, for large interconnected cases or cases with a very radial structure, having a single bus that takes on all the real power mistmatch in the system can lead to erroneous results. In PowerSystems.jl we distinguish the posibility of having slacks and reference buses. Is up to the modeler to decide how to handle the classifications inside of the applications. In other words, wether a reference bus is also a slack or viceversa is left to the application developer.
+Every power flow problem also requires buses that handle system-wide power balance and
+provide an angular reference. `PowerSystems.jl` distinguishes between these two roles,
+because conflating them — as many textbooks and smaller test systems do — can produce
+misleading results in large or radially structured networks.
 
   - `SLACK`:
 
-      + Known: Voltage Magnitude ($|V|$) and Voltage Angle ($\delta$) **when the slack and the reference are the same bus, otherwise is unknown**.
-      + Unknown: Real Power ($P$) and Reactive Power ($Q$). These values are calculated as residuals after the power flow solution converges to account for system losses and imbalances and are allocated using participation factors in the model formulation.
-      + This kind of bus absorbs or supplies the difference between the total generation and total load plus losses in the system. There can be several slack buses in a system.
-
-  - Ref:
-
-      + Known: Voltage Magnitude ($|V|$) and Voltage Angle ($\delta$). Typically, the angle is set to 0 degrees for simplicity, and the voltage is set to a fixed value per unit.0 degrees for simplicity and the voltage is set to a fixed value per unit.
-      + Unknown: Real Power ($P$) and Reactive Power ($Q$). These values are calculated as residuals after the power flow solution converges to account for system losses and imbalances when there is a single slack bus that matches the reference bus.
-      + Serves as the "reference" for all other bus voltage angles in the AC interconnected system.
-
-For the study of large interconnected areas that include different asynchronous AC networks connected through HVDC, the system can contain multiple reference buses. Since not all modeling efforts require a properly set reference bus, e.g., Zonal Modeling, **PowerSystems.jl does not perform a verification that the system buses are adequately set. This feature is implemented in [`PowerNetworkMatrices.jl`](https://nrel-sienna.github.io/PowerNetworkMatrices.jl/stable/).**
+      + **Known:** Voltage magnitude ($|V|$) and voltage angle ($\delta$) *only when the
+        slack and the reference coincide*; otherwise both are unknown.
+      + **Unknown:** Real power ($P$) and reactive power ($Q$), which are calculated as
+        residuals after the power flow solution converges. Losses and generation-load
+        imbalances are distributed across slack buses using participation factors.
+      + A system can have multiple slack buses. In large interconnected cases, distributing
+        the power mismatch across several buses is more physically realistic than
+        concentrating it at one.
+
+  - `REF`:
+
+      + **Known:** Voltage magnitude ($|V|$) and voltage angle ($\delta$). By convention
+        the angle is set to 0 radians and the voltage to a fixed per-unit value, providing
+        the angular reference against which all other bus angles are measured.
+      + **Unknown:** Real power ($P$) and reactive power ($Q$) when the reference bus is
+        also the sole slack bus.
+      + In systems that span multiple asynchronous AC networks connected through HVDC,
+        each island needs its own reference bus.
+
+`PowerSystems.jl` treats `SLACK` and `REF` as distinct designations, leaving it to the
+application developer to decide whether a reference bus should also absorb power mismatch.
+Because not all modeling workflows require a properly configured reference bus — zonal
+production cost models, for example, do not — **`PowerSystems.jl` does not verify that
+the system buses are adequately set. That validation is implemented in
+[`PowerNetworkMatrices.jl`](https://nrel-sienna.github.io/PowerNetworkMatrices.jl/stable/).**
+
+For worked examples of constructing reference and slack buses and adding them to a system,
+see the [Create and Explore a Power System](@ref tutorial_creating_system) tutorial.
 
 ## Isolated Buses and the `available` field
 
-In certain modeling applications, particularly power flow modeling tools, the designation of
-"isolated" is used to signal that the bus is temporarily disconnected from the network, as are any other components attached to it. However, in `PowerSystems.jl`, a bus and its components can be excluded from an analysis or optimization without changing the underlying network topology by setting the `available` field to false: `set_available!(bus, false)`.
-
-In PowerSystems.jl the `ISOLATED` type means exactly that: The bus is not connected to the network. In
-resource analysis where systems contain isolated subsystems that can be ignored for the purposes of the power flow but are relevant when performing optimization, the `ISOLATED` designation provides the capability to describe those situations in precise terms. `ISOLATED` buses can also be made unavailable to make the components attached to them also unavailable.
+Many power flow tools use an "isolated" designation to signal that a bus is temporarily
+disconnected from the network. `PowerSystems.jl` keeps this concept but separates it from
+the question of whether a component participates in a given analysis.
+
+In `PowerSystems.jl`, `ISOLATED` means precisely that the bus is structurally
+disconnected from the network — it has no active connections. This is distinct from
+*excluding* a bus from a particular analysis, which is handled by setting the `available`
+field to `false` via `set_available!(bus, false)`. Setting `available = false` removes the
+bus and its attached components from consideration without altering the underlying network
+topology, which is important when the same dataset is used across multiple modeling
+contexts.
+
+This design supports resource analysis workflows where isolated subsystems exist in the
+data — perhaps representing planned expansions or decommissioned equipment — and must be
+represented precisely while being excluded from active power flow or optimization runs.
+`ISOLATED` buses can additionally be made unavailable, which propagates the exclusion to
+all components attached to them.