perifit 2.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. perifit-2.0.0/PKG-INFO +292 -0
  2. perifit-2.0.0/README.md +253 -0
  3. perifit-2.0.0/perifit/__init__.py +184 -0
  4. perifit-2.0.0/perifit/cli.py +289 -0
  5. perifit-2.0.0/perifit/config.py +87 -0
  6. perifit-2.0.0/perifit/core/__init__.py +90 -0
  7. perifit-2.0.0/perifit/core/local_system.py +218 -0
  8. perifit-2.0.0/perifit/core/local_system_2d.py +149 -0
  9. perifit-2.0.0/perifit/core/moments.py +84 -0
  10. perifit-2.0.0/perifit/core/moments_2d.py +77 -0
  11. perifit-2.0.0/perifit/core/targets.py +122 -0
  12. perifit-2.0.0/perifit/core/targets_2d.py +78 -0
  13. perifit-2.0.0/perifit/core/weights.py +157 -0
  14. perifit-2.0.0/perifit/core/weights_2d.py +120 -0
  15. perifit-2.0.0/perifit/data/__init__.py +0 -0
  16. perifit-2.0.0/perifit/data/test_mesh_cube_1000.csv +1003 -0
  17. perifit-2.0.0/perifit/io/__init__.py +0 -0
  18. perifit-2.0.0/perifit/io/writers.py +533 -0
  19. perifit-2.0.0/perifit/mesh/__init__.py +0 -0
  20. perifit-2.0.0/perifit/mesh/readers.py +399 -0
  21. perifit-2.0.0/perifit/quality/__init__.py +2 -0
  22. perifit-2.0.0/perifit/quality/cleaning.py +58 -0
  23. perifit-2.0.0/perifit/quality/diagnostics.py +67 -0
  24. perifit-2.0.0/perifit.egg-info/PKG-INFO +292 -0
  25. perifit-2.0.0/perifit.egg-info/SOURCES.txt +36 -0
  26. perifit-2.0.0/perifit.egg-info/dependency_links.txt +1 -0
  27. perifit-2.0.0/perifit.egg-info/entry_points.txt +2 -0
  28. perifit-2.0.0/perifit.egg-info/requires.txt +24 -0
  29. perifit-2.0.0/perifit.egg-info/top_level.txt +1 -0
  30. perifit-2.0.0/pyproject.toml +57 -0
  31. perifit-2.0.0/setup.cfg +4 -0
  32. perifit-2.0.0/tests/test_bbpd.py +205 -0
  33. perifit-2.0.0/tests/test_cli.py +47 -0
  34. perifit-2.0.0/tests/test_moments.py +60 -0
  35. perifit-2.0.0/tests/test_nosb.py +145 -0
  36. perifit-2.0.0/tests/test_quality.py +128 -0
  37. perifit-2.0.0/tests/test_weights.py +367 -0
  38. perifit-2.0.0/tests/test_weights_reference.py +578 -0
perifit-2.0.0/PKG-INFO ADDED
@@ -0,0 +1,292 @@
1
+ Metadata-Version: 2.4
2
+ Name: perifit
3
+ Version: 2.0.0
4
+ Summary: Surface correction weights for 3-D peridynamics (bond-based, state-based LPS, and correspondence NOSB-PD) with mesh quality diagnostics
5
+ License: MIT
6
+ Project-URL: Homepage, https://github.com/Hereon-InstituteMS/perifit
7
+ Project-URL: Repository, https://github.com/Hereon-InstituteMS/perifit
8
+ Project-URL: Issues, https://github.com/Hereon-InstituteMS/perifit/issues
9
+ Keywords: peridynamics,surface correction,LPS,NOSB-PD,correspondence,state-based peridynamics,bond-based peridynamics,mesh quality,meshfree,nonlocal mechanics
10
+ Classifier: Development Status :: 5 - Production/Stable
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.9
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Topic :: Scientific/Engineering :: Physics
19
+ Requires-Python: >=3.9
20
+ Description-Content-Type: text/markdown
21
+ Requires-Dist: numpy>=1.24
22
+ Requires-Dist: scipy>=1.10
23
+ Provides-Extra: vtk
24
+ Requires-Dist: pyvista>=0.42; extra == "vtk"
25
+ Provides-Extra: exodus
26
+ Requires-Dist: netCDF4>=1.6; extra == "exodus"
27
+ Provides-Extra: hdf5
28
+ Requires-Dist: h5py>=3.8; extra == "hdf5"
29
+ Provides-Extra: gmsh
30
+ Requires-Dist: meshio>=5.3; extra == "gmsh"
31
+ Provides-Extra: all
32
+ Requires-Dist: pyvista>=0.42; extra == "all"
33
+ Requires-Dist: netCDF4>=1.6; extra == "all"
34
+ Requires-Dist: h5py>=3.8; extra == "all"
35
+ Requires-Dist: meshio>=5.3; extra == "all"
36
+ Provides-Extra: dev
37
+ Requires-Dist: pytest>=7; extra == "dev"
38
+ Requires-Dist: pytest-cov; extra == "dev"
39
+
40
+ # perifit
41
+
42
+ **Surface correction weights for 3-D peridynamics (state-based LPS, bond-based, and correspondence NOSB-PD) with mesh quality diagnostics**
43
+
44
+ [![CI](https://github.com/Hereon-InstituteMS/perifit/actions/workflows/ci.yml/badge.svg)](https://github.com/Hereon-InstituteMS/perifit/actions)
45
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
46
+
47
+ `perifit` computes optimised nodal influence weights that eliminate
48
+ the **surface/boundary effect** in three-dimensional peridynamics.
49
+
50
+ Supported models:
51
+ | Model | CLI flag | Operator rows | Notes |
52
+ |-------|----------|---------------|-------|
53
+ | **OSB-PD** (ordinary state-based, LPS) | `--model osb` | 109 | Poisson-unrestricted |
54
+ | **BB-PD** (bond-based) | `--model bb` | 54 | ν = 1/4 in 3D |
55
+ | **NOSB-PD** (non-ordinary, correspondence) | `--model nosb` | 36 | Material-independent |
56
+
57
+ Provide any 3-D mesh → get per-node weights in formats ready for
58
+ **Peridigm**, **PeriLab**, or generic CSV / DAT / VTK.
59
+
60
+ ---
61
+
62
+ ## Background
63
+
64
+ In peridynamics, nodes near the domain boundary have truncated horizon
65
+ neighbourhoods. This reduces their effective stiffness and causes
66
+ displacement errors that do **not** vanish under mesh refinement at fixed
67
+ horizon-to-spacing ratio *m = δ/Δx* — the so-called *surface effect*.
68
+
69
+ `perifit` implements an operator-matching framework for state-based (LPS), bond-based
70
+ (solid), and correspondence (NOSB-PD) models. For each node, a local overdetermined least-squares
71
+ problem is solved to find a scalar influence weight *wᵢ* such that the
72
+ truncated neighbourhood operators reproduce their full-sphere continuum
73
+ counterparts. The per-node weights are coupled through a global sparse
74
+ linear system solved by BiCGSTAB.
75
+
76
+ > **The weights are purely geometric.**
77
+ > Material constants (*G* for state-based, *c* for bond-based) appear as
78
+ > common prefactors in both the local ML matrix and the analytical targets
79
+ > and cancel exactly after per-row normalisation. For the correspondence
80
+ > model, the operator rows are material-independent by construction (no
81
+ > radial singularity, no constitutive constants). Consequently, *E*, *ν*,
82
+ > and any other material constant are **not required** — only the mesh
83
+ > geometry and the horizon matter.
84
+
85
+ ---
86
+
87
+ ## Results
88
+
89
+ ### Convergence and preprocessing time (state-based LPS)
90
+
91
+ ![Convergence and timing](docs/images/readme_convergence_timing.png)
92
+
93
+ **(a)** Displacement error convergence for the **state-based LPS** model on a unit bar under uniaxial tension (*m* = 3).
94
+ The corrected weights (solid lines) recover first-order convergence across all
95
+ Poisson ratios, while standard LPS (dashed) stagnates due to the surface effect.
96
+ **(b)** Weight computation time scales near-linearly with the number of nodes.
97
+
98
+ ### Mesh quality diagnostics (state-based LPS)
99
+
100
+ ![Mesh cleaning](docs/images/readme_cleaning.png)
101
+
102
+ **(a)** Rocker-arm geometry (1,699 nodes) colored by **LPS** weight values.
103
+ **(b)** Outlier nodes flagged by the built-in diagnostics (2*σ* threshold).
104
+ **(c)** Cleaned mesh after removing the 69 flagged nodes — weight distribution
105
+ is now uniform and well-conditioned.
106
+
107
+ ---
108
+
109
+ ## Installation
110
+
111
+ ```bash
112
+ pip install perifit
113
+ ```
114
+
115
+ With optional dependencies for specific mesh formats:
116
+
117
+ ```bash
118
+ pip install "perifit[hdf5]" # PeriLab HDF5 output
119
+ pip install "perifit[exodus]" # Exodus mesh input
120
+ pip install "perifit[gmsh]" # Gmsh / Abaqus / VTU input
121
+ pip install "perifit[all]" # everything
122
+ ```
123
+
124
+ ---
125
+
126
+ ## Quick start
127
+
128
+ ### Built-in demo (no mesh needed)
129
+
130
+ ```bash
131
+ perifit --demo
132
+ ```
133
+
134
+ Runs on the bundled 1000-node structured cube mesh and writes
135
+ `csv`, `dat`, and `vtk` output to `./perifit_output/`.
136
+
137
+ ### Python API
138
+
139
+ ```python
140
+ import numpy as np
141
+ from perifit import compute_weights, write_weights
142
+
143
+ # Build your mesh (or load it — see below)
144
+ dx = 0.05
145
+ xs = np.arange(dx / 2, 1.0, dx)
146
+ gx, gy, gz = np.meshgrid(xs, xs, xs, indexing='ij')
147
+ coords = np.column_stack([gx.ravel(), gy.ravel(), gz.ravel()])
148
+
149
+ # OSB-PD / LPS (default model is "bb"):
150
+ volumes = np.full(len(coords), dx**3)
151
+ weights = compute_weights(coords, volumes, horizon=3 * dx, model='osb')
152
+
153
+ # BB-PD:
154
+ weights = compute_weights(coords, volumes, horizon=3 * dx, model='bb')
155
+
156
+ # NOSB-PD (material-independent):
157
+ weights = compute_weights(coords, volumes, horizon=3 * dx, model='nosb')
158
+
159
+ # Export to any format
160
+ write_weights(
161
+ coords, volumes, weights,
162
+ outdir='./output',
163
+ formats=['csv', 'vtk', 'peridigm', 'perilab'],
164
+ )
165
+ ```
166
+
167
+ ### Load from a mesh file
168
+
169
+ ```python
170
+ from perifit import load_mesh, compute_weights, write_weights
171
+
172
+ # Supported: .csv .dat .txt .npy .npz .vtk .vtu .exo .g .msh .inp
173
+ coords, volumes = load_mesh('my_mesh.exo')
174
+
175
+ weights = compute_weights(coords, volumes, horizon=3 * dx, model='osb')
176
+
177
+ write_weights(coords, volumes, weights,
178
+ outdir='./weights',
179
+ formats=['peridigm', 'perilab', 'csv'])
180
+ ```
181
+
182
+ ### Mesh quality diagnostics
183
+
184
+ ```python
185
+ from perifit import compute_weights
186
+ from perifit.quality import diagnose_weights, clean_mesh
187
+
188
+ weights = compute_weights(coords, volumes, horizon=delta)
189
+
190
+ # Diagnose: flag negative weights and statistical outliers
191
+ diag = diagnose_weights(weights, threshold_sigma=2.0)
192
+ print(diag.summary)
193
+
194
+ # Clean: remove flagged nodes
195
+ result = clean_mesh(coords, volumes, weights, threshold_sigma=2.0)
196
+ print(f"Removed {result.original_n - result.cleaned_n} nodes")
197
+ ```
198
+
199
+ ### Command-line interface
200
+
201
+ ```bash
202
+ # OSB-PD / LPS
203
+ perifit --mesh nodes.csv --model osb
204
+
205
+ # BB-PD (default)
206
+ perifit --mesh nodes.csv --model bb
207
+
208
+ # NOSB-PD (material-independent weights)
209
+ perifit --mesh nodes.csv --model nosb
210
+
211
+ # Specify horizon-to-spacing ratio (default is 3)
212
+ perifit --mesh nodes.csv --m-ratio 4 --output csv,vtk
213
+
214
+ # Provide the horizon explicitly instead
215
+ perifit --mesh solid.exo --horizon 0.005 --output peridigm
216
+
217
+ # Diagnose mesh quality after computing weights
218
+ perifit --mesh cube.csv --diagnose
219
+
220
+ # Clean mesh (remove negative/outlier weight nodes)
221
+ perifit --mesh cube.csv --clean --threshold-sigma 2.0
222
+
223
+ # Show all options
224
+ perifit --help
225
+ ```
226
+
227
+ ---
228
+
229
+ ## Supported input formats
230
+
231
+ | Extension | Format | Notes |
232
+ |-----------|--------|-------|
233
+ | `.csv`, `.txt`, `.dat` | Plain text | Columns: x, y, z[, volume] |
234
+ | `.npy` | NumPy array | Shape (N, 3) or (N, 4) |
235
+ | `.npz` | NumPy archive | Keys: `coords`[, `volumes`] |
236
+ | `.vtk` | Legacy VTK ASCII | Unstructured or structured |
237
+ | `.vtu` | VTK XML | Requires `pyvista` or `meshio` |
238
+ | `.exo`, `.g` | Exodus II | Requires `netCDF4` or `meshio` |
239
+ | `.msh` | Gmsh v2/v4 | Requires `meshio` |
240
+ | `.inp` | Abaqus | Requires `meshio` |
241
+
242
+ ## Supported output formats
243
+
244
+ | Format | Description |
245
+ |--------|-------------|
246
+ | `csv` | `node_id, x, y, z, volume, weight` |
247
+ | `dat` | Space-delimited text |
248
+ | `vtk` | Legacy ASCII VTK for ParaView / VisIt |
249
+ | `peridigm` | Text mesh + weight CSV + YAML input snippet |
250
+ | `perilab` | HDF5 mesh with `Nodal_Surface_Correction` field + YAML snippet |
251
+
252
+ ---
253
+
254
+ ## Applying the weights in your solver
255
+
256
+ The bond-averaged influence weight is
257
+
258
+ ```
259
+ w̄ᵢⱼ = (wᵢ + wⱼ) / 2
260
+ ```
261
+
262
+ Replace every occurrence of the unit influence function `ω(ξ) = 1`
263
+ in your PD discretisation with `w̄ᵢⱼ`. The Peridigm and PeriLab
264
+ output files include a YAML template showing exactly where to hook in
265
+ the field.
266
+
267
+ ---
268
+
269
+ ## Auto-inference of dx, volumes, and horizon
270
+
271
+ The nodal spacing `dx` is always estimated automatically as the
272
+ **median nearest-neighbour distance** (KD-tree, O(N log N)).
273
+ This is used to:
274
+
275
+ 1. Set nodal volumes to `dx³` when not provided.
276
+ 2. Compute the horizon as `delta = m_ratio × dx` when `--horizon` is not given.
277
+ 3. Check consistency when **both** `--horizon` and `--m-ratio` are supplied.
278
+
279
+ ### Input modes
280
+
281
+ | `--horizon` | `--m-ratio` | Behaviour |
282
+ |-------------|-------------|-----------|
283
+ | not given | not given | horizon = 3 × dx (default m=3) |
284
+ | not given | given | horizon = m_ratio × dx |
285
+ | given | not given | horizon used directly |
286
+ | given | given | horizon used; **warning** if inconsistent with m_ratio × dx |
287
+
288
+ ---
289
+
290
+ ## License
291
+
292
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,253 @@
1
+ # perifit
2
+
3
+ **Surface correction weights for 3-D peridynamics (state-based LPS, bond-based, and correspondence NOSB-PD) with mesh quality diagnostics**
4
+
5
+ [![CI](https://github.com/Hereon-InstituteMS/perifit/actions/workflows/ci.yml/badge.svg)](https://github.com/Hereon-InstituteMS/perifit/actions)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
7
+
8
+ `perifit` computes optimised nodal influence weights that eliminate
9
+ the **surface/boundary effect** in three-dimensional peridynamics.
10
+
11
+ Supported models:
12
+ | Model | CLI flag | Operator rows | Notes |
13
+ |-------|----------|---------------|-------|
14
+ | **OSB-PD** (ordinary state-based, LPS) | `--model osb` | 109 | Poisson-unrestricted |
15
+ | **BB-PD** (bond-based) | `--model bb` | 54 | ν = 1/4 in 3D |
16
+ | **NOSB-PD** (non-ordinary, correspondence) | `--model nosb` | 36 | Material-independent |
17
+
18
+ Provide any 3-D mesh → get per-node weights in formats ready for
19
+ **Peridigm**, **PeriLab**, or generic CSV / DAT / VTK.
20
+
21
+ ---
22
+
23
+ ## Background
24
+
25
+ In peridynamics, nodes near the domain boundary have truncated horizon
26
+ neighbourhoods. This reduces their effective stiffness and causes
27
+ displacement errors that do **not** vanish under mesh refinement at fixed
28
+ horizon-to-spacing ratio *m = δ/Δx* — the so-called *surface effect*.
29
+
30
+ `perifit` implements an operator-matching framework for state-based (LPS), bond-based
31
+ (solid), and correspondence (NOSB-PD) models. For each node, a local overdetermined least-squares
32
+ problem is solved to find a scalar influence weight *wᵢ* such that the
33
+ truncated neighbourhood operators reproduce their full-sphere continuum
34
+ counterparts. The per-node weights are coupled through a global sparse
35
+ linear system solved by BiCGSTAB.
36
+
37
+ > **The weights are purely geometric.**
38
+ > Material constants (*G* for state-based, *c* for bond-based) appear as
39
+ > common prefactors in both the local ML matrix and the analytical targets
40
+ > and cancel exactly after per-row normalisation. For the correspondence
41
+ > model, the operator rows are material-independent by construction (no
42
+ > radial singularity, no constitutive constants). Consequently, *E*, *ν*,
43
+ > and any other material constant are **not required** — only the mesh
44
+ > geometry and the horizon matter.
45
+
46
+ ---
47
+
48
+ ## Results
49
+
50
+ ### Convergence and preprocessing time (state-based LPS)
51
+
52
+ ![Convergence and timing](docs/images/readme_convergence_timing.png)
53
+
54
+ **(a)** Displacement error convergence for the **state-based LPS** model on a unit bar under uniaxial tension (*m* = 3).
55
+ The corrected weights (solid lines) recover first-order convergence across all
56
+ Poisson ratios, while standard LPS (dashed) stagnates due to the surface effect.
57
+ **(b)** Weight computation time scales near-linearly with the number of nodes.
58
+
59
+ ### Mesh quality diagnostics (state-based LPS)
60
+
61
+ ![Mesh cleaning](docs/images/readme_cleaning.png)
62
+
63
+ **(a)** Rocker-arm geometry (1,699 nodes) colored by **LPS** weight values.
64
+ **(b)** Outlier nodes flagged by the built-in diagnostics (2*σ* threshold).
65
+ **(c)** Cleaned mesh after removing the 69 flagged nodes — weight distribution
66
+ is now uniform and well-conditioned.
67
+
68
+ ---
69
+
70
+ ## Installation
71
+
72
+ ```bash
73
+ pip install perifit
74
+ ```
75
+
76
+ With optional dependencies for specific mesh formats:
77
+
78
+ ```bash
79
+ pip install "perifit[hdf5]" # PeriLab HDF5 output
80
+ pip install "perifit[exodus]" # Exodus mesh input
81
+ pip install "perifit[gmsh]" # Gmsh / Abaqus / VTU input
82
+ pip install "perifit[all]" # everything
83
+ ```
84
+
85
+ ---
86
+
87
+ ## Quick start
88
+
89
+ ### Built-in demo (no mesh needed)
90
+
91
+ ```bash
92
+ perifit --demo
93
+ ```
94
+
95
+ Runs on the bundled 1000-node structured cube mesh and writes
96
+ `csv`, `dat`, and `vtk` output to `./perifit_output/`.
97
+
98
+ ### Python API
99
+
100
+ ```python
101
+ import numpy as np
102
+ from perifit import compute_weights, write_weights
103
+
104
+ # Build your mesh (or load it — see below)
105
+ dx = 0.05
106
+ xs = np.arange(dx / 2, 1.0, dx)
107
+ gx, gy, gz = np.meshgrid(xs, xs, xs, indexing='ij')
108
+ coords = np.column_stack([gx.ravel(), gy.ravel(), gz.ravel()])
109
+
110
+ # OSB-PD / LPS (default model is "bb"):
111
+ volumes = np.full(len(coords), dx**3)
112
+ weights = compute_weights(coords, volumes, horizon=3 * dx, model='osb')
113
+
114
+ # BB-PD:
115
+ weights = compute_weights(coords, volumes, horizon=3 * dx, model='bb')
116
+
117
+ # NOSB-PD (material-independent):
118
+ weights = compute_weights(coords, volumes, horizon=3 * dx, model='nosb')
119
+
120
+ # Export to any format
121
+ write_weights(
122
+ coords, volumes, weights,
123
+ outdir='./output',
124
+ formats=['csv', 'vtk', 'peridigm', 'perilab'],
125
+ )
126
+ ```
127
+
128
+ ### Load from a mesh file
129
+
130
+ ```python
131
+ from perifit import load_mesh, compute_weights, write_weights
132
+
133
+ # Supported: .csv .dat .txt .npy .npz .vtk .vtu .exo .g .msh .inp
134
+ coords, volumes = load_mesh('my_mesh.exo')
135
+
136
+ weights = compute_weights(coords, volumes, horizon=3 * dx, model='osb')
137
+
138
+ write_weights(coords, volumes, weights,
139
+ outdir='./weights',
140
+ formats=['peridigm', 'perilab', 'csv'])
141
+ ```
142
+
143
+ ### Mesh quality diagnostics
144
+
145
+ ```python
146
+ from perifit import compute_weights
147
+ from perifit.quality import diagnose_weights, clean_mesh
148
+
149
+ weights = compute_weights(coords, volumes, horizon=delta)
150
+
151
+ # Diagnose: flag negative weights and statistical outliers
152
+ diag = diagnose_weights(weights, threshold_sigma=2.0)
153
+ print(diag.summary)
154
+
155
+ # Clean: remove flagged nodes
156
+ result = clean_mesh(coords, volumes, weights, threshold_sigma=2.0)
157
+ print(f"Removed {result.original_n - result.cleaned_n} nodes")
158
+ ```
159
+
160
+ ### Command-line interface
161
+
162
+ ```bash
163
+ # OSB-PD / LPS
164
+ perifit --mesh nodes.csv --model osb
165
+
166
+ # BB-PD (default)
167
+ perifit --mesh nodes.csv --model bb
168
+
169
+ # NOSB-PD (material-independent weights)
170
+ perifit --mesh nodes.csv --model nosb
171
+
172
+ # Specify horizon-to-spacing ratio (default is 3)
173
+ perifit --mesh nodes.csv --m-ratio 4 --output csv,vtk
174
+
175
+ # Provide the horizon explicitly instead
176
+ perifit --mesh solid.exo --horizon 0.005 --output peridigm
177
+
178
+ # Diagnose mesh quality after computing weights
179
+ perifit --mesh cube.csv --diagnose
180
+
181
+ # Clean mesh (remove negative/outlier weight nodes)
182
+ perifit --mesh cube.csv --clean --threshold-sigma 2.0
183
+
184
+ # Show all options
185
+ perifit --help
186
+ ```
187
+
188
+ ---
189
+
190
+ ## Supported input formats
191
+
192
+ | Extension | Format | Notes |
193
+ |-----------|--------|-------|
194
+ | `.csv`, `.txt`, `.dat` | Plain text | Columns: x, y, z[, volume] |
195
+ | `.npy` | NumPy array | Shape (N, 3) or (N, 4) |
196
+ | `.npz` | NumPy archive | Keys: `coords`[, `volumes`] |
197
+ | `.vtk` | Legacy VTK ASCII | Unstructured or structured |
198
+ | `.vtu` | VTK XML | Requires `pyvista` or `meshio` |
199
+ | `.exo`, `.g` | Exodus II | Requires `netCDF4` or `meshio` |
200
+ | `.msh` | Gmsh v2/v4 | Requires `meshio` |
201
+ | `.inp` | Abaqus | Requires `meshio` |
202
+
203
+ ## Supported output formats
204
+
205
+ | Format | Description |
206
+ |--------|-------------|
207
+ | `csv` | `node_id, x, y, z, volume, weight` |
208
+ | `dat` | Space-delimited text |
209
+ | `vtk` | Legacy ASCII VTK for ParaView / VisIt |
210
+ | `peridigm` | Text mesh + weight CSV + YAML input snippet |
211
+ | `perilab` | HDF5 mesh with `Nodal_Surface_Correction` field + YAML snippet |
212
+
213
+ ---
214
+
215
+ ## Applying the weights in your solver
216
+
217
+ The bond-averaged influence weight is
218
+
219
+ ```
220
+ w̄ᵢⱼ = (wᵢ + wⱼ) / 2
221
+ ```
222
+
223
+ Replace every occurrence of the unit influence function `ω(ξ) = 1`
224
+ in your PD discretisation with `w̄ᵢⱼ`. The Peridigm and PeriLab
225
+ output files include a YAML template showing exactly where to hook in
226
+ the field.
227
+
228
+ ---
229
+
230
+ ## Auto-inference of dx, volumes, and horizon
231
+
232
+ The nodal spacing `dx` is always estimated automatically as the
233
+ **median nearest-neighbour distance** (KD-tree, O(N log N)).
234
+ This is used to:
235
+
236
+ 1. Set nodal volumes to `dx³` when not provided.
237
+ 2. Compute the horizon as `delta = m_ratio × dx` when `--horizon` is not given.
238
+ 3. Check consistency when **both** `--horizon` and `--m-ratio` are supplied.
239
+
240
+ ### Input modes
241
+
242
+ | `--horizon` | `--m-ratio` | Behaviour |
243
+ |-------------|-------------|-----------|
244
+ | not given | not given | horizon = 3 × dx (default m=3) |
245
+ | not given | given | horizon = m_ratio × dx |
246
+ | given | not given | horizon used directly |
247
+ | given | given | horizon used; **warning** if inconsistent with m_ratio × dx |
248
+
249
+ ---
250
+
251
+ ## License
252
+
253
+ MIT — see [LICENSE](LICENSE).