baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7ea08441ede622485d63dfdf3113eea65cd8979d
FESADev/docs/project-plan/SOLVER_IMPLEMENT_INITIAL_PLAN.md
T
김경종 449bd4efe2 modify documents
2026-06-08 15:45:12 +09:00

10 KiB
Raw Blame History

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. Analyze new 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: New Solver Feature Requirements Analysis

Create docs/requirements/mitc4-linear-static-shell.md.

The requirements analysis 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:

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

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:

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:

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.
  • The current local default is C:\Program Files\HDF_Group\HDF5\2.1.1; use HDF5_ROOT for this root or HDF5_DIR for C:\Program Files\HDF_Group\HDF5\2.1.1\cmake.
  • 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.
Reference in New Issue View Git Blame Copy Permalink