API Documentation

The Ratel API sets up a PETSc DM object with the data to run a SNES or TS solver for solid mechanics problems. This DM is set for a SNES or TS via SNESSetDM or TSSetDM to provide a complete solver for a solid mechanics problem.

The API also includes functions to set sensible defaults for the TS, SNES, and KSP as well as set up geometric multigrid with PCMG. The default options depend upon the RatelSolverType.

Lastly, the Ratel API includes convenience functions to facilitate computing diagnostic quantities of interest. These quantities of interest can be monitored on every time step via command line options or computed at the end of the solve with the convenience functions.

Ratel Public API

The public API provides core functionality for users.

Ratel Internal API

The internal API builds composite CeedOperator for the residual, Jacobian, and diagnostic quantity evaluation. These composite CeedOperator are used to set the appropriate DMSNES or DMTS options, depending upon the RatelSolverType.

Ratel internal API

The internal API is organized around RatelMaterial, separate material regions in the domain. See the Using Ratel section of the documentation for details on how the user specifies a material region with model parameters for the mesh.

Each RatelMaterial is responsible for adding volumetric terms to the residual, Jacobian, and diagnostic quantity evaluation operators as well as any surface terms that require volumetric or material model values. Additionally, each RatelMaterial is responsible for building and modifying corresponding preconditioner components, as needed.

Boundary and forcing terms that do not require volumetric or material model parameters, such as Dirichlet boundary conditions, are handled separately from a RatelMaterial.

New RatelMaterial are added by creating a file src/materials/new-material.c with the material model data, material creation function, and material registration function. Any new QFunction source files go in include/ratel/qfunctions, and the material is added to src/materials/ratel-model-list.h.

Any new CeedQFunction created for a RatelMaterial must list their CeedQFunction inputs and outputs in the following order, omitting any inputs or outputs that are not applicable:

Inputs:

  • Quadrature point data, such as integration weights and change of coordinate matrices

  • State data, such as plastic state

  • Stored values, such as residual evaluation data stored for reuse in the Jacobian

  • Model variables and their derivatives, as needed

  • Additional inputs as needed by the specific CeedQFunction

Outputs:

  • Current state data

  • Stored values for material model

  • Action of the operator the QFunction represents

  • Additional outputs as needed by the specific CeedQFunction

The RatelModel associated with the RatelMaterial can specify the following CeedQFunction

  • setup_q_data_volume - volumetric quadrature data setup

  • setup_q_data_surface - surface quadrature data for integration setup

  • setup_q_data_surface_grad - surface quadrature data for gradients setup

  • residual_u - nonlinear residual evaluation

  • residual_ut - nonlinear residual evaluation time derivative term

  • residual_utt - nonlinear residual evaluation time second derivative term

  • jacobian - linear Jacobian evaluation

  • jacobian_block - block suboperators by field for Jacobian evaluation

  • strain_energy - strain energy evaluation

  • projected_diagnostic - diagnostic values projected from quadrature space to the dual space

  • dual_diagnostic - diagnostic values computed on the dual space

  • contact_residual_u - residual evaluation for contact boundary conditions

  • contact_jacobian - Jacobian evaluation for contact boundary conditions

  • mms_boundary - MMS Dirichlet boundary values

  • mms_forcing - MMS forcing term

  • mms_error - MMS error against true solution

  • surface_force_cell_to_face - state in cells used to evaluate strain and stresses on the face, stress integrated to get forces on the surface

Numerical solvers

These functions setup the numerical solver and preconditioner.

Material models

These functions setup the material regions in the mesh.

Boundary conditions

These functions apply boundary conditions.

Internal functions

These functions are internal setup and application functions.