Ac/documentation branch

Project.toml

@@ -1,7 +1,7 @@
 name = "PowerSystems"
 uuid = "bcd98974-b02a-5e2f-9ee0-a103f5c450dd"
 authors = ["Jose Daniel Lara", "Daniel Thom", "Clayton Barrows", "Sourabh Dalvi", "Dheepak Krishnamurthy"]
-version = "4.4.0"
+version = "4.3.1"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
@@ -27,15 +27,15 @@ DataFrames = "1"
 DataStructures = "~0.18"
 Dates = "1"
 DocStringExtensions = "0.8, 0.9.2"
-InfrastructureSystems = "^2.3"
+InfrastructureSystems = "^2.2"
 InteractiveUtils = "1"
 JSON3 = "1"
 LinearAlgebra = "1"
 Logging = "1"
 PowerFlowData = "^1.5"
 PrettyTables = "1, 2"
 TimeSeries = "0.24"
-YAML = "~0.4"
 UUIDs = "1"
 Unicode = "1"
+YAML = "~0.4"
 julia = "^1.6"

README.md

@@ -28,7 +28,7 @@ The `PowerSystems.jl` package provides a rigorous data model using Julia structu
 - Dynamic Generators Models
 - Dynamic Inverter Models
 
-For information on using the package and a more extensive list of device data enabled, see the [stable documentation](https://nrel-sienna.github.io/PowerSystems.jl/stable/). Use the [in-development documentation](https://nrel-sienna.github.io/PowerSystems.jl/dev/) for the version of the documentation which contains the unreleased features.
+For a more exhaustive list, check the [Documentation](https://nrel-sienna.github.io/PowerSystems.jl/stable).
 
 ## Parsing capabilities in PowerSystems
 

docs/Project.toml

@@ -10,6 +10,7 @@ JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 PowerSystemCaseBuilder = "f00506e0-b84f-492a-93c2-c0a9afc4364e"
 PowerSystems = "bcd98974-b02a-5e2f-9ee0-a103f5c450dd"
+StyledStrings = "f489334b-da3d-4c2e-b8f0-e476e12c162b"
 TimeSeries = "9e3dc215-6440-5c97-bce1-76c03772f85e"
 TypeTree = "04da0e3b-1cad-4b2c-a963-fc1602baf1af"
 

docs/make.jl

@@ -13,7 +13,9 @@ pages = OrderedDict(
             "Create and Explore a Power `System`" => "tutorials/creating_system.md",
             "Working with Time Series" => "tutorials/working_with_time_series.md",
             "Adding Data for Dynamic Simulations" => "tutorials/add_dynamic_data.md",
+            "Manipulating Data Sets" => "tutorials/manipulating_datasets.md"
         ],
+
         "How to..." =>  Any[
             "...install PowerSystems.jl" => "how_to/install.md",
             "...load a `system` from `PowerSystemCaseBuilder`" => "how_to/powersystembuilder.md",
@@ -45,7 +47,7 @@ pages = OrderedDict(
         "Reference" =>
             Any["Public API" => "api/public.md",
             "Glossary and Acronyms" => "api/glossary.md",
-            "Type Tree" => "api/type_tree.md",
+            "Type Hierarchy" => "api/type_tree.md",
             "`ValueCurve` Options" => "api/valuecurve_options.md",
             "Specifying the category of..." => "api/enumerated_types.md",
             "Citation" => "api/citation.md",
@@ -89,6 +91,7 @@ pages["Model Library"] = make_model_library(
         )
 )
 
+
 # postprocess function to insert md
 function insert_md(content)
     m = match(r"APPEND_MARKDOWN\(\"(.*)\"\)", content)
@@ -106,7 +109,8 @@ folders = Dict(
     "Model Library" => filter(julia_file_filter, readdir("docs/src/model_library")),
     "Explanation" => filter(julia_file_filter, readdir("docs/src/explanation")),
     "How to..." => filter(julia_file_filter, readdir("docs/src/how_to")),
-)
+    "Tutorials" => filter(julia_file_filter, readdir("docs/src/tutorials"))
+) 
 for (section, folder) in folders
     for file in folder
         @show file

docs/src/api/type_tree.md

@@ -1,4 +1,4 @@
-# Type Tree
+# Type Hierarchy
 
 Here is the complete `PowerSystems.jl` type hierarchy:
 

docs/src/how_to/market_bid_cost.md

@@ -4,61 +4,9 @@ A [`MarketBidCost`](@ref) is an `OperationalCost` data structure that allows the
 cost model that is very similar to most US electricity market auctions with bids for energy
 and ancillary services jointly. This page showcases how to create data for this cost function.
 
-## Adding a Single Incremental Energy bids to MarketBidCost
+## Adding Energy bids to MarketBidCost
 
-### Construct directly the MarketBidCost using the `make_market_bid_curve` method.
-
-The `make_market_bid_curve` creates an incremental or decremental offer curve from a vector of `n` power values, a vector of `n-1` marginal costs and single initial input. For example, the following code creates an incremental offer curve:
-
-```@repl market_bid_cost
-using PowerSystems, Dates
-proposed_offer_curve =
-    make_market_bid_curve([0.0, 100.0, 105.0, 120.0, 130.0], [25.0, 26.0, 28.0, 30.0], 10.0)
-```
-
-Then a device with MarketBidCost can be directly instantiated using:
-
-```@repl market_bid_cost
-using PowerSystems, Dates
-bus = ACBus(1, "nodeE", "REF", 0, 1.0, (min = 0.9, max = 1.05), 230, nothing, nothing)
-
-generator = ThermalStandard(;
-    name = "Brighton",
-    available = true,
-    status = true,
-    bus = bus,
-    active_power = 6.0,
-    reactive_power = 1.50,
-    rating = 0.75,
-    prime_mover_type = PrimeMovers.ST,
-    fuel = ThermalFuels.COAL,
-    active_power_limits = (min = 0.0, max = 6.0),
-    reactive_power_limits = (min = -4.50, max = 4.50),
-    time_limits = (up = 0.015, down = 0.015),
-    ramp_limits = (up = 5.0, down = 3.0),
-    operation_cost = MarketBidCost(;
-        no_load_cost = 0.0,
-        start_up = (hot = 0.0, warm = 0.0, cold = 0.0),
-        shut_down = 0.0,
-        incremental_offer_curves = proposed_offer_curve,
-    ),
-    base_power = 100.0,
-)
-```
-
-Similarly, a decremental offer curve can also be created directly using the same helper method:
-
-```@repl market_bid_cost
-using PowerSystems, Dates
-decremental_offer =
-    make_market_bid_curve([0.0, 100.0, 105.0, 120.0, 130.0], [30.0, 28.0, 26.0, 25.0], 50.0)
-```
-
-and can be added to a `MarketBidCost` using the field `decremental_offer_curves`.
-
-## Adding Time Series Energy bids to MarketBidCost
-
-### Step 1: Constructing device with MarketBidCost
+### Step 1: Constructiong device with MarketBidCost
 
 When using [`MarketBidCost`](@ref), the user can add the cost struct to the device specifying
 only certain elements, at this point the actual energy cost bids don't need to be populated/passed.
@@ -95,22 +43,19 @@ generator = ThermalStandard(;
 ### Step 2: Creating the `TimeSeriesData` for the Market Bid
 
 The user is expected to pass the `TimeSeriesData` that holds the energy bid data which can be
-of any type (i.e. `SingleTimeSeries` or `Deterministic`) and data must be `PiecewiseStepData`.
-This data type is created by specifying a vector of `n` powers, and `n-1` marginal costs.
-The data must be specified in natural units, that is power in MW and marginal cost in $/MWh
-or it will not be accepted when adding to the system.
-Code below shows an example of how to build a Deterministic TimeSeries.
+of any type (i.e. `SingleTimeSeries` or `Deterministic`) and data can be `Array{Float64}`,
+`Array{Tuple{Float64, Float64}}` or `Array{Array{Tuple{Float64,Float64}}`. If the data is
+just floats then the cost in the optimization is seen as a constant variable cost, but if
+data is a Tuple or `Array{Tuple}` then the model expects the tuples to be cost & power-point
+pairs (cost in $/p.u-hr & power-point in p.u-hr), which is modeled same as TwoPartCost or
+ThreePartCost. Code below shows an example of how to build a TimeSeriesData.
 
 ```@repl market_bid_cost
-initial_time = Dates.DateTime("2020-01-01")
-psd1 = PiecewiseStepData([5.0, 7.33, 9.67, 12.0], [2.901, 5.8272, 8.941])
-psd2 = PiecewiseStepData([5.0, 7.33, 9.67, 12.0], [3.001, 6.0072, 9.001])
 data =
     Dict(
-        initial_time => [
-            psd1,
-            psd2,
-        ],
+        Dates.DateTime("2020-01-01") => [
+            [(0.0, 0.05), (290.1, 0.0733), (582.72, 0.0967), (894.1, 0.120)],
+            [(0.0, 0.05), (300.1, 0.0733), (600.72, 0.0967), (900.1, 0.120)]],
     )
 time_series_data = Deterministic(;
     name = "variable_cost",
@@ -119,6 +64,20 @@ time_series_data = Deterministic(;
 )
 ```
 
+**NOTE:** Due to [limitations in DataStructures.jl](https://github.com/JuliaCollections/DataStructures.jl/issues/239),
+in `PowerSystems.jl` when creating Forecasts or TimeSeries for your MarketBidCost, you need
+to define your data as in the example or with a very explicit container. Otherwise, it won't
+discern the types properly in the constructor and will return `SortedDict{Any,Any,Base.Order.ForwardOrdering}` which causes the constructor in `PowerSystems.jl` to fail. For instance, you need to define
+the `Dict` with the data as follows:
+
+```julia
+# Very verbose dict definition
+data = Dict{DateTime, Array{Array{Tuple{Float64, Float64}, 1}, 1}}()
+for t in range(initial_time_sys; step = Hour(1), length = window_count)
+    data[t] = MY_BID_DATA
+end
+```
+
 ### Step 3a: Adding Energy Bid TimeSeriesData to the device
 
 To add energy market bids time-series to the `MarketBidCost`, use `set_variable_cost!`. The
@@ -127,20 +86,12 @@ arguments for `set_variable_cost!` are:
   - `sys::System`: PowerSystem System
   - `component::StaticInjection`: Static injection device
   - `time_series_data::TimeSeriesData`: TimeSeriesData
-  - `power_units::UnitSystem`: UnitSystem
-
-Currently, time series data only supports natural units for time series data, i.e. MW for power and $/MWh for marginal costs.
 
 ```@repl market_bid_cost
 sys = System(100.0, [bus], [generator])
-set_variable_cost!(sys, generator, time_series_data, UnitSystem.NATURAL_UNITS)
+set_variable_cost!(sys, generator, time_series_data)
 ```
 
-**Note:** `set_variable_cost!` add curves to the `incremental_offer_curves` in the MarketBidCost.
-Similarly, `set_incremental_variable_cost!` can be used to add curves to the `incremental_offer_curves`.
-On the other hand, `set_decremental_variable_cost!` must be used to decremental curves (usually for storage or demand).
-The creation of the TimeSeriesData is similar to Step 2, using `PiecewiseStepData`
-
 ### Step 3b: Adding Service Bid TimeSeriesData to the device
 
 Similar to adding energy market bids, for adding bids for ancillary services, use
@@ -149,14 +100,12 @@ Similar to adding energy market bids, for adding bids for ancillary services, us
 ```@repl market_bid_cost
 service = VariableReserve{ReserveUp}("example_reserve", true, 0.6, 2.0)
 add_service!(sys, service, get_component(ThermalStandard, sys, "Brighton"))
-
-psd3 = PiecewiseStepData([0.0, 10.0], [650.3])
-psd4 = PiecewiseStepData([0.0, 10.0], [750.0])
-data = Dict(Dates.DateTime("2020-01-01") => [psd3, psd4])
+data =
+    Dict(Dates.DateTime("2020-01-01") => [650.3, 750.0])
 time_series_data = Deterministic(;
     name = get_name(service),
     data = data,
     resolution = Dates.Hour(1),
 )
-set_service_bid!(sys, generator, service, time_series_data, UnitSystem.NATURAL_UNITS)
+set_service_bid!(sys, generator, service, time_series_data)
 ```