Core Ratel Functions#

These functions are publicly exposed for users.

enum RatelSolverType#

Specify numerical method.

Values:

enumerator RATEL_SOLVER_STATIC#

Static solver, to be solved with a PETSc SNES.

enumerator RATEL_SOLVER_QUASISTATIC#

Quasistatic solver, to be solved with a PETSc TS.

enumerator RATEL_SOLVER_DYNAMIC#

Fully dynamic solver, to be solved with a PETSc TS.

enum RatelForcingType#

Specify forcing term.

Values:

enumerator RATEL_FORCING_NONE#

No forcing term.

enumerator RATEL_FORCING_CONSTANT#

Constant forcing given by forcing vector.

enumerator RATEL_FORCING_MMS#

Forcing for linear elasticity manufactured solution.

enum RatelInitialConditionType#

Specify initial condition.

Values:

enumerator RATEL_INITIAL_CONDITION_ZERO#

Initial condition zero vector.

enumerator RATEL_INITIAL_CONDITION_CONTINUE#

Initial condition given by binary file.

enum RatelMultigridType#

Specify multigrid strategy.

Values:

enumerator RATEL_MULTIGRID_P_COARSENING_LOGARITHMIC#

P-multigrid, coarsen logarithmically, decreasing basis order to next lowest power of 2.

enumerator RATEL_MULTIGRID_P_COARSENING_UNIFORM#

P-multigrid, coarsen uniformly, decreasing basis order by 1.

enumerator RATEL_MULTIGRID_P_COARSENING_USER#

P-multigrid, user defined coarsening strategy.

enumerator RATEL_MULTIGRID_AMG_ONLY#

AMG only preconditioning.

enumerator RATEL_MULTIGRID_NONE#

No multigrid preconditioning.

typedef struct Ratel_private *Ratel#

Library context created by RatelInit()

PetscErrorCode RatelHasMMS(Ratel ratel, PetscBool *has_mms)#

Determine if Ratel context has MMS solution.

Parameters:

  • ratel – [in] Ratel context

  • has_mms – [out] Boolean flag if Ratel context has MMS solution

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelComputeMMSL2Error(Ratel ratel, Vec U, PetscInt *num_fields, PetscScalar **l2_error)#

Compute the L2 error from the manufactured solution.

Note: User is responsible for freeing array of L2 error values

Parameters:

  • ratel – [in] Ratel context

  • U – [in] Computed solution vector

  • num_fields – [out] Number of L2 error values

  • l2_error – [out] Computed L2 error for solution compared to MMS

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelGetExpectedStrainEnergy(Ratel ratel, PetscScalar *expected_strain_energy)#

Retrieve expected strain energy, or NULL if no strain energy set.

Parameters:

  • ratel – [in] Ratel context

  • expected_strain_energy – [out] Expected strain energy

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelComputeStrainEnergy(Ratel ratel, Vec U, PetscScalar time, PetscScalar *strain_energy)#

Compute the final strain energy in the computed solution.

Parameters:

  • ratel – [in] Ratel context

  • U – [in] Computed solution vector

  • time – [in] Final time value, or 1.0 for SNES solution

  • strain_energy – [out] Computed strain energy

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelGetSurfaceForceFaces(Ratel ratel, PetscInt *num_faces, const PetscInt **face_numbers)#

List mesh face numbers for diagnostic force computation.

Parameters:

  • ratel – [in] Ratel context

  • num_faces – [out] Number of faces where forces are computed

  • face_numbers – [out] DMPlex mesh face numbers

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelComputeSurfaceForces(Ratel ratel, Vec U, PetscScalar time, PetscScalar **surface_forces)#

Compute surface forces on mesh faces.

Note: The component i of the centroid for face f is at index surface_forces[(2 * num_comp) * f + i]. The component i of the force for face f is at index surface_forces[(2 * num_comp + 1) * f + i].

Parameters:

  • ratel – [in] Ratel context

  • U – [in] Computed solution vector

  • time – [in] Final time value, or 1.0 for SNES solution

  • surface_forces – [out] Computed face forces - caller is responsible for freeing

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelComputeReactionForces(Ratel ratel, Vec U, PetscScalar time, PetscScalar **reaction_forces)#

Compute reaction forces on mesh faces.

Parameters:

  • ratel – [in] Ratel context

  • U – [in] Computed solution vector

  • time – [in] Final time value, or 1.0 for SNES solution

  • reaction_forces – [out] Computed face reaction forces - caller is responsible for freeing

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelComputeDiagnosticQuantities(Ratel ratel, Vec U, PetscScalar time, Vec *D)#

Compute diagnostic quantities.

Parameters:

  • ratel – [in] Ratel context

  • U – [in] Computed solution vector

  • time – [in] Final time value, or 1.0 for SNES solution

  • D – [out] Computed diagonstic quantities vector

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelTSMonitorStrainEnergy(TS ts, PetscInt steps, PetscReal time, Vec U, void *ctx)#

RatelTSMonitor function for strain energy.

Parameters:

  • ts – [in] TS object to monitor

  • steps – [in] Iteration number

  • time – [in] Current time

  • U – [in] Current state vector

  • ctx – [in] Monitor context holding Ratel context object

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelTSMonitorSurfaceForces(TS ts, PetscInt steps, PetscReal time, Vec U, void *ctx)#

RatelTSMonitor function for surface forces.

Parameters:

  • ts – [in] TS object to monitor

  • steps – [in] Iteration number

  • time – [in] Current time

  • U – [in] Current state vector

  • ctx – [in] Monitor context holding Ratel context object

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelTSMonitorReactionForces(TS ts, PetscInt steps, PetscReal time, Vec U, void *ctx)#

RatelTSMonitor function for face reaction forces.

Parameters:

  • ts – [in] TS object to monitor

  • steps – [in] Iteration number

  • time – [in] Current time

  • U – [in] Current state vector

  • ctx – [in] Monitor context holding Ratel context object

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelTSMonitorDiagnosticQuantities(TS ts, PetscInt steps, PetscReal time, Vec U, void *ctx)#

RatelTSMonitor function for diagnostic quantities (VTK/VTU viewer)

Parameters:

  • ts – [in] TS object to monitor

  • steps – [in] Iteration number

  • time – [in] Current time

  • U – [in] Current state vector

  • ctx – [in] Monitor context holding Ratel context object

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelTSMonitorCheckpoint(TS ts, PetscInt steps, PetscReal time, Vec U, void *ctx)#

RatelTSMonitor function for binary checkpoints.

Parameters:

  • ts – [in] TS object to monitor

  • steps – [in] Iteration number

  • time – [in] Current time

  • U – [in] Current state vector

  • ctx – [in] Monitor context holding Ratel context object

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelTSMonitorSet(Ratel ratel, TS ts, RatelTSMonitorFunction monitor)#

Set Ratel TSMonitor function.

Parameters:

  • ratel – [in] Ratel context

  • ts – [in] TS object to monitor

  • monitor – [in] Monitor function to set

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelTSSetup(Ratel ratel, TS ts)#

Setup default TS options, the DM, and options from command line.

Note: Sets SNES defaults from RatelSNESSetDefaults().

Parameters:

  • ratel – [in] Ratel context

  • ts – [inout] TS object to setup

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelTSSetDefaults(Ratel ratel, TS ts)#

Setup default TS options.

Note: Sets SNES defaults from RatelSNESSetDefaults().

Parameters:

  • ratel – [in] Ratel context

  • ts – [inout] TS object to setup

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelTSSetFromOptions(Ratel ratel, TS ts)#

Set additional Ratel specific TS options. 

   `-ts_monitor_strain_energy` sets TSMonitor function for strain energy
   `-ts_monitor_surface_force viewer:filename.extension` sets TSMonitor function for surface forces
   `-ts_monitor_diagnostic_quantities viewer:filename.extension` sets TSMonitor function for diagnostic quantities
   `-ts_monitor_checkpoint viewer:filename.extension` sets TSMonitor function for solution checkpoint binaries

Parameters:

  • ratel – [in] Ratel context

  • ts – [inout] TS object to setup

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelSNESSetup(Ratel ratel, SNES snes)#

Setup default SNES options, the DM, and options from command line.

Parameters:

  • ratel – [in] Ratel context

  • snes – [inout] SNES object to setup

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelSNESSetDefaults(Ratel ratel, SNES snes)#

Setup default SNES options.

Note: Sets default SNES line search to critical point method.

Parameters:

  • ratel – [in] Ratel context

  • snes – [inout] SNES object to setup

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelTSSetupPC(Ratel ratel, RatelMultigridType multigrid_type, TS ts)#

Setup preconditioner from Ratel context.

Parameters:

  • ratel – [in] Ratel context

  • multigrid_type – [in] Multigrid strategy

  • ts – [out] TS object with multigrid preconditioner

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelSNESSetupPC(Ratel ratel, RatelMultigridType multigrid_type, SNES snes)#

Setup preconditioner from Ratel context.

Parameters:

  • ratel – [in] Ratel context

  • multigrid_type – [in] Multigrid strategy

  • snes – [out] SNES object with multigrid preconditioner

Returns:

An error code: 0 - success, otherwise - failure

static PetscErrorCode RatelSetupMultigridLevel(Ratel ratel, Vec M_loc, CeedVector m_loc, PetscInt level, CeedOperator op_jacobian, CeedOperator op_prolong, CeedOperator op_restrict)#

Setup libCEED operators for multigrid prolongation, restriction, and coarse grid Jacobian evaluation.

Parameters:

  • ratel – [in] Ratel context

  • M_loc – [in] PETSc Vec holding multiplicity data

  • m_loc – [in] libCEED vector for multiplicity data

  • level – [in] Multigrid level to set up

  • op_jacobian – [inout] Composite CeedOperator for Jacobian

  • op_prolong – [inout] Composite CeedOperator for prolongation

  • op_restrict – [inout] Composite CeedOperator for restriction

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelKSPSetupPC(Ratel ratel, RatelMultigridType multigrid_type, KSP ksp)#

Setup preconditioner from Ratel context.

Note: Sets default KSP to Conjugate Gradient or Generalized Minimal Residual for more complex problems. Sets the default PC for the multigrid_type given in the arguments or command line options. Use -ksp_view and -pc_view to see the final KSP and PC.

Parameters:

  • ratel – [in] Ratel context

  • multigrid_type – [in] Multigrid strategy

  • ksp – [out] KSP object with multigrid preconditioner

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelTSSetupInitialCondition(Ratel ratel, TS ts, Vec U)#

Setup inital conditions for TS based upon command line options.

Parameters:

  • ratel – [in] Ratel context

  • ts – [inout] TS to setup

  • U – [out] Global vector to set with initial conditions

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelSNESSetupInitialCondition(Ratel ratel, SNES snes, Vec U)#

Setup inital conditions for SNES based upon command line options.

Parameters:

  • ratel – [in] Ratel context

  • snes – [inout] SNES to setup

  • U – [out] Global vector to set with initial conditions

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelTSCheckpointFinalSolutionFromOptions(Ratel ratel, TS ts, Vec U)#

Checkpoint final solution for TS.

Parameters:

  • ratel – [in] Ratel context

  • ts – [in] TS to checkpoint

  • U – [out] Global vector to checkpoint

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelSNESCheckpointFinalSolutionFromOptions(Ratel ratel, SNES snes, Vec U)#

Checkpoint final solution for SNES.

Parameters:

  • ratel – [in] Ratel context

  • snes – [in] SNES to checkpoint

  • U – [out] Global vector to checkpoint

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelGetVersion(int *major, int *minor, int *patch, PetscBool *release)#

Get Ratel library version info.

Ratel version numbers have the form major.minor.patch. Non-release versions may contain unstable interfaces.

The caller may pass NULL for any arguments that are not needed.

See also

RATEL_VERSION_GE()

Parameters:

  • major – [out] Major version of the library

  • minor – [out] Minor version of the library

  • patch – [out] Patch (subminor) version of the library

  • release – [out] True for releases; false for development branches.

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelInit(MPI_Comm comm, Ratel *ratel)#

Setup Ratel context object Note: This function call initializes the libCEED context.

Parameters:

  • comm – [in] MPI communication object

  • ratel – [out] Ratel context object

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelView(Ratel ratel, PetscViewer viewer)#

View a Ratel context Note: This function can be called with the command line option -ratel_view

Parameters:

  • ratel – [in] Ratel context to view

  • viewer – [in] Optional visualization context

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelDestroy(Ratel *ratel)#

Destroy a Ratel context.

Parameters:

  • ratel – [inout] Ratel context object to destroy

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelDMCreate(Ratel ratel, RatelSolverType solver_type, DM *dm)#

Create DM with SNES or TS hooks from Ratel context.

Parameters:

  • ratel – [in] Ratel context

  • solver_type – [in] Numerical method to use

  • dm – [out] DMPlex object with SNES and TS hooks

Returns:

An error code: 0 - success, otherwise - failure

RATEL_VERSION_MAJOR#

Ratel library version numbering.

RATEL_VERSION_GE(major, minor, patch)#

Compile-time check that the the current library version is at least as recent as the specified version.

This macro is typically used in 

#if RATEL_VERSION_GE(0, 1, 0)
  code path that needs at least 0.1.0
#else
  fallback code for older versions
#endif

A non-release version always compares as positive infinity.

See also

RatelGetVersion()

Parameters:

  • major – Major version

  • minor – Minor version

  • patch – Patch (subminor) version