FESADev/docs/NUMERICAL_CONVENTIONS.md

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:

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:

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:

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:

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