Jb/documentation updates

docs/make.jl

@@ -15,7 +15,9 @@ links = InterLinks(
 # This is a fallback for the docstrings that are referenced within IS docstrings
 fallbacks = ExternalFallbacks(
     "ComponentContainer" => "@extref InfrastructureSystems.ComponentContainer",
-    "InfrastructureSystemsComponent" => "@extref InfrastructureSystems.InfrastructureSystemsComponent"
+    "InfrastructureSystemsComponent" => "@extref InfrastructureSystems.InfrastructureSystemsComponent",
+    "InfrastructureSystemsInternal" => "@extref InfrastructureSystems.InfrastructureSystemsInternal",
+    "PiecewiseLinearData" => "@extref InfrastructureSystems.PiecewiseLinearData",
 )
 
 # This is commented out because the output is not user-friendly. Deliberation on how to best
@@ -40,8 +42,15 @@ 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",
+            "...read component values in different unit systems" => "how_to/convert_unit_systems.md",
+            "...convert transformer impedances between per-unit bases" => "how_to/convert_transformer_impedance.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",
@@ -70,7 +79,6 @@ pages = OrderedDict(
             "explanation/per_unit.md",
             "explanation/power_concepts.md",
             "explanation/conforming_and_non_conforming_loads.md",
-            "explanation/transformer_per_unit_models.md",
             "explanation/time_series.md",
             "explanation/dynamic_data.md",
             "explanation/supplemental_attributes.md",

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,25 +13,47 @@
 
   - *AVR*: Automatic Voltage Regulator
 
+### C
+
+  - *CA*: EIA prime mover code for the steam turbine (combined cycle steam) portion of a combined cycle plant
+
+  - *CAISO*: California Independent System Operator
+
+  - *CC*: EIA prime mover code for combined cycle units
+
+  - *CT*: Combustion Turbine
+
 ### 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
 
+  - *EIA*: U.S. Energy Information Administration
+
+  - *EIM*: Energy Imbalance Market
+
   - *EMF*: Electromotive force
+
   - *ESAC*: IEEE Type AC Excitation System model
+
   - *ESDC*: IEEE Type DC Excitation System model
+
   - *EXAC*: IEEE Type AC Excitation System (modified) model
+
   - *EXPIC*: Proportional/Integral Excitation System from PSS/E
+
   - *EXST*: IEEE Type ST (Static) Excitation System model
+
   - *EX4VSA*: IEEE Excitation System for Voltage Security Assessment with Over-Excitation Limits.
 
 ### F
@@ -53,6 +75,8 @@
     forecast included the next day plus a 24-hour lookahead window, the horizon would be
     `Dates.Hour(48)` or `Dates.Day(2)`. See the article on [`Time Series Data`](@ref ts_data).
 
+  - *HRSG*: Heat Recovery Steam Generator
+
   - *HVDC*: High-voltage DC
 
 ### I
@@ -83,6 +107,8 @@
 
 ### P
 
+  - *PCC*: Point of Common Coupling. The point where a generator or plant connects to the grid.
+
   - *PLL*: Phase-locked loop
 
   - *PSS*: Power System Stabilizer
@@ -101,6 +127,8 @@
 
   - *pu* or *p.u.*: Per-unit
 
+  - *PWM*: Pulse-width modulation. A switching technique used in power converters to synthesize a desired AC output voltage by rapidly toggling switches at a high frequency.
+
 ### R
 
   - *REECB1*: Renewable Energy Electric Controller Type B1
@@ -117,6 +145,8 @@
 
   - *SIL*: Surge impedance loading
 
+  - *ST*: Steam Turbine
+
   - *States*: Correspond to the set of inputs, outputs or variables, that evolve dynamically in
     [`PowerSimulationsDynamics.jl`](https://sienna-platform.github.io/PowerSimulationsDynamics.jl/stable/),
     commonly via a differential-algebraic system of equations. In `PowerSystems.jl`, a component
@@ -133,6 +163,16 @@
 
   - *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).
+
+  - *SVM*: Space vector modulation. A control algorithm for three-phase inverters that represents the desired output voltage as a vector in the complex plane and selects switching states to approximate it, achieving lower harmonic distortion than basic [PWM](@ref D).
+
+### 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 +181,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/public.md

@@ -10,7 +10,7 @@ Pages   = ["PowerSystems.jl",
            "injection.jl",
            "devices.jl",
            "loads.jl",
-           "supplemental_constructors",
+           "supplemental_constructors.jl",
            "generation.jl",
            "reserves.jl",
            "storage.jl",
@@ -20,7 +20,6 @@ Pages   = ["PowerSystems.jl",
            "static_models.jl",
            "subsystems.jl",
            "static_injection_subsystem.jl",
-           "dynamic_models.jl",
            "operational_cost.jl",
            "cost_function_timeseries.jl",
            "definitions.jl"

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/api/type_tree.md

@@ -2,7 +2,7 @@
 
 Here is the complete `PowerSystems.jl` type hierarchy:
 
-```@repl types
+```@example types
 using PowerSystems #hide
 import TypeTree: tt #hide
 docs_dir = joinpath(pkgdir(PowerSystems), "docs", "src", "tutorials", "utils"); #hide

docs/src/explanation/buses_type_explanation.md

@@ -1,26 +1,50 @@
 # [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 [`ACBusTypes`](@ref) 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 [`ACBusTypes`](@ref)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`:
 
@@ -38,8 +62,20 @@ For the study of large interconnected areas that include different asynchronous
 
 ## 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.