Skip to content

Commit 62a7ad4

Browse files
jd-larajd-lara
authored
Merge pull request #1148 from kdayday/doc_org
Re-organization of the PSY docs to follow the Diataxis format
2 parents 6c55eb2 + 0c9c8b3 commit 62a7ad4

File tree

175 files changed

+2398
-1855
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

175 files changed

+2398
-1855
lines changed

‎docs/make.jl

Lines changed: 40 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -9,45 +9,49 @@ include(joinpath(@__DIR__, "make_model_library.jl"))
99

1010
pages = OrderedDict(
1111
"Welcome Page" => "index.md",
12-
"Quick Start Guide" => "quick_start_guide.md",
1312
"Tutorials" => Any[
14-
"Introduction" => "tutorials/basics.md",
15-
"Parsing PowerFlow Data" => "tutorials/parse_powerflow_cases.md",
16-
"Parsing Tabular Data" => "tutorials/parse_tabular_data.md",
17-
"Add Forecasts" => "tutorials/add_forecasts.md",
18-
"Serialize Data" => "tutorials/serialize_data.md",
19-
"Use Dynamic Data" => "tutorials/dynamic_data.md",
20-
"PowerSystemCaseBuilder" => "tutorials/powersystembuilder.md",
21-
"Add an Operating Cost" => "tutorials/add_cost_curve.md",
13+
"Create and Explore a Power `System`" => "tutorials/creating_system.md",
14+
"Working with Time Series" => "tutorials/working_with_time_series.md",
15+
"Adding dynamic devices" => "tutorials/add_dynamic_device.md",
2216
],
23-
"Modeler Guide" =>
17+
"How to..." => Any[
18+
"...install PowerSystems.jl" => "how_to/install.md",
19+
"...load a `system` from `PowerSystemCaseBuilder`" => "how_to/powersystembuilder.md",
20+
"...parse data from Matpower, PSSE, or CSV files" => "how_to/parsing.md",
21+
"...add time series data from CSVs" => "how_to/add_ts_from_csvs.md",
22+
"...customize the tabular data parser" => "how_to/extend_tabular_parsing.md",
23+
"...get all the buses in a system" => "how_to/get_buses.md",
24+
"...get the available generators in a system" => "how_to/get_available_generators.md",
25+
"...add an Operating Cost" => "how_to/add_cost_curve.md",
26+
"...add a market bid" => "how_to/market_bid_cost.md",
27+
"...add additional data to a component" => "how_to/adding_additional_fields.md",
28+
"...add a new Type" => "how_to/add_new_types.md",
29+
"...improve performance with time series data" => "how_to/improve_ts_performance.md",
30+
"...serialize data to a JSON" => "how_to/serialize_data.md",
31+
"...reduce REPL printing" => "how_to/reduce_repl_printing.md",
32+
"...migrate from version 3.0 to 4.0" => "how_to/migrating_to_psy4.md"
33+
],
34+
"Explanation" =>
2435
Any[
25-
"modeler_guide/type_structure.md",
26-
"modeler_guide/system.md",
27-
"modeler_guide/time_series.md",
28-
"modeler_guide/enumerated_types.md",
29-
"modeler_guide/example_dynamic_data.md",
30-
"modeler_guide/system_dynamic_data.md",
31-
"modeler_guide/cost_functions.md",
32-
"modeler_guide/market_bid_cost.md",
33-
"modeler_guide/modeling_with_JuMP.md",
34-
"modeler_guide/parsing.md",
35-
"modeler_guide/glossary.md",
36-
],
37-
"Model Developer Guide" =>
38-
Any["Extending Parsing" => "model_developer_guide/extending_parsing.md",
39-
"Adding Types" => "model_developer_guide/adding_custom_types.md",
40-
"Adding Additional Fields" => "model_developer_guide/adding_additional_fields.md",
41-
42-
],
43-
"Code Base Developer Guide" =>
44-
Any["Developer Guide" => "code_base_developer_guide/developer.md",
45-
"Adding New Types" => "code_base_developer_guide/adding_new_types.md",
46-
"Troubleshooting" => "code_base_developer_guide/troubleshooting.md"
36+
"explanation/system.md",
37+
"explanation/type_structure.md",
38+
"explanation/per_unit.md",
39+
"explanation/time_series.md",
40+
"explanation/example_dynamic_data.md",
4741
],
4842
"Model Library" => Any[],
49-
"Public API Reference" => "api/public.md",
50-
"Internal API Reference" => "api/internal.md"
43+
"Reference" =>
44+
Any["Public API" => "api/public.md",
45+
"Internal API Reference" => "api/internal.md",
46+
"Glossary and Acronyms" => "api/glossary.md",
47+
"Type Hierarchy" => "api/type_tree.md",
48+
"`ValueCurve` Options" => "api/valuecurve_options.md",
49+
"Specifying the category of..." => "api/enumerated_types.md",
50+
"Developer Guidelines" => "api/developer_guidelines.md",
51+
"Citation" => "api/citation.md"
52+
]
53+
54+
5155
)
5256

5357
pages["Model Library"] = make_model_library(
@@ -97,9 +101,8 @@ end
97101
julia_file_filter = x -> occursin(".jl", x)
98102
folders = Dict(
99103
"Model Library" => filter(julia_file_filter, readdir("docs/src/model_library")),
100-
"Modeler Guide" => filter(julia_file_filter, readdir("docs/src/modeler_guide")),
101-
"Model Developer Guide" => filter(julia_file_filter, readdir("docs/src/model_developer_guide")),
102-
"Code Base Developer Guide" => filter(julia_file_filter, readdir("docs/src/code_base_developer_guide")),
104+
"Explanation" => filter(julia_file_filter, readdir("docs/src/explanation")),
105+
"How to..." => filter(julia_file_filter, readdir("docs/src/how_to")),
103106
)
104107
for (section, folder) in folders
105108
for file in folder

‎docs/src/api/citation.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
### Citation
2+
3+
Users are requested to please cite the
4+
[following paper:](https://www.sciencedirect.com/science/article/pii/S2352711021000765)
5+
6+
```bibtex
7+
@article{LARA2021100747,
8+
title = {PowerSystems.jl — A power system data management package for large scale modeling},
9+
journal = {SoftwareX},
10+
volume = {15},
11+
pages = {100747},
12+
year = {2021},
13+
issn = {2352-7110},
14+
doi = {https://doi.org/10.1016/j.softx.2021.100747},
15+
url = {https://www.sciencedirect.com/science/article/pii/S2352711021000765},
16+
author = {José Daniel Lara and Clayton Barrows and Daniel Thom and Dheepak Krishnamurthy and Duncan Callaway},
17+
keywords = {Power Systems, Julia, Energy},
18+
```
19+
20+
------------
21+
PowerSystems has been developed as part of the [Sienna modeling framework](https://www.nrel.gov/analysis/sienna.html)
22+
by the U.S. Department of Energy's National Renewable Energy Laboratory
23+
([NREL](https://www.nrel.gov/)).

‎docs/src/code_base_developer_guide/developer.md renamed to ‎docs/src/api/developer_guidelines.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Guidelines for Developers
1+
# Developer Guidelines
22

33
In order to contribute to `PowerSystems.jl` repository please read the following sections of
44
[`InfrastructureSystems.jl`](https://github.com/NREL-Sienna/InfrastructureSystems.jl)

‎docs/src/modeler_guide/enumerated_types.md renamed to ‎docs/src/api/enumerated_types.md

Lines changed: 85 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,37 @@
11

2-
# Enumerated Types
2+
# Specifying the type of...
33

4-
To specify fields representing an option from a pre-defined list, some of the fields of
5-
`Component` structs are specified with
6-
[`IS.scoped_enums`](https://nrel-sienna.github.io/InfrastructureSystems.jl/stable/InfrastructureSystems/#InfrastructureSystems.@scoped_enum-Tuple{Any,%20Vararg{Any,%20N}%20where%20N}) (e.g.
7-
`set_fuel!(gen, ThermalFuels.COAL)`). Below are the enumerated types contained in `PowerSystems`.
4+
Some fields in PowerSystems.jl are specified with an option from a pre-defined list
5+
(Specified with [`IS.scoped_enums`](https://nrel-sienna.github.io/InfrastructureSystems.jl/stable/InfrastructureSystems/#InfrastructureSystems.@scoped_enum-Tuple{Any,%20Vararg{Any,%20N}%20where%20N})).
86

9-
## [`ThermalFuels`](@id tf_list)
7+
Example syntax:
8+
```
9+
set_fuel!(gen, ThermalFuels.COAL)
10+
```
1011

11-
Each `ThermalGen` generator struct contains a field for `fuel::ThermalFuels` where `ThermalFuels`
12-
are intended to reflect the options denoted by the
13-
[Aggregated Fuel Codes](https://www.eia.gov/survey/form/eia_923/instructions.pdf) from the
14-
EIA Annual Energy Review. Specifically, `ThermalFuels` is an enumerated type with the
15-
following options:
12+
These predefined lists are below:
1613

17-
| EnumName | EIA Fuel Code | Description |
18-
|----------|---------------|-------------|
19-
| `COAL` | COL | Anthracite Coal and Bituminous Coal |
20-
| `WASTE_COAL` | WOC | Waste/Other Coal (includes anthracite culm, gob, fine coal, lignite waste, waste coal) |
21-
| `DISTILLATE_FUEL_OIL` | DFO | Distillate Fuel Oil (Diesel, No. 1, No. 2, and No. 4) |
22-
| `WASTE_OIL` | WOO | Waste Oil Kerosene and JetFuel Butane, Propane |
23-
| `PETROLEUM_COKE` | PC | Petroleum Coke |
24-
| `RESIDUAL_FUEL_OIL` | RFO | Residual Fuel Oil (No. 5, No. 6 Fuel Oils, and Bunker Oil) |
25-
| `NATURAL_GAS` | NG | Natural Gas |
26-
| `OTHER_GAS` | OOG | Other Gas and blast furnace gas |
27-
| `NUCLEAR` | NUC | Nuclear Fission (Uranium, Plutonium, Thorium) |
28-
| `AG_BIPRODUCT` | ORW | Agricultural Crop Byproducts/Straw/Energy Crops |
29-
| `MUNICIPAL_WASTE` | MLG | Municipal Solid Waste – Biogenic component |
30-
| `WOOD_WASTE` | WWW | Wood Waste Liquids excluding Black Liquor (BLQ) (Includes red liquor, sludge wood, spent sulfite liquor, and other wood-based liquids) |
31-
| `GEOTHERMAL` | GEO | Geothermal |
32-
| `OTHER` | OTH | Other |
14+
## [AC Buses](@id acbustypes_list)
15+
16+
`ACBusTypes` categorize buses for modeling activities and denote which quantities are specified
17+
for load flow calculations. `ACBusTypes` has the options:
3318

34-
## [`PrimeMovers`](@id pm_list)
19+
| Name | Description |
20+
|:----------|:-------------|
21+
| `ISOLATED` | Disconnected from network |
22+
| `PQ` | Active and reactive power defined (load bus)|
23+
| `PV` | Active power and voltage magnitude defined (generator bus)|
24+
| `REF` | Reference bus (θ = 0)|
25+
| `SLACK` | Slack bus |
3526

36-
Each generator struct contains a field for `prime_mover::PrimeMovers` where `PrimeMovers`
37-
are intended to reflect the options denoted by
38-
[EIA form 923](https://www.eia.gov/survey/form/eia_923/instructions.pdf). Specifically,
39-
`PrimeMovers` is an enumerated type with the following options:
27+
## [Prime Movers](@id pm_list)
4028

41-
| EnumName | Description |
42-
|----------|-------------|
29+
Each generator contains a field for `prime_mover::PrimeMovers`, based on the options in
30+
[EIA form 923](https://www.eia.gov/survey/form/eia_923/instructions.pdf).
31+
`PrimeMovers` has the options:
32+
33+
| Name | Description |
34+
|:----------|:-------------|
4335
| `BA` | Energy Storage, Battery |
4436
| `BT` | Turbines Used in a Binary Cycle (including those used for geothermal applications) |
4537
| `CA` | Combined-Cycle – Steam Part |
@@ -60,36 +52,71 @@ are intended to reflect the options denoted by
6052
| `PS` | Energy Storage, Reversible Hydraulic Turbine (Pumped Storage) |
6153
| `OT` | Other |
6254
| `ST` | Steam Turbine (including nuclear, geothermal and solar steam; does not include combined-cycle turbine) |
63-
| `PV` | Photovoltaic *renaming from EIA PV to PVe to avoid conflict with ACBusType.PV |
55+
| `PVe` | Photovoltaic \(*Note*: renaming from EIA PV to PVe to avoid conflict with `ACBusType.PV`\) |
6456
| `WT` | Wind Turbine, Onshore |
6557
| `WS` | Wind Turbine, Offshore |
6658

67-
## [`ACBusTypes`](@id acbustypes_list)
68-
69-
`ACBusTypes` is used to denote which quantities are specified for load flow calculations and
70-
to otherwise categorize buses for modeling activities.
59+
## [Fuels for Thermal Generators](@id tf_list)
7160

72-
| EnumName | Description |
73-
|----------|-------------|
74-
| `ISOLATED` | Disconnected from network |
75-
| `PQ` | Active and reactive power defined (load bus)|
76-
| `PV` | Active power and voltage magnitude defined (generator bus)|
77-
| `REF` | Reference bus (θ = 0)|
78-
| `SLACK` | Slack bus |
79-
80-
## [`AngleUnits`](@id angleunits_list)
81-
82-
| EnumName |
83-
|----------|
84-
| `DEGREES` |
85-
| `RADIANS` |
86-
87-
## [`StateTypes`](@id states_list)
61+
Each [`ThermalGen`](@ref) generator has a field for `fuel::ThermalFuels` where `ThermalFuels`
62+
are intended to reflect the options in the
63+
[Aggregated Fuel Codes](https://www.eia.gov/survey/form/eia_923/instructions.pdf) from the
64+
EIA Annual Energy Review. `ThermalFuels` has the options:
8865

89-
`StateTypes` are used to denote the type of dynamic equation a specific state is subject to in `PowerSimulationsDynamics.jl`
66+
| Name | EIA Fuel Code | Description |
67+
|:----------|:---------------|:-------------|
68+
| `COAL` | COL | Anthracite Coal and Bituminous Coal |
69+
| `WASTE_COAL` | WOC | Waste/Other Coal (includes anthracite culm, gob, fine coal, lignite waste, waste coal) |
70+
| `DISTILLATE_FUEL_OIL` | DFO | Distillate Fuel Oil (Diesel, No. 1, No. 2, and No. 4) |
71+
| `WASTE_OIL` | WOO | Waste Oil Kerosene and JetFuel Butane, Propane |
72+
| `PETROLEUM_COKE` | PC | Petroleum Coke |
73+
| `RESIDUAL_FUEL_OIL` | RFO | Residual Fuel Oil (No. 5, No. 6 Fuel Oils, and Bunker Oil) |
74+
| `NATURAL_GAS` | NG | Natural Gas |
75+
| `OTHER_GAS` | OOG | Other Gas and blast furnace gas |
76+
| `NUCLEAR` | NUC | Nuclear Fission (Uranium, Plutonium, Thorium) |
77+
| `AG_BIPRODUCT` | ORW | Agricultural Crop Byproducts/Straw/Energy Crops |
78+
| `MUNICIPAL_WASTE` | MLG | Municipal Solid Waste – Biogenic component |
79+
| `WOOD_WASTE` | WWW | Wood Waste Liquids excluding Black Liquor (BLQ) (Includes red liquor, sludge wood, spent sulfite liquor, and other wood-based liquids) |
80+
| `GEOTHERMAL` | GEO | Geothermal |
81+
| `OTHER` | OTH | Other |
9082

91-
| EnumName | Description |
92-
|----------|-------------|
83+
## [Energy Storage](@id storagetech_list)
84+
85+
`StorageTech` defines the storage technology used in an energy [`Storage`](@ref) system, based
86+
on the options in [EIA form 923](https://www.eia.gov/survey/form/eia_923/instructions.pdf).
87+
`StorageTech` has the options:
88+
89+
| Name | Description |
90+
|:----------|:-------------|
91+
| `PTES` | Pumped thermal energy storage |
92+
| `LIB` | LiON Battery |
93+
| `LAB` | Lead Acid Battery |
94+
| `FLWB` | Redox Flow Battery |
95+
| `SIB` | Sodium Ion Battery |
96+
| `ZIB` | Zinc Ion Battery |
97+
| `HGS` | Hydrogen Gas Storage |
98+
| `LAES` | Liquid Air Storage |
99+
| `OTHER_CHEM` | Other Chemical Storage |
100+
| `OTHER_MECH` | Other Mechanical Storage |
101+
| `OTHER_THERM` | Other Thermal Storage |
102+
103+
## [Dynamic States](@id states_list)
104+
105+
`StateTypes` are used to denote the type of dynamic equation a specific [state](@ref S) is subject
106+
to in [`PowerSimulationsDynamics.jl`](https://nrel-sienna.github.io/PowerSimulationsDynamics.jl/stable/).
107+
`StateTypes` has the options:
108+
109+
| Name | Description |
110+
|:----------|:-------------|
93111
| `Differential` | State evolves over time via a differential equation ``\dot{x} = f(x)`` |
94112
| `Algebraic` | State evolves over time by satisfying an algebraic equation ``0 = g(x)`` |
95113
| `Hybrid` | Depending on specific parameters, the state can be `Differential` or `Algebraic` |
114+
115+
## [Angle Units](@id angleunits_list)
116+
117+
`AngleUnits` can be specified in:
118+
119+
| Name |
120+
|----------|
121+
| `DEGREES` |
122+
| `RADIANS` |

0 commit comments

Comments
 (0)