Repository navigation
diff-soup 1.1.0
New tutorials and worked examples, and the fixes and features found and added while writing them.
Breaking changes
-
spec.observe.{spatial_mean,boundary_mean}now average.fnreturns one value per node, weighted by cell volume or facet measure. Previously the name was only a label. A scalar-valuedfnis now refused.# Before (1.0.0): fn computed the mean spec.observe.spatial_mean(name="T_avg", fn=lambda q: jnp.mean(q.T)) # After: fn returns nodal values spec.observe.spatial_mean(name="T_avg", fn=lambda q: q.T)
-
spec.bc.neumannnow imposesdu/dn = son FVM, FDM and FEM. Previously it was an alias ofspec.bc.flux, which imposesD du/dn = s.name=andcross_facet=are now onfluxonly.# Before (1.0.0): neumann was an alias of flux spec.bc.neumann("u", on="left", value=s) # imposed D du/dn = s # After: say which one you mean spec.bc.flux("u", on="left", value=s) # D du/dn = s spec.bc.neumann("u", on="left", value=s) # du/dn = s
-
Grid boundary conditions and boundary integrals in 2D and 3D now weight each selected cell by one face. Previously edge and corner cells were counted more than once. A selection spanning several faces now raises. Pick one with
axis=andside=. -
Fixed the sign of flux and Robin terms on clockwise meshes, which includes every
mask_to_meshmesh. Element volumes now use|det J|. A tangled element now raises. -
FEM operators now read a 1D coefficient by its length:
num_dofsvalues are nodal andn_cellsvalues are per cell. Previously a per-cell array was read as nodal. -
The residual form
q.dt(...)now works on meshes (previously its coefficients were dropped), and keeps the boundary conditions of the field it writes on grids and meshes alike. -
NewtonTrustRegionandLevenbergMarquardtnow endSTALLED(converged=False) when the trust radius or damping holds a step short of a stopping test. Previously these fits reported converged.result.info["stall_reason"]says why. -
NewtonTrustRegion(hessian=)now defaults to"auto", which picks Gauss-Newton on any problem with residual rows, including everyInferenceProblem.optsolveandconstrained_optsolvefollow. Previously the default was the true Hessian. Passhessian="true"to get it back. -
NewtonTrustRegion(hessian_tile=)now defaults to"auto", and a true Hessian or Gauss-Newton Jacobian too large for the device stops the fit before its first step with aConfigurationError. Previously the default was"full". -
sample(kernel="nuts")now adapts all chains together (adapt="pooled",warmup=200), and each chain keeps its adapted state. Previously one chain adapted for 500 steps and the others started from a perturbed fit.chains=1, adapt="window", warmup=500reproduces the old draws. -
Identifiability checks now skip network columns, including on multi-experiment problems, so a network-only fit no longer warns.
theta_singular_values,jacobian_condandparam_group_condnow cover the non-network columns only. -
stats.linear_solve_modenow reports"fp32_factor"forPrecision.fp32_factor(). Previously it reported"fp32", which now means end-to-end float32 only.
Features
-
Added
ds.compile, which compiles apdesolvecall without running it. The result runs on newt_span,y0andthetaof the same shapes and dtypes, and reportscompile_seconds,cost_analysis()andmemory_analysis(). See Running a simulation.compiled = ds.compile(problem, solver, (0.0, 0.1), y0) sol = compiled((0.0, 0.2), y0)
-
theta[handle]reads a parameter, andtheta.replace(handle, value)writes every copy of it. A theta that went throughjax.tree.map, a device transfer or a tracer still works withds.default_theta. See Learnable parameters. -
Added
ds.parameter_gradient(grads, handle), which readsdloss/dparamfromjax.grad(loss)(theta)and sums the copies of a parameter that several equations read. -
Added
est.values(x)[handle], which reads parameters from a vector in the fit coordinate.ParameterSchemais exported fromds.inference. -
Added
recipe.spec(**inputs), which returns theProblemSpeca recipe authors, andgrid.{coordinates,meshgrid()}on both grid classes. -
Grid transport:
q.ops.advect_upwindtakes velocity fields,q.ops.div_advectis the conservative form, with flux-limited face values by default (scheme="tvd",limiter="van_leer","koren"or"minmod": second order where smooth, no new extrema at any cell Péclet number), third-order"weno3","central"or first-order"upwind", andq.ops.div_fluxtakes a per-axis(Dx, Dy, Dz).spec.bc.{dirichlet,flux,robin,neumann}takeaxis=andside=, and the newspec.bc.inflowgives the Danckwerts condition withdiv_advect. -
spec.bc.periodic(var, axes=(0,))makes a field periodic on some axes and allows other conditions on the rest. -
Mesh regions:
TaggedMesh(cell_tags=, cell_tag_names=),q.ops.cell_indicator(name),polygons_to_tagged_mesh({name: polygon}, ...)with conforming interfaces and per-region edge tags (segment_tags=,segment_names=), andread_meshphysical groups as cell and boundary tags. -
Mesh boundary conditions: flux, Robin and Neumann conditions,
surface_measureandq.ops.boundary_integralon QUAD4, TRI6, QUAD8, HEX8, TET4, TET10, HEX20 and HEX27. A condition bynode_indicesselects the facets whose vertices all lie in the set. -
On a mesh,
Fieldcomposes with weak terms and nodal arrays and supports**,absand comparisons.c * q.dt(field)takes one value ofcper cell. -
Added
ds.inference.approx.WIRE, a coordinate network with the Gabor-wavelet activation of Saragadam et al. (2023) and the interface ofSIREN. See Function approximation. -
The Gauss-Newton Jacobian is now tiled:
NewtonTrustRegion(hessian_tile=)applies to it, andLevenbergMarquardt(jacobian_tile=)is new. Previously an integerhessian_tilewas ignored under Gauss-Newton. See Solvers. -
NUTS options:
sampletakesadapt=,mass=("diag"or"dense"),step_size=andmax_tree_depth=, anddraws.info["adaptation"]records what ran. See MCMC. -
Added
ds.inference.evidence(est, fit)andlaplace(est, fit).log_evidence, the Laplace evidence of a MAP fit. Its stationarity check scales with the solver tolerance and precision of the problem, it accepts float32 posteriors, and a refusal names the solver tolerance.information,laplace,identifiabilityandpredictnow take a multiple-shooting fit. -
Measurement(observe="name")reads aspec.observedeclaration. -
A fit now seeds
with_start,posterior_target,information(at=),identifiability,profile,predictandOptResult.load(problem=)whenever its parameter layout matches. A rebuilt recipe or another solver tolerance no longer refuses it, and a start can be a mapping{handle: value}. -
verify_gradientnow returns averdict:"passed","failed"or"inconclusive". -
ds.default_thetatakes a whole module for a function parameter.
Bugfixes
ds.default_thetaoverrides no longer leak between two problems equal in content. Fixed parameters declared from one array, and functions declared from one module, are now copied.optsolve(checkpoint=)now resumesLevenbergMarquardtandNewtonTrustRegionfits from their saved steps. It refuses a directory written by a fit of other parameters.sample(kernel="nuts")now audits the gradient at a jittered chain start instead of the MAP, where the audit meant nothing. It refuses only a failed audit.posterior_target(gradient="reverse"),log_posteriorandLogDensity.from_callablenow scale their reverse/forward check with the solverrtoland run it one percent away from the start, so a float32 fit passes at its mode.jax.jitandeqx.filter_jitnow compile aLogDensity.- Fixed
ExperimentSet.log_posterior, which raised on every call. - Meshes: a scalar source term in the residual form now builds, a first use under
jax.jitno longer leaves a tracer in the cache, andread_meshno longer reports TET10 meshes as tangled. - Fixed the operator-level
FluxBC: the wrong sign on the low side of an FVM grid, and a crash with a per-cellDon a 2D grid. It now also works on 2D and 3D FDM grids. - Importing JAX before diff-soup no longer turns off constant hoisting, which made closures over large arrays compile to large programs.
Performance
- Fitted window starts now solve each window once per evaluation instead of once per observed frame. With 110 frames in 5 windows the integrated time drops from 1265 to 110. Fitted values are unchanged up to the solver tolerance.
- With fitted window starts, the Gauss-Newton Jacobian now pushes each direction through all windows at once. On an 803-variable FitzHugh-Nagumo fit one Jacobian takes 7.2 s instead of 31.0 s on CPU, 0.78 s instead of 3.30 s on an RTX 4070 Ti, and 0.33 GiB of compiled memory instead of 1.26 GiB.
Precision.fp32_factor()now solves its float32 factors unrefined, as documented. On Gray-Scott 256x256 atrtol=1e-6on an RTX 4070 Ti, a solve drops from 5.10 s to 3.06 s with the same steps and errors.- Fit diagnostics now differentiate only the non-network columns, which removes most of their cost on network fits.
Other
- Better errors:
jax.gradthrough a solve with the default forward-only adjoint raises aValueErrornamingCheckpointAdjoint.pdesolve(theta=)refuses a theta that is not the problem's parameter pytree, andds.default_thetachecks keys, values and shapes. - An end-to-end
Precision.fp32()solve that cannot initialize, as on some stiff DAEs where float32 rounding alone exceeds the tolerance, now says so and namesPrecision.fp32_ir()andPrecision.fp64(). - Warnings now point at your own line. A float32 solve with
jax_enable_x64off no longer prints JAX's truncation warnings from inside diff-soup. - Clearer output: results print as
diff_soup.RESULT<...>,ProblemSpecand the recipe handles print short reprs, and the event-stop and window-rank messages use plain words. - diff-soup now requires
blackjax>=1.7, andmeshiojoins the[mesh]extra. - Docs: Precision explains the mixed modes, recommends
fp32_ir, gives the float32 initialization floor and says that end-to-end float32 fits on a GPU are not bitwise reproducible from run to run. Boundary conditions states the order of a per-cell value on a grid face. The docs now state the float64step_tolandcost_toldefaults (1e-8), whatconvergedmeans, and when to run small problems on the CPU.
Wheels for CPython 3.12 and 3.13 on x86_64 Linux (manylinux_2_28). They carry the KLU sparse direct solver. Install the cuDSS solver with pip install "diff-soup[cu12]" or "diff-soup[cu13]". SHA256SUMS lists the checksums.
Documentation: https://stmorgenstern.github.io/diff-soup/
Full Changelog: v1.0.0...v1.1.0