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.: '' |
vanmeerkerk
requested changes
Aug 21, 2026
vanmeerkerk
left a comment
vanmeerkerk
left a comment
Contributor
There was a problem hiding this comment.
Sam een paar opmerkingen.
| validating consistency across pages.: '' | ||
| argument-hint: Documentation goal, affected sections/pages, and scope constraints. | ||
| tools: [read, search, edit, execute/runInTerminal, web, agent] | ||
| tools: ['read', 'search', 'edit', 'execute/runInTerminal', 'web', 'agent', 'read_file', 'file_search', 'grep_search', 'insert_edit_into_file', 'replace_string_in_file', 'create_file', 'get_terminal_output', 'open_file', 'ask_questions', 'get_errors', 'list_dir', 'validate_cves', 'run_subagent', 'semantic_search', 'run_in_terminal'] |
Contributor
There was a problem hiding this comment.
These tools: 'read_file', 'file_search', 'grep_search', 'insert_edit_into_file', 'replace_string_in_file', 'create_file', 'get_terminal_output', 'open_file', 'ask_questions', 'get_errors', 'list_dir', 'validate_cves', 'run_subagent', 'semantic_search', 'run_in_terminal' are uknown on VS Code Copilot.
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.: '' |
|
|
||
| Limitations | ||
| ----------- | ||
| The absolute term keeps quantities that are near zero from blocking convergence, while the |
Contributor
There was a problem hiding this comment.
Algemene vraag zouden deze criteria niet uitgewerkt moeten worden in dimensieloze waarde? Zodat alle core quantities evenveel bijdragen aan de tolerance?
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. |
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.