FESADev/docs/implementation-plans/analysis-model-objects-implementation-plan.md

Analysis Model Objects Implementation Plan

Metadata

• feature_id: analysis-model-objects
• source_requirement: AGENTS.md; docs/ARCHITECTURE.md; docs/ADR.md
• source_research: N/A for this architecture/model-object slice
• source_formulation: N/A for this architecture/model-object slice
• source_numerical_review: N/A for this architecture/model-object slice
• source_io_definition: docs/ARCHITECTURE.md Domain and factory/registry ownership rules
• source_reference_models: N/A for this architecture/model-object slice
• status: ready-for-implementation
• owner_agent: implementation-planning-agent
• date: 2026-06-09

Readiness Check

input	required_status	observed_status	decision
architecture	model object boundaries documented	documented in docs/ARCHITECTURE.md and ADR-004/010/011	proceed
domain foundation	base Domain storage available	implemented in domain-model-foundation	proceed
formulation	not required for identity-only model object skeletons	N/A	proceed
numerical_review	not required for identity-only model object skeletons	N/A	proceed
io_definition	parser DTO compatibility sufficient	existing *Definition objects remain input DTOs	proceed
reference_models	not required because this slice produces no solver result	N/A	proceed

Implementation Scope

• included_behavior: C++17 model object classes for nodes, elements, materials, shell properties, loads, and boundary conditions.
• included_behavior: abstract base classes for element, material, load, and boundary condition model objects.
• included_behavior: MITC4 element model skeleton with id, connectivity, property id, 4-node count, and 24-DOF count.
• included_behavior: Domain RAII ownership for polymorphic model objects through std::unique_ptr.
• included_behavior: compatibility with existing *Definition value objects and tests.
• excluded_behavior: MITC4 stiffness, Jacobian, MITC shear interpolation, constitutive matrices, global force assembly, boundary-condition elimination, equation numbering, solver vectors, reaction recovery, HDF5 output, parser/factory implementation, and reference comparison.
• non_goals: numerical correctness claims, release readiness, reference-solver execution, and reference artifact generation.

Model Object Contract

Domain remains the owner of parsed model definition. This phase adds runtime model objects that can later be used by AnalysisModel, factories, and element/material implementations without storing analysis state in Domain.

Model object responsibilities:

• Node: id and reference coordinates only; fixed six-DOF count from project convention.
• Element: identity, element type, connectivity, property reference, and node count only.
• Mitc4Element: MITC4 model skeleton with four node ids and 24 element DOFs only.
• Material: material identity only.
• LinearElasticMaterial: id, Young's modulus, and Poisson ratio only.
• ShellProperty: property id, material id, and thickness only.
• Load: load kind only.
• NodalLoad: node id, DOF, and scalar value only.
• BoundaryCondition: boundary kind only.
• SinglePointConstraint: node id, DOF, and prescribed scalar value only.

Excluded from all model objects:

• equation ids
• sparse matrix data
• displacement, residual, reaction, velocity, acceleration, or temperature vectors
• current time, increment, or iteration counters
• element integration point state
• MKL, TBB, HDF5, or reference-comparison handles

Existing *Definition value objects remain parser/factory DTOs for now. This phase must not delete them. Later parser/factory work may either map DTOs into model objects or retire DTOs with an explicit migration plan.

Compatibility decision:

• Existing ElementDefinition, LinearElasticMaterialDefinition, ShellPropertyDefinition, BoundaryCondition, NodalLoadDefinition, and LinearStaticStepDefinition classes remain under include/fesa/core/ as value-style input DTOs.
• New runtime model objects live under ownership namespaces: fesa::element, fesa::material, fesa::property, fesa::load, and fesa::boundary.
• Domain supports both existing DTO storage APIs and new polymorphic model-object ownership APIs during the transition.
• Parser/factory work must make an explicit choice to map DTOs to model objects or replace DTOs in a separate phase. This phase does not decide parser behavior.

Work Breakdown

task_id	order	purpose	upstream_trace	depends_on	expected_test_first
AMO-001	1	refine Node model class contract	ADR-010; docs/ARCHITECTURE.md Node	none	AMO-TEST-001
AMO-002	2	add abstract Element base interface	ADR-004; docs/ARCHITECTURE.md Element	AMO-001	AMO-TEST-002
AMO-003	3	add MITC4 element model skeleton	AGENTS.md MITC4 scope	AMO-002	AMO-TEST-003
AMO-004	4	add material base and linear elastic material object	docs/ARCHITECTURE.md Material	AMO-002	AMO-TEST-004
AMO-005	5	add shell property model object	docs/ARCHITECTURE.md Property	AMO-004	AMO-TEST-005
AMO-006	6	add load base and nodal load object	docs/ARCHITECTURE.md loads	AMO-002	AMO-TEST-006
AMO-007	7	add boundary base and single-point constraint object	ADR-012	AMO-002	AMO-TEST-007
AMO-008	8	extend Domain with polymorphic object ownership	ADR-010; ADR-011	AMO-003 to AMO-007	AMO-TEST-008
AMO-009	9	preserve *Definition compatibility	domain-model-foundation plan	AMO-008	AMO-TEST-009
AMO-010	10	record build/test evidence and handoff	docs/build-test-reports/README.md	AMO-009	AMO-TEST-010

TDD Test Plan

test_id	order	test_type	red_condition	green_condition	linked_task	command
AMO-TEST-001	1	unit	Node::dofCount() missing	Node model tests pass	AMO-001	ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain
AMO-TEST-002	2	unit	fesa/element/Element.hpp missing	Element base polymorphism tests pass	AMO-002	ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model-object
AMO-TEST-003	3	unit	Mitc4Element missing	MITC4 model skeleton tests pass	AMO-003	ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model-object
AMO-TEST-004	4	unit	material model headers missing	material base and linear elastic tests pass	AMO-004	ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model-object
AMO-TEST-005	5	unit	shell property model missing	shell property tests pass	AMO-005	ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model-object
AMO-TEST-006	6	unit	load model headers missing	load base and nodal load tests pass	AMO-006	ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model-object
AMO-TEST-007	7	unit	boundary model headers missing	boundary base and SPC tests pass	AMO-007	ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model-object
AMO-TEST-008	8	unit	Domain polymorphic APIs missing	Domain owns and retrieves model objects by base interface	AMO-008	`ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R "domain
AMO-TEST-009	9	regression	existing definition tests fail	existing Domain definition tests remain passing	AMO-009	ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain
AMO-TEST-010	10	validation	report evidence missing	validation report records passing commands or classified failure	AMO-010	python scripts/validate_workspace.py

CMake/CTest Plan

• target_candidates: fesa_core, fesa_domain_tests, fesa_model_object_tests
• labels: domain, core, model-object, element, material, property, load, boundary
• msvc_config: Debug
• expected_feature_command: ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R "domain|model-object"
• workspace_validation: python scripts/validate_workspace.py

Candidate Files and Ownership

file_candidate	purpose	owner_boundary	notes
include/fesa/core/Node.hpp	existing node model object	core model definition	no solver state
include/fesa/element/Element.hpp	abstract element model base	element model identity	no stiffness API
include/fesa/element/Mitc4Element.hpp	MITC4 element model skeleton	element model identity	no formulation implementation
src/element/Mitc4Element.cpp	MITC4 model accessors	element model identity	no numerical behavior
include/fesa/material/Material.hpp	abstract material model base	material identity	no constitutive matrix
include/fesa/material/LinearElasticMaterial.hpp	linear elastic material model	material input values	no stress update
src/material/LinearElasticMaterial.cpp	linear elastic material accessors	material input values	no numerical behavior
include/fesa/property/ShellProperty.hpp	shell property model	property input values	no section stiffness
src/property/ShellProperty.cpp	shell property validation/accessors	property input values	thickness validation only
include/fesa/load/Load.hpp	abstract load model base	load identity	no assembly
include/fesa/load/NodalLoad.hpp	nodal load model	load input values	no global vector behavior
src/load/NodalLoad.cpp	nodal load accessors	load input values	no assembly
include/fesa/boundary/BoundaryCondition.hpp	abstract boundary model base	boundary identity	no matrix application
include/fesa/boundary/SinglePointConstraint.hpp	SPC boundary model	boundary input values	no reaction recovery
src/boundary/SinglePointConstraint.cpp	SPC accessors	boundary input values	no matrix application
include/fesa/core/Domain.hpp	Domain ownership extension	core ownership	preserve existing APIs
src/core/Domain.cpp	Domain ownership implementation	core ownership	no solver state
tests/**	TDD coverage	tests	write before production changes

Acceptance Traceability Matrix

requirement_id	task_id	test_id	reference_model_id	acceptance_criterion	status
AMO-REQ-001 Node is model data only	AMO-001	AMO-TEST-001	N/A	Node tests pass and no solver state added	draft
AMO-REQ-002 Element base is identity-only	AMO-002	AMO-TEST-002	N/A	Element base tests pass	draft
AMO-REQ-003 MITC4 model skeleton has 4 nodes and 24 DOFs	AMO-003	AMO-TEST-003	N/A	MITC4 model tests pass	draft
AMO-REQ-004 Material model stores input values only	AMO-004	AMO-TEST-004	N/A	material tests pass	draft
AMO-REQ-005 Shell property validates thickness only	AMO-005	AMO-TEST-005	N/A	shell property tests pass	draft
AMO-REQ-006 Load and boundary models do not assemble/apply	AMO-006; AMO-007	AMO-TEST-006; AMO-TEST-007	N/A	load/boundary tests pass and APIs remain value accessors	draft
AMO-REQ-007 Domain owns polymorphic model objects via RAII	AMO-008	AMO-TEST-008	N/A	Domain ownership tests pass	draft
AMO-REQ-008 Existing definition APIs remain compatible	AMO-009	AMO-TEST-009	N/A	existing domain tests pass	draft

Validation Commands

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|model-object"

Risks and Downstream Handoff

Implementation Agent

• Keep model objects identity-only until formulation and solver stages define numerical APIs.
  • Preserve existing *Definition tests.
• Prefer RAII ownership through std::unique_ptr and const retrieval.

Build/Test Executor Agent

• Use Visual Studio 17 2022, x64, Debug, and build/msvc-debug.
• Use python scripts/validate_workspace.py as canonical validation.

Correction Agent

• Implementation-owned failures are expected to be compile or unit-test failures in model object headers, model object sources, CMake registration, or Domain ownership methods.
• Upstream-contract failures include requests to add numerical MITC4 behavior or solver state in this phase.

Reference Verification Agent

• No reference verification is required for this phase.
• This phase produces no HDF5 result and consumes no reference artifacts.

Open Issues

• Parser/factory mapping from *Definition DTOs to model objects remains deferred.
• MITC4 formulation, material constitutive behavior, shell section stiffness, assembly, solver, and HDF5 output remain separate future phases.