hIPPyMFEM

User guide

  • Installation
    • Requirements
    • Step by step
    • A single-precision hypre
    • Docker
    • Running the tests
    • Cross-validation against hIPPYlibx
  • Concepts
    • The residual density
    • The blocks, and where they come from
    • Variables and the state vector
    • The three objects of an inverse problem
    • Densities a form language cannot express
    • What you do not write
  • Finite element spaces
    • What each family gives the density
    • Why vector elements need more than a sign
    • Quadrature
    • Limitations
  • Boundary terms
    • The full gradient is available on the boundary
    • Selecting part of the boundary
    • Boundary functionals on their own
    • Not supported
  • Interior facet terms and DG
    • What the density is given
    • Faces shared between ranks
    • A worked example
    • What is checked
  • Priors
    • Sampling
    • Other priors
  • Observations and misfits
    • Pointwise data
    • Distributed data
    • Others
    • The noise covariance
  • Linear solvers
    • Letting the size choose
    • Krylov with a hypre preconditioner
    • Exact solves, including in parallel
    • Genuinely distributed direct solvers
    • A solve that only preconditions
    • Choosing
  • Finding the MAP point
    • Inexact Newton-CG
    • The CG of a Newton step
    • Gradient norms
    • BFGS
    • Verifying a new problem
  • The posterior
    • The Laplace approximation
    • What the posterior gives
    • Choosing k
    • Solvers matter here
  • MCMC
    • Reporting a chain honestly
    • Cost
  • Forward uncertainty propagation
    • A quantity of interest
    • The parameter-to-QoI map
    • Taylor approximations with variance reduction
    • After the data
  • Time-dependent problems
    • The initial state
    • Why the previous level is a differentiation slot
    • Operators along the trajectory
    • Scalar parameters
    • Time-dependent vectors
  • Running on a GPU
    • What runs where
    • Turning it on
    • Recommended settings
    • What to expect
    • Where the device loses
    • Single precision
    • Several GPUs
    • How large a problem fits
    • Reproducibility and correctness
    • The Laplace approximation on the cards
    • Taking exactly the GPUs and cores you asked for
    • AMD cards
    • Going further
  • Configuration
    • Set before the import
    • Every other setting, one object
  • Performance
    • Where the time goes
    • How an assembly is built
    • CPU against GPU
    • What the GPU does not accelerate
    • Scaling
    • What a linearization point assembles
    • Measuring it yourself
  • Parallel correctness
    • The rule
    • Ways to break it
    • Partition independence
    • Assembly in parallel
    • Object lifetime
  • An application: basin-scale geothermal inversion
    • The problem
    • Running it
    • What it gives
    • Three things to check in a problem of your own

Tutorials

  • MFEM101: solving a PDE with hIPPyMFEM
    • Weak formulation
    • Residual densities
    • 1. Load modules
    • 2. Define the mesh and the finite element space
    • 3. Define boundary labels
    • 4. Define the coefficients of the PDE and the boundary conditions
    • 5. Define and solve the variational problem
    • 6. Compute the discretization error
    • 7. Convergence of the finite element method
    • 8. A nonlinear problem, with nothing more to write
  • Coefficient field inversion in an elliptic partial differential equation
    • The variational (or weak) form of the state equation:
    • Gradient evaluation:
    • Hessian action:
    • Inexact Newton-CG:
    • Discrete Newton system:
    • What hIPPyMFEM writes for you
    • Goals:
    • Mathematical tools used:
    • List of software used:
    • Set up
      • Import dependencies
      • Model set up:
      • The forward problem:
      • Set up synthetic observations:
      • The cost function evaluation:
      • Initial guess
      • The reduced Hessian apply to a vector \(\bhm\):
    • The inexact Newton-CG optimization with Armijo line search:
    • The same inversion with the library
  • Bayesian quantification of parameter uncertainty
    • Estimating the Gaussian approximation of the posterior pdf of the coefficient parameter field in an elliptic PDE
      • Bayes’ Theorem:
      • Gaussian prior and noise:
      • The Laplace approximation to the posterior: \(\mathcal{N}({\vec \map},\bf \postcov)\)
    • This tutorial shows:
    • Goals:
    • Mathematical tools used:
    • List of software used:
    • 1. Load modules
    • 2. Generate the true parameter
    • 3. Set up the mesh and finite element spaces
    • 4. Set up the forward problem
    • 5. Set up the prior
    • 6. Set up the misfit functional and generate synthetic observations
    • 7. Set up the model and test gradient and Hessian
    • 8. Compute the MAP point
    • 9. Compute the low rank-based Laplace approximation of the posterior
    • 10. Prior and Laplace approximation to posterior pointwise variance fields
    • 11. Generate samples from the prior and the Laplace approximation to the posterior
  • Bayesian initial condition inversion in an advection-diffusion problem
    • The Bayesian inverse problem:
    • The forward problem:
    • The adjoint problem:
    • In hIPPyMFEM
    • 1. Load modules
    • 2. Construct the velocity field
    • 3. Set up the mesh and finite element spaces
    • 4. Set up model (prior, true/proposed initial condition)
    • 5. Generate the synthetic observations
    • 6. Test the gradient and the Hessian of the cost (negative log posterior)
    • 7. Evaluate the gradient
    • 8. The Gaussian posterior
    • 9. Compute the MAP point
    • 10. Prior and posterior pointwise variance fields
    • 11. Draw samples from the prior and posterior distributions
  • Spectrum of the preconditioned Hessian misfit operator
    • The linear source inversion problem
    • 1. Load modules
    • 2. The linear source inversion problem
    • 3. Solution of the source inversion problem
    • 4. Mesh independence of the spectrum of the preconditioned Hessian misfit
    • 5. Dependence on the noise level
    • 6. Dependence on the PDE coefficients
  • Sampling the posterior with MCMC
    • Bayesian quantification of the uncertainty in the coefficient field of an elliptic PDE
      • Bayes’ Theorem:
      • Gaussian prior and noise:
      • The Gaussian approximation of the posterior: \(\mathcal{N}({\vec \map},\bf \postcov)\)
      • Markov chain Monte Carlo
    • This tutorial shows:
    • Mathematical tools used:
    • List of software used:
    • 1. Load modules
    • 2. Generate the true parameter
    • 3. Set up the mesh and finite element spaces
    • 4. Set up the forward problem
    • 5. Set up the prior
    • 6. Set up the misfit functional and generate synthetic observations
    • 7. Set up the model and test gradient and Hessian
    • 8. Compute the MAP point
    • 9. Compute the low rank Gaussian approximation of the posterior
    • 10. Prior and posterior pointwise variance fields
    • 11. Generate samples from the prior and the Laplace approximation of the posterior
    • 12. Define a quantity of interest
    • 13. Compute posterior expectations using MCMC
    • 14. How much is the chain worth?
  • Gaussian priors in infinite dimensions
    • Import dependencies
    • Plot the marginal variance and correlation structure at a given point
      • The 1D case
      • The 2D case
    • Generating Samples
      • Isotropic samples
      • Anisotropic samples with \(\alpha = \frac{\pi}{4}\)
      • Anisotropic samples with \(\alpha = -\frac{\pi}{4}\)
    • Mesh Dependence and Independence
      • Laplacian plots
      • BiLaplacian Plots
  • Residuals as programs: a law no form language can write
    • 1. Load modules
    • 2. Mesh, spaces and boundary conditions
    • 3. The constitutive law, as data
    • 4. The residual density
    • 5. Data, prior, model
    • 6. The derivatives nobody wrote
    • 7. The inverse problem
    • What to take from this
  • On the GPU: the same script, different hardware
    • 1. Choose the device, then import
    • 2. Check, do not assume
    • 3. A problem, timed on this machine
    • 4. What the device path actually costs
    • 5. Memory: three knobs worth knowing
    • 6. More than one card
    • Where to look next
  • Densities on faces: discontinuous Galerkin
    • 1. Load modules
    • 2. A discontinuous space
    • 3. Three densities
    • 4. The plume
    • 5. The face terms are differentiated too
    • What to take from this
  • Vector fields and mixed systems
    • 1. Load modules
    • 2. A vector state: a beam of unknown stiffness
    • 3. The density, with tensors in it
    • 4. Observing a vector field
    • 5. The inverse problem, unchanged
    • 6. Where the measurements reach
    • 7. Families whose basis functions are vectors
    • 8. Two unknowns, two families
    • What to take from this
  • Predicting a number, not a field
    • 1. Load modules
    • 2. The flow problem, and the number we care about
    • 3. The map has derivatives
    • 4. A quadratic model, with moments in closed form
    • 5. Monte Carlo on the difference
    • 6. The same question after the data
    • What to take from this

Reference

  • API reference
    • Finite element layer
      • hippymfem.fem.spaces
      • hippymfem.fem.elementbatch
      • hippymfem.fem.kernel
      • hippymfem.fem.vectorfe
      • hippymfem.fem.boundary
      • hippymfem.fem.facets
      • hippymfem.fem.csrassemble
      • hippymfem.fem.pattern
      • hippymfem.fem.prolongation
      • hippymfem.fem.parmat
      • hippymfem.fem.elimination
      • hippymfem.fem.assemble
      • hippymfem.fem.coefficients
      • hippymfem.fem.bcs
      • hippymfem.fem.jaxops
      • hippymfem.fem.io
    • Modeling layer
      • hippymfem.modeling.variables
      • hippymfem.modeling.PDEProblem
      • hippymfem.modeling.PDEVariationalProblem
      • hippymfem.modeling.TimeDependentPDEVariationalProblem
      • hippymfem.modeling.prior
      • hippymfem.modeling.misfit
      • hippymfem.modeling.pointwiseObservation
      • hippymfem.modeling.model
      • hippymfem.modeling.reducedHessian
      • hippymfem.modeling.posterior
      • hippymfem.modeling.modelVerify
      • hippymfem.modeling.timeDependentVector
    • Algorithms
      • hippymfem.algorithms.NewtonCG
      • hippymfem.algorithms.bfgs
      • hippymfem.algorithms.steepestDescent
      • hippymfem.algorithms.cgsolverSteihaug
      • hippymfem.algorithms.linSolvers
      • hippymfem.algorithms.directSolvers
      • hippymfem.algorithms.multivector
      • hippymfem.algorithms.randomizedEigensolver
      • hippymfem.algorithms.randomizedSVD
      • hippymfem.algorithms.lowRankOperator
      • hippymfem.algorithms.traceEstimator
      • hippymfem.algorithms.cgsampler
    • MCMC
      • hippymfem.mcmc.chain
      • hippymfem.mcmc.kernels
      • hippymfem.mcmc.tracers
      • hippymfem.mcmc.diagnostics
    • Forward UQ
      • hippymfem.forward_uq.qoi
      • hippymfem.forward_uq.variationalQoi
      • hippymfem.forward_uq.parameter2QoiMap
      • hippymfem.forward_uq.taylorApproximationQoi
      • hippymfem.forward_uq.varianceReductionMC
    • Common
      • hippymfem.common.parvector
      • hippymfem.common.operators
      • hippymfem.common.linalg
      • hippymfem.common.random
      • hippymfem.common.parameterList
      • hippymfem.common.keepalive
      • hippymfem.common.mfemconfig
      • hippymfem.common.identitycache
      • hippymfem.common.mpiutil
    • Configuration object
      • FLAG_TRUE
      • parse_flag()
      • env_flag()
      • parse_tristate()
      • env_tristate()
      • env_choice()
      • PROFILES
      • EXPLICIT
      • apply_profile_env()
      • Config
    • Utilities
      • hippymfem.utils.nb
  • Coming from hIPPYlib
    • Differences that change results
    • Things hIPPyMFEM has that hIPPYlib does not
    • Things hIPPYlib has that hIPPyMFEM does not
  • Verification and validation
    • Against MFEM’s own integrators
    • Against hIPPYlibx on a shared discrete problem
    • Internal consistency
    • Implementation equivalences
    • Partition independence
    • The test suites
  • Limits, stated up front
    • What the AD route does not cover
    • Performance
    • Solvers
    • Randomized eigenvector tails
    • Reproducibility
    • Things that will bite you
    • Maturity

Project

  • Changelog
    • Unreleased
      • Changed
    • Version 0.1.0, released on November 10, 2026
      • Added
      • Changed
      • Removed
      • Fixed
    • First public version, September 21, 2026
      • The library
      • Tutorials, applications and validation
      • Testing and infrastructure
      • Design notes
  • Contributing to hIPPyMFEM
    • Workflow
    • Developer guidelines
    • Pull request checklist
    • Automated testing
    • Developer’s Certificate of Origin 1.1
hIPPyMFEM
  • Search

© Copyright 2026, Peng Chen and contributors.

Built with Sphinx using a theme provided by Read the Docs.