PDESolver Physics Interface

Documentation of the PDESolver Physics Module Interface

The PDESolver Module provides some structure for physics modules to plug into. See Interfaces in PDESolver for details. Each physics module should create a new subtype of AbstractSolutionData. This physics module should then extend the required methods, specializing one of the arguments with the new (physics-specific) type. This structure allows the API for the physics module to be visible to other parts of the code (such as NonlinearSolvers), while being defined within the physics module.

One exception to this pattern of defining generic functions and then specializing one argument is the initialization functions. These functions run before the AbstractSolutionData object is created, so they can not dispatch to different methods. Instead, each physics module has to register itself and provide the required initialization functions. See the Registration Functions section.

Functions to be Extended

All the functions in this section should be extended by each physics module with a new method, specializing the type of the eqn argument.

PDESolver.createFunctional — Method.

Creates a functional object.

Each physics modules should extend this function with a new method, specializing the eqn argument.

Inputs

  • mesh : Abstract PUMI mesh

  • sbp : Summation-by-parts operator

  • eqn : AbstractSolutionData object

  • opts : Options dictionary

  • functional_name: the name of the functional

  • functional_bcs: the boundary condition numbers the functional is computed on.

Outputs

source
PDESolver.evalFunctional — Method.

High level function that evaluates the given functional This function is agnostic to the type of the functional being computed and calls a mid level functional-type specific function for the actual evaluation.

The functional is evaluated at the state in eqn.q_vec.

Arguments

  • mesh : Abstract mesh object

  • sbp : Summation-By-Parts operator

  • eqn : AbstractSolutionData object

  • opts : Options dictionary

  • functionalData : Object of type AbstractFunctional. This type determines the functional being computed and holds all the relevant data.

source
PDESolver.evalFunctionalDeriv — Method.

Computes a 3D array of hte derivative of a functional wrt eqn.q.

The derivative is evaluated at the state in eqn.q_vec.

Inputs

  • mesh

  • sbp

  • eqn

  • opts

  • functionalData: AbstractIntegralFunctional to evaluate

Inputs/Outputs

  • func_deriv_arr: array to hold derivative of function wrt eqn.q, same size as equation.q

Options Keys

This funciton is not compatible with precompute_q_bndry = false

source
PDESolver.evalHomotopyJacobian — Method.

Evaluates the Jacobian of the evalHomotopy multiplied by the homotopy parameter lambda. Conceptually similar to evalJacobian.

Inputs

  • mesh: an AbstractMesh

  • sbp: an AbstractSBP

  • eqn: an AbstractSolutionData (physics modules should specialize this argument)

  • opts: options dictionary

  • assembler: an object used to assemble contributions into the Jacobian

  • lambda: the homotopy parameter

source
PDESolver.evalJacobian — Function.

Similar function to evalResidual, but instead of computing the residual, it computes and assembles the Jacobian of the residual with respect to eqn.q into the system matrix.

The functions assembleElement and assembleInterface in NonlinearSolvers should be used to assembles the Jacobians of individual elements and interfaces into the system matrix.

Physics modules that can compute element Jacobians directly should extend this function with a new method, otherwise the coloring algorithm with be used with evalResidual to compute the system matrix. For physics modules that support multiple formuations, this function should throw an exception if called with an unsupported formulation.

Inputs

  • mesh: an AbstractMesh

  • sbp: an SBP operator

  • eqn: AbstractSolutionData (physics modules should specialize this argument)

  • opts: options dictionary

  • assembler: object that must be passed to assembleElement and assembleInterface

Keyword Arguments

  • start_comm: whether or not to start parallel communication, default false because the functions Nonlinear solvers have already done parallel communication when this function gets called.

Options Keys

TODO: describe the key that controls whether this function gets called or not.

source
PDESolver.evalJacobianStrong — Function.

This function evaluates the Jacobian of the strong form of the spatial residual. Note that the residual is written

du/dt = -(Q * f) + SAT

Note the negative sign.

Currently this function neglects the SAT terms (both interface and boundary conditions)

Inputs

  • mesh: an AbstractMesh

  • sbp: an SBP operator

  • eqn: AbstractSolutionData (physics modules should specialize this argument)

  • opts: options dictionary

  • assembler: object that must be passed to assembleElement and assembleInterface

source
PDESolver.evalResidual — Function.

This function evalutes dq/dt = R(q). For steady problems it evalutes R(q) at some state q. The state is stored in eqn.q, and eqn.res is populated with R(q). Note that these are 3 dimensional arrays. The physics modules only interact with the 3 dimensional arrays, never the vectors eqn.q_vec and eqn.res_vec. Each physics module must implement this function for its own subtype of AbstractSolutionData (ie. with a more specific type for the eqn argument and equallty specific types for the other arguments). This is important because evalResidual is common to all physics modules, so a user or some other part of the code can call evalResidual(mesh, sbp eqn, opts), and Julia's multiple dispatch will figure out the right method to call based on the type of the eqn argument.

The evaluation of the residual R(q) should depend only on the data stored in mesh, sbp, eqn, and opts, and any data that depend on q should be recalculated every time the function is called. This function is used as a building block by other parts of the solver, particularly the NonlinearSolvers. See interfaces.md for details

Inputs

  • mesh: an AbstractMesh describing the mesh on which to solve the physics

  • sbp: an SBP operator

  • eqn: a subtype of AbstractSolution data, used to store all of the data used by the physics module

  • opts: the options dictionary

  • t: the current time value, defaults to 0.0

#TODO: list required options keys

source
PDESolver.solvePDE — Function.

This function takes fully initialzed objects and solves the partial differential equation.

Every physics should extend this function with a new method, specialzing the eqn argument type.

Objects can be created with the createObjects function.

The functions in the SolverCommon module are helpful in writing this function.

Inputs

  • mesh: an AbstractMesh

  • sbp: an SBP Operator

  • eqn: an AbstractSolutionData

  • opts: the options dictionary

  • pmesh: mesh for preconditioning (optional)

Outputs

  • mesh

  • sbp

  • eqn: on exit, eqn.q_vec should have the converged solution in it.

  • opts

Options Keys

  • Relfunc_name: also writes vtk files called "solution_relfunc" if key not present, ignored TODO: fix that

  • IC_name

  • calc_error: also write vtk files called "solution_error"

  • calc_trunc_error

  • perturb_ic

  • calc_dt

For options like calc_dt and Relfunc_name, it is very important that
the computed quantity be saved to the options dictionary for use later
in the code (ie. and not passed directly to another function).  The
code won't restart correctly if this happens.
source
PDESolver.updateMetricDependents — Method.

This function recalculates all quantities that depend on the mesh metrics. This function handles changes in the metric values only (not changed in mesh topology).

This function should be called after the mesh is warped (ie. using mesh movement).

Every physics module should extend this function with a new method specializing the eqn argument type.

Inputs

  • mesh

  • sbp

  • eqn

  • opts

source

Additional Functions

These functions are available for all physics module, but do not need to be extended with a new method. They usually boil down to calling one of the functions in the previous section.

PDESolver.createFunctional — Function.

Creates a functional object, using the data described in the options dictionary

Arguments

  • mesh : Abstract PUMI mesh

  • sbp : Summation-by-parts operator

  • eqn : AbstractSolutionData

  • opts : Options dictionary

  • functional_number : which functional (of the functionals described in the options dictionary) to create

Outputs

same as other method

source
PDESolver.createObjects — Method.

This function returns the fully initialized objects needed to solve an equations.

Inputs

  • fname: input file name

Outputs

  • mesh: an AbstractMesh of some kind (depending on input file)

  • sbp: an SBP operator of some kind (depending on input file)

  • eqn: an AbstractSolutionData of some kind (depending on input file)

  • opts: options dictionary

  • pmesh: mesh for computing preconditioning, may be the same object as mesh

source
PDESolver.createObjects — Method.

Method for creating objects from an options dictionary

Inputs

  • opts: the options dictionary

Outputs

see other method
source
PDESolver.createObjects — Method.

This method constructs a new equation object for the given mesh, sbp and opts.

This is useful for solving on a submesh.

Inputs

  • mesh: an AbstractMesh

  • sbp: an AbstractSBP

  • opts: options dictionary

Outputs

same as other method

source
PDESolver.solvePDE — Method.

Additional methods for solvePDE, allows solving the PDE starting with either a file name or options dictionary.

See the other method for details

Inputs

  • opts: either a file name to load an options dictionary from or the options dictionary itself

Outputs

same as other method

source

Registration Functions

These function provide the basic API for registering and retrieving physics modules with the PDESolver module.

PDESolver.register_physics — Function.

This function registered a new physics module with the global list of all known physics modules. Every physics module should do this as part of module initialization. The name, the module, and the startup function must be unique (ie. they must not already exist in the list). This function throws and exception if they are not.

Inputs

  • modname: an String name for this entry in the list. It is used to retrieve the module and startup function in the retrieve_physics function. Typically the name is capitalized.

  • mod: the Module itself

  • _createObjects: function that creates the mesh, sbp, eqn, and opts objects. Must have a method with signature _createObjects(opt::Dict)

                 If this physics modules supports solving on a submesh,
             this function should also have a method
             `_createObjects(mesh::AbstractMesh, sbp::AbstractSBP, opts::Dict)`
             to create a new equation object.  See [`createObjects`](@ref).

  • _checkOptions: physics-specific function for supplying default options and checking options. Note that most of the input option processing is done in read_input, _checkOptions need only do the physics-specific part. This function must have signature _checkOptions(opts::Dict).

Outputs

none
source
PDESolver.retrieve_physics — Function.

Retrieves the physics module and function registered using register_physics

Input

  • modname: an String containing the name of the module supplied to register_physics

Outputs

  • mod: the physics Module

  • _createObjects: function that creates the solver objects

  • _checkOptions: the options checking function

source

See also registerIC and registerBC.