tpmslab 0.3.0__tar.gz

tpmslab-0.3.0/.zenodo.json

@@ -0,0 +1,24 @@
+{
+  "title": "TPMS Lab v0.3.0",
+  "version": "0.3.0",
+  "upload_type": "software",
+  "description": "Python package for graded complementary solid and pore-fluid meshes with shared interfaces, connected-domain metadata and optional verified COMSOL workflows. Source, tests, examples and numerical validation records are included.",
+  "creators": [
+    {
+      "name": "Chen, Xin",
+      "affiliation": "McGill University"
+    },
+    {
+      "name": "Akbarzadeh, Abdolhamid",
+      "affiliation": "McGill University"
+    }
+  ],
+  "license": "MIT",
+  "keywords": [
+    "TPMS",
+    "graded lattices",
+    "volume meshes",
+    "COMSOL",
+    "Python"
+  ]
+}

tpmslab-0.3.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 0.3.0
+
+- Package the verified complementary solid/fluid workflow and independent audits.
+- Include density, refinement, interface, channel and performance records with provenance.
+- Retain the validated numerical implementation from commit 686b783e0385.
+- Clarify geometry/solver response stability and local quality-strategy limitations.
+- Add isolated-wheel reference checks, exact-commit release preparation and public version documentation.
+- Preserve historical validation provenance; GitHub publication and DOI registration remain separate records.
+
+
+## 0.3.0rc1 — solid and pore-fluid domains
+
+- Add complementary solid/fluid meshes with shared interface vertices and faces.
+- Preserve independently connected solid and fluid domains, phase arrays and named boundaries.
+- Add fluid preview, domain metadata and optional COMSOL named selections.
+- Verify three fixed-wall pore-flow examples in COMSOL; deformation-coupled FSI is not implemented.
+- Add analytical partition and multi-family interface regression tests.
+
+## 0.2.0rc1 — local release candidate
+
+- Introduce src-layout packaging, public Python API and command-line commands.
+- Keep Flask and the browser interface optional; COMSOL remains optional.
+- Add conservative interior-fan selection with unchanged external boundary.
+- Add quality-tail diagnostics, deterministic mesh/boundary fingerprints,
+  environment records and file-integrity manifests.
+- Normalize configuration lists to immutable tuples and apply phase controls
+  consistently in the field helper.
+- Include reproducible comparisons, automated tests and release documentation.
+
+No PyPI release has been made; earlier rc entries describe local release candidates.

tpmslab-0.3.0/CITATION.cff

@@ -0,0 +1,13 @@
+cff-version: 1.2.0
+message: "Please cite the exact software version used."
+type: software
+title: "TPMS Lab"
+version: "0.3.0"
+authors:
+  - family-names: Chen
+    given-names: Xin
+  - family-names: Akbarzadeh
+    given-names: Abdolhamid
+repository-code: "https://github.com/Slight1211/TPMSLab"
+license: MIT
+abstract: "A Python package for graded complementary solid and pore-fluid meshes with connected-domain metadata and optional verified COMSOL workflows."

tpmslab-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TPMS Lab contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tpmslab-0.3.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md LICENSE CHANGELOG.md THIRD_PARTY_NOTICES.md
+recursive-include licenses *.txt
+recursive-include docs *.md *.m
+recursive-include examples *.json *.py
+recursive-include tests *.py
+recursive-include benchmarks *.py
+
+exclude docs/RELEASE_CHECKLIST.md
+prune paper
+
+recursive-include validation *.json *.csv *.md
+include CITATION.cff .zenodo.json

tpmslab-0.3.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: tpmslab
+Version: 0.3.0
+Summary: Direct conforming volume meshes for graded implicit TPMS lattices
+License-Expression: MIT
+Keywords: TPMS,finite-element,meshing,graded-lattice,COMSOL
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: licenses/LattGen-MIT.txt
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: scipy<2,>=1.11
+Requires-Dist: trimesh<6,>=4
+Provides-Extra: web
+Requires-Dist: flask<4,>=3.1; extra == "web"
+Provides-Extra: test
+Requires-Dist: pytest<10,>=8; extra == "test"
+Requires-Dist: flask<4,>=3.1; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: flask<4,>=3.1; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Requires-Dist: ruff>=0.12; extra == "dev"
+Dynamic: license-file
+
+# TPMS Lab
+
+[English quick start](docs/QUICKSTART_EN.md) | [中文使用说明](docs/QUICKSTART_ZH.md)
+
+An installable Python toolkit for graded TPMS-derived **solid and complementary pore-fluid volume meshes**.
+Version 0.3.0. This repository is public. Source, tests, examples and versioned
+reproducibility records are distributed together. Use an exact commit or the
+`v0.3.0` tag, rather than a changing `main`, for reproducible work.
+
+[Version and installation details](docs/VERSION_0.3.0.md) |
+[GitHub releases](https://github.com/Slight1211/TPMSLab/releases)
+
+A public source repository, a GitHub Release, a Zenodo archive and a PyPI upload
+are separate records. Cite a DOI only after the archive is actually published.
+No PyPI release has been made.
+
+## Install
+
+Use Python 3.11 or newer. From this source directory:
+
+```sh
+python -m pip install .
+# Optional local browser interface
+python -m pip install ".[web]"
+```
+
+Build a wheel locally with `python -m build` (requires the `build` package). The core does not require Flask, COMSOL, MATLAB,
+OpenCascade, a CAD import licence or a graphics display. COMSOL model creation
+and solving require a separate compatible COMSOL installation and licence.
+
+## Python API
+
+```python
+from tpmslab import Config, generate, save_model
+
+mesh = generate(Config(family="Gyroid", resolution=16,
+                       density_start=0.25, density_end=0.50,
+                       gradient="linear", quality_strategy="quality_fan"))
+print(mesh["report"]["actual_density"])
+save_model(mesh, "gyroid_result")  # destination must not exist
+```
+
+`generate` also accepts a dictionary. `list_families()` returns formula metadata.
+Coordinates are millimetres; array connectivity is zero-based. The returned
+mapping contains `points`, `tetra`, `boundary`, `boundary_ids`, `domains`,
+`surface` (a trimesh object) and `report`. This API may change before
+1.0. Configuration objects normalize sequence fields to immutable tuples.
+
+## Command line
+
+```sh
+tpmslab init-config params.json
+tpmslab generate --config params.json --out result
+tpmslab families
+tpmslab web --output local_models
+# Requires licensed COMSOL on Windows:
+tpmslab generate --config params.json --out solved_result --solve
+```
+
+Export includes `mesh.nas` (CTETRA volume elements and labelled boundary
+triangles), `mesh.npz`, `preview.stl`, parameters, diagnostics, environment and a
+SHA-256 manifest. Existing output directories are rejected. A failed export
+can leave a partial directory; choose a new destination after addressing the
+error. STL is only a boundary preview. The optional bridge imports the volume
+mesh, creates an MPH and reopens it to check the embedded element count.
+Set `COMSOL_BIN` to the folder containing `comsolbatch.exe` and
+`comsolcompile.exe` if automatic Windows detection fails.
+
+## Method and limits
+
+The library samples trigonometric level-set approximations, calibrates density
+against a 56 cubed periodic-cell sample and clips a six-tetrahedra-per-voxel
+background mesh. Sheet structures use two separate interpolated inequalities;
+they do not have constant physical wall thickness. Shared intersections and
+canonical face diagonals form a conforming tetrahedral volume mesh. Material
+volume, boundary closure, face incidence and orientation are checked before
+export. The result is a piecewise-planar solid domain, **not editable smooth
+STEP/NURBS CAD**. Mesh generation can reject difficult parameter combinations.
+
+`quality_fan` compares the original pulling fan with an interior-centroid fan
+for poor cut cells and accepts only a better worst mean-ratio quality while
+preserving boundary triangles and volume. This increases element count and can
+reduce median quality. It provides no angle bound, global optimization or
+finite-element convergence guarantee. `pulling` retains the baseline method.
+
+There are 29 reference labels (27 distinct expressions, with aliases), eight
+density profiles, sheet and two network modes, phase controls, and a restricted
+custom-formula parser. Built-in formulas are adapted from LattGen; see
+`THIRD_PARTY_NOTICES.md`. They are not claimed as new TPMS families or exact
+minimal surfaces. Density targets are periodic-cell calibrations, not guaranteed
+finite-specimen volume fractions. Current bounds: box domains, 1–6 cells per
+axis, 8–64 samples per cell and at most 200,000 background voxels. The built-in
+static demo is limited to 180,000 tetrahedra and connected material. Top/bottom
+contact, constraints and convergence must be checked for a research model.
+
+## Development and reproduction
+
+```sh
+python -m pip install ".[dev]"
+python -m pytest
+python -m ruff check src tests benchmarks
+python -m build
+python -m twine check dist/*
+python benchmarks/run_benchmarks.py --out benchmark_results
+```
+
+See `docs/METHOD.md`, `docs/SOLID_FLUID.md` and `docs/VALIDATION.md`.
+The CI matrix is configured for Windows/Linux and Python 3.11/3.12; configuring
+CI does not mean those jobs have run. The measured local environment is Windows
+and Python 3.12. Optional COMSOL validation is separate from the open test suite.
+
+## Licence and attribution
+
+MIT. See `LICENSE`, `THIRD_PARTY_NOTICES.md` and `licenses/` for the
+package licence and third-party formula and browser-library notices.
+
+## Solid and pore-fluid domains (0.3)
+
+```python
+from tpmslab import Config, generate, save_model
+from tpmslab.comsol import build_mph
+
+mesh = generate(Config(domain_mode="solid_fluid", family="Gyroid", resolution=12))
+folder = save_model(mesh, "solid_fluid_gyroid")
+# Optional, licensed COMSOL: verifies selections, each domain volume and saved mesh.
+build_mph(folder, mesh["report"], solve=False)
+# solve=True instead runs the fixed-wall pore-flow demonstration described below.
+```
+
+In the browser, select **固体 + 孔隙流体（共享界面）** under **计算域**.
+The phase selector switches the preview between solid and pore fluid.
+The default remains solid-only for compatibility. The JSON/CLI parameter is
+`"domain_mode": "solid_fluid"`.
+
+Both phases partition the same bounding box. They use shared cut-edge vertices
+and identical interface triangles. For sheet structures the two complementary
+inequalities are meshed separately, allowing disconnected labyrinths to remain
+separate domains. Connectivity is determined by shared tetrahedron faces.
+The combined mesh is checked for positive volumes, opposite adjacent-face
+orientation, complete interface matching and total volume conservation.
+
+`phase_ids` is one value per tetrahedron (1=solid, 2=fluid); `domains` identifies
+individual connected domains. `interface` is oriented out of the solid.
+`boundary` includes the outer boundary AND the solid-fluid interface once.
+Additional arrays are `solid_boundary` and `fluid_boundary`. `surface` and
+`preview.stl` continue to show the solid; `fluid_surface` and `fluid_preview.stl`
+show the pore fluid. The NPZ retains all phase and boundary arrays. `domains.json`
+records domain-to-phase and boundary-name mappings. Report `volume_mm3` remains
+solid volume; `total_mesh_volume_mm3` includes both phases.
+
+NASTRAN PSOLID property IDs are `100 + domain_id`. Boundary PIDs 2–7 are solid
+xmin/xmax/ymin/ymax/zmin/zmax; 12–17 are the corresponding fluid faces; PID 8
+is the shared interface. PIDs are NOT COMSOL entity numbers. The bridge resolves
+imported PID selections and creates `solid_domains`, `fluid_domains`, individual
+connected-domain selections, `solid_fluid_interface`, and the nonempty exterior
+face selections. It assigns demonstration solid/fluid materials separately.
+An unsolved export requires no CFD physics interface and is a starting point
+for the user's physics setup.
+
+For dual-domain models, `solve=True` runs stationary **creeping flow only in the
+fluid**, with fixed no-slip solid walls, pressure 0.01 Pa at fluid_zmin and 0 Pa
+at fluid_zmax, and no-slip on other fluid exterior faces. Density is 1000 kg/m³
+and viscosity 0.001 Pa·s. Every fluid component must reach both Z faces; otherwise
+the automatic demo is refused while unsolved export remains available. This
+requires the corresponding COMSOL physics licence. It reports inlet/outlet
+flow and relative imbalance (the smoke-test threshold is 5%, not an accuracy
+claim). It is **not deformation-coupled FSI**, not conjugate heat transfer, and
+not a validated permeability prediction. Boundary layers, external reservoirs,
+mesh convergence and realistic boundary conditions remain user responsibilities.
+See `docs/SOLID_FLUID.md` for validation and reproducibility.
+
+## Solid–fluid quick start
+
+Run [the Python example](examples/solid_fluid_api.py). Installation, exported
+files and optional COMSOL calculations are documented in the
+[English quick start](docs/QUICKSTART_EN.md) and
+[中文使用说明](docs/QUICKSTART_ZH.md).
+
+## Independent verification
+
+See [Verification and reproducible studies](docs/VERIFICATION.md) for density realization, independent interface incidence and area audits, channel-wise COMSOL flux checks, and refinement/performance scripts. `quality_fan` is optional local worst-element mitigation, not a general quality or solver-speed guarantee.
+
+## Reproducibility records
+
+See [validation/README.md](validation/README.md) for the numerical records,
+configuration provenance and reproduction commands corresponding to the verified
+workflow. The package provides mesh-defined simulation domains, not smooth CAD
+reconstruction or coupled FSI.

tpmslab-0.3.0/README.md

@@ -0,0 +1,188 @@
+# TPMS Lab
+
+[English quick start](docs/QUICKSTART_EN.md) | [中文使用说明](docs/QUICKSTART_ZH.md)
+
+An installable Python toolkit for graded TPMS-derived **solid and complementary pore-fluid volume meshes**.
+Version 0.3.0. This repository is public. Source, tests, examples and versioned
+reproducibility records are distributed together. Use an exact commit or the
+`v0.3.0` tag, rather than a changing `main`, for reproducible work.
+
+[Version and installation details](docs/VERSION_0.3.0.md) |
+[GitHub releases](https://github.com/Slight1211/TPMSLab/releases)
+
+A public source repository, a GitHub Release, a Zenodo archive and a PyPI upload
+are separate records. Cite a DOI only after the archive is actually published.
+No PyPI release has been made.
+
+## Install
+
+Use Python 3.11 or newer. From this source directory:
+
+```sh
+python -m pip install .
+# Optional local browser interface
+python -m pip install ".[web]"
+```
+
+Build a wheel locally with `python -m build` (requires the `build` package). The core does not require Flask, COMSOL, MATLAB,
+OpenCascade, a CAD import licence or a graphics display. COMSOL model creation
+and solving require a separate compatible COMSOL installation and licence.
+
+## Python API
+
+```python
+from tpmslab import Config, generate, save_model
+
+mesh = generate(Config(family="Gyroid", resolution=16,
+                       density_start=0.25, density_end=0.50,
+                       gradient="linear", quality_strategy="quality_fan"))
+print(mesh["report"]["actual_density"])
+save_model(mesh, "gyroid_result")  # destination must not exist
+```
+
+`generate` also accepts a dictionary. `list_families()` returns formula metadata.
+Coordinates are millimetres; array connectivity is zero-based. The returned
+mapping contains `points`, `tetra`, `boundary`, `boundary_ids`, `domains`,
+`surface` (a trimesh object) and `report`. This API may change before
+1.0. Configuration objects normalize sequence fields to immutable tuples.
+
+## Command line
+
+```sh
+tpmslab init-config params.json
+tpmslab generate --config params.json --out result
+tpmslab families
+tpmslab web --output local_models
+# Requires licensed COMSOL on Windows:
+tpmslab generate --config params.json --out solved_result --solve
+```
+
+Export includes `mesh.nas` (CTETRA volume elements and labelled boundary
+triangles), `mesh.npz`, `preview.stl`, parameters, diagnostics, environment and a
+SHA-256 manifest. Existing output directories are rejected. A failed export
+can leave a partial directory; choose a new destination after addressing the
+error. STL is only a boundary preview. The optional bridge imports the volume
+mesh, creates an MPH and reopens it to check the embedded element count.
+Set `COMSOL_BIN` to the folder containing `comsolbatch.exe` and
+`comsolcompile.exe` if automatic Windows detection fails.
+
+## Method and limits
+
+The library samples trigonometric level-set approximations, calibrates density
+against a 56 cubed periodic-cell sample and clips a six-tetrahedra-per-voxel
+background mesh. Sheet structures use two separate interpolated inequalities;
+they do not have constant physical wall thickness. Shared intersections and
+canonical face diagonals form a conforming tetrahedral volume mesh. Material
+volume, boundary closure, face incidence and orientation are checked before
+export. The result is a piecewise-planar solid domain, **not editable smooth
+STEP/NURBS CAD**. Mesh generation can reject difficult parameter combinations.
+
+`quality_fan` compares the original pulling fan with an interior-centroid fan
+for poor cut cells and accepts only a better worst mean-ratio quality while
+preserving boundary triangles and volume. This increases element count and can
+reduce median quality. It provides no angle bound, global optimization or
+finite-element convergence guarantee. `pulling` retains the baseline method.
+
+There are 29 reference labels (27 distinct expressions, with aliases), eight
+density profiles, sheet and two network modes, phase controls, and a restricted
+custom-formula parser. Built-in formulas are adapted from LattGen; see
+`THIRD_PARTY_NOTICES.md`. They are not claimed as new TPMS families or exact
+minimal surfaces. Density targets are periodic-cell calibrations, not guaranteed
+finite-specimen volume fractions. Current bounds: box domains, 1–6 cells per
+axis, 8–64 samples per cell and at most 200,000 background voxels. The built-in
+static demo is limited to 180,000 tetrahedra and connected material. Top/bottom
+contact, constraints and convergence must be checked for a research model.
+
+## Development and reproduction
+
+```sh
+python -m pip install ".[dev]"
+python -m pytest
+python -m ruff check src tests benchmarks
+python -m build
+python -m twine check dist/*
+python benchmarks/run_benchmarks.py --out benchmark_results
+```
+
+See `docs/METHOD.md`, `docs/SOLID_FLUID.md` and `docs/VALIDATION.md`.
+The CI matrix is configured for Windows/Linux and Python 3.11/3.12; configuring
+CI does not mean those jobs have run. The measured local environment is Windows
+and Python 3.12. Optional COMSOL validation is separate from the open test suite.
+
+## Licence and attribution
+
+MIT. See `LICENSE`, `THIRD_PARTY_NOTICES.md` and `licenses/` for the
+package licence and third-party formula and browser-library notices.
+
+## Solid and pore-fluid domains (0.3)
+
+```python
+from tpmslab import Config, generate, save_model
+from tpmslab.comsol import build_mph
+
+mesh = generate(Config(domain_mode="solid_fluid", family="Gyroid", resolution=12))
+folder = save_model(mesh, "solid_fluid_gyroid")
+# Optional, licensed COMSOL: verifies selections, each domain volume and saved mesh.
+build_mph(folder, mesh["report"], solve=False)
+# solve=True instead runs the fixed-wall pore-flow demonstration described below.
+```
+
+In the browser, select **固体 + 孔隙流体（共享界面）** under **计算域**.
+The phase selector switches the preview between solid and pore fluid.
+The default remains solid-only for compatibility. The JSON/CLI parameter is
+`"domain_mode": "solid_fluid"`.
+
+Both phases partition the same bounding box. They use shared cut-edge vertices
+and identical interface triangles. For sheet structures the two complementary
+inequalities are meshed separately, allowing disconnected labyrinths to remain
+separate domains. Connectivity is determined by shared tetrahedron faces.
+The combined mesh is checked for positive volumes, opposite adjacent-face
+orientation, complete interface matching and total volume conservation.
+
+`phase_ids` is one value per tetrahedron (1=solid, 2=fluid); `domains` identifies
+individual connected domains. `interface` is oriented out of the solid.
+`boundary` includes the outer boundary AND the solid-fluid interface once.
+Additional arrays are `solid_boundary` and `fluid_boundary`. `surface` and
+`preview.stl` continue to show the solid; `fluid_surface` and `fluid_preview.stl`
+show the pore fluid. The NPZ retains all phase and boundary arrays. `domains.json`
+records domain-to-phase and boundary-name mappings. Report `volume_mm3` remains
+solid volume; `total_mesh_volume_mm3` includes both phases.
+
+NASTRAN PSOLID property IDs are `100 + domain_id`. Boundary PIDs 2–7 are solid
+xmin/xmax/ymin/ymax/zmin/zmax; 12–17 are the corresponding fluid faces; PID 8
+is the shared interface. PIDs are NOT COMSOL entity numbers. The bridge resolves
+imported PID selections and creates `solid_domains`, `fluid_domains`, individual
+connected-domain selections, `solid_fluid_interface`, and the nonempty exterior
+face selections. It assigns demonstration solid/fluid materials separately.
+An unsolved export requires no CFD physics interface and is a starting point
+for the user's physics setup.
+
+For dual-domain models, `solve=True` runs stationary **creeping flow only in the
+fluid**, with fixed no-slip solid walls, pressure 0.01 Pa at fluid_zmin and 0 Pa
+at fluid_zmax, and no-slip on other fluid exterior faces. Density is 1000 kg/m³
+and viscosity 0.001 Pa·s. Every fluid component must reach both Z faces; otherwise
+the automatic demo is refused while unsolved export remains available. This
+requires the corresponding COMSOL physics licence. It reports inlet/outlet
+flow and relative imbalance (the smoke-test threshold is 5%, not an accuracy
+claim). It is **not deformation-coupled FSI**, not conjugate heat transfer, and
+not a validated permeability prediction. Boundary layers, external reservoirs,
+mesh convergence and realistic boundary conditions remain user responsibilities.
+See `docs/SOLID_FLUID.md` for validation and reproducibility.
+
+## Solid–fluid quick start
+
+Run [the Python example](examples/solid_fluid_api.py). Installation, exported
+files and optional COMSOL calculations are documented in the
+[English quick start](docs/QUICKSTART_EN.md) and
+[中文使用说明](docs/QUICKSTART_ZH.md).
+
+## Independent verification
+
+See [Verification and reproducible studies](docs/VERIFICATION.md) for density realization, independent interface incidence and area audits, channel-wise COMSOL flux checks, and refinement/performance scripts. `quality_fan` is optional local worst-element mitigation, not a general quality or solver-speed guarantee.
+
+## Reproducibility records
+
+See [validation/README.md](validation/README.md) for the numerical records,
+configuration provenance and reproduction commands corresponding to the verified
+workflow. The package provides mesh-defined simulation domains, not smooth CAD
+reconstruction or coupled FSI.

tpmslab-0.3.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,22 @@
+# Third-party notices
+
+The formula registry is adapted from Hilda Chris-Amadin and Osezua Ibhadode,
+LattGen: A TPMS lattice generation tool, Software Impacts 21 (2024), 100665,
+https://doi.org/10.1016/j.simpa.2024.100665.
+Source: https://github.com/SoftwareImpacts/SIMPAC-2024-10 .
+The repository MIT notice is preserved in licenses/LattGen-MIT.txt.
+The 29 source labels include two duplicate-expression aliases; the paper's
+reported family count should not be used to claim 29 distinct new families.
+Reference functions are in docs/lattgen_reference.m where available.
+
+Three.js r169 and OrbitControls are redistributed under MIT. Full notice:
+src/tpmslab/static/vendor/THREE-LICENSE.txt. Source: https://github.com/mrdoob/three.js .
+
+NumPy, SciPy, trimesh and optional Flask are dependencies installed separately;
+their upstream licences remain applicable. COMSOL is proprietary software,
+installed and licensed separately. No COMSOL executable is redistributed.
+
+The direct cut-volume workflow was informed by the user's earlier TPMS cut-mesh
+validation scripts. Provenance and contributor authorship require maintainer
+review before public release. No novelty claim is made for clipping,
+pulling triangulation, centroid fans or the supplied level-set functions.

tpmslab-0.3.0/benchmarks/density_study.py

@@ -0,0 +1,84 @@
+"""Density realization and exact grid-aligned slab volumes for reference specimens."""
+
+import argparse
+from dataclasses import replace
+import json
+from pathlib import Path
+import numpy as np
+from tpmslab import Config, generate
+from tpmslab.model import raw_field
+from tpmslab.verification import audit_interface
+
+
+def load_mesh(folder):
+    a = np.load(Path(folder) / "mesh.npz")
+    return dict(
+        points=a["points_mm"],
+        tetra=a["tetrahedra"],
+        phase_ids=a["phase_ids"],
+        interface=a["interface"],
+        domains=a["domain_ids"],
+    )
+
+
+def geometry_record(model, config):
+    p = model["points"][model["tetra"]]
+    v = (
+        np.abs(
+            np.einsum("ij,ij->i", p[:, 1] - p[:, 0], np.cross(p[:, 2] - p[:, 0], p[:, 3] - p[:, 0]))
+        )
+        / 6
+    )
+    solid = model["phase_ids"] == 1
+    n = config.resolution * config.cells[2]
+    z = np.clip(np.floor(p[:, :, 2].mean(axis=1) / config.size[2] * n).astype(int), 0, n - 1)
+    bins = np.bincount(z[solid], weights=v[solid], minlength=n)
+    expected = (config.density_start + config.density_end) / 2
+    result = dict(
+        family=config.family,
+        resolution=config.resolution,
+        target_average=expected,
+        mesh_density=float(v[solid].sum() / np.prod(config.size)),
+        slab_z_mm=((np.arange(n) + 0.5) * config.size[2] / n).tolist(),
+        slab_density=(bins / (np.prod(config.size) / n)).tolist(),
+        audit=audit_interface(model),
+    )
+    result["relative_target_deviation"] = (result["mesh_density"] - expected) / expected
+    return result
+
+
+def field_reference(config, n):
+    # Independent midpoint integration of the unlinearized implicit field;
+    # it uses the same threshold calibration, not the tetrahedral mesh.
+    x = (np.arange(n) + 0.5) * config.size[0] / n
+    y = (np.arange(n) + 0.5) * config.size[1] / n
+    count = 0
+    for z in (np.arange(n) + 0.5) * config.size[2] / n:
+        count += np.count_nonzero(raw_field(config, x[:, None], y[None, :], z) >= 0)
+    return count / n**3
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--source", type=Path)
+    p.add_argument("--out", type=Path, required=True)
+    args = p.parse_args()
+    args.out.mkdir(parents=True, exist_ok=False)
+    records = []
+    for family in ["Gyroid", "Primitive Schwartz", "Diamond"]:
+        c = Config(family=family, domain_mode="solid_fluid", resolution=12)
+        model = load_mesh(args.source / family.replace(" ", "_")) if args.source else generate(c)
+        r = geometry_record(model, c)
+        r["implicit_midpoint_128"] = field_reference(c, 128)
+        r["implicit_midpoint_256"] = field_reference(c, 256)
+        records.append(r)
+        for lo, hi in [(0.125, 0.375), (0.375, 0.625)]:
+            cc = replace(c, density_start=lo, density_end=hi)
+            m = generate(cc)
+            records.append(geometry_record(m, cc))
+        print("DENSITY", family, flush=True)
+    (args.out / "density_results.json").write_text(json.dumps(records, indent=2), "utf8")
+
+
+if __name__ == "__main__":
+    main()