Per-type service models with merged sparse/dense reserve containers

docs/make.jl

@@ -13,7 +13,9 @@ make_tutorials()
 
 pages = OrderedDict(
     "Welcome Page" => "index.md",
-    # "Tutorials" => Any["stub" => "tutorials/generated_stub.md"],
+    "Tutorials" => Any[
+        "Running a Problem with Service Bids" => "tutorials/generated_service_bids.md",
+    ],
     # "How to..." => Any["stub" => "how_to_guides/stub.md"],
     # "Explanation" => Any["stub" => "explanation/stub.md"],
     "Reference" => Any[

docs/make_tutorials.jl

@@ -441,19 +441,29 @@ function make_tutorials()
 
                 outputfile = string("generated_", replace("$file", ".jl" => ""))
 
-                # Generate markdown
+                # Generate markdown with the Documenter flavor (so `@ref`/`@extref` links and
+                # `!!! admonition` blocks render). Code-block execution follows the `execute`
+                # opt-in: tutorials marked `EXECUTE = TRUE` keep Documenter `@example` blocks
+                # (run at `makedocs` time, output captured); all others have their `@example`
+                # fences rewritten to plain `julia` blocks that Documenter does not execute - so
+                # a tutorial needing solvers or data the docs environment does not carry still
+                # builds, and the downloadable script/notebook remains fully runnable.
                 Literate.markdown(infile_path,
                     tutorial_outputdir;
                     name = outputfile,
                     credit = false,
                     flavor = Literate.DocumenterFlavor(),
                     documenter = true,
                     postprocess = (
-                        content -> add_download_links(
-                            insert_md(content),
-                            file,
-                            string(outputfile, ".ipynb"),
-                        )
+                        content -> begin
+                            content = add_download_links(
+                                insert_md(content),
+                                file,
+                                string(outputfile, ".ipynb"),
+                            )
+                            execute ? content :
+                            replace(content, r"```@example[^\n]*" => "```julia")
+                        end
                     ),
                     execute = execute)
 

docs/src/reference/formulation_library.md

@@ -514,15 +514,15 @@ no-op.
 
 ## [Service Formulations](@id service_formulations)
 
-| Formulation                  | Service type                | Argument stage                                                                                 | Model stage                                                |
-|:---------------------------- |:--------------------------- |:---------------------------------------------------------------------------------------------- |:---------------------------------------------------------- |
-| `RangeReserve`               | `PSY.Reserve`               | `RequirementTimeSeriesParameter` (omitted for `ConstantReserve`), `ActivePowerReserveVariable` | `RequirementConstraint`, `ParticipationFractionConstraint` |
-| `RampReserve`                | `PSY.Reserve`               | as above                                                                                       | as above **+ `RampConstraint`**                            |
-| `NonSpinningReserve`         | `PSY.ReserveNonSpinning`    | as above, but **no** device-range expression wiring                                            | as above **+ `ReservePowerConstraint`**                    |
-| `StepwiseCostReserve` (ORDC) | `PSY.Reserve`               | `ServiceRequirementVariable` + ORDC slope/breakpoint parameters                                | `RequirementConstraint` only — no participation constraint |
-| `GroupReserve`               | `PSY.ConstantReserveGroup`  | no variables                                                                                   | `RequirementConstraint` across contributing services       |
-| `ConstantMaxInterfaceFlow`   | `PSY.TransmissionInterface` | optional slacks, `InterfaceTotalFlow` expression                                               | `InterfaceFlowLimit` (`"ub"`/`"lb"`)                       |
-| `VariableMaxInterfaceFlow`   | `PSY.TransmissionInterface` | as above **+ min/max flow-limit parameters**                                                   | as above, with parameterized limits                        |
+| Formulation                                            | Service type                | Argument stage                                                                                 | Model stage                                                |
+|:------------------------------------------------------ |:--------------------------- |:---------------------------------------------------------------------------------------------- |:---------------------------------------------------------- |
+| `RangeReserve`                                         | `PSY.Reserve`               | `RequirementTimeSeriesParameter` (omitted for `ConstantReserve`), `ActivePowerReserveVariable` | `RequirementConstraint`, `ParticipationFractionConstraint` |
+| `RampReserve`                                          | `PSY.Reserve`               | as above                                                                                       | as above **+ `RampConstraint`**                            |
+| `NonSpinningReserve`                                   | `PSY.ReserveNonSpinning`    | as above, but **no** device-range expression wiring                                            | as above **+ `ReservePowerConstraint`**                    |
+| `StepwiseCostReserve` (operating reserve demand curve) | `PSY.Reserve`               | `ServiceRequirementVariable` + demand-curve slope/breakpoint parameters                        | `RequirementConstraint` only — no participation constraint |
+| `GroupReserve`                                         | `PSY.ConstantReserveGroup`  | no variables                                                                                   | `RequirementConstraint` across contributing services       |
+| `ConstantMaxInterfaceFlow`                             | `PSY.TransmissionInterface` | optional slacks, `InterfaceTotalFlow` expression                                               | `InterfaceFlowLimit` (`"ub"`/`"lb"`)                       |
+| `VariableMaxInterfaceFlow`                             | `PSY.TransmissionInterface` | as above **+ min/max flow-limit parameters**                                                   | as above, with parameterized limits                        |
 
 `GroupReserve` is deliberately constructed **last** in both stages, because it aggregates the other
 services' variables.
@@ -586,8 +586,8 @@ commitment.
 
 Offer *direction* selects the delta family: generation is an `IncrementalOffer`; the charging side
 of storage, the import side of a `Source`, and controllable loads are `DecrementalOffer` (negative
-objective sign). ORDC reserve demand curves are also decremental, because a willingness-to-pay
-curve is concave.
+objective sign). Operating reserve demand curves are also decremental, because a
+willingness-to-pay curve is concave.
 
 ## [When to use `meta` versus a new key type](@id meta_vs_key_type)