biomechpy 1.1.0__tar.gz

biomechpy-1.1.0/CITATION.cff

@@ -0,0 +1,9 @@
+cff-version: 1.2.0
+message: "If you use BiomechPy, please cite the software release metadata."
+title: "BiomechPy: Universal Growth and Remodeling of Biological Tissues"
+type: software
+authors:
+  - name: "BiomechPy contributors"
+version: "1.1.0"
+date-released: "2026-09-09"
+license: MIT

biomechpy-1.1.0/LICENSE

@@ -0,0 +1,7 @@
+MIT License
+
+Copyright (c) 2026 BiomechPy 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, subject to inclusion of this notice.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

biomechpy-1.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md
+include LICENSE
+include CITATION.cff
+include environment.yml
+include environment-fenicsx.yml
+recursive-include docs *.md *.png
+recursive-include notebooks *.ipynb
+recursive-include examples *.py
+recursive-include scripts *.py *.sh *.bat
+recursive-include src/biomechpy *.py py.typed
+
+recursive-include src/biomechpy/data *.json
+recursive-include tests *.py

biomechpy-1.1.0/PKG-INFO

@@ -0,0 +1,472 @@
+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.