From ee56ad5d92303b1fdd7f3e1f5352e00e5b4c004e Mon Sep 17 00:00:00 2001 From: kdayday Date: Mon, 2 Sep 2024 21:00:31 -0600 Subject: [PATCH] Expand per unit explanation and update Branch rating docstrings --- docs/src/explanation/per_unit.md | 46 +++++++++++++------ src/descriptors/power_system_structs.json | 10 ++-- src/models/generated/Line.jl | 4 +- src/models/generated/MonitoredLine.jl | 4 +- .../generated/PhaseShiftingTransformer.jl | 4 +- src/models/generated/TapTransformer.jl | 4 +- src/models/generated/Transformer2W.jl | 4 +- 7 files changed, 47 insertions(+), 29 deletions(-) diff --git a/docs/src/explanation/per_unit.md b/docs/src/explanation/per_unit.md index fcbb434efe..db68630dec 100644 --- a/docs/src/explanation/per_unit.md +++ b/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/)). diff --git a/src/descriptors/power_system_structs.json b/src/descriptors/power_system_structs.json index ec2e777dad..1983d7375b 100644 --- a/src/descriptors/power_system_structs.json +++ b/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": { diff --git a/src/models/generated/Line.jl b/src/models/generated/Line.jl index 2a638e096d..86c3b5c663 100644 --- a/src/models/generated/Line.jl +++ b/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 diff --git a/src/models/generated/MonitoredLine.jl b/src/models/generated/MonitoredLine.jl index 3ba2d6e195..44dabafffd 100644 --- a/src/models/generated/MonitoredLine.jl +++ b/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 diff --git a/src/models/generated/PhaseShiftingTransformer.jl b/src/models/generated/PhaseShiftingTransformer.jl index 380827ae14..2147b9598c 100644 --- a/src/models/generated/PhaseShiftingTransformer.jl +++ b/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 diff --git a/src/models/generated/TapTransformer.jl b/src/models/generated/TapTransformer.jl index cfa9303488..9fcb566226 100644 --- a/src/models/generated/TapTransformer.jl +++ b/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} diff --git a/src/models/generated/Transformer2W.jl b/src/models/generated/Transformer2W.jl index 2147edea36..20c87dbffd 100644 --- a/src/models/generated/Transformer2W.jl +++ b/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}