diff --git a/docs/make.jl b/docs/make.jl index 5befc20519..2004144c69 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -18,6 +18,7 @@ pages = OrderedDict( "...install PowerSystems.jl" => "how_to/install.md", "...load a `system` from `PowerSystemCaseBuilder`" => "how_to/powersystembuilder.md", "...parse data from Matpower, PSSE, or CSV files" => "how_to/parsing.md", + "...add a component using natural units (MW)" => "how_to/add_component_natural_units.md", "...add time series data from CSVs" => "how_to/add_ts_from_csvs.md", "...customize the tabular data parser" => "how_to/extend_tabular_parsing.md", "...get all the buses in a system" => "how_to/get_buses.md", diff --git a/docs/src/how_to/add_component_natural_units.md b/docs/src/how_to/add_component_natural_units.md new file mode 100644 index 0000000000..3b29d4e3d6 --- /dev/null +++ b/docs/src/how_to/add_component_natural_units.md @@ -0,0 +1,90 @@ +# Add a Component in Natural Units + +```@setup add_in_nu +using PowerSystems; #hide +using PowerSystemCaseBuilder #hide +system = build_system(PSISystems, "modified_RTS_GMLC_DA_sys"); #hide +``` + +`PowerSystems.jl` has [three per-unitization options](@ref per_unit) for getting, setting +and displaying data. + +Currently, only one of these options -- `"DEVICE_BASE"` -- is supported when using a +constructor function define a component. You can see +[an example of the default capabilities using `"DEVICE_BASE"` here](@ref "Adding Loads and Generators"). + +We hope to add capability to define components in +`"NATURAL_UNITS"` with constructors in the future, but for now, below is a workaround +for users who prefer to define data using `"NATURAL_UNITS"` (e.g., MW, MVA, MVAR, or MW/min): + +### Step 1: Set Units Base + +Set your (previously-defined) `System`'s units base to `"NATURAL_UNITS"`: + +```@repl add_in_nu +set_units_base_system!(system, "NATURAL_UNITS") +``` + +Now, the "setter" functions have been switched to define data using natural units (MW, MVA, +etc.), taking care of the necessary data conversions behind the scenes. + +### Step 2: Define Empty Component + +Define an empty component with `0.0` or `nothing` for all the power-related fields except +`base_power`, which is always in MVA. + +For example: + +```@repl add_in_nu +gas1 = ThermalStandard(; + name = "gas1", + available = true, + status = true, + bus = get_component(ACBus, system, "Cobb"), # Attach to a previously-defined bus named Cobb + active_power = 0.0, + reactive_power = 0.0, + rating = 0.0, + active_power_limits = (min = 0.0, max = 0.0), + reactive_power_limits = nothing, + ramp_limits = nothing, + operation_cost = ThermalGenerationCost(nothing), + base_power = 30.0, # MVA + time_limits = (up = 8.0, down = 8.0), # Hours, unaffected by per-unitization + must_run = false, + prime_mover_type = PrimeMovers.CC, + fuel = ThermalFuels.NATURAL_GAS, +); +``` + +### Step 3: Attach the Component + +Attach the component to your `System`: + +```@repl add_in_nu +add_component!(system, gas1) +``` + +### Step 4: Add Data with "setter" Functions + +Use individual "setter" functions to set each the value of each numeric field in natural +units: + +```@repl add_in_nu +set_rating!(gas1, 30.0) #MVA +set_active_power_limits!(gas1, (min = 6.0, max = 30.0)) # MW +set_reactive_power_limits!(gas1, (min = 6.0, max = 30.0)) # MVAR +set_ramp_limits!(gas1, (up = 6.0, down = 6.0)) #MW/min +``` +Notice the return values are divided by the `base_power` of 30 MW, showing the setters have +done the per-unit conversion into `"DEVICE_BASE"` behind the scenes. + +!!! tip + + Steps 2-4 can be called within a `for` loop to define many components at once (or step 3 + can be replaced with [`add_components!`](@ref) to add all components at once). + +#### See Also + + - [Read more to understand per-unitization in PowerSystems.jl](@ref per_unit) + - Learn how to use the default constructors and explore the per-unitization settings in + [Create and Explore a Power `System`](@ref) diff --git a/docs/src/tutorials/creating_system.md b/docs/src/tutorials/creating_system.md index 26b9a4de2a..3e5b12d233 100644 --- a/docs/src/tutorials/creating_system.md +++ b/docs/src/tutorials/creating_system.md @@ -378,3 +378,4 @@ Next, you might want to: - [Import a `System` from an existing Matpower or PSSE file instead of creating it manually](@ref parsing) - [Create your own `System` from .csv files instead of creating it manually](@ref table_data) - [Read more to understand per-unitization in PowerSystems.jl](@ref per_unit) + - See a workaround for how to [Add a Component in Natural Units](@ref)