FESADev/phases/euler-beam-3d/step4.md

Step 4: io-reference-contract

Read These Files First

Read the following files before editing:

• /AGENTS.md
• /docs/PRD.md
• /docs/ARCHITECTURE.md
• /docs/ADR.md
• /docs/requirements/euler-beam-3d.md
• /docs/formulations/euler-beam-3d-formulation.md
• /docs/numerical-reviews/euler-beam-3d-review.md
• /docs/io-definitions/README.md
• /docs/reference-models/README.md

Task

Create two documents:

• /docs/io-definitions/euler-beam-3d-io.md
• /docs/reference-models/euler-beam-3d-reference-models.md

The I/O contract must describe the planned Abaqus subset without claiming it is implemented in this kernel increment:

• element keyword mapping candidate: two-node beam topology equivalent to Abaqus B31
• section keyword candidate: beam section constants sufficient for A, J, Iy, Iz, E, and G
• orientation data requirement for constructing local axes
• boundary/load DOFs: 1..6 map to ux, uy, uz, rx, ry, rz
• HDF5 output quantities expected after solver integration: nodal displacement, reaction, element internal force, stress placeholders if stress recovery is later approved
• unsupported input cases and diagnostics

The reference model contract must list required future models without generating artifacts:

• axial cantilever bar-as-beam
• torsion cantilever
• bending cantilever about local y
• bending cantilever about local z
• skew-oriented beam transform check

For each future model, specify expected files under reference/<model-id>/ and which CSV quantities are required. State that Abaqus reference CSVs must not be generated or modified in this phase.

Do not create C++ files in this step.

Tests To Write First

• No C++ test is required in this documentation-only step.

Acceptance Criteria

python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py

Verification Notes

1. Confirm reference artifacts are specified, not created.
2. Confirm unsupported parser or solver paths are explicit open issues.
3. Update phases/euler-beam-3d/index.json step 4:
   • success: "status": "completed", "summary": "3D Euler beam I/O and reference model contracts added"
   • failure after retries: "status": "error", "error_message": "<specific error>"
   • blocked: "status": "blocked", "blocked_reason": "<specific reason>"

Forbidden

• Do not create or modify files under /reference/.
• Do not modify source or tests.