From c88de37a8386ee8a7011032070acf6d0e9713909 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:58:23 +0900 Subject: [PATCH] docs: complete euler beam planning gates --- .../formulations/euler-beam-3d-formulation.md | 210 ++++++++++++++++++ .../euler-beam-3d-implementation-plan.md | 127 +++++++++++ docs/io-definitions/euler-beam-3d-io.md | 94 ++++++++ .../numerical-reviews/euler-beam-3d-review.md | 76 +++++++ .../euler-beam-3d-reference-models.md | 136 ++++++++++++ docs/research/euler-beam-3d-research.md | 81 +++++++ phases/euler-beam-3d/index.json | 17 +- 7 files changed, 735 insertions(+), 6 deletions(-) create mode 100644 docs/formulations/euler-beam-3d-formulation.md create mode 100644 docs/implementation-plans/euler-beam-3d-implementation-plan.md create mode 100644 docs/io-definitions/euler-beam-3d-io.md create mode 100644 docs/numerical-reviews/euler-beam-3d-review.md create mode 100644 docs/reference-models/euler-beam-3d-reference-models.md create mode 100644 docs/research/euler-beam-3d-research.md diff --git a/docs/formulations/euler-beam-3d-formulation.md b/docs/formulations/euler-beam-3d-formulation.md new file mode 100644 index 0000000..229d947 --- /dev/null +++ b/docs/formulations/euler-beam-3d-formulation.md @@ -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. diff --git a/docs/implementation-plans/euler-beam-3d-implementation-plan.md b/docs/implementation-plans/euler-beam-3d-implementation-plan.md new file mode 100644 index 0000000..82715c9 --- /dev/null +++ b/docs/implementation-plans/euler-beam-3d-implementation-plan.md @@ -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. diff --git a/docs/io-definitions/euler-beam-3d-io.md b/docs/io-definitions/euler-beam-3d-io.md new file mode 100644 index 0000000..7e9bbb4 --- /dev/null +++ b/docs/io-definitions/euler-beam-3d-io.md @@ -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//frames//nodal/displacement` | `` | float64 | component names, units, coordinate system | nodal | Components `ux,uy,uz,rx,ry,rz`. | +| reaction | `/steps//frames//nodal/reaction` | `` | float64 | component names, units, coordinate system | nodal | Requires constraints/assembly. | +| internal force | `/steps//frames//element/internal_force` | `` | float64 | component names, units, coordinate system, element ids | element end | Components match beam local/global recovery contract. | +| stress | `/steps//frames//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//`. + +Required future CSV mappings: +- `_displacements.csv`: step, frame, node id, `ux`, `uy`, `uz`, and future rotational components if approved for comparison. +- `_reactions.csv`: step, frame, node id, force and moment reaction components. +- `_internalforces.csv`: step, frame, element id, end location, component, value. +- `_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. diff --git a/docs/numerical-reviews/euler-beam-3d-review.md b/docs/numerical-reviews/euler-beam-3d-review.md new file mode 100644 index 0000000..b074faf --- /dev/null +++ b/docs/numerical-reviews/euler-beam-3d-review.md @@ -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. diff --git a/docs/reference-models/euler-beam-3d-reference-models.md b/docs/reference-models/euler-beam-3d-reference-models.md new file mode 100644 index 0000000..480cf83 --- /dev/null +++ b/docs/reference-models/euler-beam-3d-reference-models.md @@ -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//` 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.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.inp + metadata.json + _displacements.csv + _reactions.csv + _internalforces.csv + README.md +``` + +`_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//frames//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//frames//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. diff --git a/docs/research/euler-beam-3d-research.md b/docs/research/euler-beam-3d-research.md new file mode 100644 index 0000000..fbbf63b --- /dev/null +++ b/docs/research/euler-beam-3d-research.md @@ -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//`; 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. diff --git a/phases/euler-beam-3d/index.json b/phases/euler-beam-3d/index.json index ff525fb..dad3bb2 100644 --- a/phases/euler-beam-3d/index.json +++ b/phases/euler-beam-3d/index.json @@ -16,7 +16,8 @@ { "step": 1, "name": "research-evidence", - "status": "pending", + "status": "completed", + "summary": "3D Euler beam research evidence added", "allowed_paths": [ "docs/research/euler-beam-3d-research.md" ] @@ -24,7 +25,8 @@ { "step": 2, "name": "formulation-spec", - "status": "pending", + "status": "completed", + "summary": "3D Euler beam formulation contract added", "allowed_paths": [ "docs/formulations/euler-beam-3d-formulation.md" ] @@ -32,7 +34,8 @@ { "step": 3, "name": "numerical-review", - "status": "pending", + "status": "completed", + "summary": "3D Euler beam numerical review added", "allowed_paths": [ "docs/numerical-reviews/euler-beam-3d-review.md" ] @@ -40,7 +43,8 @@ { "step": 4, "name": "io-reference-contract", - "status": "pending", + "status": "completed", + "summary": "3D Euler beam I/O and reference model contracts added", "allowed_paths": [ "docs/io-definitions/euler-beam-3d-io.md", "docs/reference-models/euler-beam-3d-reference-models.md" @@ -49,7 +53,8 @@ { "step": 5, "name": "implementation-plan", - "status": "pending", + "status": "completed", + "summary": "3D Euler beam implementation plan added", "allowed_paths": [ "docs/implementation-plans/euler-beam-3d-implementation-plan.md" ] @@ -100,4 +105,4 @@ } ], "created_at": "2026-06-12T17:44:12+0900" -} \ No newline at end of file +}