binding design doc

Author: wpbonelli

binding-resolution-design.md

@@ -0,0 +1,356 @@
+# Binding Resolution Design for Component Loading
+
+## Problem Statement
+
+MF6 simulation and model namefiles use **bindings** to reference child components in tabular list blocks:
+
+```
+BEGIN MODELS
+  gwf6  model.nam  modelname
+END MODELS
+
+BEGIN SOLUTIONGROUP 1
+  ims6  model.ims  modelname
+END SOLUTIONGROUP
+```
+
+**On write**: The `Binding` class converts component instances to binding tuples:
+```python
+Binding.from_component(model) → ('gwf6', 'model.nam', 'modelname')
+```
+
+**On load**: We need the inverse operation - convert binding tuples back to component instances:
+```python
+# Transformer outputs:
+{'models': [['gwf6', 'model.nam', 'modelname']]}
+
+# Component expects:
+{'models': {'modelname': Model(...)}}
+```
+
+The challenge: **Binding resolution requires recursive component loading**.
+
+---
+
+## Approach 1: Inline Resolution in Structure Hook
+
+### Description
+Register custom cattrs structure hooks for Simulation/Model that resolve bindings during structuring:
+
+```python
+def _structure_simulation_hook(data: dict, cls: type) -> Simulation:
+    """Custom structure hook for Simulation that resolves bindings."""
+
+    # Resolve model bindings
+    models_bindings = data.get('models', [])
+    models = {}
+    workspace = ...  # Need to pass workspace somehow
+
+    for binding_tuple in models_bindings:
+        model_type, fname, name = binding_tuple
+        model_cls = _resolve_component_class(model_type)
+        model = model_cls.load(workspace / fname)
+        models[name] = model
+
+    # Similar for solutions, exchanges...
+
+    return Simulation(models=models, solutions=solutions, ...)
+
+# Register the hook
+COMPONENT_CONVERTER.register_structure_hook(Simulation, _structure_simulation_hook)
+```
+
+### Pros
+- ✅ Clean separation - structure hooks handle all structuring logic
+- ✅ Fits cattrs design pattern
+- ✅ Type-specific logic encapsulated in hooks
+
+### Cons
+- ❌ Structure hooks don't have access to `workspace` (only get `data` and `cls`)
+- ❌ Requires passing workspace through the data dict or via closure
+- ❌ Mixing structural transformation with I/O (recursive loads)
+- ❌ Harder to test in isolation
+- ❌ Need separate hooks for each component type with bindings
+
+---
+
+## Approach 2: Post-Processing After Structure
+
+### Description
+Keep structuring simple, then resolve bindings as a post-processing step:
+
+```python
+def resolve_bindings(component: Component, workspace: Path) -> Component:
+    """
+    Recursively resolve binding tuples to component instances.
+
+    Processes a component after structuring to:
+    1. Detect binding lists (list of tuples with type/fname/terms)
+    2. Recursively load referenced components
+    3. Replace binding lists with dicts of component instances
+    """
+
+    if isinstance(component, Simulation):
+        # Resolve models
+        if isinstance(component.models, list):
+            resolved_models = {}
+            for binding_tuple in component.models:
+                model = Binding.to_component(binding_tuple, workspace)
+                resolved_models[model.name] = model
+            component.models = resolved_models
+
+        # Resolve solutions
+        if isinstance(component.solutions, dict):
+            for group_name, bindings in list(component.solutions.items()):
+                if isinstance(bindings, list):
+                    resolved = {}
+                    for binding_tuple in bindings:
+                        solution = Binding.to_component(binding_tuple, workspace)
+                        resolved[solution.name] = solution
+                    component.solutions.update(resolved)
+
+        # Similar for exchanges...
+
+    elif isinstance(component, Model):
+        # Resolve package bindings if model namefiles have them
+        pass
+
+    return component
+
+# Usage in loader:
+def _load_mf6(cls, path: Path) -> Component:
+    with open(path, "r") as fp:
+        component = structure(load_mf6(fp), path, component_type=cls)
+        component = resolve_bindings(component, path.parent)
+        return component
+```
+
+### Pros
+- ✅ Clear separation of concerns: structure = data transformation, binding = I/O
+- ✅ Has access to workspace naturally
+- ✅ Easy to test independently
+- ✅ Reusable across different component types
+- ✅ Doesn't complicate cattrs setup
+- ✅ Can be optional/conditional (e.g., skip for testing)
+
+### Cons
+- ❌ Requires components to temporarily hold invalid state (lists instead of dicts)
+- ❌ Two-pass processing (structure, then resolve)
+- ❌ Need to handle partially-resolved states gracefully
+
+---
+
+## Approach 3: Binding Helper Method on Binding Class
+
+### Description
+Add a `to_component()` classmethod to `Binding` that handles the conversion:
+
+```python
+# flopy4/mf6/binding.py
+
+@define
+class Binding:
+    type: str
+    fname: str
+    terms: tuple[str, ...] | None = None
+
+    @classmethod
+    def from_component(cls, component: Component) -> "Binding":
+        """Create binding from component (for write)."""
+        # ... existing code ...
+
+    @classmethod
+    def to_component(cls, binding_tuple: tuple, workspace: Path) -> Component:
+        """
+        Resolve binding tuple to component instance (for load).
+
+        Parameters
+        ----------
+        binding_tuple : tuple
+            Binding in form (type, fname) or (type, fname, *terms)
+        workspace : Path
+            Workspace directory for resolving file paths
+
+        Returns
+        -------
+        Component
+            Loaded component instance
+        """
+        binding_type, fname = binding_tuple[0:2]
+        terms = binding_tuple[2:] if len(binding_tuple) > 2 else ()
+
+        # Resolve component class from type
+        component_cls = _resolve_component_class(binding_type)
+
+        # Recursively load the component
+        component_path = workspace / fname
+        component = component_cls.load(component_path)
+
+        # Apply terms (e.g., set name from binding)
+        if terms:
+            component.name = terms[0]
+
+        return component
+
+
+def _resolve_component_class(binding_type: str) -> type[Component]:
+    """Map binding type string to component class."""
+    type_map = {
+        'gwf6': 'flopy4.mf6.gwf.Model',
+        'gwt6': 'flopy4.mf6.gwt.Model',
+        'gwe6': 'flopy4.mf6.gwe.Model',
+        'ims6': 'flopy4.mf6.ims.Ims',
+        'gwf-gwf': 'flopy4.mf6.exchange.GwfGwf',
+        # ... etc
+    }
+
+    if binding_type.lower() not in type_map:
+        raise ValueError(f"Unknown binding type: {binding_type}")
+
+    # Dynamic import
+    module_path, class_name = type_map[binding_type.lower()].rsplit('.', 1)
+    module = __import__(module_path, fromlist=[class_name])
+    return getattr(module, class_name)
+```
+
+### Pros
+- ✅ Symmetric API: `from_component()` (write) ↔ `to_component()` (load)
+- ✅ Encapsulates type resolution logic in one place
+- ✅ Binding class owns both directions of the transformation
+- ✅ Composable with Approach 2 for the actual resolution loop
+
+### Cons
+- ❌ Couples Binding class to component loading (circular dependency risk)
+- ❌ Still needs a driver (Approach 1 or 2) to call it
+- ❌ Type map maintenance burden
+
+---
+
+## Recommended Approach: Hybrid (2 + 3)
+
+**Use Approach 2 (post-processing) as the driver, with Approach 3 (Binding.to_component) for the conversion logic.**
+
+### Implementation Strategy
+
+1. **Add `Binding.to_component()` method** to encapsulate type resolution and loading:
+   ```python
+   # Symmetric to Binding.from_component()
+   Binding.to_component(binding_tuple, workspace) → Component
+   ```
+
+2. **Add `resolve_bindings()` post-processor** to handle the iteration:
+   ```python
+   def resolve_bindings(component: Component, workspace: Path) -> Component:
+       """Post-process component to resolve binding tuples."""
+       if isinstance(component, Simulation):
+           # Use Binding.to_component() for each binding
+           component.models = _resolve_binding_dict(component.models, workspace)
+           component.solutions = _resolve_binding_dict(component.solutions, workspace)
+           component.exchanges = _resolve_binding_dict(component.exchanges, workspace)
+       return component
+   ```
+
+3. **Call from loaders** after structuring:
+   ```python
+   def _load_mf6(cls, path: Path) -> Component:
+       component = structure(load_mf6(fp), path, component_type=cls)
+       component = resolve_bindings(component, path.parent)
+       return component
+   ```
+
+### Why This is Best
+
+1. **Separation of Concerns**
+   - `Binding.to_component()`: Type resolution + loading (cohesive, reusable)
+   - `resolve_bindings()`: Iteration + dict building (structural transformation)
+   - Loaders: Orchestration (parse → structure → resolve → return)
+
+2. **Symmetric Design**
+   - Write: `Component → Binding.from_component() → tuple`
+   - Load: `tuple → Binding.to_component() → Component`
+
+3. **Testability**
+   - Test `Binding.to_component()` with simple bindings
+   - Test `resolve_bindings()` with mock components
+   - Test loaders end-to-end with real files
+
+4. **Flexibility**
+   - Can skip binding resolution for unit tests
+   - Can resolve bindings for programmatically created components
+   - Can extend to support lazy loading later
+
+5. **Compatibility with Classmethod API**
+   - `Binding.to_component()` naturally calls `Component.load()` classmethod
+   - Recursive loading works seamlessly
+   - Workspace propagates correctly
+
+---
+
+## Implementation Checklist
+
+- [ ] Add `Binding.to_component(binding_tuple, workspace)` classmethod
+- [ ] Add `_resolve_component_class(binding_type)` helper function
+- [ ] Add `resolve_bindings(component, workspace)` post-processor
+- [ ] Integrate `resolve_bindings()` into `_load_mf6()`, `_load_json()`, `_load_toml()`
+- [ ] Update transformer to preserve binding tuples in output
+- [ ] Write tests for `Binding.to_component()`
+- [ ] Write tests for `resolve_bindings()`
+- [ ] Write integration tests for Simulation.load() with bindings
+
+---
+
+## Future Enhancements
+
+### Lazy Loading
+Instead of loading all child components immediately, could return proxy objects:
+
+```python
+class BindingProxy:
+    def __init__(self, binding_tuple, workspace):
+        self.binding_tuple = binding_tuple
+        self.workspace = workspace
+        self._component = None
+
+    @property
+    def component(self):
+        if self._component is None:
+            self._component = Binding.to_component(self.binding_tuple, self.workspace)
+        return self._component
+```
+
+### Caching
+Avoid loading the same component multiple times:
+
+```python
+def resolve_bindings(component, workspace, cache=None):
+    cache = cache or {}
+    # Check cache before calling Binding.to_component()
+    # Store loaded components in cache by path
+```
+
+### Validation
+Verify binding references exist before attempting to load:
+
+```python
+def validate_bindings(component, workspace):
+    """Check that all binding files exist before loading."""
+    # Collect all binding tuples
+    # Verify files exist
+    # Raise helpful error if missing
+```
+
+---
+
+## Related Issues
+
+- Simulation structuring bug (name parameter receives entire dict)
+  - **Fixed by**: Passing `component_type=cls` to `structure()` ✅
+  - Implemented in this session
+
+- Transformer output format for simulations
+  - **Needs**: Simulation parser/transformer implementation
+  - **Blocks**: Full simulation loading until implemented
+
+- Component dimension resolution for standalone package loading
+  - **Future**: May need `dims` parameter for `Package.load(path, dims={...})`
+  - Not needed for Simulation/Model loading (get dims from children)