From 4c4f9a9a6f33205fe8e340041cc7ff93725ab74a Mon Sep 17 00:00:00 2001 From: Mike van Meerkerk Date: Thu, 25 Jun 2026 11:59:06 +0200 Subject: [PATCH 01/11] Support update referencing exisiting process --- .github/agents/SupportDocAgent.agent.md | 22 +++++--- ...documentation-architecture.instructions.md | 19 +++++-- CONTRIBUTING.md | 6 ++- README.md | 7 +++ doc/support/support.rst | 53 ++++++++++++++++--- 5 files changed, 88 insertions(+), 19 deletions(-) diff --git a/.github/agents/SupportDocAgent.agent.md b/.github/agents/SupportDocAgent.agent.md index 36711c84..35dde38f 100644 --- a/.github/agents/SupportDocAgent.agent.md +++ b/.github/agents/SupportDocAgent.agent.md @@ -52,21 +52,31 @@ Before writing, inspect the closest matching existing documentation page and pre 1. Follow repository documentation style first, especially: - ``doc/index.rst`` - - ``doc/support/support.rst`` (existing Support page; already references the issue - tracker, ``CONTRIBUTING.md``, and ``README.md``) + - ``doc/support/support.rst`` (existing Support page; already references the + ``user_feedback`` repository, this repository's own issue tracker, ``CONTRIBUTING.md``, + and ``README.md``) - ``CONTRIBUTING.md`` (repository root — branch/PR/review workflow, lint/type-check requirements, test coverage guideline) - ``README.md`` (repository root) 2. Use repository context as the authority for support channels. -Concrete support paths confirmed to exist in this repository: -- the GitHub issue tracker, +Concrete support paths confirmed to exist: +- the `Project-OMOTES/user_feedback `_ + repository's Discussions, "Q&A" category — for usage questions + (``https://github.com/Project-OMOTES/user_feedback/discussions/new?category=q-a``), +- the same repository's Issues, using the ``bug_report.yml``/``feature_request.yml`` + templates — for bug reports and feature requests; browse existing issues at + ``https://github.com/Project-OMOTES/user_feedback/issues`` before filing a new one, +- this repository's own GitHub issue tracker — for development/code-level issues in + simulator-core itself, paired with ``CONTRIBUTING.md``, - ``CONTRIBUTING.md``, - ``README.md``. -No ``.github/ISSUE_TEMPLATE/`` directory exists in this repository — do not reference or -invent issue templates. +No ``.github/ISSUE_TEMPLATE/`` directory exists in *this* repository (simulator-core) — do +not invent templates here. Templates do exist in the external ``user_feedback`` repository +(``bug_report.yml``, ``feature_request.yml``, ``question.yml``) and may be referenced by +name/purpose since they are real, confirmed artifacts — do not fabricate others. Rules for source usage: - Do not invent support channels that are not present in the repository context. diff --git a/.github/instructions/documentation-architecture.instructions.md b/.github/instructions/documentation-architecture.instructions.md index c69fa60a..6b619b66 100644 --- a/.github/instructions/documentation-architecture.instructions.md +++ b/.github/instructions/documentation-architecture.instructions.md @@ -96,10 +96,21 @@ Support page requirements -------------------------- - Keep a dedicated ``Support`` page (``doc/support/support.rst``) in the main toctree. - Provide clear instructions for requesting support. -- Ground support paths in what actually exists in the repository: the GitHub issue - tracker, ``CONTRIBUTING.md`` (branch/PR/review workflow, lint/type-check, test coverage - guideline), and ``README.md``. No ``.github/ISSUE_TEMPLATE/`` directory exists in this - repository — do not reference or invent issue templates. +- Ground support paths in what actually exists: + - The `Project-OMOTES/user_feedback `_ + repository is the end-user support front door for the Design toolkit (of which + simulator-core is a backend component): Discussions, "Q&A" category, for usage + questions; Issues, using the ``bug_report.yml``/``feature_request.yml`` templates, for + bug reports and feature requests. + - ``CONTRIBUTING.md`` (branch/PR/review workflow, lint/type-check, test coverage + guideline) and this repository's own GitHub issue tracker for contributor/development + questions and code-level bugs in simulator-core itself. + - ``README.md`` for package/usage overview. +- No ``.github/ISSUE_TEMPLATE/`` directory exists in *this* repository (simulator-core) — + do not invent templates here. Templates do exist in the external ``user_feedback`` + repository (``bug_report.yml``, ``feature_request.yml``, ``question.yml``) and may be + referenced by name/purpose since they are real, confirmed artifacts — do not fabricate + others. - Keep the page concise and actionable. Style rules diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c8499519..85566d40 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,8 @@ # This file -This file should describe the development process for this project and include instruction on -how to run/build your project. Any environment settings/requirements? +This file describes the development workflow for contributors making code changes to +simulator-core. If you're an end user reporting a bug, requesting a feature, or asking a +usage question, use the [user feedback repository](https://github.com/Project-OMOTES/user_feedback) +instead — see `doc/support/support.rst` for the full process. # Development guidelines The general proces is as follows: diff --git a/README.md b/README.md index 46642e98..3291841c 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,13 @@ sim = SimulationManager(EsdlObject(pyesdl_from_file(esdl_file_path)), config) result = sim.execute(progressLogger) ``` +## Support + +Found a bug, want a feature, or have a usage question? See the +[user feedback repository](https://github.com/Project-OMOTES/user_feedback) — open a +Discussion (Q&A category) for questions, or check/open an Issue for bugs and feature +requests. + ## Contributing Pull requests are welcome. For major changes, please open an issue first diff --git a/doc/support/support.rst b/doc/support/support.rst index 4885b6f1..614a4721 100644 --- a/doc/support/support.rst +++ b/doc/support/support.rst @@ -3,25 +3,64 @@ Support Use this section when you need help using, interpreting, or extending OMOTES.SIMULATOR_CORE. +When to use this page +---------------------- + +- You are a toolkit user, system modeler, or integrator with a usage question, a bug to + report, or a feature to request. +- You are a contributor with a question about the development workflow, or you have found + a code-level issue in this repository. +- Use the conceptual sections (Intro, Solver, Network, Physics, Control) or Developer + Documentation instead if you are trying to understand existing behavior or + implementation rather than report or ask something new. + Support Paths -------------- +-------------- + +**Usage questions** + +- Open a new Discussion under the "Q&A" category in the + `Project-OMOTES/user_feedback `_ + repository: https://github.com/Project-OMOTES/user_feedback/discussions/new?category=q-a + +**Bug reports and feature requests** -- For bug reports and feature requests, open an issue in the project repository. -- For contribution workflow and collaboration expectations, read ``CONTRIBUTING.md``. -- For package context and usage overview, read ``README.md``. +- Check the existing issues first: https://github.com/Project-OMOTES/user_feedback/issues +- If not already reported, open a new issue in the same repository using the + "Bug Report" or "Feature Request" template. + +**Development questions** + +- For the contribution workflow, code review process, and lint/type-check/testing + requirements for this repository, read ``CONTRIBUTING.md``. +- If you have found a code-level bug in simulator-core itself, open an issue directly on + this repository. What to include ---------------- +---------------- - A short problem summary - Steps to reproduce - Expected behavior and observed behavior - Relevant input model context (for example ESDL source) - Environment details (operating system and Python version) +- If attaching an ESDL file: GitHub does not accept ``.esdl`` attachments directly, so + append ``.txt`` to the filename or zip the file first. Before requesting support -------------------------- +--------------------------- -- Check the relevant conceptual section first: Intro, Solver, Network, Physics, or Control. +- Search existing issues and discussions in + `Project-OMOTES/user_feedback `_ to + avoid duplicates. +- Check the relevant conceptual section first: Intro, Solver, Network, Physics, or + Control. - Use Developer Documentation when the question is implementation-oriented. - Include the documentation page or workflow area that appears to be affected. + +Related Documentation +----------------------- + +- ``CONTRIBUTING.md`` for contribution workflow, code review, and testing requirements. +- ``README.md`` for package installation and usage overview. +- :doc:`../developer/developer_main` for implementation-oriented guidance and reference. From a54fdb0d52aad771b46cecf99549007d697b0868 Mon Sep 17 00:00:00 2001 From: Mike van Meerkerk Date: Thu, 25 Jun 2026 14:55:56 +0200 Subject: [PATCH 02/11] Update intro --- doc/intro/intro_main.rst | 54 +++++++++++++++++++++++++++------------- 1 file changed, 37 insertions(+), 17 deletions(-) diff --git a/doc/intro/intro_main.rst b/doc/intro/intro_main.rst index 49dd0c56..908e6894 100644 --- a/doc/intro/intro_main.rst +++ b/doc/intro/intro_main.rst @@ -1,15 +1,36 @@ Introduction ============ -OMOTES.SIMULATOR_CORE is a Python package for thermo-hydraulic simulation of district heating systems. -It combines network topology, asset behavior, and controller setpoints to compute mass flow rate, -pressure, and thermal state over time. +Overview +-------- -This Intro section provides package-level orientation before moving into the domain sections. -Use it to understand what the package does, who it is for, and what inputs and outputs define a -simulation run. +OMOTES.SIMULATOR_CORE is the simulation package used to evaluate thermo-hydraulic behavior in district +heating systems. It provides the package-level entry point for understanding what the simulator does, +how the main subsystems fit together, and how to interpret the results that come out of a run. -**Contents** +What OMOTES.SIMULATOR_CORE Does +------------------------------ + +The package turns a time-based system description into simulation results. In practice, it combines the +network structure, asset behavior, control setpoints, and solver execution needed to compute how the +system evolves over time. + +This introductory section keeps the focus on the overall package rather than on implementation detail. +Use it to understand the scope of the simulator before moving into the solver, network, physics, and +control sections. + +Why It Is Used +-------------- + +The package is used when you need to study how a district-heating system behaves under changing demand, +network conditions, and control decisions. It supports modelers and integrators who want to compare +scenarios, interpret operational behavior, or connect simulation results to surrounding tooling. + +Typical use is to answer questions such as whether a configuration can meet demand, how a control +strategy affects system response, or what thermal and hydraulic trends appear over a simulation period. + +Contents +-------- .. toctree:: :maxdepth: 1 @@ -18,18 +39,17 @@ simulation run. audience_and_use_cases simulation_input_and_output -Section map ------------ +Related Documentation +--------------------- -- For solver architecture and numerical flow, see :doc:`../solver/solver_main`. -- For network concepts and topology behavior, see :doc:`../network/network_main`. -- For physical relations and asset equations, see :doc:`../physics/physics_main`. -- For controller behavior and setpoint logic, see :doc:`../controller/controller`. -- For contributor and API guidance, see :doc:`../developer/developer_main`. -- For issue reporting and collaboration support, see :doc:`../support/support`. +For the next level of detail, see: -External context ----------------- +- :doc:`../solver/solver_main` for solver behavior and numerical execution. +- :doc:`../network/network_main` for network representation and connectivity concepts. +- :doc:`../physics/physics_main` for asset-level physical relations. +- :doc:`../controller/controller` for control concepts and setpoint behavior. +- :doc:`../developer/developer_main` for contributor and API-oriented material. +- :doc:`../support/support` for support and issue-reporting guidance. For project context and standards, see the `NWN website`_ and `ESDL`_. From b3a45c1edf88794c86c9b036d7e0f2cee0b7759b Mon Sep 17 00:00:00 2001 From: Mike van Meerkerk Date: Thu, 25 Jun 2026 15:34:18 +0200 Subject: [PATCH 03/11] Network layer documentation --- .github/agents/NetworkLayerDocAgent.agent.md | 261 +++++++++++++++++++ doc/network/network_main.rst | 8 + doc/network/network_topology.rst | 168 ++++++++++++ 3 files changed, 437 insertions(+) create mode 100644 .github/agents/NetworkLayerDocAgent.agent.md create mode 100644 doc/network/network_topology.rst diff --git a/.github/agents/NetworkLayerDocAgent.agent.md b/.github/agents/NetworkLayerDocAgent.agent.md new file mode 100644 index 00000000..f5bcfa40 --- /dev/null +++ b/.github/agents/NetworkLayerDocAgent.agent.md @@ -0,0 +1,261 @@ +--- +name: NetworkLayerDocAgent +description: Create end-user network layer documentation in reStructuredText for doc/network, explaining how the network graph is represented, constructed from ESDL, and partitioned, at a level of source-grounded detail comparable to the physics asset pages. +argument-hint: Network topic name, page title, and output file name (for example: Network Topology, Network Topology and Connectivity, network_topology.rst). +tools: [read, search, edit, execute/runInTerminal, web] +agents: [] +--- + +You are a technical documentation agent. + +Your only task is to write end-user network layer documentation in valid reStructuredText for files in ``doc/network``. + +Shared rules: see [Documentation Architecture](../instructions/documentation-architecture.instructions.md) for the fixed section order, equation/notation rules, and build-validation command. The rules below are specific to network layer pages. + +Inputs +------ +- Network topic: ```` +- Page title: ```` +- Output file: ``network_.rst`` + +Primary objective +----------------- +Write documentation that helps end users, system modelers, and integrators understand: +- how the network graph is structurally represented (nodes, junctions, connection points, multi-port assets), +- how that structure is constructed from ESDL connectivity, +- how the network is partitioned into sub-networks, +- which structural rules and assumptions govern connectivity and partitioning, +- which limitations affect the network representation. + +Document the network's structure and construction. Do not document asset-internal physics +equations, controller dispatch decisions, solver equation-assembly/iteration mechanics, or +class-by-class API reference. + +Relationship to the rest of the Network documentation +------------------------------------------------------- +Network documentation is split across several owners. This agent owns exactly one part of it: + +- Network conceptual documentation (``doc/network/network_main.rst``): owned by + ``SystemConceptDocAgent`` — a short, high-level overview of connectivity and communication + between assets and the solver/controller. Cross-link to it; do not rewrite it. +- **Network layer structure documentation (this agent):** source-grounded detail on how the + network graph is represented, built from ESDL, and partitioned. +- Asset-internal physics and governing equations (mixing, heat loss, pressure drop, and similar + behavior owned by a specific asset, e.g. ``Junction``, ``Pipe``, producer/consumer assets) are + owned by ``PhysicsAssetDocAgent`` under ``doc/physics``. Link to the matching ``doc/physics`` + page; do not re-derive its equations. +- Controller dispatch, priority, curtailment, and other per-timestep decisions are owned by + ``ControllerBehaviorDocAgent``. Do not restate how sub-networks are used to make control + decisions; only explain how the network is partitioned into them. +- Solver equation-assembly and iteration mechanics are owned by ``SolverBehaviorDocAgent``. Do + not restate how the assembled equations are solved. +- Class/module API reference (``doc/solver/network.rst``, ``doc/controller/sub_network_class.rst``, + ``doc/reference/architecture_reference.rst``, and similar generated/curated reference pages) is + owned by ``APIReferenceAgent``. Cross-link to these with ``:doc:``/``:ref:`` prose; never add a + ``.. toctree::`` entry that duplicates a page already toctreed from the curated reference tier + or the generated API tree (single toctree path rule). + +Do not absorb any of these roles into a network layer structure page. + +Source priority +--------------- +Before writing, inspect ``doc/network/network_main.rst`` as the landing page and style anchor, +and the closest matching existing page in ``doc/network`` if one exists. + +1. Follow repository style first. Candidate ``doc/network`` pages and their matching + implementation source are: + + .. list-table:: + :header-rows: 1 + + * - doc/network page + - source file + * - network_topology.rst + - solver/network/network.py (``Network``), solver/network/assets/node.py (``Node``), + solver/network/assets/base_node_item.py + * - network_construction.rst + - entities/heat_network.py (``HeatNetwork``, ``conversion_factory``), + simulation/mappers/mappers.py, entities/esdl_object.py + * - network_boundary_conditions.rst + - solver/network/assets/boundary.py (``BaseBoundary``), + solver/network/assets/production_asset.py (``HeatBoundary``) + * - network_subnetworks.rst + - entities/network_controller.py (``NetworkController``), + entities/network_controller_abstract.py (``NetworkControllerAbstract``) + + Also use ``doc/network/network_main.rst`` as the section landing page and style anchor. + +Rules for source usage: +- Use repository sources only. +- Use ``doc/network/network_main.rst`` as the authoritative style baseline. +- Use the source file(s) matching the target topic (table above) to ground structural claims in + actual implementation, not invented behavior. +- If repository sources are missing or ambiguous for a claim, omit the claim rather than + inferring or importing external material. + +Audience and scope +------------------ +Audience: +- End users +- System modelers +- Integrators + +Scope: +- Network structure and construction only +- Topology, connectivity, and partitioning relevant to configuration and interpretation +- How the network graph is built from ESDL connectivity +- Structural assumptions and limitations that affect results + +Do not include: +- asset-internal physics, governing equations, or constitutive relations +- controller dispatch or priority decisions +- solver equation-assembly or iteration mechanics +- class-by-class API walkthroughs +- contributor extension workflow +- software architecture discussion beyond what is needed to explain network structure + +Content requirements +--------------------- +Include, where applicable: +- a conceptual description of the structural element being documented, +- the key classes/structures involved and the structural role each plays, +- how the structure is constructed (only for construction-focused topics), +- structural connectivity and partitioning rules, +- structural assumptions, +- structural limitations. + +Only include details that affect how users configure, interpret, or reason about the network +structure. + +Section order +------------- +Use the following section order for all sections that are present: + +1. Title +2. Description +3. Representation +4. Construction +5. Connectivity and Behavior +6. Assumptions +7. Limitations +8. See Also / References + +Optional sections: +- Omit ``Construction`` if the topic is not about how the structure is built from ESDL input. + +Classification rules +--------------------- +Classify content as follows: +- ``Representation``: the key classes/data structures involved and the structural role each + plays (for example: node, junction, connection point, multi-port asset, sub-network). +- ``Construction``: how the structure is derived/assembled from ESDL connectivity. +- ``Connectivity and Behavior``: structural rules governing how the network behaves as a graph + during simulation (connection validity, degrees of freedom, partitioning), not asset physics. +- ``Assumptions``: explicit structural assumptions collected in one place for correct + interpretation. +- ``Limitations``: structural simplifications and omissions, and cases where a more detailed + network representation is needed. + +Section requirements +---------------------- + +Description +~~~~~~~~~~~ +Explain: +- what structural element of the network this page covers, +- its role in the overall network graph, +- how users should interpret it when configuring or reasoning about a network. + +Representation +~~~~~~~~~~~~~~ +Use a ``.. list-table::`` with columns: +- Component +- Structural role +- Source class + +Add a short explanatory paragraph below the table when useful. + +Construction +~~~~~~~~~~~~ +Explain how the structure is built from ESDL connectivity. Describe the construction process at +a conceptual level grounded in the source; do not turn this into a class-by-class API walkthrough. + +Connectivity and Behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Explain the structural rules that govern the topic: +1. what the rule is, +2. why it matters for a valid/solvable network, +3. the practical consequence for users configuring or interpreting a network. + +Use equations only to clarify a structural constraint (for example, counting equations against +unknowns at a node). Do not use equations to restate asset-internal physics that belongs in +``doc/physics`` — cross-link instead. + +Assumptions +~~~~~~~~~~~ +Use short bullets when that improves readability. +State structural assumptions users need for correct interpretation. + +Limitations +~~~~~~~~~~~ +Use short bullets. +State what is structurally simplified, omitted, or idealized. +Mention when a more detailed network representation is needed. + +See Also / References +~~~~~~~~~~~~~~~~~~~~~~ +Cross-link to the relevant ``doc/physics`` asset page(s), ``doc/network/network_main.rst``, and +the relevant ``doc/reference/`` or generated API page(s) with ``:doc:``/``:ref:`` prose. Do not +invent references. Do not re-toctree a page already toctreed elsewhere. + +Style rules +----------- +See [Documentation Architecture](../instructions/documentation-architecture.instructions.md) for the shared style rules. In addition: +- Use end-user-oriented language; match the tone and approximate length of existing + ``doc/network`` and ``doc/physics`` pages. +- Prefer short paragraphs with direct structural interpretation; be explanatory where needed, + but concise. +- Avoid textbook density. +- Avoid implementation-oriented wording beyond what is needed to ground structural claims. +- Avoid unnecessary bullets outside tables, assumptions, and limitations. + +reStructuredText requirements +------------------------------ +See [Documentation Architecture](../instructions/documentation-architecture.instructions.md) for the shared output-format requirements. In addition: +- Use ``.. list-table::`` for representation tables. +- Use ``.. math::`` sparingly, only for structural constraints, not asset physics. + +Final check before writing +---------------------------- +Ensure that the page: +- reads like it belongs beside ``doc/network/network_main.rst`` and the ``doc/physics`` pages, +- stays focused on structure and construction rather than asset physics, controller decisions, + solver mechanics, or API reference, +- cross-links to the correct owning page instead of restating its content, +- explains structural assumptions and limitations clearly, +- does not introduce a second toctree path to a page already toctreed elsewhere. + +Validation +---------- +After writing or updating the file in ``doc/network``: + +1. Verify that the new or edited ``.rst`` file is valid reStructuredText. +2. Check that section headings, ``.. list-table::`` blocks, math blocks, references, and + indentation are syntactically valid. +3. Verify that all required sections are present in the correct order, except optional sections + that may be omitted by rule. +4. Verify that terminology, heading style, and table style match + ``doc/network/network_main.rst`` and the closest existing ``doc/physics`` page. +5. Check that the page does not introduce warnings or errors in the documentation build, + especially in ``doc/network``. +6. Verify that the page does not introduce a second toctree path to a page already toctreed + from ``doc/network_main.rst``, the curated ``doc/reference/`` tier, or the generated API tree. +7. If command execution or validation tools are available, run ``doc/run_spinx.bat`` from the + repository root as the preferred validation command. +8. Inspect the build or validation output for errors and warnings related to the new or edited + page, including reStructuredText syntax errors, malformed tables, invalid math blocks, broken + references, and indentation or heading issues. +9. If an error or warning is found, fix it before returning the final content. +10. Do not consider the task complete if the new or edited documentation introduces a build + error or warning in ``doc/network``, restates content owned by another specialist agent, or + introduces a duplicate toctree path. diff --git a/doc/network/network_main.rst b/doc/network/network_main.rst index c632748a..b47a2b00 100644 --- a/doc/network/network_main.rst +++ b/doc/network/network_main.rst @@ -6,6 +6,14 @@ It focuses on connectivity, communication between nodes and assets, and how netw The network model is configured from ESDL-derived assets and represented as connected components and nodes. At each simulation step, setpoints from the controller are applied to assets, the network equations are assembled, and solver results are propagated back to entities. +Network layer pages +------------------- + +.. toctree:: + :maxdepth: 1 + + network_topology + Implementation reference ------------------------- diff --git a/doc/network/network_topology.rst b/doc/network/network_topology.rst new file mode 100644 index 00000000..edf66831 --- /dev/null +++ b/doc/network/network_topology.rst @@ -0,0 +1,168 @@ +Network Topology +================ + +Overview +-------- + +This page describes how the heat-network graph is represented internally, how it is +assembled from ESDL connectivity, and how it is partitioned into sub-networks. It is +intended for users, modelers, and integrators who need to understand the network data +model and its relationship to simulation behavior. + +For a conceptual overview of connectivity and communication between assets and the +solver, see :doc:`network_main`. For solver-side class details, see +:doc:`../reference/solver_reference`. + +Representation +-------------- + +The network is represented as a graph of *assets* and *nodes*. Assets model +physical components (pipes, producers, consumers, heat exchangers, storage). Nodes +model the connection points between assets where hydraulic and thermal state is shared. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Component + - Structural role + * - ``Network`` + - Top-level graph container; holds all assets and nodes and provides connection + logic. + * - ``BaseAsset`` + - Solver-side asset element; carries one or more numbered connection points, each + of which is linked to exactly one ``Node``. + * - ``Node`` + - Solver-side node element; represents a shared hydraulic and thermal state point; + records all (asset, connection-point) pairs attached to it. + * - ``Junction`` + - Entity-level wrapper around a solver ``Node``; carries physical attributes such + as nominal pressure, fluid temperature, and height. + * - ``HeatNetwork`` + - Entity-level network container; owns a solver ``Network``, a list of asset + entities, and a list of ``Junction`` objects. + +For class and implementation details see :doc:`../reference/solver_reference`. + +Each asset exposes a fixed number of connection points (typically two: inlet at index 0 +and outlet at index 1). Each connection point maps to a single ``Node``; a node may be +shared by any number of asset connection points, representing a physical junction between +components. + +The solver ``Network`` stores assets and nodes in plain dictionaries, keyed by UUID +string. This allows the solver to enumerate all items when assembling the equation +system. + +Construction +------------ + +The network is built from an ESDL energy-system description during simulation +initialization. Construction proceeds in two steps. + +**Step 1 — Asset conversion** + +Each enabled ESDL asset is translated into an entity that carries a solver-side +representation and an ordered list of port identifiers that preserve ESDL connection +order. ESDL ``Joint`` elements are not converted in this step; they are resolved in +step 2. + +**Step 2 — Junction creation and connectivity** + +For each converted asset, every connection point is resolved against the ESDL +connectivity description to identify the neighbouring asset and port. If the connection +passes through a ``Joint``, the joint is absorbed and the two flanking assets are +connected directly; no solver node is created for the joint itself. + +Nodes are created and shared as connections are wired: + +- If neither side has a node yet, a new node is created and both sides are wired to it. +- If one side already has a node, the other side is wired to the same node. +- If both sides already have separate nodes, those nodes are merged into one and all + existing connections are rewired accordingly. + +Each resulting shared node is recorded as a ``Junction`` in the network. + +Sub-network partitioning +------------------------ + +The controller layer partitions the full asset graph into hydraulically independent +sub-networks. This partitioning is driven by the presence of heat transfer assets (heat +exchangers and heat pumps), which form the boundaries between primary and secondary +circuit sides. + +An intermediate graph is constructed from the ESDL topology. Each non-heat-transfer +asset is represented as a single node in this graph; each heat transfer asset is +represented as two nodes reflecting the hydraulic separation of its primary and secondary +sides. ESDL port connections are translated into graph edges. + +Assets are then assigned to sub-networks through graph reachability: + +1. Heat transfer assets are grouped first; their primary and secondary sides anchor + separate sub-network boundaries. +2. All remaining assets (producers, consumers, storage) are assigned to the sub-network + whose boundary nodes are reachable from that asset. + +When no heat transfer assets are present, all assets belong to a single sub-network. + +The partitioning determines which producers, consumers, and storage devices share a +common hydraulic circuit. The controller dispatches setpoints per sub-network, and the +conversion factors across heat transfer assets relate thermal demands between connected +sub-networks. How those setpoints are computed and applied is the responsibility of the +controller; see :doc:`../reference/controller_reference`. + +Node connectivity rules +----------------------- + +Each asset connection point is linked to at most one node. A node may be connected to +any number of asset connection points. The continuity and energy-balance equations +assembled at each node require at least one connected asset; isolated nodes are not +meaningful in the solved system. + +At a node with :math:`n` connected asset ports, the solver enforces one mass-flow +continuity equation: + +.. math:: + + \sum_{i=1}^{n} \dot{m}_i = 0 + +This single constraint accounts for conservation at the junction. Connected assets +contribute their own pressure and thermal relations at that node. See +:doc:`../physics/junction_physics` for the full set of node equations. + +Assumptions +----------- + +- Only ESDL assets with state ``ENABLED`` are included in the network; disabled assets + are silently skipped during construction. +- ESDL ``Joint`` elements are absorbed into junctions during construction; they do not + produce standalone solver nodes or equation contributions. +- Heat transfer assets are the only structural boundaries between sub-networks; all + other assets within a connected graph component belong to the same sub-network. +- Each asset connection point connects to exactly one node; fan-out at a single port is + not directly supported and must be modelled via explicit junction assets. +- The partitioning into sub-networks is performed once at construction time and does not + change during the simulation. + +Limitations +----------- + +- The sub-network partitioning uses undirected graph reachability and does not account + for flow direction or valve states; topological isolation by closing a valve is not + reflected in the sub-network structure. +- Merging of solver nodes during construction may produce a network structure that differs + from a naive one-node-per-ESDL-port interpretation when multiple ESDL connections share + a port. +- ESDL assets not covered by a registered mapper raise ``NotImplementedError`` and + cannot be included in the network. +- The graph used for sub-network detection is derived from the ESDL file topology, not + from the solved hydraulic state; circuits that become hydraulically isolated at runtime + (for example, due to zero-flow heat exchangers) are not reflected as separate + sub-networks. + +See Also +-------- + +- :doc:`network_main` — conceptual overview of network connectivity and simulation communication. +- :doc:`../physics/junction_physics` — node-level mass flow, energy, and pressure equations. +- :doc:`../reference/solver_reference` — solver-side network class and asset implementation details. +- :doc:`../reference/controller_reference` — controller-side sub-network behavior and dispatch. From fc00667becbac265e0a612c2902d37e308db3289 Mon Sep 17 00:00:00 2001 From: Mike van Meerkerk Date: Thu, 25 Jun 2026 16:28:19 +0200 Subject: [PATCH 04/11] Update intro --- .github/agents/DocReviewAgent.agent.md | 37 +++++++++ .../agents/DocumentationCoordinator.agent.md | 81 ++++++++++++++++++- .github/agents/SphinxValidationAgent.agent.md | 4 + .github/agents/SystemConceptDocAgent.agent.md | 22 ++++- doc/intro/audience_and_use_cases.rst | 26 ------ doc/intro/intro_main.rst | 81 ++++++++++++------- doc/intro/package_scope.rst | 29 ------- doc/intro/simulation_input_and_output.rst | 32 -------- doc/solver/solver_convergence.rst | 2 +- 9 files changed, 195 insertions(+), 119 deletions(-) delete mode 100644 doc/intro/audience_and_use_cases.rst delete mode 100644 doc/intro/package_scope.rst delete mode 100644 doc/intro/simulation_input_and_output.rst diff --git a/.github/agents/DocReviewAgent.agent.md b/.github/agents/DocReviewAgent.agent.md index 6bc08eb0..0b252ad6 100644 --- a/.github/agents/DocReviewAgent.agent.md +++ b/.github/agents/DocReviewAgent.agent.md @@ -164,6 +164,25 @@ Flag the following as errors: correlations owned by ``PhysicsAssetDocAgent`` instead of cross-linking, or restating the conceptual solver pages. +Intro-specific review rules +--------------------------- +Treat intro documentation as four distinct page intents: + +1. Intro landing and orientation +2. Scope and boundaries +3. Audience and use cases +4. Input/output and execution contract + +Flag the following as errors: +- boundary pages restating detailed runtime execution steps, +- audience pages restating detailed input/output contract material, +- input/output pages omitting a concrete ESDL-to-result execution path, +- intro pages that answer multiple intro intents without a clear separation, +- an intro subpage repeating the same cross-link target across more than one navigation + section (for example, an audience's "first stop" link reappearing verbatim in a later + "where to continue"/"see also" list, or a navigation section silently dropping an audience + covered everywhere else on the page). + Control-specific review rules ----------------------------- Treat control documentation as four distinct documentation types: @@ -183,6 +202,24 @@ Flag the following as errors: - contributor control guides drifting into end-user explanation as their primary purpose, - controller API reference pages containing long narrative explanation better suited for conceptual docs or developer guides. +Network-specific review rules +------------------------------ +Treat network documentation as two distinct documentation types: + +1. Network conceptual documentation +2. Network layer structure documentation + +Review network pages against these distinctions. + +Flag the following as errors: +- the conceptual network page (``doc/network/network_main.rst``) drifting into detailed + topology/representation, ESDL-construction, or sub-network partitioning detail, +- network layer structure pages drifting into bare API reference, re-deriving asset-internal + physics equations owned by ``PhysicsAssetDocAgent`` instead of cross-linking, restating + controller dispatch decisions owned by ``ControllerBehaviorDocAgent``, restating solver + equation-assembly mechanics owned by ``SolverBehaviorDocAgent``, or restating the conceptual + network page. + Completeness review by page type -------------------------------- Review each page according to its type. diff --git a/.github/agents/DocumentationCoordinator.agent.md b/.github/agents/DocumentationCoordinator.agent.md index f0a82aaa..e2d389b8 100644 --- a/.github/agents/DocumentationCoordinator.agent.md +++ b/.github/agents/DocumentationCoordinator.agent.md @@ -5,6 +5,7 @@ argument-hint: Documentation goal, affected sections/pages, and scope constraint tools: [read, search, edit, execute/runInTerminal, web, agent] agents: - SystemConceptDocAgent + - NetworkLayerDocAgent - PhysicsAssetDocAgent - SolverBehaviorDocAgent - ControllerBehaviorDocAgent @@ -89,6 +90,7 @@ Classify each task into one of the following documentation types: - Solver conceptual documentation - Solver behavior and physical impact - Network conceptual documentation +- Network layer structure documentation - Physics asset documentation - User-facing control concepts - Controller behavior and physical impact @@ -99,6 +101,27 @@ Classify each task into one of the following documentation types: - Support documentation - Navigation/index/toctree maintenance +Intro documentation refinement +----------------------------- +Treat intro documentation as a single consolidated page intent, authored entirely in +``doc/intro/intro_main.rst``. The page must cover, concisely and in this order: + +1. Overview — what OMOTES.SIMULATOR_CORE is. +2. What It Does — scope and boundaries (what simulator-core includes and excludes). +3. Why It Is Used — audience and use cases (who uses the package and what + decisions/questions it supports). +4. Example — the concrete ESDL-to-result run contract, with a trimmed runnable code + example and a short walkthrough, cross-referencing ``README.md`` for the full example. +5. Related Documentation — links to the adjacent sections. + +Intro decision rule +------------------- +Do not split intro content into multiple pages or sub-tasks. Keep the page short +(mesido-style brevity: short prose sections, not a page per audience/topic). If a request +would grow the page into a long, multi-topic essay, push the excess detail out via +cross-links to the relevant Solver/Network/Physics/Control/Developer pages rather than +adding a new intro subpage. + Solver documentation refinement -------------------------------- Treat solver documentation as two distinct types: @@ -115,6 +138,21 @@ Treat solver documentation as two distinct types: solving that system changes the solved physical model, at a level of detail comparable to the physics asset pages (``doc/solver/solver_behavior.rst``) +Network documentation refinement +--------------------------------- +Treat network documentation as two distinct types: + +- Network conceptual documentation: + short, high-level overview of connectivity and communication between assets and the + solver/controller, for users and integrators (``doc/network/network_main.rst``) + +- Network layer structure documentation: + detailed, source-grounded explanation of how the network graph is represented (nodes, + junctions, connection points), how it is constructed from ESDL connectivity, and how it is + partitioned into sub-networks, at a level of detail comparable to the physics asset pages + (``doc/network/network_topology.rst``, ``network_construction.rst``, + ``network_boundary_conditions.rst``, ``network_subnetworks.rst``, and similar topic pages) + Control documentation refinement -------------------------------- Treat control as four distinct documentation types: @@ -154,6 +192,9 @@ Delegate work according to the following rules: - Network conceptual documentation Route to: ``SystemConceptDocAgent`` +- Network layer structure documentation + Route to: ``NetworkLayerDocAgent`` + - Physics asset documentation Route to: ``PhysicsAssetDocAgent`` @@ -198,6 +239,21 @@ If a solver-related request is ambiguous, classify by the primary question being When a request mixes both, split it into separate sub-tasks and assign them separately. Do not allow a single page to serve both purposes. +Network decision rule +---------------------- +If a network-related request is ambiguous, classify by the primary question being answered: + +- "How is the network represented conceptually?" or "How does the network communicate with the + solver and controller during simulation?" + => network conceptual documentation + +- "How is the network graph structured/represented?", "how is it built from ESDL?", or "how is + it partitioned into sub-networks?" + => network layer structure documentation + +When a request mixes both, split it into separate sub-tasks and assign them separately. Do not +allow a single page to serve both purposes. + Control decision rule --------------------- If a control-related request is ambiguous, classify by the primary question being answered: @@ -264,7 +320,10 @@ Use the following ownership model: - ``NavigationAgent`` for Solver section landing pages and toctree consistency - Network - owned by: ``SystemConceptDocAgent`` + ``NavigationAgent`` + owned by: + - ``SystemConceptDocAgent`` for the conceptual network landing page + - ``NetworkLayerDocAgent`` for the detailed network layer structure pages + - ``NavigationAgent`` for Network section landing pages and toctree consistency - Physics owned by: ``PhysicsAssetDocAgent`` + ``NavigationAgent`` @@ -364,9 +423,13 @@ Use these cues when classifying requests: tolerance", "pressure-drop closure", "physical impact of the solve" => Solver behavior and physical impact -- "how is the network represented", "nodes", "connections", "communication" +- "how is the network represented", "communication between assets and solver/controller" => Network conceptual documentation +- "network topology", "node/junction connectivity", "how is the network built from ESDL", + "sub-network partitioning", "connection points" + => Network layer structure documentation + - "control behavior", "setpoint propagation", "operating logic", "what does control do" => User-facing control concepts @@ -410,6 +473,7 @@ Prevent duplication across sections. In particular: - Solver, Network, and Control pages may describe system behavior conceptually, but should not repeat asset-level physics details already owned by ``PhysicsAssetDocAgent``. +- Network layer structure pages may describe topology, construction, and partitioning in detail, but should not repeat asset-level physics, controller dispatch decisions, or solver equation-assembly mechanics owned by other specialist agents. - Developer guide pages may describe extension workflows, but should not duplicate autogenerated API reference. - API reference pages must not contain long narrative explanations that belong in the developer guide. @@ -424,6 +488,19 @@ Do not allow solver documentation to collapse into a mixed page type. - ``APIReferenceAgent`` must not write long narrative explanations that belong in conceptual docs or the solver behavior page +Network duplication control +---------------------------- +Do not allow network documentation to collapse into a mixed page type. + +- ``SystemConceptDocAgent`` must not write the detailed network structure, ESDL-construction, or + sub-network partitioning detail as part of the conceptual network page +- ``NetworkLayerDocAgent`` must not restate the conceptual network page, re-derive asset-internal + physics equations owned by ``PhysicsAssetDocAgent``, restate controller dispatch decisions + owned by ``ControllerBehaviorDocAgent``, restate solver equation-assembly mechanics owned by + ``SolverBehaviorDocAgent``, or become API reference +- ``APIReferenceAgent`` must not write long narrative explanations that belong in conceptual docs + or the network layer structure pages + Control duplication control --------------------------- Do not allow control documentation to collapse into a mixed page type. diff --git a/.github/agents/SphinxValidationAgent.agent.md b/.github/agents/SphinxValidationAgent.agent.md index cbdba830..70ffa7ba 100644 --- a/.github/agents/SphinxValidationAgent.agent.md +++ b/.github/agents/SphinxValidationAgent.agent.md @@ -5,6 +5,7 @@ argument-hint: Validation goal, target docs/files or scope of build validation, tools: [read, search, edit, execute/runInTerminal, web, agent] agents: - PhysicsAssetDocAgent + - NetworkLayerDocAgent - SystemConceptDocAgent - DeveloperGuideAgent - APIReferenceAgent @@ -157,6 +158,9 @@ Examples: - solver or network conceptual page with broken section structure or cross-links => ``SystemConceptDocAgent`` +- end-user network layer structure page with malformed structure or cross-links + => ``NetworkLayerDocAgent`` + - developer guide with malformed list-tables or incorrect workflow-linked references => ``DeveloperGuideAgent`` diff --git a/.github/agents/SystemConceptDocAgent.agent.md b/.github/agents/SystemConceptDocAgent.agent.md index 994242a4..fae661ee 100644 --- a/.github/agents/SystemConceptDocAgent.agent.md +++ b/.github/agents/SystemConceptDocAgent.agent.md @@ -72,8 +72,7 @@ Before writing, inspect the closest matching existing documentation page and pre 1. Follow repository documentation style first, especially: - ``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 Intro pages: ``doc/intro/intro_main.rst`` (the single consolidated intro page) - For Solver pages: ``doc/solver/solver_main.rst`` - For Network pages: ``doc/network/network_main.rst`` - For Control pages: ``doc/controller/controller.rst`` @@ -148,6 +147,25 @@ Classify the page intent as follows: - ``Control``: current control concepts, setpoint propagation, operating logic at a conceptual level, and the user-visible consequences of control actions +Intro single-page rule +---------------------- +Keep the entire Intro in one page, ``doc/intro/intro_main.rst``. Do not split it into +subpages. The page must answer, in this order, as short prose/bullet sections: + +1. Overview — what OMOTES.SIMULATOR_CORE is. +2. What It Does — scope boundaries (what is in scope and out of scope). +3. Why It Is Used — audience and use cases (who uses the package and what + decisions/questions it supports). +4. Example — one concrete ESDL-to-result path at a conceptual level (ESDL model -> + EsdlObject -> SimulationConfiguration -> SimulationManager.execute -> DataFrame), with a + trimmed runnable code example, cross-linking to ``README.md`` for the full example and to + existing architecture/reference documentation for deeper details. +5. Related Documentation — links to adjacent sections. + +Do not list the same cross-link target in more than one navigation section. Keep the page +concise (mesido-style brevity) rather than growing it into a long, multi-topic essay; push +excess depth out via cross-links instead of adding new intro subpages. + Do not use this agent to document: - how to extend control classes as a contributor, - how to add a new asset in code, diff --git a/doc/intro/audience_and_use_cases.rst b/doc/intro/audience_and_use_cases.rst deleted file mode 100644 index bd939b31..00000000 --- a/doc/intro/audience_and_use_cases.rst +++ /dev/null @@ -1,26 +0,0 @@ -Audience and use cases -====================== - -This package serves multiple audiences. The documentation is structured so each audience can move to -relevant sections without mixing responsibilities. - -Primary audiences ------------------ - -- End users and modelers: run simulations, interpret results, compare operational behavior -- Integrators: connect simulator execution to surrounding tooling and workflows -- Contributors: extend package capabilities while preserving simulation correctness - -Typical use cases ------------------ - -- Evaluate design alternatives for thermal networks -- Compare control strategies under changing demand and source availability -- Assess expected hydraulic and thermal behavior across simulation periods - -Where to continue ------------------ - -- End-user conceptual details: :doc:`../solver/solver_main`, :doc:`../network/network_main`, :doc:`../physics/physics_main`, :doc:`../controller/controller` -- Contributor workflows and API material: :doc:`../developer/developer_main` -- Support and issue handling: :doc:`../support/support` diff --git a/doc/intro/intro_main.rst b/doc/intro/intro_main.rst index 908e6894..525dbe1b 100644 --- a/doc/intro/intro_main.rst +++ b/doc/intro/intro_main.rst @@ -4,45 +4,72 @@ Introduction Overview -------- -OMOTES.SIMULATOR_CORE is the simulation package used to evaluate thermo-hydraulic behavior in district -heating systems. It provides the package-level entry point for understanding what the simulator does, -how the main subsystems fit together, and how to interpret the results that come out of a run. +OMOTES.SIMULATOR_CORE is the simulation engine used to evaluate thermo-hydraulic behavior in +district heating systems. Given a network description in ESDL format, a start/stop time, and a +timestep, it computes how hydraulic and thermal state evolves over the simulation period and +returns the result as a time series. -What OMOTES.SIMULATOR_CORE Does ------------------------------- +What It Does +------------ -The package turns a time-based system description into simulation results. In practice, it combines the -network structure, asset behavior, control setpoints, and solver execution needed to compute how the -system evolves over time. +The package combines four things to produce a result: network topology, asset physics, control +setpoints, and solver execution. At each timestep, setpoints are applied, the network equations are +assembled and solved, and the resulting state is recorded. -This introductory section keeps the focus on the overall package rather than on implementation detail. -Use it to understand the scope of the simulator before moving into the solver, network, physics, and -control sections. +In scope: + +- Time-stepped simulation of hydraulic and thermal behavior +- Integration of network topology, asset physics, and controller setpoints +- Deterministic results for a given model and run configuration + +Out of scope: + +- Interactive visualization dashboards and scenario authoring tools +- Site-specific deployment and operational orchestration +- Generic data platform concerns not required for simulation execution Why It Is Used --------------- +--------------- -The package is used when you need to study how a district-heating system behaves under changing demand, -network conditions, and control decisions. It supports modelers and integrators who want to compare -scenarios, interpret operational behavior, or connect simulation results to surrounding tooling. +The package is used to study how a district-heating system behaves under changing demand, network +conditions, and control decisions: -Typical use is to answer questions such as whether a configuration can meet demand, how a control -strategy affects system response, or what thermal and hydraulic trends appear over a simulation period. +- **End users and modelers** compare scenarios and interpret operational behavior — whether a + configuration meets demand, or how a control strategy affects system response. +- **Integrators** connect simulation runs to surrounding tooling and workflows. +- **Contributors** extend package capabilities while preserving simulation correctness. -Contents --------- +Example +------- -.. toctree:: - :maxdepth: 1 +A run is defined by an ESDL model and a time configuration, and returns a pandas ``DataFrame`` of +results: - package_scope - audience_and_use_cases - simulation_input_and_output +.. code-block:: python -Related Documentation ---------------------- + from omotes_simulator_core.entities.esdl_object import EsdlObject + from omotes_simulator_core.entities.simulation_configuration import SimulationConfiguration + from omotes_simulator_core.infrastructure.simulation_manager import SimulationManager + from omotes_simulator_core.infrastructure.utils import pyesdl_from_file -For the next level of detail, see: + config = SimulationConfiguration( + simulation_id=uuid.uuid1(), + name="test run", + timestep=3600, + start=datetime.strptime("2019-01-01T00:00:00", "%Y-%m-%dT%H:%M:%S"), + stop=datetime.strptime("2019-01-01T01:00:00", "%Y-%m-%dT%H:%M:%S"), + ) + + sim = SimulationManager(EsdlObject(pyesdl_from_file("path/to/file.esdl")), config) + result = sim.execute(progressLogger) + +The ESDL model is loaded and wrapped as an ``EsdlObject``; run parameters (start/stop, timestep) +are captured in a ``SimulationConfiguration``; ``SimulationManager`` ties the two together; and +``execute`` runs the timestep loop and returns the result ``DataFrame``. See ``README.md`` for the +full runnable example, including progress reporting. + +Related Documentation +---------------------- - :doc:`../solver/solver_main` for solver behavior and numerical execution. - :doc:`../network/network_main` for network representation and connectivity concepts. diff --git a/doc/intro/package_scope.rst b/doc/intro/package_scope.rst deleted file mode 100644 index e76d8342..00000000 --- a/doc/intro/package_scope.rst +++ /dev/null @@ -1,29 +0,0 @@ -Package scope -============= - -OMOTES.SIMULATOR_CORE provides the simulation engine used to evaluate district-heating behavior over -time. It focuses on thermo-hydraulic state evolution in a network of connected assets. - -What is in scope ----------------- - -- Time-stepped simulation of hydraulic and thermal behavior -- Integration of network topology, asset physics, and controller setpoints -- Execution on ESDL-based model definitions - -What is out of scope --------------------- - -- Interactive visualization dashboards and scenario authoring tools -- Site-specific deployment and operational orchestration -- Generic data platform concerns not required for simulation execution - -Package boundaries ------------------- - -At a high level, simulation behavior is produced by collaboration between: - -- Solver: assembles and solves the network equation system -- Network representation: maintains connected nodes and assets -- Physics models: define asset-specific constitutive behavior -- Controller: computes per-step setpoints and dispatch decisions diff --git a/doc/intro/simulation_input_and_output.rst b/doc/intro/simulation_input_and_output.rst deleted file mode 100644 index 84acb2ed..00000000 --- a/doc/intro/simulation_input_and_output.rst +++ /dev/null @@ -1,32 +0,0 @@ -Simulation input and output -=========================== - -A simulation run is defined by a model description and a time configuration. The package then returns -structured time-series results for analysis and integration. - -Input model ------------ - -Simulation input is based on ESDL (Energy System Description Language). ESDL assets and topology are -mapped into simulator entities before execution. - -Run configuration ------------------ - -A run is configured with: - -- Simulation start and stop datetime -- Timestep duration -- Simulation identifiers and metadata used by calling workflows - -Output ------- - -Simulation output is provided as time-series data for relevant hydraulic and thermal quantities over -the configured period. - -See also --------- - -- Package usage examples in the repository README -- Solver and physics sections for interpretation of state variables and governing relations diff --git a/doc/solver/solver_convergence.rst b/doc/solver/solver_convergence.rst index 2326021c..dafef6e7 100644 --- a/doc/solver/solver_convergence.rst +++ b/doc/solver/solver_convergence.rst @@ -61,4 +61,4 @@ 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 +- For simulation-loop context, see :doc:`../intro/intro_main`. \ No newline at end of file From 98c48b2447b15c865db2e7fdfe19852e1e6fff08 Mon Sep 17 00:00:00 2001 From: Mike van Meerkerk Date: Thu, 25 Jun 2026 16:48:15 +0200 Subject: [PATCH 05/11] Update network topology part --- .github/agents/DocReviewAgent.agent.md | 23 +- .../agents/DocumentationCoordinator.agent.md | 72 ++--- .github/agents/NetworkLayerDocAgent.agent.md | 261 ------------------ .github/agents/SphinxValidationAgent.agent.md | 4 - .github/agents/SystemConceptDocAgent.agent.md | 25 +- doc/network/network_main.rst | 169 +++++++++++- doc/network/network_topology.rst | 168 ----------- 7 files changed, 208 insertions(+), 514 deletions(-) delete mode 100644 .github/agents/NetworkLayerDocAgent.agent.md delete mode 100644 doc/network/network_topology.rst diff --git a/.github/agents/DocReviewAgent.agent.md b/.github/agents/DocReviewAgent.agent.md index 0b252ad6..c8286c01 100644 --- a/.github/agents/DocReviewAgent.agent.md +++ b/.github/agents/DocReviewAgent.agent.md @@ -50,7 +50,8 @@ When reviewing, verify that each page belongs in the correct part of this struct Special attention: - Physics pages should remain asset-focused and end-user-oriented. -- Intro, Solver, Network, and conceptual Control pages should remain conceptual rather than implementation-heavy. +- Intro, Solver, and conceptual Control pages should remain conceptual rather than implementation-heavy. +- The Network page combines conceptual connectivity with source-grounded structural depth (representation, ESDL construction, sub-network partitioning) in one page; it should not, however, restate asset-internal physics, controller dispatch, or solver equation-assembly mechanics owned by other specialist agents. - Developer Documentation should remain contributor-facing. - API reference should remain generated reference rather than narrative documentation. - Support should remain concise and actionable. @@ -204,21 +205,15 @@ Flag the following as errors: Network-specific review rules ------------------------------ -Treat network documentation as two distinct documentation types: - -1. Network conceptual documentation -2. Network layer structure documentation - -Review network pages against these distinctions. +Network documentation is a single consolidated page (``doc/network/network_main.rst``) +covering connectivity/communication with the solver and controller together with +topology/representation, ESDL construction, and sub-network partitioning. Flag the following as errors: -- the conceptual network page (``doc/network/network_main.rst``) drifting into detailed - topology/representation, ESDL-construction, or sub-network partitioning detail, -- network layer structure pages drifting into bare API reference, re-deriving asset-internal - physics equations owned by ``PhysicsAssetDocAgent`` instead of cross-linking, restating - controller dispatch decisions owned by ``ControllerBehaviorDocAgent``, restating solver - equation-assembly mechanics owned by ``SolverBehaviorDocAgent``, or restating the conceptual - network page. +- the network page drifting into bare API reference, re-deriving asset-internal physics + equations owned by ``PhysicsAssetDocAgent`` instead of cross-linking, restating controller + dispatch decisions owned by ``ControllerBehaviorDocAgent``, or restating solver + equation-assembly mechanics owned by ``SolverBehaviorDocAgent``. Completeness review by page type -------------------------------- diff --git a/.github/agents/DocumentationCoordinator.agent.md b/.github/agents/DocumentationCoordinator.agent.md index e2d389b8..2537fcd1 100644 --- a/.github/agents/DocumentationCoordinator.agent.md +++ b/.github/agents/DocumentationCoordinator.agent.md @@ -5,7 +5,6 @@ argument-hint: Documentation goal, affected sections/pages, and scope constraint tools: [read, search, edit, execute/runInTerminal, web, agent] agents: - SystemConceptDocAgent - - NetworkLayerDocAgent - PhysicsAssetDocAgent - SolverBehaviorDocAgent - ControllerBehaviorDocAgent @@ -89,8 +88,7 @@ Classify each task into one of the following documentation types: - Intro documentation - Solver conceptual documentation - Solver behavior and physical impact -- Network conceptual documentation -- Network layer structure documentation +- Network documentation - Physics asset documentation - User-facing control concepts - Controller behavior and physical impact @@ -140,18 +138,13 @@ Treat solver documentation as two distinct types: Network documentation refinement --------------------------------- -Treat network documentation as two distinct types: - -- Network conceptual documentation: - short, high-level overview of connectivity and communication between assets and the - solver/controller, for users and integrators (``doc/network/network_main.rst``) - -- Network layer structure documentation: - detailed, source-grounded explanation of how the network graph is represented (nodes, - junctions, connection points), how it is constructed from ESDL connectivity, and how it is - partitioned into sub-networks, at a level of detail comparable to the physics asset pages - (``doc/network/network_topology.rst``, ``network_construction.rst``, - ``network_boundary_conditions.rst``, ``network_subnetworks.rst``, and similar topic pages) +Treat network documentation as a single consolidated page intent, authored entirely in +``doc/network/network_main.rst``. The page covers, in one place: connectivity and +communication between assets and the solver/controller, how the network graph is +represented (nodes, junctions, connection points), how it is constructed from ESDL +connectivity, and how it is partitioned into sub-networks. Depth comparable to the +physics asset pages is expected within this single page; do not split it into separate +topology/construction/sub-network pages. Control documentation refinement -------------------------------- @@ -189,12 +182,9 @@ Delegate work according to the following rules: - Solver behavior and physical impact Route to: ``SolverBehaviorDocAgent`` -- Network conceptual documentation +- Network documentation Route to: ``SystemConceptDocAgent`` -- Network layer structure documentation - Route to: ``NetworkLayerDocAgent`` - - Physics asset documentation Route to: ``PhysicsAssetDocAgent`` @@ -241,18 +231,10 @@ allow a single page to serve both purposes. Network decision rule ---------------------- -If a network-related request is ambiguous, classify by the primary question being answered: - -- "How is the network represented conceptually?" or "How does the network communicate with the - solver and controller during simulation?" - => network conceptual documentation - -- "How is the network graph structured/represented?", "how is it built from ESDL?", or "how is - it partitioned into sub-networks?" - => network layer structure documentation - -When a request mixes both, split it into separate sub-tasks and assign them separately. Do not -allow a single page to serve both purposes. +Do not split network content into multiple pages or sub-tasks. Whether the request is about +connectivity/communication with the solver and controller, or about graph +structure/representation, ESDL construction, or sub-network partitioning, route it to +``doc/network/network_main.rst``. Control decision rule --------------------- @@ -320,10 +302,7 @@ Use the following ownership model: - ``NavigationAgent`` for Solver section landing pages and toctree consistency - Network - owned by: - - ``SystemConceptDocAgent`` for the conceptual network landing page - - ``NetworkLayerDocAgent`` for the detailed network layer structure pages - - ``NavigationAgent`` for Network section landing pages and toctree consistency + owned by: ``SystemConceptDocAgent`` + ``NavigationAgent`` - Physics owned by: ``PhysicsAssetDocAgent`` + ``NavigationAgent`` @@ -423,12 +402,10 @@ Use these cues when classifying requests: tolerance", "pressure-drop closure", "physical impact of the solve" => Solver behavior and physical impact -- "how is the network represented", "communication between assets and solver/controller" - => Network conceptual documentation - -- "network topology", "node/junction connectivity", "how is the network built from ESDL", +- "how is the network represented", "communication between assets and solver/controller", + "network topology", "node/junction connectivity", "how is the network built from ESDL", "sub-network partitioning", "connection points" - => Network layer structure documentation + => Network documentation - "control behavior", "setpoint propagation", "operating logic", "what does control do" => User-facing control concepts @@ -473,7 +450,7 @@ Prevent duplication across sections. In particular: - Solver, Network, and Control pages may describe system behavior conceptually, but should not repeat asset-level physics details already owned by ``PhysicsAssetDocAgent``. -- Network layer structure pages may describe topology, construction, and partitioning in detail, but should not repeat asset-level physics, controller dispatch decisions, or solver equation-assembly mechanics owned by other specialist agents. +- The network page may describe topology, construction, and partitioning in detail, but should not repeat asset-level physics, controller dispatch decisions, or solver equation-assembly mechanics owned by other specialist agents. - Developer guide pages may describe extension workflows, but should not duplicate autogenerated API reference. - API reference pages must not contain long narrative explanations that belong in the developer guide. @@ -488,19 +465,6 @@ Do not allow solver documentation to collapse into a mixed page type. - ``APIReferenceAgent`` must not write long narrative explanations that belong in conceptual docs or the solver behavior page -Network duplication control ----------------------------- -Do not allow network documentation to collapse into a mixed page type. - -- ``SystemConceptDocAgent`` must not write the detailed network structure, ESDL-construction, or - sub-network partitioning detail as part of the conceptual network page -- ``NetworkLayerDocAgent`` must not restate the conceptual network page, re-derive asset-internal - physics equations owned by ``PhysicsAssetDocAgent``, restate controller dispatch decisions - owned by ``ControllerBehaviorDocAgent``, restate solver equation-assembly mechanics owned by - ``SolverBehaviorDocAgent``, or become API reference -- ``APIReferenceAgent`` must not write long narrative explanations that belong in conceptual docs - or the network layer structure pages - Control duplication control --------------------------- Do not allow control documentation to collapse into a mixed page type. diff --git a/.github/agents/NetworkLayerDocAgent.agent.md b/.github/agents/NetworkLayerDocAgent.agent.md deleted file mode 100644 index f5bcfa40..00000000 --- a/.github/agents/NetworkLayerDocAgent.agent.md +++ /dev/null @@ -1,261 +0,0 @@ ---- -name: NetworkLayerDocAgent -description: Create end-user network layer documentation in reStructuredText for doc/network, explaining how the network graph is represented, constructed from ESDL, and partitioned, at a level of source-grounded detail comparable to the physics asset pages. -argument-hint: Network topic name, page title, and output file name (for example: Network Topology, Network Topology and Connectivity, network_topology.rst). -tools: [read, search, edit, execute/runInTerminal, web] -agents: [] ---- - -You are a technical documentation agent. - -Your only task is to write end-user network layer documentation in valid reStructuredText for files in ``doc/network``. - -Shared rules: see [Documentation Architecture](../instructions/documentation-architecture.instructions.md) for the fixed section order, equation/notation rules, and build-validation command. The rules below are specific to network layer pages. - -Inputs ------- -- Network topic: ```` -- Page title: ```` -- Output file: ``network_.rst`` - -Primary objective ------------------ -Write documentation that helps end users, system modelers, and integrators understand: -- how the network graph is structurally represented (nodes, junctions, connection points, multi-port assets), -- how that structure is constructed from ESDL connectivity, -- how the network is partitioned into sub-networks, -- which structural rules and assumptions govern connectivity and partitioning, -- which limitations affect the network representation. - -Document the network's structure and construction. Do not document asset-internal physics -equations, controller dispatch decisions, solver equation-assembly/iteration mechanics, or -class-by-class API reference. - -Relationship to the rest of the Network documentation -------------------------------------------------------- -Network documentation is split across several owners. This agent owns exactly one part of it: - -- Network conceptual documentation (``doc/network/network_main.rst``): owned by - ``SystemConceptDocAgent`` — a short, high-level overview of connectivity and communication - between assets and the solver/controller. Cross-link to it; do not rewrite it. -- **Network layer structure documentation (this agent):** source-grounded detail on how the - network graph is represented, built from ESDL, and partitioned. -- Asset-internal physics and governing equations (mixing, heat loss, pressure drop, and similar - behavior owned by a specific asset, e.g. ``Junction``, ``Pipe``, producer/consumer assets) are - owned by ``PhysicsAssetDocAgent`` under ``doc/physics``. Link to the matching ``doc/physics`` - page; do not re-derive its equations. -- Controller dispatch, priority, curtailment, and other per-timestep decisions are owned by - ``ControllerBehaviorDocAgent``. Do not restate how sub-networks are used to make control - decisions; only explain how the network is partitioned into them. -- Solver equation-assembly and iteration mechanics are owned by ``SolverBehaviorDocAgent``. Do - not restate how the assembled equations are solved. -- Class/module API reference (``doc/solver/network.rst``, ``doc/controller/sub_network_class.rst``, - ``doc/reference/architecture_reference.rst``, and similar generated/curated reference pages) is - owned by ``APIReferenceAgent``. Cross-link to these with ``:doc:``/``:ref:`` prose; never add a - ``.. toctree::`` entry that duplicates a page already toctreed from the curated reference tier - or the generated API tree (single toctree path rule). - -Do not absorb any of these roles into a network layer structure page. - -Source priority ---------------- -Before writing, inspect ``doc/network/network_main.rst`` as the landing page and style anchor, -and the closest matching existing page in ``doc/network`` if one exists. - -1. Follow repository style first. Candidate ``doc/network`` pages and their matching - implementation source are: - - .. list-table:: - :header-rows: 1 - - * - doc/network page - - source file - * - network_topology.rst - - solver/network/network.py (``Network``), solver/network/assets/node.py (``Node``), - solver/network/assets/base_node_item.py - * - network_construction.rst - - entities/heat_network.py (``HeatNetwork``, ``conversion_factory``), - simulation/mappers/mappers.py, entities/esdl_object.py - * - network_boundary_conditions.rst - - solver/network/assets/boundary.py (``BaseBoundary``), - solver/network/assets/production_asset.py (``HeatBoundary``) - * - network_subnetworks.rst - - entities/network_controller.py (``NetworkController``), - entities/network_controller_abstract.py (``NetworkControllerAbstract``) - - Also use ``doc/network/network_main.rst`` as the section landing page and style anchor. - -Rules for source usage: -- Use repository sources only. -- Use ``doc/network/network_main.rst`` as the authoritative style baseline. -- Use the source file(s) matching the target topic (table above) to ground structural claims in - actual implementation, not invented behavior. -- If repository sources are missing or ambiguous for a claim, omit the claim rather than - inferring or importing external material. - -Audience and scope ------------------- -Audience: -- End users -- System modelers -- Integrators - -Scope: -- Network structure and construction only -- Topology, connectivity, and partitioning relevant to configuration and interpretation -- How the network graph is built from ESDL connectivity -- Structural assumptions and limitations that affect results - -Do not include: -- asset-internal physics, governing equations, or constitutive relations -- controller dispatch or priority decisions -- solver equation-assembly or iteration mechanics -- class-by-class API walkthroughs -- contributor extension workflow -- software architecture discussion beyond what is needed to explain network structure - -Content requirements ---------------------- -Include, where applicable: -- a conceptual description of the structural element being documented, -- the key classes/structures involved and the structural role each plays, -- how the structure is constructed (only for construction-focused topics), -- structural connectivity and partitioning rules, -- structural assumptions, -- structural limitations. - -Only include details that affect how users configure, interpret, or reason about the network -structure. - -Section order -------------- -Use the following section order for all sections that are present: - -1. Title -2. Description -3. Representation -4. Construction -5. Connectivity and Behavior -6. Assumptions -7. Limitations -8. See Also / References - -Optional sections: -- Omit ``Construction`` if the topic is not about how the structure is built from ESDL input. - -Classification rules ---------------------- -Classify content as follows: -- ``Representation``: the key classes/data structures involved and the structural role each - plays (for example: node, junction, connection point, multi-port asset, sub-network). -- ``Construction``: how the structure is derived/assembled from ESDL connectivity. -- ``Connectivity and Behavior``: structural rules governing how the network behaves as a graph - during simulation (connection validity, degrees of freedom, partitioning), not asset physics. -- ``Assumptions``: explicit structural assumptions collected in one place for correct - interpretation. -- ``Limitations``: structural simplifications and omissions, and cases where a more detailed - network representation is needed. - -Section requirements ----------------------- - -Description -~~~~~~~~~~~ -Explain: -- what structural element of the network this page covers, -- its role in the overall network graph, -- how users should interpret it when configuring or reasoning about a network. - -Representation -~~~~~~~~~~~~~~ -Use a ``.. list-table::`` with columns: -- Component -- Structural role -- Source class - -Add a short explanatory paragraph below the table when useful. - -Construction -~~~~~~~~~~~~ -Explain how the structure is built from ESDL connectivity. Describe the construction process at -a conceptual level grounded in the source; do not turn this into a class-by-class API walkthrough. - -Connectivity and Behavior -~~~~~~~~~~~~~~~~~~~~~~~~~~ -Explain the structural rules that govern the topic: -1. what the rule is, -2. why it matters for a valid/solvable network, -3. the practical consequence for users configuring or interpreting a network. - -Use equations only to clarify a structural constraint (for example, counting equations against -unknowns at a node). Do not use equations to restate asset-internal physics that belongs in -``doc/physics`` — cross-link instead. - -Assumptions -~~~~~~~~~~~ -Use short bullets when that improves readability. -State structural assumptions users need for correct interpretation. - -Limitations -~~~~~~~~~~~ -Use short bullets. -State what is structurally simplified, omitted, or idealized. -Mention when a more detailed network representation is needed. - -See Also / References -~~~~~~~~~~~~~~~~~~~~~~ -Cross-link to the relevant ``doc/physics`` asset page(s), ``doc/network/network_main.rst``, and -the relevant ``doc/reference/`` or generated API page(s) with ``:doc:``/``:ref:`` prose. Do not -invent references. Do not re-toctree a page already toctreed elsewhere. - -Style rules ------------ -See [Documentation Architecture](../instructions/documentation-architecture.instructions.md) for the shared style rules. In addition: -- Use end-user-oriented language; match the tone and approximate length of existing - ``doc/network`` and ``doc/physics`` pages. -- Prefer short paragraphs with direct structural interpretation; be explanatory where needed, - but concise. -- Avoid textbook density. -- Avoid implementation-oriented wording beyond what is needed to ground structural claims. -- Avoid unnecessary bullets outside tables, assumptions, and limitations. - -reStructuredText requirements ------------------------------- -See [Documentation Architecture](../instructions/documentation-architecture.instructions.md) for the shared output-format requirements. In addition: -- Use ``.. list-table::`` for representation tables. -- Use ``.. math::`` sparingly, only for structural constraints, not asset physics. - -Final check before writing ----------------------------- -Ensure that the page: -- reads like it belongs beside ``doc/network/network_main.rst`` and the ``doc/physics`` pages, -- stays focused on structure and construction rather than asset physics, controller decisions, - solver mechanics, or API reference, -- cross-links to the correct owning page instead of restating its content, -- explains structural assumptions and limitations clearly, -- does not introduce a second toctree path to a page already toctreed elsewhere. - -Validation ----------- -After writing or updating the file in ``doc/network``: - -1. Verify that the new or edited ``.rst`` file is valid reStructuredText. -2. Check that section headings, ``.. list-table::`` blocks, math blocks, references, and - indentation are syntactically valid. -3. Verify that all required sections are present in the correct order, except optional sections - that may be omitted by rule. -4. Verify that terminology, heading style, and table style match - ``doc/network/network_main.rst`` and the closest existing ``doc/physics`` page. -5. Check that the page does not introduce warnings or errors in the documentation build, - especially in ``doc/network``. -6. Verify that the page does not introduce a second toctree path to a page already toctreed - from ``doc/network_main.rst``, the curated ``doc/reference/`` tier, or the generated API tree. -7. If command execution or validation tools are available, run ``doc/run_spinx.bat`` from the - repository root as the preferred validation command. -8. Inspect the build or validation output for errors and warnings related to the new or edited - page, including reStructuredText syntax errors, malformed tables, invalid math blocks, broken - references, and indentation or heading issues. -9. If an error or warning is found, fix it before returning the final content. -10. Do not consider the task complete if the new or edited documentation introduces a build - error or warning in ``doc/network``, restates content owned by another specialist agent, or - introduces a duplicate toctree path. diff --git a/.github/agents/SphinxValidationAgent.agent.md b/.github/agents/SphinxValidationAgent.agent.md index 70ffa7ba..cbdba830 100644 --- a/.github/agents/SphinxValidationAgent.agent.md +++ b/.github/agents/SphinxValidationAgent.agent.md @@ -5,7 +5,6 @@ argument-hint: Validation goal, target docs/files or scope of build validation, tools: [read, search, edit, execute/runInTerminal, web, agent] agents: - PhysicsAssetDocAgent - - NetworkLayerDocAgent - SystemConceptDocAgent - DeveloperGuideAgent - APIReferenceAgent @@ -158,9 +157,6 @@ Examples: - solver or network conceptual page with broken section structure or cross-links => ``SystemConceptDocAgent`` -- end-user network layer structure page with malformed structure or cross-links - => ``NetworkLayerDocAgent`` - - developer guide with malformed list-tables or incorrect workflow-linked references => ``DeveloperGuideAgent`` diff --git a/.github/agents/SystemConceptDocAgent.agent.md b/.github/agents/SystemConceptDocAgent.agent.md index fae661ee..1df39635 100644 --- a/.github/agents/SystemConceptDocAgent.agent.md +++ b/.github/agents/SystemConceptDocAgent.agent.md @@ -142,7 +142,10 @@ Classify the page intent as follows: how the solver participates in timestep execution, convergence behavior, result interpretation, and the relation between solving and simulation progression - ``Network``: - how the network is represented conceptually, how assets and connectivity affect behavior, and how users should think about network-level interactions + how the network is represented conceptually and structurally — connectivity and + communication with the solver/controller, the graph representation (nodes, junctions, + connection points), how it is constructed from ESDL, and how it is partitioned into + sub-networks, in a single page - ``Control``: current control concepts, setpoint propagation, operating logic at a conceptual level, and the user-visible consequences of control actions @@ -166,6 +169,21 @@ Do not list the same cross-link target in more than one navigation section. Keep concise (mesido-style brevity) rather than growing it into a long, multi-topic essay; push excess depth out via cross-links instead of adding new intro subpages. +Network single-page rule +------------------------- +Keep the entire Network section in one page, ``doc/network/network_main.rst``. Do not split +it into topology/construction/sub-network subpages. The page covers, in order: Overview +(connectivity and communication with the solver/controller), Representation (a structural +component/role table — for example ``Network``, ``BaseAsset``, ``Node``, ``Junction``, +``HeatNetwork`` — grounded in source), Construction (how the graph is built from ESDL +connectivity), Sub-network partitioning, Node connectivity rules (including a concise +structural equation such as node mass-flow continuity where it clarifies a constraint), +Assumptions, Limitations, and Implementation reference. The structural component table and +construction/partitioning narrative are an explicit exception to the general "no +class-by-class API walkthrough" rule below — they describe structural role, not full API +detail, and must still cross-link to ``doc/physics`` and ``doc/reference`` rather than +re-deriving asset physics, controller dispatch, or solver equation-assembly mechanics. + Do not use this agent to document: - how to extend control classes as a contributor, - how to add a new asset in code, @@ -203,7 +221,10 @@ Only include details that improve user understanding or interpretation. Section order ------------- -Use the following section order for all sections that are present: +Use the following section order for all sections that are present, except where the +``Intro single-page rule`` or ``Network single-page rule`` above specifies a different, +page-specific order — those take precedence for ``doc/intro/intro_main.rst`` and +``doc/network/network_main.rst`` respectively: 1. Title 2. Overview diff --git a/doc/network/network_main.rst b/doc/network/network_main.rst index b47a2b00..d85a5b9d 100644 --- a/doc/network/network_main.rst +++ b/doc/network/network_main.rst @@ -1,24 +1,171 @@ Network layer -========================= -This section describes how assets are connected into a hydraulic network and how information is exchanged during simulation. -It focuses on connectivity, communication between nodes and assets, and how network behavior interacts with solver and controller flow. +============== -The network model is configured from ESDL-derived assets and represented as connected components and nodes. -At each simulation step, setpoints from the controller are applied to assets, the network equations are assembled, and solver results are propagated back to entities. +Overview +-------- -Network layer pages -------------------- +This section describes how assets are connected into a hydraulic network, how that +structure is represented and built from ESDL, and how information is exchanged during +simulation. It covers connectivity, communication between nodes and assets, and how +network behavior interacts with solver and controller flow. -.. toctree:: - :maxdepth: 1 +The network model is configured from ESDL-derived assets and represented as connected +components and nodes. At each simulation step, setpoints from the controller are applied +to assets, the network equations are assembled, and solver results are propagated back to +entities. - network_topology +Representation +--------------- + +The network is represented as a graph of *assets* and *nodes*. Assets model physical +components (pipes, producers, consumers, heat exchangers, storage). Nodes model the +connection points between assets where hydraulic and thermal state is shared. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Component + - Structural role + * - ``Network`` + - Top-level graph container; holds all assets and nodes and provides connection + logic. + * - ``BaseAsset`` + - Solver-side asset element; carries one or more numbered connection points, each + of which is linked to exactly one ``Node``. + * - ``Node`` + - Solver-side node element; represents a shared hydraulic and thermal state point; + records all (asset, connection-point) pairs attached to it. + * - ``Junction`` + - Entity-level wrapper around a solver ``Node``; carries physical attributes such + as nominal pressure, fluid temperature, and height. + * - ``HeatNetwork`` + - Entity-level network container; owns a solver ``Network``, a list of asset + entities, and a list of ``Junction`` objects. + +For class and implementation details see :doc:`../reference/solver_reference`. + +Each asset exposes a fixed number of connection points (typically two: inlet at index 0 +and outlet at index 1). Each connection point maps to a single ``Node``; a node may be +shared by any number of asset connection points, representing a physical junction between +components. + +The solver ``Network`` stores assets and nodes in plain dictionaries, keyed by UUID +string. This allows the solver to enumerate all items when assembling the equation +system. + +Construction +------------ + +The network is built from an ESDL energy-system description during simulation +initialization. Construction proceeds in two steps. + +**Step 1 — Asset conversion** + +Each enabled ESDL asset is translated into an entity that carries a solver-side +representation and an ordered list of port identifiers that preserve ESDL connection +order. ESDL ``Joint`` elements are not converted in this step; they are resolved in +step 2. + +**Step 2 — Junction creation and connectivity** + +For each converted asset, every connection point is resolved against the ESDL +connectivity description to identify the neighbouring asset and port. If the connection +passes through a ``Joint``, the joint is absorbed and the two flanking assets are +connected directly; no solver node is created for the joint itself. + +Nodes are created and shared as connections are wired: + +- If neither side has a node yet, a new node is created and both sides are wired to it. +- If one side already has a node, the other side is wired to the same node. +- If both sides already have separate nodes, those nodes are merged into one and all + existing connections are rewired accordingly. + +Each resulting shared node is recorded as a ``Junction`` in the network. + +Sub-network partitioning +------------------------- + +The controller layer partitions the full asset graph into hydraulically independent +sub-networks. This partitioning is driven by the presence of heat transfer assets (heat +exchangers and heat pumps), which form the boundaries between primary and secondary +circuit sides. + +An intermediate graph is constructed from the ESDL topology. Each non-heat-transfer +asset is represented as a single node in this graph; each heat transfer asset is +represented as two nodes reflecting the hydraulic separation of its primary and secondary +sides. ESDL port connections are translated into graph edges. + +Assets are then assigned to sub-networks through graph reachability: + +1. Heat transfer assets are grouped first; their primary and secondary sides anchor + separate sub-network boundaries. +2. All remaining assets (producers, consumers, storage) are assigned to the sub-network + whose boundary nodes are reachable from that asset. + +When no heat transfer assets are present, all assets belong to a single sub-network. + +The partitioning determines which producers, consumers, and storage devices share a +common hydraulic circuit. The controller dispatches setpoints per sub-network, and the +conversion factors across heat transfer assets relate thermal demands between connected +sub-networks. How those setpoints are computed and applied is the responsibility of the +controller; see :doc:`../reference/controller_reference`. + +Node connectivity rules +------------------------ + +Each asset connection point is linked to at most one node. A node may be connected to +any number of asset connection points. The continuity and energy-balance equations +assembled at each node require at least one connected asset; isolated nodes are not +meaningful in the solved system. + +At a node with :math:`n` connected asset ports, the solver enforces one mass-flow +continuity equation: + +.. math:: + + \sum_{i=1}^{n} \dot{m}_i = 0 + +This single constraint accounts for conservation at the junction. Connected assets +contribute their own pressure and thermal relations at that node. See +:doc:`../physics/junction_physics` for the full set of node equations. + +Assumptions +----------- + +- Only ESDL assets with state ``ENABLED`` are included in the network; disabled assets + are silently skipped during construction. +- ESDL ``Joint`` elements are absorbed into junctions during construction; they do not + produce standalone solver nodes or equation contributions. +- Heat transfer assets are the only structural boundaries between sub-networks; all + other assets within a connected graph component belong to the same sub-network. +- Each asset connection point connects to exactly one node; fan-out at a single port is + not directly supported and must be modelled via explicit junction assets. +- The partitioning into sub-networks is performed once at construction time and does not + change during the simulation. + +Limitations +----------- + +- The sub-network partitioning uses undirected graph reachability and does not account + for flow direction. +- Merging of solver nodes during construction may produce a network structure that differs + from a naive one-node-per-ESDL-port interpretation when multiple ESDL connections share + a port. +- ESDL assets not covered by a registered mapper raise ``NotImplementedError`` and + cannot be included in the network. +- The graph used for sub-network detection is derived from the ESDL file topology, not + from the solved hydraulic state; circuits that become hydraulically isolated at runtime + (for example, due to zero-flow heat exchangers) are not reflected as separate + sub-networks. Implementation reference ------------------------- For solver-side network class details, see :doc:`../reference/solver_reference`. For controller-side sub-network behavior, see :doc:`../reference/controller_reference`. For -network simulation orchestration, see :doc:`../reference/architecture_reference`. +network simulation orchestration, see :doc:`../reference/architecture_reference`. For +node-level mass flow, energy, and pressure equations, see +:doc:`../physics/junction_physics`. See also :ref:`network-class` for the solver-side network class and :ref:`sub_network_class` for controller-side sub-network behavior. diff --git a/doc/network/network_topology.rst b/doc/network/network_topology.rst deleted file mode 100644 index edf66831..00000000 --- a/doc/network/network_topology.rst +++ /dev/null @@ -1,168 +0,0 @@ -Network Topology -================ - -Overview --------- - -This page describes how the heat-network graph is represented internally, how it is -assembled from ESDL connectivity, and how it is partitioned into sub-networks. It is -intended for users, modelers, and integrators who need to understand the network data -model and its relationship to simulation behavior. - -For a conceptual overview of connectivity and communication between assets and the -solver, see :doc:`network_main`. For solver-side class details, see -:doc:`../reference/solver_reference`. - -Representation --------------- - -The network is represented as a graph of *assets* and *nodes*. Assets model -physical components (pipes, producers, consumers, heat exchangers, storage). Nodes -model the connection points between assets where hydraulic and thermal state is shared. - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Component - - Structural role - * - ``Network`` - - Top-level graph container; holds all assets and nodes and provides connection - logic. - * - ``BaseAsset`` - - Solver-side asset element; carries one or more numbered connection points, each - of which is linked to exactly one ``Node``. - * - ``Node`` - - Solver-side node element; represents a shared hydraulic and thermal state point; - records all (asset, connection-point) pairs attached to it. - * - ``Junction`` - - Entity-level wrapper around a solver ``Node``; carries physical attributes such - as nominal pressure, fluid temperature, and height. - * - ``HeatNetwork`` - - Entity-level network container; owns a solver ``Network``, a list of asset - entities, and a list of ``Junction`` objects. - -For class and implementation details see :doc:`../reference/solver_reference`. - -Each asset exposes a fixed number of connection points (typically two: inlet at index 0 -and outlet at index 1). Each connection point maps to a single ``Node``; a node may be -shared by any number of asset connection points, representing a physical junction between -components. - -The solver ``Network`` stores assets and nodes in plain dictionaries, keyed by UUID -string. This allows the solver to enumerate all items when assembling the equation -system. - -Construction ------------- - -The network is built from an ESDL energy-system description during simulation -initialization. Construction proceeds in two steps. - -**Step 1 — Asset conversion** - -Each enabled ESDL asset is translated into an entity that carries a solver-side -representation and an ordered list of port identifiers that preserve ESDL connection -order. ESDL ``Joint`` elements are not converted in this step; they are resolved in -step 2. - -**Step 2 — Junction creation and connectivity** - -For each converted asset, every connection point is resolved against the ESDL -connectivity description to identify the neighbouring asset and port. If the connection -passes through a ``Joint``, the joint is absorbed and the two flanking assets are -connected directly; no solver node is created for the joint itself. - -Nodes are created and shared as connections are wired: - -- If neither side has a node yet, a new node is created and both sides are wired to it. -- If one side already has a node, the other side is wired to the same node. -- If both sides already have separate nodes, those nodes are merged into one and all - existing connections are rewired accordingly. - -Each resulting shared node is recorded as a ``Junction`` in the network. - -Sub-network partitioning ------------------------- - -The controller layer partitions the full asset graph into hydraulically independent -sub-networks. This partitioning is driven by the presence of heat transfer assets (heat -exchangers and heat pumps), which form the boundaries between primary and secondary -circuit sides. - -An intermediate graph is constructed from the ESDL topology. Each non-heat-transfer -asset is represented as a single node in this graph; each heat transfer asset is -represented as two nodes reflecting the hydraulic separation of its primary and secondary -sides. ESDL port connections are translated into graph edges. - -Assets are then assigned to sub-networks through graph reachability: - -1. Heat transfer assets are grouped first; their primary and secondary sides anchor - separate sub-network boundaries. -2. All remaining assets (producers, consumers, storage) are assigned to the sub-network - whose boundary nodes are reachable from that asset. - -When no heat transfer assets are present, all assets belong to a single sub-network. - -The partitioning determines which producers, consumers, and storage devices share a -common hydraulic circuit. The controller dispatches setpoints per sub-network, and the -conversion factors across heat transfer assets relate thermal demands between connected -sub-networks. How those setpoints are computed and applied is the responsibility of the -controller; see :doc:`../reference/controller_reference`. - -Node connectivity rules ------------------------ - -Each asset connection point is linked to at most one node. A node may be connected to -any number of asset connection points. The continuity and energy-balance equations -assembled at each node require at least one connected asset; isolated nodes are not -meaningful in the solved system. - -At a node with :math:`n` connected asset ports, the solver enforces one mass-flow -continuity equation: - -.. math:: - - \sum_{i=1}^{n} \dot{m}_i = 0 - -This single constraint accounts for conservation at the junction. Connected assets -contribute their own pressure and thermal relations at that node. See -:doc:`../physics/junction_physics` for the full set of node equations. - -Assumptions ------------ - -- Only ESDL assets with state ``ENABLED`` are included in the network; disabled assets - are silently skipped during construction. -- ESDL ``Joint`` elements are absorbed into junctions during construction; they do not - produce standalone solver nodes or equation contributions. -- Heat transfer assets are the only structural boundaries between sub-networks; all - other assets within a connected graph component belong to the same sub-network. -- Each asset connection point connects to exactly one node; fan-out at a single port is - not directly supported and must be modelled via explicit junction assets. -- The partitioning into sub-networks is performed once at construction time and does not - change during the simulation. - -Limitations ------------ - -- The sub-network partitioning uses undirected graph reachability and does not account - for flow direction or valve states; topological isolation by closing a valve is not - reflected in the sub-network structure. -- Merging of solver nodes during construction may produce a network structure that differs - from a naive one-node-per-ESDL-port interpretation when multiple ESDL connections share - a port. -- ESDL assets not covered by a registered mapper raise ``NotImplementedError`` and - cannot be included in the network. -- The graph used for sub-network detection is derived from the ESDL file topology, not - from the solved hydraulic state; circuits that become hydraulically isolated at runtime - (for example, due to zero-flow heat exchangers) are not reflected as separate - sub-networks. - -See Also --------- - -- :doc:`network_main` — conceptual overview of network connectivity and simulation communication. -- :doc:`../physics/junction_physics` — node-level mass flow, energy, and pressure equations. -- :doc:`../reference/solver_reference` — solver-side network class and asset implementation details. -- :doc:`../reference/controller_reference` — controller-side sub-network behavior and dispatch. From 1fabd8ffe69b9b9bde087ff8c7c64ae0a09b139b Mon Sep 17 00:00:00 2001 From: Mike van Meerkerk Date: Thu, 25 Jun 2026 17:02:00 +0200 Subject: [PATCH 06/11] AI statement --- doc/_templates/page.html | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 doc/_templates/page.html diff --git a/doc/_templates/page.html b/doc/_templates/page.html new file mode 100644 index 00000000..1eca9038 --- /dev/null +++ b/doc/_templates/page.html @@ -0,0 +1,10 @@ +{% extends "!page.html" %} +{% block footer %} +{{ super() }} +

+ Parts of this documentation was produced with the assistance of generative AI via the + agent-based documentation pipeline defined in .github/agents/. This + applies to the documentation only. All content has been reviewed and verified + by the maintainers of this project. +

+{% endblock %} \ No newline at end of file From 15bacb0352843f772ac31d2897626cbef56e8c26 Mon Sep 17 00:00:00 2001 From: Mike van Meerkerk Date: Mon, 29 Jun 2026 10:45:39 +0200 Subject: [PATCH 07/11] General changes to documentation --- ...documentation-architecture.instructions.md | 1 + doc/_templates/page.html | 6 ++-- doc/intro/intro_main.rst | 30 ++++++++++++++----- doc/network/network_main.rst | 12 ++++---- doc/support/support.rst | 4 +-- 5 files changed, 36 insertions(+), 17 deletions(-) diff --git a/.github/instructions/documentation-architecture.instructions.md b/.github/instructions/documentation-architecture.instructions.md index 6b619b66..fae08034 100644 --- a/.github/instructions/documentation-architecture.instructions.md +++ b/.github/instructions/documentation-architecture.instructions.md @@ -118,6 +118,7 @@ Style rules - Use neutral, technical language. - Keep sections concise, actionable, and cross-linked. - Prefer short paragraphs and clear headings. +- Use sentence case for headings: capitalize only the first letter (and proper nouns/acronyms). - Avoid unnecessary bullets except for assumptions, limitations, and checklists. - Output valid reStructuredText when writing ``.rst`` files. diff --git a/doc/_templates/page.html b/doc/_templates/page.html index 1eca9038..74d6db2b 100644 --- a/doc/_templates/page.html +++ b/doc/_templates/page.html @@ -2,8 +2,10 @@ {% block footer %} {{ super() }}

- Parts of this documentation was produced with the assistance of generative AI via the - agent-based documentation pipeline defined in .github/agents/. This + Parts of this documentation were produced with the assistance of generative AI via the + agent-based documentation pipeline defined in .github/agents/. + This applies to the documentation only. All content has been reviewed and verified by the maintainers of this project.

diff --git a/doc/intro/intro_main.rst b/doc/intro/intro_main.rst index 525dbe1b..264f29de 100644 --- a/doc/intro/intro_main.rst +++ b/doc/intro/intro_main.rst @@ -4,12 +4,12 @@ Introduction Overview -------- -OMOTES.SIMULATOR_CORE is the simulation engine used to evaluate thermo-hydraulic behavior in +OMOTES.SIMULATOR_CORE is a simulation engine used to evaluate thermo-hydraulic behavior in district heating systems. Given a network description in ESDL format, a start/stop time, and a timestep, it computes how hydraulic and thermal state evolves over the simulation period and returns the result as a time series. -What It Does +What it does ------------ The package combines four things to produce a result: network topology, asset physics, control @@ -28,7 +28,7 @@ Out of scope: - Site-specific deployment and operational orchestration - Generic data platform concerns not required for simulation execution -Why It Is Used +Why it is used --------------- The package is used to study how a district-heating system behaves under changing demand, network @@ -47,11 +47,23 @@ results: .. code-block:: python + import uuid + from datetime import datetime + import logging + from omotes_simulator_core.entities.esdl_object import EsdlObject from omotes_simulator_core.entities.simulation_configuration import SimulationConfiguration from omotes_simulator_core.infrastructure.simulation_manager import SimulationManager from omotes_simulator_core.infrastructure.utils import pyesdl_from_file + # Setup logger + logger = logging.getLogger(__name__) + + # Create a callable that prints the progress messages + def progressLogger(progress: float, message: str) -> None: + """Function to report progress to logging/stdout.""" + logger.info(f"({progress*100:.2f}%) {message}") + config = SimulationConfiguration( simulation_id=uuid.uuid1(), name="test run", @@ -63,12 +75,14 @@ results: sim = SimulationManager(EsdlObject(pyesdl_from_file("path/to/file.esdl")), config) result = sim.execute(progressLogger) -The ESDL model is loaded and wrapped as an ``EsdlObject``; run parameters (start/stop, timestep) -are captured in a ``SimulationConfiguration``; ``SimulationManager`` ties the two together; and -``execute`` runs the timestep loop and returns the result ``DataFrame``. See ``README.md`` for the -full runnable example, including progress reporting. +Overview of the Simulation Process: + +- The ESDL model is loaded and wrapped as an ``EsdlObject``. +- Run parameters (start/stop, timestep) are captured in a ``SimulationConfiguration``. +- ``SimulationManager`` ties the two together. +- ``execute`` runs the timestep loop and returns the result ``DataFrame``. -Related Documentation +Related documentation ---------------------- - :doc:`../solver/solver_main` for solver behavior and numerical execution. diff --git a/doc/network/network_main.rst b/doc/network/network_main.rst index d85a5b9d..2ef80f09 100644 --- a/doc/network/network_main.rst +++ b/doc/network/network_main.rst @@ -4,10 +4,12 @@ Network layer Overview -------- -This section describes how assets are connected into a hydraulic network, how that -structure is represented and built from ESDL, and how information is exchanged during -simulation. It covers connectivity, communication between nodes and assets, and how -network behavior interacts with solver and controller flow. +This section describes: +- how assets are connected into a hydraulic network, +- how that structure is represented and built from ESDL, +- and how information is exchanged during simulation. + +It covers connectivity, communication between nodes and assets, and how network behavior interacts with solver and controller flow. The network model is configured from ESDL-derived assets and represented as connected components and nodes. At each simulation step, setpoints from the controller are applied @@ -17,7 +19,7 @@ entities. Representation --------------- -The network is represented as a graph of *assets* and *nodes*. Assets model physical +The network is represented as a graph of *assets* and *nodes*. Assets model (combined) physical components (pipes, producers, consumers, heat exchangers, storage). Nodes model the connection points between assets where hydraulic and thermal state is shared. diff --git a/doc/support/support.rst b/doc/support/support.rst index 614a4721..9abff850 100644 --- a/doc/support/support.rst +++ b/doc/support/support.rst @@ -14,7 +14,7 @@ When to use this page Documentation instead if you are trying to understand existing behavior or implementation rather than report or ask something new. -Support Paths +Support paths -------------- **Usage questions** @@ -58,7 +58,7 @@ Before requesting support - Use Developer Documentation when the question is implementation-oriented. - Include the documentation page or workflow area that appears to be affected. -Related Documentation +Related documentation ----------------------- - ``CONTRIBUTING.md`` for contribution workflow, code review, and testing requirements. From a92c4ac2efb83c7dc1b87ba551f9d68d992b64e6 Mon Sep 17 00:00:00 2001 From: Mike van Meerkerk Date: Mon, 29 Jun 2026 10:55:18 +0200 Subject: [PATCH 08/11] Removed uid reference. --- doc/network/network_main.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/network/network_main.rst b/doc/network/network_main.rst index 2ef80f09..3f750729 100644 --- a/doc/network/network_main.rst +++ b/doc/network/network_main.rst @@ -52,10 +52,6 @@ and outlet at index 1). Each connection point maps to a single ``Node``; a node shared by any number of asset connection points, representing a physical junction between components. -The solver ``Network`` stores assets and nodes in plain dictionaries, keyed by UUID -string. This allows the solver to enumerate all items when assembling the equation -system. - Construction ------------ From 3360aa539070ef4b5e44e121b6c5b279b5bed4f2 Mon Sep 17 00:00:00 2001 From: Mike van Meerkerk Date: Tue, 30 Jun 2026 14:30:31 +0200 Subject: [PATCH 09/11] Resolve comment reviewer support page --- .github/agents/SupportDocAgent.agent.md | 17 ++++------------- doc/support/support.rst | 19 +++---------------- 2 files changed, 7 insertions(+), 29 deletions(-) diff --git a/.github/agents/SupportDocAgent.agent.md b/.github/agents/SupportDocAgent.agent.md index 35dde38f..9758585e 100644 --- a/.github/agents/SupportDocAgent.agent.md +++ b/.github/agents/SupportDocAgent.agent.md @@ -114,7 +114,6 @@ A good support page should answer: - Is this a bug, a documentation issue, or a usage question? - What should I include in my report? - Where should I look first before opening an issue? -- When should I consult developer docs instead? A support page should not: - become a developer onboarding page, @@ -139,11 +138,10 @@ Section order Use the following section order for all sections that are present: 1. Title -2. When to use this page -3. Support Paths -4. What to include -5. Before requesting support -6. Related Documentation +2. Support Paths +3. What to include +4. Before requesting support +5. Related Documentation Optional sections: - ``Bug Reports`` @@ -157,13 +155,6 @@ Optional sections may be added only when they materially improve clarity. Section requirements -------------------- -When to use this page -~~~~~~~~~~~~~~~~~~~~~ -Explain: -- who this page is for, -- which types of requests belong here, -- when the reader should use other documentation instead. - Support Paths ~~~~~~~~~~~~~ Describe the practical support/reporting routes available in the repository context. diff --git a/doc/support/support.rst b/doc/support/support.rst index 9abff850..de14d000 100644 --- a/doc/support/support.rst +++ b/doc/support/support.rst @@ -1,19 +1,6 @@ Support ======= -Use this section when you need help using, interpreting, or extending OMOTES.SIMULATOR_CORE. - -When to use this page ----------------------- - -- You are a toolkit user, system modeler, or integrator with a usage question, a bug to - report, or a feature to request. -- You are a contributor with a question about the development workflow, or you have found - a code-level issue in this repository. -- Use the conceptual sections (Intro, Solver, Network, Physics, Control) or Developer - Documentation instead if you are trying to understand existing behavior or - implementation rather than report or ask something new. - Support paths -------------- @@ -50,13 +37,13 @@ What to include Before requesting support --------------------------- -- Search existing issues and discussions in - `Project-OMOTES/user_feedback `_ to - avoid duplicates. - Check the relevant conceptual section first: Intro, Solver, Network, Physics, or Control. - Use Developer Documentation when the question is implementation-oriented. - Include the documentation page or workflow area that appears to be affected. +- Search existing issues and discussions in + `Project-OMOTES/user_feedback `_ to + avoid duplicates. Related documentation ----------------------- From 2da129886f283cbc93e59d745dfad53059714f8a Mon Sep 17 00:00:00 2001 From: Mike van Meerkerk Date: Tue, 30 Jun 2026 15:11:09 +0200 Subject: [PATCH 10/11] Add linking to limitations and assumptions of other pages. --- .../agents/DocumentationCoordinator.agent.md | 32 ++++++++++++++++--- doc/controller/controller_behavior.rst | 4 +++ doc/physics/junction_physics.rst | 4 +++ doc/solver/solver_behavior.rst | 4 +++ 4 files changed, 40 insertions(+), 4 deletions(-) diff --git a/.github/agents/DocumentationCoordinator.agent.md b/.github/agents/DocumentationCoordinator.agent.md index 2537fcd1..6525df52 100644 --- a/.github/agents/DocumentationCoordinator.agent.md +++ b/.github/agents/DocumentationCoordinator.agent.md @@ -146,6 +146,21 @@ connectivity, and how it is partitioned into sub-networks. Depth comparable to t physics asset pages is expected within this single page; do not split it into separate topology/construction/sub-network pages. +Network assumptions/limitations linking policy +---------------------------------------------- +When authoring or reviewing the ``Assumptions`` and ``Limitations`` sections in +``doc/network/network_main.rst``: + +- Link only to pages that already exist in the repository, or pages that are explicitly + being created in the same coordinated task. +- Prefer section-level links (labels/``:ref:``) when a corresponding assumptions or + limitations section exists in the target page. +- Do not reference API root pages, generated package index pages, or fallback API trees + as the primary target for these sections. +- If a required target page does not yet exist and is not in-scope to be created, + remove the link and keep the statement local rather than inventing a destination. +- Treat unresolved links as a blocking validation failure. + Control documentation refinement -------------------------------- Treat control as four distinct documentation types: @@ -362,6 +377,12 @@ Each delegated task must include: - validation criteria, - required cross-links where relevant. +For network documentation tasks, also include explicit link-target constraints for +``Assumptions`` and ``Limitations``: +- permitted targets (existing conceptual pages or pages created in-task), +- prohibited targets (API root/generated index/fallback API tree), +- required handling when no valid target exists (keep text local, no fabricated links). + Coordinator output format ------------------------- For each request, produce a coordination plan containing: @@ -496,7 +517,10 @@ After coordination and downstream edits: 3. Verify that pages are routed to the correct audience. 4. Verify that there is no major duplication between end-user docs, conceptual docs, developer guides, and API reference. 5. Verify that navigation and cross-links are coherent. -6. Route authored pages through ``DocReviewAgent`` where audience, scope, or duplication review is needed. -7. Route structural and build checks through ``SphinxValidationAgent``. -8. If warnings or errors occur, route fixes back to the responsible specialist agent. -9. Do not consider the task complete if the documentation architecture is inconsistent, the toctree order is broken, pages are assigned to the wrong documentation type, or required review/validation steps remain unresolved. \ No newline at end of file +6. For ``doc/network/network_main.rst`` assumptions/limitations links, verify that every + link target exists (or is created in-task), resolves cleanly in Sphinx, and does not + point to API root/generated index pages. +7. Route authored pages through ``DocReviewAgent`` where audience, scope, or duplication review is needed. +8. Route structural and build checks through ``SphinxValidationAgent``. +9. If warnings or errors occur, route fixes back to the responsible specialist agent. +10. Do not consider the task complete if the documentation architecture is inconsistent, the toctree order is broken, pages are assigned to the wrong documentation type, required review/validation steps remain unresolved, or network assumptions/limitations links violate the link-target policy above. \ No newline at end of file diff --git a/doc/controller/controller_behavior.rst b/doc/controller/controller_behavior.rst index da26c94a..cbaa68fb 100644 --- a/doc/controller/controller_behavior.rst +++ b/doc/controller/controller_behavior.rst @@ -444,6 +444,8 @@ same total heat setpoints are requested. For broader network interpretation, see :doc:`../network/network_main`. +.. _controller-behavior-assumptions: + Assumptions ----------- @@ -454,6 +456,8 @@ Assumptions - Consumer curtailment under shortage is proportional across all consumers. - Pressure selection uses a fixed precedence rule rather than an optimization or hydraulic-quality criterion. +.. _controller-behavior-limitations: + Limitations ----------- diff --git a/doc/physics/junction_physics.rst b/doc/physics/junction_physics.rst index 51e0a39d..778d6518 100644 --- a/doc/physics/junction_physics.rst +++ b/doc/physics/junction_physics.rst @@ -80,6 +80,8 @@ node pressure in their coupling equations. The node can also be operated with a This is used when pressure must be prescribed at the junction. +.. _junction-physics-assumptions: + Assumptions ----------- @@ -88,6 +90,8 @@ Assumptions - Pressure losses and heat losses inside the junction are neglected. - Node discharge is represented as an algebraic balancing variable. +.. _junction-physics-limitations: + Limitations ----------- diff --git a/doc/solver/solver_behavior.rst b/doc/solver/solver_behavior.rst index 46819785..7816626b 100644 --- a/doc/solver/solver_behavior.rst +++ b/doc/solver/solver_behavior.rst @@ -229,6 +229,8 @@ The practical consequence is that any of the interpretations above are only vali is confirmed; an unconverged solve should be treated as an unreliable snapshot of the equation system rather than a physically consistent state. +.. _solver-behavior-assumptions: + Assumptions ----------- @@ -239,6 +241,8 @@ Assumptions - 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. +.. _solver-behavior-limitations: + Limitations ----------- From e97f8aa3aa20f4539eb20b3d97e84edaffaa952a Mon Sep 17 00:00:00 2001 From: Mike van Meerkerk Date: Tue, 30 Jun 2026 15:15:03 +0200 Subject: [PATCH 11/11] Fixed network main --- doc/network/network_main.rst | 48 +++++++++++++++++++----------------- 1 file changed, 26 insertions(+), 22 deletions(-) diff --git a/doc/network/network_main.rst b/doc/network/network_main.rst index 3f750729..e376e8de 100644 --- a/doc/network/network_main.rst +++ b/doc/network/network_main.rst @@ -5,9 +5,10 @@ Overview -------- This section describes: -- how assets are connected into a hydraulic network, -- how that structure is represented and built from ESDL, -- and how information is exchanged during simulation. + +- how assets are connected into a hydraulic network, +- how that structure is represented and built from ESDL, +- and how information is exchanged during simulation. It covers connectivity, communication between nodes and assets, and how network behavior interacts with solver and controller flow. @@ -113,25 +114,23 @@ Node connectivity rules ------------------------ Each asset connection point is linked to at most one node. A node may be connected to -any number of asset connection points. The continuity and energy-balance equations -assembled at each node require at least one connected asset; isolated nodes are not -meaningful in the solved system. - -At a node with :math:`n` connected asset ports, the solver enforces one mass-flow -continuity equation: - -.. math:: - - \sum_{i=1}^{n} \dot{m}_i = 0 +any number of asset connection points. A node must have at least one connected port to +be meaningful in the solved system; isolated nodes are not retained. -This single constraint accounts for conservation at the junction. Connected assets -contribute their own pressure and thermal relations at that node. See -:doc:`../physics/junction_physics` for the full set of node equations. +At each shared node the solver enforces mass-flow continuity over all connected asset +ports; see :doc:`../physics/junction_physics` for the node continuity and energy-balance +equations. Assumptions ----------- -- Only ESDL assets with state ``ENABLED`` are included in the network; disabled assets +The assumptions below are specific to network construction and partitioning in this +page. Related controller, solver, and junction assumptions are documented in +:ref:`controller behavior assumptions `, +:ref:`solver behavior assumptions `, and +:ref:`junction physics assumptions `. + +- Only ESDL assets with state ``ENABLED`` are included in the network; disabled or optional assets are silently skipped during construction. - ESDL ``Joint`` elements are absorbed into junctions during construction; they do not produce standalone solver nodes or equation contributions. @@ -145,6 +144,12 @@ Assumptions Limitations ----------- +The limitations below focus on the network-graph construction and partitioning logic. +Related controller, solver, and junction limitations are documented in +:ref:`controller behavior limitations `, +:ref:`solver behavior limitations `, and +:ref:`junction physics limitations `. + - The sub-network partitioning uses undirected graph reachability and does not account for flow direction. - Merging of solver nodes during construction may produce a network structure that differs @@ -160,10 +165,9 @@ Limitations Implementation reference ------------------------- -For solver-side network class details, see :doc:`../reference/solver_reference`. For -controller-side sub-network behavior, see :doc:`../reference/controller_reference`. For -network simulation orchestration, see :doc:`../reference/architecture_reference`. For +For solver-side network class details, see :doc:`../reference/solver_reference` +(:ref:`network-class`). For controller-side sub-network behavior, see +:doc:`../reference/controller_reference` (:ref:`sub_network_class`). For network +simulation orchestration, see :doc:`../reference/architecture_reference`. For node-level mass flow, energy, and pressure equations, see :doc:`../physics/junction_physics`. - -See also :ref:`network-class` for the solver-side network class and :ref:`sub_network_class` for controller-side sub-network behavior.