Physics Modules

Overview

MrHyDE is designed to allow for rapid development of physics modules with automatic coupling to any existing physics module. This is achieved by having a lightweight and simple format for the physics modules that derives from a common base class. The physics modules are also isolated from the rest of code. Only the physics interface interacts with the physics modules, and the modules themselves only interact with the workset and the function manager. The MrHyDE repository has a number of physics modules to serve as examples for future users. Some of the more interesting (or more developed) physics modules live in external repositories and are not open source. Adding in a new physics module is straightforward and this part of the code rarely changes.

In general, weak formulations of partial differential equations can have three different types of contributions: volumetric, boundary and face. In MrHyDE, we consider general equations of the form

$$ V(u,v) + B(u,v) + F(u,v) = 0, $$

where $u$ is the solution, $v$ is the test function, and $V$, $B$, and $F$ represent the volumetric, boundary and face contributions respectively. As a concrete example, consider a Poisson equation on some domain $\Omega \subset \mathbb{R}^d$ with mixed (Robin) boundary conditions:

$$ -\nabla \cdot (\mathbf{K} \nabla u) = f, \quad x\in \Omega $$ $$ \mathbf{K} \nabla u \cdot \mathbf{n} + \alpha u = g, \quad x \in \partial \Omega, $$

The weak formulation seeks $u\in V = H^1(\Omega)$ such that,

$$ \int_{\Omega} \left(\mathbf{K} \nabla u \cdot \nabla v - f v\right) \ dx + \int_{\partial \Omega} \left(\alpha u-g \right) v \ ds = 0, $$

for all $v \in V$. The first term represents $V(u,v)$ and the second represents $B(u,v)$. While this example is linear, any of the contributions can be nonlinear in $u$. Thanks to the utilization of automatic differentiation, the Jacobian is automatically computed from the residual, regardless of the complexity in residuals.

Solving Fully Coupled Multi-physics Problems

Any number of physics modules can be added to a simulation and solved fully coupled or iteratively. In this section, we focus on the fully-coupled case and the next section will illustrate the iteratively coupled case. The key to enabling both of these cases is the workset object. Worksets span both physics modules and physics sets, which are groups of physics modules. They always know the latest available solutions for all physics in the problem and can provide this information at the integration points for any variable, regardless of the physics module.

Setting up a multiphysics system is simple:

Physics:
    modules: 'navier stokes, cdr'
    Dirichlet conditions:
      ux:
        bottom: '0.0'
        top: '0.0'
      uy:
        bottom: '0.0'
        top: '0.0'
      c:
        bottom: '0.0'
        top: '0.0'
    usePSPG: true
  Discretization:
    order:
      ux: 1
      uy: 1
      pr: 1
      c: 1
    quadrature: 2

While one can solve this system of equations, they are not yet coupled together. One simple way to couple the equations is through the definitions of source terms and coefficients. Both the Navier Stokes module and the convection-diffusion-reaction (cdr) module can read in functions defined in the input file, so we couple the equations through these:

Functions:
    source ux: '1.0'
    source uy: '0.1*c^2'
    source: 'exp(bubble)'
    diffusion: '0.01'
    xvel: 'ux'
    yvel: 'uy'
    reaction: '0.0'
    SUPG tau: '0.0'
    bubble: '-10.0*(x-2)*(x-2) - 10.0*(y-0.5)*(y-0.5)'

Here, we have set the convection velocities to be the fluid velocities and introduced a nonlinear source term in the Navier Stokes equation that depends on the concentration of the advected field. Thus, there is a two-way coupling between these equations.

Physics Sets and Iterative Coupling

The concept of physics sets was recently introduced into MrHyDE to allow for multiphysics systems to be iteratively coupled and to enable operator splitting time-integration methods, such the leap-frog scheme for Maxwell's equations. The idea is quite simple. Each physics set is a group of equations that are solved together. Going back to the example in the previous section, the following input file would create two physics sets:

Physics:
    physics set names: "Fluid, CDR"
    Fluid:
      modules: 'navier stokes'
      Dirichlet conditions:
        ux:
          bottom: '0.0'
          top: '0.0'
        uy:
          bottom: '0.0'
          top: '0.0'
      usePSPG: true
    CDR:
      modules: "cdr"
      Dirichlet conditions:
        c:
          bottom: '0.0'
          top: '0.0'

Sets are solved in the order they are given in physics set names. Therefore, this input file would instruct MrHyDE to first solve the fluid equations, then solve the CDR equation. By itself, this is just one way coupling since the fluid has not seen the updated values from the CDR equation. If this is a transient problem, then this is a first-order operator splitting method. However, one can also introduce subcycling between the physics sets to converge (hopefully) to the fully coupled solution. Of course, convergence of such operator decomposition schemes is not guaranteed.