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.
-
enumerator RATEL_SOLVER_STATIC#
-
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.
-
enumerator RATEL_FORCING_NONE#
-
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.
-
enumerator RATEL_INITIAL_CONDITION_ZERO#
-
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.
-
enumerator RATEL_MULTIGRID_P_COARSENING_LOGARITHMIC#
-
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 facef
is at indexsurface_forces[(2 * num_comp) * f + i]
. The componenti
of the force for facef
is at indexsurface_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
- 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
- Parameters:
major – Major version
minor – Minor version
patch – Patch (subminor) version