baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: complete euler beam planning gates

Browse Source
This commit is contained in:
김경종
2026-06-12 17:58:23 +09:00
parent 4c47b2766a
commit c88de37a83
7 changed files with 735 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/formulations/euler-beam-3d-formulation.md
+210
View File
@@ -0,0 +1,210 @@
# 3D Euler-Bernoulli Beam Kernel Formulation
## Metadata
- feature_id: euler-beam-3d
- source_requirement: docs/requirements/euler-beam-3d.md
- source_research: docs/research/euler-beam-3d-research.md
- status: ready-for-numerical-review
- owner_agent: formulation-agent
- date: 2026-06-12
## Scope and Assumptions
- analysis_type: linear static kernel only.
- element_type: two-node straight prismatic 3D Euler-Bernoulli beam.
- deformation: small displacement and small rotation.
- linearity: linear elastic.
- material_model_boundary: constant `E` and `G`.
- section_model_boundary: constant `A`, `J`, `Iy`, `Iz`.
- coordinate_system: local Cartesian beam basis and global Cartesian basis.
- units: user-consistent.
## Primary Variables and DOFs
- nodal_variables: displacement vector and rotation vector at each node.
- dof_ordering: `[u1, v1, w1, rx1, ry1, rz1, u2, v2, w2, rx2, ry2, rz2]`.
- local_axis_convention:
- local `x` is the normalized vector from node 1 to node 2.
- local `y` is the normalized projection of the user orientation vector onto the plane normal to local `x`.
- local `z = x cross y`.
- sign_convention: internal local end force vector is `f_local = K_local * u_local` in the same DOF order.
## Strong Form and Boundary Conditions
The kernel is an element-level direct-stiffness implementation of the linear Euler-Bernoulli frame equations. For a prismatic member in local coordinate `x`:
- axial equilibrium uses constant axial stiffness `EA`.
- torsional equilibrium uses constant torsional stiffness `GJ`.
- bending in local `x-y` uses flexural rigidity `EIz`.
- bending in local `x-z` uses flexural rigidity `EIy`.
Essential and natural boundary conditions are not applied by this kernel. They are downstream solver assembly concerns.
## Weak or Variational Form
The element stiffness represents the second variation of strain energy:
```text
U = 1/2 integral_0^L [
EA * (du/dx)^2
+ GJ * (drx/dx)^2
+ EIz * (d2v/dx2)^2
+ EIy * (d2w/dx2)^2
] dx
```
The element internal force is the derivative of this energy with respect to the nodal DOFs:
```text
f_local = K_local * u_local
```
External load vectors are out of scope for this increment.
## Discretization
- axial interpolation: linear two-node interpolation for `u`.
- torsion interpolation: linear two-node interpolation for `rx`.
- bending interpolation: cubic Hermite interpolation for each transverse displacement and corresponding nodal rotation.
- nodal_layout: node 1 at local coordinate `x=0`, node 2 at `x=L`.
- partition_of_unity_check: axial and torsion linear shape functions sum to one.
- kronecker_delta_check: axial, torsion, and Hermite bending shape functions recover the nodal displacement/rotation DOFs.
## Kinematics
- axial strain: `epsilon_x = du/dx`.
- torsion rate: `kappa_x = drx/dx`.
- bending curvature for local `x-y` bending: curvature associated with `v` and rotations `rz`.
- bending curvature for local `x-z` bending: curvature associated with `w` and rotations `ry`.
- strain_measure: infinitesimal strain and small rotation curvature measures only.
## Constitutive Contract
- axial force result: `N = EA * du/dx`.
- torsional moment result: `Mx = GJ * drx/dx`.
- bending moment about local `z`: uses `EIz`.
- bending moment about local `y`: uses `EIy`.
- material_state_variables: none.
## Element Equations
Let:
```text
a = E*A/L
t = G*J/L
by = E*Iy
bz = E*Iz
cy1 = 12*by/L^3
cy2 = 6*by/L^2
cy3 = 4*by/L
cy4 = 2*by/L
cz1 = 12*bz/L^3
cz2 = 6*bz/L^2
cz3 = 4*bz/L
cz4 = 2*bz/L
```
`K_local` is a 12x12 symmetric matrix initialized to zero, with these nonzero entries before symmetric mirroring:
```text
K(0,0)= a K(0,6)=-a K(6,6)= a
K(3,3)= t K(3,9)=-t K(9,9)= t
K(1,1)= cz1 K(1,5)= cz2 K(1,7)=-cz1 K(1,11)= cz2
K(5,5)= cz3 K(5,7)=-cz2 K(5,11)= cz4
K(7,7)= cz1 K(7,11)=-cz2 K(11,11)= cz3
K(2,2)= cy1 K(2,4)=-cy2 K(2,8)=-cy1 K(2,10)=-cy2
K(4,4)= cy3 K(4,8)= cy2 K(4,10)= cy4
K(8,8)= cy1 K(8,10)= cy2 K(10,10)= cy3
```
The implementation must mirror upper-triangular entries to the lower triangle.
## Mapping and Numerical Integration
- reference_coordinates: local beam coordinate `x in [0,L]`.
- isoparametric_mapping: straight member mapping only.
- jacobian: `dx/dxi = L/2` if a parent coordinate is introduced; the direct closed-form stiffness does not require runtime quadrature.
- determinant_checks: `L > 0` and finite.
- gauss_points_and_weights: not used by the closed-form kernel.
- integration_policy: analytical closed-form.
## Transformation
Let `R` be the 3x3 matrix whose rows are local basis vectors expressed in global coordinates:
```text
R = [ x_local^T
y_local^T
z_local^T ]
```
For each node, the same `R` maps global translational and rotational components to local components. The 12x12 transform `T` is block diagonal:
```text
u_local = T * u_global
K_global = T^T * K_local * T
```
Global end-force recovery uses the same convention:
```text
u_local = T * u_global
f_local = K_local * u_local
f_global = T^T * f_local
```
## Output Recovery
- displacement: input only for this kernel.
- reaction: not recovered by this kernel; downstream assembly/constraints own reactions.
- element_force: local and global element end forces recover from stiffness times displacement.
- strain: out of scope.
- stress: out of scope.
- nodal_extrapolation: not applicable.
## Invalid Input Handling
- `length <= 0`, nonfinite length, or near-zero geometry length must throw `std::invalid_argument`.
- nonpositive or nonfinite `E`, `G`, `A`, `J`, `Iy`, or `Iz` must throw `std::invalid_argument`.
- zero orientation vector or orientation parallel to local `x` must throw `std::invalid_argument`.
## Unit Test Tolerance
- representative coefficient checks: absolute tolerance `1.0e-10` for the planned deterministic values.
- symmetry checks: absolute tolerance `1.0e-10`.
- rigid mode force norm checks: absolute tolerance `1.0e-9` for simple test magnitudes.
## Algorithm Pseudocode
```text
validate length and section constants
compute named stiffness coefficients
initialize 12x12 local matrix to zero
fill upper triangular axial, torsion, and bending terms
mirror upper triangular terms
for global operations:
compute normalized local x from node2 - node1
project orientation onto plane normal to local x and normalize as local y
compute local z = x cross y
build block diagonal T from R
compute K_global = T^T * K_local * T
recover forces with u_local = T*u_global, f_local = K_local*u_local, f_global = T^T*f_local
```
## Numerical Risks
- rigid_body_modes: the unconstrained local/global stiffness should produce near-zero force for six rigid body modes; tests should include at least rigid translation in this increment.
- patch_test: future solver-level patch tests require parser/assembly integration.
- symmetry: local and global matrices must remain symmetric.
- positive_definiteness: constrained systems may become positive definite; the isolated element is positive semidefinite.
- hourglass: not applicable to this closed-form beam kernel.
- shear_locking: excluded by Euler-Bernoulli assumptions and no shear deformation terms.
- volumetric_locking: not applicable.
- distortion: curved or offset geometry is out of scope.
- singular_jacobian: represented by zero or near-zero length.
## Open Issues and Downstream Handoff
### Numerical Review Agent
- Confirm signs for the local `w` and `ry` bending block.
- Confirm the transformation convention and invalid orientation handling are implementation-ready.
### I/O Definition Agent
- Define future orientation input mapping and unsupported cases without claiming parser support in this kernel increment.
### Reference Model Agent
- Define future axial, torsion, bending, and skew-oriented reference models without generating artifacts.
### Implementation Planning Agent
- Transcribe the matrix entries and transformation convention into C++ tests before production implementation.
docs/implementation-plans/euler-beam-3d-implementation-plan.md
+127
View File
@@ -0,0 +1,127 @@
# 3D Euler-Bernoulli Beam Kernel Implementation Plan
## Metadata
- feature_id: euler-beam-3d
- source_requirement: docs/requirements/euler-beam-3d.md
- source_research: docs/research/euler-beam-3d-research.md
- source_formulation: docs/formulations/euler-beam-3d-formulation.md
- source_numerical_review: docs/numerical-reviews/euler-beam-3d-review.md
- source_io_definition: docs/io-definitions/euler-beam-3d-io.md
- source_reference_models: docs/reference-models/euler-beam-3d-reference-models.md
- status: ready-for-implementation
- owner_agent: implementation-planning-agent
- date: 2026-06-12
## Readiness Check
| input | required_status | observed_status | decision |
| --- | --- | --- | --- |
| requirement | sufficient draft | draft, kernel scope explicit | proceed |
| research | ready-for-formulation | ready-for-formulation | proceed |
| formulation | ready-for-numerical-review | ready-for-numerical-review | proceed |
| numerical_review | pass-for-implementation-planning | pass-for-implementation-planning | proceed |
| io_definition | ready-for-implementation-planning or explicit future scope | ready-for-implementation-planning | proceed |
| reference_models | planned artifacts or future gate | needs-reference-artifacts | proceed for kernel only |
## Implementation Scope
- included_behavior:
- semantic `beam2` model topology.
- local 12x12 stiffness for a two-node 3D Euler-Bernoulli beam.
- local end-force recovery as `K_local * u_local`.
- local/global basis construction, global stiffness transform, and global end-force recovery.
- excluded_behavior:
- parser integration, assembly, solver integration, HDF5 output, reference CSV generation, reference comparison, stress recovery, distributed loads, mass, geometric stiffness, releases, offsets, warping, shear deformation, nonlinear and dynamic behavior.
- non_goals:
- no external linear algebra dependency.
- no CMake edits unless the existing source/test globs fail to pick up new files.
## Work Breakdown
| task_id | order | purpose | upstream_trace | depends_on | expected_test_first |
| --- | --- | --- | --- | --- | --- |
| EB3D-TASK-001 | 1 | Add `ElementTopology::beam2` semantic topology. | EB3D-REQ-001, EB3D-REQ-002 | none | EB3D-TEST-001 |
| EB3D-TASK-002 | 2 | Add local stiffness and local end-force kernel. | EB3D-REQ-004, EB3D-REQ-005, EB3D-REQ-007, EB3D-REQ-009 | EB3D-TASK-001 | EB3D-TEST-002 |
| EB3D-TASK-003 | 3 | Add global transform and global end-force recovery. | EB3D-REQ-006, EB3D-REQ-008, EB3D-REQ-010, EB3D-REQ-011 | EB3D-TASK-002 | EB3D-TEST-003 |
| EB3D-TASK-004 | 4 | Record build/test evidence. | project validation policy | EB3D-TASK-003 | N/A |
| EB3D-TASK-005 | 5 | Record release-readiness note with limitations. | EB3D-REQ-012 through EB3D-REQ-015 | EB3D-TASK-004 | N/A |
## TDD Test Plan
| test_id | order | test_type | red_condition | green_condition | linked_task | command |
| --- | --- | --- | --- | --- | --- | --- |
| EB3D-TEST-001 | 1 | unit | compile fails because `ElementTopology::beam2` is missing | model element test passes with `beam2` and existing topologies preserved | EB3D-TASK-001 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model_element_test` |
| EB3D-TEST-002 | 2 | unit | compile fails because `euler_beam_3d.hpp` API is missing | local stiffness entries, symmetry, `K*u`, and invalid inputs pass | EB3D-TASK-002 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_local_stiffness_test` |
| EB3D-TEST-003 | 3 | unit | compile fails because global transform API is missing | identity transform, rotated symmetry, rigid translation, axial force, and invalid orientation pass | EB3D-TASK-003 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_transform_recovery_test` |
## CMake/CTest Plan
- target_candidates: existing FESA library target and unit-test executable pattern.
- add_test_needs: only if existing test globs do not register new tests.
- labels: unit.
- msvc_config: Debug.
- expected_feature_commands:
- `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model_element_test`
- `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_local_stiffness_test`
- `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_transform_recovery_test`
- workspace_validation: `python scripts/validate_workspace.py`.
## Candidate Files and Ownership
| file_candidate | purpose | owner_boundary | notes |
| --- | --- | --- | --- |
| `src/fesa/model/element.hpp` | add semantic topology enum value | model semantic layer | No equation IDs or section constants. |
| `src/fesa/model/element.cpp` | only if topology string/conversion exists | model semantic layer | Preserve existing behavior. |
| `tests/unit/model_element_test.cpp` | topology unit test | test-first for model change | Must be edited before production enum change. |
| `src/fesa/elements/euler_beam_3d.hpp` | kernel declarations and small value types | element kernel layer | C++17 standard library only. |
| `src/fesa/elements/euler_beam_3d.cpp` | local/global stiffness and recovery implementation | element kernel layer | No parser, assembly, or HDF5 code. |
| `tests/unit/euler_beam_3d_local_stiffness_test.cpp` | local kernel tests | test-first for local kernel | Covers representative entries and invalid inputs. |
| `tests/unit/euler_beam_3d_transform_recovery_test.cpp` | transform/recovery tests | test-first for global transform | Covers identity, rotation, rigid translation, axial force, invalid orientation. |
## Acceptance Traceability Matrix
| requirement_id | task_id | test_id | reference_model_id | acceptance_criterion | status |
| --- | --- | --- | --- | --- | --- |
| EB3D-REQ-001 | EB3D-TASK-001 | EB3D-TEST-001 | N/A | semantic topology exists for two-node beam | planned |
| EB3D-REQ-002 | EB3D-TASK-002 | EB3D-TEST-002 | N/A | local DOF order matches formulation entries | planned |
| EB3D-REQ-004 | EB3D-TASK-002 | EB3D-TEST-002 | N/A | section constants are used and invalid constants rejected | planned |
| EB3D-REQ-005 | EB3D-TASK-002 | EB3D-TEST-002 | N/A | local 12x12 stiffness entries match formulation | planned |
| EB3D-REQ-006 | EB3D-TASK-003 | EB3D-TEST-003 | `eb3d-skew-transform` future | global stiffness uses documented transform | planned |
| EB3D-REQ-007 | EB3D-TASK-002 | EB3D-TEST-002 | N/A | local end forces equal `K*u` | planned |
| EB3D-REQ-008 | EB3D-TASK-003 | EB3D-TEST-003 | `eb3d-skew-transform` future | global end forces use consistent transform | planned |
| EB3D-REQ-009 | EB3D-TASK-002/003 | EB3D-TEST-002/003 | N/A | local and global stiffness matrices are symmetric | planned |
| EB3D-REQ-010 | EB3D-TASK-003 | EB3D-TEST-003 | N/A | rigid global translation has near-zero end forces | planned |
| EB3D-REQ-011 | EB3D-TASK-003 | EB3D-TEST-003 | `eb3d-skew-transform` future | transform and recovery conventions are consistent | planned |
| EB3D-REQ-012 | EB3D-TASK-002/003 | EB3D-TEST-002/003 | N/A | excluded behaviors are not implemented | planned |
| EB3D-REQ-013 | EB3D-TASK-004 | N/A | all future models | no `reference/` artifacts are modified | planned |
| EB3D-REQ-014 | EB3D-TASK-005 | N/A | N/A | no full Abaqus compatibility claim | planned |
| EB3D-REQ-015 | EB3D-TASK-005 | N/A | N/A | kernel completion remains separate from full solver release | planned |
## Validation Commands
```powershell
ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model_element_test
ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_local_stiffness_test
ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_transform_recovery_test
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
```
## Risks and Downstream Handoff
### Implementation Agent
- Follow `RED -> GREEN -> VERIFY` for each production change.
- Keep matrix storage row-major with index `row * 12 + col`.
- Throw `std::invalid_argument` for invalid length, section constants, and orientation.
### Build/Test Executor Agent
- Record CTest and workspace validation evidence after the C++ steps.
### Correction Agent
- Compile failures are likely missing CMake glob registration or signature mismatch.
- Test failures are likely sign convention, transform convention, or tolerance mistakes.
### Reference Verification Agent
- No reference comparison is expected until future HDF5 and reference artifact work is approved.
## Open Issues
- Exact parser keyword subset and HDF5 schema are future integration work.
- Reference artifacts remain unavailable by design in this kernel phase.
docs/io-definitions/euler-beam-3d-io.md
+94
View File
@@ -0,0 +1,94 @@
# 3D Euler-Bernoulli Beam I/O Definition
## Metadata
- feature_id: euler-beam-3d
- source_requirement: docs/requirements/euler-beam-3d.md
- source_formulation: docs/formulations/euler-beam-3d-formulation.md
- source_numerical_review: docs/numerical-reviews/euler-beam-3d-review.md
- source_research: docs/research/euler-beam-3d-research.md
- status: ready-for-implementation-planning
- owner_agent: io-definition-agent
- date: 2026-06-12
## Abaqus Input Scope
- input_format: Abaqus input file (`.inp`) in a future parser integration phase.
- compatibility_disclaimer: FESA will support only the keyword subset defined for this feature; full Abaqus compatibility is not claimed.
- kernel_increment_status: no parser, HDF5 writer, or reference comparison implementation is included in the current kernel phase.
| keyword | support_status | level | required_parameters | mapped_internal_concept | notes |
| --- | --- | --- | --- | --- | --- |
| `*NODE` | future-supported | model | none | node id and global coordinates | Required for future beam geometry. |
| `*ELEMENT` | future-supported | model | `TYPE` | two-node beam topology | Candidate Abaqus-equivalent type: `B31`; exact subset remains future parser work. |
| `*MATERIAL` | future-supported | model | `NAME` | material identity | Required before solver integration. |
| `*ELASTIC` | future-supported | model | none | `E`, Poisson ratio or `E,G` derivation policy | Future contract must define `G` source. |
| beam section keyword | future-supported | model | section assignment | `A`, `J`, `Iy`, `Iz` | Exact Abaqus keyword subset is not implemented in this kernel phase. |
| orientation data | future-supported | model | orientation vector | local axis construction | Must define nonparallel orientation vector. |
| `*BOUNDARY` | future-supported | history | DOF range | constrained DOFs | DOF numbers `1..6` map to `ux,uy,uz,rx,ry,rz`. |
| `*CLOAD` | future-supported | history | node, DOF, magnitude | concentrated load | Distributed loads are out of this kernel increment. |
| `*STEP` / procedure | future-supported | history | procedure data | linear static step | Solver integration gate. |
| output keywords | future-supported | history | output variables | HDF5 field/history requests | Authoritative output remains `results.h5`. |
## Syntax Policy
- case_insensitivity: future parser should treat Abaqus keyword names case-insensitively.
- comma_separated_fields: future parser should follow the existing parser subset policy when this feature is integrated.
- comment_lines: lines beginning with `**`.
- unsupported_keywords: unsupported with a clear diagnostic unless a future I/O contract explicitly marks them ignored-with-warning.
- ascii_assumption: input text policy follows the parser project contract.
## Model Data Mapping
- nodes: node label and three global Cartesian coordinates.
- elements: two node labels and semantic topology `beam2`.
- material: linear elastic constants sufficient to obtain `E` and `G`.
- section: constants `A`, `J`, `Iy`, `Iz` assigned to the beam element set.
- coordinates: global Cartesian coordinates plus a local orientation vector.
- units: user-consistent and recorded in future metadata.
## History Data Mapping
- boundary_conditions: Abaqus DOF numbers map as `1=ux`, `2=uy`, `3=uz`, `4=rx`, `5=ry`, `6=rz`.
- loads: future `*CLOAD` concentrated nodal loads may use the same DOF numbering.
- output_requests: future nodal displacement, reaction, and element internal force requests must map to HDF5 datasets.
## Internal Model Contract
- element_type: two-node 3D Euler-Bernoulli beam semantic model, not an Abaqus compatibility claim.
- connectivity: exactly two distinct nodes.
- orientation: nonzero vector not parallel to the beam axis.
- section_constants: positive finite `A`, `J`, `Iy`, `Iz`.
- material_constants: positive finite `E` and `G`.
- unsupported_cases: shear deformation, warping, releases, offsets, distributed loads, mass, geometric stiffness, nonlinear kinematics, dynamics, and thermal coupling.
## Output HDF5 Schema
This kernel phase does not write HDF5. Future solver integration should extend authoritative `results.h5` output with:
| quantity | dataset_path | shape | dtype | required_attributes | location | notes |
| --- | --- | --- | --- | --- | --- | --- |
| displacement | `/steps/<step>/frames/<frame>/nodal/displacement` | `<nnode, 6>` | float64 | component names, units, coordinate system | nodal | Components `ux,uy,uz,rx,ry,rz`. |
| reaction | `/steps/<step>/frames/<frame>/nodal/reaction` | `<nnode, 6>` | float64 | component names, units, coordinate system | nodal | Requires constraints/assembly. |
| internal force | `/steps/<step>/frames/<frame>/element/internal_force` | `<nelem, 12>` | float64 | component names, units, coordinate system, element ids | element end | Components match beam local/global recovery contract. |
| stress | `/steps/<step>/frames/<frame>/element/stress` | TBD | float64 | component names, units, location | TBD | Placeholder only; stress recovery is not approved in this kernel increment. |
## FESA HDF5 to Reference CSV Comparison Schema
Future reference comparison must read FESA HDF5 rows and compare them to Abaqus-generated CSV files under `reference/<model-id>/`.
Required future CSV mappings:
- `<model-id>_displacements.csv`: step, frame, node id, `ux`, `uy`, `uz`, and future rotational components if approved for comparison.
- `<model-id>_reactions.csv`: step, frame, node id, force and moment reaction components.
- `<model-id>_internalforces.csv`: step, frame, element id, end location, component, value.
- `<model-id>_stresses.csv`: not required until stress recovery is approved.
## Validation Rules
- Reject elements whose connectivity does not contain exactly two distinct nodes.
- Reject missing or nonpositive `E`, `G`, `A`, `J`, `Iy`, or `Iz`.
- Reject missing, zero, or parallel orientation vectors when global transform construction is required.
- Reject unsupported beam keywords with a clear diagnostic in future parser work.
- Do not generate or modify Abaqus reference CSV files in this kernel phase.
## Open Issues and Downstream Handoff
### Reference Model Agent
- Future `model.inp` files must stay within the subset documented here or record open parser issues.
### Implementation Planning Agent
- Current implementation may add only kernel-level C++ tests and source files. Parser/HDF5 work remains out of scope.
### Reference Verification Agent
- Use HDF5 as authoritative FESA output when future reference comparison is implemented.
docs/numerical-reviews/euler-beam-3d-review.md
+76
View File
@@ -0,0 +1,76 @@
# 3D Euler-Bernoulli Beam Kernel Numerical Review
## Metadata
- feature_id: euler-beam-3d
- source_formulation: docs/formulations/euler-beam-3d-formulation.md
- status: pass-for-implementation-planning
- owner_agent: numerical-review-agent
- date: 2026-06-12
## Review Verdict
- verdict: pass-for-implementation-planning
- reason: the formulation has a bounded kernel scope, explicit DOF order, closed-form local stiffness, unambiguous transform convention, and concrete invalid-input behavior.
## Critical Findings
- No blocking numerical defects were found for kernel implementation planning.
- The formulation is not a full solver release contract. Parser, assembly, HDF5 output, reference comparison, and physics sanity remain downstream gates.
## Numerical Risk Assessment
- rigid_body_modes: expected six zero-energy modes for the unconstrained element. Implementation tests must include at least rigid global translation and local/global force consistency.
- patch_test: solver-level patch testing is blocked until assembly and parser integration exist.
- symmetry: local stiffness is symmetric by construction; global stiffness remains symmetric if `K_global = T^T K_local T` is used consistently.
- positive_definiteness: isolated element stiffness is positive semidefinite, not positive definite. Positive definiteness requires enough constraints in a solver model.
- hourglass: not applicable to closed-form Euler-Bernoulli beam stiffness.
- shear_locking: Timoshenko shear terms are excluded, so shear locking is not introduced by this kernel increment.
- volumetric_locking: not applicable.
- distortion: curved geometry and offsets are out of scope; zero or near-zero length must be rejected.
- singular_jacobian: zero length is the relevant singular mapping case.
- conditioning: very slender elements or large stiffness ratios can be ill-conditioned; tests should use moderate deterministic values.
- convergence: not applicable to this linear element kernel.
## Consistency Checks
- units: pass. `EA/L`, `GJ/L`, `EI/L^3`, `EI/L^2`, and `EI/L` have the expected force/displacement or moment/rotation dimensions for the matching DOF pairs.
- dimensions: pass. The element vector is 12x1 and stiffness is 12x12.
- signs: pass for the documented DOF order; local `v-rz` and `w-ry` coupling signs are explicitly stated.
- dof_ordering: pass. The formulation keeps node 1 DOFs followed by node 2 DOFs.
- coordinate_transforms: pass. `u_local = T*u_global`, `K_global = T^T*K_local*T`, and `f_global = T^T*f_local` are mutually consistent.
- matrix_vector_dimensions: pass.
- integration_weights: not applicable because the kernel uses closed-form stiffness.
- output_locations: pass for element end forces only; stress/strain recovery is explicitly out of scope.
## Verification Readiness
- unit_tests:
- model topology accepts `ElementTopology::beam2`.
- local stiffness representative entries match named coefficients.
- local stiffness is symmetric within `1.0e-10`.
- local force recovery equals `K*u`.
- invalid length and nonpositive section constants throw `std::invalid_argument`.
- axis-aligned transform produces global stiffness equal to local stiffness.
- rotated global stiffness remains symmetric.
- rigid global translation produces near-zero global end forces.
- simple axial extension produces equal and opposite axial end forces.
- parallel orientation vector throws `std::invalid_argument`.
- patch_tests: future solver integration gate.
- mms_or_mes: not required for this closed-form kernel increment.
- benchmark_reference_comparison: future gate after reference artifacts exist.
- missing_evidence: no missing evidence blocks kernel implementation.
## Required Revisions
### Formulation Agent
- None before implementation planning.
### Research Agent
- None before implementation planning.
### Reference Model Agent
- Future reference model artifacts remain required before release readiness, but they are not required for this kernel implementation.
## Downstream Handoff
### Implementation Planning Agent
- Use the verification readiness list as the minimum C++ TDD checklist.
- Keep tests deterministic and avoid ill-conditioned constants.
### Reference Model Agent
- Define future solution-verification models separately from these kernel-only unit tests.
docs/reference-models/euler-beam-3d-reference-models.md
+136
View File
@@ -0,0 +1,136 @@
# 3D Euler-Bernoulli Beam Reference Models
## Metadata
- feature_id: euler-beam-3d
- source_requirement: docs/requirements/euler-beam-3d.md
- source_research: docs/research/euler-beam-3d-research.md
- source_formulation: docs/formulations/euler-beam-3d-formulation.md
- source_numerical_review: docs/numerical-reviews/euler-beam-3d-review.md
- source_io_definition: docs/io-definitions/euler-beam-3d-io.md
- status: needs-reference-artifacts
- owner_agent: reference-model-agent
- date: 2026-06-12
## Reference Strategy
- verification_scope: future solver-level verification after parser, assembly, solve, HDF5 output, and comparison tooling exist.
- code_verification: current kernel unit tests cover local stiffness, transformation, and force recovery without external reference artifacts.
- solution_verification: future cantilever and skew-orientation models will compare displacement, reaction, and internal force quantities.
- benchmark_reference_comparison: future Abaqus-generated CSV files under `reference/<model-id>/` are required before release readiness.
- excluded_validation_scope: physical experiment validation is not in scope.
## Model Inventory
| model_id | category | purpose | status | required_artifacts |
| --- | --- | --- | --- | --- |
| `eb3d-axial-cantilever` | analytical | axial bar-as-beam displacement, reaction, and axial end force | needs-reference-artifacts | `model.inp`, `metadata.json`, displacement, reaction, internal force CSV, README |
| `eb3d-torsion-cantilever` | analytical | torsional rotation, reaction moment, and torsional end moment | needs-reference-artifacts | `model.inp`, `metadata.json`, displacement/rotation, reaction, internal force CSV, README |
| `eb3d-bend-y-cantilever` | analytical | bending response using `EIy` | needs-reference-artifacts | `model.inp`, `metadata.json`, displacement, reaction, internal force CSV, README |
| `eb3d-bend-z-cantilever` | analytical | bending response using `EIz` | needs-reference-artifacts | `model.inp`, `metadata.json`, displacement, reaction, internal force CSV, README |
| `eb3d-skew-transform` | regression | skew-oriented beam transform and component mapping | needs-reference-artifacts | `model.inp`, `metadata.json`, displacement, reaction, internal force CSV, README |
## Model Records
### `eb3d-axial-cantilever`
- category: analytical.
- verified_requirements: EB3D-REQ-005, EB3D-REQ-007, future solver I/O requirements.
- analysis_type: linear static.
- element_type: two-node 3D Euler-Bernoulli beam, Abaqus-equivalent candidate `B31`.
- expected_physical_quantities: axial displacement, support reaction, element axial end force.
- artifact_status: needs-reference-artifacts.
### `eb3d-torsion-cantilever`
- category: analytical.
- verified_requirements: EB3D-REQ-005, EB3D-REQ-007.
- analysis_type: linear static.
- expected_physical_quantities: twist, reaction moment about beam axis, torsional end moment.
- artifact_status: needs-reference-artifacts.
### `eb3d-bend-y-cantilever`
- category: analytical.
- verified_requirements: EB3D-REQ-005, EB3D-REQ-007.
- analysis_type: linear static.
- expected_physical_quantities: transverse displacement, support reaction, bending end forces using `EIy`.
- artifact_status: needs-reference-artifacts.
### `eb3d-bend-z-cantilever`
- category: analytical.
- verified_requirements: EB3D-REQ-005, EB3D-REQ-007.
- analysis_type: linear static.
- expected_physical_quantities: transverse displacement, support reaction, bending end forces using `EIz`.
- artifact_status: needs-reference-artifacts.
### `eb3d-skew-transform`
- category: regression.
- verified_requirements: EB3D-REQ-006, EB3D-REQ-008, EB3D-REQ-011.
- analysis_type: linear static.
- expected_physical_quantities: transformed displacement, reaction, and internal force components.
- artifact_status: needs-reference-artifacts.
## Abaqus Input Requirements
- input_file: `reference/<model-id>/model.inp`.
- supported_keyword_subset: must follow docs/io-definitions/euler-beam-3d-io.md when future parser work is approved.
- model_data: nodes, one or more beam elements, material, section, orientation, and units.
- history_data: linear static step, boundary conditions, concentrated loads or moments, and output requests.
- unsupported_keyword_policy: unsupported unless explicitly added by a future I/O contract.
## Artifact Bundle Contract
```text
reference/
<model-id>/
model.inp
metadata.json
<model-id>_displacements.csv
<model-id>_reactions.csv
<model-id>_internalforces.csv
README.md
```
`<model-id>_stresses.csv` is not required until stress recovery is approved. No artifact in this bundle is created or modified in the current phase.
## Metadata JSON Contract
Future `metadata.json` files must include:
- `feature_id`
- `model_id`
- `artifact_status`
- `input_file`
- Abaqus version/source and generation owner
- generation date
- source documents
- units and coordinate system
- analysis type and element types
- material and section values
- boundary and load summaries
- output requests
- reference CSV schema version
- reference CSV files
- tolerance policy
- limitations
## Coverage Matrix
| requirement_id | model_id | compared_quantity | fesa_hdf5_dataset | reference_csv | tolerance | verification_method | status |
| --- | --- | --- | --- | --- | --- | --- | --- |
| EB3D-REQ-005 | `eb3d-axial-cantilever` | displacement/internal force | `/steps/<step>/frames/<frame>/nodal/displacement`, `/element/internal_force` | displacement/internal force CSV | TBD | hdf5-to-reference-csv | needs-reference-artifacts |
| EB3D-REQ-006 | `eb3d-skew-transform` | displacement/reaction/internal force | displacement, reaction, internal force HDF5 datasets | displacement/reaction/internal force CSV | TBD | hdf5-to-reference-csv | needs-reference-artifacts |
| EB3D-REQ-007 | `eb3d-torsion-cantilever` | rotation/reaction/internal force | displacement, reaction, internal force HDF5 datasets | displacement/reaction/internal force CSV | TBD | hdf5-to-reference-csv | needs-reference-artifacts |
| EB3D-REQ-008 | `eb3d-skew-transform` | global end force | `/steps/<step>/frames/<frame>/element/internal_force` | internal force CSV | TBD | hdf5-to-reference-csv | needs-reference-artifacts |
| EB3D-REQ-011 | `eb3d-skew-transform` | transform consistency | displacement and internal force datasets | displacement/internal force CSV | TBD | hdf5-to-reference-csv | needs-reference-artifacts |
## Artifact Acceptance Checklist
- No files under `reference/` are created or modified in this phase.
- Every future model must document provenance before use as verification evidence.
- Required CSV files keep the model status at `needs-reference-artifacts` until generated through an approved reference phase.
- Stress CSV files remain out of scope until stress recovery is approved.
## Open Issues and Downstream Handoff
### I/O Definition Agent
- Finalize the exact beam section and orientation keyword subset before creating `model.inp` files.
### Implementation Planning Agent
- Kernel TDD may proceed without reference artifacts because this phase only implements element-level matrix and recovery routines.
### Reference Verification Agent
- Do not compare results until authoritative HDF5 output and approved CSV artifacts exist.
docs/research/euler-beam-3d-research.md
+81
View File
@@ -0,0 +1,81 @@
# 3D Euler-Bernoulli Beam Kernel Research Brief
## Metadata
- feature_id: euler-beam-3d
- source_requirement: docs/requirements/euler-beam-3d.md
- status: ready-for-formulation
- owner_agent: research-agent
- date: 2026-06-12
## Research Questions
- What theory is sufficient for a straight, prismatic, two-node 3D Euler-Bernoulli beam kernel?
- Which terms must appear in the local stiffness matrix for axial, torsion, and two uncoupled bending planes?
- Which implementation checks can verify the kernel without running Abaqus or creating reference CSV artifacts?
- Which input cases must be rejected before matrix construction?
## Source Inventory
| source_type | title | author_or_org | URL_or_identifier | access_date | reliability_tier | notes |
| --- | --- | --- | --- | --- | --- | --- |
| textbook | Concepts and Applications of Finite Element Analysis | Cook, Malkus, Plesha, Witt | ISBN 978-0-471-35605-9 | 2026-06-12 | Tier 2 | Beam element stiffness and coordinate transformation background. |
| textbook | A First Course in the Finite Element Method | Daryl L. Logan | ISBN 978-1-305-63511-1 | 2026-06-12 | Tier 2 | Direct-stiffness beam and frame examples. |
| textbook | Matrix Structural Analysis | William McGuire, Richard H. Gallagher, Ronald D. Ziemian | ISBN 978-0-471-12379-7 | 2026-06-12 | Tier 2 | Space-frame element local stiffness and transformation conventions. |
| project requirement | 3D Euler-Bernoulli Beam Kernel Requirements | FESA | docs/requirements/euler-beam-3d.md | 2026-06-12 | Tier 1 project contract | Defines approved kernel scope and exclusions. |
## Extracted Facts
- Verified fact: a 3D straight prismatic Euler-Bernoulli beam frame element can be assembled from one axial response, one torsional response, and two uncoupled cubic-Hermite bending responses in the element local frame.
- Verified fact: for a local element axis `x`, bending displacement in local `y` couples with rotation about local `z` and uses `EIz`; bending displacement in local `z` couples with rotation about local `y` and uses `EIy`.
- Verified fact: a two-node space-frame element with six DOFs per node has a 12-entry vector. The FESA requirement fixes per-node order as `ux, uy, uz, rx, ry, rz`.
- Verified fact: the unconstrained element local stiffness is symmetric positive semidefinite and has six rigid body modes before constraints are applied.
- Project contract: no shear deformation, warping, end releases, offsets, mass, geometric stiffness, nonlinear kinematics, parser integration, HDF5 output, or reference artifact generation is allowed in this kernel increment.
## Candidate Benchmarks
| benchmark_id | source | benchmark_type | physics | target_quantities | artifact_needs | applicability |
| --- | --- | --- | --- | --- | --- | --- |
| EB3D-BENCH-001 | project/formulation | code verification | local matrix algebra | symmetry of all `K(i,j)` | C++ unit test only | Does not verify solver assembly. |
| EB3D-BENCH-002 | direct stiffness theory | analytical | axial extension | `EA/L` terms and equal/opposite axial end forces | C++ unit test only | Axis-aligned local response. |
| EB3D-BENCH-003 | direct stiffness theory | analytical | torsion | `GJ/L` terms and equal/opposite torsional end moments | C++ unit test only | Saint-Venant torsion constant assumed supplied. |
| EB3D-BENCH-004 | beam theory | analytical | bending in local `x-y` | `12EIz/L^3`, `6EIz/L^2`, `4EIz/L`, `2EIz/L` terms | C++ unit test only | Euler-Bernoulli small-displacement bending. |
| EB3D-BENCH-005 | beam theory | analytical | bending in local `x-z` | `12EIy/L^3`, `6EIy/L^2`, `4EIy/L`, `2EIy/L` terms | C++ unit test only | Euler-Bernoulli small-displacement bending. |
| EB3D-BENCH-006 | matrix structural analysis | invariant | rigid body motion | local end forces are near zero for rigid translations/rotations | C++ unit test only | Numerical tolerance needed. |
| EB3D-BENCH-007 | matrix structural analysis | invariant | coordinate transform | axis-aligned global stiffness equals local stiffness when basis is identity | C++ unit test only | Does not validate parser orientation input. |
## Verification Relevance
- code_verification: local stiffness entries, symmetry, end-force recovery as `K*u`, invalid input handling, and transformation invariants can be checked by deterministic C++ unit tests.
- solution_verification: future cantilever axial, torsion, and bending reference models can compare displacements, reactions, and internal forces after parser/assembly/HDF5 integration exists.
- validation: no physical experiment validation is in scope for this kernel increment.
- reference_comparison: future reference comparison requires Abaqus-generated artifacts under `reference/<model-id>/`; this phase only defines the contract and must not create those files.
## Applicability Limits
- linear_or_nonlinear: linear only.
- deformation: small displacement and small rotation.
- element_type: straight two-node prismatic Euler-Bernoulli beam.
- material_model: constant linear elastic `E` and `G`.
- geometry: nonzero length, no offsets, no curved beams.
- boundary_conditions: not applied inside the kernel.
- loads: no distributed or equivalent nodal load vector in this increment.
- coordinate_system: right-handed local Cartesian basis and global Cartesian basis.
- units: user-consistent; no conversion.
## Risks and Open Issues
- Orientation vector parallel or nearly parallel to the beam axis must be rejected because the local `y` direction is undefined.
- Zero or near-zero length must be rejected before stiffness coefficient computation.
- Nonpositive or nonfinite `E`, `G`, `A`, `J`, `Iy`, or `Iz` must be rejected.
- Very slender beams can produce ill-conditioned local stiffness matrices; kernel tests should avoid relying on a condition-number estimate as a pass/fail criterion.
- Exact parser keyword mapping for future beam input remains open and belongs to the I/O contract, not the kernel implementation.
## Downstream Handoff
### Formulation Agent
- Define the local stiffness matrix with named axial, torsion, `EIz`, and `EIy` coefficients.
- Define the local-to-global transform convention so global stiffness and force recovery are unambiguous.
### Numerical Review Agent
- Review symmetry, rigid body modes, sign convention, coefficient dimensions, and invalid geometry handling.
### Reference Model Agent
- Future reference models should include axial cantilever, torsion cantilever, two bending cantilevers, and one skew transform case.
### Implementation Planning Agent
- Unit tests should cover representative local entries, symmetry, `K*u` force recovery, invalid constants, axis-aligned transform identity, rotated symmetry, rigid translation, and axial end forces.
phases/euler-beam-3d/index.json
+10 -5
View File
@@ -16,7 +16,8 @@
{ {
"step": 1, "step": 1,
"name": "research-evidence", "name": "research-evidence",
"status": "pending", "status": "completed",
"summary": "3D Euler beam research evidence added",
"allowed_paths": [ "allowed_paths": [
"docs/research/euler-beam-3d-research.md" "docs/research/euler-beam-3d-research.md"
] ]
@@ -24,7 +25,8 @@
{ {
"step": 2, "step": 2,
"name": "formulation-spec", "name": "formulation-spec",
"status": "pending", "status": "completed",
"summary": "3D Euler beam formulation contract added",
"allowed_paths": [ "allowed_paths": [
"docs/formulations/euler-beam-3d-formulation.md" "docs/formulations/euler-beam-3d-formulation.md"
] ]
@@ -32,7 +34,8 @@
{ {
"step": 3, "step": 3,
"name": "numerical-review", "name": "numerical-review",
"status": "pending", "status": "completed",
"summary": "3D Euler beam numerical review added",
"allowed_paths": [ "allowed_paths": [
"docs/numerical-reviews/euler-beam-3d-review.md" "docs/numerical-reviews/euler-beam-3d-review.md"
] ]
@@ -40,7 +43,8 @@
{ {
"step": 4, "step": 4,
"name": "io-reference-contract", "name": "io-reference-contract",
"status": "pending", "status": "completed",
"summary": "3D Euler beam I/O and reference model contracts added",
"allowed_paths": [ "allowed_paths": [
"docs/io-definitions/euler-beam-3d-io.md", "docs/io-definitions/euler-beam-3d-io.md",
"docs/reference-models/euler-beam-3d-reference-models.md" "docs/reference-models/euler-beam-3d-reference-models.md"
@@ -49,7 +53,8 @@
{ {
"step": 5, "step": 5,
"name": "implementation-plan", "name": "implementation-plan",
"status": "pending", "status": "completed",
"summary": "3D Euler beam implementation plan added",
"allowed_paths": [ "allowed_paths": [
"docs/implementation-plans/euler-beam-3d-implementation-plan.md" "docs/implementation-plans/euler-beam-3d-implementation-plan.md"
] ]