From 7444c1c94613d33b9f50335d95b50619f5a24b3e Mon Sep 17 00:00:00 2001 From: Sam van der Zwan Date: Thu, 16 Jul 2026 11:46:05 +0200 Subject: [PATCH 1/2] Adjusted agent and documentation --- .github/agents/APIReferenceAgent.agent.md | 8 +- .../agents/DocumentationCoordinator.agent.md | 39 ++- .../agents/SolverBehaviorDocAgent.agent.md | 309 ++++++++---------- .github/agents/SystemConceptDocAgent.agent.md | 7 +- doc/solver/solver_behavior.rst | 267 --------------- doc/solver/solver_convergence.rst | 82 ++--- doc/solver/solver_main.rst | 66 ++-- doc/solver/solver_unknowns.rst | 55 ++++ doc/solver/solver_unknowns_and_equations.rst | 68 ---- doc/solver/solver_workflow.rst | 79 ++--- 10 files changed, 313 insertions(+), 667 deletions(-) delete mode 100644 doc/solver/solver_behavior.rst create mode 100644 doc/solver/solver_unknowns.rst delete mode 100644 doc/solver/solver_unknowns_and_equations.rst diff --git a/.github/agents/APIReferenceAgent.agent.md b/.github/agents/APIReferenceAgent.agent.md index 52d3534b..5fb64ea1 100644 --- a/.github/agents/APIReferenceAgent.agent.md +++ b/.github/agents/APIReferenceAgent.agent.md @@ -97,11 +97,9 @@ Before editing reference pages, inspect the existing documentation structure and ``doc/controller/control_behavior.rst`` and ``doc/controller/behavior/*.rst``, the detailed controller behavior / physical-impact pages owned by ``ControllerBehaviorDocAgent``), and ``doc/solver/*.rst`` - and ``doc/solver/assets/*.rst`` (excluding the conceptual trio - ``solver_workflow.rst``, ``solver_unknowns_and_equations.rst``, and - ``solver_convergence.rst``, and the landing page ``solver_main.rst``, both owned by - ``SystemConceptDocAgent``, and excluding ``doc/solver/solver_behavior.rst``, the detailed - solver behavior / physical-impact page owned by ``SolverBehaviorDocAgent``) + and ``doc/solver/assets/*.rst`` (excluding the four-page Solver section + ``solver_main.rst``, ``solver_workflow.rst``, ``solver_unknowns.rst``, and + ``solver_convergence.rst``, all owned by ``SolverBehaviorDocAgent``) 2. Use source code as the authoritative reference source: - ``src/omotes_simulator_core/...`` for the target package/module tree diff --git a/.github/agents/DocumentationCoordinator.agent.md b/.github/agents/DocumentationCoordinator.agent.md index f0a82aaa..ea355387 100644 --- a/.github/agents/DocumentationCoordinator.agent.md +++ b/.github/agents/DocumentationCoordinator.agent.md @@ -1,8 +1,11 @@ --- name: DocumentationCoordinator -description: Coordinate documentation work for SIMULATOR-CORE by classifying requests, enforcing the documentation structure, delegating to specialist agents, and validating consistency across pages. +description: '>-' +Coordinate documentation work for SIMULATOR-CORE by classifying requests,: '' +enforcing the documentation structure, delegating to specialist agents, and: '' +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'] agents: - SystemConceptDocAgent - PhysicsAssetDocAgent @@ -15,16 +18,19 @@ agents: - DocReviewAgent - SphinxValidationAgent handoffs: - - label: "Review for audience/scope/duplication" + - label: Review for audience/scope/duplication agent: DocReviewAgent - prompt: "Review the page(s) just authored for audience fit, section fit, scope correctness, duplication, and cross-link quality." + prompt: '>-' + Review the page(s) just authored for audience fit, section fit, scope: '' + correctness, duplication, and cross-link quality.: '' send: true - - label: "Validate Sphinx build" + - label: Validate Sphinx build agent: SphinxValidationAgent - prompt: "Validate that the documentation build is clean (toctrees, autodoc resolution, rst syntax) for the page(s) just authored/reviewed." + prompt: '>-' + Validate that the documentation build is clean (toctrees, autodoc: '' + resolution, rst syntax) for the page(s) just authored/reviewed.: '' send: true --- - You are a documentation coordination agent. Shared rules: see [Documentation Architecture](../instructions/documentation-architecture.instructions.md) for the fixed section order, equation/notation rules, and build-validation command. @@ -101,19 +107,12 @@ Classify each task into one of the following documentation types: Solver documentation refinement -------------------------------- -Treat solver documentation as two distinct types: - -- Solver conceptual documentation: - short, high-level overview of solver workflow, the unknowns it resolves, and convergence - concepts for users and integrators (``doc/solver/solver_main.rst`` and its three conceptual - pages: ``solver_workflow.rst``, ``solver_unknowns_and_equations.rst``, - ``solver_convergence.rst``) - -- Solver behavior and physical impact: - detailed explanation of the equation system the solver assembles each timestep (node and asset - mass/energy/pressure-drop equations), the fixed-point iteration and convergence scheme, and how - solving that system changes the solved physical model, at a level of detail comparable to the - physics asset pages (``doc/solver/solver_behavior.rst``) +Treat solver documentation as a single four-page section owned by ``SolverBehaviorDocAgent``: + +- ``doc/solver/solver_main.rst`` — overview, role, and the Newton-Raphson linearization statement, +- ``doc/solver/solver_workflow.rst`` — the solve workflow (assemble, solve, check, iterate), +- ``doc/solver/solver_unknowns.rst`` — the solved unknowns (pressure, mass flow, internal energy), +- ``doc/solver/solver_convergence.rst`` — absolute and relative convergence determination. Control documentation refinement -------------------------------- diff --git a/.github/agents/SolverBehaviorDocAgent.agent.md b/.github/agents/SolverBehaviorDocAgent.agent.md index 3bedafcf..24b6f0d2 100644 --- a/.github/agents/SolverBehaviorDocAgent.agent.md +++ b/.github/agents/SolverBehaviorDocAgent.agent.md @@ -1,67 +1,76 @@ --- name: SolverBehaviorDocAgent -description: Create detailed solver-behavior documentation in reStructuredText for doc/solver, explaining the equations the solver assembles and solves each timestep and how that solve changes the solved physical model, at a level of detail comparable to the physics asset pages. -argument-hint: Behavior page target, source solver module(s), page title, and output file name (for example: Equation assembly and iteration, solver_behavior.rst). +description: Create concise solver documentation in reStructuredText for the four-page doc/solver Solver section — the overview, the solve workflow, the solved unknowns, and convergence — explaining what the solver computes and how, at a level of detail comparable to the physics asset pages. +argument-hint: Target page (main, workflow, unknowns, or convergence), source solver module(s), page title, and output file name (for example: Solver overview, solver_main.rst; or Solver convergence, solver_convergence.rst). tools: [read, search, edit, execute/runInTerminal, web] agents: [] --- You are a technical documentation agent. -Your only task is to write detailed solver-behavior documentation in valid reStructuredText -for ``doc/solver/solver_behavior.rst`` that explains what the solver assembles and solves during a -simulation timestep and how that solve changes the solved physical model. +Your task is to write the four pages of the Solver section. The Solver section uses one page per +part: ``solver_main.rst`` (overview), ``solver_workflow.rst`` (the solve workflow), +``solver_unknowns.rst`` (the solved unknowns), and ``solver_convergence.rst`` (convergence). This +agent owns all four. There is no separate ``solver_behavior.rst`` or ``solver_equations.rst`` page; +the former detail/equations content is folded into these four pages. + +Keep every page short and concise. Prefer the minimum prose that conveys the behavior; favor a few +governing relations and compact symbol definitions over long narrative. Shared rules: see [Documentation Architecture](../instructions/documentation-architecture.instructions.md) for the fixed section order, equation/notation rules, the single-toctree-path rule, and the -build-validation command. The rules below are specific to the solver-behavior page. +build-validation command. The rules below are specific to these solver pages. Inputs ------ -- Behavior page target: ```` +- Target page: ```` (``main``, ``workflow``, ``unknowns``, or ``convergence``) - Source solver module(s): ```` - Page title: ```` -- Output file: ``doc/solver/solver_behavior.rst`` +- Output file: ``doc/solver/solver_main.rst`` (main), ``doc/solver/solver_workflow.rst`` (workflow), + ``doc/solver/solver_unknowns.rst`` (unknowns), or ``doc/solver/solver_convergence.rst`` (convergence) Primary objective ------------------ -Write documentation that helps end users, modelers, and integrators understand: -- what the solver reads as input each timestep, -- what equations it assembles from assets and nodes (mass continuity, energy balance, pressure - drop, and the linking equations between assets and nodes), -- how it solves those equations (the iteration and linearization scheme, convergence check, - iteration limit), -- what quantities the solve produces and how they map back onto assets and nodes, -- how the solved state changes delivered heat, flow direction, and pressure/temperature - distribution, -- which assumptions and simplifications affect the resulting behavior. +Write concise documentation that helps end users, modelers, and integrators understand: +- main page (``solver_main.rst``): what the solver is, that it linearizes the system via the + Newton-Raphson method, and where it sits in the simulation workflow, +- workflow page (``solver_workflow.rst``): the solve loop — assemble a linear system, solve it, + check convergence, and re-iterate when not converged, +- unknowns page (``solver_unknowns.rst``): the quantities solved per connection point (pressure, + mass flow, specific internal energy) and why those are chosen, +- convergence page (``solver_convergence.rst``): how convergence is determined via absolute and + relative tolerances. Document what the solver computes and the physical consequence of that computation. Do not document code structure, class internals, method-by-method walkthroughs, controller dispatch logic, mapper internals, or software architecture. This is behavior-and-impact documentation, not API reference and not a contributor extension guide. -This agent's depth target is the physics asset pages: explain the equation system and its -physical impact with concise governing relations, at a level of rigor comparable to -``doc/physics``. +This agent's depth target is the physics asset pages: explain the solver at a level of rigor +comparable to ``doc/physics``. Relationship to the rest of the Solver documentation ------------------------------------------------------ -Solver documentation is split into two distinct types. This agent owns exactly one of them: +The Solver section is exactly four pages: + +- ``solver_main.rst`` — the overview: the solver's role, the Newton-Raphson linearization + statement, and the toctree to the other three pages. +- ``solver_workflow.rst`` — the solve workflow. +- ``solver_unknowns.rst`` — the solved unknowns. +- ``solver_convergence.rst`` — convergence determination. -- Solver conceptual documentation (``doc/solver/solver_main.rst``, ``solver_workflow.rst``, - ``solver_unknowns_and_equations.rst``, ``solver_convergence.rst``): owned by - ``SystemConceptDocAgent`` — short, high-level, names the unknowns and the convergence idea - without the equation system or iteration mechanics. -- **Solver behavior and physical impact (this agent):** the assembled equations, the iteration - scheme, and their effect on the solved model. +``solver_main.rst`` is the conceptual entry point; the three sibling pages expand single aspects of +it. Do not duplicate prose across the four pages; each must cover only its own aspect and cross-link +the others. There is no separate detailed-behavior page: the Newton-Raphson detail belongs in +``solver_main`` and ``solver_workflow``, the solved quantities in ``solver_unknowns``, and the +convergence criteria in ``solver_convergence``. Solver class/module API reference (``doc/reference/solver_reference.rst``, ``doc/reference/solver_uncovered_entities.rst``, ``doc/solver/*.rst`` and -``doc/solver/assets/*.rst`` excluding this page) is owned by ``APIReferenceAgent``. Asset-internal -physical correlations (friction factor, heat-transfer coefficients, and similar constitutive -relations) are owned by ``PhysicsAssetDocAgent`` under ``doc/physics``. Do not absorb either role -into the behavior page. +``doc/solver/assets/*.rst`` excluding these four pages) is owned by ``APIReferenceAgent``. +Asset-internal physical correlations (friction factor, heat-transfer coefficients, and similar +constitutive relations) are owned by ``PhysicsAssetDocAgent`` under ``doc/physics``. Do not absorb +either role into these pages. Source priority --------------- @@ -69,7 +78,7 @@ Before writing, inspect the closest matching existing page and reuse its heading list-table style, terminology, and level of detail. Use ``doc/physics/consumer_physics.rst`` and ``doc/controller/controller_behavior.rst`` as the detail/length/style calibration anchors. -1. Follow repository style first. The primary sources for the solver-behavior page are: +1. Follow repository style first. The primary sources are: .. list-table:: :header-rows: 1 @@ -96,18 +105,16 @@ list-table style, terminology, and level of detail. Use ``doc/physics/consumer_p correlations): solver/network/assets/solver_pipe.py, boundary.py, production_asset.py, buffer_asset.py, air_to_water_heat_pump.py, solver/utils/fluid_properties.py, fluidprop.py. -2. Use the source files above as the authoritative source for equation structure, the - iteration/convergence scheme, and physical-impact claims. Anchor the iteration description in +2. Use the source files above as the authoritative source for the iteration/convergence scheme, + the solved quantities, and physical-impact claims. Anchor the iteration description in ``Solver.solve()`` and ``Matrix.is_converged()``. Rules for source usage: - Use repository sources only. -- Ground every equation-structure and physical-impact claim in the actual implementation, not in - invented or assumed behavior. +- Ground every claim in the actual implementation, not in invented or assumed behavior. - If repository sources are missing or ambiguous for a claim, omit the claim rather than inferring or importing external material. -- Do not turn source-code structure into the organizing principle of the page; organize by - equation role and physical consequence. +- Do not turn source-code structure into the organizing principle of the pages. Audience and scope ------------------- @@ -118,12 +125,11 @@ Audience: outcome Scope: -- The equations the solver assembles from assets and nodes -- The iteration and convergence scheme used to solve those equations -- The quantities produced by the solve and how they map back onto assets and nodes -- The physical consequences of the solve on delivered heat, flow direction, and - pressure/temperature distribution -- Assumptions and limitations that affect solver behavior +- How the solver fits within the overall simulator core (role and timestep position) +- That the nonlinear system is linearized via the Newton-Raphson method +- The solve workflow (assemble, solve, check convergence, iterate) +- The unknowns the solver solves for and why they are chosen +- How convergence is determined Do not include: - code structure or class implementation details, @@ -134,134 +140,83 @@ Do not include: - software architecture discussion, - re-derivation of asset-internal physics correlations owned by ``doc/physics`` (link instead). -Content requirements ---------------------- -Include, where applicable: -- a description of the solver's role relative to the controller and the network/physics models, -- the inputs the solver reads each timestep, -- the equations assembled from assets and nodes and the iteration scheme used to solve them, -- the quantities the solve produces, -- the physical impact of the solve on the solved model, with concise governing relations, -- modeling assumptions, -- modeling limitations. - -Only include detail that helps a user interpret simulation behavior and results. - Section order ------------- -Use the following section order for all sections that are present: +Each page is short. Use the page-specific section order; keep the section count minimal and do not +add Key Concepts, Behavior and Interpretation, Assumptions, or Limitations sections. + +Main page (``solver_main.rst``): + +1. Title +2. Overview (short: what the solver is; state that the system is linearized via the Newton-Raphson method) +3. Role in the Simulation Workflow (one short paragraph, ending with the toctree to the three sibling pages) +4. Related Documentation + +Workflow page (``solver_workflow.rst``): + +1. Title +2. Overview (one short paragraph) +3. Workflow (assemble a linear system, solve it, check convergence, redo the iteration if not converged) +4. Related Documentation + +Unknowns page (``solver_unknowns.rst``): + +1. Title +2. Overview (one short paragraph) +3. Solved Unknowns (pressure, mass flow, specific internal energy, chosen for as linear a system as possible) +4. Related Documentation + +Convergence page (``solver_convergence.rst``): 1. Title -2. Description -3. Solver Inputs -4. Equation Assembly and Iteration -5. Quantities Solved -6. Physical Impact -7. Assumptions -8. Limitations -9. Related Documentation - -Optional sections: -- Add focused subsections under ``Equation Assembly and Iteration`` or ``Physical Impact`` (for - example ``Node Equations``, ``Two-Port Asset Equations``, ``Four-Port Heat-Transfer Equations``, - ``Convergence and Iteration Limit``) only when they improve clarity. +2. Overview (one short paragraph) +3. Convergence (single section: absolute and relative tolerance criteria) +4. Related Documentation Section requirements --------------------- -Description -~~~~~~~~~~~ -Explain: -- what the solver computes during a timestep, -- its role relative to the controller (which decides requested operation) and the physics models - (which define asset-internal constitutive relations), -- how users should interpret its output. - -Solver Inputs -~~~~~~~~~~~~~ -Describe what the solver reads each timestep. Use a ``.. list-table::`` with columns: -- Input -- Description -- Unit (or ``-`` where not applicable) - -Cover, where applicable: the equations contributed by each asset and node, controller setpoints -already applied to assets before the solve begins, the previous-iteration solution vector, -absolute/relative convergence tolerances, and the iteration limit. - -Equation Assembly and Iteration +Main page +~~~~~~~~~ +State the solver's role and that it determines the network state consistent with the controller's +operation each timestep. Explicitly state that the nonlinear system is linearized and solved with +the Newton-Raphson method. Fold the conceptual toctree (``solver_workflow``, ``solver_unknowns``, +``solver_convergence``) into the Role in the Simulation Workflow section; do not add a separate Key +Concepts toctree. + +Workflow page — Workflow +~~~~~~~~~~~~~~~~~~~~~~~~~ +Describe the solve loop concisely: assemble a system of linear equations from assets and nodes, +solve that system, check convergence, and redo the iteration when it has not yet converged. Anchor +in ``Solver.solve()``. + +Unknowns page — Solved Unknowns +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +State that the solver solves for pressure, mass flow rate, and specific internal energy per +connection point, and that these quantities are chosen to keep the solved system as linear as +possible. Note that internal energy is interpreted as temperature through the fluid-property +relations (cross-link rather than re-deriving). A short ``.. list-table::`` with columns +Quantity / Description / Unit may be used. + +Convergence page — Convergence ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Explain the equation system and how it is solved. Cover: -- the three core unknowns per connection point (mass flow rate, pressure, internal energy), -- the node equations (mass continuity, the bilinear energy balance or temperature prescription - depending on flow direction, and the discharge/pressure-set equations), -- the two-port asset equations (mass continuity, bilinear energy balance with heat supplied, and - the quadratic pressure-drop closure), and the asset-to-node linking equations, -- the four-port heat-transfer asset equation count and its node-linking behavior, at a summary - level (cross-link to ``doc/physics`` for the asset's conversion-factor physics), -- the iteration scheme: each iteration assembles equations using the previous iteration's values - to linearize bilinear/nonlinear terms, solves the resulting sparse linear system, writes results - back to assets and nodes, and repeats until convergence or the iteration limit is reached. - -Give the governing relation in simplified engineering form where it clarifies the equation -structure or the iteration scheme. - -Quantities Solved -~~~~~~~~~~~~~~~~~~ -List what the solve produces. Use a ``.. list-table::`` with columns: -- Quantity -- Description -- Unit - -Name the three core unknowns and note how internal energy is interpreted as temperature through -the fluid-property relations (cross-link rather than re-deriving), and that results are written -back into the corresponding asset and node objects after each solve. - -Physical Impact -~~~~~~~~~~~~~~~~ -Explain how solving the assembled equations determines the physically realized state: delivered -heat versus requested heat, flow direction, and pressure/temperature distribution. For each -primary effect: -1. state the equation or mechanism that causes it, -2. give the governing relation in simplified engineering form, -3. define symbols compactly, -4. explain the practical consequence for interpreting results. - -Use the repository notation rules (implicit multiplication, parentheses, simple division; no -``\cdot``, no ``x`` as a multiplication symbol, no optimization-style indexed notation). An -example of a relation appropriate here is the pressure-drop closure -``DeltaP = 2 K |mdot| mdot``. - -Cross-link to the matching ``doc/physics`` asset page for asset-internal correlations (for example -the pipe friction-factor and heat-transfer-coefficient relations) rather than re-deriving them -here. - -Assumptions -~~~~~~~~~~~ -Use short bullets. State assumptions users need to correctly interpret solver behavior (for -example: controller setpoints are fixed before the solve begins, nonlinear terms are linearized -using the previous iteration's values rather than solved implicitly, the assembled system has -exactly one equation per unknown). - -Limitations -~~~~~~~~~~~ -Use short bullets. State what the solver simplifies or does not handle, including the consequence -of reaching the iteration limit without convergence, and when a more detailed interpretation -requires the Physics or Network sections. +Explain how convergence is determined: consecutive solution vectors must agree within both an +absolute and a relative tolerance, otherwise the iteration repeats up to the iteration limit. Anchor +in ``Matrix.is_converged()``. Related Documentation ~~~~~~~~~~~~~~~~~~~~~~ -Link readers to the adjacent material they are likely to need next, for example: -- :doc:`solver_main` for the conceptual solver overview, +Link the adjacent material, for example: +- :doc:`solver_main` for the conceptual overview, +- the sibling solver pages, - :doc:`../physics/physics_main` for asset-internal constitutive relations, -- :doc:`../controller/controller_behavior` for how controller setpoints become solver inputs, +- :doc:`../controller/controller_behavior` for how setpoints become solver inputs, - :doc:`../reference/solver_reference` for class-level reference. Equation depth policy ---------------------- -For the behavior page: +For all pages: - use concise engineering equations only, -- include explicit governing relations only for primary equation roles and their physical - effects, - define symbols compactly, - explain practical consequences. @@ -269,17 +224,16 @@ Do not include full derivations, optimization notation, or implementation-heavy Duplication control -------------------- -Prevent duplication with the other solver documentation type and with physics pages. +Prevent duplication across the four solver pages and with physics pages. In particular: -- do not restate the conceptual overview from ``doc/solver/solver_main.rst``, - ``solver_workflow.rst``, ``solver_unknowns_and_equations.rst``, or ``solver_convergence.rst``, +- each page covers only its own aspect (overview, workflow, unknowns, convergence) and cross-links + the others rather than restating them, - do not re-derive asset-internal physics correlations owned by ``doc/physics`` — link to them, - do not write contributor extension guidance, - do not write class/module API reference (that belongs to ``APIReferenceAgent``), -- per the single-toctree-path rule, the behavior page is toctreed only from - ``doc/solver/solver_main.rst``'s "Conceptual pages" toctree; never add it to a - ``doc/reference/`` page or any other toctree. +- per the single-toctree-path rule, the three sibling pages are toctreed only once from + ``doc/solver/solver_main.rst``; never add them to a ``doc/reference/`` page or any other toctree. Style rules ----------- @@ -288,41 +242,42 @@ the shared style rules. In addition: - Use end-user-oriented language; match the tone and approximate depth of ``doc/physics`` pages. - Prefer short paragraphs with direct interpretation of equations and their consequences. - Avoid textbook density and implementation-oriented wording. -- Avoid unnecessary bullets outside tables, assumptions, and limitations. +- Do not add Key Concepts, Behavior and Interpretation, Assumptions, or Limitations sections. reStructuredText requirements ------------------------------- See [Documentation Architecture](../instructions/documentation-architecture.instructions.md) for the shared output-format requirements. In addition: -- Use ``.. list-table::`` for input and quantity tables. +- Use ``.. list-table::`` for the solved-unknowns table. - Use ``.. math::`` for displayed equations when needed. Final check before writing ---------------------------- -Ensure that the page: -- reads like a detailed behavior companion comparable to ``doc/physics`` pages, -- explains the solver's equation system and iteration scheme and their physical impact, not its - code, +Ensure each page: +- is short and concise, and reads like a focused companion to ``doc/physics`` pages, +- uses only its minimal section order with no Key Concepts/Behavior/Assumptions/Limitations sections, +- main page states the Newton-Raphson linearization and folds the sibling toctree into the role + section; workflow page describes assemble/solve/check/iterate; unknowns page names pressure, mass + flow, and specific internal energy with the linearity rationale; convergence page describes the + absolute and relative criteria, +- explains the solver's behavior, not its code, - grounds every claim in the source files in the source-priority table, -- stays separate from the conceptual landing tier and API reference, -- cross-links to physics pages instead of re-deriving asset-internal correlations, -- includes an explicit governing relation for each primary equation role/effect, unless none is - appropriate and that is stated. +- cross-links to physics pages instead of re-deriving asset-internal correlations. Validation ---------- -After writing or updating the behavior page: +After writing or updating any page: 1. Verify that the file is valid reStructuredText. 2. Check that section headings, ``.. list-table::`` blocks, math blocks, references, and indentation are syntactically valid. -3. Verify that the section order is respected, except optional sections omitted by rule. +3. Verify that the page-specific section order is respected. 4. Verify that terminology, heading style, and table style match ``doc/physics`` depth and ``doc/controller/controller_behavior.rst``. -5. Verify that equation-structure and physical-impact claims are supported by the source files in - the source-priority table. -6. Verify the page is toctreed only from ``doc/solver/solver_main.rst`` and not duplicated in any - ``doc/reference/`` page. +5. Verify that quantity, linearization, convergence, and workflow claims are supported by the + source files in the source-priority table. +6. Verify the three sibling pages are toctreed only once from ``doc/solver/solver_main.rst`` and not + duplicated in any ``doc/reference/`` page. 7. If command execution or validation tools are available, run ``doc/run_spinx.bat`` or the repository-preferred documentation build command. 8. Inspect the build output for warnings and errors related to the new or edited page, including diff --git a/.github/agents/SystemConceptDocAgent.agent.md b/.github/agents/SystemConceptDocAgent.agent.md index 994242a4..533c1c76 100644 --- a/.github/agents/SystemConceptDocAgent.agent.md +++ b/.github/agents/SystemConceptDocAgent.agent.md @@ -74,7 +74,6 @@ Before writing, inspect the closest matching existing documentation page and pre - ``doc/index.rst`` - For Intro pages: ``doc/intro/intro_main.rst``, ``doc/intro/audience_and_use_cases.rst``, ``doc/intro/package_scope.rst``, ``doc/intro/simulation_input_and_output.rst`` - - For Solver pages: ``doc/solver/solver_main.rst`` - For Network pages: ``doc/network/network_main.rst`` - For Control pages: ``doc/controller/controller.rst`` - ``doc/physics/physics_main.rst`` (cross-reference landing page only, not a style source for Physics content itself) @@ -157,9 +156,9 @@ Do not use this agent to document: short, high-level conceptual landing page (``doc/controller/controller.rst``); link to the detailed behavior pages rather than absorbing their content. - the solver's detailed equation-assembly/iteration mechanics or their physical impact on the - solved model — these belong to ``SolverBehaviorDocAgent``. For Solver, this agent owns only the - existing shallow conceptual tier (``doc/solver/solver_main.rst`` and its three conceptual pages); - link to ``doc/solver/solver_behavior.rst`` rather than absorbing its content. + solved model — these belong to ``SolverBehaviorDocAgent``, which owns the entire four-page Solver + section (``doc/solver/solver_main.rst``, ``solver_workflow.rst``, ``solver_unknowns.rst``, and + ``solver_convergence.rst``). Link to those pages rather than absorbing their content. When a conceptual page needs to point readers to implementation/reference detail (for example solver internals or controller classes), cross-link to the relevant diff --git a/doc/solver/solver_behavior.rst b/doc/solver/solver_behavior.rst deleted file mode 100644 index 46819785..00000000 --- a/doc/solver/solver_behavior.rst +++ /dev/null @@ -1,267 +0,0 @@ -Solver Behavior -================ - -Overview --------- - -This page describes the equation system the solver assembles each simulation timestep and how -solving that system determines the realized hydraulic and thermal state. It explains the solver -at the same level of detail as the physics asset pages, but from the perspective of the equation -system rather than a single asset's constitutive relations. - -The solver does not decide operational setpoints. Those are written onto assets by the controller -before the solve begins (see :doc:`../controller/controller_behavior`). The solver's task is to -find mass flow rates, pressures, and internal energies that satisfy every asset and node equation -simultaneously for that fixed set of inputs. The timestep path is centered on ``Solver.solve()``: -it assembles equations from every asset and node, solves the resulting sparse linear system, writes -the result back onto the network, and repeats until the solution stops changing materially between -iterations or an iteration limit is reached. - -Solver Inputs -------------- - -The solver reads the following inputs each timestep. - -.. list-table:: - :header-rows: 1 - - * - Input - - Description - - Unit - * - Asset and node equation contributions - - Mass continuity, energy balance, and pressure-drop equations each asset and node - contributes for the current iteration - - - - * - Controller setpoints - - Heat demand, prescribed inlet/outlet temperatures, and the pressure-setting flag already - written onto assets before the solve begins - - asset-specific - * - Previous-iteration solution - - The most recently solved mass flow rate, pressure, and internal energy at every - connection point, used to linearize nonlinear terms - - kg/s, Pa, J/kg - * - Absolute convergence tolerance - - Threshold below which an unknown is treated as unchanged between iterations - - matches unknown - * - Relative convergence tolerance - - Threshold below which an unknown's relative change is treated as negligible - - - - * - Iteration limit - - Maximum number of iterations attempted before the solve is abandoned with a warning - - - - -Equation Assembly and Iteration --------------------------------- - -Core Unknowns -~~~~~~~~~~~~~ - -Every connection point in the network carries three unknowns: mass flow rate :math:`\dot{m}` -[kg/s], pressure :math:`p` [Pa], and specific internal energy :math:`u` [J/kg]. A node has one -implicit connection point of its own; a two-port asset (pipes, heat-transfer two-port components, -boundaries, producers, consumers, storages) has two; the four-port heat-transfer asset has four. - -Node Equations -~~~~~~~~~~~~~~ - -Each node contributes three equations: - -- **Mass continuity**: the sum of the node's own mass flow rate and the mass flow rates of every - connected asset at its connecting point equals zero. -- **Energy balance**: if every connected flow is inbound, every connected flow is outbound, or all - connected flows are within the numerical zero-flow threshold, the node instead prescribes its - internal energy to a fixed initial value (there is no meaningful mixing to solve for). Otherwise - the node enforces a linearized energy balance across all connected flows: - - .. math:: - - \sum_i \dot{m}_i u_i = 0 - - Because :math:`\dot{m}_i u_i` is bilinear in the unknowns, each iteration linearizes it around - the previous iteration's values (superscript :math:`k-1`): - - .. math:: - - \sum_i \left( \dot{m}_i^{k-1} u_i + u_i^{k-1} \dot{m}_i \right) = \sum_i \dot{m}_i^{k-1} u_i^{k-1} - - where the sum runs over the node's own connection and every asset connected to it. -- **Discharge equation**: a third equation fixes the node's own implicit mass flow rate to zero, - completing the three equations needed for the node's three unknowns. Exactly one asset in each - hydraulically connected part of the network instead carries a fixed reference pressure, chosen - by the controller (see :doc:`../controller/controller_behavior`'s "Pressure-Setting Behavior"). - -Two-Port Asset Equations -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Two-port assets (for example pipes, producers, consumers, and ideal/ATES storages) carry six -unknowns (two connection points times three core quantities) and six equations: - -- Two **pressure-to-node** equations, one per connection point, tying the asset's pressure at that - point to its connected node's pressure. -- Two **thermal** equations, chosen per connection point from the previous iteration's flow at - that point: a connection point with significant inflow contributes the asset's bilinear internal - energy balance, - - .. math:: - - \dot{m}_0 u_0 + \dot{m}_1 u_1 + Q_{asset} = 0 - - linearized the same way as the node energy balance, where :math:`Q_{asset}` is the heat supplied - to or extracted from the asset (positive when heat is added). A connection point with negligible - or reversed inflow instead ties the asset's internal energy directly to its connected node's - value. -- One **internal continuity** equation, :math:`\dot{m}_0 + \dot{m}_1 = 0`, enforcing that no mass - accumulates inside the asset. -- One **internal pressure-loss** equation, - - .. math:: - - p_0 - p_1 - 2 K \left| \dot{m}_0 \right| \dot{m}_0 = 0 - - where :math:`K` is the asset's loss coefficient. For pipes, :math:`K` is derived each iteration - from the previous iteration's flow through the friction-factor correlations described in - :doc:`../physics/pipe_physics`; this page does not re-derive that correlation. - -Four-Port Heat-Transfer Asset Equations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The four-port heat-transfer asset (used for heat exchangers and four-port heat pumps) carries -twelve unknowns (four connection points times three core quantities) and extends the same pattern -to both of its hydraulic sides: each side's pressures link to its connected node, each side's -outlet temperature is prescribed or linked to its node depending on flow direction, and one -mass-flow-or-pressure pair per side encodes whether that side is actively converting heat or -passing flow through as a bypass. Which mode is active is decided by the controller for the -current timestep (see :doc:`../controller/controller_behavior`'s "Heat-Transfer Asset Handling"); -the asset's conversion-factor physics are described in :doc:`../physics/heat_pump_physics` and -:doc:`../physics/heat_exchanger_physics`. - -Iteration Scheme -~~~~~~~~~~~~~~~~~ - -``Solver.solve()`` resets the solution vector to a uniform initial guess, then repeats the -following sequence: - -#. Assemble the equations above from every asset and node, using the previous iteration's values - wherever a nonlinear or bilinear term needs linearizing. -#. Solve the resulting sparse linear system with a direct sparse solver. -#. Write the new solution back onto every asset and node so the next iteration linearizes around - it. -#. Check whether the new and previous solution vectors are close within the configured absolute - and relative tolerances; if so, stop. Otherwise repeat, up to the iteration limit. If the limit - is reached first, the solver logs a warning and returns the last computed solution as-is. - -This is a fixed-point (successive-substitution) iteration: nonlinear terms are not solved -implicitly within one linear solve, they are re-linearized and resolved repeatedly until the -solution stabilizes. For the equation-count bookkeeping behind "every asset and node contributes -exactly the equations needed for its unknowns," see :doc:`solver_unknowns_and_equations`. - -Quantities Solved ------------------- - -Each solve produces the following per connection point, written back onto the corresponding asset -or node. - -.. list-table:: - :header-rows: 1 - - * - Quantity - - Description - - Unit - * - ``mass_flow_rate`` - - Solved mass flow rate at the connection point - - kg/s - * - ``pressure`` - - Solved pressure at the connection point - - Pa - * - ``internal_energy`` - - Solved specific internal energy at the connection point; interpreted as temperature through - the fluid-property relations - - J/kg - -Physical Impact ----------------- - -Pressure Drop and Flow Distribution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The pressure-drop closure :math:`p_0 - p_1 = 2 K |\dot{m}_0| \dot{m}_0` is quadratic in flow, and -for pipes :math:`K` itself depends on the flow through the friction-factor correlation. Because -both are re-evaluated each iteration from the previous flow before the next linear solve, the -converged flow split across parallel paths is the outcome of an iterative search, not a fixed -proportional division. The practical consequence is that a topology or boundary-pressure change -can shift flow distribution nonlinearly rather than in direct proportion to the change. - -Node Mixing and Delivered Temperature -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Where multiple flows merge at a node, the linearized energy balance converges to the flow-weighted -mix of every connected inflow's internal energy. The practical consequence is that the temperature -seen downstream of a junction depends on the converged mass-flow split between its inflows, so a -change in demand or production elsewhere in the network can shift downstream delivered temperature -even when the total injected heat is unchanged. For the asset-level heat-to-temperature relation, -see :doc:`../physics/consumer_physics` and :doc:`../physics/producer_physics`. - -Flow Direction and Thermal-Equation Choice -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Because each two-port connection point's thermal equation is selected from the previous -iteration's flow sign, a connection point whose solved flow direction reverses during iteration -switches between a prescribed-temperature equation and a node-linked equation. The practical -consequence is that the solved flow direction at a connection need not match the direction implied -by controller setpoints, and the realized temperature interpretation at that point changes -accordingly. - -Pressure-Setting Choice -~~~~~~~~~~~~~~~~~~~~~~~~ - -Exactly one asset in each hydraulically connected part of the network anchors that part with a -fixed reference pressure, selected by the controller rather than by the solver itself (see -:doc:`../controller/controller_behavior`'s "Pressure-Setting Choice"). Changing which asset carries -that boundary changes the solved pressure distribution and flow pattern throughout that part of the -network even when every heat setpoint is unchanged. - -Non-Convergence -~~~~~~~~~~~~~~~~ - -If the iteration limit is reached before the solution satisfies the convergence tolerances, the -solver returns the last computed solution without a warning being escalated beyond a log message. -The practical consequence is that any of the interpretations above are only valid once convergence -is confirmed; an unconverged solve should be treated as an unreliable snapshot of the equation -system rather than a physically consistent state. - -Assumptions ------------ - -- Controller setpoints (heat demand, prescribed temperatures, the pressure-setting flag) are fixed - inputs to the solve and do not change while the solver iterates. -- Nonlinear and bilinear terms are linearized using the previous iteration's values rather than - solved implicitly within a single linear solve. -- The assembled system has exactly one equation per declared unknown. -- The solution vector starts from a uniform initial guess at the beginning of every new solve. - -Limitations ------------ - -- This page does not describe asset-specific constitutive correlations (friction factor, - heat-transfer coefficients, conversion factors); see the relevant page under - :doc:`../physics/physics_main`. -- It does not enumerate every equation branch for every asset type; boundary, production, buffer, - and heat-pump assets follow the same continuity/energy/pressure-drop pattern with parameters - described in Physics. -- If the iteration limit is reached, this page does not prescribe a recovery strategy; the - returned state should be treated as unreliable. -- It does not replace the lower-level class reference for ``Solver``, ``Matrix``, or ``Network``. - -Related Documentation ----------------------- - -- :doc:`solver_main` for the conceptual solver overview. -- :doc:`solver_unknowns_and_equations` for how unknowns and equations are counted and indexed. -- :doc:`solver_convergence` for the conceptual description of matrix- and timestep-level - convergence. -- :doc:`../physics/pipe_physics` for the friction-factor and heat-transfer-coefficient - correlations used in the pressure-drop and energy equations. -- :doc:`../physics/physics_main` for asset-level physical interpretation more broadly. -- :doc:`../controller/controller_behavior` for how controller setpoints, including the - pressure-setting choice, become solver inputs. -- :doc:`../reference/solver_reference` for solver implementation reference. diff --git a/doc/solver/solver_convergence.rst b/doc/solver/solver_convergence.rst index 2326021c..4af318e2 100644 --- a/doc/solver/solver_convergence.rst +++ b/doc/solver/solver_convergence.rst @@ -1,64 +1,52 @@ -Solver convergence -================== +.. _solver-convergence: + +Convergence +=========== Overview -------- -Convergence in OMOTES.SIMULATOR_CORE is handled at two levels: inside the solver itself and at the -broader timestep level in the network simulation loop. - -Role in the Simulation Workflow -------------------------------- - -Inside ``Solver.solve()``, the matrix solution is updated repeatedly until the solution vector is -considered converged or an iteration limit is reached. After each matrix solve, the network receives -the updated results so assets and nodes can evaluate their next equations from the latest state. - -Outside the solver, ``NetworkSimulation.run()`` may repeat an entire timestep until asset-level -convergence is reached or the timestep iteration limit is hit. - -Key Concepts ------------- - -- Matrix convergence: checks whether consecutive solution vectors are sufficiently close. -- Solver iteration limit: stops the internal solve loop after 100 iterations. -- Timestep convergence: checks whether assets report a converged state across repeated timestep runs. -- Timestep iteration limit: stops timestep retries after 20 iterations. +The solver decides that it has found the network state when the solution stops changing +between iterations. Convergence is judged by comparing the new solution vector against the +previous iteration's vector using a combined absolute and relative tolerance test. -Behavior and Interpretation ---------------------------- +Convergence +----------- -Matrix convergence is tested using relative and absolute tolerances through a vector comparison: +The iteration is converged when every entry of the new solution agrees with the corresponding +entry of the previous solution within tolerance: .. math:: - x_{new} \approx x_{old} - -where closeness is evaluated using configured absolute and relative convergence thresholds. - -This means the solver is not checking a single scalar residual in isolation. It is checking whether -the full solved state stops changing materially between iterations. + \left| s_{new} - s_{old} \right| \le a_{tol} + r_{tol} \left| s_{old} \right| -The timestep loop adds a second layer of stability checking. Even if one solver call converges, -asset-level post-solve behavior may still require another timestep iteration before the network is -treated as converged for output purposes. +.. list-table:: + :widths: 20 80 + :stub-columns: 1 -Assumptions ------------ - -- Consecutive solution vectors are a sufficient indicator of internal numerical convergence. -- Asset-level ``is_converged()`` checks represent the network's timestep stability criterion. -- Resetting the solution state at the start of a new solve provides a consistent iteration start. + * - :math:`s_{new}` + - Solution entry from the current iteration + * - :math:`s_{old}` + - Solution entry from the previous iteration + * - :math:`a_{tol}` + - Absolute tolerance, :math:`10^{-6}` + * - :math:`r_{tol}` + - Relative tolerance, :math:`10^{-6}` -Limitations ------------ +The absolute term keeps quantities that are near zero from blocking convergence, while the +relative term scales the allowed change with the magnitude of the quantity, so large +pressures and small mass flows are each judged on a comparable footing. The check must hold +for every solved unknown at once; a single entry still changing keeps the iteration running. -- The documentation does not define asset-specific convergence logic; that depends on each asset implementation. -- If iteration limits are reached, the current code warns or exits the loop, but this page does not prescribe recovery strategy. +In practice, tighter tolerances require more iterations to satisfy, while looser tolerances +converge sooner at the cost of accuracy. If the criterion is not met within the iteration +limit, the solver logs a non-converged warning and reports the last iterate as the result for +the timestep (see :doc:`solver_workflow`). Related Documentation --------------------- -- For the overall solver flow, see :doc:`solver_workflow`. -- For unknown and equation structure, see :doc:`solver_unknowns_and_equations`. -- For simulation-loop context, see :doc:`../intro/simulation_input_and_output`. \ No newline at end of file +- :doc:`solver_main` — the conceptual overview. +- :doc:`solver_workflow` — where the convergence check sits in the solve loop. +- :doc:`solver_unknowns` — the solved vector that is tested against tolerance. +- :doc:`../reference/solver_reference` — class-level reference. diff --git a/doc/solver/solver_main.rst b/doc/solver/solver_main.rst index f918763e..06ab4299 100644 --- a/doc/solver/solver_main.rst +++ b/doc/solver/solver_main.rst @@ -1,50 +1,50 @@ +.. _solver-main: + Solver ====== -This section explains how the solver participates in each simulation timestep. It focuses on the -numerical role of the solver, the unknowns it resolves, and how convergence is handled between the -matrix solve and the broader timestep loop. +Overview +-------- + +The solver computes the hydraulic and thermal state of the thermal network for each +simulation step. It owns the :doc:`Network <../network/network_main>` of assets and nodes +together with the matrix that holds the assembled system, and it mediates between the two: +it collects the linearized equations contributed by each asset and node, passes them to the +matrix to solve, and writes the resulting state back onto the assets and nodes. -The solver operates on the network assembled from assets and nodes. For each solve, it builds the -equation system, computes updated hydraulic and thermal state values, and writes those results back -to the network entities. +The network equations are nonlinear, mainly because pressure losses and convective energy +transport depend on the unknowns themselves. The solver does not solve this nonlinear system +directly. Instead, each iteration linearizes the equations about the current solution using +the Newton-Raphson method, assembles them into a linear system, and solves that system. The +new state becomes the linearization point for the next iteration, and the process repeats +until the solution no longer changes within tolerance. -How to use this section ------------------------ +Role in the Simulation Workflow +------------------------------- -- Start with the conceptual pages below to understand solver workflow and result interpretation. -- Use :doc:`solver_behavior` for the detailed explanation of the equation system the solver solves - each timestep and how that solve changes the physical model. -- Use the Solver Reference page (linked below) for class-level information about solver internals. -- Use the Physics section for asset-specific constitutive relations and the Network section for - connectivity concepts. +The solver runs once per simulation timestep, after the controller has translated its +setpoints into asset inputs. Given those inputs it determines the network state — pressure, +mass flow, and thermal state at every connection point — that is consistent with both the +controller's operation and the asset-internal physics. The solved state is then reported as +the result for that timestep. -Conceptual pages ----------------- +The three pages below expand the individual aspects of this process: how the iteration is +assembled and driven, which quantities are solved, and how convergence is determined. .. toctree:: :maxdepth: 1 solver_workflow - solver_unknowns_and_equations + solver_unknowns solver_convergence - solver_behavior - -Implementation reference -------------------------- - -For solver classes, matrix assembly, and asset-level solver implementation details, use -:doc:`../reference/solver_reference`. Related Documentation --------------------- -- For network representation and connectivity, see :doc:`../network/network_main`. -- For interpretation of physical state variables and governing relations, see :doc:`../physics/physics_main`. -- For package-level execution context, see :doc:`../intro/intro_main`. - - - - - - +- :doc:`solver_workflow` — the assemble, solve, check, and iterate loop. +- :doc:`solver_unknowns` — the quantities solved per connection point. +- :doc:`solver_convergence` — the absolute and relative convergence criteria. +- :doc:`../network/network_main` — how assets and nodes are connected into the network. +- :doc:`../physics/physics_main` — the asset-internal constitutive relations. +- :doc:`../controller/controller_behavior` — how setpoints become solver inputs. +- :doc:`../reference/solver_reference` — class-level reference. diff --git a/doc/solver/solver_unknowns.rst b/doc/solver/solver_unknowns.rst new file mode 100644 index 00000000..837ed36b --- /dev/null +++ b/doc/solver/solver_unknowns.rst @@ -0,0 +1,55 @@ +.. _solver-unknowns: + +Solved Unknowns +=============== + +Overview +-------- + +The solver solves for a fixed set of core quantities at every connection point of the +network. These quantities are chosen so that the assembled system is as linear as possible, +which keeps the Newton-Raphson iteration well behaved and fast to converge. + +Solved Unknowns +--------------- + +Each asset and node registers how many unknowns it needs and receives the matrix indices for +them. Per connection point, the solver solves for three core quantities: + +.. list-table:: + :header-rows: 1 + :widths: 30 50 20 + + * - Quantity + - Description + - Unit + * - :math:`p` + - Pressure at the connection point + - Pa + * - :math:`\dot{m}` + - Mass flow rate through the connection point + - kg/s + * - :math:`u` + - Specific internal energy at the connection point + - J/kg + +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`). + +Near-zero flow is handled with a small mass-flow limit, ``MASSFLOW_ZERO_LIMIT`` = +:math:`10^{-3}` kg/s. Flows below this magnitude are treated as effectively zero, which +avoids ill-conditioned energy relations where the convective term would otherwise be divided +by a vanishing mass flow. + +Related Documentation +--------------------- + +- :doc:`solver_main` — the conceptual overview. +- :doc:`solver_workflow` — how these unknowns are assembled and solved each iteration. +- :doc:`solver_convergence` — how the solved vector is tested for convergence. +- :doc:`../physics/physics_main` — fluid-property relations and asset-internal physics. +- :doc:`../reference/solver_reference` — class-level reference. diff --git a/doc/solver/solver_unknowns_and_equations.rst b/doc/solver/solver_unknowns_and_equations.rst deleted file mode 100644 index 98482e3b..00000000 --- a/doc/solver/solver_unknowns_and_equations.rst +++ /dev/null @@ -1,68 +0,0 @@ -Solver unknowns and equations -============================= - -Overview --------- - -The solver resolves hydraulic and thermal state variables over the assembled network. Unknowns are -stored in one global solution vector and indexed across assets and nodes. - -Role in the Simulation Workflow -------------------------------- - -Before the first solve, the solver assigns matrix indices to each asset and node according to the -number of unknowns they contribute. During each iteration, assets and nodes return their current -equations and the matrix layer solves the resulting system. - -Key Concepts ------------- - -The primary unknowns described by the solver documentation are: - -#. Mass flow rate :math:`\dot{m}` [kg/s] -#. Pressure :math:`p` [Pa] -#. Specific internal energy :math:`u` [J/kg] - -Specific internal energy is used as the thermal state variable in the solve. Temperature is then -interpreted through the fluid-property relations described in the Physics section. - -Behavior and Interpretation ---------------------------- - -The global equation system is assembled from two sources: - -- Asset equations: represent pressure, energy, and component-specific behavior across each asset. -- Node equations: enforce continuity and state consistency where assets connect. - -For the system to be solvable, the number of equations must equal the number of unknowns: - -.. math:: - - N_{equations} = N_{unknowns} - -The matrix layer verifies this equality before solving. If too many or too few equations are -supplied, the solve is rejected rather than silently proceeding with an inconsistent system. - -Users should interpret the solution vector as the internal numerical representation of the network -state. Asset and node result values are derived by mapping segments of that vector back to the -corresponding objects. - -Assumptions ------------ - -- Assets and nodes correctly report how many unknowns and equations they contribute. -- The assembled system can be represented as a sparse matrix. -- The solved state is meaningful only after it has been propagated back to assets and nodes. - -Limitations ------------ - -- This page does not enumerate asset-specific equations; those belong in Physics. -- It does not document every matrix or equation-object method; those belong in the detailed solver pages. - -Related Documentation ---------------------- - -- For timestep flow around the solver, see :doc:`solver_workflow`. -- For convergence handling, see :doc:`solver_convergence`. -- For governing physical relations, see :doc:`../physics/physics_main`. diff --git a/doc/solver/solver_workflow.rst b/doc/solver/solver_workflow.rst index d2391d61..c3eead8b 100644 --- a/doc/solver/solver_workflow.rst +++ b/doc/solver/solver_workflow.rst @@ -1,63 +1,50 @@ -Solver workflow -=============== +.. _solver-workflow: + +Solve Workflow +============== Overview -------- -The solver is responsible for computing the hydraulic and thermal state of the network for a single -solve. It sits inside the timestep execution path and is called after controller setpoints have been -applied to the network assets. - -Role in the Simulation Workflow -------------------------------- - -At a high level, the execution flow is: +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. -#. The simulation loop advances to the next timestep. -#. The controller updates network state and computes setpoints for that timestep. -#. The heat network applies those setpoints to assets. -#. The solver assembles and solves the network equation system. -#. Results are written back to assets and nodes. -#. Asset-level convergence is checked at timestep level before output is stored. - -In the implementation, ``NetworkSimulation.run()`` drives the timestep loop, ``HeatNetwork`` applies -controller input and invokes ``Solver.solve()``, and the solver delegates equation solution to the -matrix layer. - -Key Concepts ------------- +Workflow +-------- -- Timestep solve: one call to the solver that computes updated state values for the current network state. -- Equation assembly: assets and nodes each contribute equations to the global system. -- Result propagation: the solved vector is transferred back into asset and node state. +Each call to the solver runs the following loop. -Behavior and Interpretation ---------------------------- +**Initialize.** The matrix solution is reset and every asset and node discards its previous +solution, so the iteration starts from a clean state. -The solver itself does not decide operational setpoints. Those come from the controller. Its task is -to find a network state that satisfies the assembled hydraulic and thermal equations for the current -inputs and topology. +**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. -Because the solve runs inside the broader timestep loop, users should interpret solver output as the -numerical state associated with one controller-driven network condition, not as a standalone control -decision. +**Solve.** The assembled linear system is solved for a new solution vector. This solution is +the linearized estimate of the network state for the current iteration. -Assumptions ------------ +**Transfer.** The new solution is written back onto the assets and nodes, so that the next +assembly step linearizes around the updated state. -- Controller inputs have already been applied before the solve begins. -- Asset and node equations together provide a square system with one equation per unknown. -- The solver writes results back into network entities after each matrix solve. +**Check and iterate.** Convergence is tested by comparing the new solution against the +solution of the previous iteration (see :doc:`solver_convergence`). If the two agree within +tolerance, the loop stops and the network state is final for the timestep. Otherwise the loop +repeats from the assembly step. -Limitations ------------ +**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. -- This page describes solver workflow, not asset-specific physical models. -- It does not replace the lower-level class reference pages for ``Solver``, ``Matrix``, or ``Network``. +Because the equations are re-linearized about the latest solution on every pass, successive +iterates move toward the state that satisfies the full nonlinear network equations. Related Documentation --------------------- -- For unknowns and equation structure, see :doc:`solver_unknowns_and_equations`. -- For convergence behavior across iterations and timesteps, see :doc:`solver_convergence`. -- For asset-level physics, see :doc:`../physics/physics_main`. +- :doc:`solver_main` — the conceptual overview and Newton-Raphson linearization statement. +- :doc:`solver_unknowns` — the quantities assembled into each linear system. +- :doc:`solver_convergence` — how the convergence check in the loop is evaluated. +- :doc:`../physics/physics_main` — the asset-internal relations that form the equations. +- :doc:`../reference/solver_reference` — class-level reference. From 98a58e891aed356672776ce9b6014fef28e7a67b Mon Sep 17 00:00:00 2001 From: Sam van der Zwan Date: Thu, 10 Sep 2026 11:32:49 +0200 Subject: [PATCH 2/2] Fixed based on review --- .github/agents/DocumentationCoordinator.agent.md | 14 +++++++------- doc/solver/solver_unknowns.rst | 2 +- doc/solver/solver_workflow.rst | 11 ++++++----- 3 files changed, 14 insertions(+), 13 deletions(-) diff --git a/.github/agents/DocumentationCoordinator.agent.md b/.github/agents/DocumentationCoordinator.agent.md index ea355387..b7efcae7 100644 --- a/.github/agents/DocumentationCoordinator.agent.md +++ b/.github/agents/DocumentationCoordinator.agent.md @@ -1,9 +1,9 @@ --- name: DocumentationCoordinator description: '>-' -Coordinate documentation work for SIMULATOR-CORE by classifying requests,: '' -enforcing the documentation structure, delegating to specialist agents, and: '' -validating consistency across pages.: '' + Coordinate documentation work for SIMULATOR-CORE by classifying requests, + enforcing the documentation structure, delegating to specialist agents, and + validating consistency across pages. argument-hint: Documentation goal, affected sections/pages, and scope constraints. 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'] agents: @@ -21,14 +21,14 @@ handoffs: - label: Review for audience/scope/duplication agent: DocReviewAgent prompt: '>-' - Review the page(s) just authored for audience fit, section fit, scope: '' - correctness, duplication, and cross-link quality.: '' + Review the page(s) just authored for audience fit, section fit, scope + correctness, duplication, and cross-link quality. send: true - label: Validate Sphinx build agent: SphinxValidationAgent prompt: '>-' - Validate that the documentation build is clean (toctrees, autodoc: '' - resolution, rst syntax) for the page(s) just authored/reviewed.: '' + Validate that the documentation build is clean (toctrees, autodoc + resolution, rst syntax) for the page(s) just authored/reviewed. send: true --- You are a documentation coordination agent. diff --git a/doc/solver/solver_unknowns.rst b/doc/solver/solver_unknowns.rst index 837ed36b..a449ad94 100644 --- a/doc/solver/solver_unknowns.rst +++ b/doc/solver/solver_unknowns.rst @@ -34,7 +34,7 @@ them. Per connection point, the solver solves for three core quantities: - J/kg 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 +directly. This keeps the energy-transport terms bilinear 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 diff --git a/doc/solver/solver_workflow.rst b/doc/solver/solver_workflow.rst index c3eead8b..5fcd5697 100644 --- a/doc/solver/solver_workflow.rst +++ b/doc/solver/solver_workflow.rst @@ -6,10 +6,11 @@ Solve Workflow Overview -------- -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. +The solver reaches the network state through iteration by using a Newton-Rapson method to +linearize the equations: 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. Workflow -------- @@ -21,7 +22,7 @@ solution, so the iteration starts from a clean state. **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. +unknowns, so the linear system is square. **Solve.** The assembled linear system is solved for a new solution vector. This solution is the linearized estimate of the network state for the current iteration.