186 lines
9.0 KiB
Markdown
186 lines
9.0 KiB
Markdown
# Numerical Conventions
|
|
|
|
## Purpose
|
|
This document defines the numerical conventions that must remain stable across the FESA solver, reference data, tests, and result files.
|
|
|
|
When a convention here conflicts with a lower-level implementation note, this document wins unless `docs/ADR.md` is updated.
|
|
|
|
## Source Basis
|
|
- Abaqus defines translational DOFs 1-3 and rotational DOFs 4-6, with rotations expressed in radians: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-conventions.htm
|
|
- Abaqus has no built-in unit system except rotation and angle measures; user data must be self-consistent: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-conventions.htm
|
|
- Abaqus uses right-handed coordinate systems and defines shell local surface directions from the projected global axis and positive element normal: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-conventions.htm
|
|
- Intel oneMKL provides `pardiso_64`, an ILP64-style PARDISO interface accepting `long long int` integer data for large sparse systems: https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-c/2024-2/pardiso-64.html
|
|
|
|
## Binding Decisions
|
|
- MITC4 coordinate and strain details will be defined explicitly in `docs/MITC4_FORMULATION.md`.
|
|
- Phase 1 shell nodes use 6 DOFs per node.
|
|
- The drilling DOF is retained and receives a small artificial stiffness in Phase 1.
|
|
- FESA does not enforce a unit system. Input values must be self-consistent, Abaqus-style.
|
|
- Result sign conventions follow Abaqus conventions.
|
|
- Essential boundary conditions are applied by constrained DOF elimination.
|
|
- Reaction forces are recovered from the full system vectors, not from the reduced system alone.
|
|
- Reference comparison uses stored Abaqus inputs and stored solved reference results under `reference/`.
|
|
- Mesh quality diagnostics are not part of Phase 1.
|
|
- Singular system diagnostics are required.
|
|
- Floating-point values use `double` by default.
|
|
- Large-model ids and indices use signed 64-bit integers.
|
|
|
|
## Degrees of Freedom
|
|
All Phase 1 shell nodes expose six structural DOFs:
|
|
|
|
| FESA Component | Abaqus DOF | Meaning | Unit |
|
|
|---|---:|---|---|
|
|
| `UX` | 1 | Translation in global or transformed x-direction | model length |
|
|
| `UY` | 2 | Translation in global or transformed y-direction | model length |
|
|
| `UZ` | 3 | Translation in global or transformed z-direction | model length |
|
|
| `RX` | 4 | Rotation about x-axis | radian |
|
|
| `RY` | 5 | Rotation about y-axis | radian |
|
|
| `RZ` | 6 | Rotation about z-axis | radian |
|
|
|
|
Implementation rules:
|
|
- Store DOF component ids using a compact enum or integer range `1..6`.
|
|
- Store global node ids, element ids, equation ids, sparse indices, and nonzero counts with signed 64-bit integer types.
|
|
- `DofManager` owns active DOF discovery, constrained/free partitioning, equation numbering, and sparse pattern inputs.
|
|
- Do not store equation ids inside `Node` or `Element`.
|
|
|
|
## Precision and Numeric Types
|
|
Recommended type aliases:
|
|
|
|
```cpp
|
|
using Real = double;
|
|
using GlobalId = std::int64_t;
|
|
using LocalIndex = std::int64_t;
|
|
using EquationId = std::int64_t;
|
|
using SparseIndex = std::int64_t;
|
|
```
|
|
|
|
Rules:
|
|
- Use `double` for matrix entries, vector entries, coordinates, material constants, loads, displacements, rotations, and result values.
|
|
- Use 64-bit integer indexing throughout the sparse assembly path so that MKL `pardiso_64` remains available for large models.
|
|
- Avoid silent narrowing when passing ids or sparse arrays to external libraries.
|
|
|
|
## Units
|
|
FESA follows the Abaqus convention: no unit system is built into the solver.
|
|
|
|
Rules:
|
|
- The solver core treats all dimensional input as unitless numeric values.
|
|
- The user and reference data must use a self-consistent unit system.
|
|
- Rotations are always radians.
|
|
- Result files may store an optional `unit_system_note` metadata string, but the solver must not convert units.
|
|
|
|
Examples of acceptable unit systems:
|
|
- `N, mm, tonne, second`
|
|
- `N, m, kg, second`
|
|
- `lbf, inch, lbf*s^2/in, second`
|
|
|
|
## Coordinate Systems
|
|
Global coordinates:
|
|
- The default global system is right-handed Cartesian.
|
|
- Phase 1 does not support user-defined transformed nodal coordinate systems unless explicitly added to `docs/ABAQUS_INPUT_SUBSET.md`.
|
|
|
|
Shell local directions:
|
|
- FESA result signs follow Abaqus shell local direction conventions.
|
|
- The exact MITC4 element basis construction must be defined in `docs/MITC4_FORMULATION.md`.
|
|
- For Abaqus compatibility, the positive shell normal is tied to node ordering by the right-hand rule.
|
|
- Local 1 and 2 directions must form a right-handed basis with the positive normal.
|
|
|
|
## Result Sign Convention
|
|
FESA result sign conventions follow Abaqus unless a FESA-specific exception is documented.
|
|
|
|
Phase 1 output variables:
|
|
- `U`: nodal displacement and rotation vector in DOF order `UX, UY, UZ, RX, RY, RZ`.
|
|
- `RF`: nodal reaction force and reaction moment in the same component order.
|
|
- `S`: shell stress components in local shell directions when available.
|
|
- `E`: shell strain components in local shell directions when available.
|
|
- `SF`: shell section force and moment resultants when available.
|
|
|
|
Stress and strain component ordering follows the Abaqus convention:
|
|
- direct 1
|
|
- direct 2
|
|
- direct 3
|
|
- shear 12
|
|
- shear 13
|
|
- shear 23
|
|
|
|
Shear strain output should be documented as engineering shear strain when matched to Abaqus-style output.
|
|
|
|
## Boundary Conditions
|
|
Phase 1 uses constrained DOF elimination:
|
|
|
|
1. Build the full DOF list.
|
|
2. Mark constrained DOFs from `*Boundary`.
|
|
3. Partition DOFs into free and constrained sets.
|
|
4. Assemble or project the reduced free-DOF system.
|
|
5. Solve for free DOF unknowns.
|
|
6. Reconstruct the full displacement vector.
|
|
|
|
Rules:
|
|
- Phase 1 supports zero-valued fixed constraints as the primary path.
|
|
- Nonzero prescribed displacements are not a Phase 1 requirement unless added to `docs/ABAQUS_INPUT_SUBSET.md`.
|
|
- `DofManager` owns constrained/free mapping and must provide enough data to reconstruct full vectors.
|
|
|
|
## Reaction Recovery
|
|
Reaction force and moment recovery uses the full system:
|
|
|
|
```text
|
|
R_full = K_full * U_full - F_full
|
|
```
|
|
|
|
Rules:
|
|
- `K_full` means the assembled stiffness before constrained DOF elimination.
|
|
- `U_full` means the solved displacement vector reconstructed with constrained DOF values.
|
|
- `F_full` means the full external load vector in the original global DOF space.
|
|
- `RF` is reported primarily for constrained DOFs, but full residual-like vectors may be retained for diagnostics.
|
|
- Reference comparison should include at least one reaction balance test.
|
|
|
|
## Drilling DOF Policy
|
|
Phase 1 retains `RZ` at each shell node and assigns a small artificial drilling stiffness.
|
|
|
|
Rules:
|
|
- The value must be parameterized, not hard-coded deep inside the MITC4 kernel.
|
|
- The default value must be documented in `docs/MITC4_FORMULATION.md` before implementation.
|
|
- The artificial stiffness should be small relative to representative membrane or bending stiffness, but large enough to avoid a singular stiffness matrix for unconstrained drilling modes.
|
|
- Reference comparisons should include sensitivity checks if the drilling stiffness materially changes displacement results.
|
|
|
|
## Singular System Diagnostics
|
|
FESA must provide actionable diagnostics before or during linear solve failure.
|
|
|
|
Required Phase 1 checks:
|
|
- No free DOFs exist after applying constraints.
|
|
- At least one active element exists in the current `AnalysisModel`.
|
|
- Every active element references existing nodes.
|
|
- Every active element references an assigned property and material.
|
|
- Every active property references an existing material.
|
|
- Every load and boundary condition references an existing node or node set.
|
|
- At least one load component is nonzero for ordinary static solve tests unless the test explicitly expects zero response.
|
|
- Free DOFs exist that are not touched by any active element connectivity.
|
|
- Rotational DOFs, especially drilling DOFs, may be unconstrained or weakly constrained.
|
|
- The reduced system size and sparse nonzero count are nonzero before solve.
|
|
- The sparse solver reports zero pivot, numerical factorization failure, or structural singularity.
|
|
|
|
Recommended diagnostic style:
|
|
|
|
```text
|
|
FESA-SINGULAR-DOF-UNTOUCHED:
|
|
Node 42 DOF RZ is free but has no stiffness contribution from active elements.
|
|
Check boundary conditions, element connectivity, property assignment, or drilling stiffness settings.
|
|
```
|
|
|
|
Phase 1 explicitly does not perform mesh quality diagnostics such as aspect ratio, warpage, skew, or element distortion checks.
|
|
|
|
## Reference Comparison Tolerances
|
|
Reference comparison must use both absolute and relative tolerances:
|
|
|
|
```text
|
|
pass if abs(actual - expected) <= abs_tol
|
|
or abs(actual - expected) <= rel_tol * max(abs(expected), reference_scale)
|
|
```
|
|
|
|
Initial defaults may be proposed per benchmark in `docs/VERIFICATION_PLAN.md`. Final tolerances should be tied to stored reference data and solver maturity.
|
|
|
|
## Open Decisions
|
|
- The exact default drilling stiffness scale.
|
|
- The final MITC4 local basis algorithm for warped quadrilateral elements.
|
|
- Which shell stress/strain/resultant outputs are mandatory in Phase 1.
|
|
- The first accepted reference result file format under `reference/`.
|