diff --git a/.github/agents/DocReviewAgent.agent.md b/.github/agents/DocReviewAgent.agent.md index 6bc08eb0..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. @@ -164,6 +165,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 +203,18 @@ 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 +------------------------------ +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 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 -------------------------------- Review each page according to its type. diff --git a/.github/agents/DocumentationCoordinator.agent.md b/.github/agents/DocumentationCoordinator.agent.md index f0a82aaa..6525df52 100644 --- a/.github/agents/DocumentationCoordinator.agent.md +++ b/.github/agents/DocumentationCoordinator.agent.md @@ -88,7 +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 documentation - Physics asset documentation - User-facing control concepts - Controller behavior and physical impact @@ -99,6 +99,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 +136,31 @@ 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 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. + +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: @@ -151,7 +197,7 @@ Delegate work according to the following rules: - Solver behavior and physical impact Route to: ``SolverBehaviorDocAgent`` -- Network conceptual documentation +- Network documentation Route to: ``SystemConceptDocAgent`` - Physics asset documentation @@ -198,6 +244,13 @@ 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 +---------------------- +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 --------------------- If a control-related request is ambiguous, classify by the primary question being answered: @@ -324,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: @@ -364,8 +423,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", "nodes", "connections", "communication" - => Network conceptual documentation +- "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 documentation - "control behavior", "setpoint propagation", "operating logic", "what does control do" => User-facing control concepts @@ -410,6 +471,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``. +- 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. @@ -455,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/.github/agents/SupportDocAgent.agent.md b/.github/agents/SupportDocAgent.agent.md index 36711c84..9758585e 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. @@ -104,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, @@ -129,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`` @@ -147,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/.github/agents/SystemConceptDocAgent.agent.md b/.github/agents/SystemConceptDocAgent.agent.md index 994242a4..1df39635 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`` @@ -143,11 +142,48 @@ 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 +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. + +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, @@ -185,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/.github/instructions/documentation-architecture.instructions.md b/.github/instructions/documentation-architecture.instructions.md index c69fa60a..fae08034 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 @@ -107,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/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/_templates/page.html b/doc/_templates/page.html new file mode 100644 index 00000000..74d6db2b --- /dev/null +++ b/doc/_templates/page.html @@ -0,0 +1,12 @@ +{% extends "!page.html" %} +{% block footer %} +{{ super() }} +

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

+{% endblock %} \ 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/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 49dd0c56..264f29de 100644 --- a/doc/intro/intro_main.rst +++ b/doc/intro/intro_main.rst @@ -1,35 +1,96 @@ 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 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. -**Contents** +What it does +------------ -.. toctree:: - :maxdepth: 1 +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. - package_scope - audience_and_use_cases - simulation_input_and_output +In scope: -Section map ------------ +- 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 -- 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`. +Out of scope: -External context ----------------- +- 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 to study how a district-heating system behaves under changing demand, network +conditions, and control decisions: + +- **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. + +Example +------- + +A run is defined by an ESDL model and a time configuration, and returns a pandas ``DataFrame`` of +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", + 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) + +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 +---------------------- + +- :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`_. 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/network/network_main.rst b/doc/network/network_main.rst index c632748a..e376e8de 100644 --- a/doc/network/network_main.rst +++ b/doc/network/network_main.rst @@ -1,16 +1,173 @@ 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 +-------- -Implementation reference +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 +to assets, the network equations are assembled, and solver results are propagated back to +entities. + +Representation +--------------- + +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. + +.. 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. + +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 ------------------------- -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`. +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. A node must have at least one connected port to +be meaningful in the solved system; isolated nodes are not retained. + +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 +----------- + +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. +- 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 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 + 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 +------------------------- -See also :ref:`network-class` for the solver-side network class and :ref:`sub_network_class` for controller-side sub-network behavior. +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`. 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 ----------- 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 diff --git a/doc/support/support.rst b/doc/support/support.rst index 4885b6f1..de14d000 100644 --- a/doc/support/support.rst +++ b/doc/support/support.rst @@ -1,27 +1,53 @@ Support ======= -Use this section when you need help using, interpreting, or extending OMOTES.SIMULATOR_CORE. +Support paths +-------------- -Support Paths -------------- +**Usage questions** -- 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``. +- 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** + +- 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. +- 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 +----------------------- + +- ``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.