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

BiomechPy NumPy Q4 reference
            vs
DOLFINx 0.11 / PETSc SNES

The frozen reference values are

total energy  1.4271533287877007
reaction x   15.55219526522195
reaction y   30.83467144077694

Run the strict gate with

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:

biomechpy verify-backends --allow-missing

For the real MPI matrix in the dedicated FEniCSx environment:

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/fenicsx_verification_environment.md
• notebooks/11_matched_backend_verification.ipynb

Stable API

For long-lived research code:

import biomechpy.api as bmp

For notebooks and interactive work:

import biomechpy as bmp

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

Build your own tissue

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

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

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

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

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

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

For long simulations:

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:

biomechpy verify
biomechpy verify-backends

or:

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

Current contracts:

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

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

Optional tissue presets

Presets are examples, not the architecture:

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.

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:

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/custom_tissue.md
• docs/api_stability.md
• docs/stable_api_v1.md
• docs/benchmark_contracts.md
• docs/modeling_scope.md
• docs/units_and_dimensions.md
• docs/scientific_audit_resolution_v1.0.md
• docs/migration_0_9_to_1_0.md
• docs/scientific_contracts.md
• docs/architecture.md

Installation

From the repository:

python -m pip install -e .

For notebooks:

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

or:

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.