FESADev/phases/1-linear-static-mitc4/step9.md

Step 9: reference-displacement-comparator

Sprint Contract

Objective

Implement the references/*_displacements.csv loader and comparator for FESA U output.

Required Reading

• /AGENTS.md
• /PROGRESS.md
• /PLAN.md
• /docs/README.md
• /docs/HARNESS_ENGINEERING.md
• /docs/NUMERICAL_CONVENTIONS.md
• /docs/VERIFICATION_PLAN.md
• /docs/RESULTS_SCHEMA.md
• /references/README.md
• /phases/1-linear-static-mitc4/step8.md

Scope

• Load Abaqus displacement CSV files with columns Node Label, U-U1, U-U2, U-U3, UR-UR1, UR-UR2, UR-UR3.
• Compare by node id, not row order.
• Implement absolute and relative tolerance behavior with a documented default or configuration path.
• Report missing columns, duplicate nodes, missing nodes, nonnumeric values, and tolerance failures.

Allowed Files

• include/**
• src/**
• tests/**
• references/** only for small test fixtures or documentation updates
• docs/VERIFICATION_PLAN.md only for comparator tolerance clarification
• docs/RESULTS_SCHEMA.md only for schema clarification
• PLAN.md
• PROGRESS.md
• phases/1-linear-static-mitc4/index.json

Explicit Non-Goals

• Do not require Abaqus execution.
• Do not treat references/quad_01.inp as Phase 1 supported input.
• Do not compare RF here unless a *_reactions.csv contract is added.

Tests To Write First

• CSV header validation tests.
• Node-id matching and row-order independence tests.
• Absolute/relative tolerance pass/fail tests.
• Duplicate, missing, and malformed value diagnostics tests.
• Format-only smoke test using references/quad_01_displacements.csv if stable enough for CI.

Reference Artifacts

• Format-only: references/quad_01_displacements.csv.
• Required later for solver regression: at least one Phase 1-compatible TYPE=S4 input and matching displacement CSV.

Acceptance Commands

python scripts/validate_workspace.py

Evaluator Checklist

• Component mapping matches docs/VERIFICATION_PLAN.md and docs/RESULTS_SCHEMA.md.
• Comparison is by node id and independent of row order.
• Missing or malformed reference data fails with actionable diagnostics.
• quad_01 is not used to imply S4R or nonlinear support.

Handoff Requirements

• Record comparator behavior, tolerance decision, and validation in PROGRESS.md.
• Update PLAN.md if R-009 or reference artifact blockers change.
• Update the matching phase index entry: use completed with a one-line summary, or blocked with blocked_reason, or error with error_message.

Verification

1. Run the acceptance command.
2. Inspect comparator tests for tolerance and malformed CSV behavior.

Do Not

• Do not silently skip reference nodes or components.