feat: implement phase 1 solver baseline

docs/MITC4_FORMULATION.md

@@ -35,6 +35,47 @@ Non-scope:
 - Thermal-stress coupling.
 - Mesh quality diagnostics.
 
+## Phase 1 Closed Baseline Decisions
+The following decisions close the Phase 1 implementation gate for the first baseline C++ implementation. They are intentionally conservative and may be revised by ADR after Abaqus S4 reference cases are added.
+
+Decisions:
+- Mandatory Phase 1 result outputs are limited to nodal `U` and `RF`. Element `S`, `E`, and `SF` remain future outputs.
+- In-plane membrane and bending terms use standard bilinear Reissner-Mindlin interpolation with 2x2 Gauss integration.
+- Transverse shear uses MITC4 mid-side tying interpolation:
+
+```text
+gamma_xz_mitc(r, s) =
+  0.5 * (1 - s) * gamma_xz(0, -1)
+  + 0.5 * (1 + s) * gamma_xz(0, +1)
+
+gamma_yz_mitc(r, s) =
+  0.5 * (1 - r) * gamma_yz(-1, 0)
+  + 0.5 * (1 + r) * gamma_yz(+1, 0)
+```
+
+- The four tying points are the midside natural-coordinate points `(0,-1)`, `(0,+1)`, `(-1,0)`, and `(+1,0)`.
+- Local basis construction uses averaged opposite edges:
+
+```text
+v1 = 0.5 * ((x2 - x1) + (x3 - x4))
+v2 = 0.5 * ((x4 - x1) + (x3 - x2))
+e1 = normalize(v1)
+e2_raw = v2 - dot(v2, e1) * e1
+e2_pre = normalize(e2_raw)
+e3 = normalize(cross(e1, e2_pre))
+e2 = normalize(cross(e3, e1))
+```
+
+- For mildly warped quadrilaterals this is an averaged midsurface basis. Severe warpage is not diagnosed as mesh quality in Phase 1, but near-zero vectors or Jacobians are invalid/singular element diagnostics.
+- Integration point order for stiffness tests is `(-g,-g)`, `(g,-g)`, `(g,g)`, `(-g,g)` conceptually, with `g = 1 / sqrt(3)`. Implementation may loop over the same set in row-major order as long as assembled stiffness is invariant.
+- The default drilling stiffness scale is:
+
+```text
+drilling_stiffness_scale = 1.0e-6
+```
+
+The current baseline applies this scale to a representative `E * thickness` drilling stabilization term. The value is reported through the element options path and must be revisited after Abaqus S4 displacement references are available.
+
 ## Nodal DOFs
 Each node has:
 
@@ -64,7 +105,7 @@ Node ordering:
 - Abaqus `TYPE=S4R` is not supported in Phase 1.
 
 ## Coordinate Frames
-The exact local basis construction must be completed before MITC4 implementation.
+The Phase 1 local basis construction is defined by the averaged-edge algorithm in `Phase 1 Closed Baseline Decisions`.
 
 Minimum requirements:
 - Define a local shell normal from the quadrilateral geometry.
@@ -73,11 +114,10 @@ Minimum requirements:
 - Document behavior for non-planar quadrilaterals.
 - Use the same convention consistently for stiffness, stress/strain recovery, and result output.
 
-Recommended Phase 1 convention:
-- Use the element midsurface geometry to compute an average normal.
-- Use a projected global axis to define the local 1-direction when possible, matching Abaqus convention conceptually.
-- Fall back to a stable element-edge-based direction when the projected global axis is nearly parallel to the normal.
-- Record the final algorithm in this document before coding.
+Phase 1 convention:
+- Use the element midsurface geometry to compute an average basis from opposite edges.
+- Use the positive shell normal implied by the input node ordering.
+- Use a right-handed local basis consistently for stiffness, reaction recovery, and future result output.
 
 ## Shape Functions
 Baseline quadrilateral bilinear interpolation:
@@ -108,12 +148,12 @@ MITC4 requirement:
 - Use MITC transverse shear interpolation to alleviate shear locking.
 - Do not replace MITC4 with plain full-integration Reissner-Mindlin Q4.
 
-The exact tying point equations and shear interpolation formula must be added from the selected primary source before implementation.
+The Phase 1 transverse shear tying formula is the midside interpolation stated in `Phase 1 Closed Baseline Decisions`.
 
 ## Numerical Integration
-Initial Phase 1 plan:
-- In-plane integration: 2x2 Gauss for membrane/bending/shear stiffness unless the final formulation requires a different split.
-- Thickness integration: homogeneous linear elastic section may be integrated analytically or with a documented simple rule.
+Phase 1 baseline:
+- In-plane integration: 2x2 Gauss for membrane, bending, MITC shear, and drilling stabilization.
+- Thickness integration: homogeneous linear elastic shell section is integrated analytically using `t`, `t^3 / 12`, and shear correction `5 / 6`.
 - Benchmark literature commonly reports 2x2 in-plane Gauss integration for S4/MITC4-style 4-node elements and 2-point thickness integration in comparative shell studies.
 
 Rules:
@@ -124,6 +164,7 @@ Rules:
 ## Drilling DOF Stabilization
 Decision:
 - Phase 1 uses small artificial drilling stiffness.
+- Default scale: `drilling_stiffness_scale = 1.0e-6`.
 
 Requirements:
 - Expose a parameter such as `drilling_stiffness_scale`.
@@ -132,13 +173,14 @@ Requirements:
 - Include benchmark sensitivity checks if reference results are sensitive to the value.
 - Report the value in result metadata.
 
-Open default proposal:
+Baseline rule:
 
 ```text
-k_drill = alpha * representative_element_stiffness
+k_drill = drilling_stiffness_scale * representative_element_stiffness
+representative_element_stiffness = E * thickness
 ```
 
-where `alpha` should be selected only after reviewing formulation sources and early reference cases.
+The representative stiffness may be refined after the first Abaqus S4 reference cases are available.
 
 ## Element Outputs
 Phase 1 minimum:
@@ -165,15 +207,14 @@ Before integration with the global solver:
 - drilling stiffness sensitivity check.
 
 ## Pre-Implementation Gate
-Do not implement `MITC4Element` until these decisions are recorded in this document or a linked ADR:
-- exact transverse shear tying point equations.
-- exact local shell basis algorithm for flat and non-flat quadrilaterals.
-- exact default drilling stiffness scale and parameter name.
-- exact integration point ordering.
-- whether Phase 1 reports only `U` and `RF`, or also element stress/strain/resultant fields.
-- stress/strain recovery locations if `S`, `E`, or `SF` are included in Phase 1.
+Phase 1 baseline implementation may proceed because these items are now recorded above:
+- transverse shear tying point equations.
+- local shell basis algorithm for flat and mildly warped quadrilaterals.
+- default drilling stiffness scale and parameter name.
+- integration point set and ordering convention.
+- Phase 1 mandatory output scope: `U` and `RF` only.
 
-If implementation starts before all optional stress/resultant decisions are closed, limit Phase 1 mandatory outputs to `U` and `RF`.
+Stress/strain recovery locations for `S`, `E`, and `SF` remain future decisions and must not be implemented as mandatory Phase 1 outputs.
 
 ## Reference Benchmarks
 MITC4 baseline acceptance should include:
@@ -212,9 +253,5 @@ S4R:
 - Requires reduced integration and hourglass control decisions.
 
 ## Open Decisions Before Coding
-- Exact MITC4 transverse shear tying point formula.
-- Exact element local basis for warped quads.
-- Exact drilling stiffness default.
 - Exact stress/strain recovery locations.
-- Whether Phase 1 reports `S`, `E`, and `SF`, or only `U` and `RF`.
 - Whether local coordinate transforms from Abaqus input are deferred or rejected.