docs: complete euler beam planning gates
This commit is contained in:
김경종
@@ -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.
|
||||
Reference in New Issue
Block a user