docs(bmad): Add Hierarchical Subsystems (FR48) to PRD, Arch, Epics and Sprint

_bmad-output/implementation-artifacts/3-6-hierarchical-macro-components.md

@@ -0,0 +1,81 @@
+# Story 3.6: Hierarchical Subsystems (MacroComponents)
+
+Status: ready-for-dev
+
+## Story
+
+As a system designer,
+I want to encapsulate a complete system (e.g., a Chiller with compressor, condenser, valve, evaporator) into a single reusable block,
+so that I can compose larger models (like buildings or parallel chiller plants) using these blocks, just like in Modelica.
+
+## Acceptance Criteria
+
+1. **MacroComponent Trait Implementation** (AC: #1)
+   - Given a fully defined `System` with internal components and connections
+   - When I wrap it in a `MacroComponent`
+   - Then this `MacroComponent` implements the `Component` trait
+   - And the global solver treats it exactly like a basic Component
+
+2. **External Port Mapping** (AC: #2)
+   - Given a `MacroComponent` wrapping an internal `System`
+   - When I want to expose specific internal ports (e.g., Evaporator Water In/Out, Condenser Water In/Out)
+   - Then I can map these to the `MacroComponent`'s external ports
+   - And external connections to these mapped ports correctly route fluid states to the internal components
+
+3. **Residual and Jacobian Delegation** (AC: #3)
+   - Given a system solver calling `compute_residuals` or `jacobian_entries` on a `MacroComponent`
+   - When the `MacroComponent` executes these methods
+   - Then it delegates or flattens the computation down to the nested internal `System`
+   - And all equations are solved simultaneously globally, avoiding nested numerical solver delays
+
+4. **Serialization and Persistence** (AC: #4)
+   - Given a `System` that contains `MacroComponent`s
+   - When serializing the system to JSON
+   - Then the internal topology of the `MacroComponent` is preserved and can be deserialized perfectly
+
+## Tasks / Subtasks
+
+- [ ] Define `MacroComponent` struct in `crates/components/src/macro_component.rs` (AC: #1)
+  - [ ] Store internal `System`
+  - [ ] Store `port_mapping` dictionary
+- [ ] Implement `Component` trait for `MacroComponent` (AC: #1, #3)
+  - [ ] Implement `get_ports` returning mapped external ports
+  - [ ] Implement `compute_residuals` by delegating to internal components
+  - [ ] Implement `jacobian_entries` by offsetting indices and delegating to internal components
+  - [ ] Implement `n_equations` returning the sum of internal equations
+- [ ] Implement external port bounding/mapping logic (AC: #2)
+  - [ ] Create API for `expose_port(internal_node_id, external_port_name)`
+- [ ] Integration Tests (AC: #1-#3)
+  - [ ] Test encapsulating a 4-component cycle into a single `MacroComponent`
+  - [ ] Test connecting two identical `MacroComponent` chillers in parallel inside a higher-level `System`
+  - [ ] Assert global convergence works simultaneously.
+
+## Dev Notes
+
+### Epic Context
+
+**Epic 3: System Topology (Graph)** — Enable component assembly via Ports and manage multi-circuits with thermal coupling.
+This story adds the capability to wrap topologies into sub-blocks.
+
+**FRs covered:** FR48 (Hierarchical Subsystems).
+
+### Architecture Context
+
+**Technical Stack:**
+- Rust, `entropyk-components`, `entropyk-solver`
+- Need to ensure that `SystemState` indices stay aligned when a `MacroComponent` is placed into a larger `System`.
+
+**Relevant Architecture Decisions:**
+- **Wrapper Pattern:** `MacroComponent` implements `Component`.
+- **SystemState Flattening:** The global solver dictates state vector indices. The `MacroComponent` must know how its internal node IDs map to the global `SystemState` indices, or it must reconstruct an internal `SystemState` slice.
+- **Zero-allocation:** Port mapping and index offsetting must be pre-calculated during the topology finalization phase.
+
+### Code Structure
+
+- Create `crates/components/src/macro_component.rs`.
+- May require slight structural adjustments to `crates/solver/src/system.rs` if `System` doesn't currently support being completely embedded.
+
+### Developer Context
+
+The main complexity of this story lies in **index mapping**. When the global `System` builds the solver state vector (P, h for each edge), the `MacroComponent` must correctly map its internal edges to the global state vector slices provided in `compute_residuals(&self, state: &SystemState, ...)`.
+Consider building an initialization step where `MacroComponent` is informed of its global state offsets before solving begins.

_bmad-output/implementation-artifacts/sprint-status.yaml

@@ -73,6 +73,7 @@ development_status:
   3-3-multi-circuit-machine-definition: done
   3-4-thermal-coupling-between-circuits: done
   3-5-zero-flow-branch-handling: done
+  3-6-hierarchical-macro-components: ready-for-dev
   epic-3-retrospective: optional
 
   # Epic 4: Intelligent Solver Engine

_bmad-output/planning-artifacts/architecture.md

@@ -283,6 +283,32 @@ impl Compressor<Disconnected> {
 - Extensible pour composants custom (e.g., Ejecteur de Robert)
 - AHRI 540 coefficients intégrés dans struct Compressor
 
+### Hierarchical Subsystems (MacroComponents)
+
+**Decision:** Wrapper Pattern matching the `Component` trait
+
+**Core Pattern:**
+```rust
+struct MacroComponent {
+    internal_system: System,
+    port_mapping: HashMap<PortId, InternalLocation>, /* e.g., Exposes 'Condenser Water In' */
+}
+
+impl Component for MacroComponent {
+    fn compute_residuals(&self, state: &SystemState, residuals: &mut ResidualVector) {
+        // Delegates or flattens computation to internal_system
+        self.internal_system.compute_residuals(state, residuals);
+    }
+    // ... maps external ports to internal boundary ports ...
+}
+```
+
+**Rationale:**
+- Allows users to build reusable blocks (like a full Chiller, Air Handling Unit)
+- Mimics Modelica/Simulink ecosystem composability
+- The global solver treats `MacroComponent` exactly like a basic Component, preserving zero-cost abstractions
+- `SystemState` flattening ensures equations are solved simultaneously globally, avoiding nested numerical solver delays.
+
 ### Fluid Properties Backend
 
 **Decision:** Trait abstraction with multiple backends
@@ -794,7 +820,7 @@ pub trait Solver {
 | Feature | FRs | Location |
 |---------|-----|----------|
 | Component Modeling | FR1-FR8 | `crates/components/src/` |
-| System Topology | FR9-FR13 | `crates/solver/src/system.rs` |
+| System Topology | FR9-FR13, FR48 | `crates/solver/src/system.rs` & `macro_component.rs` |
 | Solver Engine | FR14-FR21 | `crates/solver/src/strategies/` |
 | Inverse Control | FR22-FR24 | `crates/solver/src/inverse/` |
 | Fluid Properties | FR25-FR29 | `crates/fluids/src/` |

_bmad-output/planning-artifacts/epics.md

@@ -251,6 +251,7 @@ This document provides the complete epic and story breakdown for Entropyk, decom
 | FR45 | Epic 7 | Inverse calibration (parameter estimation) |
 | FR46 | Epic 1 | Air Coils (EvaporatorCoil, CondenserCoil) |
 | FR47 | Epic 2 | Rich Thermodynamic State Abstraction |
+| FR48 | Epic 3 | Hierarchical Subsystems (MacroComponents) |
 
 ## Epic List
 
@@ -273,11 +274,11 @@ This document provides the complete epic and story breakdown for Entropyk, decom
 ---
 
 ### Epic 3: System Topology (Graph)
-**Goal:** Enable component assembly via Ports and manage multi-circuits with thermal coupling.
+**Goal:** Enable component assembly via Ports and manage multi-circuits with thermal coupling, and support hierarchical subsystems.
 
-**Innovation:** Multi-fluid directed graph in a single model.
+**Innovation:** Multi-fluid directed graph in a single model, with natively supported hierarchical sub-blocks.
 
-**FRs covered:** FR9, FR10, FR11, FR12, FR13
+**FRs covered:** FR9, FR10, FR11, FR12, FR13, FR48
 
 ---
 
@@ -664,6 +665,23 @@ This document provides the complete epic and story breakdown for Entropyk, decom
 
 ---
 
+### Story 3.6: Hierarchical Subsystems (MacroComponents)
+
+**As a** system designer,
+**I want** to encapsulate a complete system (e.g., a Chiller with compressor, condenser, valve, evaporator) into a single reusable block,
+**So that** I can compose larger models (like buildings or parallel chiller plants) using these blocks, just like in Modelica.
+
+**Acceptance Criteria:**
+
+**Given** a fully defined `System` with internal components and connections
+**When** I wrap it in a `MacroComponent`
+**Then** I can expose specific internal ports (e.g., Evaporator Water In/Out, Condenser Water In/Out) as the `MacroComponent`'s external ports
+**And** this `MacroComponent` implements the `Component` trait
+**And** I can add it to a higher-level `System` just like any regular component
+**And** the global solver correctly flattens or delegates the residual and jacobian computations down to the nested components.
+
+---
+
 ## Epic 4: Intelligent Solver Engine
 
 ### Story 4.1: Solver Trait Abstraction

_bmad-output/planning-artifacts/prd.md

@@ -460,6 +460,7 @@ Le produit est utile uniquement si tous les éléments critiques fonctionnent en
 - **FR11** : Le système supporte les connexions entre circuits (couplage thermique)
 - **FR12** : Le système peut résoudre les N circuits simultanément ou séquentiellement
 - **FR13** : Le système gère mathématiquement les branches à débit nul sans division par zéro
+- **FR48** : Le système permet de définir des sous-systèmes hiérarchiques (MacroComponents/Blocks) comme dans Modelica, encapsulant une topologie interne et exposant uniquement des ports (ex: raccorder deux Chillers en parallèle).
 
 ### 3. Résolution du Système (Solver)
 
@@ -552,7 +553,7 @@ Le produit est utile uniquement si tous les éléments critiques fonctionnent en
 
 **Workflow :** BMAD Create PRD  
 **Steps Completed :** 12/12  
-**Total FRs :** 47  
+**Total FRs :** 48  
 **Total NFRs :** 17  
 **Personas :** 5  
 **Innovations :** 5