From 04616cdeb34cff95496221754fe100f86518e153 Mon Sep 17 00:00:00 2001
From: sbosse <sbosse@uni-bremen.de>
Date: Mon, 15 Sep 2025 09:45:45 +0200
Subject: [PATCH] Mon 15 Sep 09:43:56 CEST 2025

---
 README.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 133 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 15808ad..5b5f085 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,41 @@ python2 $TOP/src/main.py ParamJSON/simndt_paramas_alu_hole_20mm.json
 
 ## JSON Format
 
+### Material Libarary
+
+All materials are labelled with an integer index number (0, positive) and a name. The simulation set-up uses only the index number of a material:
+
+Note: The included material list determines the simulation model with respect to minimal grid distance and time step distance. Therefore, include only materials used in this simulation!
+
+1. Pre-defined from built-in material library:
+
+```
+  "Materials": [
+    {
+      "Name": "aluminium",
+      "Label": 0
+    },
+    {
+      "Name": "air",
+      "Label": 160
+    }
+  ]
+```
+
+2. User-defined by providing material parameters (Rho: density, VL/VT: long. and transv. velocities in m/s):
+
+```
+  "Materials": [
+    {
+      "Name": "mysteel",
+      "Label": 130,
+      "VL": 5850,
+      "VT": 3220,
+      "Rho": 7800      
+    },
+
+```
+
 ### Import
 
 #### Material
@@ -69,16 +104,60 @@ Exports material matrix
 
 `enableMaterial:true,Material:XX`
 
-- Iabs: Material label matrix w/o boundaries, front-end
-- Im: Material label matrix with boundaries (same size as field matrix), front-end
-- RV: Rho,VT,VL material matrix set, back-end (engine)
-- RC: Rho,C11,.. material matrix set, back-end (engine)
+- *Iabs*: Material label matrix w/o boundaries, front-end
+- *Im*: Material label matrix with boundaries (same size as field matrix), front-end
+- *RV*: Rho,VT,VL material matrix set, back-end (engine)
+- *RC*: Rho,C11,.. material matrix set, back-end (engine)
+
+#### Signals
 
 `enableSignals:true,Field:XX`
 
 - Export sensor signals (derived from Field XX)
 
-Fields: "Vx","Vy","[Vx,Vy]","Txx","Txy","Tyy","[Txx:Txy:Tyy]","Dx","Dy","[Dx,Dy]","SV"
+- Fields: "Vx","Vy","[Vx,Vy]","Txx","Txy","Tyy","[Txx:Txy:Tyy]","Dx","Dy","[Dx,Dy]","SV"
+
+
+#### Sensor Placement
+
+- Paramters (margin offsets and delta increment): [ox,oy,dx,dy]
+- Sensor matrix shape (number of columns and rows): [sx,sy]
+- Default: 
+
+```
+ox=dx=round(xn/(sx+1.0))
+oy=dy=round(yn/(sy+1.0))
+for x in range(0,sx):
+  for y in range(0,sy):
+    S[y,x]=D[oy+y*dy,ox+x*dx]
+```
+
+- User setting: 
+
+```
+  "sensorPlacement":[ox,dx,oy,dy],
+  "sensorShape":[sx,sy]
+```
+
+All parameter values in grid coordindates! 
+E.g., plate 500x500, 1mm grid distance, but field grid is 187x187 points (depends on other simulation and material settings)! 
+
+
+#### Output Formats
+
+1. numpy (enableNumPy=true), 2-dim (one file per time step) or 3-dim (enableVolume=true)
+2. csv (only single sensor signals, no 2-dim fields), one row per time step
+
+#### Field
+
+- Tension Txx, Txy, Tyy
+- Velocity Vx, Vy
+- Displacement Dx, Dy
+- SV
+
+#### Example Sensor Field
+
+- Optional: The material grid is exported (Rho, VL, VT), too
 
 ```
   "Export": {
@@ -92,6 +171,7 @@ Fields: "Vx","Vy","[Vx,Vy]","Txx","Txy","Tyy","[Txx:Txy:Tyy]","Dx","Dy","[Dx,Dy]
     "Material": "RV",
     "enableFields": false,
     "enableNumPy": true,
+    "enableCsv": true,
     "enableSignals": true,
     "enableImages": false,
     "enableMaterial": true,
@@ -103,3 +183,51 @@ Fields: "Vx","Vy","[Vx,Vy]","Txx","Txy","Tyy","[Txx:Txy:Tyy]","Dx","Dy","[Dx,Dy]
   }
 ```
 
+#### Example Single Sensor
+
+Note: The sensor settings have no inmpact on the simulation model and the simulation, it is just a field selection rule.
+
+- sensor position ist (56,180) mm
+- more than one sensor can be sampled (saved)
+
+```
+  "Export": {
+    "Step": 20,
+    "Save_filepath": "./data",
+    "Filename": "fields-sensor-56-180",
+    "Field": "Txx",
+    "enableFields": false,
+    "enableNumPy": false,
+    "enableCsv": true,
+    "enableSignals": true,
+    "enableImages": false,
+    "enableVolume": true,
+    "enableView": false,
+    "sensorShape": [1,1],
+    "sensorPlacement": [56,0,180,0],
+    "sensorSize": 0
+  }
+```
+
+### Simulation
+
+
+- dx and dt are optional and set static simulation constraints and must be lower than computed minimal req. dx/dt
+- Entire simulation time in Seconds
+- Maximum frequency to be sampled in Hz (minimum value is given by the stimulus base frequency and time step)
+- Point cycle sets the snapshot interval saving field (sensor) values, i.e., each PointCycle step
+
+```
+  "Simulation": {
+    "PointCycle": 10,
+    "SimulationTime": 150e-6,
+    "TimeScale": 1.0,
+    "MaxFreq": 120000.0,
+    "Order": 2,
+    "Device":"CPU",
+    "dx" : 0.001,
+    "dt" : 1e-7
+  },
+```
+
+