FESADev/docs/implementation-plans/analysis-state-analysis-base-implementation-plan.md

Analysis State And Analysis Base Implementation Plan

Metadata

• feature_id: analysis-state-analysis-base
• source_requirement: AGENTS.md; docs/PRD.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 state ownership and analysis strategy rules
• source_reference_models: N/A for this architecture foundation slice
• status: ready-for-implementation
• owner_agent: implementation-planning-agent
• date: 2026-06-09

Readiness Check

input	required_status	observed_status	decision
architecture	Domain, Analysis, AnalysisState boundaries documented	documented in docs/ARCHITECTURE.md and ADR-010	proceed
domain foundation	Domain runtime storage available	implemented in prior phases	proceed
formulation	not required for state/interface foundation	N/A	proceed
numerical_review	not required for state/interface foundation	N/A	proceed
io_definition	not required; no result output in this phase	N/A	proceed
reference_models	not required because this phase produces no solver result	N/A	proceed

Implementation Scope

• included_behavior: AnalysisState mutable vector state for displacement, external force, internal force, residual, and reaction.
• included_behavior: AnalysisState time, increment, and iteration counters.
• included_behavior: Analysis base interface for future analysis strategies.
• included_behavior: CMake/CTest registration for analysis-layer unit tests.
• excluded_behavior: AnalysisModel, DofManager, equation numbering, global assembly, boundary-condition elimination, linear solve, MITC4 numerical formulation, HDF5 output, and reference comparison.
• non_goals: numerical correctness claims, release readiness, reference-solver execution, and reference artifact generation.

AnalysisState Contract

AnalysisState lives under fesa::core and owns mutable analysis quantities only. It does not reference or own Domain, model objects, equation maps, sparse matrices, solvers, result writers, or reference artifacts.

Required interface:

namespace fesa::core {

class AnalysisState {
public:
    AnalysisState();
    explicit AnalysisState(std::size_t dof_count);

    std::size_t dofCount() const noexcept;
    void resize(std::size_t dof_count);

    const std::vector<double>& displacement() const noexcept;
    const std::vector<double>& externalForce() const noexcept;
    const std::vector<double>& internalForce() const noexcept;
    const std::vector<double>& residual() const noexcept;
    const std::vector<double>& reaction() const noexcept;

    void setDisplacement(std::vector<double> values);
    void setExternalForce(std::vector<double> values);
    void setInternalForce(std::vector<double> values);
    void setResidual(std::vector<double> values);
    void setReaction(std::vector<double> values);
    void clearForces() noexcept;

    double currentTime() const noexcept;
    void setCurrentTime(double value) noexcept;
    std::int64_t incrementIndex() const noexcept;
    void setIncrementIndex(std::int64_t value) noexcept;
    std::int64_t iterationIndex() const noexcept;
    void setIterationIndex(std::int64_t value) noexcept;
};

} // namespace fesa::core

This phase intentionally defers velocity, acceleration, temperature, element state, and integration-point state until dynamic, thermal, nonlinear, or element-state phases define concrete contracts.

Analysis Base Contract

Analysis lives under fesa::analysis and is the base strategy interface for future analysis algorithms. Domain is immutable input. AnalysisState is mutable output/state.

Required interface:

namespace fesa::analysis {

class Analysis {
public:
    virtual ~Analysis() = default;

    virtual const char* name() const noexcept = 0;
    void run(const fesa::core::Domain& domain, fesa::core::AnalysisState& state);

protected:
    virtual void doRun(const fesa::core::Domain& domain, fesa::core::AnalysisState& state) = 0;
};

} // namespace fesa::analysis

Analysis::run is only an entry-point wrapper in this phase. It does not define assembly, solve, boundary-condition, or output hooks until AnalysisModel and DofManager exist.

Work Breakdown

task_id	order	purpose	upstream_trace	depends_on	expected_test_first
ASAB-001	1	record state and base-analysis contract	ADR-010; docs/ARCHITECTURE.md	none	N/A
ASAB-002	2	add AnalysisState zero-sized and sized state	ADR-010 AnalysisState	ASAB-001	ASAB-TEST-001
ASAB-003	3	add AnalysisState mutation guards and counters	docs/ARCHITECTURE.md State Ownership	ASAB-002	ASAB-TEST-002
ASAB-004	4	add Analysis base interface	docs/ARCHITECTURE.md Analysis strategy	ASAB-003	ASAB-TEST-003
ASAB-005	5	register analysis CTest path	AGENTS.md C++ validation	ASAB-004	ASAB-TEST-004
ASAB-006	6	record build/test evidence and handoff	docs/build-test-reports/README.md	ASAB-005	ASAB-TEST-005

TDD Test Plan

test_id	order	test_type	red_condition	green_condition	linked_task	command
ASAB-TEST-001	1	unit	AnalysisState header/class missing	default and sized state tests pass	ASAB-002	ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R analysis
ASAB-TEST-002	2	unit	setter/guard methods missing	mutation guard and counter tests pass	ASAB-003	ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R analysis
ASAB-TEST-003	3	unit	Analysis header/base missing	derived recording analysis tests pass	ASAB-004	ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R analysis
ASAB-TEST-004	4	integration	analysis tests not registered or not built	ctest -R analysis runs analysis target	ASAB-005	`ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R "analysis
ASAB-TEST-005	5	validation	report evidence missing	validation report records passing commands or classified failure	ASAB-006	python scripts/validate_workspace.py

CMake/CTest Plan

• target_candidates: fesa_core, fesa_analysis_tests
• add_test_needs: register analysis.base
• labels: analysis, core
• msvc_config: Debug
• expected_feature_command: ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R analysis
• workspace_validation: python scripts/validate_workspace.py

Candidate Files and Ownership

file_candidate	purpose	owner_boundary	notes
include/fesa/core/AnalysisState.hpp	mutable analysis state public contract	core state	no Domain/model object ownership
src/core/AnalysisState.cpp	state vector/counter implementation	core state	no solver logic
include/fesa/analysis/Analysis.hpp	base analysis strategy interface	analysis	no LinearStaticAnalysis implementation
tests/core/analysis_state_test.cpp	state TDD coverage	tests	write before production changes
tests/analysis/analysis_base_test.cpp	analysis base TDD coverage	tests	write before production changes
CMakeLists.txt	source and CTest registration	build	MSVC Debug compatible

Acceptance Traceability Matrix

requirement_id	task_id	test_id	reference_model_id	acceptance_criterion	status
ASAB-REQ-001 mutable state is outside Domain	ASAB-002	ASAB-TEST-001	N/A	AnalysisState tests pass and Domain remains unchanged	draft
ASAB-REQ-002 state vectors are size-consistent	ASAB-003	ASAB-TEST-002	N/A	size mismatch throws and failed setters do not mutate	draft
ASAB-REQ-003 Analysis takes const Domain and mutable state	ASAB-004	ASAB-TEST-003	N/A	recording analysis updates state through base API	draft
ASAB-REQ-004 C++ validation path includes analysis tests	ASAB-005	ASAB-TEST-004	N/A	ctest -R analysis runs successfully	draft

Validation Commands

ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R analysis
ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R "analysis|domain|model-object|io"
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
git diff --check

Risks and Downstream Handoff

Implementation Agent

• Keep AnalysisState as storage only.
• Keep Analysis as a base interface only.
• Do not introduce LinearStaticAnalysis until AnalysisModel and DofManager contracts exist.

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 state headers, state sources, analysis header, analysis tests, or CMake registration.
• Upstream-contract failures include requests to add equation numbering, assembly, solver behavior, HDF5 output, or numerical MITC4 behavior 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

• AnalysisModel, DofManager, and LinearStaticAnalysis remain separate downstream phases.