modify documents
This commit is contained in:
NINI
185
docs/NUMERICAL_CONVENTIONS.md
Normal file
185
docs/NUMERICAL_CONVENTIONS.md
Normal file
@@ -0,0 +1,185 @@
|
||||
# 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/`.
|
||||
Reference in New Issue
Block a user