Fast, validated solvers for inertial microcavitation rheometry — measuring how soft materials behave at strain rates a rheometer cannot reach, by watching a bubble collapse inside them.
Built for inference campaigns that need thousands of forward solves: closed-form hot paths for the common constitutive laws, exact forward sensitivities from the production right-hand side, and Bayesian model comparison on top.
pip install pyimrimport numpy as np
from pyimr import NeoHookeanKelvinVoigt, SimulationConfig, simulate
t = np.linspace(0.0, 120e-6, 300)
config = SimulationConfig(
R0=225e-6,
Req=37.5e-6,
material=NeoHookeanKelvinVoigt(shear_modulus_pa=2500.0, viscosity_pa_s=0.1),
)
result = simulate(t, config)
result.radius_ratio # R(t)/R0
result.internal_pressure_paEvery input is dimensional, and every material is explicit and typed — no integer constitutive selector, no shared bag of parameters.
| bubble dynamics | dynamics= Rayleigh-Plesset, Keller-Miksis, Keller enthalpy, Herring, Gilmore, Lezzi-Prosperetti (2nd order); the last four take liquid_eos= Tait, Mie-Gruneisen or Noble-Abel stiffened gas |
| thermodynamics | polytropic closure, or gas and liquid thermal PDEs with vapor transport |
| discretization | Chebyshev collocation (default) or second-order finite difference |
| forcing | constant, Gaussian, histotripsy, Heaviside step, or a sampled pressure history |
| materials | hyperelastic, generalized-Newtonian, viscoelastic memory, distributed nonlinear memory |
Materials compose: pick an elastic law and a viscous law and combine them, or
reach for a closed-form memory model when it applies. Neo-Hookean, Mooney-Rivlin,
Yeoh, Fung, Gent, Arruda-Boyce and Ogden on the elastic side; Carreau-Yasuda,
Cross, Powell-Eyring, Herschel-Bulkley and Bingham on the viscous side; the Zener
family (linear, quadratic, cubic, two-mode and Carreau-thinning), Oldroyd-B and
linear Maxwell in closed form; Giesekus and linear PTT as distributed memory.
RelaxingMaterial puts a Maxwell arm on any elastic law. See
docs/materials.md.
Sensitivities. The tangent-linear solver differentiates the production RHS, not a surrogate — across materials, thermal states, forcing and geometry. Six simultaneous gradients cost about 1.9 forward solves.
Inference. Prepared likelihoods with analytic Jacobians, deterministic multistart, and process-parallel batch evaluation. A PyMC bridge runs NUTS on the exact tangents.
Model selection. Constitutive models nest, so comparing best fits always
favors the flexible ones. pyimr.selection scores by evidence instead, with
redundancy and Occam penalties.
Knowing your resolution. pyimr.resolution measures the cheapest grid and
tolerance meeting an accuracy target on your problem, and raises rather than
guessing when the target is out of reach.
Experiment design. pyimr.design scores a design that has not been run;
pyimr.measure optimizes over a batch of them and returns a certificate of
global optimality with the answer; pyimr.gain scores any question, a material
parameter or a model label, in nats, so one batch can serve several;
pyimr.discriminate screens which rivals are still worth an experiment;
pyimr.pareto traces the front when the criteria disagree.
Knowing why a solve failed. pyimr.diagnose separates a step budget, a
material-domain violation and an ill-conditioned trajectory, which raise the
same error. pyimr.store caches solves and failures on disk so a re-run of an
unchanged study costs nothing. pyimr.assimilation runs 4D-Var and ensemble
state estimation on the exact tangents.
See docs/usage.md.
The suite pins IMRv2 trajectories across radial equations, forcing, vapor, heat transfer, mass transfer, and the specialized constitutive models, and separately checks closed forms, reduction limits, and every analytic tangent against independent centered differences.
PyIMR reproduces IMRv2 except where upstream is wrong. Eight defects were found and each correction validated against something other than upstream — a closed form, an independent equation of state, or a reduction limit.
pytest # everything, including numerical validation
pytest -m "not slow" # skip the high-resolution convergence studiesThe suite prints a table of measured deviations after the run, not just pass/fail: a check that still passes but has moved an order of magnitude is visible.
| Usage | solving, sensitivities, inference, model selection, experiment design, diagnostics |
| Materials | every constitutive law, and what each one requires |
| Accuracy | what error each tolerance and discretization actually buys |
| Discretization | stress quadrature and the two thermal backends |
| Validation | what the suite pins, and per-case deviations from IMRv2 |
| Upstream | defects found in IMRv2, and what PyIMR does instead |
| Boundaries | where PyIMR stops, and where it diverges deliberately |
API reference: pip install 'PyIMR[docs]', then python tools/api_docs.py
(every public module; python -m pdoc pyimr alone stops at the package page).
If you use PyIMR, please cite it via CITATION.cff, along with:
- Estrada, Barajas, Henann, Johnsen & Franck, High strain-rate soft material characterization via inertial cavitation, JMPS (2018). https://doi.org/10.1016/j.jmps.2017.12.006
- Warnez & Johnsen, Numerical modeling of bubble dynamics in viscoelastic media with relaxation, Physics of Fluids 27, 063103 (2015). https://doi.org/10.1063/1.4922598
Built with some initial guidance from IMRv2.
MIT — see LICENSE.
This code in this tool was built, in part, with Anthropic Claude Code Opus 5. The documentation was sketched and polished via the same tool.