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