Metadata-Version: 2.4
Name: biomechpy
Version: 1.1.0
Summary: Universal Python framework for growth and remodeling of biological tissues.
Author: BiomechPy contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/Data-Driven-Biomedicine-Lab/BiomechPy
Project-URL: Repository, https://github.com/Data-Driven-Biomedicine-Lab/BiomechPy
Project-URL: Issues, https://github.com/Data-Driven-Biomedicine-Lab/BiomechPy/issues
Keywords: biomechanics,growth,remodeling,constrained mixture,soft tissue,mechanobiology
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Provides-Extra: notebook
Requires-Dist: matplotlib>=3.7; extra == "notebook"
Requires-Dist: pandas>=2.0; extra == "notebook"
Requires-Dist: jupyterlab>=4.0; extra == "notebook"
Requires-Dist: ipykernel>=6.0; extra == "notebook"
Requires-Dist: nbformat>=5.9; extra == "notebook"
Requires-Dist: nbclient>=0.10; extra == "notebook"
Requires-Dist: nbconvert>=7.0; extra == "notebook"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Dynamic: license-file

# BiomechPy

**Universal Growth and Remodeling of Biological Tissues**  
Version `1.1.0`

BiomechPy is a Python research framework for finite-strain mechanics, growth,
remodeling, constituent turnover, and constrained-mixture modeling of
biological tissues.

Version 1.0 froze the first stable user-facing architecture:

\[
\text{constituents}
\rightarrow
\text{mechanics}
\rightarrow
\text{stimuli}
\rightarrow
\text{production/removal}
\rightarrow
\text{deposition}
\rightarrow
\text{growth/remodeling}.
\]

The package is **universal by composition**. A new tissue model is built by
combining reusable scientific components; adding a new organ does not require
creating a new solver class.


## 1.1 final release status

BiomechPy **1.1.0** is the promoted stable release from the independently
audited `1.1.0rc4` candidate. The numerical/scientific source used for the
release gate is unchanged by the promotion; only release metadata and final
release documentation were updated.

The matched backend contract was executed with DOLFINx 0.11.0, PETSc 3.25.5,
and real MPICH runs on 1, 2, and 4 ranks. NumPy/FEniCSx energy and reactions
agree to relative errors below `1.4e-15` for this contract. All 104 tests, all
four scientific/regression contracts, all seven notebooks, all four examples,
Ruff check/format, wheel/sdist isolated installs, and the full release manifest
passed in the independently audited release candidate.

This verifies the stated synthetic matched-backend boundary. It is not
experimental, clinical, patient-specific, or tissue-wide validation.


## What is new in 1.1

BiomechPy 1.1 does not introduce a new tissue law. It verifies the numerical
backend boundary established by the stable 1.0 scientific core.

The first matched contract solves the same homogeneous fiber-reinforced
biaxial patch with

```text
BiomechPy NumPy Q4 reference
            vs
DOLFINx 0.11 / PETSc SNES
```

The frozen reference values are

```text
total energy  1.4271533287877007
reaction x   15.55219526522195
reaction y   30.83467144077694
```

Run the strict gate with

```bash
biomechpy verify-backends
```

The command intentionally returns exit code `2` when the FEniCSx candidate was
not executed. Missing DOLFINx is **not** interpreted as a successful backend
verification.

For NumPy-only environment diagnostics:

```bash
biomechpy verify-backends --allow-missing
```

For the real MPI matrix in the dedicated FEniCSx environment:

```bash
bash scripts/run_fenicsx_mpi_matrix.sh
```

which executes the same problem on 1, 2, and 4 MPI ranks.

The audited RC4 run completed all three ranks and the comparer returned exit
code `0`; machine-readable results are archived under `results/data/`.

See:

- [`docs/backend_verification_1_1.md`](docs/backend_verification_1_1.md)
- [`docs/fenicsx_verification_environment.md`](docs/fenicsx_verification_environment.md)
- [`notebooks/11_matched_backend_verification.ipynb`](notebooks/11_matched_backend_verification.ipynb)

## Stable API

For long-lived research code:

```python
import biomechpy.api as bmp
```

For notebooks and interactive work:

```python
import biomechpy as bmp
```

The names documented in `biomechpy.api` are covered by the BiomechPy 1.x
compatibility/deprecation policy.

## Build your own tissue

```python
import numpy as np
import biomechpy.api as bmp

matrix = bmp.ConstituentDefinition(
    name="matrix",
    material=bmp.NeoHookean(2.0, 180.0),
    survival_law=bmp.PermanentSurvival(),
    production_law=bmp.ConstantProduction(0.0),
    initial_density=0.4,
)

architecture = bmp.FiberArchitecture.from_angles(
    np.deg2rad([25.0]),
    structural_order=[0.8],
    weights=[1.0],
    names=["fiber"],
)

fiber = bmp.ConstituentDefinition(
    name="fiber",
    material=bmp.ExponentialFiber(5.0, 5.0),
    survival_law=bmp.ExponentialSurvival(12.0),
    production_law=bmp.HomeostaticProduction(
        0.6 / 12.0,
        gain=2.0,
        density_feedback=0.25,
    ),
    initial_density=0.6,
    architecture=architecture,
    deposition_rule=bmp.DirectionalDepositionStretch(1.04, 1.0),
)

tissue = (
    bmp.TissueBuilder("custom_tissue", dimension=2)
    .add_constituents((matrix, fiber))
    .describe("Synthetic custom tissue model.")
    .with_metadata(data="synthetic")
    .build()
)
```

No preset is required.

## Validate before simulation

```python
report = bmp.validate_tissue_definition(tissue)
print(report.summary())
report.raise_for_errors()
```

Validation checks software/scientific invariants such as deposition
Jacobians, survival-law ranges, production-law outputs, and dimensional
compatibility. It does **not** claim physiological or experimental validation.

## Constitutive parameter and units contract

`NeoHookean(mu, lame_lambda)` uses the first Lamé parameter `lambda` in the
logarithmic volumetric term; the second argument is **not** a physical bulk
modulus. To construct from a requested small-strain bulk modulus `K`, use
`NeoHookean.from_shear_bulk(mu, K, dimension=...)`.

Constituent `initial_density` / `deposited_density` are dimensionless normalized
reference-content weights in the 1.0 mixture model. Two-dimensional material
calculations are intrinsic 2D formulations and are not silently interpreted as
plane stress or plane strain. See `docs/units_and_dimensions.md`.

## Material-point constrained mixture

```python
state = tissue.initial_mixture()

step = bmp.advance_turnover(
    state,
    np.diag([1.08, 1.02]),
    time_step=1.0,
    stimuli={"fiber": 0.05},
)
```

For a cohort deposited at biological time \(\tau\),

\[
\mathbf F_e^{\alpha,\tau}(t)
=
\mathbf F(t)
\mathbf F^{-1}(\tau)
\mathbf G_h^\alpha(\tau).
\]

The constrained-mixture energy is accumulated over surviving constituent
cohorts.

## Spatial growth and remodeling

```python
mesh = bmp.rectangular_quad_mesh(8, 4)
spatial_state = tissue.initial_spatial_mixture(mesh)
```

Every integration location stores its own constituent/cohort history.

BiomechPy supports:

- local production and removal;
- spatially heterogeneous initial constituent densities;
- cohort deposition histories;
- exact local mass-balance audits;
- structured reference Q4 equilibrium;
- optional cohort compression;
- checkpoint/restart;
- packed ragged cohort storage.

## Unstructured and 3D state workflows

```python
mesh3d = bmp.unit_cube_tet_mesh(2, 2, 2)
```

The unstructured layer provides:

- triangles and tetrahedra;
- stable global cell IDs;
- stable global quadrature-location IDs;
- deterministic partition plans;
- exact partition/reconstruction of biological histories;
- partition-aware checkpoints;
- 3D constrained-mixture affine reference benchmarks.

The current tetrahedral reference benchmark uses **prescribed affine
kinematics**; it is not presented as a nonlinear 3D FE equilibrium solve.

## Scalable history storage

```python
packed = bmp.pack_spatial_mixture_state(spatial_state)
restored = packed.to_state()
```

For long simulations:

```python
policy = bmp.CohortCompressionPolicy(
    maximum_cohorts=12,
    protected_recent_cohorts=2,
    old_age_bins=9,
)
```

Compression preserves current surviving density at the compression instant but
approximates history-dependent mechanics. BiomechPy reports this approximation
error explicitly.

## Versioned benchmark contracts

BiomechPy 1.0 freezes synthetic numerical reference contracts:

```bash
biomechpy verify
biomechpy verify-backends
```

or:

```python
for result in bmp.run_all_benchmark_contracts():
    print(result.summary())
```

Current contracts:

```text
material_point_turnover_v1
spatial_q4_turnover_v1
unstructured_3d_turnover_v1
scientific_invariants_v1
```

The first three contracts reproduce corrected synthetic numerical behavior.
`scientific_invariants_v1` instead targets analytical/invariance properties such
as homeostatic mass preservation, frame indifference, constitutive
differentiation, homeostatic growth, and affine FE mesh invariance. Passing any
contract is computational verification, not experimental validation.

## Command line

```bash
biomechpy info
biomechpy presets
biomechpy preset tendon --json
biomechpy verify
```

## Optional tissue presets

Presets are examples, not the architecture:

```python
bmp.available_tissue_presets()
```

currently includes examples for arterial wall, tendon, skin, myocardium,
uterus, intestine, and cartilage. All return the same `TissueDefinition` type.
Parameters are synthetic software defaults.

## FEniCSx

FEniCSx is optional. The 1.1 verification backend targets the stable DOLFINx `0.11.x`
release series.

```bash
conda env create -f environment-fenicsx.yml
conda activate biomechpy-fenicsx
```

Ragged constituent histories remain in packed sidecar storage while fixed-size
summaries can be mapped to DG0 fields.

The verified FEniCSx scope is the matched homogeneous patch. It does not imply
that an arbitrary distributed nonlinear constrained-mixture model has been
experimentally validated.

## Notebooks

Recommended sequence:

```text
00_START_HERE.ipynb
06_constituent_turnover_and_constrained_mixture.ipynb
07_spatial_constrained_mixtures.ipynb
08_scalable_spatial_mixtures.ipynb
09_distributed_unstructured_mixtures.ipynb
10_build_your_own_tissue_model.ipynb
```

Notebook 10 is the main 1.0 user tutorial: it builds a model without using a
preset.

## Documentation

- [`docs/quickstart.md`](docs/quickstart.md)
- [`docs/custom_tissue.md`](docs/custom_tissue.md)
- [`docs/api_stability.md`](docs/api_stability.md)
- [`docs/stable_api_v1.md`](docs/stable_api_v1.md)
- [`docs/benchmark_contracts.md`](docs/benchmark_contracts.md)
- [`docs/modeling_scope.md`](docs/modeling_scope.md)
- [`docs/units_and_dimensions.md`](docs/units_and_dimensions.md)
- [`docs/scientific_audit_resolution_v1.0.md`](docs/scientific_audit_resolution_v1.0.md)
- [`docs/migration_0_9_to_1_0.md`](docs/migration_0_9_to_1_0.md)
- [`docs/scientific_contracts.md`](docs/scientific_contracts.md)
- [`docs/architecture.md`](docs/architecture.md)

## Installation

From the repository:

```bash
python -m pip install -e .
```

For notebooks:

```bash
python -m pip install -e ".[notebook]"
```

or:

```bash
conda env create -f environment.yml
conda activate biomechpy
jupyter lab
```

## Scientific scope

BiomechPy provides a common architecture for G&R models; it does not assert
that one material law or one mechanobiological hypothesis applies to all
biological tissues.

Separate extensions are still required for physics such as:

- biphasic/poroelastic transport;
- electrophysiology;
- fluid–structure interaction;
- reaction–diffusion;
- contact;
- mineralized-tissue remodeling;
- detailed cell-population dynamics.

## Scientific status

All distributed benchmark and preset parameters are synthetic unless a user
explicitly supplies calibrated data. BiomechPy 1.1 is a computational research
framework and numerically verified software release for the stated contracts; it does not claim clinical
or tissue-specific experimental validation.


### Scope of `remodeling_law`

`TissueDefinition.remodeling_law` is currently a reusable standalone
remodeling primitive. The constrained-mixture simulation loops update
production, survival, deposition, cohorts and mechanics; they do **not**
automatically advance that remodeling law. A model that couples both mechanisms
must call the remodeling state transition explicitly.

This distinction is intentional in the 1.1 release and prevents the
high-level architecture diagram from being read as a claim of an already
fully coupled arbitrary G&R solver.



## Verified release boundary

The independent RC4 release-gate audit approved promotion to `1.1.0 FINAL`.
Allowed claims are limited to the stated numerical/software contracts: NumPy
reference verification, DOLFINx 0.11 matched-backend verification, real MPI
rank invariance, scientific invariants, and checkpoint/restart reproducibility.
BiomechPy 1.1.0 does **not** claim experimental validation for all tissues,
clinical validation, or patient-specific predictive validity.
