diff --git a/docs/exec-plans/active/20260407-formdsl-iga-multipatch-interface-controls.md b/docs/exec-plans/active/20260407-formdsl-iga-multipatch-interface-controls.md new file mode 100644 index 0000000..3d6a8d6 --- /dev/null +++ b/docs/exec-plans/active/20260407-formdsl-iga-multipatch-interface-controls.md @@ -0,0 +1,41 @@ +# Form DSL IGA Multipatch Interface Controls + +## Objective + +Add deterministic per-interface coupling controls for IGA multipatch assembly +while preserving global fallback semantics. + +## Scope + +- Add optional per-interface penalty field in multipatch interface descriptors. +- Validate interface penalties deterministically during parsing/IR checks. +- Apply per-interface override precedence over global `multipatch_penalty`. +- Expose effective interface penalty values in IGA payload metadata. +- Add regression tests and docs updates. + +## Non-Goals + +- DG-SEM multipatch execution. +- New coupling families beyond current penalty-style model. +- Adaptive penalty tuning heuristics. + +## Acceptance Criteria + +- Valid per-interface penalties parse and propagate through IR. +- Per-interface penalties override global penalty for targeted interfaces only. +- Invalid penalty values fail deterministically. +- IGA payload metadata reports effective interface penalties. +- Regression tests and docs cover new behavior. + +## Implementation Checklist + +- [x] Add OpenSpec proposal/design/spec/tasks artifacts. +- [ ] Implement descriptor and validation support for optional interface + penalties. +- [ ] Implement IGA precedence and metadata exposure for effective penalties. +- [ ] Add regression tests and docs updates. + +## Risks / Open Questions + +- Interface duplicates remain invalid regardless of penalties; no merge policy is + introduced in this phase. diff --git a/docs/formdsl-nurbs-multipatch-evaluation.md b/docs/formdsl-nurbs-multipatch-evaluation.md index fec96aa..37c4508 100644 --- a/docs/formdsl-nurbs-multipatch-evaluation.md +++ b/docs/formdsl-nurbs-multipatch-evaluation.md @@ -56,6 +56,10 @@ Implication: ## Tracking +- Active OpenSpec change: + `openspec/changes/formdsl-iga-multipatch-interface-controls/` +- Active execution plan: + `docs/exec-plans/active/20260407-formdsl-iga-multipatch-interface-controls.md` - Multipatch numerical coupling archive: `openspec/changes/archive/2026-04-07-formdsl-iga-multipatch-interface-coupling-numerics/` - Multipatch numerical completed plan: diff --git a/docs/ufl-backend-support.md b/docs/ufl-backend-support.md index a0db15a..45366dc 100644 --- a/docs/ufl-backend-support.md +++ b/docs/ufl-backend-support.md @@ -176,3 +176,6 @@ These are tracked outcomes from the Phase 3 backlog tasks: `openspec/changes/archive/2026-04-07-formdsl-iga-multipatch-interface-coupling-numerics/` and `docs/exec-plans/completed/20260407-formdsl-iga-multipatch-interface-coupling-numerics.md`. + Per-interface coupling controls are tracked in active change + `openspec/changes/formdsl-iga-multipatch-interface-controls/` and active plan + `docs/exec-plans/active/20260407-formdsl-iga-multipatch-interface-controls.md`. diff --git a/openspec/changes/formdsl-iga-multipatch-interface-controls/.openspec.yaml b/openspec/changes/formdsl-iga-multipatch-interface-controls/.openspec.yaml new file mode 100644 index 0000000..2fe001e --- /dev/null +++ b/openspec/changes/formdsl-iga-multipatch-interface-controls/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-04-07 diff --git a/openspec/changes/formdsl-iga-multipatch-interface-controls/design.md b/openspec/changes/formdsl-iga-multipatch-interface-controls/design.md new file mode 100644 index 0000000..bd2d874 --- /dev/null +++ b/openspec/changes/formdsl-iga-multipatch-interface-controls/design.md @@ -0,0 +1,50 @@ +## Context + +`multipatch_penalty` currently configures one scalar value for all IGA +multipatch interfaces. Recent multipatch stress fixtures showed a practical need +for heterogeneous interface weights while keeping deterministic behavior. + +## Goals / Non-Goals + +**Goals** + +- Add optional per-interface penalty control in multipatch descriptors. +- Preserve deterministic fallback to global `multipatch_penalty` when interface + penalty is omitted. +- Keep parsing and assembly validation deterministic for malformed penalties. +- Expose effective interface penalties in IGA payload metadata. + +**Non-Goals** + +- DG-SEM multipatch execution. +- Interface-family expansion beyond current penalty-style coupling model. +- Runtime adaptive penalty heuristics. + +## Decisions + +1. Add optional `penalty` field on each interface descriptor. + - Rationale: keeps controls colocated with interface topology/orientation. + +2. Keep metadata-level `multipatch_penalty` as fallback. + - Rationale: backward-compatible behavior for existing payloads. + +3. Validate penalties at parse and IR-validation stages. + - Rationale: fail early with deterministic diagnostics before assembly. + +4. Record effective coupling penalty in `interface_lowering` metadata. + - Rationale: improves observability and testability of control precedence. + +## Risks / Trade-offs + +- [Risk] Duplicate interfaces with differing penalties may still be ambiguous. + - Mitigation: keep canonical duplicate rejection independent of penalty. +- [Risk] Very large penalties can worsen conditioning. + - Mitigation: enforce finite positive values and leave numerical tuning to the + caller. + +## Migration Plan + +1. Extend OpenSpec requirements for per-interface coupling controls. +2. Implement IR/parser support and deterministic penalty validation. +3. Apply per-interface penalty precedence in IGA coupling assembly. +4. Add regression tests/docs and update execution tracking. diff --git a/openspec/changes/formdsl-iga-multipatch-interface-controls/proposal.md b/openspec/changes/formdsl-iga-multipatch-interface-controls/proposal.md new file mode 100644 index 0000000..fd89534 --- /dev/null +++ b/openspec/changes/formdsl-iga-multipatch-interface-controls/proposal.md @@ -0,0 +1,41 @@ +## Why + +IGA multipatch coupling now supports deterministic metadata and numerical +interface contributions, but coupling strength is controlled only by one global +metadata value (`multipatch_penalty`). This makes heterogeneous interface +stabilization awkward because users cannot tune individual interfaces without +changing all interface penalties. + +We need deterministic per-interface coupling controls so interface-specific +penalties can be expressed directly in multipatch descriptors while preserving +current global-default behavior. + +## What Changes + +- Extend multipatch interface descriptors with optional per-interface penalty + configuration. +- Keep `multipatch_penalty` metadata as the global fallback when interface + penalty is omitted. +- Validate per-interface penalties deterministically (finite, positive). +- Surface effective interface penalties in IGA lowering payload metadata. +- Add regression coverage for override precedence and malformed controls. + +## Capabilities + +### Modified Capabilities + +- `ufl-iga-form-dsl`: multipatch coupling control expands from global penalty + only to per-interface override controls with deterministic fallback semantics. + +### Unchanged Capabilities + +- `ufl-dgsem-form-dsl`: remains multipatch execution unsupported. + +## Impact + +- Affected code: + - `src/cutkit/formdsl/ir.py` + - `src/cutkit/formdsl/adapter.py` + - `src/cutkit/formdsl/iga_backend.py` + - `tests/formdsl/test_formdsl_assembly.py` + - docs updates under `docs/` diff --git a/openspec/changes/formdsl-iga-multipatch-interface-controls/specs/form-dsl-backend-assembly/spec.md b/openspec/changes/formdsl-iga-multipatch-interface-controls/specs/form-dsl-backend-assembly/spec.md new file mode 100644 index 0000000..1285578 --- /dev/null +++ b/openspec/changes/formdsl-iga-multipatch-interface-controls/specs/form-dsl-backend-assembly/spec.md @@ -0,0 +1,30 @@ +## ADDED Requirements + +### Requirement: Multipatch interface descriptors accept optional penalties +The system SHALL accept optional finite positive per-interface penalty values in +multipatch interface descriptors. + +#### Scenario: Parse interface descriptor with penalty +- **WHEN** a multipatch interface descriptor includes a valid numeric positive + `penalty` +- **THEN** parsing succeeds and IR retains the per-interface penalty value + +### Requirement: IGA multipatch coupling applies deterministic penalty precedence +The system SHALL use per-interface `penalty` when present and otherwise fall +back to global `multipatch_penalty` metadata. + +#### Scenario: Interface penalty overrides global penalty +- **WHEN** a form provides both global `multipatch_penalty` metadata and a + specific interface `penalty` +- **THEN** that interface uses its own penalty value during coupling assembly + and payload metadata reports the effective value + +### Requirement: Invalid interface penalties fail deterministically +The system MUST reject malformed per-interface penalties with deterministic +validation errors. + +#### Scenario: Non-finite or non-positive interface penalty +- **WHEN** a multipatch interface descriptor specifies `penalty` that is + non-numeric, non-finite, or non-positive +- **THEN** parsing or IR validation fails with deterministic error metadata + naming the invalid penalty field diff --git a/openspec/changes/formdsl-iga-multipatch-interface-controls/tasks.md b/openspec/changes/formdsl-iga-multipatch-interface-controls/tasks.md new file mode 100644 index 0000000..c1edd9a --- /dev/null +++ b/openspec/changes/formdsl-iga-multipatch-interface-controls/tasks.md @@ -0,0 +1,21 @@ +## 1. OpenSpec Artifacts + +- [x] 1.1 Add proposal/design/spec/tasks artifacts for per-interface multipatch + controls. + +## 2. Descriptor + Validation + +- [ ] 2.1 Add optional per-interface penalty field to multipatch interface + descriptors in IR/parser. +- [ ] 2.2 Add deterministic validation for malformed per-interface penalties. + +## 3. IGA Coupling Integration + +- [ ] 3.1 Apply per-interface penalty override precedence in IGA interface + coupling assembly. +- [ ] 3.2 Expose effective interface penalty values in lowering metadata. + +## 4. Validation + Docs + +- [ ] 4.1 Add regression tests for precedence behavior and malformed values. +- [ ] 4.2 Update docs and execution-plan progress.