# 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/`.