김경종
197 lines
23 KiB
Markdown
197 lines
23 KiB
Markdown
# 3D Euler-Bernoulli Beam UEL Requirements
|
|
|
|
## Metadata
|
|
- feature_id: uel-3d-euler-beam
|
|
- title: 3D Euler-Bernoulli Beam Abaqus/Standard UEL
|
|
- status: needs-user-decision
|
|
- owner_agent: requirement-agent
|
|
- date: 2026-06-11
|
|
|
|
## Purpose
|
|
Define a measurable requirements baseline for a two-node, small-displacement, linear elastic 3D Euler-Bernoulli beam element implemented as an Abaqus/Standard `UEL`. This document is the handoff contract for research, formulation, interface definition, no-Abaqus test model design, Fortran implementation planning, and external Abaqus result validation.
|
|
|
|
## In Scope
|
|
- Abaqus/Standard `UEL` entry point for static small-displacement analysis.
|
|
- Two-node 3D Euler-Bernoulli beam element with 12 total degrees of freedom.
|
|
- Six degrees of freedom per node ordered as `U1, U2, U3, UR1, UR2, UR3`.
|
|
- Linear elastic response with axial, bending about two principal local section axes, and Saint-Venant torsion stiffness.
|
|
- Static element stiffness contribution through `AMATRX`.
|
|
- Static internal force or residual contribution through `RHS`, with exact Abaqus sign convention delegated to the interface contract.
|
|
- User-consistent units with no unit conversion inside the element.
|
|
- No-Abaqus analytical evidence before any Fortran production source changes.
|
|
- External Abaqus artifact evidence based on user-generated ODB-extracted CSV files before solver-result comparison.
|
|
|
|
## Out Of Scope
|
|
- Geometric nonlinearity, large rotation, follower loads, and corotational updates.
|
|
- Timoshenko shear deformation, shear correction factors, and shear locking mitigation.
|
|
- Distributed loads, body forces, pressure loads, point-load handling inside `UEL`, and load interpolation.
|
|
- Mass matrix, damping matrix, modal dynamics, transient dynamics, and density-dependent behavior.
|
|
- Thermal strain, plasticity, damage, creep, viscoelasticity, warping torsion, section offset, tapered members, and curved beams.
|
|
- Direct ODB parsing or Abaqus job execution from this repository.
|
|
- Generated reference CSV, `.msg`, `.dat`, `.log`, or `.sta` evidence produced by Codex.
|
|
- Fortran source, no-Abaqus tests, reference artifacts, or implementation plans in this requirements step.
|
|
|
|
## Analysis Definition
|
|
- analysis_type: linear static small-displacement
|
|
- Abaqus entry point: `UEL`
|
|
- element_family: two-node 3D Euler-Bernoulli beam
|
|
- element_nodes: 2
|
|
- total_dofs: 12
|
|
- dofs_per_node: 6
|
|
- dof_order: node 1 `U1, U2, U3, UR1, UR2, UR3`, then node 2 `U1, U2, U3, UR1, UR2, UR3`
|
|
- material_model: linear elastic beam section stiffness
|
|
- required physical properties: `E`, `G`, `A`, `Iy`, `Iz`, `J`
|
|
- density: not required for first implementation; required only if a later approved mass-matrix scope is added
|
|
- coordinate_system: global nodal coordinates plus a local beam frame defined by the element axis and an orientation reference
|
|
- units: user-consistent force-length unit system; every external CSV used for validation must declare units
|
|
- boundary_conditions: defined by downstream no-Abaqus and external reference models
|
|
- loads: applied outside the `UEL`; first-scope `UEL` does not implement distributed or body load generation
|
|
|
|
## Requirement Decisions
|
|
- The first implementation shall require independent `E` and `G` values rather than deriving `G` from `E` and `nu`.
|
|
- The first implementation shall require `A`, `Iy`, `Iz`, and `J` as positive section properties.
|
|
- The first implementation shall not use density because mass and dynamics are out of scope.
|
|
- Element local axis 1 shall be the line from node 1 to node 2.
|
|
- A nonparallel orientation reference shall be required to define the remaining local beam axes; the exact Abaqus keyword and property mapping belongs to the I/O Definition Agent.
|
|
- `RHS` sign convention shall be resolved by the I/O Definition Agent against Abaqus `UEL` residual conventions and then tested by no-Abaqus single-element cases.
|
|
|
|
## Must Requirements
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-001: The feature shall target Abaqus/Standard `UEL` only.
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-002: The element shall be a two-node, small-displacement, linear elastic 3D Euler-Bernoulli beam.
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-003: The element shall expose exactly 12 active element degrees of freedom with six degrees of freedom per node.
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-004: The element degree-of-freedom ordering shall be `U1, U2, U3, UR1, UR2, UR3` at node 1 followed by the same order at node 2.
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-005: The first-scope material and section contract shall provide `E`, `G`, `A`, `Iy`, `Iz`, and `J`.
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-006: The accepted physical properties shall be finite and strictly positive.
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-007: The element orientation contract shall define a valid right-handed local beam frame from the node coordinates and a nonparallel orientation reference.
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-008: The element shall provide the static tangent stiffness contribution in `AMATRX`.
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-009: The element shall provide the static internal force or residual contribution in `RHS` according to the interface contract sign convention.
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-010: The first implementation shall exclude mass, damping, distributed load, thermal, nonlinear geometry, plasticity, damage, shear deformation, warping torsion, and section offset behavior.
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-011: The implementation shall not require this repository to run Abaqus jobs or parse ODB files.
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-012: The implementation shall have no-Abaqus evidence before any Fortran production source is changed.
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-013: Solver-result comparison shall require externally generated Abaqus artifacts under `references/uel-3d-euler-beam/`.
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-014: Every external solver-result CSV used for comparison shall include identifiers, component labels, coordinate-system labels, units, and numeric values.
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-015: Numerical comparisons shall use explicit absolute and relative tolerances rather than informal pass/fail judgment.
|
|
- ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-016: The requirements, research, formulation, interface, test model, implementation, and validation artifacts shall remain separate gate outputs.
|
|
|
|
## Should Requirements
|
|
- The no-Abaqus test suite should include independent single-element checks for axial extension, torsion, bending about local `y`, bending about local `z`, rigid-body modes, stiffness symmetry, and coordinate transformation.
|
|
- External Abaqus reference models should include at least one cantilever-style displacement/reaction check and one rotated-orientation check.
|
|
- The interface contract should name the exact `PROPS` or alternative property mapping only after the orientation convention and `RHS` sign convention are settled.
|
|
- The formulation document should document local-to-global transformation, rigid-body modes, and expected matrix symmetry without changing the requirements scope.
|
|
|
|
## Could Requirements
|
|
- A later approved scope could add density and consistent or lumped mass matrix behavior.
|
|
- A later approved scope could add distributed load vector generation.
|
|
- A later approved scope could add Timoshenko shear deformation as a separate element family or variant.
|
|
- A later approved scope could add section offset or warping-torsion behavior after new requirements and validation artifacts are approved.
|
|
|
|
## Input Requirements
|
|
- Conceptual physical inputs: `E`, `G`, `A`, `Iy`, `Iz`, `J`, node coordinates, and one orientation reference that is not parallel to the element axis.
|
|
- The I/O Definition Agent must define the Abaqus-facing source of these values, including property ordering, keyword support, validation behavior for invalid inputs, and mapping to `UEL` arguments.
|
|
- The requirements step does not approve a final `PROPS`, `JPROPS`, `COORDS`, or `PARAMS` layout.
|
|
|
|
## Output Requirements
|
|
- `AMATRX`: required for the static stiffness contribution.
|
|
- `RHS`: required for the static internal force or residual contribution.
|
|
- `SVARS`: not required for first implementation unless later interface work identifies a minimal diagnostic need.
|
|
- `ENERGY`: not required for first implementation; if populated later, it requires a separate requirement and verification method.
|
|
- ODB-extracted validation outputs: nodal displacement and reaction CSV evidence are required before solver-result comparison.
|
|
|
|
## Verification Quantities
|
|
- nodal_displacement: required for external Abaqus reference comparison.
|
|
- reaction: required for external Abaqus reference comparison.
|
|
- element_internal_force_or_residual: required for no-Abaqus verification; external CSV is optional unless a downstream extraction contract exposes it.
|
|
- stiffness_matrix: required for no-Abaqus verification.
|
|
- rigid_body_modes: required for no-Abaqus verification.
|
|
- stress: not-applicable for first implementation unless a later output recovery contract is approved.
|
|
- strain: not-applicable for first implementation unless a later output recovery contract is approved.
|
|
- energy_or_residual: residual required for no-Abaqus verification; energy not required for first implementation.
|
|
|
|
## Tolerance Policy
|
|
- no_abaqus_stiffness_absolute_tolerance: `1.0e-10` in user-consistent force-length units after nondimensional or scale-aware comparison.
|
|
- no_abaqus_stiffness_relative_tolerance: `1.0e-10`.
|
|
- no_abaqus_vector_absolute_tolerance: `1.0e-10` in user-consistent force or moment units after scale-aware comparison.
|
|
- no_abaqus_vector_relative_tolerance: `1.0e-10`.
|
|
- no_abaqus_symmetry_absolute_tolerance: `1.0e-12` for `AMATRX - transpose(AMATRX)` after scale-aware normalization.
|
|
- external_displacement_absolute_tolerance: `1.0e-8` in declared length units unless the reference model contract justifies a tighter value.
|
|
- external_reaction_relative_tolerance: `1.0e-6` for externally generated Abaqus CSV comparison.
|
|
- tolerance_owner: Reference Model Agent may tighten or scale these tolerances only by documenting the physical quantity, units, scale, and rationale.
|
|
|
|
## Required No-Abaqus Evidence Before Fortran Production Changes
|
|
- A no-Abaqus test or driver must check that the 12-by-12 stiffness matrix has the expected symmetry, rank behavior, and rigid-body null modes for an unconstrained element.
|
|
- A no-Abaqus test or driver must check axial stiffness against a closed-form two-node beam expectation.
|
|
- A no-Abaqus test or driver must check torsional stiffness against a closed-form two-node beam expectation.
|
|
- A no-Abaqus test or driver must check bending response about both local section axes.
|
|
- A no-Abaqus test or driver must check at least one rotated element orientation against an independently computed transformation expectation.
|
|
- A no-Abaqus test or driver must check that `RHS` is consistent with the accepted `AMATRX` and displacement vector sign convention.
|
|
- `tests/fortran/manifest.json` or an approved equivalent no-Abaqus validation entry must exist before production Fortran source is changed.
|
|
|
|
## Required External Abaqus Artifact Evidence Before Solver-Result Comparison
|
|
Expected location: `references/uel-3d-euler-beam/<model-id>/`
|
|
|
|
- `metadata.json`: required with schema version, artifact status, Abaqus version, precision, compiler information, entry point list, source file hashes, input file reference, CSV declarations, and extraction provenance.
|
|
- `model.inp`: required.
|
|
- `job.msg.tail.txt`: required.
|
|
- `job.dat.tail.txt`: required.
|
|
- `job.log.tail.txt`: required.
|
|
- `job.sta.tail.txt`: required.
|
|
- `extracted/*.csv`: required for declared comparison quantities.
|
|
- `result.odb.sha256`: optional when the ODB is not stored but provenance needs to identify the source result database.
|
|
- Minimum CSV comparison quantities for first external evidence: nodal displacement and reaction at selected nodes for static benchmark models.
|
|
|
|
## Requirement Verification Matrix
|
|
|
|
| id | statement | category | rationale | source | priority | verification_method | acceptance_criteria | tolerance | downstream_agents | status |
|
|
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-001 | The feature shall target Abaqus/Standard `UEL` only. | scope | Prevents mixed ABI assumptions. | user; step0 | must | document-inspection | Requirements, interface, and later source identify `UEL` as the only entry point. | not-applicable | I/O Definition Agent; Implementation Planning Agent | draft |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-002 | The element shall be a two-node, small-displacement, linear elastic 3D Euler-Bernoulli beam. | functional | Defines the element family and excludes shear deformation and nonlinear kinematics. | user; step0 | must | formulation-review; no-abaqus-tests | Formulation and tests cover axial, torsion, and two bending modes without shear terms or nonlinear update terms. | no-Abaqus relative `1.0e-10` for analytical checks | Research Agent; Formulation Agent; Reference Model Agent | draft |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-003 | The element shall expose exactly 12 active element degrees of freedom with six degrees of freedom per node. | interface | Fixes the element topology for `UEL` assembly. | user; step0 | must | interface-review; no-abaqus-tests | Interface contract and tests use `NDOFEL=12` and two six-DOF nodes. | not-applicable | I/O Definition Agent; Reference Model Agent | draft |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-004 | The element degree-of-freedom ordering shall be `U1, U2, U3, UR1, UR2, UR3` at node 1 followed by the same order at node 2. | interface | Prevents stiffness and residual component permutation errors. | user; step0 | must | interface-review; no-abaqus-tests | Unit tests or driver checks map all 12 components to the documented order. | exact index match | I/O Definition Agent; Reference Model Agent; Implementation Planning Agent | draft |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-005 | The first-scope material and section contract shall provide `E`, `G`, `A`, `Iy`, `Iz`, and `J`. | input | Provides all stiffness scalars needed for linear axial, torsion, and bending response. | user; requirement decision | must | interface-review; no-abaqus-tests | Interface contract defines all six required physical properties and no-Abaqus tests exercise each property. | not-applicable for presence; numerical checks per quantity tolerances | I/O Definition Agent; Reference Model Agent | draft |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-006 | The accepted physical properties shall be finite and strictly positive. | input-validation | Prevents singular or nonphysical stiffness definitions. | requirement decision | must | no-abaqus-tests | Invalid zero, negative, NaN, or infinite properties are rejected or reported by the approved interface behavior before matrix assembly. | exact validation outcome | I/O Definition Agent; Reference Model Agent; Implementation Planning Agent | draft |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-007 | The element orientation contract shall define a valid right-handed local beam frame from the node coordinates and a nonparallel orientation reference. | orientation | 3D bending requires stable local section axes. | requirement decision | must | formulation-review; interface-review; no-abaqus-tests | Formulation and interface define the local frame, reject parallel orientation references, and pass a rotated-orientation test. | no-Abaqus relative `1.0e-10` for transformed stiffness checks | Formulation Agent; I/O Definition Agent; Reference Model Agent | draft |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-008 | The element shall provide the static tangent stiffness contribution in `AMATRX`. | output | `AMATRX` is the primary static contribution for Abaqus/Standard assembly. | user; step0 | must | no-abaqus-tests; external-reference-comparison | No-Abaqus tests match analytical stiffness expectations; external reference models converge and match displacement/reaction evidence. | no-Abaqus relative `1.0e-10`; external reaction relative `1.0e-6` | Formulation Agent; Reference Model Agent; Implementation Planning Agent; Validation Agent | draft |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-009 | The element shall provide the static internal force or residual contribution in `RHS` according to the interface contract sign convention. | output | Static equilibrium requires a consistent residual vector. | user; step0 | must | interface-review; no-abaqus-tests; external-reference-comparison | Interface defines the sign convention; no-Abaqus tests verify consistency with `AMATRX` and displacement; external models match reactions and displacements. | no-Abaqus vector relative `1.0e-10`; external displacement absolute `1.0e-8` | I/O Definition Agent; Reference Model Agent; Validation Agent | draft |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-010 | The first implementation shall exclude mass, damping, distributed load, thermal, nonlinear geometry, plasticity, damage, shear deformation, warping torsion, and section offset behavior. | non-scope | Keeps the first implementation verifiable and linear. | user; step0 | must | document-inspection; source-review | Requirements, formulation, interface, tests, and source contain no approved behavior from the excluded list. | not-applicable | Research Agent; Formulation Agent; Implementation Planning Agent | draft |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-011 | The implementation shall not require this repository to run Abaqus jobs or parse ODB files. | validation-boundary | Preserves project architecture and reproducibility. | AGENTS.md; ADR-004 | must | workspace-validation; reference-artifact-review | Validation commands use no-Abaqus tests and artifact metadata checks; no repository script is required to run Abaqus or parse ODB. | not-applicable | Reference Model Agent; Validation Agent | draft |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-012 | The implementation shall have no-Abaqus evidence before any Fortran production source is changed. | process | Enforces RED -> GREEN -> VERIFY for numerical code. | AGENTS.md; ADR-007 | must | manifest-review; validation-command | A no-Abaqus test manifest or approved equivalent exists and fails for expected missing behavior before production source changes. | exact process evidence | Reference Model Agent; Implementation Planning Agent | draft |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-013 | Solver-result comparison shall require externally generated Abaqus artifacts under `references/uel-3d-euler-beam/`. | reference-artifact | Ensures solver evidence has provenance. | AGENTS.md; ADR-006 | must | reference-artifact-validation | `python scripts/validate_reference_artifacts.py` accepts only complete externally generated artifact bundles before comparison. | not-applicable | Reference Model Agent; Validation Agent | draft |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-014 | Every external solver-result CSV used for comparison shall include identifiers, component labels, coordinate-system labels, units, and numeric values. | csv-schema | Prevents ambiguous numerical comparison. | ARCHITECTURE.md | must | schema-validation; reference-artifact-review | CSV schema includes step/frame or time, node or element identifier as applicable, component, coordinate system, unit, and value columns. | exact schema match | I/O Definition Agent; Validation Agent | draft |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-015 | Numerical comparisons shall use explicit absolute and relative tolerances rather than informal pass/fail judgment. | tolerance | Makes verification reproducible. | requirements skill | must | test-review; validation-review | Test model and validation artifacts name absolute and relative tolerances for each compared quantity. | values in Tolerance Policy unless narrowed by owner | Reference Model Agent; Validation Agent | draft |
|
|
| ABAQUS-USUB-REQ-UEL-3D-EULER-BEAM-016 | The requirements, research, formulation, interface, test model, implementation, and validation artifacts shall remain separate gate outputs. | process | Avoids mixing unreviewed decisions into implementation. | AGENTS.md; ADR-003 | must | document-inspection; workspace-validation | Each downstream phase writes to its own documented artifact family and does not replace requirements with implementation details. | not-applicable | Coordinator Agent; all downstream agents | draft |
|
|
|
|
## Open Questions
|
|
- Exact Abaqus input keyword subset for assigning UEL properties and orientation: owner `I/O Definition Agent`.
|
|
- Exact `PROPS`, `JPROPS`, `COORDS`, and orientation reference mapping: owner `I/O Definition Agent`.
|
|
- Exact `RHS` sign convention and treatment of `LFLAGS` static requests: owner `I/O Definition Agent`.
|
|
- Whether `SVARS` or `ENERGY` should carry diagnostics in a later scope: owner `Formulation Agent` and `I/O Definition Agent`.
|
|
- Exact external benchmark model set and CSV filenames: owner `Reference Model Agent`.
|
|
- Whether any first-scope reference model needs element-level force extraction beyond nodal `U` and `RF`: owner `Reference Model Agent` and `Validation Agent`.
|
|
|
|
## Downstream Handoff
|
|
|
|
### Research Agent
|
|
- Confirm Abaqus/Standard `UEL` static contribution expectations for `RHS`, `AMATRX`, `LFLAGS`, and required argument semantics.
|
|
- Collect reliable references for 3D Euler-Bernoulli beam stiffness, local coordinate construction, and transformation behavior.
|
|
- Separate manual-backed facts from implementation inference.
|
|
|
|
### Formulation Agent
|
|
- Define the local stiffness matrix, local-to-global transformation, rigid-body mode expectations, and internal force/residual relation without adding out-of-scope physics.
|
|
- Define how the right-handed local frame is constructed from node coordinates and orientation reference.
|
|
- Identify numerical risks such as near-zero element length or nearly parallel orientation references.
|
|
|
|
### I/O Definition Agent
|
|
- Define the exact Abaqus-facing input contract for `E`, `G`, `A`, `Iy`, `Iz`, `J`, coordinates, and orientation.
|
|
- Define `UEL` argument responsibilities, including `RHS`, `AMATRX`, `SVARS`, `ENERGY`, `LFLAGS`, tensor/component ordering, units, and validation behavior.
|
|
- Define CSV schema requirements for external solver-result comparison.
|
|
|
|
### Reference Model Agent
|
|
- Design no-Abaqus tests for axial, torsion, two bending modes, matrix symmetry, rigid-body modes, orientation transformation, and `RHS` consistency.
|
|
- Define required `tests/fortran/manifest.json` entries or approved equivalent no-Abaqus validation entries before Fortran production changes.
|
|
- Define external Abaqus reference artifact bundles under `references/uel-3d-euler-beam/<model-id>/` without generating reference CSVs in this repository.
|
|
|
|
### Implementation Planning Agent
|
|
- Do not create or modify Fortran production source until no-Abaqus RED evidence exists.
|
|
- Keep the Abaqus `UEL` wrapper thin and isolate testable beam calculations where the approved interface contract permits.
|
|
- Use `python scripts/validate_fortran.py`, `python scripts/validate_reference_artifacts.py`, and `python scripts/validate_workspace.py` for VERIFY evidence.
|