Solver documentation#363
Open
samvanderzwan wants to merge 1 commit into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR restructures and refreshes the Solver documentation, shifting from older “conceptual + detailed behavior” pages to a concise four-page Solver section (overview, workflow, unknowns, convergence) and updates the documentation-agent guidance to match that new ownership model.
Changes:
- Rewrites the Solver conceptual pages to a shorter, cross-linked set:
solver_main,solver_workflow,solver_unknowns, andsolver_convergence. - Adds a new dedicated “Solved Unknowns” page and removes the deprecated “unknowns and equations” and “solver behavior” pages.
- Updates documentation agent metadata/instructions to reflect the new Solver documentation structure and responsibilities.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| doc/solver/solver_workflow.rst | Rewritten workflow explanation of the solver iteration loop and references to related pages. |
| doc/solver/solver_unknowns.rst | New page documenting the solved unknowns (p, ṁ, u) and related interpretation notes. |
| doc/solver/solver_unknowns_and_equations.rst | Removed legacy page in favor of the new unknowns page. |
| doc/solver/solver_main.rst | Updated landing page with toctree pointing to the new three sibling pages. |
| doc/solver/solver_convergence.rst | Rewritten convergence criteria page with explicit tolerance definition. |
| doc/solver/solver_behavior.rst | Removed; detailed content folded into the four-page Solver section approach. |
| .github/agents/SystemConceptDocAgent.agent.md | Updates agent scope guidance to point Solver content to SolverBehaviorDocAgent. |
| .github/agents/SolverBehaviorDocAgent.agent.md | Redefines this agent’s scope to own the full four-page Solver section. |
| .github/agents/DocumentationCoordinator.agent.md | Updates solver-doc routing guidance; also modifies YAML front matter/tooling metadata. |
| .github/agents/APIReferenceAgent.agent.md | Updates exclusions to reflect the new four-page Solver section ownership. |
Comment on lines
+9
to
+12
| The solver reaches the network state through a fixed-point Newton-Raphson iteration: it | ||
| repeatedly assembles a linear system from the current solution, solves it, transfers the | ||
| result back to the assets and nodes, and tests whether the solution has stopped changing. | ||
| The loop stops when the solution has converged or when an iteration limit is reached. |
Comment on lines
+22
to
+24
| **Assemble.** Each asset and then each node contributes its equations, linearized about the | ||
| current solution, into a single system. The number of equations always matches the number of | ||
| unknowns, so the linear system is square and solvable. |
Comment on lines
+37
to
+38
| **Iteration limit.** The loop is capped at 100 iterations. If convergence is not reached | ||
| within that limit, a warning is logged and the last computed iterate is used as the result. |
Comment on lines
+36
to
+41
| Specific internal energy is used as the thermal state variable rather than temperature | ||
| directly. This keeps the energy-transport terms linear in the solved unknowns: convective | ||
| energy transport appears as the product of mass flow and specific internal energy, both of | ||
| which are solved quantities. Temperature is recovered from the specific internal energy | ||
| through the fluid-property relations; those relations are not re-derived here (see | ||
| :doc:`../physics/physics_main`). |
Comment on lines
+3
to
+6
| description: '>-' | ||
| Coordinate documentation work for SIMULATOR-CORE by classifying requests,: '' | ||
| enforcing the documentation structure, delegating to specialist agents, and: '' | ||
| validating consistency across pages.: '' |
Comment on lines
+23
to
+25
| prompt: '>-' | ||
| Review the page(s) just authored for audience fit, section fit, scope: '' | ||
| correctness, duplication, and cross-link quality.: '' |
Comment on lines
+29
to
+31
| prompt: '>-' | ||
| Validate that the documentation build is clean (toctrees, autodoc: '' | ||
| resolution, rst syntax) for the page(s) just authored/reviewed.: '' |
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.
No description provided.