Merge branch 'psy4' into docs

README.md

@@ -5,7 +5,7 @@
 [![Documentation Build](https://github.com/NREL-Sienna/PowerSystems.jl/workflows/Documentation/badge.svg?)](https://nrel-sienna.github.io/PowerSystems.jl/stable)
 [![DOI](https://zenodo.org/badge/114039584.svg)](https://zenodo.org/badge/latestdoi/114039584)
 [<img src="https://img.shields.io/badge/slack-@Sienna/PSY-sienna.svg?logo=slack">](https://join.slack.com/t/nrel-sienna/shared_invite/zt-glam9vdu-o8A9TwZTZqqNTKHa7q3BpQ)
-[![PowerSystems.jl Downloads](https://shields.io/endpoint?url=https://pkgs.genieframework.com/api/v1/badge/PowerSystems)](https://pkgs.genieframework.com?packages=PowerSystems)
+[![PowerSystems.jl Downloads](https://img.shields.io/badge/dynamic/json?url=http%3A%2F%2Fjuliapkgstats.com%2Fapi%2Fv1%2Fmonthly_downloads%2FPowerSystems&query=total_requests&suffix=%2Fmonth&label=Downloads)](http://juliapkgstats.com/pkg/PowerSystems)
 
 The `PowerSystems.jl` package provides a rigorous data model using Julia structures to enable power systems analysis and modeling. In addition to stand-alone system analysis tools and data model building, the `PowerSystems.jl` package is used as the foundational data container for the [PowerSimulations.jl](https://github.com/NREL/PowerSimulations.jl) and [PowerSimulationsDynamics.jl](https://github.com/NREL-Sienna/PowerSimulationsDynamics.jl) packages. `PowerSystems.jl` supports a limited number of data file formats for parsing.
 

docs/src/model_developer_guide/adding_custom_types.md

@@ -12,9 +12,11 @@ Refer to the
 [managing components guide](https://nrel-sienna.github.io/InfrastructureSystems.jl/stable/dev_guide/components_and_container/)
 for component requirements.
 
-**Note**: `get_internal`, `get_name`, and `get_time_series_container` are
-imported into `PowerSystems`, so you should implement your methods as
-`PowerSystems` methods.
+In particular, please note the methods `supports_time_series` (default = false) and
+`supports_supplemental_attributes` (default = true) that you may need to implement.
+
+**Note**: `get_internal` and `get_name` are imported into `PowerSystems`, so you should
+implement your methods as `PowerSystems` methods.
 
 Some abstract types define required interface functions in docstring. Be sure
 to implement each of them for your new type.

docs/src/modeler_guide/cost_functions.md

@@ -0,0 +1,16 @@
+# PowerSystems Cost Functions
+
+PowerSystems.jl provides an extensive type hierarchy to explicitly express relationships between power production and cost. This lets the modeler represent cost functions as linear, quadratic, or piecewise input-output curves, potentially piecewise marginal heat rates, average heat rates, and more, as best fits the input data.
+
+To represent a cost for a particular [`Component`](@ref), the modeler first chooses one of the variable cost representations in the table below. Then, they wrap this [`ProductionVariableCost`](@ref) in either a [`CostCurve`](@ref) to indicate a cost in currency or in a [`FuelCurve`](@ref) to indicate a cost per unit of fuel plus a fuel cost. Finally, the user creates a domain-specific [`OperationalCost`](@ref) that contains this variable cost as well as other costs that may exist in that domain, such as a fixed cost that is always incurred when the unit is on. For instance, we may have `RenewableGenerationCost(CostCurve(TODO), 0.0)` to represent the cost of a renewable unit that produces at TODO, or `ThermalGenerationCost(; variable = FuelCurve(TODO), fixed = TODO, start_up = TODO, shut_down = TODO)` to represent the cost of a thermal unit that produces at TODO. Below, we give the options for `ProductionVariableCost`s. Information on what domain-specific cost must be provided for a given component type can be found in that component type's documentation.
+
+## Variable Cost Representations
+For more details, see the documentation page for each type.
+| Type alias | Description | Constructor parameters | Example |
+| --- | --- | --- | --- |
+| `LinearCurve` | Linear input-output curve with zero no-load cost (constant average rate) | Average/marginal rate | `LinearCurve(3.0)` |
+| `LinearCurve` | Linear input-output curve with nonzero no-load cost (constant marginal rate) | Marginal rate, cost at zero production | `LinearCurve(3.0, 5.0)` |
+| `QuadraticCurve` | Quadratic input-output curve, may have nonzero no-load cost | Quadratic, proportional, and constant terms of input-output curve | `QuadraticCurve(1.0, 1.0, 18.0)` |
+| `PiecewisePointCurve` | Piecewise linear curve specified by cost values at production points | Vector of (production, cost) pairs | `PiecewisePointCurve([(1.0, 20.0), (2.0, 24.0), (3.0, 30.0)])` |
+| `PiecewiseIncrementalCurve` | Piecewise linear curve specified by marginal rates (slopes) between production points, may have nonzero initial value | Cost at minimum production point, vector of $n$ production points, vector of $n-1$ marginal rates/slopes of the curve segments between the points | `PiecewiseIncrementalCurve(20., [1.0, 2.0, 3.0], [4.0, 6.0])` |
+| `PiecewiseAverageCurve` | Piecewise linear curve specified by average rates between production points, may have nonzero initial value | Cost at minimum production point, vector of $n$ production points, vector of average rates at the $n-1$ latter points | `PiecewiseAverageCurve(20., [1.0, 2.0, 3.0], [12.0, 10.0])` |

docs/src/modeler_guide/market_bid_cost.md

@@ -32,7 +32,7 @@ generator = ThermalStandard(
         time_limits = (up = 0.015, down = 0.015),
         ramp_limits = (up = 5.0, down = 3.0),
         operation_cost = MarketBidCost(
-            no_load = 0.0,
+            no_load_cost = 0.0,
             start_up = (hot = 0.0, warm = 0.0, cold = 0.0),
             shut_down = 0.0,
         ),
@@ -79,8 +79,8 @@ the `Dict` with the data as follows:
 
 ### Step 3a: Adding Energy Bid TimeSeriesData to the device
 
-To add energy market bids time-series to the `MarketBidCost`, the use of `set_variable_cost!`
-is recommended. The arguments for `set_variable_cost!` are:
+To add energy market bids time-series to the `MarketBidCost`, use `set_variable_cost!`. The
+arguments for `set_variable_cost!` are:
 
 - `sys::System`: PowerSystem System
 - `component::StaticInjection`: Static injection device
@@ -93,8 +93,8 @@ set_variable_cost!(sys, generator, time_series_data)
 
 ### Step 3b: Adding Service Bid TimeSeriesData to the device
 
-Similar to adding energy market bids, for adding bids for ancillary services the use of
-`set_service_bid!` is recommended.
+Similar to adding energy market bids, for adding bids for ancillary services, use
+`set_service_bid!`.
 
 ```@repl market_bid_cost
 service = VariableReserve{ReserveUp}("example_reserve", true, 0.6, 2.0)

docs/src/modeler_guide/system.md

@@ -213,9 +213,3 @@ jq '.data.components | .[] | select(.__metadata__.type == "ThermalStandard" and
 ```zsh
 jq '.data.components | .[] | select(.__metadata__.type == "ThermalStandard" and .active_power > 2.3)' system.json
 ```
-
-- View the time series metadata for a component.
-
-```zsh
-jq '.data.components | .[] | select(.__metadata__.type == "RenewableDispatch") | .time_series_container' system.json
-```

docs/src/modeler_guide/time_series.md

@@ -2,9 +2,9 @@
 
 ## Introduction
 
-The bulk of the data in many power system models is time series data, in order to
-organize the data the potential inherent complexity, `PowerSystems.jl` has a set of definitions
-to enable consistent modeling.
+The bulk of the data in many power system models is time series data. Given the potential
+inherent complexity, `PowerSystems.jl` has a set of definitions to organize this data and
+enable consistent modeling.
 
 - **Resolution**: The period of time between each discrete value in the data, all resolutions
   are represented using `Dates.Period` types. For instance, a Day-ahead market data set usually

docs/src/quick_start_guide.md

@@ -88,7 +88,7 @@ new_renewable = RenewableDispatch(
         prime_mover_type = PrimeMovers.WT,
         reactive_power_limits = (min = 0.0, max = 0.0),
         base_power = 100.0,
-        operation_cost = TwoPartCost(22.0, 0.0),
+        operation_cost = RenewableGenerationCost(CostCurve(LinearCurve(22.0))),
         power_factor = 1.0
     )
 

docs/src/tutorials/basics.md

@@ -52,8 +52,8 @@ print(join(tt(PowerSystems.IS.InfrastructureSystemsType, concrete = false), ""))
 ### `TimeSeriesData`
 
 [_Read the Docs!_](https://nrel-sienna.github.io/PowerSystems.jl/stable/modeler_guide/time_series/)
-Every `Component` has a `time_series_container::InfrastructureSystems.TimeSeriesContainer`
-field. `TimeSeriesData` are used to hold time series information that describes the
+Some `Component` types support time series data (refer to `supports_time_series(component)`.
+`TimeSeriesData` are used to hold time series information that describes the
 temporally dependent data of fields within the same struct. For example, the
 `ThermalStandard.time_series_container` field can
 describe other fields in the struct (`available`, `activepower`, `reactivepower`).
@@ -192,7 +192,7 @@ get_forecast_initial_times(sys)
 We can find the names of all time series attached to a component:
 
 ```@repl basics
-ts_names = get_time_series_names(Deterministic, loads[1])
+show_time_series(loads[1])
 ```
 
 We can access a specific time series for a specific component:

src/PowerSystems.jl

@@ -42,25 +42,25 @@ export PhaseShiftingTransformer
 export FunctionData
 export LinearFunctionData
 export QuadraticFunctionData
-export PolynomialFunctionData
-export PiecewiseLinearPointData
-export PiecewiseLinearSlopeData
+export PiecewiseLinearData
+export PiecewiseStepData
 export get_proportional_term
 export get_quadratic_term
 export get_constant_term
-export get_coefficients
 export get_slopes
 export get_x_lengths
 export is_convex
 export get_points
 export get_x_coords
-export get_y0
+export get_y_coords
 
-export ThreePartCost
-export TwoPartCost
-export MultiStartCost
-export MarketBidCost
-export StorageManagementCost
+export ValueCurve, InputOutputCurve, IncrementalCurve, AverageRateCurve
+export LinearCurve, QuadraticCurve
+export PiecewisePointCurve, PiecewiseIncrementalCurve, PiecewiseAverageCurve
+export ProductionVariableCost, CostCurve, FuelCurve
+export OperationalCost, MarketBidCost, LoadCost, StorageCost
+export HydroGenerationCost, RenewableGenerationCost, ThermalGenerationCost
+export get_function_data, get_initial_input, get_value_curve, get_power_units, get_fuel_cost
 
 export Generator
 export HydroGen
@@ -264,6 +264,8 @@ export Deterministic
 export Probabilistic
 export SingleTimeSeries
 export DeterministicSingleTimeSeries
+export StaticTimeSeriesInfo
+export ForecastInfo
 export Scenarios
 export ForecastCache
 export StaticTimeSeriesCache
@@ -321,23 +323,31 @@ export has_supplemental_attributes
 export iterate_supplemental_attributes
 export get_time_series
 export get_time_series_array
-export get_time_series_resolution
+export list_time_series_resolutions
+export supports_time_series
+export supports_supplemental_attributes
 export get_time_series_timestamps
 export get_time_series_values
-export get_time_series_names
 export get_time_series_counts
 export get_scenario_count
 export get_percentiles
 export get_next_time_series_array!
 export get_next_time
 export get_horizon
 export get_forecast_initial_times
-export get_forecast_total_period
+export list_time_series_info
+export show_time_series
 export get_resolution
 export get_data
 export iterate_components
 export get_time_series_multiple
 export get_variable_cost
+export get_no_load_cost
+export get_start_up
+export get_shut_down
+export get_incremental_offer_curves
+export get_decremental_offer_curves
+export get_ancillary_service_offers
 export get_services_bid
 export set_variable_cost!
 export set_service_bid!
@@ -356,7 +366,6 @@ export get_bus_numbers
 export get_name
 export set_name!
 export get_component_uuids
-export get_supplemental_attributes_container
 export get_description
 export set_description!
 export get_base_power
@@ -451,7 +460,7 @@ import Logging
 import Dates
 import TimeSeries
 import DataFrames
-import DataStructures: OrderedDict
+import DataStructures: OrderedDict, SortedDict
 import JSON3
 import CSV
 import YAML
@@ -471,7 +480,9 @@ import InfrastructureSystems:
     Deterministic,
     Probabilistic,
     SingleTimeSeries,
+    StaticTimeSeriesInfo,
     DeterministicSingleTimeSeries,
+    ForecastInfo,
     Scenarios,
     ForecastCache,
     StaticTimeSeriesCache,
@@ -497,18 +508,17 @@ import InfrastructureSystems:
     get_component_uuids,
     get_supplemental_attribute,
     get_supplemental_attributes,
-    get_supplemental_attributes_container,
     set_name!,
     get_internal,
     set_internal!,
-    get_time_series_container,
     iterate_windows,
     get_time_series,
     has_time_series,
     get_time_series_array,
     get_time_series_timestamps,
     get_time_series_values,
-    get_time_series_names,
+    list_time_series_info,
+    show_time_series,
     get_scenario_count, # Scenario Forecast Exports
     get_percentiles, # Probabilistic Forecast Exports
     get_next_time_series_array!,
@@ -538,21 +548,21 @@ import InfrastructureSystems:
     FunctionData,
     LinearFunctionData,
     QuadraticFunctionData,
-    PolynomialFunctionData,
-    PiecewiseLinearPointData,
-    PiecewiseLinearSlopeData,
+    PiecewiseLinearData,
+    PiecewiseStepData,
     get_proportional_term,
     get_quadratic_term,
     get_constant_term,
-    get_coefficients,
     get_slopes,
+    running_sum,
     get_x_lengths,
     is_convex,
     get_points,  # TODO possible rename to disambiguate from geographical information
     get_x_coords,
-    get_y0,  # TODO reevaluate whether this should be exported
-    get_raw_data,
-    get_raw_data_type
+    get_y_coords,
+    get_raw_data_type,
+    supports_time_series,
+    supports_supplemental_attributes
 
 const IS = InfrastructureSystems
 
@@ -579,6 +589,9 @@ abstract type Component <: IS.InfrastructureSystemsComponent end
 """ Supertype for "devices" (bus, line, etc.) """
 abstract type Device <: Component end
 
+supports_time_series(::Device) = true
+supports_supplemental_attributes(::Device) = true
+
 # Include utilities
 include("utils/logging.jl")
 include("utils/IO/base_checks.jl")
@@ -593,7 +606,6 @@ include("models/static_injection_subsystem.jl")
 # PowerSystems models
 include("models/topological_elements.jl")
 include("models/branches.jl")
-include("models/operational_cost.jl")
 #include("models/network.jl")
 
 # Static types
@@ -606,6 +618,18 @@ include("models/dynamic_generator_components.jl")
 include("models/dynamic_inverter_components.jl")
 include("models/OuterControl.jl")
 
+# Costs
+include("models/cost_functions/ValueCurves.jl")
+include("models/cost_functions/cost_aliases.jl")
+include("models/cost_functions/variable_cost.jl")
+include("models/cost_functions/operational_cost.jl")
+include("models/cost_functions/MarketBidCost.jl")
+include("models/cost_functions/HydroGenerationCost.jl")
+include("models/cost_functions/LoadCost.jl")
+include("models/cost_functions/RenewableGenerationCost.jl")
+include("models/cost_functions/StorageCost.jl")
+include("models/cost_functions/ThermalGenerationCost.jl")
+
 # Include all auto-generated structs.
 include("models/generated/includes.jl")
 include("models/regulation_device.jl")