Step 2: formulation-spec

Read These Files First

Read the following files before editing:

Create /docs/formulations/euler-beam-3d-formulation.md.

The formulation must define the implementation contract for the C++ kernel. Include:

local coordinate system: local x from node 1 to node 2; local y from the user orientation vector projected normal to local x; local z = x cross y
local DOF order: [u1, v1, w1, rx1, ry1, rz1, u2, v2, w2, rx2, ry2, rz2]
section constants: E, G, A, J, Iy, Iz
local 12x12 stiffness matrix terms for:
- axial: EA/L
- torsion: GJ/L
- bending in local x-y using EIz
- bending in local x-z using EIy
transformation matrix convention and global stiffness equation K_global = T^T K_local T
end-force recovery equation f_local = K_local u_local
validation tolerances for unit tests, using deterministic double comparisons
singular and invalid input handling:
- zero or near-zero length throws std::invalid_argument
- nonpositive E, G, A, J, Iy, or Iz throws std::invalid_argument
- orientation vector parallel to beam axis throws std::invalid_argument

Use compact matrices and named scalar coefficients so the implementation step can transcribe directly.

Do not create C++ files in this step.

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

Confirm the matrix is symmetric by construction.
Confirm local/global transformation convention is unambiguous.
Update phases/euler-beam-3d/index.json step 2:
- success: "status": "completed", "summary": "3D Euler beam formulation contract added"
- failure after retries: "status": "error", "error_message": "<specific error>"
- blocked: "status": "blocked", "blocked_reason": "<specific reason>"