diff --git a/.github/agents/ControllerBehaviorDocAgent.agent.md b/.github/agents/ControllerBehaviorDocAgent.agent.md index 0cdfe768..87cb262a 100644 --- a/.github/agents/ControllerBehaviorDocAgent.agent.md +++ b/.github/agents/ControllerBehaviorDocAgent.agent.md @@ -97,6 +97,11 @@ existing ``doc/controller/behavior`` page as the structural template. setpoints, and physical-impact claims. Anchor the network dispatch description in ``NetworkController.update_setpoints``. +3. For updates scoped to ``doc/controller/controller_behavior.rst``, also consult: + ``doc/physics/ideal_heat_storage_physics.rst`` for fill-level and effective + charge/discharge-capability interpretation, and ``doc/physics/heat_pump_physics.rst`` for + water-to-water heat-pump terminology context. + Rules for source usage: - Use repository sources only. - Ground every decision-logic and physical-impact claim in the actual implementation, not in @@ -192,6 +197,12 @@ curtail consumers), plus heat-transfer conversion and the pressure-set asset sel For a component page, cover that component's local rule (for example deriving effective storage charge/discharge power from available volume, or applying a producer priority and factor). +For the ``Dispatch Logic for Supply, Demand, and Storage`` section in +``doc/controller/controller_behavior.rst``, explicitly explain how storage fill level affects +effective charge and discharge capability, including why capability clips near empty/full bounds, +and cross-link to ``doc/physics/ideal_heat_storage_physics.rst`` instead of re-deriving +asset-internal physics. + Give the governing relation in simplified engineering form where it clarifies the decision. Setpoints Produced @@ -274,6 +285,9 @@ the shared style rules. In addition: - Prefer short paragraphs with direct interpretation of decisions and their consequences. - Avoid textbook density and implementation-oriented wording. - Avoid unnecessary bullets outside tables, assumptions, and limitations. +- For ``doc/controller/controller_behavior.rst`` specifically, use + ``water-to-water heat-pump`` as the preferred term in place of + ``four-port heat pump`` or ``four-port heat-pump``. reStructuredText requirements ----------------------------- @@ -305,13 +319,16 @@ After writing or updating a behavior page: existing ``doc/controller`` pages. 5. Verify that decision-logic and physical-impact claims are supported by the source files in the source-priority table. -6. Verify the page is toctreed only from ``doc/controller/controller.rst`` and not duplicated in +6. For ``doc/controller/controller_behavior.rst``, verify terminology uses + ``water-to-water heat-pump`` and that storage-dispatch explanations include fill-level impact + and clipping context with a physics cross-link. +7. Verify the page is toctreed only from ``doc/controller/controller.rst`` and not duplicated in any ``doc/reference/`` page. -7. If command execution or validation tools are available, run ``doc/run_spinx.bat`` or the +8. If command execution or validation tools are available, run ``doc/run_spinx.bat`` or the repository-preferred documentation build command. -8. Inspect the build output for warnings and errors related to the new or edited page, +9. Inspect the build output for warnings and errors related to the new or edited page, including rst syntax errors, malformed tables, invalid math blocks, broken references, and broken toctrees. -9. If an error or warning is found, fix it before returning the final content. -10. Do not finish with known syntax errors, broken section structure, malformed tables, broken +10. If an error or warning is found, fix it before returning the final content. +11. Do not finish with known syntax errors, broken section structure, malformed tables, broken math blocks, or unresolved build warnings caused by the change. diff --git a/.github/agents/DocReviewAgent.agent.md b/.github/agents/DocReviewAgent.agent.md index 6bc08eb0..4fa748ae 100644 --- a/.github/agents/DocReviewAgent.agent.md +++ b/.github/agents/DocReviewAgent.agent.md @@ -183,6 +183,14 @@ 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. +For reviews of ``doc/controller/controller_behavior.rst``, also flag as errors: +- use of ``four-port heat pump`` or ``four-port heat-pump`` where + ``water-to-water heat-pump`` terminology is required, +- missing explanation in ``Dispatch Logic for Supply, Demand, and Storage`` of how fill level + constrains effective storage charge/discharge capability and clipping near empty/full bounds, +- missing cross-link to ``doc/physics/ideal_heat_storage_physics.rst`` when storage fill-level + interpretation is discussed. + Completeness review by page type -------------------------------- Review each page according to its type. @@ -270,6 +278,11 @@ Before accepting a page, verify that: - it links to the right neighboring documentation where useful, - it does not blur the boundary between conceptual docs, physics docs, developer guides, API reference, navigation, and support. +For ``doc/controller/controller_behavior.rst`` specifically, also verify: +- terminology uses ``water-to-water heat-pump`` consistently, +- storage dispatch explanation includes fill-level impact and clipping behavior, +- storage fill-level interpretation links to ``doc/physics/ideal_heat_storage_physics.rst``. + Validation ---------- After review and any focused edits: diff --git a/.github/agents/DocumentationCoordinator.agent.md b/.github/agents/DocumentationCoordinator.agent.md index f0a82aaa..d953bf8b 100644 --- a/.github/agents/DocumentationCoordinator.agent.md +++ b/.github/agents/DocumentationCoordinator.agent.md @@ -217,6 +217,9 @@ If a control-related request is ambiguous, classify by the primary question bein When a request mixes more than one of these, split it into multiple sub-tasks and assign them separately. Do not allow a single page to serve all three purposes. +If the user explicitly scopes a request to ``doc/controller/controller_behavior.rst`` only, +keep scope locked to that single page unless the user asks to broaden scope. + Audience separation rules ------------------------- Enforce the following audience boundaries: @@ -296,6 +299,14 @@ When delegating to a specialist agent, always specify: - validation criteria, - required cross-links to adjacent sections where relevant. +For tasks scoped to ``doc/controller/controller_behavior.rst``, also specify: +- terminology requirement: use ``water-to-water heat-pump`` wording, +- completeness requirement: in the ``Dispatch Logic for Supply, Demand, and Storage`` section, + explain storage fill-level impact on effective charge/discharge capability and clipping near + empty/full bounds, +- physics link requirement: include a cross-link to + ``doc/physics/ideal_heat_storage_physics.rst`` for asset-internal storage behavior. + The coordinator must not delegate vague requests such as: - "write the docs" - "improve this page" @@ -324,6 +335,9 @@ Each delegated task must include: - validation criteria, - required cross-links where relevant. +For control-behavior tasks scoped to ``doc/controller/controller_behavior.rst``, add explicit +exclusions preventing edits to other pages unless the user requests broader scope. + Coordinator output format ------------------------- For each request, produce a coordination plan containing: diff --git a/.github/agents/SystemConceptDocAgent.agent.md b/.github/agents/SystemConceptDocAgent.agent.md index 994242a4..06e70c12 100644 --- a/.github/agents/SystemConceptDocAgent.agent.md +++ b/.github/agents/SystemConceptDocAgent.agent.md @@ -77,6 +77,7 @@ Before writing, inspect the closest matching existing documentation page and pre - For Solver pages: ``doc/solver/solver_main.rst`` - For Network pages: ``doc/network/network_main.rst`` - For Control pages: ``doc/controller/controller.rst`` + - For Control behavioral terminology/context only: ``doc/controller/controller_behavior.rst`` - ``doc/physics/physics_main.rst`` (cross-reference landing page only, not a style source for Physics content itself) - ``doc/architecture/architecture.rst`` - any existing landing page in the same section as ```` @@ -146,7 +147,10 @@ Classify the page intent as follows: how the network is represented conceptually, how assets and connectivity affect behavior, and how users should think about network-level interactions - ``Control``: - current control concepts, setpoint propagation, operating logic at a conceptual level, and the user-visible consequences of control actions + current control concepts, setpoint propagation, operating logic at a conceptual level, and the user-visible consequences of control actions. + Keep descriptions tied to the heat-network physics interface: controller output should be framed as + requested heat extraction/injection and boundary-condition intent that is later realized or constrained + by the hydraulic and thermal solve. Do not use this agent to document: - how to extend control classes as a contributor, @@ -205,6 +209,8 @@ Optional sections: Optional sections may be added only when they materially improve clarity. +**For ``Control`` pages specifically:** Omit the ``Limitations`` section. Control pages should end with ``Assumptions`` before proceeding to ``Related Documentation`` or the toctree. + Section requirements -------------------- @@ -215,6 +221,10 @@ Explain: - why it matters, - how readers should think about it. +For ``Control`` pages, phrase overview text in terms of physics-facing setpoint intent (for example, +asset-level heat extraction/injection requests and pressure-boundary intent for the timestep solve), +not only generic demand-profile propagation wording. + For ``Intro`` pages, explicitly include: - what OMOTES.SIMULATOR_CORE does, - why it is used in practice. @@ -244,6 +254,37 @@ Examples: Keep definitions concise and simulation-oriented. +For ``Control`` pages, format each concept as a reStructuredText definition list: + + **Concept Name** + Definition text here. For multi-line definitions, continue text on the next line with consistent indentation (same indent level as the first line of the definition). + +**IMPORTANT for reStructuredText formatting:** To prevent text from being boxed as literal blocks: + - Do NOT use extra indentation or line breaks that create gaps in the definition text. + - Do NOT use ``::`` or ``|`` markers within definitions. + - Write multi-line definitions as flowing text with uniform indentation, not as separate paragraphs or code blocks. + - Example of CORRECT formatting: + + **Storages** + Flexible control components that can absorb or release heat. In the current model this includes ideal heat storage and ATES-based storage. Effective charge and discharge capability depends on current fill level or state of charge, which affects how much storage can contribute in a timestep. + + - Example of INCORRECT formatting (will create a box): + + **Storages** + Flexible control components that can absorb or release heat. In the current model this includes + ideal heat storage and ATES-based storage. Effective charge and discharge capability depends on + current fill level or state of charge, which affects how much storage can contribute in a timestep. + +Include at least these concepts when relevant to the current model: +- Network Controller: the top-level control component that coordinates subnetworks +- Subnetworks: hydraulically separated groups of assets +- Consumers: demand-side components +- Producers: supply-side components +- Storages: flexible components with effective charge/discharge capability tied to fill level or state of charge +- Heat-transfer assets: coupling components between subnetworks +- Setpoints: asset-level control targets +- Priority: dispatch ordering used when producer output must be capped; determines which producer supplies heat under surplus conditions + Behavior and Interpretation ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Describe the main behavior in practical terms. @@ -268,12 +309,8 @@ Include only assumptions that matter for: - model setup, - understanding the documented workflow. -Limitations -~~~~~~~~~~~ -Use short bullets. - -State what the page intentionally simplifies or does not cover. -Point readers to more specific sections when relevant. +For ``Control`` pages, state that storage behavior is constrained by effective charging/discharging +capability and that this capability depends on the current fill level/state of charge. Related Documentation ~~~~~~~~~~~~~~~~~~~~~ @@ -320,6 +357,14 @@ See [Documentation Architecture](../instructions/documentation-architecture.inst - Avoid implementation-oriented wording unless needed to anchor behavior. - Avoid unnecessary bullets outside assumptions, limitations, and short checklists. +For ``Control`` page Key Concepts specifically: +- Each concept must be formatted as a definition-list entry (bold concept name followed by indented definition). +- Do not use code blocks, boxed elements, or literal formatting for concept definitions. +- Do not use ``::`` or ``|`` markers within definition text. +- Keep each definition to 1–2 concise sentences. +- Do not nest concepts within examples or use numbered/bulleted lists within concept definitions. +- For multi-line definitions, maintain consistent indentation across all lines to prevent reStructuredText from treating the text as a literal block (which would create a box). + reStructuredText requirements ----------------------------- See [Documentation Architecture](../instructions/documentation-architecture.instructions.md) for the shared output-format requirements. In addition: @@ -349,4 +394,11 @@ After writing or updating the file: 7. Check that the page introduces no documentation build warnings or errors. 8. If command execution or validation tools are available, run ``doc/run_spinx.bat`` or the repository-preferred documentation build command. 9. If an error or warning is found, fix it before returning the final content. -10. Do not finish with known syntax errors, broken headings, malformed math blocks, broken references, or unresolved build warnings caused by the change. \ No newline at end of file +10. Do not finish with known syntax errors, broken headings, malformed math blocks, broken references, or unresolved build warnings caused by the change. + +For ``Control`` pages specifically, also verify: +- All required concepts (Network Controller, Subnetworks, Consumers, Producers, Storages, Heat-transfer assets, Setpoints, Priority) are present in the Key Concepts section. +- Priority concept is clearly defined as related to dispatch ordering when producer output is capped. +- No ``Limitations`` section is present; the page proceeds directly from ``Assumptions`` to ``Related Documentation``. +- All Key Concept definitions are formatted as definition-list entries (bold name, indented definition) with no code blocks or boxes. +- Specifically verify that the Storages concept definition does NOT appear in a box; its text should flow naturally as a continuation of the definition line. \ No newline at end of file