Expand per unit explanation and update Branch rating docstrings

docs/src/explanation/per_unit.md

@@ -7,24 +7,42 @@ It is often useful to express power systems data in relative terms using per-uni
  2. `"SYSTEM_BASE"`: Parameter values are divided by the system `base_power`.
  3. `"DEVICE_BASE"`: Parameter values are divided by the device `base_mva`.
 
-To see the unit system setting of a `System`:
+`PowerSystems.jl` supports these unit systems because different power system tools and data
+sets use different units systems by convention, such as:
 
-```@repl per-unit
-using PowerSystems; #hide
-file_dir = joinpath(pkgdir(PowerSystems), "docs", "src", "tutorials", "tutorials_data") #hide
-system = System(joinpath(file_dir, "RTS_GMLC.m")); #hide
-get_units_base(system)
-```
+  - Dynamics data is often defined in device base
+  - Network data (e.g., reactance, resistance) is often defined in system base
+  - Production cost modeling data is often gathered from variety of data sources,
+    which are typically defined in natural units
 
-To change the unit system setting of a `System`:
+These three unit bases allow easy conversion between unit systems.
+This allows `PowerSystems.jl` users to input data in the formats they have available,
+as well as view data in the unit system that is most intuitive to them.
 
-```@repl per-unit
-set_units_base_system!(system, "DEVICE_BASE")
-```
+You can get and set the unit system setting of a `System` with [`get_units_base`](@ref)
+and [`set_units_base_system!`](@ref).
 
-The units of the parameter values stored in each struct are defined in
-`src/descriptors/power_system_structs.json`. Conversion between unit systems does not change
+Conversion between unit systems does not change
 the stored parameter values. Instead, unit system conversions are made when accessing
 parameters using the [accessor functions](@ref dot_access), thus making it
 imperative to utilize the accessor functions instead of the "dot" accessor methods to
-ensure the return of the correct values.
+ensure the return of the correct values. The units of the parameter values stored in each
+struct are defined in `src/descriptors/power_system_structs.json`.
+
+There are some unit system conventions in `PowerSystems.jl` when defining new components.
+Currently, when you define components that aren't attached to a `System`,
+you must define all fields in `"DEVICE_BASE"`, except for certain components that don't
+have their own `base_power` rating, such as [`Line`](@ref)s, where the `rating` must be
+defined in `"SYSTEM_BASE"`.
+
+In the future, `PowerSystems.jl` hopes to support defining components in natural units.
+For now, if you want to define data in natural units, you must first
+set the system units to `"NATURAL_UNITS"`, define an empty component, and then use the
+[accessor functions](@ref dot_access) (e.g., getters and setters), to define each field
+within the component. The accessor functions will then do the data conversion from your
+input data in natural units (e.g., MW or MVA) to per-unit.
+
+By default, `PowerSystems.jl` uses `"SYSTEM_BASE"` because many optimization problems won't
+converge when using natural units. If you change the unit setting, it's suggested that you
+switch back to `"SYSTEM_BASE"` before solving an optimization problem (for example in
+[`PowerSimulations.jl`](https://nrel-sienna.github.io/PowerSimulations.jl/stable/)).

src/descriptors/power_system_structs.json

@@ -465,7 +465,7 @@
                 {
                     "null_value": "0.0",
                     "name": "rating",
-                    "comment": "Thermal rating (MVA). Flow on the line must be between -`rating` and `rating`. When defining a line before it is attached to a `System`, `rating` must be in per-unit divided by the base power of the `System` it will be attached to",
+                    "comment": "Thermal rating (MVA). Flow on the line must be between -`rating` and `rating`. When defining a line before it is attached to a `System`, `rating` must be in pu ([`SYSTEM_BASE`](@ref per_unit)) using the base power of the `System` it will be attached to",
                     "data_type": "Float64",
                     "needs_conversion": true
                 },
@@ -585,7 +585,7 @@
                     "null_value": "0.0",
                     "name": "rating",
                     "data_type": "Float64",
-                    "comment": "Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a line before it is attached to a `System`, `rating` must be in per-unit divided by the base power of the `System` it will be attached to",
+                    "comment": "Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a line before it is attached to a `System`, `rating` must be in pu ([`SYSTEM_BASE`](@ref per_unit)) using the base power of the `System` it will be attached to",
                     "needs_conversion": true
                 },
                 {
@@ -717,7 +717,7 @@
                 },
                 {
                     "name": "rating",
-                    "comment": "Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a transformer before it is attached to a `System`, `rating` must be in per-unit divided by the base power of the `System` it will be attached to",
+                    "comment": "Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a transformer before it is attached to a `System`, `rating` must be in pu ([`SYSTEM_BASE`](@ref per_unit)) using the base power of the `System` it will be attached to",
                     "null_value": "0.0",
                     "data_type": "Union{Nothing, Float64}",
                     "valid_range": {
@@ -846,7 +846,7 @@
                 },
                 {
                     "name": "rating",
-                    "comment": "Thermal rating (MVA). Flow through the transformer must be between -`rating`. When defining a transformer before it is attached to a `System`, `rating` must be in per-unit divided by the base power of the `System` it will be attached to",
+                    "comment": "Thermal rating (MVA). Flow through the transformer must be between -`rating`. When defining a transformer before it is attached to a `System`, `rating` must be in pu ([`SYSTEM_BASE`](@ref per_unit)) using the base power of the `System` it will be attached to",
                     "null_value": "0.0",
                     "data_type": "Union{Nothing, Float64}",
                     "valid_range": {
@@ -952,7 +952,7 @@
                 },
                 {
                     "name": "rating",
-                    "comment": "Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a transformer before it is attached to a `System`, `rating` must be in per-unit divided by the base power of the `System` it will be attached to",
+                    "comment": "Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a transformer before it is attached to a `System`, `rating` must be in pu ([`SYSTEM_BASE`](@ref per_unit)) using the base power of the `System` it will be attached to",
                     "null_value": "nothing",
                     "data_type": "Union{Nothing, Float64}",
                     "valid_range": {

src/models/generated/Line.jl

@@ -32,7 +32,7 @@ An AC transmission line
 - `r::Float64`: Resistance in pu ([`SYSTEM_BASE`](@ref per_unit)), validation range: `(0, 4)`
 - `x::Float64`: Reactance in pu ([`SYSTEM_BASE`](@ref per_unit)), validation range: `(0, 4)`
 - `b::FromTo`: Shunt susceptance in pu ([`SYSTEM_BASE`](@ref per_unit)), specified both on the `from` and `to` ends of the line. These are commonly modeled with the same value, validation range: `(0, 100)`
-- `rating::Float64`: Thermal rating (MVA). Flow on the line must be between -`rating` and `rating`. When defining a line before it is attached to a `System`, `rating` must be in per-unit divided by the base power of the `System` it will be attached to
+- `rating::Float64`: Thermal rating (MVA). Flow on the line must be between -`rating` and `rating`. When defining a line before it is attached to a `System`, `rating` must be in pu ([`SYSTEM_BASE`](@ref per_unit)) using the base power of the `System` it will be attached to
 - `angle_limits::MinMax`: Minimum and maximum angle limits (radians), validation range: `(-1.571, 1.571)`
 - `services::Vector{Service}`: (default: `Device[]`) Services that this device contributes to
 - `ext::Dict{String, Any}`: (default: `Dict{String, Any}()`) An [*ext*ra dictionary](@ref additional_fields) for users to add metadata that are not used in simulation, such as latitude and longitude.
@@ -55,7 +55,7 @@ mutable struct Line <: ACBranch
     x::Float64
     "Shunt susceptance in pu ([`SYSTEM_BASE`](@ref per_unit)), specified both on the `from` and `to` ends of the line. These are commonly modeled with the same value"
     b::FromTo
-    "Thermal rating (MVA). Flow on the line must be between -`rating` and `rating`. When defining a line before it is attached to a `System`, `rating` must be in per-unit divided by the base power of the `System` it will be attached to"
+    "Thermal rating (MVA). Flow on the line must be between -`rating` and `rating`. When defining a line before it is attached to a `System`, `rating` must be in pu ([`SYSTEM_BASE`](@ref per_unit)) using the base power of the `System` it will be attached to"
     rating::Float64
     "Minimum and maximum angle limits (radians)"
     angle_limits::MinMax

src/models/generated/MonitoredLine.jl

@@ -36,7 +36,7 @@ For example, monitored lines can be used to restrict line flow following a conti
 - `x::Float64`: Reactance in pu ([`SYSTEM_BASE`](@ref per_unit)), validation range: `(0, 4)`
 - `b::FromTo`: Shunt susceptance in pu ([`SYSTEM_BASE`](@ref per_unit)), specified both on the `from` and `to` ends of the line. These are commonly modeled with the same value, validation range: `(0, 2)`
 - `flow_limits::FromTo_ToFrom`: Minimum and maximum permissable flow on the line (MVA), if different from the thermal rating defined in `rating`
-- `rating::Float64`: Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a line before it is attached to a `System`, `rating` must be in per-unit divided by the base power of the `System` it will be attached to
+- `rating::Float64`: Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a line before it is attached to a `System`, `rating` must be in pu ([`SYSTEM_BASE`](@ref per_unit)) using the base power of the `System` it will be attached to
 - `angle_limits::MinMax`: Minimum and maximum angle limits (radians), validation range: `(-1.571, 1.571)`
 - `services::Vector{Service}`: (default: `Device[]`) Services that this device contributes to
 - `ext::Dict{String, Any}`: (default: `Dict{String, Any}()`) An [*ext*ra dictionary](@ref additional_fields) for users to add metadata that are not used in simulation, such as latitude and longitude.
@@ -61,7 +61,7 @@ mutable struct MonitoredLine <: ACBranch
     b::FromTo
     "Minimum and maximum permissable flow on the line (MVA), if different from the thermal rating defined in `rating`"
     flow_limits::FromTo_ToFrom
-    "Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a line before it is attached to a `System`, `rating` must be in per-unit divided by the base power of the `System` it will be attached to"
+    "Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a line before it is attached to a `System`, `rating` must be in pu ([`SYSTEM_BASE`](@ref per_unit)) using the base power of the `System` it will be attached to"
     rating::Float64
     "Minimum and maximum angle limits (radians)"
     angle_limits::MinMax

src/models/generated/PhaseShiftingTransformer.jl

@@ -38,7 +38,7 @@ The model uses an equivalent circuit assuming the impedance is on the High Volta
 - `primary_shunt::Float64`:, validation range: `(0, 2)`
 - `tap::Float64`: Normalized tap changer position for voltage control, varying between 0 and 2, with 1 centered at the nominal voltage, validation range: `(0, 2)`
 - `α::Float64`: Initial condition of phase shift (radians) between the `from` and `to` buses , validation range: `(-1.571, 1.571)`
-- `rating::Union{Nothing, Float64}`: Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a transformer before it is attached to a `System`, `rating` must be in per-unit divided by the base power of the `System` it will be attached to, validation range: `(0, nothing)`
+- `rating::Union{Nothing, Float64}`: Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a transformer before it is attached to a `System`, `rating` must be in pu ([`SYSTEM_BASE`](@ref per_unit)) using the base power of the `System` it will be attached to, validation range: `(0, nothing)`
 - `phase_angle_limits::MinMax`: (default: `(min=-1.571, max=1.571)`) Minimum and maximum phase angle limits (radians), validation range: `(-1.571, 1.571)`
 - `services::Vector{Service}`: (default: `Device[]`) Services that this device contributes to
 - `ext::Dict{String, Any}`: (default: `Dict{String, Any}()`) An [*ext*ra dictionary](@ref additional_fields) for users to add metadata that are not used in simulation, such as latitude and longitude.
@@ -64,7 +64,7 @@ mutable struct PhaseShiftingTransformer <: ACBranch
     tap::Float64
     "Initial condition of phase shift (radians) between the `from` and `to` buses "
     α::Float64
-    "Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a transformer before it is attached to a `System`, `rating` must be in per-unit divided by the base power of the `System` it will be attached to"
+    "Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a transformer before it is attached to a `System`, `rating` must be in pu ([`SYSTEM_BASE`](@ref per_unit)) using the base power of the `System` it will be attached to"
     rating::Union{Nothing, Float64}
     "Minimum and maximum phase angle limits (radians)"
     phase_angle_limits::MinMax

src/models/generated/TapTransformer.jl

@@ -35,7 +35,7 @@ The model uses an equivalent circuit assuming the impedance is on the High Volta
 - `x::Float64`: Reactance in p.u. ([`SYSTEM_BASE`](@ref per_unit)), validation range: `(-2, 4)`
 - `primary_shunt::Float64`: Shunt reactance in p.u. ([`SYSTEM_BASE`](@ref per_unit)), validation range: `(0, 2)`
 - `tap::Float64`: Normalized tap changer position for voltage control, varying between 0 and 2, with 1 centered at the nominal voltage, validation range: `(0, 2)`
-- `rating::Union{Nothing, Float64}`: Thermal rating (MVA). Flow through the transformer must be between -`rating`. When defining a transformer before it is attached to a `System`, `rating` must be in per-unit divided by the base power of the `System` it will be attached to, validation range: `(0, nothing)`
+- `rating::Union{Nothing, Float64}`: Thermal rating (MVA). Flow through the transformer must be between -`rating`. When defining a transformer before it is attached to a `System`, `rating` must be in pu ([`SYSTEM_BASE`](@ref per_unit)) using the base power of the `System` it will be attached to, validation range: `(0, nothing)`
 - `services::Vector{Service}`: (default: `Device[]`) Services that this device contributes to
 - `ext::Dict{String, Any}`: (default: `Dict{String, Any}()`) An [*ext*ra dictionary](@ref additional_fields) for users to add metadata that are not used in simulation, such as latitude and longitude.
 - `internal::InfrastructureSystemsInternal`: (**Do not modify.**) PowerSystems.jl internal reference
@@ -59,7 +59,7 @@ mutable struct TapTransformer <: ACBranch
     primary_shunt::Float64
     "Normalized tap changer position for voltage control, varying between 0 and 2, with 1 centered at the nominal voltage"
     tap::Float64
-    "Thermal rating (MVA). Flow through the transformer must be between -`rating`. When defining a transformer before it is attached to a `System`, `rating` must be in per-unit divided by the base power of the `System` it will be attached to"
+    "Thermal rating (MVA). Flow through the transformer must be between -`rating`. When defining a transformer before it is attached to a `System`, `rating` must be in pu ([`SYSTEM_BASE`](@ref per_unit)) using the base power of the `System` it will be attached to"
     rating::Union{Nothing, Float64}
     "Services that this device contributes to"
     services::Vector{Service}

src/models/generated/Transformer2W.jl

@@ -33,7 +33,7 @@ The model uses an equivalent circuit assuming the impedance is on the High Volta
 - `r::Float64`: Resistance in pu ([`SYSTEM_BASE`](@ref per_unit)), validation range: `(-2, 4)`
 - `x::Float64`: Reactance in pu ([`SYSTEM_BASE`](@ref per_unit)), validation range: `(-2, 4)`
 - `primary_shunt::Float64`: Shunt reactance in pu ([`SYSTEM_BASE`](@ref per_unit)), validation range: `(0, 2)`
-- `rating::Union{Nothing, Float64}`: Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a transformer before it is attached to a `System`, `rating` must be in per-unit divided by the base power of the `System` it will be attached to, validation range: `(0, nothing)`
+- `rating::Union{Nothing, Float64}`: Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a transformer before it is attached to a `System`, `rating` must be in pu ([`SYSTEM_BASE`](@ref per_unit)) using the base power of the `System` it will be attached to, validation range: `(0, nothing)`
 - `services::Vector{Service}`: (default: `Device[]`) Services that this device contributes to
 - `ext::Dict{String, Any}`: (default: `Dict{String, Any}()`) An [*ext*ra dictionary](@ref additional_fields) for users to add metadata that are not used in simulation, such as latitude and longitude.
 - `internal::InfrastructureSystemsInternal`: (**Do not modify.**) PowerSystems.jl internal reference
@@ -55,7 +55,7 @@ mutable struct Transformer2W <: ACBranch
     x::Float64
     "Shunt reactance in pu ([`SYSTEM_BASE`](@ref per_unit))"
     primary_shunt::Float64
-    "Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a transformer before it is attached to a `System`, `rating` must be in per-unit divided by the base power of the `System` it will be attached to"
+    "Thermal rating (MVA). Flow through the transformer must be between -`rating` and `rating`. When defining a transformer before it is attached to a `System`, `rating` must be in pu ([`SYSTEM_BASE`](@ref per_unit)) using the base power of the `System` it will be attached to"
     rating::Union{Nothing, Float64}
     "Services that this device contributes to"
     services::Vector{Service}