Base PKs#

There are many PKs, and each PK has its own valid input spec. However, there are three main types of PKs, from which nearly all PKs derive. Note that none of these are true PKs and cannot stand alone.

PK#

src/pks/PK.hh

The interface for a Process Kernel, an equation or system of equations.

A process kernel represents a single or system of partial/ordinary differential equation(s) or conservation law(s), and is used as the fundamental unit for coupling strategies.

Implementations of this interface typically are either an MPC (multi-process coupler) whose job is to heirarchically couple several other PKs and represent the system of equations, or a Physical PK, which represents a single equation.

Note there are two PK specs – the first is the “typed” spec, which appears in the “cycle driver” list in the PK tree and has no other parameters other than its type and its children. The second is the spec for the base class PK, which is inherited and included by each actual PK, lives in the “PKs” sublist of “main”, and has all needed parameters.

pk-spec

  • “PK type” [string] One of the registered PK types. Note this must match the corresponding entry in the [pk-typed-spec]

  • “verbose object” [verbose-object-spec] optional See Verbose Object

Example:

<ParameterList name="PK tree">
  <ParameterList name="my cool MPC PK">
    <Parameter name="PK type" type="string" value="my cool MPC PK"/>
    <ParameterList name="sub PK 1">
      ...
    </ParameterList>
    <ParameterList name="sub PK 2">
      ...
    </ParameterList>
    ...
  </ParameterList>
</ParameterList>

PK: Physical#

src/pks/PK_Physical_Default.hh

A physical PK is single PDE or DAE defined on a single mesh, and represents a single process model. Typically all leaves of the PK tree will be a physical PK.

pk-physical-default-spec

  • “domain name” [string] Name from the Mesh list on which this PK is defined.

  • “primary variable key” [string] The primary variable e.g. “pressure”, or “temperature”. Most PKs supply sane defaults.

  • “initial conditions” [initial-conditions-spec] See Initial Conditions.

  • “max valid change” [double] -1 Sets a limiter on what is a valid change in a single timestep. Changes larger than this are declared invalid and the timestep fails. By default, any change is valid. Units are the same as the primary variable.

INCLUDES:

  • [pk-spec] This is a PK.

  • [debugger-spec] Uses a Debugger

PK: BDF#

src/physics/ats/src/pks/pk_bdf_default.hh

A BDF or Backward Difference Formula a process kernel that is integrated in time using an “implicit” or “backwards difference” method. Both Physical PKs and MPCs may be BDF PKs – when an MPC is integrated using a BDF method we say it is coupled through a “globally implicit” method (as opposed to sequential or operator split method).

pk-bdf-default-spec

  • “initial timestep [s]” [double] 1. Initial timestep size used for the first timestep. After this, the “timestep controller” may change the step size.

  • “time integrator” [bdf1-ti-spec] optional A TimeIntegrator_. Note that this is only required if this PK is not strongly coupled to other PKs.

  • “assemble preconditioner” [bool] true A flag, typically not set by user but by an MPC.

  • “inverse” [inverse-typed-spec] optional A Linear Solver or Preconditioner provided as an Inverse. Note that this is only used if this PK is not strongly coupled to other PKs.

INCLUDES:

  • [pk-spec] This is a PK.

PK: Physical and BDF#

src/physics/ats/src/pks/pk_physical_bdf_default.hh

PKs that are both Physical and BDF are likely conservation equations. Given a conserved quantity, we can supply a default error norm for conservation. By default, the error norm used by solvers is given by:

\(ENORM(u, du) = |du| / ( a_{tol} + r_{tol} * |u| )\)

where \(u\) is the conserved quantity and \(du\) is the error in conservation.

The defaults here are typically good, or else good defaults are set in the code, so usually are not supplied by the user.

pk-physical-bdf-default-spec

  • “conserved quantity key” [string] Name of the conserved quantity. Usually a sane default is set by the PK.

  • “absolute error tolerance” [double] 1.0 Absolute tolerance, \(a_{tol}\) in the equation above. Unit are the same as the conserved quantity. Note that this default is often overridden by PKs with more physical values, and very rarely are these set by the user.

  • “relative error tolerance” [double] 1.0 Relative tolerance, \(r_{tol}\) in the equation above. [-] Note that this default can be overridden by PKs with more physical values, and very rarely are these set by the user.

  • “flux error tolerance” [double] 1.0 Relative tolerance on the flux, or face-based error caused by a mismatch in flux from either side of the face. Note that this default is often overridden by PKs with more physical values, and very rarely are these set by the user.

INCLUDES: