Metadata-Version: 2.4
Name: biomimetic-lattice-pipeline
Version: 0.2.0
Summary: Micro-CT-driven generation of biomimetic enamel lattices with FEA-based design optimization.
Author-email: "Cameron B. Renteria" <crentb@uw.edu>
License: Apache-2.0
Project-URL: Homepage, https://github.com/crentb/biomimetic-lattice-pipeline
Project-URL: Issues, https://github.com/crentb/biomimetic-lattice-pipeline/issues
Keywords: bioinspired design,biomimetic materials,tooth enamel,finite element analysis,parametric CAD,design optimization,synchrotron microCT,lattice,Optuna
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: pandas>=2.0
Requires-Dist: matplotlib>=3.7
Requires-Dist: trimesh>=4.0
Requires-Dist: optuna>=3.4
Requires-Dist: PyYAML>=6.0
Requires-Dist: jsonschema>=4.0
Provides-Extra: fea
Requires-Dist: pyvista>=0.43; extra == "fea"
Requires-Dist: gmsh>=4.11; extra == "fea"
Requires-Dist: meshio>=5.3; extra == "fea"
Requires-Dist: scikit-image>=0.21; extra == "fea"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff==0.14.10; extra == "dev"
Requires-Dist: black==26.3.1; extra == "dev"
Requires-Dist: mypy==1.17.1; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Dynamic: license-file

# biomimetic-lattice-pipeline

[![CI](https://github.com/crentb/biomimetic-lattice-pipeline/actions/workflows/ci.yml/badge.svg)](https://github.com/crentb/biomimetic-lattice-pipeline/actions/workflows/ci.yml)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%E2%80%933.12-blue.svg)](pyproject.toml)

Micro-CT–driven generation of **biomimetic enamel lattices** with finite-element-based design optimization.

The pipeline turns measured three-dimensional rod geometry from synchrotron micro-CT of tooth enamel into
**parametric CAD lattices**, runs **linear-elastic finite-element analysis (FEA)** on them, scores the results
against pluggable **objectives**, and can drive a **closed-loop Optuna optimization** that searches the
manufacturability-constrained design space — emitting a metrics JSON and a LaTeX/PDF report per run.

> This is the software behind the *Matter* manuscript *"Translating Helically Decussated Enamel into
> Damage-Tolerant Bioinspired Lattices"* (Renteria et al., in preparation).

## Architecture

![pipeline architecture](docs/figures/01_architecture.png)

A single canonical `morphometrics.json` is the only coupling point between stages, so each component can be
swapped independently:

```
ingest/        measured micro-CT morphometrics  ->  canonical morphometrics.json
mapping/       morphometrics  ->  CAD parameters (deterministic, with logged manufacturability clamps)
generators/    parametric continuous-twist CAD family + rod-by-rod digital-twin variants
fea/           strain-solver driving SfePy to a target representative stress
metrics/       crack-deflection streamlines, biomimicry score, SCF, toughness, ...
objectives/    YAML-configured, registry-based scoring (crack deflection, toughness, ...)
orchestration/ single-run, sweep, Optuna optimization, and closed-loop drivers
reporting/     LaTeX/PDF report generation
geometry/      CadQuery + SfePy CAD/mesh/FEA engine, driven by generators/ + fea/ via subprocess (conda)
```

## Install

```bash
git clone https://github.com/crentb/biomimetic-lattice-pipeline.git
cd biomimetic-lattice-pipeline
python -m pip install -e ".[dev]"      # core runtime + dev tools (pytest, ruff, black)
```

Optional heavy geometry/visualization extras:

```bash
python -m pip install -e ".[fea]"      # pyvista, gmsh, meshio, scikit-image
```

> **Full FEA** additionally requires **CadQuery** and **SfePy** (installed via conda, as they are awkward to
> pip-install across platforms); the CAD/FEA engine itself ships in this repo under `geometry/`
> (see `geometry/README.md`). The default install and the CI exercise the **pure-Python design and analytics
> logic**; the heavy FEA/CAD path is gated behind the `slow` pytest marker.

## Quickstart

```bash
# End-to-end single-specimen run: morphometrics -> CAD -> mesh -> FEA -> metrics -> report
python scripts/run_pipeline.py --morphometrics path/to/morphometrics.json \
    --run-name demo --objective crack_deflection --model-type continuous_twist

# Parametric sweep over a single free CAD parameter
python scripts/run_sweep.py --morphometrics path/to/morphometrics.json \
    --run-name sweep_layers --param N_BRIDGE_LAYERS --values 4 6 8

# Closed-loop Optuna optimization of an objective
python scripts/run_optimize.py --morphometrics path/to/morphometrics.json \
    --run-name opt_cd --objective crack_deflection --n-trials 30
```

(See `scripts/` for the full set of CLI entry points.)

## Testing

```bash
pytest -m "not slow"      # fast, pure-Python logic tests (what CI runs)
pytest                    # everything, including the FEA integration test (needs the conda FEA stack)
```

## License

Apache-2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).

## Citation

A `CITATION.cff` will accompany the first tagged release; until then, please cite the *Matter* manuscript above.
