김경종
191 lines
12 KiB
Markdown
191 lines
12 KiB
Markdown
# Domain Model Foundation Implementation Plan
|
|
|
|
## Metadata
|
|
- feature_id: domain-model-foundation
|
|
- source_requirement: AGENTS.md; docs/ARCHITECTURE.md; docs/ADR.md
|
|
- source_research: N/A for this architecture foundation slice
|
|
- source_formulation: N/A for this architecture foundation slice
|
|
- source_numerical_review: N/A for this architecture foundation slice
|
|
- source_io_definition: docs/ARCHITECTURE.md input-model ownership rules
|
|
- source_reference_models: N/A for this architecture foundation slice
|
|
- status: ready-for-implementation
|
|
- owner_agent: implementation-planning-agent
|
|
- date: 2026-06-08
|
|
|
|
## Readiness Check
|
|
|
|
| input | required_status | observed_status | decision |
|
|
| --- | --- | --- | --- |
|
|
| architecture | Domain, AnalysisModel, AnalysisState, DofManager boundaries documented | documented in docs/ARCHITECTURE.md and docs/ADR.md | proceed |
|
|
| requirements | Domain ownership rules documented | documented in AGENTS.md and docs/ARCHITECTURE.md | proceed |
|
|
| formulation | not required for model-container storage | N/A | proceed |
|
|
| numerical_review | not required for model-container storage | N/A | proceed |
|
|
| io_definition | parser contract not required; semantic storage boundary documented | sufficient for Domain foundation | proceed |
|
|
| reference_models | not required because this slice produces no solver result | N/A | proceed |
|
|
|
|
## Implementation Scope
|
|
|
|
- included_behavior: C++17 core model-definition storage for nodes, element definitions, material definitions, shell property definitions, sets, boundary conditions, nodal loads, and linear static step definitions.
|
|
- included_behavior: CMake/CTest bootstrap for MSVC x64 Debug validation.
|
|
- included_behavior: deterministic id validation and const retrieval APIs for stored model definitions.
|
|
- excluded_behavior: MITC4 stiffness, shape functions, Jacobian checks, assembly, solver, reaction recovery, HDF5 output, Abaqus parser, MKL, TBB, and reference comparison.
|
|
- non_goals: numerical correctness claims, release readiness, Abaqus/Nastran execution, and stored reference artifact generation.
|
|
|
|
## Domain Contract
|
|
|
|
`Domain` owns parsed model definitions only. It preserves the model that an input parser or factory layer creates and should be treated as immutable by analysis code after parsing/building is complete.
|
|
|
|
Included model definitions:
|
|
|
|
- nodes
|
|
- element definitions
|
|
- material definitions
|
|
- shell property definitions
|
|
- node sets
|
|
- element sets
|
|
- boundary conditions
|
|
- nodal loads
|
|
- analysis step definitions
|
|
|
|
Excluded state:
|
|
|
|
- equation ids
|
|
- sparse matrix structure or values
|
|
- reduced or full displacement vectors
|
|
- residual vectors
|
|
- reaction vectors
|
|
- current time
|
|
- increment counters
|
|
- nonlinear iteration counters
|
|
- element integration point state
|
|
- MKL, TBB, or HDF5 handles
|
|
|
|
Boundary responsibilities:
|
|
|
|
- `DofManager` owns active DOF discovery, constrained/free DOF mapping, equation numbering, sparse pattern connectivity, and full-vector reconstruction.
|
|
- `AnalysisModel` owns the step-local execution view over active domain objects. It references `Domain` objects by id or stable reference and does not copy the whole domain.
|
|
- `AnalysisState` owns mutable solution, residual, load vector, time/increment, and future element state.
|
|
|
|
Common data rules:
|
|
|
|
- All ids use signed 64-bit storage.
|
|
- Node DOF order is `U1, U2, U3, UR1, UR2, UR3`.
|
|
- Coordinates and scalar physical values use `double`.
|
|
- Units are user-consistent and are not enforced or converted by `Domain`.
|
|
- Duplicate ids fail with `std::invalid_argument`.
|
|
- Insertions that reference missing required objects fail with `std::invalid_argument`.
|
|
- Direct lookup of a missing object fails with `std::out_of_range`.
|
|
- Optional `find*` lookup APIs return `nullptr` for missing objects.
|
|
- Retrieval APIs return const references or const pointers.
|
|
|
|
## Work Breakdown
|
|
|
|
| task_id | order | purpose | upstream_trace | depends_on | expected_test_first |
|
|
| --- | --- | --- | --- | --- | --- |
|
|
| TASK-001 | 1 | Bootstrap CMake, core target, and CTest for Domain tests | ADR-002 | none | TEST-001 |
|
|
| TASK-002 | 2 | Define signed 64-bit id aliases and six-DOF ordering constants | ADR-014; AGENTS.md MITC4 scope | TASK-001 | TEST-002 |
|
|
| TASK-003 | 3 | Add `Node` and node storage/retrieval in `Domain` | ADR-010; docs/ARCHITECTURE.md Domain section | TASK-002 | TEST-003 |
|
|
| TASK-004 | 4 | Add MITC4 element definition storage without element computation | ADR-004; docs/ARCHITECTURE.md Core Runtime Objects | TASK-003 | TEST-004 |
|
|
| TASK-005 | 5 | Add material, shell property, node set, and element set storage | docs/ARCHITECTURE.md Domain included data | TASK-004 | TEST-005 |
|
|
| TASK-006 | 6 | Add boundary condition, nodal load, and linear static step definition storage | ADR-012; docs/ARCHITECTURE.md Domain included data | TASK-005 | TEST-006 |
|
|
| TASK-007 | 7 | Lock down Domain invariants and failed-insert stability | ADR-010; docs/AGENT_RULES.md boundaries | TASK-006 | TEST-007 |
|
|
| TASK-008 | 8 | Record build/test evidence and handoff status | docs/build-test-reports/README.md | TASK-007 | TEST-008 |
|
|
|
|
## TDD Test Plan
|
|
|
|
| test_id | order | test_type | red_condition | green_condition | linked_task | command |
|
|
| --- | --- | --- | --- | --- | --- | --- |
|
|
| TEST-001 | 1 | CTest bootstrap | `domain.bootstrap` is not registered or cannot run | `domain.bootstrap` passes under MSVC Debug | TASK-001 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain.bootstrap` |
|
|
| TEST-002 | 2 | unit | `fesa/core/ModelTypes.hpp` is missing | id aliases are 64-bit and DOF ordinals are 0..5 | TASK-002 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain` |
|
|
| TEST-003 | 3 | unit | `Node` and `Domain` node APIs are missing | add/find/direct lookup/duplicate node tests pass | TASK-003 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain` |
|
|
| TEST-004 | 4 | unit | element definition APIs are missing | element add/find/direct lookup/connectivity/missing-node tests pass | TASK-004 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain` |
|
|
| TEST-005 | 5 | unit | material, property, and set APIs are missing | material/property/set validation tests pass | TASK-005 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain` |
|
|
| TEST-006 | 6 | unit | boundary, load, and step APIs are missing | BC/load/step storage tests pass | TASK-006 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain` |
|
|
| TEST-007 | 7 | unit | failed insertion mutates Domain or mutable access leaks | invariant and failed-insert stability tests pass | TASK-007 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain` |
|
|
| TEST-008 | 8 | validation | build/test evidence is missing | build/test report records passing validation or classified failure | TASK-008 | `python scripts/validate_workspace.py` |
|
|
|
|
## CMake/CTest Plan
|
|
|
|
- target_candidates: `fesa_core`, `fesa_domain_tests`
|
|
- add_test_needs: `domain.bootstrap` initially, then Domain behavior tests under the same `domain` CTest filter.
|
|
- labels: `domain`, `core`
|
|
- msvc_config: Debug
|
|
- expected_feature_command: `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain`
|
|
- workspace_validation: `python scripts/validate_workspace.py`
|
|
|
|
## Candidate Files and Ownership
|
|
|
|
| file_candidate | purpose | owner_boundary | notes |
|
|
| --- | --- | --- | --- |
|
|
| `CMakeLists.txt` | root CMake project, core library, CTest registration | build/test bootstrap | MSVC x64 Debug baseline |
|
|
| `include/fesa/core/ModelTypes.hpp` | id aliases and DOF constants | core model definitions | no solver state |
|
|
| `include/fesa/core/Node.hpp` | node id and coordinate definition | core model definitions | no displacement storage |
|
|
| `include/fesa/core/ElementDefinition.hpp` | element id, type, connectivity, property reference | core model definitions | no stiffness behavior |
|
|
| `include/fesa/core/MaterialDefinition.hpp` | linear elastic material input definition | core model definitions | no constitutive matrix |
|
|
| `include/fesa/core/PropertyDefinition.hpp` | shell property input definition | core model definitions | no section stiffness |
|
|
| `include/fesa/core/BoundaryCondition.hpp` | prescribed DOF value definition | core model definitions | no matrix application |
|
|
| `include/fesa/core/LoadDefinition.hpp` | nodal load definition | core model definitions | no global vector assembly |
|
|
| `include/fesa/core/StepDefinition.hpp` | linear static step definition | core model definitions | no analysis driver |
|
|
| `include/fesa/core/Domain.hpp` | Domain public storage/retrieval API | core model definitions | const retrieval only |
|
|
| `src/core/Domain.cpp` | Domain validation and storage implementation | core model definitions | no external dependencies |
|
|
| `tests/core/domain_bootstrap_test.cpp` | CTest bootstrap executable | test | created before production code |
|
|
| `tests/core/model_types_test.cpp` | id and DOF tests | test | optional separate executable |
|
|
| `tests/core/domain_storage_test.cpp` | Domain behavior tests | test | required before production changes |
|
|
|
|
## Data Flow Contract
|
|
|
|
1. A future Abaqus parser and factory/registry layer creates semantic model definitions.
|
|
2. `Domain` stores those definitions and validates duplicate ids and missing required references.
|
|
3. A future `AnalysisModel` builds a step-local execution view from `Domain` ids or stable references.
|
|
4. A future `DofManager` derives active DOFs and equation ids outside `Domain`.
|
|
5. A future `AnalysisState` stores solution and iteration state outside `Domain`.
|
|
|
|
## Acceptance Traceability Matrix
|
|
|
|
| requirement_id | task_id | test_id | reference_model_id | acceptance_criterion | status |
|
|
| --- | --- | --- | --- | --- | --- |
|
|
| DOM-REQ-001 Domain owns parsed model definitions | TASK-003 to TASK-006 | TEST-003 to TEST-006 | N/A | storage and const retrieval tests pass | draft |
|
|
| DOM-REQ-002 Domain excludes solver state | TASK-007 | TEST-007 | N/A | invariant tests and member review pass | draft |
|
|
| DOM-REQ-003 ids use signed 64-bit storage | TASK-002 | TEST-002 | N/A | `sizeof(Id) == 8` test passes | draft |
|
|
| DOM-REQ-004 node DOF order is fixed | TASK-002 | TEST-002 | N/A | DOF ordinal test passes | draft |
|
|
| DOM-REQ-005 duplicate ids are rejected | TASK-003 to TASK-006 | TEST-003 to TEST-006 | N/A | duplicate tests throw `std::invalid_argument` | draft |
|
|
| DOM-REQ-006 missing required references are rejected | TASK-004 to TASK-006 | TEST-004 to TEST-006 | N/A | missing-reference tests throw `std::invalid_argument` | draft |
|
|
| DOM-REQ-007 direct missing lookup is deterministic | TASK-003 to TASK-007 | TEST-003 to TEST-007 | N/A | direct missing lookup throws `std::out_of_range` | draft |
|
|
| DOM-REQ-008 validation uses MSVC CMake/CTest | TASK-001; TASK-008 | TEST-001; TEST-008 | N/A | configure/build/CTest evidence recorded | draft |
|
|
|
|
## Validation Commands
|
|
|
|
```powershell
|
|
python -m unittest discover -s scripts -p "test_*.py"
|
|
python scripts/validate_workspace.py
|
|
ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain
|
|
```
|
|
|
|
## Risks and Downstream Handoff
|
|
|
|
### Implementation Agent
|
|
|
|
- Keep each storage layer separate and test-first.
|
|
- Do not add numerical behavior while implementing model definitions.
|
|
- Preserve `Domain` as a model container, not a solver-state object.
|
|
|
|
### Build/Test Executor Agent
|
|
|
|
- Use Visual Studio 17 2022, x64, Debug, and `build/msvc-debug`.
|
|
- After `CMakeLists.txt` exists, `python scripts/validate_workspace.py` must configure, build, and run CTest instead of taking the no-CMake path.
|
|
|
|
### Correction Agent
|
|
|
|
- Implementation-owned failures are expected to be compile or unit-test failures in `fesa_core` or `fesa_domain_tests`.
|
|
- Upstream-contract failures include requests to store equation ids, displacements, reaction vectors, or integration point state inside `Domain`.
|
|
|
|
### Reference Verification Agent
|
|
|
|
- No reference verification is required for this phase.
|
|
- This phase produces no HDF5 result and consumes no reference artifacts.
|
|
|
|
## Open Issues
|
|
|
|
- The full MITC4 requirements, formulation, I/O definition, and reference model artifacts are still separate upstream stages.
|
|
- The parser-to-Domain factory API is intentionally deferred until the Abaqus input subset phase.
|