feat: add PyTorch structural surrogate

.github/workflows/ci.yml

@@ -35,6 +35,11 @@ jobs:
       - name: Upgrade pip
         run: python -m pip install --upgrade pip
 
+              - name: Install PyTorch
+        run: >
+          python -m pip install torch
+          --index-url https://download.pytorch.org/whl/cpu
+
       - name: Install CalculiX
         run: |
           sudo apt-get update

.gitignore

@@ -225,6 +225,9 @@ __pycache__/
 # Virtual environment
 .venv/
 
+# ML model checkpoints
+models/checkpoints/
+
 # Testing
 .pytest_cache/
 .coverage

README.md

@@ -136,4 +136,31 @@ The initial implementation does not yet include:
 - notch effects
 - multiaxial fatigue
 - low-cycle fatigue
-- crack-growth modelling
+- crack-growth modelling
+
+## PyTorch Structural Surrogate
+
+BodySimPy includes a feed-forward neural-network surrogate trained on a six-dimensional CalculiX design dataset.
+
+### Inputs
+
+- wall thickness
+- section height
+- section width
+- Young's modulus
+- material density
+- applied tip force
+
+### Predicted responses
+
+- maximum axial stress
+- tip displacement
+- mode-1 natural frequency
+
+The training dataset is generated using Latin Hypercube sampling across a bounded engineering design space and evaluated using automated static and modal CalculiX analyses.
+
+The dataset is separated into training, validation and held-out test subsets. Input and target normalization statistics are fitted exclusively on the training subset.
+
+Training includes validation monitoring, early stopping and best-model checkpointing.
+
+The surrogate is intended for interpolation within the sampled design space and does not replace finite-element validation outside that domain.

docs/validation/ml_test_metrics.csv

@@ -0,0 +1,4 @@
+response,mae,rmse,unit,mape_percent
+max_stress,1.9490350221438695,2.932099727218547,MPa,1.0589989299689422
+tip_deflection,0.18823362033881488,0.23935947693489001,mm,1.2683177190784598
+mode_1_frequency,0.18998264970865583,0.23496431869832404,Hz,0.39162889707918835

docs/validation/ml_test_predictions.csv

@@ -0,0 +1,76 @@
+dataset_index,fea_stress_mpa,predicted_stress_mpa,stress_error_percent,fea_deflection_mm,predicted_deflection_mm,deflection_error_percent,fea_mode_1_hz,predicted_mode_1_hz,frequency_error_percent
+42,274.448,272.13121021255654,0.8441634799464595,28.65977,28.626280741528284,0.11685110687112067,40.25603,40.214920003300534,0.10212133859068655
+122,149.726,150.37295949221573,0.4320956228148236,12.55155,12.55032835153552,0.009733048623324862,51.24648,51.448913689454734,0.3950196958985984
+17,129.528,128.30799269712094,0.9418869301456559,9.737117999999999,9.813152064206239,0.7808682631374104,58.3487,58.48410556354259,0.23206269127262613
+167,141.19,139.708068538925,1.0496008648452495,11.12311,11.222740169858184,0.8957042576957763,56.66618,56.65204309250483,0.024947698071696476
+297,106.189,104.71795467386846,1.385308578225181,7.358541,7.087176196197982,3.6877528276599616,58.67287,58.99222490194318,0.5442973932299178
+309,197.111,200.4860308954336,1.712248882829271,16.78299,17.30556942066072,3.1137444559087517,50.81534,50.28339202023226,1.0468255841006593
+76,148.075,146.46737102704878,1.085685614013982,12.96576,12.723348811011167,1.8696257603783577,48.61301,48.78898020054705,0.36198170108587946
+313,130.024,129.76400711091839,0.19995761481082502,14.580070000000001,14.569931488331855,0.06953678321259889,40.96967,41.08347741534639,0.27778455463855617
+296,136.049,134.58927938411748,1.072937409229407,9.990808,9.92060088733867,0.7027170641386475,59.21533,59.284097706745854,0.11613159421023628
+208,139.017,137.5602948458969,1.0478611638167277,13.25902,13.219076662222411,0.30125407290725686,46.81396,47.244874046743355,0.920481939027063
+325,128.214,126.38690881913325,1.4250325088264526,9.70662,9.59750402573519,1.124139754773625,57.60937,58.05981301578479,0.7818919314423887
+31,339.243,342.5390047921197,0.9715763603433945,30.927889999999998,31.306249410860353,1.2233599216123519,46.23214,46.473090696943764,0.5211757382283471
+129,178.66,177.02560240987148,0.9148089052549598,15.42724,15.378379174143106,0.31671786954046577,51.32497,51.268952656498335,0.10914247685223215
+440,334.329,334.71227046839505,0.1146387146777738,37.458909999999996,37.31760874886367,0.3772166652375374,40.7236,40.407508768589295,0.7761868582608176
+105,188.075,184.43881588802657,1.9333691941903148,19.92095,19.85370361024632,0.33756617909126163,39.75445,39.89926561798853,0.364275239598421
+290,227.159,225.35985347308852,0.7920207990488896,18.30562,18.276313023749207,0.16009824442327142,51.1127,51.17278931461073,0.11756239566826894
+267,144.223,148.021632341125,2.633860300454859,14.1373,14.597671530649645,3.2564317843551813,44.58579,44.147606211195814,0.9827879887385389
+398,192.78,191.28761673931072,0.7741380125994856,19.87259,20.00370905137204,0.659798503225,41.8462,41.60971485283626,0.5651293239618909
+212,166.386,166.63320642852736,0.1485740558264248,16.3791,16.108387169762878,1.652794294174414,44.56947,44.7315990745063,0.36376711346645235
+43,132.889,132.00803037314097,0.6629364558834999,9.59169,9.22767730513522,3.79508402445013,56.1129,56.36174203539302,0.4434667169100476
+467,203.259,204.0166041077326,0.3727284438733803,21.00174,21.112740201313805,0.5285285948392962,42.50944,42.7806186921512,0.6379258163626783
+160,160.414,165.50133161337092,3.171376322123334,11.335059999999999,11.535777697680269,1.7707687271198302,59.76948,59.668240997687164,0.16938243784760643
+317,138.883,136.12888755105746,1.9830450443485106,15.559140000000001,15.481741214504785,0.497448994579489,40.76916,40.62381313063999,0.35651180784694
+57,142.15,143.4712291402295,0.9294612312553593,11.26476,11.441895068427597,1.572470859810569,52.98613,52.79743752880044,0.3561167256404008
+279,80.4094,78.60520396645228,2.2437625868962017,5.586346,5.414545443461058,3.0753654811023567,59.48575,59.465718342157906,0.03367471678863712
+23,190.176,191.21617946944917,0.5469562244705759,21.65979,21.939008886378254,1.289111696735071,40.07667,39.97532189563701,0.25288554254380646
+420,130.566,130.57534841791866,0.007159917527267663,10.83774,11.05890548975869,2.040697504818247,50.92668,50.71804841833739,0.4096704942529305
+272,105.678,104.87871440557325,0.7563405764934529,8.140125,8.172602209571147,0.39897679177098805,53.68218,53.53434735601382,0.27538494894615784
+15,103.329,104.58138080583842,1.2120322521638853,7.48595,7.877220105330684,5.2267261380410535,59.16491,59.26153942042988,0.16332217936252696
+432,209.824,210.9694388991427,0.5459046148880408,20.60915,20.66925922310192,0.2916627959033804,43.58569,43.44131692042306,0.3312396329550752
+316,258.888,250.70323224685114,3.16150912871545,22.667820000000003,22.082232657940576,2.583342121383637,51.59212,51.69800696957759,0.20523864802917519
+109,146.11,146.4827141612869,0.25509147990344283,11.4848,11.632117045764494,1.2827132014880003,55.77594,55.62369676875108,0.2729550254983013
+137,116.673,116.67490821102813,0.00163552066727423,8.614212,8.468071587687763,1.6965035491608043,56.46961,56.44972728490281,0.035209584583972546
+190,130.136,130.58445624766284,0.3446058336377653,10.61867,10.83734485008912,2.0593431200811487,52.82385,52.787310135660256,0.06917304274441204
+287,171.461,169.06678367366754,1.3963620452070442,19.644209999999998,19.336859967046127,1.564583319735791,38.64532,39.18606879267061,1.3992607453389247
+451,213.219,211.696750671673,0.713936998263288,21.31171,21.43337545022351,0.5708854438405516,40.9142,41.05166212824357,0.33597657596523883
+16,137.729,139.3202158944519,1.155323783990239,13.3726,13.350812500058627,0.16292643122035777,44.95145,44.804597487366586,0.32669138066384
+300,92.6734,92.74444870928694,0.0766656983416418,7.632664,7.635477177889538,0.03685709065063151,51.25112,51.30159533531011,0.09848630685555912
+240,134.389,134.50813326943097,0.0886480808927555,11.1082,10.970262963471928,1.2417586695240603,52.40608,52.682274018571086,0.5270266705143425
+110,317.101,318.1433705123675,0.32871877173754954,29.11953,29.304247049517578,0.6343407655191378,45.78276,45.77209752863784,0.023289271686896814
+431,195.477,196.0517089456437,0.2940033587806715,14.94727,15.085671157780881,0.9259293354631326,55.70136,55.790945550867214,0.16083189147843563
+195,122.291,121.51822546269568,0.6319144804640668,11.39212,11.349850084436378,0.37104520987860445,44.87243,45.13852455167049,0.5930023216270911
+34,222.919,220.34743127729507,1.1535888473862332,19.77011,19.55820466504549,1.0718470203479413,51.33286,51.33225664822386,0.001175371440701417
+286,208.407,209.54119465043846,0.544220995666392,15.397070000000001,15.693006799362971,1.9220332138710157,57.29776,57.28324584429875,0.025331104917974745
+314,210.637,223.2833300271023,6.003850238610639,14.91733,15.334447176956685,2.7961919254765113,57.82756,57.936387080017326,0.1881924120909263
+458,192.327,192.9411199876968,0.3193103348447158,19.49838,19.84532327902626,1.7793441251337947,43.52351,43.39471385999859,0.29592314590760854
+35,142.191,144.37484714332217,1.535854690748479,13.4156,13.729455921259426,2.3394847883018755,46.5728,46.343395563782934,0.49257170755691443
+333,196.064,198.11009299387388,1.0435842346753428,15.987029999999999,16.105060770833667,0.7382907946858757,53.21741,53.15539713427091,0.11652740283506413
+182,207.879,205.0143490618039,1.3780376748955367,16.78317,16.523423007165135,1.547663479753018,55.88252,56.436428223544944,0.9912012263314972
+49,219.118,220.73533113141198,0.738109663018086,24.312150000000003,24.690950771651636,1.5580718762085357,40.79314,40.55618942763107,0.5808588708026224
+6,269.621,272.28623215678294,0.988510597016896,27.24539,27.430883934694943,0.6808268653704034,43.87272,44.09748970156992,0.5123222393549313
+102,282.157,294.0323087024773,4.208759202315475,22.96308,23.69546823627052,3.1894163860881077,53.47129,53.05083402426985,0.7863209878238522
+175,157.912,155.95812545519587,1.237318598209209,14.383140000000001,14.283375056772945,0.6936242241058346,49.43597,49.332171476145064,0.20996558549358685
+139,171.252,173.85683755258472,1.5210552592581152,16.60204,16.962544777609672,2.17144867504037,43.35496,43.19729048777958,0.3636712205948655
+480,145.159,145.36789473783446,0.1439075343826105,14.7096,14.772963150014558,0.4307605238385706,44.34643,44.760881030543224,0.9345758622356439
+41,174.947,171.77547602598577,1.8128484478237537,14.87771,14.642012777063732,1.5842305229519085,52.43997,52.531335455004545,0.1742286561272674
+366,177.175,173.71115403905495,1.9550421678820602,15.30511,15.172242356885459,0.8681260253244887,49.87935,50.13899321522556,0.5205424995024168
+22,88.7934,88.08407972191466,0.7988434704441277,6.5026839999999995,6.559953894706915,0.8807116370242637,58.65858,58.4011217338076,0.43890981710160937
+275,181.245,181.53888430468845,0.1621475376912211,15.69864,15.79401407635589,0.6075308202232111,50.76481,50.586849282035345,0.3505592121090414
+163,311.733,313.108905044426,0.4413729199109572,35.1699,34.8779923344602,0.8299928789669515,40.51074,40.59294830605589,0.2029296578040529
+320,165.5,166.50066716928754,0.6046327306873309,16.408559999999998,16.37673703199716,0.19394125994506448,43.96808,43.745807448787424,0.5055316293378657
+303,200.948,202.11738011058426,0.5819316990386861,19.799799999999998,19.8606412716678,0.30728225369851386,43.24253,43.278317046805206,0.08275891074181868
+113,104.605,105.20524535424876,0.5738209017243556,7.9322360000000005,8.132726204605714,2.5275370602401854,57.08203,56.99563603441233,0.15135054865370917
+237,158.553,156.50519807068335,1.2915567219268258,12.80154,12.550525737311492,1.9608130169378617,56.85573,57.33666673102755,0.8458896421302613
+396,184.358,179.24355233054473,2.774193509072164,13.472019999999999,13.30089918369176,1.2701941973678785,59.06584,58.718338970125416,0.5883282619439353
+437,230.981,229.18728818868425,0.7765624927226678,19.25119,19.14509642311174,0.5511013962682875,52.46686,52.84333663902092,0.7175513057593341
+491,231.997,232.1199294730686,0.052987527023450706,22.43247,22.4012419211296,0.13920927508384495,45.33662,45.30147994186314,0.07750921470736201
+14,311.583,313.27499583437026,0.543032140511599,32.84355,33.29795345481694,1.3835394006340367,41.40182,41.17748646202045,0.5418446290031547
+141,225.316,223.0130947629142,1.0220779869542416,19.73357,19.458650253397426,1.3931576830881254,50.55017,50.79319102496676,0.48075214181625525
+194,154.633,150.38605108959524,2.7464699710959315,12.03957,11.745071871709811,2.4460851034562547,53.35685,53.482333998997795,0.23517879896919297
+36,205.546,205.32753239157003,0.10628648012122267,18.87922,18.958985697856665,0.42250526164040303,45.91477,45.85656302712764,0.12677178361637295
+97,199.348,198.02348054716083,0.6644257543788581,18.77233,18.55576326150663,1.153648686622111,45.18773,45.35859999609362,0.37813361302641557
+449,238.148,236.60322961255545,0.6486598197106656,23.00238,22.997776400982982,0.020013576929947565,47.17491,46.802399640320125,0.7896366091209752
+461,248.565,247.05387957072725,0.6079377343040014,25.7504,25.822291000318923,0.27918401391404785,42.81855,42.714904810864766,0.24205674674933103
+136,153.611,153.48181621938593,0.08409800119397572,11.40235,11.529262743607545,1.1130402382626692,57.03368,57.22917475817141,0.34277072454629215

pyproject.toml

@@ -31,6 +31,12 @@ dev = [
     "ruff>=0.5",
     "mypy>=1.10",
     "types-PyYAML",
+    "scipy-stubs",
+    "pandas-stubs",
+]
+
+ml = [
+    "torch>=2.7",
 ]
 
 [project.scripts]