Draft
Conversation
added 9 commits
February 17, 2026 15:17
…per_unit explanation for transformers
Changed accessor and getter language across multiple pages
Edits include deleting the original supplemental attributes explanation, and creating a new one. Then, adding in two how tos, which describe how to add supplemental attributes and then a second how to about querying the supplemental attributes to get additional information. Update the glossary with UUID description as well.
First edits to system explanation and a new how-to. Also edited the make.jl file to include previously committed files and these new files.
Key changes include adding @id references to the tutorials, referencing those tutorials in the explanation, and creating a separate how-to using code originally featured in the system explanation.
Successfully compiled the documentation and fixed a number of issues. Most of them were for broken or missing references.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #1635 +/- ##
==========================================
+ Coverage 84.13% 84.15% +0.02%
==========================================
Files 204 204
Lines 10540 10536 -4
==========================================
- Hits 8868 8867 -1
+ Misses 1672 1669 -3
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
Contributor
|
@jbrossman I haven't taken a look yet, but FYI, about figures there's a different file path to get it to show up locally versus on github ("../" vs. "../../" or vice versa). We will want whichever one gets it to show up on the github Preview, so don't worry about it if it doesn't show up locally |
added 4 commits
March 2, 2026 14:09
Edits to Power Concepts including a new and more built out how-to
Mostly reorganizing the information
kdayday
reviewed
Mar 3, 2026
| @@ -1,4 +1,4 @@ | |||
| # # Create and Explore a Power `System` | |||
| # # [Create and Explore a Power `System`](@id tutorial_creating_system) | |||
Contributor
There was a problem hiding this comment.
I think these ID tags show up badly in the Jupyter notebook versions of the tutorials, so let's remove and just use the title tags if it all possible
kdayday
reviewed
Mar 3, 2026
kdayday
reviewed
Mar 3, 2026
kdayday
reviewed
Mar 3, 2026
kdayday
reviewed
Mar 3, 2026
kdayday
reviewed
Mar 3, 2026
|
|
||
| Each infrastructure component is represented as a [`struct`](@ref S) — a composite data | ||
| type that bundles together the fields needed to describe that component. For example, an | ||
| `ACBus` carries fields for its bus number, nominal voltage, bus type, and more: |
Contributor
There was a problem hiding this comment.
Add hyperlinks on all type and function names
added 6 commits
March 3, 2026 08:28
Edits to use_subsystems.md to get an error free example, word changes, and reference links.
Julia blocks changed to REPL blocks, additional references added, and further explanation about data storage.
Key changes include additional references, describing what a dynamic device is, taking out the images that originally appeared, and more clearly linking the ideas between the sections.
Remove @id tags in tutorials, and update any references to these tutorials to use the title instead.
Search and edit how_to folder to convert all '''julia code blocks to use the '''repl formatting instead.
Modify most files in explanation and how_to revisiting the best practices for hyperlinks.
Bring back background on concrete versus abstract supplemental attributes, and provide two examples using the Type Tree.
Short note about what broadcast functions are and link to a blog that describes them well.
Small edits to plant_attributes. More to come.
More getter functions added to tutorial. Need to check what steps would be required to get them into the accompanying notebook and markdown files.
Docstring edits across these files. Followed general advice in the Organize APIs and Write Docstrings site.
Additional files from when compiling locally
Some enum edits for issue 1611. Reached out to Hannah to find out what PumpHydroStatus was because an initial search did now show this.
Draft pr was failing on a PowerNetworkMatrices issue. Copilot suggested taking this part out because it was defined somewhere else.
These lines were causing failures on a job. Copilot suggested removing the last argument in each of these occurances.
Removed double definition of one item, and fixed a struct issue and reran those.
Contributor
There was a problem hiding this comment.
Pull request overview
This draft PR primarily updates PowerSystems.jl documentation and docstrings to better explain supplemental attributes, subsystems, time series usage, and various model/type concepts (per Issues #1504 and #1461). It also makes a small functional addition to subsystem checking and adjusts a time-series transform test to reflect current InfrastructureSystems behavior.
Changes:
- Expanded/rewrote many docstrings across
src/(types, getters, supplemental attributes, dynamics) and reorganized docs pages/cross-references. - Added new how-to guides (supplemental attributes, subsystems, unit conversions, transformer impedance conversion) and updated tutorials accordingly.
- Adjusted subsystem validation by adding a
check_subsystems(sys::System)entrypoint; updated a deterministic STS transform test to assert replacement behavior.
Reviewed changes
Copilot reviewed 85 out of 89 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| test/test_system.jl | Updates a time series transform test to assert deterministic STS replacement behavior. |
| src/subsystems.jl | Adds check_subsystems(sys::System) to validate subsystem assignment consistency system-wide. |
| src/outages.jl | Docstring expansions/clarifications for outage supplemental attributes. |
| src/models/topological_elements.jl | Improves type hierarchy docstrings for topology elements. |
| src/models/supplemental_constructors.jl | Converts some docstrings to inline comments for legacy constructors. |
| src/models/storage.jl | Expands Storage abstract type docstring. |
| src/models/static_models.jl | Adds/clarifies docstrings for service support and related accessors. |
| src/models/static_injection_subsystem.jl | Clarifies subsystem docstrings and time series copying semantics. |
| src/models/services.jl | Expands high-level services docstring and subtype list. |
| src/models/reserves.jl | Improves reserve direction/type docstrings (but contains a formatting issue noted in comments). |
| src/models/loads.jl | Expands docstrings for load abstract types and relationships. |
| src/models/injection.jl | Clarifies set_dynamic_injector! purpose and signature docs. |
| src/models/generation.jl | Expands generator type docstrings; tightens RenewableGen helper method signatures. |
| src/models/generated/SEXS.jl | Doc formatting for state listings. |
| src/models/generated/RenewableNonDispatch.jl | Updates docstring cross-reference for get_max_active_power. |
| src/models/generated/RenewableDispatch.jl | Updates docstring cross-reference for get_max_active_power. |
| src/models/dynamic_models.jl | Expands dynamic model docstrings and clarifies relationships. |
| src/models/dynamic_inverter_components.jl | Adds docstrings for inverter control supertypes. |
| src/models/dynamic_inverter.jl | Switches to $(TYPEDFIELDS) and adds per-field docstrings. |
| src/models/dynamic_generator.jl | Switches to $(TYPEDFIELDS) and adds per-field docstrings. |
| src/models/dynamic_branch.jl | Switches docstring to $(TYPEDFIELDS) and adds field docs. |
| src/models/devices.jl | Improves docs for service/turbine APIs and supports_services behavior. |
| src/models/cost_functions/operational_cost.jl | Clarifies OperationalCost supertype docs. |
| src/models/cost_functions/MarketBidCost.jl | Minor docstring adjustment for is_market_bid_curve. |
| src/models/components.jl | Docstring improvements and signature simplifications for unit conversion helpers. |
| src/models/branches.jl | Expands branch hierarchy docs and adds docs for bus accessors. |
| src/models/SalientPoleQuadratic.jl | Switches to $(TYPEDFIELDS) and adds field docs. |
| src/models/SalientPoleExponential.jl | Switches to $(TYPEDFIELDS) and adds field docs. |
| src/models/RoundRotorQuadratic.jl | Switches to $(TYPEDFIELDS) and adds field docs. |
| src/models/RoundRotorExponential.jl | Switches to $(TYPEDFIELDS) and adds field docs. |
| src/models/OuterControl.jl | Switches to $(TYPEDFIELDS) and adds per-field docstrings. |
| src/models/HybridSystem.jl | Switches to $(TYPEDFIELDS) and adds per-field docstrings. |
| src/impedance_correction.jl | Expanded docstrings for impedance correction supplemental attribute. |
| src/get_components_interface.jl | Adds clearer docstrings/examples for component retrieval APIs. |
| src/descriptors/power_system_structs.json | Keeps generated descriptor docstrings in sync with source doc changes. |
| src/definitions.jl | Adds docs for StartUpStages and expands many enum docstrings. |
| src/PowerSystems.jl | Exports StartUpStages and expands Device docstring. |
| scripts/format_and_build_docs.jl | Adds a helper script to format and build docs (path robustness issue noted). |
| scripts/format_and_build_docs.bat | Adds a Windows helper script (contains machine-specific path; issue noted). |
| docs/src/tutorials/working_with_time_series.jl | Updates tutorial structure; removes multi-interval transform section; adds metadata/value/timestamp examples. |
| docs/src/tutorials/manipulating_datasets.jl | Updates time-series tutorial linking text/reference. |
| docs/src/tutorials/creating_system.jl | Updates “next steps” links to new/renamed anchors. |
| docs/src/tutorials/add_dynamic_data.jl | Fixes doc cross-reference for dynamic devices page anchor. |
| docs/src/how_to/use_supplemental_attributes.md | New how-to for querying supplemental attributes and associated components. |
| docs/src/how_to/use_subsystems.md | New how-to describing subsystem creation, filtering, and exporting. |
| docs/src/how_to/use_context_managers.md | Adds ids and converts examples to @repl; updates cross-links. |
| docs/src/how_to/serialize_data.md | Adds id and updates UUID references/example fencing. |
| docs/src/how_to/reduce_repl_printing.md | Adds id and converts example to @repl. |
| docs/src/how_to/parse_ts_from_csvs.md | Improves linking, terminology, and cross-references. |
| docs/src/how_to/parse_matpower_psse.md | Fixes wording/typos and improves formatting/linking. |
| docs/src/how_to/parse_dynamic_data.md | Minor doc corrections and stronger System references. |
| docs/src/how_to/migrating_to_psy5.md | Minor corrections and link updates. |
| docs/src/how_to/market_bid_cost.md | Improves linking for types/functions and clarifies units. |
| docs/src/how_to/jump.md | Wording update (“getter functions”). |
| docs/src/how_to/improve_ts_performance.md | Adds ids, converts examples to @repl, and updates references. |
| docs/src/how_to/handle_3W_transformers.md | Minor wording/typo fixes. |
| docs/src/how_to/create_system_with_source_import_export_cost.md | Adds id and standardizes heading. |
| docs/src/how_to/create_hydro_datasets.md | Converts code fences to @repl blocks. |
| docs/src/how_to/convert_unit_systems.md | New how-to explaining unit system switching and interpretation. |
| docs/src/how_to/convert_transformer_impedance.md | New how-to walking through transformer impedance base conversion. |
| docs/src/how_to/build_system_with_files.md | Converts examples to @repl, fixes links/typos, updates cross-references. |
| docs/src/how_to/adding_additional_fields.md | Improves linking to component types. |
| docs/src/how_to/add_supplemental_attributes.md | New how-to showing how to attach supplemental attributes (single/bulk/shared). |
| docs/src/how_to/add_new_types.md | Adds ids, improves links, and standardizes terminology. |
| docs/src/how_to/add_fuel_curve_timeseries.md | Minor doc improvements and updated time series tutorial link. |
| docs/src/how_to/add_cost_curve.md | Improves linking to referenced types. |
| docs/src/how_to/add_component_natural_units.md | Adds id, improves cross-links, and fixes final tutorial link. |
| docs/src/generate_input_config_table.jl | Fixes a spelling issue in a comment. |
| docs/src/explanation/type_structure.md | Major rewrite/expansion of type hierarchy explanation (contains trailing code fences issue noted). |
| docs/src/explanation/transformer_per_unit_models.md | Replaces long content with a pointer to the new transformer impedance how-to. |
| docs/src/explanation/time_series.md | Expands data storage/scaling factor explanation; updates links and hierarchy references. |
| docs/src/explanation/system.md | Rewrites/expands system explanation; moves subsystem guidance to a how-to link. |
| docs/src/explanation/supplemental_attributes_2.md | New/rewritten supplemental attributes explanation page. |
| docs/src/explanation/supplemental_attributes.md | Removes the old supplemental attributes explanation page. |
| docs/src/explanation/power_concepts.md | Improves linking to getter functions and moves unit conversion example to new how-to. |
| docs/src/explanation/plant_attributes.md | Updates references to new supplemental attributes explanation page and improves wording. |
| docs/src/explanation/per_unit.md | Improves wording and links; adds transformer per-unit section and link to new how-to. |
| docs/src/explanation/dynamic_data.md | Adds @id dynamic_data and expands explanation (contains trailing code fences issue noted). |
| docs/src/explanation/conforming_and_non_conforming_loads.md | Rewrites for clarity; adds structure and “see also” section. |
| docs/src/explanation/buses_type_explanation.md | Significant rewrite for clarity and correctness; adds references and examples. |
| docs/src/api/static_injection_subtypes.md | Fixes a typo in explanatory text. |
| docs/src/api/public.md | Updates autodocs page list (adds .jl suffix; removes dynamic_models.jl entry). |
| docs/src/api/glossary.md | Expands glossary navigation/entries (adds C/U sections and definitions). |
| docs/src/api/enumerated_types.md | Fixes multiple typos; updates enum tables (but introduces a mismatch vs code for a ThermalFuels entry; noted). |
| docs/make.jl | Updates docs navigation structure to include new how-to pages and new supplemental attributes explanation page. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+1
to
+4
| @echo off | ||
| cd /d "c:\Users\jstershi\Documents\GitHub\Sienna\PowerSystems.jl" | ||
| julia scripts\format_and_build_docs.jl | ||
| pause |
There was a problem hiding this comment.
This batch file hard-codes a developer-specific absolute path (and pauses), which will break for other contributors and CI environments. Suggest removing this file from the repo, or rewriting it to run from the repo root using relative paths (e.g., based on the script location) without user-specific directories.
Comment on lines
+1
to
+4
| include("scripts/formatter/formatter_code.jl") | ||
| using Pkg | ||
| Pkg.activate("docs") | ||
| include("docs/make.jl") |
There was a problem hiding this comment.
This script assumes it is executed from the repository root (relative includes/activation). To make it robust when run from any working directory (including CI), use paths based on @__DIR__ (e.g., joinpath(@__DIR__, "formatter", ...) and Pkg.activate(joinpath(@__DIR__, "..", "docs"))).
Comment on lines
+55
to
+57
| Abstract parametric type for all reserve products, parameterized on direction | ||
| `T <: `[`ReserveDirection`](@ref). | ||
|
|
There was a problem hiding this comment.
Docstring has a stray/back-to-back backtick around the type constraint: `T <: `[`ReserveDirection`](@ref). This will render incorrectly in the docs. Remove the extra backtick so it reads like T <: ReserveDirection (with an optional link to ReserveDirection).
| | `WOOD_WASTE_LIQUIDS` | WDL | Wood Waste Liquids excluding Black Liquor (includes red liquor, sludge wood, spent sulfite liquor, and other wood-based liquids) | | ||
| | `LANDFILL_GAS` | LFG | Landfill Gas | | ||
| | `OTHEHR_BIOMASS_GAS` | OBG | Other Biomass Gas (includes digester gas, methane, and other biomass gasses) | | ||
| | `OTHER_BIOMASS_GAS` | OBG | Other Biomass Gas (includes digester gas, methane, and other biomass gasses) | |
There was a problem hiding this comment.
The docs list the fuel enum value as OTHER_BIOMASS_GAS, but the actual enum in src/definitions.jl is spelled OTHEHR_BIOMASS_GAS. This mismatch will confuse users and example code will fail if they follow the docs. Either update the enum name in code (and provide a deprecation alias if needed) or keep the docs aligned with the current exported name.
Suggested change
| | `OTHER_BIOMASS_GAS` | OBG | Other Biomass Gas (includes digester gas, methane, and other biomass gasses) | | |
| | `OTHEHR_BIOMASS_GAS` | OBG | Other Biomass Gas (includes digester gas, methane, and other biomass gasses) | |
Contributor
There was a problem hiding this comment.
Update src/definitions.jl and any other uses and note the breaking change in PR comment
Comment on lines
+119
to
121
|
|
||
| ``` | ||
| ``` |
There was a problem hiding this comment.
The file ends with two standalone triple-backtick fences, which creates an empty code block and can break/alter Documenter rendering. These look accidental—remove the trailing fences (or replace with the intended markdown content).
Suggested change
| ``` | |
| ``` |
Comment on lines
+72
to
74
|
|
||
| ``` | ||
| ``` |
There was a problem hiding this comment.
The file ends with two standalone triple-backtick fences, which creates an empty code block and can break/alter Documenter rendering. These appear accidental—remove the trailing fences (or replace with the intended markdown content).
Suggested change
| ``` | |
| ``` |
kdayday
requested changes
Apr 20, 2026
Contributor
There was a problem hiding this comment.
Thanks for catching all these references and typos! Big picture comments:
- preference to replace
@replwith@example: code blocks can fail silently with@repl, but will fail the documentation build with@exampleso we can catch them (sorry, I just learned this) - I didn't review the explanation sections yet
- make sure PR's are clean of your local files (e.g., build.zip)
- avoid code changes in documentation PR's to keep the scope in (it looks like tests are all passing, but I don't want to change function signatures that could introduce breaking changes)
- Let's set up a quick meeting to touch base on priorities for docstrings
- merge main again, please mark things as resolved when done, and also address copilot suggestions
| "explanation/time_series.md", | ||
| "explanation/dynamic_data.md", | ||
| "explanation/supplemental_attributes.md", | ||
| "explanation/supplemental_attributes_2.md", |
Contributor
There was a problem hiding this comment.
Rename the new file back to supplemental_attributes.md
| | `WOOD_WASTE_LIQUIDS` | WDL | Wood Waste Liquids excluding Black Liquor (includes red liquor, sludge wood, spent sulfite liquor, and other wood-based liquids) | | ||
| | `LANDFILL_GAS` | LFG | Landfill Gas | | ||
| | `OTHEHR_BIOMASS_GAS` | OBG | Other Biomass Gas (includes digester gas, methane, and other biomass gasses) | | ||
| | `OTHER_BIOMASS_GAS` | OBG | Other Biomass Gas (includes digester gas, methane, and other biomass gasses) | |
Contributor
There was a problem hiding this comment.
Update src/definitions.jl and any other uses and note the breaking change in PR comment
Contributor
There was a problem hiding this comment.
revert all changes to function signatures
| interval = interval, | ||
| ) | ||
| put!(channel, time_series) | ||
| if isnothing(interval) || ( |
Contributor
There was a problem hiding this comment.
Where is this change from? revert?
| end | ||
|
|
||
| """ | ||
| Check the the consistency of subsystems. |
|
|
||
| IS.@scoped_enum(ACBusTypes, PQ = 1, PV = 2, REF = 3, ISOLATED = 4, SLACK = 5,) | ||
| @doc" | ||
| ACBusTypes |
Contributor
There was a problem hiding this comment.
These scoped enum docstrings are new (Great to have) and should be used to replace this old Page where we documented them before: https://nrel-sienna.github.io/PowerSystems.jl/stable/api/enumerated_types/ .
- each docstring has an unnecessary repetition of the type name at the top
- merge the tables from the enumerated type page into each docstring
- replace all @ref's the subsections of the enumerated types page (e.g.,
@ref pm_list) with the actual docstring (@ref PrimeMovers) - delete the old page
Contributor
There was a problem hiding this comment.
Where are these changes from?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Draft PR to address issues shown in #1504 and #1461 . Most changes occur from the supplemental attributes and system explanations. Spelling and cross reference issues were also addressed. While compiling the documentation a lot of the files were changed, but it's not clear what the change was.
One known issue still which is a figure not displaying. I will continue to work on this.
The contributing guidelines opened a link that did not work for me as well. Not sure if that is because I am a NLR employee or if the link is broken.