From 4c47b2766a8af4a0057aefde8ca39387b838a3fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EA=B2=BD=EC=A2=85?= Date: Fri, 12 Jun 2026 17:51:35 +0900 Subject: [PATCH] feat(euler-beam-3d): step 0 requirements-baseline --- docs/requirements/euler-beam-3d.md | 201 +++++++++++++++++++++++++++++ phases/euler-beam-3d/index.json | 12 +- 2 files changed, 209 insertions(+), 4 deletions(-) create mode 100644 docs/requirements/euler-beam-3d.md diff --git a/docs/requirements/euler-beam-3d.md b/docs/requirements/euler-beam-3d.md new file mode 100644 index 0000000..804cdfc --- /dev/null +++ b/docs/requirements/euler-beam-3d.md @@ -0,0 +1,201 @@ +# 3D Euler-Bernoulli Beam Kernel Requirements + +## Metadata +- feature_id: euler-beam-3d +- title: Kernel-first 3D Euler-Bernoulli beam element +- status: draft +- owner_agent: requirement-agent +- date: 2026-06-12 + +## Purpose +Define the first implementable requirements baseline for a two-node, straight, prismatic, small-displacement 3D Euler-Bernoulli beam element kernel. This increment is limited to element-level stiffness and end-force recovery so downstream formulation, numerical review, and C++ implementation can proceed without claiming full solver readiness. + +## Assumptions +- The element is a two-node straight beam with nonzero length. +- The element uses small-displacement, small-rotation, linear elastic kinematics. +- Each node has six mechanical DOFs in this order: `ux, uy, uz, rx, ry, rz`. +- The element displacement vector order is node 1 DOFs followed by node 2 DOFs, each in `ux, uy, uz, rx, ry, rz` order. +- Section and material constants are constant over the element: `E`, `G`, `A`, `J`, `Iy`, `Iz`. +- `Iy` and `Iz` are second moments of area about the element local principal bending axes, and `J` is the torsional constant about the local beam axis. +- Units are user-consistent; the kernel does not perform unit conversion in this increment. +- The local element basis is right-handed and orthonormal. The local `x` axis follows node 1 to node 2; the source of local `y` and `z` orientation for parser or solver integration remains open. +- Boundary conditions, global equation numbering, sparse assembly, linear solve, HDF5 writing, and reference comparison are downstream solver concerns, not kernel responsibilities in this increment. + +## In Scope +- Two-node, straight, prismatic 3D Euler-Bernoulli beam element kernel. +- Six mechanical DOFs per node in `ux, uy, uz, rx, ry, rz` order. +- Linear elastic section constants: `E`, `G`, `A`, `J`, `Iy`, `Iz`. +- Local 12x12 stiffness matrix support. +- Global 12x12 stiffness matrix support when a valid local-to-global transformation is supplied. +- Local and global element end-force recovery from compatible 12-entry nodal displacement vectors. +- Kernel-level verification hooks for stiffness symmetry, rigid body modes, and local/global transformation consistency. + +## Out Of Scope +- Shear deformation, Timoshenko beam behavior, shear correction factors, and shear locking treatment. +- Warping DOFs, warping stiffness, restrained warping, or bimoment recovery. +- End releases, offsets, rigid links, eccentric sections, or joint constraints. +- Distributed loads, equivalent nodal load vectors, body forces, or pressure loads. +- Mass matrix, damping matrix, geometric stiffness, buckling, nonlinear kinematics, dynamics, or thermal coupling. +- Abaqus reference CSV generation or modification. +- Full Abaqus compatibility claims. +- Parser integration, end-to-end assembly, solver execution, HDF5 result output, reference comparison, physics sanity, or release readiness. + +## Analysis Definition +- analysis_type: linear static kernel only +- element_type: two-node 3D Euler-Bernoulli beam +- nodes_per_element: 2 +- dofs_per_node: 6 +- dof_order: `ux, uy, uz, rx, ry, rz` +- element_vector_size: 12 +- material_model: linear elastic constants `E` and `G` +- section_model: constant section constants `A`, `J`, `Iy`, `Iz` +- coordinate_system: local Cartesian beam frame and global Cartesian frame +- loads: not in this increment +- boundary_conditions: not in this increment +- official_solver_output: not in this increment + +## Input Requirements +- The kernel must receive or derive two distinct node positions sufficient to determine element length and local `x` direction. +- The kernel must receive positive finite constants for `E`, `G`, `A`, `J`, `Iy`, and `Iz`. +- The kernel must receive a valid right-handed orthonormal local basis or equivalent transformation data before producing a global stiffness matrix or global end-force vector. +- The kernel must receive 12-entry nodal displacement vectors ordered as node 1 then node 2, with each node using `ux, uy, uz, rx, ry, rz`. + +## Output Requirements +- The kernel must produce a local 12x12 stiffness matrix in the documented element DOF order. +- The kernel must produce a global 12x12 stiffness matrix in the documented global DOF order when supplied with a valid local-to-global transformation. +- The kernel must recover local element end forces from a compatible local nodal displacement vector. +- The kernel must recover global element end forces from a compatible global nodal displacement vector when supplied with the same transformation used for the global stiffness matrix. +- This increment must not write `results.h5` and must not create deterministic CSV views or Abaqus reference CSV files. + +## Verification Quantities +| quantity | required_for_kernel | verification intent | downstream owner | +| --- | --- | --- | --- | +| displacement DOFs | yes | Confirm 12-entry vectors use the required `ux, uy, uz, rx, ry, rz` per-node ordering. | Implementation Planning Agent | +| reactions / end forces | yes | Confirm local and global end-force recovery is consistent with the corresponding stiffness matrix and displacement vector. | Formulation Agent; Implementation Planning Agent | +| stiffness symmetry | yes | Confirm local and global 12x12 stiffness matrices are symmetric within the formulation-defined numeric tolerance. | Numerical Review Agent; Implementation Planning Agent | +| rigid body modes | yes | Confirm an unconstrained isolated element has six zero-energy rigid body modes within the formulation-defined numeric tolerance. | Formulation Agent; Numerical Review Agent | +| local/global transformation consistency | yes | Confirm transformed stiffness and force recovery are mutually consistent for the same basis and displacement vector. | Formulation Agent; Implementation Planning Agent | +| stress | no | Stress recovery is not part of this kernel increment. | Future requirements | +| strain | no | Strain recovery is not part of this kernel increment. | Future requirements | +| energy or residual | downstream hook | Strain energy consistency may be added as a kernel verification hook after formulation review. | Numerical Review Agent | + +## Tolerance Policy +- absolute_tolerance: needs-downstream-decision by Numerical Review Agent and Implementation Planning Agent +- relative_tolerance: needs-downstream-decision by Numerical Review Agent and Implementation Planning Agent +- norm_based_tolerance: needs-downstream-decision by Numerical Review Agent and Implementation Planning Agent +- Units: user-consistent structural units; no unit conversion in this increment. +- Coordinate system: local and global Cartesian frames with a right-handed orthonormal element basis. +- Rule: any numerical kernel test added later must state the tolerance source and whether it checks component-wise values, matrix norms, eigenvalue/residual norms, or force vector norms. + +## Reference Artifact Requirements +Reference artifacts are not required for kernel completion in this increment. + +Future end-to-end solver verification may use a bundle under `reference//`, but this requirements baseline does not authorize creating, modifying, or regenerating Abaqus reference CSV files. + +| artifact | kernel increment status | future solver-release status | +| --- | --- | --- | +| `model.inp` | not required | required after parser and assembly scope is approved | +| `metadata.json` | not required | required with provenance for approved reference artifacts | +| `_displacements.csv` | not required | required for reference comparison | +| `_reactions.csv` | not required | required for reaction/end-force comparison | +| `_internalforces.csv` | not required | required when internal force comparison scope is approved | +| `_stresses.csv` | not required | not required until stress recovery is in scope | + +## Must Requirements +| id | requirement | +| --- | --- | +| EB3D-REQ-001 | The beam kernel must model only a two-node, straight, prismatic, small-displacement 3D Euler-Bernoulli beam element in this increment. | +| EB3D-REQ-002 | The beam kernel must use six mechanical DOFs per node ordered as `ux, uy, uz, rx, ry, rz`. | +| EB3D-REQ-003 | The beam kernel must use a 12-entry element vector ordered as all node 1 DOFs followed by all node 2 DOFs. | +| EB3D-REQ-004 | The beam kernel must accept linear elastic constants `E` and `G` and section constants `A`, `J`, `Iy`, and `Iz`. | +| EB3D-REQ-005 | The beam kernel must produce a local 12x12 stiffness matrix in the documented local DOF order. | +| EB3D-REQ-006 | The beam kernel must produce a global 12x12 stiffness matrix when supplied with a valid right-handed orthonormal local-to-global transformation. | +| EB3D-REQ-007 | The beam kernel must recover local element end forces from a compatible local nodal displacement vector. | +| EB3D-REQ-008 | The beam kernel must recover global element end forces from a compatible global nodal displacement vector and the same transformation convention used for global stiffness. | +| EB3D-REQ-009 | The local and global stiffness matrices must be symmetric within the formulation-defined tolerance. | +| EB3D-REQ-010 | The unconstrained isolated element stiffness must preserve six rigid body modes within the formulation-defined tolerance. | +| EB3D-REQ-011 | The local and global stiffness and end-force recovery paths must be mutually consistent under the same transformation. | +| EB3D-REQ-012 | The kernel increment must not include shear deformation, warping, end releases, offsets, distributed loads, mass matrix, geometric stiffness, nonlinear kinematics, dynamics, or thermal coupling. | +| EB3D-REQ-013 | The kernel increment must not create, modify, or regenerate Abaqus reference CSV files. | +| EB3D-REQ-014 | The requirements and downstream implementation must not claim full Abaqus compatibility for this feature. | +| EB3D-REQ-015 | The kernel completion criteria must be separate from full solver release readiness. | + +## Requirement Verification Matrix +| id | source | priority | verification_method | acceptance_criteria | tolerance | downstream_agents | status | +| --- | --- | --- | --- | --- | --- | --- | --- | +| EB3D-REQ-001 | user step scope | must | formulation review; C++ unit tests in later implementation steps | Formulation and implementation address only the scoped Euler-Bernoulli beam kernel and do not add excluded behaviors. | not numeric | Formulation Agent; Implementation Planning Agent | draft | +| EB3D-REQ-002 | user step scope | must | unit test; code review | Tests or implementation checks demonstrate the exact per-node DOF order `ux, uy, uz, rx, ry, rz`. | not numeric | Implementation Planning Agent | draft | +| EB3D-REQ-003 | user step scope | must | unit test; code review | Tests or implementation checks demonstrate the 12-entry node 1 then node 2 vector order. | not numeric | Implementation Planning Agent | draft | +| EB3D-REQ-004 | user step scope | must | input validation test in later implementation steps | Nonpositive or nonfinite constants are rejected or diagnosed according to the downstream implementation contract. | not numeric for this baseline | I/O Definition Agent; Implementation Planning Agent | draft | +| EB3D-REQ-005 | user step scope | must | formulation review; local stiffness unit test | Local stiffness is 12x12, uses the documented local DOF order, and matches formulation-specified benchmark values. | formulation-defined | Formulation Agent; Numerical Review Agent; Implementation Planning Agent | draft | +| EB3D-REQ-006 | user step scope | must | transformation unit test | Global stiffness is 12x12 and matches the formulation-specified transformation of the local matrix. | formulation-defined | Formulation Agent; Implementation Planning Agent | draft | +| EB3D-REQ-007 | user step scope | must | local force recovery unit test | Local end-force output is consistent with the local stiffness matrix and local displacement vector. | formulation-defined | Formulation Agent; Implementation Planning Agent | draft | +| EB3D-REQ-008 | user step scope | must | global force recovery unit test | Global end-force output is consistent with global stiffness, global displacement, and the local/global transformation convention. | formulation-defined | Formulation Agent; Implementation Planning Agent | draft | +| EB3D-REQ-009 | user verification notes | must | matrix symmetry unit test | Local and global stiffness matrices satisfy symmetry checks within the selected matrix tolerance. | needs-downstream-decision | Numerical Review Agent; Implementation Planning Agent | draft | +| EB3D-REQ-010 | user verification notes | must | rigid body mode unit test; numerical review | Six rigid body modes produce zero or tolerance-bounded internal force/energy for an unconstrained isolated element. | needs-downstream-decision | Formulation Agent; Numerical Review Agent | draft | +| EB3D-REQ-011 | user verification notes | must | transformation consistency unit test | Stiffness transformation and end-force transformation use one consistent convention for the same local basis. | formulation-defined | Formulation Agent; Implementation Planning Agent | draft | +| EB3D-REQ-012 | user exclusions | must | scope review; code review | No excluded behavior appears in requirements, formulation, or kernel implementation for this increment. | not numeric | Coordinator Agent; Implementation Planning Agent | draft | +| EB3D-REQ-013 | user forbidden list | must | git diff review | No file under `reference/` and no Abaqus reference CSV is created or modified in this increment. | not numeric | Reference Model Agent; Coordinator Agent | draft | +| EB3D-REQ-014 | ADR-003; user verification notes | must | documentation review; I/O contract review | Documentation states this is a limited feature subset and does not claim full Abaqus compatibility. | not numeric | I/O Definition Agent; Coordinator Agent | draft | +| EB3D-REQ-015 | project acceptance gates | must | release gate review | Kernel completion can be marked separately, while full solver release remains blocked until parser, assembly, HDF5 output, reference comparison, physics sanity, and release readiness gates pass. | not numeric | Release Agent; Coordinator Agent | draft | + +## Acceptance Criteria +### This Documentation Step +- `docs/requirements/euler-beam-3d.md` exists and contains metadata, assumptions, non-goals, must requirements, verification quantities, acceptance criteria, and open issues. +- The document does not create source, test, or reference artifact files. +- The document does not claim full Abaqus compatibility. +- Every `must` requirement has an acceptance criterion or downstream verification hook in the Requirement Verification Matrix. +- The following validation commands pass: + +```powershell +python -m unittest discover -s scripts -p "test_*.py" +python scripts/validate_workspace.py +``` + +### Kernel Completion +Kernel completion may be claimed only after downstream implementation steps provide C++ tests and implementation evidence for: +- local 12x12 stiffness matrix generation; +- global 12x12 stiffness matrix transformation; +- local and global end-force recovery; +- DOF ordering; +- stiffness symmetry; +- six rigid body modes; +- local/global transformation consistency. + +Kernel completion does not require Abaqus reference CSV files, `results.h5`, parser integration, global sparse assembly, or release readiness. + +### Full Solver Release Readiness +Full solver release readiness is not in scope for this increment. It requires later evidence for: +- parser and I/O contract approval for the beam feature; +- Domain, AnalysisModel, DofManager, assembly, constraints, solve, and ResultsWriter integration; +- HDF5 result schema coverage; +- approved reference artifacts under `reference//`; +- FESA `results.h5` to Abaqus reference CSV comparison; +- physics sanity review; +- release readiness review with known limitations. + +## Open Issues +- Parser integration: define the approved Abaqus keyword subset, beam section mapping, orientation input, and unsupported keyword diagnostics before parser work starts. +- Reference artifact availability: no Abaqus reference CSV files are required or generated in this kernel increment; approved reference artifacts are still needed for later solver-level verification. +- Full end-to-end assembly: global sparse assembly, boundary condition application, reaction recovery, solve flow, and HDF5 output are not covered by this kernel baseline. +- Local orientation convention: downstream formulation and I/O contract must define how local `y` and `z` axes are supplied, derived, validated, and reported. +- Tolerance values: downstream numerical review must select tolerances for matrix symmetry, rigid body mode residuals, transformation consistency, and force recovery. + +## Downstream Handoff +### Research Agent +- Confirm authoritative Euler-Bernoulli 3D beam references and benchmark cases for stiffness, transformation, and rigid body checks. + +### Formulation Agent +- Define local stiffness, transformation convention, end-force recovery convention, rigid body mode checks, and edge cases for invalid geometry or constants. + +### Numerical Review Agent +- Review stiffness symmetry, rank/rigid body modes, sign conventions, transformation convention, conditioning risks, and numerical tolerances. + +### I/O Definition Agent +- Define future parser and semantic model mapping for beam geometry, section constants, material constants, and local orientation without claiming full Abaqus compatibility. + +### Reference Model Agent +- Define future reference model bundles only after parser and end-to-end solver scope is approved; do not generate reference CSV files in this increment. + +### Implementation Planning Agent +- Plan C++ tests before production code for local stiffness, global transformation, end-force recovery, DOF order, symmetry, rigid body modes, and invalid inputs. diff --git a/phases/euler-beam-3d/index.json b/phases/euler-beam-3d/index.json index b430e82..ff525fb 100644 --- a/phases/euler-beam-3d/index.json +++ b/phases/euler-beam-3d/index.json @@ -5,10 +5,13 @@ { "step": 0, "name": "requirements-baseline", - "status": "pending", + "status": "completed", + "summary": "3D Euler beam kernel requirements baseline added", "allowed_paths": [ "docs/requirements/euler-beam-3d.md" - ] + ], + "started_at": "2026-06-12T17:44:12+0900", + "completed_at": "2026-06-12T17:50:31+0900" }, { "step": 1, @@ -95,5 +98,6 @@ "docs/releases/euler-beam-3d-release.md" ] } - ] -} + ], + "created_at": "2026-06-12T17:44:12+0900" +} \ No newline at end of file