Update to psy5 and document package

.claude/Sienna.md

@@ -0,0 +1,165 @@
+# Sienna Programming Practices
+
+This document describes general programming practices and conventions that apply across all Sienna packages (PowerSystems.jl, PowerSimulations.jl, PowerFlows.jl, PowerNetworkMatrices.jl, InfrastructureSystems.jl, etc.).
+
+## Performance Requirements
+
+**Priority:** Critical. See the [Julia Performance Tips](https://docs.julialang.org/en/v1/manual/performance-tips/).
+
+### Anti-Patterns to Avoid
+
+#### Type instability
+
+Functions must return consistent concrete types. Check with `@code_warntype`.
+
+- Bad: `f(x) = x > 0 ? 1 : 1.0`
+- Good: `f(x) = x > 0 ? 1.0 : 1.0`
+
+#### Abstract field types
+
+Struct fields must have concrete types or be parameterized.
+
+- Bad: `struct Foo; data::AbstractVector; end`
+- Good: `struct Foo{T<:AbstractVector}; data::T; end`
+
+#### Untyped containers
+
+- Bad: `Vector{Any}()`, `Vector{Real}()`
+- Good: `Vector{Float64}()`, `Vector{Int}()`
+
+#### Non-const globals
+
+- Bad: `THRESHOLD = 0.5`
+- Good: `const THRESHOLD = 0.5`
+
+#### Unnecessary allocations
+
+- Use views instead of copies (`@view`, `@views`)
+- Pre-allocate arrays instead of `push!` in loops
+- Use in-place operations (functions ending with `!`)
+
+#### Captured variables
+
+Avoid closures that capture variables causing boxing. Pass variables as function arguments instead.
+
+#### Splatting penalty
+
+Avoid splatting (`...`) in performance-critical code.
+
+#### Abstract return types
+
+Avoid returning `Union` types or abstract types.
+
+### Best Practices
+
+- Use `@inbounds` when bounds are verified
+- Use broadcasting (dot syntax) for element-wise operations
+- Avoid `try-catch` in hot paths
+- Use function barriers to isolate type instability
+
+> Apply these guidelines with judgment. Not every function is performance-critical. Focus optimization efforts on hot paths and frequently called code.
+
+## Code Conventions
+
+Style guide: <https://nrel-sienna.github.io/InfrastructureSystems.jl/stable/style/>
+
+Formatter (JuliaFormatter): Use the formatter script provided in each package.
+
+Key rules:
+
+- Constructors: use `function Foo()` not `Foo() = ...`
+- Asserts: prefer `InfrastructureSystems.@assert_op` over `@assert`
+- Globals: `UPPER_CASE` for constants
+- Exports: all exports in main module file
+- Comments: complete sentences, describe why not how
+
+## Documentation Practices and Requirements
+
+Framework: [Diataxis](https://diataxis.fr/)
+
+Sienna guide: <https://nrel-sienna.github.io/InfrastructureSystems.jl/stable/docs_best_practices/explanation/>
+
+Sienna guide for Diataxis-style tutorials: <https://nrel-sienna.github.io/InfrastructureSystems.jl/stable/docs_best_practices/how-to/write_a_tutorial/>
+Format for tutorial scripts: <https://fredrikekre.github.io/Literate.jl/v2/>
+Sienna guide for Diataxis-style how-to's: <https://nrel-sienna.github.io/InfrastructureSystems.jl/stable/docs_best_practices/how-to/write_a_how-to/>
+Sienna guide for APIs: <https://nrel-sienna.github.io/InfrastructureSystems.jl/stable/docs_best_practices/how-to/write_docstrings_org_api/>
+
+Docstring requirements:
+
+- Scope: all elements of public interface (IS is selective about exports)
+- Include: function signatures and arguments list
+- Automation: `DocStringExtensions.TYPEDSIGNATURES` (`TYPEDFIELDS` used sparingly in IS)
+- See also: add links for functions with same name (multiple dispatch)
+
+API docs:
+
+- Public: typically in `docs/src/api/public.md` using `@autodocs` with `Public=true, Private=false`
+- Internals: typically in `docs/src/api/internals.md`
+
+## Design Principles
+
+- Elegance and concision in both interface and implementation
+- Fail fast with actionable error messages rather than hiding problems
+- Validate invariants explicitly in subtle cases
+- Avoid over-adherence to backwards compatibility for internal helpers
+
+## Contribution Workflow
+
+**Note:** The default branch for all Sienna packages is `main`, not `master`.
+
+Branch naming: `feature/description` or `fix/description`
+
+1. Create feature branch
+2. Follow style guide and run formatter
+3. Ensure tests pass
+4. Submit pull request
+
+## AI Agent Guidance
+
+**Key priorities:** Read existing patterns first, maintain consistency, use concrete types in hot paths, run formatter, add docstrings to public API, ensure tests pass.
+
+**Critical rules:**
+- Always use `julia --project=<env>` (never bare `julia`)
+- Never edit auto-generated files directly
+- Verify type stability with `@code_warntype` for performance-critical code
+- Consider downstream package impact
+
+## Julia Environment Best Practices
+
+**CRITICAL:** Always use `julia --project=<env>` when running Julia code in Sienna repositories. **NEVER** use bare `julia` or `julia --project` without specifying the environment. Each package typically defines dependencies in `test/Project.toml` for testing.
+
+Common patterns:
+
+```sh
+# Run tests (using test environment)
+julia --project=test test/runtests.jl
+
+# Run specific test
+julia --project=test test/runtests.jl test_file_name
+
+# Run expression
+julia --project=test -e 'using PackageName; ...'
+
+# Instantiate environment
+julia --project=test -e 'using Pkg; Pkg.instantiate()'
+
+# Build docs (using docs environment)
+julia --project=docs docs/make.jl
+```
+
+**Why this matters:** Running without `--project=<env>` will fail because required packages won't be available in the default environment. The test/docs environments contain all necessary dependencies for their respective tasks.
+
+## Troubleshooting
+
+**Type instability**
+- Symptom: Poor performance, many allocations
+- Diagnosis: `@code_warntype` on suspect function
+- Solution: See performance anti-patterns above
+
+**Formatter fails**
+- Symptom: Formatter command returns error
+- Solution: Run the formatter script provided in the package (e.g., `julia -e 'include("scripts/formatter/formatter_code.jl")'`)
+
+**Test failures**
+- Symptom: Tests fail unexpectedly
+- Solution: `julia --project=test -e 'using Pkg; Pkg.instantiate()'`

.github/workflows/doc-preview-cleanup.yml

@@ -0,0 +1,34 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+# Ensure that only one "Doc Preview Cleanup" workflow is force pushing at a time
+concurrency:
+  group: doc-preview-cleanup
+  cancel-in-progress: false
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    # This workflow pushes to gh-pages; permissions are per-job and independent of docs.yml
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+          if [ -d "${preview_dir}" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "documenter@juliadocs.github.io"
+              git rm -rf "${preview_dir}"
+              git commit -m "delete preview"
+              git branch gh-pages-new "$(echo "delete history" | git commit-tree "HEAD^{tree}")"
+              git push --force origin gh-pages-new:gh-pages
+          fi
+        env:
+          preview_dir: previews/PR${{ github.event.number }}

CONTRIBUTING.md

@@ -1,6 +1,7 @@
 # Contributing
 
 Community driven development of this package is encouraged. To maintain code quality standards, please adhere to the following guidlines when contributing:
- - To get started, <a href="https://www.clahub.com/agreements/NREL/SIIP-PACKAGE.jl">sign the Contributor License Agreement</a>.
- - Please do your best to adhere to our [coding style guide](docs/src/developer/style.md).
- - To submit code contributions, [fork](https://help.github.com/articles/fork-a-repo/) the repository, commit your changes, and [submit a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/).
+
+  - To get started, <a href="https://www.clahub.com/agreements/NREL/SIIP-PACKAGE.jl">sign the Contributor License Agreement</a>.
+  - Please do your best to adhere to our [coding style guide](docs/src/developer/style.md).
+  - To submit code contributions, [fork](https://help.github.com/articles/fork-a-repo/) the repository, commit your changes, and [submit a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/).

Project.toml

@@ -13,10 +13,10 @@ PowerSimulations = "e690365d-45e2-57bb-ac84-44ba829e73c4"
 PowerSystems = "bcd98974-b02a-5e2f-9ee0-a103f5c450dd"
 
 [compat]
-DataStructures = "~0.18"
-DocStringExtensions = "~0.8, ~0.9"
-JuMP = "1"
+DataStructures = "~0.18, ^0.19"
+DocStringExtensions = "0.8, 0.9.2"
+JuMP = "^1.28"
 MathOptInterface = "1"
-PowerSimulations = "^0.29"
-PowerSystems = "4"
-julia = "^1.6"
+PowerSimulations = "^0.33"
+PowerSystems = "5.5"
+julia = "^1.10"

docs/Project.toml

@@ -1,9 +1,13 @@
 [deps]
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
 HybridSystemsSimulations = "bed98974-b02a-5e2f-9ee0-a103f5c450dd"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d"
 
 [compat]
-Documenter = "0.27"
+Documenter = "1.0"
 julia = "^1.6"

docs/make.jl

@@ -1,31 +1,49 @@
-using Documenter, HybridSystemsSimulations
-import DataStructures: OrderedDict
+using Documenter
+using HybridSystemsSimulations
+using DataStructures
+using DocumenterInterLinks
+using Literate
+
+const _DOCS_BASE_URL = "https://nrel-sienna.github.io/HybridSystemsSimulations.jl/stable"
+
+links = InterLinks(
+    "Julia" => "https://docs.julialang.org/en/v1/",
+    "InfrastructureSystems" => "https://nrel-sienna.github.io/InfrastructureSystems.jl/stable/",
+    "PowerSystems" => "https://nrel-sienna.github.io/PowerSystems.jl/stable/",
+    "PowerSimulations" => "https://nrel-sienna.github.io/PowerSimulations.jl/stable/",
+)
+
+include(joinpath(@__DIR__, "make_tutorials.jl"))
+make_tutorials()
 
 pages = OrderedDict(
     "Welcome Page" => "index.md",
-    "Quick Start Guide" => "quick_start_guide.md",
-    "Tutorials" => "tutorials/intro_page.md",
-    "Public API Reference" => "api/public.md",
-    "Internal API Reference" => "api/internal.md",
+    "Tutorials" => Any[],
+    "Reference" => Any[
+        "Public API" => "api/public.md",
+        "Internals" => "api/internal.md",
+    ],
 )
 
-makedocs(
-    modules=[HybridSystemsSimulations],
-    format=Documenter.HTML(;
-        mathengine=Documenter.MathJax(),
-        prettyurls=haskey(ENV, "GITHUB_ACTIONS"),
+makedocs(;
+    modules = [HybridSystemsSimulations],
+    format = Documenter.HTML(;
+        mathengine = Documenter.MathJax(),
+        prettyurls = haskey(ENV, "GITHUB_ACTIONS"),
+        size_threshold = nothing,
     ),
-    sitename="HybridSystemsSimulations.jl",
-    authors="Jose Daniel Lara, Rodrigo Henriquez-Auba",
-    pages=Any[p for p in pages],
+    sitename = "HybridSystemsSimulations.jl",
+    authors = "Jose Daniel Lara, Rodrigo Henriquez-Auba",
+    pages = Any[p for p in pages],
+    plugins = [links],
 )
 
-deploydocs(
-    repo="github.com/NREL-Sienna/HybridSystemsSimulations.jl.git",
-    target="build",
-    branch="gh-pages",
-    devbranch="main",
-    devurl="dev",
-    push_preview=true,
-    versions=["stable" => "v^", "v#.#"],
+deploydocs(;
+    repo = "github.com/NREL-Sienna/HybridSystemsSimulations.jl.git",
+    target = "build",
+    branch = "gh-pages",
+    devbranch = "main",
+    devurl = "dev",
+    push_preview = true,
+    versions = ["stable" => "v^", "v#.#"],
 )