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] 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.