KneeMechBridge

KneeMechBridge is a traceable reduced-order research framework and executable computational companion to the published scientific review:

Mikołaj Stańczak, Bartłomiej Kacprzak, and Magdalena Hagner-Derengowska,
From Joint Loading to Osteoarthritis: A Multiscale Review of Knee Mechanobiology and Digital Modelling,
International Journal of Molecular Sciences 27(16), 7462 (2026).

It makes the review's cross-scale assumptions inspectable and testable. It does not turn an incomplete evidence chain into a patient forecast.

Research software. Not for clinical diagnosis or treatment decisions.

KneeMechBridge is not a finite-element solver, a validated OA progression model, or a clinically validated digital twin.

This repository implements reduced-order computational representations of concepts reviewed in the publication. It does not reproduce every cited experimental study and does not constitute a validated patient-specific clinical model.

Quick start

Python 3.12 is preferred; Python 3.11 and 3.12 are tested in CI. Install uv, then run:

cd KneeMechBridge
uv sync
uv run --frozen kneemechbridge simulate --activity level_walking --mass 75

That one simulation reports the whole-joint and reduced tissue response together with validation maturity and domain warnings. To run the dashboard:

uv run --frozen streamlit run app/dashboard.py

For a minimal library/CLI environment without development tools, use uv sync --no-dev. For a minimal dashboard environment, use uv sync --extra app --no-dev.

The single authoritative repository validation command is:

uv run --frozen python scripts/validate_repository.py

Scientific motivation

Knee loading is not itself a cartilage, cell, or biological outcome. Each transfer introduces geometry, material, boundary-condition, biological, and population uncertainty. This repository therefore keeps each scale separate:

flowchart TD
    L[Literature / reference parameters]
    I[Joint / gait scenario<br/>activity, body mass, loading scale]
    W[Whole-joint load state<br/>empirical TKR anchor]
    T[Tissue mechanical state<br/>reduced-order pressure, strain estimate, fluid support]
    C[Cell / membrane stimulus<br/>opt-in uncalibrated heuristic]
    S[Mechanosensor response<br/>phenomenological logistic recruitment]
    U[Biological turnover signal<br/>explicitly withheld]
    O[OA feedback trajectory<br/>separate hypothesis-generating model]
    P[Updated cartilage property fraction<br/>normalized phenomenological state]

    L --> I --> W --> T
    T -. disabled by default .-> C --> S
    S -. no calibrated transfer implemented .-> U
    U -. future validated coupling required .-> O --> P
    P -. hypothetical feedback only .-> T

    V1[Implant telemetry] -. required validation anchor .-> W
    V2[Pressure / imaging / cadaveric tests] -. required validation anchor .-> T
    V3[AFM / aspiration / microscopy] -. required validation anchor .-> C
    V4[Calcium / perturbation experiments] -. required validation anchor .-> S
    V5[Assays / histology] -. required validation anchor .-> U
    V6[Longitudinal external cohorts] -. required validation anchor .-> O

    V[Validation ladder]
    Q[Uncertainty propagation]
    ML[ML surrogate]
    D[Digital-shadow layer]
    V -. assesses each output .-> W
    V -. assesses each output .-> T
    V -. assesses each output .-> C
    Q -. propagates scenario spread .-> W
    Q -. propagates scenario spread .-> T
    ML -. emulates parent model .-> T
    D -. one-way scalar assimilation demo .-> I

Loading

The executable default chain stops before the unvalidated tissue-to-cell transfer. The turnover state is represented explicitly but contains unavailable values rather than an invented equation. The OA module is deliberately separate and uses a user-selected normalized exposure.

Typed multiscale architecture

MultiscaleKneeModel.simulate() returns a SimulationResult containing:

• WholeJointLoadState
• TissueMechanicalState
• CellMechanicalStimulus
• MechanosensorResponse
• BiologicalTurnoverSignal

Every transition has StageMetadata describing inputs, outputs, units, assumptions, uncertainty, validation source, model type, and maturity. Legacy flat properties such as result.contact_force_n remain available.

The tissue layer computes force divided by an effective contact area, a characteristic biphasic consolidation time, transient fluid/solid load sharing, Darcy flux, and an apparent linear solid-strain estimate. The strain estimate is solid stress / aggregate modulus; it is not a local finite-element strain and a warning is emitted outside a nominal small-strain domain.

Implemented equations and models

Component	Implementation	Scientific scope
Grood–Suntay floating axis	floating_axis	Stable scalar/batched 3-vector construction; rejects degenerate axes
Newton–Euler and inverse dynamics	newton_euler_force, newton_euler_moment, generalized_loads	Algebraic relations in a common frame; not a full musculoskeletal solver
Static muscle optimization	static_muscle_optimization	Bounded activation cost with a moment constraint
Hill actuator	hill_muscle_force	Algebraic normalized force factors
Hertz contact	hertz_contact_radius, hertz_peak_pressure	Elastic half-space reference, not biphasic cartilage contact
Darcy / biphasic scale	darcy_flux, consolidation_time_s	Hydraulic permeability in m⁴/(N·s); geometry factor omitted from time scale
QLV	qlv_stress	Trapezoidal hereditary integral with dimensionless reduced relaxation g(0)=1
Dispersed GOH/HGO-type ligament mechanics	hgo_strain_energy	Isochoric, two-family, tension-only fibre energy with kappa; no volumetric term
Bone mechanostat	bone_density_rate	SED-driven schematic adaptation with a lazy zone
Cell/tissue tests	aspiration, SLS, conical and spherical indentation	Idealized linear material/test assumptions
Finite growth	finite_growth_decomposition	Orientation-preserving multiplicative decomposition
Mechanosensors	channel_open_probability	Generic phenomenological logistic response
OA feedback	simulate_oa_feedback	Bounded, phenomenological, hypothesis-generating states; rates are per year

See scientific scope for the complete units and validity-domain table, paper mapping for the distinction between direct equations and repository-level synthesis, and the audited model provenance registry for source roles and DOIs.

Python API

from kneemechbridge.multiscale import MultiscaleKneeModel, SimulationConfig

config = SimulationConfig(
    body_mass_kg=75,
    activity="level_walking",
    loading_scale=1.0,
    contact_area_mm2=1200,
    cartilage_thickness_mm=2.2,
    elapsed_loading_s=1.0,
)
result = MultiscaleKneeModel().simulate(config)

print(result.whole_joint.contact_force_n)
print(result.tissue.fluid_pressure_mpa)
print(result.tissue.apparent_solid_strain)
print(result.turnover.reason)
print(result.validation_summary())

The uncalibrated cell transfer must be enabled explicitly:

from kneemechbridge.multiscale import (
    MembraneTransferConfig,
    MultiscaleKneeModel,
    SimulationConfig,
)

heuristic_config = SimulationConfig(
    activity="stair_descent",
    allow_heuristic_cell_transfer=True,
    membrane_transfer=MembraneTransferConfig(coupling_fraction=0.001),
)
heuristic_result = MultiscaleKneeModel().simulate(heuristic_config)
print(heuristic_result.mechanosensors.piezo_open_probability)

Those cell values are sensitivity outputs, not physiological thresholds.

Reproducing examples from the review

The examples reproduce transparent software scenarios built from concepts and cohort-level inputs summarized in the review. They do not reproduce every source experiment.

Activity loading:

from kneemechbridge import MultiscaleKneeModel, SimulationConfig

result = MultiscaleKneeModel().simulate(
    SimulationConfig(activity="stair_ascent", body_mass_kg=75),
    record_reproducibility=True,
)
print(result.contact_force_n, result.mean_contact_pressure_mpa)
result.save_json("outputs/stair_ascent.json")

Uncertainty propagation:

from kneemechbridge import SimulationConfig
from kneemechbridge.uncertainty import monte_carlo, summarize

samples = monte_carlo(SimulationConfig(activity="level_walking"), n=1000, seed=7)
print(summarize(samples))  # scenario spread, not a clinical confidence interval

Surrogate comparison:

from kneemechbridge import SimulationConfig
from kneemechbridge.surrogate import train_surrogate

benchmark = train_surrogate(SimulationConfig(), n_samples=800, seed=7)
print(benchmark.r2, benchmark.mae, benchmark.rmse)

Run the complete flagship case with one command:

uv run --frozen python examples/reproduce_multiscale_case.py

It saves strict JSON, nominal and Monte Carlo CSV files, interval summaries, and a plain-text report under outputs/reproducible_case/. Timestamps document the run; seeded numerical tables are deterministic in a fixed dependency environment.

Scientific benchmarks and figures

Five regression scenarios cover two-leg standing, level walking, stair ascent, stair descent, and deep knee bend. Each includes nominal cross-scale outputs, seeded central 90% scenario intervals, validation status, and domain warnings.

uv run --frozen python benchmarks/generate_reference_results.py
uv run --frozen python scripts/figures/generate_all.py

Benchmark methods and tolerances are documented in benchmarks/README.md. The figure command regenerates Figures A-F as 320 dpi PNG and vector SVG files in outputs/figures/. Generated outputs/ are intentionally ignored and regenerable; seeded numerical tables are reproducible in the locked environment. The small versioned regression reference is benchmarks/reference_results.json.

Clean-checkout reproduction

From a new, unmodified checkout, run the following commands exactly:

uv sync --frozen --extra app --group dev
uv run --frozen python scripts/validate_repository.py
uv run --frozen python examples/reproduce_multiscale_case.py
uv run --frozen python scripts/figures/generate_all.py
uv run --frozen kneemechbridge benchmark
uv run --frozen streamlit run app/dashboard.py --server.headless true --server.port 8501

While Streamlit is running, curl --fail http://127.0.0.1:8501/_stcore/health must return ok; then stop the server with Ctrl+C. The flagship example and figure generator recreate outputs/, which remains outside the versioned source tree.

Command-line interface

uv run --frozen kneemechbridge --help
uv run --frozen kneemechbridge simulate --activity stair_descent --mass 75 --area 1200 --seed 7 --json
uv run --frozen kneemechbridge uncertainty --activity level_walking --samples 1000 --seed 7
uv run --frozen kneemechbridge validate
uv run --frozen kneemechbridge models
uv run --frozen kneemechbridge benchmark

Inputs are checked for finite physical domains and JSON output is strict. Invalid values produce a concise command-line error rather than a scientific traceback. Legacy option-first calls such as kneemechbridge --activity level_walking remain compatible and are interpreted as simulate.

Streamlit dashboard

uv run --frozen streamlit run app/dashboard.py

The dashboard provides:

• activity, body-mass/loading, geometry, and cartilage-property controls;
• whole-joint, tissue stress/strain/fluid, optional cell, and sensor outputs;
• an explicit unavailable turnover transition;
• seeded Monte Carlo intervals and Spearman sensitivity screening;
• ML surrogate R², MAE, RMSE, training ranges, and OOD guidance;
• the bounded OA hypothesis and cartilage-property state;
• run-specific validation status at all six scales;
• conservative digital-model maturity criteria.

Uncertainty framework

from kneemechbridge import SimulationConfig
from kneemechbridge.uncertainty import monte_carlo, sensitivity_summary, summarize

config = SimulationConfig(activity="level_walking")
samples = monte_carlo(config, n=2000, seed=7)
intervals = summarize(samples)
sensitivity = sensitivity_summary(samples)
print(samples.attrs["uncertainty"])

The sampler varies loading scale, contact area, cartilage thickness, aggregate modulus, hydraulic permeability, and fluid fraction. When the heuristic cell link is enabled, upstream uncertainty reaches its cell outputs. Every distribution is independent and explicitly marked as an uncalibrated scenario assumption. Central 90% quantiles describe simulated scenario spread; they are not clinical confidence intervals, Bayesian credible intervals, or population reference ranges. Seeds ensure reproducibility within a fixed dependency environment.

Machine-learning surrogate

The ExtraTrees surrogate uses a seeded split and estimator, rejects target leakage, reports R²/MAE/RMSE, stores its scenario context and feature bounds, and warns when prediction rows leave any axis-aligned training range.

A surrogate can faithfully reproduce its parent simulation while the parent simulation itself may still be biologically incorrect or insufficiently validated.

Surrogate fidelity is not biological validity and is not clinical validity.

Validation ladder

Runtime gates distinguish absent outputs from weakly validated ones:

Scale	Required comparison	Default status
Whole-joint force	Instrumented implant telemetry / validated musculoskeletal data	anchored to a small TKR cohort
Tissue mechanics	Pressure, imaging, cadaveric and specimen-specific tests	model_dependent
Chondron/cell mechanics	Microscopy, AFM and aspiration	not_evaluated by default
Mechanotransduction	Calcium, electrophysiology and perturbation experiments	not_evaluated by default
Matrix turnover	Assays, histology and compositional imaging	not_evaluated
Clinical progression	Prospective longitudinal external cohorts	not_evaluated

Enabling the heuristic cell transfer changes only the chondron/cell run status to uncalibrated/illustrative. It does not validate turnover or OA progression.

Digital-model maturity

DigitalTwinMaturity defines:

1. STATIC_MODEL
2. DIGITAL_SHADOW
3. RESEARCH_TWIN
4. CLINICALLY_VALIDATED_TWIN

The included DigitalShadow performs repeated scalar Gaussian state assimilation with uncertainty and optional process variance. It is capped at DIGITAL_SHADOW. A digital twin requires, at minimum, repeated patient-state updating, data assimilation, counterfactual prediction, uncertainty estimation, and external validation. This repository lacks validated counterfactual and external clinical components and therefore cannot be classified as a clinical digital twin.

OA feedback model

The OA module separates normalized mechanical exposure/overload, cartilage degradation, inflammation, subchondral bone adaptation, pain/activity-mediated loading, and a cartilage-property fraction. Saturating source and sink terms keep states invariant in [0, 1]; bounds are not manufactured by clipping runaway solutions. Coefficients are uncalibrated per-year demonstration rates. A single trajectory must not be interpreted as biological truth or an individual prognosis.

Tests and quality checks

uv run --frozen python scripts/validate_repository.py

Tests include analytical equation cases, shape/broadcast behavior, zero loads, invalid physical inputs, monotonicity and conservation checks, QLV quadrature, OA long-horizon invariance, Monte Carlo/ML reproducibility, leakage and OOD guards, CLI errors, data/code consistency, typed pipeline smoke tests, and a Streamlit application render. The validation command runs Ruff, strict mypy checks over the scientific core, pytest with at least 85% package coverage, packaging checks, and CLI/import smoke tests.

Project structure

app/dashboard.py                 Streamlit research dashboard
benchmarks/                      five versioned scientific regression cases
data/                            activity, evidence and parameter reference tables
docs/scientific_scope.md         assumptions, units and validity domains
docs/paper_mapping.md            published-article-to-code traceability
docs/model_registry.md           human-readable provenance summary
examples/reproduce_multiscale_case.py  flagship reproducible experiment
scripts/figures/                 deterministic publication-figure generator
src/kneemechbridge/model_registry.json packaged machine-readable provenance
src/kneemechbridge/registry.py   Python traceability API
src/kneemechbridge/equations.py  scientific equation utilities
src/kneemechbridge/multiscale.py typed transmission chain
src/kneemechbridge/evidence.py   scale-specific validation ladder
src/kneemechbridge/uncertainty.py seeded scenario propagation and sensitivity
src/kneemechbridge/surrogate.py  parent-model fidelity benchmark and OOD guard
src/kneemechbridge/oa_feedback.py bounded phenomenological OA hypothesis
src/kneemechbridge/digital_shadow.py scalar assimilation and maturity terminology
tests/                           scientific, integration, CLI and app tests

Data provenance and scientific limitations

data/activity_loads.csv contains representative mean peak resultant tibiofemoral forces from five instrumented-TKR subjects reported by Kutzner et al. (2010). These are not native-knee norms or patient-level distributions. data/parameter_ranges.csv contains author-curated scenario bounds whose row-level literature sources remain pending; they vary with depth, site, disease, protocol, geometry, and fitting method.

The project does not:

• reproduce OpenSim/AnyBody inverse dynamics or subject-specific muscle control;
• solve subject-specific finite-element contact or local tissue fields;
• validate the apparent strain estimate outside its reduced linear assumptions;
• infer a universal tissue-strain threshold for PIEZO or TRPV4;
• implement a calibrated mechanosensor-to-turnover transfer;
• fit OA dynamics to longitudinal human outcomes;
• demonstrate clinical utility, treatment benefit, or regulatory readiness.

Citation

Use CITATION.cff to cite the software and its associated article:

Stańczak, M.; Kacprzak, B.; Hagner-Derengowska, M. From Joint Loading to Osteoarthritis: A Multiscale Review of Knee Mechanobiology and Digital Modelling. Int. J. Mol. Sci. 2026, 27, 7462. https://doi.org/10.3390/ijms27167462

The code is MIT licensed. The article is open access under CC BY 4.0; source data and any third-party material remain subject to their respective rights and provenance terms.