docs: finalize BodySimPy project showcase

README.md

@@ -1,189 +1,242 @@
 # BodySimPy
 
-Python-driven structural CAE workflow automation for simplified automotive body structures.
+## Python-Driven Structural CAE Workflow Automation for Automotive Body Structures
+
+[![CI](https://github.com/savbcar/BodySimPy/actions/workflows/ci.yml/badge.svg)](https://github.com/savbcar/BodySimPy/actions/workflows/ci.yml)
+[![Tests](https://img.shields.io/github/actions/workflow/status/savbcar/BodySimPy/ci.yml?branch=main&label=tests)](https://github.com/savbcar/BodySimPy/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.12-blue)
+![License](https://img.shields.io/badge/License-MIT-green)
+
+**BodySimPy** is a Python-based engineering software project for automating structural CAE studies around a simplified automotive body crossmember surrogate.
+
+The project combines analytical mechanics, CalculiX finite-element analysis, structural dynamics, uncertainty propagation, fatigue assessment, parameter-study automation, PyTorch surrogate modelling, automated reporting, test-driven development, AI-assisted software development, and simulation QA.
+
+The objective is not to reproduce a proprietary vehicle body model. The objective is to demonstrate how Python can be used to build a **reproducible, validated and extensible structural engineering workflow** around an open-source finite-element solver.
+
+---
+
+## Engineering Workflow
+
+```mermaid
+flowchart LR
+    A[YAML Configuration] --> B[Validated Domain Model]
+
+    B --> C[Analytical Solver]
+    B --> D[CalculiX FEA]
+
+    D --> E[Static Analysis]
+    D --> F[Modal Analysis]
 
-## Overview
+    C --> G[FEA Validation]
+    E --> G
 
-BodySimPy is an engineering software project exploring the automation of structural simulation workflows using Python.
+    E --> H[Parameter Sweeps]
+    E --> I[Stochastic Analysis]
+    E --> J[Fatigue Assessment]
 
-The project combines:
+    E --> K[FEA Dataset]
+    F --> K
 
-- parameterized structural models
-- automated FEA solver execution
-- static structural analysis
-- modal analysis
-- simulation result extraction
-- stochastic parameter studies
-- fatigue assessment
-- PyTorch surrogate modelling
-- automated testing and continuous integration
-- engineering result reporting
+    K --> L[PyTorch Surrogate]
 
-## Current Status
+    G --> M[Engineering Results]
+    H --> M
+    I --> M
+    J --> M
+    L --> M
 
-The current implementation contains:
+    M --> N[Simulation QA Agent]
+    M --> O[Automated Reporting]
 
-- validated geometric section calculations
-- material-domain models
-- analytical cantilever reference calculations
-- static deflection estimation
-- bending-stress estimation
-- first natural-frequency estimation
-- automated unit tests
-- Ruff formatting and linting
-- strict static type checking with mypy
-- GitHub Actions CI configuration
-- command-line interface
 
-## Planned Workflow
 
-Configuration → Model generation → FEA solver → Result parsing → Validation → Parameter studies → ML surrogate → Engineering report
+## Software Architecture
 
-## Engineering Philosophy
+BodySimPy/
+│
+├── configs/
+│   └── simulation and study configurations
+│
+├── data/
+│   └── generated engineering / surrogate datasets
+│
+├── docs/
+│   ├── figures/
+│   ├── validation/
+│   ├── ai_assisted_development.md
+│   └── simulation_qa_agent.md
+│
+├── reports/
+│   └── automated engineering summaries
+│
+├── scripts/
+│   └── reproducible study and reporting entry points
+│
+├── src/bodysimpy/
+│   ├── agents/
+│   ├── analysis/
+│   ├── config/
+│   ├── domain/
+│   ├── ml/
+│   ├── modeling/
+│   ├── reporting/
+│   ├── solvers/
+│   │   └── parsers/
+│   └── workflows/
+│
+└── tests/
+    ├── integration/
+    └── unit/
 
-Numerical simulation results are validated against independent analytical reference solutions wherever practical.
 
-## Current Technology
+Development Environment
 
-Python · NumPy · SciPy · pandas · pytest · Ruff · mypy · Typer · Git · GitHub Actions · Linux
+Primary development workflow:
+
+Linux through WSL / Ubuntu;
+Python virtual environment;
+Visual Studio Code;
+Git;
+GitHub;
+CalculiX;
+NumPy;
+SciPy;
+pandas;
+Matplotlib;
+Pydantic;
+Typer;
+pytest;
+Ruff;
+mypy;
+PyTorch;
+GitHub Copilot.
 
-## Planned Integration
+What I Learned
 
-CalculiX · PyTorch
+BodySimPy reinforced several engineering-development principles.
 
-## Current Crossmember Surrogate
+Automate repetitive engineering work
 
-The current baseline model represents a simplified automotive body structural crossmember as a uniform thin-walled rectangular hollow section.
+Python provides significantly more value when it controls the complete simulation workflow rather than merely post-processing isolated files.
 
-It is intended to validate the BodySimPy simulation workflow and solver automation architecture rather than reproduce a production vehicle body structure.
+Validate numerical models
 
-### Current assumptions
+Finite-element output should not be accepted only because a solver completed successfully. Analytical references, mesh studies, trend checks and explicit assumptions are essential.
 
-- uniform prismatic cross-section
-- linear-elastic isotropic material
-- idealized cantilever boundary condition
-- transverse point loading
-- beam-element representation
-- small-deformation structural response
+Separate physics from software infrastructure
 
-### Not currently represented
+Domain models, solver adapters, parsers, analyses and reporting become easier to test when responsibilities are separated.
 
-- stamped sheet-metal geometry
-- local beads or reinforcements
-- joints and spot welds
-- complex vehicle boundary conditions
-- production load cases
-- proprietary vehicle geometry
+Quantify uncertainty rather than hiding it
 
-## Planned Geometry Evolution
+A deterministic baseline gives one answer. Stochastic studies reveal how response distributions change when engineering inputs vary.
 
-The structural representation will evolve incrementally from the validated beam surrogate toward a parameterized thin-walled shell model.
+ML usefulness depends on economics as well as accuracy
 
-Planned parameters include:
+A surrogate is valuable only when its prediction quality, training-data cost, evaluation volume and domain of validity make the trade-off worthwhile.
 
-- wall thickness
-- section depth
-- flange width
-- local reinforcement
-- mesh density
-- joint and spot-weld idealization
+AI output still requires engineering judgement
 
-## Stochastic Engineering
+AI coding tools can accelerate exploration and testing, but physical assumptions, numerical methods and final implementation decisions remain human engineering responsibilities.
 
-BodySimPy includes Monte Carlo uncertainty propagation for selected manufacturing, material and loading parameters.
+Communication is part of engineering
 
-The baseline stochastic study evaluates 500 independently sampled configurations with uncertainty in:
+A technically correct Python workflow is incomplete if its results cannot be communicated clearly to engineers, reviewers and decision-makers.
 
-- wall thickness
-- Young's modulus
-- applied load
+Limitations
 
-Each sampled configuration is evaluated using automated CalculiX static and modal analyses.
+BodySimPy is a portfolio and engineering-method development project. Its results must be interpreted within the assumptions of the implemented model.
 
-Reported quantities include:
+Current limitations include:
 
-- response mean and standard deviation
-- 5th and 95th percentiles
-- stress-threshold exceedance fraction
-- mode-1 frequency variation
-- correlation analysis
-- standardized linear sensitivity coefficients
+the structural geometry is a simplified crossmember surrogate rather than a production body-in-white model;
+beam idealization does not represent detailed shell geometry, spot welds, adhesives, joints, local stamped features or contact;
+materials are currently represented using simplified linear-elastic isotropic behaviour;
+boundary conditions and loads are idealized;
+finite-element validation is primarily against analytical mechanics rather than physical vehicle-test data;
+numerical agreement with the analytical surrogate does not constitute validation of a real automotive structure;
+stochastic input distributions are study assumptions rather than measured manufacturing distributions;
+sampled threshold-exceedance fractions are not real-world failure probabilities;
+simple correlation and regression sensitivity metrics are screening tools rather than full global sensitivity analysis;
+the initial fatigue model uses simplified S-N and Palmgren-Miner damage assumptions;
+fatigue calculations do not yet model weld classes, notch effects, rainflow counting, mean-stress correction, multiaxial fatigue, low-cycle fatigue or crack growth;
+the PyTorch surrogate reproduces the underlying CalculiX model and cannot improve the physical fidelity of its training labels;
+ML accuracy has only been demonstrated inside the sampled parameter domain;
+surrogate predictions outside that domain should not be treated as validated extrapolation;
+runtime comparisons depend on hardware, solver settings and benchmarking methodology;
+statistical outlier detection in the QA workflow is a screening heuristic;
+Simulation QA statuses support engineering review and do not replace engineering sign-off;
+AI-assisted development tools may propose incorrect code or engineering assumptions and therefore require human validation.
 
-The stochastic model is intended as an engineering uncertainty study for the simplified structural surrogate and does not represent production vehicle reliability.
+These limitations are intentionally documented because acknowledging model boundaries is part of responsible engineering analysis.
 
+Future Development
 
-## Fatigue Assessment
+Potential extensions include:
 
-BodySimPy includes an initial stress-life fatigue assessment module based on a power-law S-N model and linear Palmgren-Miner cumulative damage.
+shell-element automotive structural models;
+spot-weld and adhesive-joint representation;
+additional static and dynamic load cases;
+geometry import and richer meshing workflows;
+experimental or high-fidelity reference validation;
+nonlinear material behaviour;
+buckling analysis;
+transient structural dynamics;
+rainflow cycle counting;
+mean-stress corrections;
+welded-joint fatigue classes;
+global sensitivity analysis;
+correlated manufacturing uncertainty;
+optimization loops;
+uncertainty-aware ML surrogates;
+automatic model-domain checking before surrogate inference;
+richer simulation QA tooling;
+expanded CLI orchestration;
+interactive engineering dashboards.
 
-The module evaluates constant-amplitude loading blocks and reports:
+Quick Start
 
-- predicted cycles to failure for each stress amplitude
-- individual Miner damage contributions
-- cumulative damage fraction
-- estimated repeated-spectrum life
-- critical loading block
+Clone the repository:
 
-The current fatigue model is intended for workflow development and engineering-method demonstration. Example S-N parameters are generic and are not representative of proprietary vehicle material or joint durability data.
+git clone https://github.com/savbcar/BodySimPy.git
+cd BodySimPy
 
-### Current limitations
+Create and activate a virtual environment:
 
-The initial implementation does not yet include:
+python3.11 -m venv .venv
+source .venv/bin/activate
 
-- rainflow counting
-- mean-stress corrections
-- weld-class fatigue curves
-- notch effects
-- multiaxial fatigue
-- low-cycle fatigue
-- crack-growth modelling
+Upgrade pip:
 
-## PyTorch Structural Surrogate
+python -m pip install --upgrade pip
 
-BodySimPy includes a feed-forward neural-network surrogate trained on a six-dimensional CalculiX design dataset.
+Install BodySimPy and development dependencies:
 
-### Inputs
+python -m pip install -e ".[dev]"
 
-- wall thickness
-- section height
-- section width
-- Young's modulus
-- material density
-- applied tip force
+Install CalculiX on Ubuntu / WSL:
 
-### Predicted responses
+sudo apt update
+sudo apt install calculix-ccx
 
-- maximum axial stress
-- tip displacement
-- mode-1 natural frequency
+Run the quality gate:
 
-The training dataset is generated using Latin Hypercube sampling across a bounded engineering design space and evaluated using automated static and modal CalculiX analyses.
+ruff format --check .
+ruff check .
+mypy src
+python -m pytest
 
-The dataset is separated into training, validation and held-out test subsets. Input and target normalization statistics are fitted exclusively on the training subset.
+Explore the CLI:
 
-Training includes validation monitoring, early stopping and best-model checkpointing.
+bodysim --help
+Project Status
 
-The surrogate is intended for interpolation within the sampled design space and does not replace finite-element validation outside that domain.
+BodySimPy is under active development as a structural CAE and engineering-software portfolio project.
 
-## Simulation QA Agent
+The focus is on:
 
-BodySimPy includes a deterministic simulation-quality-assurance agent
-that orchestrates validated analysis tools after a structural simulation
-completes.
+reproducibility, validation, automation, explicit assumptions and engineering interpretation.
 
-Depending on available metadata, the agent can:
+License
 
-- verify solver completion;
-- inspect simulation logs;
-- compare structural responses with a baseline;
-- check supplied stress thresholds;
-- detect excessive modal-frequency shifts;
-- screen results for statistical outliers;
-- produce a human-readable engineering summary.
-
-The agent does not independently generate engineering truth. Its role is
-to select and coordinate deterministic tools whose outputs remain
-testable and reviewable.
-
-See [`docs/simulation_qa_agent.md`](docs/simulation_qa_agent.md) for the
-workflow and limitations.
+MIT License.