modify documents

2026-06-05 16:58:13 +09:00
parent 5a23502570
commit 92a5cb19c0
38 changed files with 268 additions and 45 deletions
@@ -0,0 +1,313 @@
+# MITC4 Linear Static Shell Solver Initial Implementation Plan
+
+## Summary
+FESA will implement an initial finite element structural solver feature named `mitc4-linear-static-shell`. The feature reads an Abaqus-style input file, builds an internal finite element model, performs linear static analysis with a MITC4 shell element, writes HDF5 results, and verifies those results against stored Abaqus reference artifacts.
+
+The implementation must follow the full solver development workflow:
+
+1. Define solver feature requirements.
+2. Research books, papers, manuals, and related solver implementations.
+3. Write the finite element formulation required for code implementation.
+4. Define solver input and output data contracts.
+5. Create TDD test models for both FESA and the reference solver.
+6. Implement code.
+7. Compare FESA results against reference solver results for nodal displacement, reaction, element internal force, and stress.
+8. Mark implementation complete only when result differences are within tolerance.
+9. Release the solver feature.
+
+## Scope
+Feature id: `mitc4-linear-static-shell`
+
+Included:
+- Linear static structural analysis.
+- MITC4 4-node shell element.
+- Six DOF per node: `U1, U2, U3, UR1, UR2, UR3`.
+- Single-layer isotropic linear elastic shell section.
+- Abaqus `.inp` subset input.
+- Intel oneAPI MKL CSR/PARDISO sparse linear solve.
+- Intel oneAPI TBB parallel element computation and result recovery.
+- HDF5 solver result output.
+- Stored Abaqus S4R primary reference comparison.
+- Stored Abaqus S4 diagnostic reference comparison.
+
+Excluded:
+- Nastran BDF input.
+- Nonlinear geometry.
+- Nonlinear material.
+- Dynamic analysis.
+- Buckling/eigenvalue analysis.
+- Composite/layered shell section.
+- Contact.
+- Agent-run Abaqus or Nastran execution.
+- Reference artifact generation by agents.
+- OpenSees API compatibility.
+
+## Architecture
+Use OpenSees as an architectural reference, not as an API clone. FESA should use modern C++17 ownership and small testable modules.
+
+Primary conceptual modules:
+- `Domain`: model container for nodes, elements, constraints, loads, materials, sections, and analysis metadata.
+- `Node`: id, coordinates, and six ordered DOFs.
+- `Element`: abstract element behavior for stiffness, internal force, result recovery, and connectivity.
+- `ShellMITC4Element`: four-node MITC4 implementation with 24 element DOFs.
+- `Material/Section`: isotropic elastic shell section with membrane, bending, shear, and stress recovery contract.
+- `Analysis`: linear static analysis driver.
+- `SystemOfEqn`: DOF numbering, constraints, CSR assembly, MKL PARDISO solve.
+- `ResultWriter`: HDF5 output.
+- `ReferenceComparator`: HDF5 reference comparison.
+
+## Step 1: Requirements Baseline
+Create `docs/requirements/mitc4-linear-static-shell.md`.
+
+The requirement document must define:
+- analysis type: linear static
+- element type: MITC4 shell
+- DOF order: `U1, U2, U3, UR1, UR2, UR3`
+- material: isotropic linear elastic
+- section: uniform shell thickness
+- input: Abaqus `.inp` subset
+- output: HDF5
+- verification quantities: nodal displacement, reaction, element internal force/resultant, stress
+- tolerance: single value `1e-5`
+- pass rule: `abs(error) <= 1e-5` or `relative(error) <= 1e-5`
+
+Acceptance criteria:
+- Every must requirement has a verification method.
+- Every numerical output requirement has component names and units policy.
+- Reference artifact needs are listed under `references/mitc4-linear-static-shell/`.
+
+## Step 2: Research Evidence
+Create `docs/research/mitc4-linear-static-shell-research.md`.
+
+Research must cover:
+- Dvorkin-Bathe continuum mechanics based four-node shell formulation.
+- MITC4 mixed interpolation of tensorial components.
+- Assumed transverse shear strain interpolation and shear locking.
+- OpenSees `ShellMITC4` class structure and resultants.
+- Abaqus S4/S4R behavior as practical reference elements.
+- Patch tests and Scordelis-Lo shell benchmark.
+
+The research document must separate verified source facts from implementation inference.
+
+## Step 3: FEM Formulation
+Create `docs/formulations/mitc4-linear-static-shell-formulation.md`.
+
+The formulation must define:
+- reference coordinates and node ordering.
+- shell midsurface interpolation.
+- director and local coordinate basis policy.
+- six-DOF nodal displacement vector.
+- membrane, bending, transverse shear strain measures.
+- MITC transverse shear tying/interpolation.
+- isotropic shell constitutive matrix.
+- element stiffness expression.
+- 2x2 Gauss integration.
+- drill stiffness policy.
+- stress and resultant recovery.
+- invalid Jacobian and degenerate element checks.
+
+Default drill stiffness policy:
+- v0 hardcodes `alpha=1`.
+- `Ktt = alpha * min_eigenvalue(D_membrane)`.
+- Input override is deferred to a later phase.
+
+## Step 4: I/O Contract
+Create `docs/io-definitions/mitc4-linear-static-shell-io.md`.
+
+Input subset:
+- `*NODE`
+- `*ELEMENT, TYPE=S4`
+- `*ELEMENT, TYPE=S4R`
+- `*MATERIAL`
+- `*ELASTIC`
+- `*SHELL SECTION`
+- `*BOUNDARY`
+- `*CLOAD`
+- `*STEP`
+
+Output format:
+- HDF5 file.
+- No CSV output is required for this feature.
+
+Required HDF5 layout:
+```text
+/metadata
+  feature_id
+  solver_version
+  model_id
+  units
+  tolerance
+  reference_solver
+
+/mesh/nodes
+/mesh/elements/mitc4/connectivity
+
+/results/step_000/frame_000/nodal/displacement
+/results/step_000/frame_000/nodal/reaction
+/results/step_000/frame_000/element/forces
+/results/step_000/frame_000/element/stress
+```
+
+Required result components:
+- displacement: `U1, U2, U3, UR1, UR2, UR3`
+- reaction: `RF1, RF2, RF3, RM1, RM2, RM3`
+- element force/resultant: `N11, N22, N12, M11, M22, M12, Q13, Q23`
+- stress: `S11, S22, S12, S13, S23`
+
+## Step 5: TDD Reference Models
+Create `docs/reference-models/mitc4-linear-static-shell-reference-models.md`.
+
+Reference policy:
+- FESA agents do not run Abaqus or Nastran.
+- Stored Abaqus S4R HDF5 artifacts are the primary pass/fail reference.
+- Stored Abaqus S4 HDF5 artifacts are diagnostic only.
+
+Initial model portfolio:
+- membrane patch
+- bending patch
+- transverse shear patch
+- twist patch
+- coarse Scordelis-Lo shell
+
+Each model bundle must include:
+```text
+references/mitc4-linear-static-shell/<model-id>/
+  model.inp
+  metadata.json
+  abaqus_s4r/results.h5
+  abaqus_s4/results.h5
+  README.md
+```
+
+`metadata.json` must record:
+- model id
+- source/provenance
+- Abaqus version
+- element type
+- units
+- output locations
+- tolerance `1e-5`
+- compared quantities
+- known limitations
+
+## Step 6: Code Implementation Plan
+Create `docs/implementation-plans/mitc4-linear-static-shell-implementation-plan.md`.
+
+Implementation must be TDD-first:
+
+1. Write failing parser tests.
+2. Implement minimum Abaqus `.inp` parser behavior.
+3. Write failing MITC4 element tests.
+4. Implement shape functions, Jacobian checks, MITC shear interpolation, stiffness, and recovery.
+5. Write failing assembly tests.
+6. Implement DOF numbering, constraint handling, and deterministic CSR assembly.
+7. Write failing MKL PARDISO solve tests.
+8. Implement solver wrapper and reaction recovery.
+9. Write failing TBB deterministic parallel tests.
+10. Implement TBB parallel element computations with deterministic merge.
+11. Write failing HDF5 schema tests.
+12. Implement HDF5 C API RAII wrapper and result writer.
+13. Write failing reference comparison tests.
+14. Implement HDF5 reference comparator.
+15. Run full validation.
+
+Required validation commands:
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -L mitc4
+```
+
+## Step 7: Reference Verification
+Create `docs/reference-verifications/mitc4-linear-static-shell-reference-verification.md`.
+
+Comparison inputs:
+- FESA `results.h5`
+- stored Abaqus S4R `results.h5`
+- diagnostic Abaqus S4 `results.h5`
+- metadata tolerance and schema version
+
+Compared quantities:
+- nodal displacement
+- nodal reaction
+- element internal force/resultant
+- stress
+
+Matching rules:
+- node id for nodal quantities
+- element id plus Gauss point id for element quantities
+- component name for scalar comparisons
+
+Pass rule:
+```text
+abs(error) <= 1e-5 OR relative(error) <= 1e-5
+```
+
+Report:
+- compared quantity
+- number of matched rows
+- missing rows
+- extra rows
+- maximum absolute error
+- maximum relative error
+- worst id
+- worst component
+- pass/fail
+
+## Step 8: Completion Decision
+Implementation is complete only when:
+- all required tests pass;
+- CMake/MSVC/x64/Debug build passes;
+- all required HDF5 result quantities compare within tolerance `1e-5`;
+- no required reference artifact is missing;
+- failures are not hidden as known limitations.
+
+If comparison fails, classify the failure as one of:
+- missing reference artifact
+- schema mismatch
+- id mismatch
+- unit or coordinate mismatch
+- formulation defect
+- implementation defect
+- tolerance failure
+- reference artifact issue
+
+Then return to the owning workflow step.
+
+## Step 9: Release
+Create `docs/releases/mitc4-linear-static-shell-release.md`.
+
+Release document must include:
+- feature id and scope
+- supported input keywords
+- supported outputs
+- dependency versions
+- test model list
+- reference comparison summary
+- tolerance policy
+- known limitations
+- validation commands and status
+
+Release is not approved by build success alone. Release requires reference comparison success and documented limitations.
+
+## Dependency Plan
+MKL:
+- Use oneAPI MKL through `MKLROOT` or known oneAPI path.
+- Use CSR matrix storage and PARDISO for the global linear system.
+
+TBB:
+- Use oneAPI TBB through `TBBROOT` or known oneAPI path.
+- Parallelize element-local stiffness and result recovery.
+- Use deterministic merge for global assembly.
+
+HDF5:
+- FESA provides an internal RAII wrapper around the HDF5 C API.
+- The HDF5 C library itself must be supplied through `HDF5_ROOT` or `HDF5_DIR`.
+- HDF5 is required for solver output and reference comparison.
+
+## Assumptions
+- Abaqus reference artifacts are generated outside the agent workflow.
+- S4R is the primary reference for pass/fail.
+- S4 is diagnostic and does not determine pass/fail.
+- The single tolerance value is `1e-5`.
+- The initial implementation prioritizes correctness and traceability over broad element coverage.