Core Ratel Functions¶

These functions are publicly exposed for users.

enum RatelSolverType¶

Specify solver type.

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 RatelMethodType¶

Specify numerical method.

Values:

enumerator RATEL_METHOD_FEM¶: FEM method.

enumerator RATEL_METHOD_MPM¶: MPM method.

enum RatelFormulationType¶

Specify model formulation.

Values:

enumerator RATEL_FORMULATION_TOTAL_LAGRANGIAN¶: Total Lagrangian formulation.

enumerator RATEL_FORMULATION_PREVIOUS_LAGRANGIAN¶: Previous Lagrangian formulation.

enum RatelForcingType¶

Specify forcing term.

Values:

enumerator RATEL_FORCING_NONE¶: No forcing term.

enumerator RATEL_FORCING_BODY¶: User-specified body force with interpolation.

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.

enumerator RATEL_INITIAL_CONDITION_MMS¶: Non-zero initial condition for time dependent MMS.

enumerator RATEL_INITIAL_CONDITION_NONZERO¶: Non-zero initial condition.

enum RatelPMultigridCoarseningType¶

Specify p-multigrid coarsening strategy.

Values:

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

enumerator RATEL_P_MULTIGRID_COARSENING_UNIFORM¶: P-multigrid, coarsen uniformly, decreasing basis order by 1.

enumerator RATEL_P_MULTIGRID_COARSENING_USER¶: P-multigrid, user defined coarsening strategy.

enum RatelPointLocationType¶

Specify initial point locations for MPM.

Values:

enumerator RATEL_POINT_LOCATION_GAUSS¶: Initial point locations at Gauss quadrature points in each cell.

enumerator RATEL_POINT_LOCATION_UNIFORM¶: Initial point locations uniformly spaced in each cell.

enumerator RATEL_POINT_LOCATION_CELL_RANDOM¶: Initial point locations randomly distributed in each cell.

enum RatelMPMProjectionType¶

Specify swarm-to-mesh projection type for MPM.

Values:

enumerator RATEL_MPM_PROJECTION_CONSISTENT¶: Swarm-to-mesh projection using KSP with consistent mass matrix.

enumerator RATEL_MPM_PROJECTION_LUMPED¶: Swarm-to-mesh projection using lumped mass matrix.

enum RatelMPMInitializationType¶

Specify how MPM materials should be initialized.

Values:

enumerator RATEL_MPM_INITIALIZATION_DEFAULT¶: Use background mesh regions and materials.

enumerator RATEL_MPM_INITIALIZATION_MATERIAL_MESH¶: Use auxiliary mesh regions and MPM materials.

enumerator RATEL_MPM_INITIALIZATION_VOXEL¶: Use labeled voxel data and MPM materials.

enumerator RATEL_MPM_INITIALIZATION_LAMMPS¶: Use LAMMPS dump file and MPM materials.

enum RatelMPMStabilizationType¶

Specify method for stabilizing MPM stiffness.

Values:

enumerator RATEL_MPM_STABILIZATION_NONE¶: No stabilization.

enumerator RATEL_MPM_STABILIZATION_BACKGROUND_STIFFNESS¶: Add artificial stiffness to background mesh, residual and Jacobian.

enum RatelDirectionType¶

Specify cartesian coordinate direction.

Values:

enumerator RATEL_DIRECTION_X¶: X coordinate direction.

enumerator RATEL_DIRECTION_Y¶: Y coordinate direction.

enumerator RATEL_DIRECTION_Z¶: Z coordinate direction.

enum RatelOutputFieldsType¶

Model field Sub-DM indices.

Values:

enumerator RATEL_OUTPUT_FIELDS_PROJECTED¶: Sub-DM index for projected output fields.

enumerator RATEL_OUTPUT_FIELDS_DUAL¶: Sub-DM index for dual (nodal) output fields.

const char *const RatelSolverTypes[]¶: Pretty-print strings for RatelSolverType

const char *const RatelMethodTypes[]¶: Pretty-print strings for RatelMethodType

const char *const RatelMethodTypesCL[]¶: Command-line option strings for RatelMethodType

const char *const RatelForcingTypes[]¶: Pretty-print strings for RatelForcingType

const char *const RatelForcingTypesCL[]¶: Command-line option strings for RatelForcingType

const char *const RatelInitialConditionTypes[]¶: Pretty-print strings for RatelInitialConditionType

const char *const RatelPMutigridCoarseningTypes[]¶: Pretty-print strings for RatelPMultigridCoarseningType

const char *const RatelPMultigridCoarseningTypesCL[]¶: Command-line option strings for RatelPMultigridCoarseningType

const char *const RatelPointLocationTypesCL[]¶: Command-line option strings for RatelPointLocationType

const char *const RatelMPMProjectionTypes[]¶: Pretty-print strings for RatelMPMProjectionType

const char *const RatelMPMProjectionTypesCL[]¶: Command-line option strings for RatelMPMProjectionType

const char *const RatelMPMInitializationTypes[]¶: Pretty-print strings for RatelMPMInitializationType

const char *const RatelMPMInitializationTypesCL[]¶: Command-line option strings for RatelMPMInitializationType

const char *const RatelMPMStabilizationTypes[]¶: Pretty-print strings for RatelMPMStabilizationType

const char *const RatelMPMStabilizationTypesCL[]¶: Command-line option strings for RatelMPMStabilizationType

const char *const RatelDirectionTypesCL[]¶: Command-line option strings for RatelDirectionType

const char *const RatelElasticityDualOutputFieldsComponentNames[]¶: Common output fields component names.

static PetscErrorCode RatelViewerWriteTimestep_VTKSeries(RatelViewer ratel_viewer, PetscInt steps, PetscReal time, Vec U)¶

Write data and series at a given timestep for VTK series file.

Collective across MPI processes.

Parameters:

ratel_viewer – [in] RatelViewer storing PetscViewerASCII object as its aux_viewer
steps – [in] Timestep number
time – [in] Timestep time
U – [in] Solution vector

Returns:

An error code: 0 - success, otherwise - failure

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

TSMonitor function for strain energy.

Collective across MPI processes.

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

static PetscErrorCode RatelViewerWriteSurfaceForce(RatelViewer viewer, PetscInt steps, PetscReal time, const char *name, const PetscScalar centroid[3], const PetscScalar force[3])¶

Write surface force for a face to a RatelViewer.

Collective across MPI processes.

Parameters:

viewer – [in] RatelViewer context
steps – [in] Current iteration number
time – [in] Current time
name – [in] Name of the face
centroid – [in] Centroid of the face
force – [in] Computed surface force on the face

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelTSMonitorSurfaceForceCellToFace(TS ts, PetscInt steps, PetscReal time, Vec U, void *ctx)¶

TSMonitor function for surface forces.

Collective across MPI processes.

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 RatelTSMonitorSurfaceForce(TS ts, PetscInt steps, PetscReal time, Vec U, void *ctx)¶

TSMonitor function for face surface forces.

Collective across MPI processes.

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 RatelTSMonitorSurfaceForcePerFace(TS ts, PetscInt steps, PetscReal time, Vec U, void *ctx)¶

TSMonitor function for face surface forces.

Collective across MPI processes.

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 RatelViewers context object

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelTSMonitorOutputFields(TS ts, PetscInt steps, PetscReal time, Vec U, void *ctx)¶

TSMonitor function for output fields.

Collective across MPI processes.

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

static PetscErrorCode RatelDMSwarmView_WriteDMInfo(DM dm, RatelViewer ratel_viewer, PetscViewer binary_viewer, PetscInt *offset)¶

Write time, topology, and geometry information for DMSwarm to XDMF file and store binary coordinate data.

Not collective across MPI processes.

Parameters:

dm – [in] DMSwarm object
ratel_viewer – [inout] Ratel viewer storing PetscViewerASCII object
binary_viewer – [inout] PetscViewerBinary object to store topology and coordinate data
offset – [out] Current offset in binary file

Returns:

An error code: 0 - success, otherwise - failure

static PetscErrorCode RatelDMSwarmView_WriteField_Binary(Ratel ratel, DM dm, const char *field, PetscViewer binary_viewer)¶

Write field data for DMSwarm to binary file.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
dm – [in] DMSwarm object
field – [in] Field name to write
binary_viewer – [inout] Viewer to write field data to

Returns:

An error code: 0 - success, otherwise - failure

static PetscErrorCode RatelDMSwarmView_WriteField(DM dm, const char *field, RatelViewer ratel_viewer, PetscViewer binary_viewer, PetscInt *offset)¶

Write field data for DMSwarm to XDMF file and store binary field data.

Not collective across MPI processes.

Parameters:

dm – [in] DMSwarm object
field – [in] Field name to write
ratel_viewer – [inout] Ratel viewer storing PetscViewerASCII object
binary_viewer – [inout] PetscViewerBinary object to store field data
offset – [out] Current offset in binary file

Returns:

An error code: 0 - success, otherwise - failure

static PetscErrorCode RatelDMSwarmSubViewerCreate(DM dm, RatelViewer ratel_viewer, PetscViewer *binary_viewer)¶

Create a sub-viewer for DMSwarm to store binary data.

Collective across MPI processes.

Parameters:

dm – [in] DMSwarm object
ratel_viewer – [in] Ratel viewer storing PetscViewerASCII object
binary_viewer – [out] Created PetscViewerBinary object for the current timestep

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelTSMonitorSwarm(TS ts, PetscInt steps, PetscReal time, Vec U, void *ctx)¶

TSMonitor function for swarm data.

Collective across MPI processes.

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 RatelTSMonitorSwarmSolution(TS ts, PetscInt steps, PetscReal time, Vec U, void *ctx)¶

TSMonitor function for swarm solution (with minimal additional data).

Collective across MPI processes.

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_MPM(Ratel ratel, DM dm_swarm, PetscViewer viewer)¶

Monitor checkpoint data for DMSwarm to binary file.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
dm_swarm – [in] DMSwarm object
viewer – [inout] Binary viewer to write field data to

Returns:

An error code: 0 - success, otherwise - failure

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

TSMonitor function for binary checkpoints.

Collective across MPI processes.

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 RatelCheckpointDataRead(Ratel ratel, const char filename[], PetscBool check_hash, RatelCheckpointData *data)¶

Read RatelCheckpointData from a binary file.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
filename – [in] Continue file name
check_hash – [in] Flag to determine whether to check the SHA256 hash of the binary file, overwritten by -continue_file_skip_hash
data – [out] Pointer to store created RatelCheckpointData object

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelCheckpointDataDestroy(RatelCheckpointData *data)¶

Destroy RatelCheckpointData.

Collective across MPI processes.

Parameters:

data – [out] RatelCheckpointData object to destroy

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelCheckpointCtxCreateFromOptions(Ratel ratel, const char opt[], const char text[], RatelCheckpointCtx *ctx, PetscBool *set)¶

Create a RatelCheckpointCtx object from PetscOptions command line handling.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
opt – [in] TS monitor flag
text – [in] Description of the flag
ctx – [out] RatelCheckpointCtx object to create
set – [out] PetscBool indicating if the flag was set

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelCheckpointCtxCreate(Ratel ratel, PetscInt interval, PetscBool toggle, const char file_name[], RatelCheckpointCtx *ctx)¶

Create a RatelCheckpointCtx object.

Not collective across MPI processes.

Parameters:

ratel – [in] Ratel context
interval – [in] Checkpoint interval
toggle – [in] Flag to toggle between two files
file_name – [in] Base file name for checkpoint files
ctx – [out] RatelCheckpointCtx object to create

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelCheckpointCtxDestroy(RatelCheckpointCtx *ctx)¶

Destroy RatelCheckpointCtx.

Not collective across MPI processes.

Parameters:

ctx – [inout] RatelCheckpointCtx object to destroy

Returns:

An error code: 0 - success, otherwise - failure

static PetscErrorCode RatelViewerWriteHeader_CSV(RatelViewer ratel_viewer, void *ctx)¶

Write header for CSV file.

Collective across MPI processes.

Parameters:

ratel_viewer – [in] RatelViewer storing PetscViewerASCII object
ctx – [out] Header string

Returns:

An error code: 0 - success, otherwise - failure

static PetscErrorCode RatelViewerWriteHeader_VTKSeries(RatelViewer ratel_viewer, void *ctx)¶

Write header for VTK series file.

Collective across MPI processes.

Parameters:

ratel_viewer – [in] RatelViewer storing PetscViewerASCII object as its aux_viewer
ctx – [out] Context, unused

Returns:

An error code: 0 - success, otherwise - failure

static PetscErrorCode RatelViewerWriteFooter_VTKSeries(RatelViewer ratel_viewer)¶

Write footer for VTK series file.

Collective across MPI processes.

Parameters:

ratel_viewer – [in] RatelViewer storing PetscViewerASCII object as its aux_viewer

Returns:

An error code: 0 - success, otherwise - failure

static PetscErrorCode RatelViewerWriteHeader_XDMF(RatelViewer ratel_viewer, void *ctx)¶

Write header for XDMF file.

Collective across MPI processes.

Parameters:

ratel_viewer – [inout] Ratel viewer storing PetscViewerASCII object
ctx – [in] Context, unused

Returns:

An error code: 0 - success, otherwise - failure

static PetscErrorCode RatelViewerWriteFooter_XDMF(RatelViewer ratel_viewer)¶

Write footer for XDMF file.

Collective across MPI processes.

Parameters:

ratel_viewer – [inout] Ratel viewer storing PetscViewerASCII object

Returns:

An error code: 0 - success, otherwise - failure

static PetscErrorCode RatelGetViewerInfo(Ratel ratel, const char value[], char **type, char **filename, PetscViewerFormat *format, PetscFileMode *file_mode)¶

Split a viewer specification string into its components, type, filename, format, and file mode.

Not collective across MPI processes.

Note

Adapted from PetscOptionsCreateViewers_Single() in petsc/src/sys/classes/viewer/interface/viewreg.c.

Parameters:

ratel – [in] Ratel context
value – [in] Viewer specification string
type – [out] Pointer to PetscViewerType string
filename – [out] Pointer to filename string
format – [out] PetscViewerFormat enum, if specified
file_mode – [out] PetscFileMode enum, if specified

Returns:

An error code: 0 - success, otherwise - failure

Post:

type and filename point to NULL or allocated strings, and must be freed by the caller.

static PetscErrorCode RatelViewerStringIsCSV(Ratel ratel, const char type[], const char filename[], PetscBool *is_csv)¶

Check if a viewer of type type with filename filename is a CSV viewer.

Not collective across MPI processes.

Parameters:

ratel – [in] Ratel context
type – [in] PetscViewerType string
filename – [in] File name string
is_csv – [out] Pointer to PetscBool to store whether the resulting viewer should be a CSV viewer

Returns:

An error code: 0 - success, otherwise - failure

static PetscErrorCode RatelViewerStringIsXDMF(Ratel ratel, const char type[], const char filename[], PetscBool *is_xdmf)¶

Check if a viewer of type type with filename filename is a XDMF viewer.

Not collective across MPI processes.

Parameters:

ratel – [in] Ratel context
type – [in] PetscViewerType string
filename – [in] File name string
is_xdmf – [out] Pointer to PetscBool to store whether the resulting viewer should be a XDMF viewer

Returns:

An error code: 0 - success, otherwise - failure

static PetscErrorCode RatelLoadViewerFromCheckpoint_CSV(Ratel ratel, const char filename[], RatelCheckpointData checkpoint_data, PetscViewer *viewer)¶

Load an existing CSV file into a PetscViewer and move the file pointer to start writing at the checkpointed step.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
filename – [in] File name of the CSV file
checkpoint_data – [in] RatelCheckpointData object
viewer – [out] Created PetscViewer, or NULL if the old file is empty.

Returns:

An error code: 0 - success, otherwise - failure

static PetscErrorCode RatelLoadViewerFromCheckpoint_XDMF(Ratel ratel, const char filename[], RatelCheckpointData checkpoint_data, PetscViewer *viewer)¶

Load an existing XDMF file into a PetscViewer and move the file pointer to start writing at the checkpointed step.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
filename – [in] File name of the XDMF file
checkpoint_data – [in] RatelCheckpointData object
viewer – [out] Created PetscViewer, or NULL if the old file is empty.

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelViewerCreateFromOptions(Ratel ratel, const char opt[], const char text[], RatelViewer *monitor_viewer, PetscBool *set)¶

Create a RatelViewer object from PetscOptions command line handling.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
opt – [in] TS monitor flag
text – [in] Description of the flag
monitor_viewer – [out] RatelViewer object to create
set – [out] PetscBool indicating if the flag was set

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelViewerListCreateFromOptions(Ratel ratel, const char opt[], const char text[], RatelViewer monitor_viewers[], PetscInt *num_viewers, PetscBool *set)¶

Create the list of RatelViewer object from PetscOptions command line handling.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
opt – [in] TS monitor flag
text – [in] Description of the flag
monitor_viewers – [out] Array of RatelViewer objects to create
num_viewers – [out] Number of RatelViewer objects created
set – [out] PetscBool indicating if the flag was set

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelViewerCreate(Ratel ratel, PetscViewer viewer, PetscViewerFormat viewer_format, PetscInt interval, RatelViewer *monitor_viewer)¶

Create a RatelViewer object.

Not collective across MPI processes.

Parameters:

ratel – [in] Ratel context
viewer – [in] PetscViewer object to use
viewer_format – [in] PetscViewerFormat object to use
interval – [in] Monitor interval
monitor_viewer – [out] RatelViewer object to create

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelViewerDestroy(RatelViewer *monitor_viewer)¶

Destroy viewer data for RatelViewer.

Not collective across MPI processes.

Parameters:

monitor_viewer – [inout] RatelViewer object to destroy

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelViewerWriteHeader(RatelViewer ratel_viewer, void *ctx)¶

Write header for a RatelViewer.

Collective across MPI processes.

Parameters:

ratel_viewer – [in] RatelViewer context
ctx – [out] Header context, optional

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelViewerWriteFooter(RatelViewer ratel_viewer)¶

Write footer for a RatelViewer.

Collective across MPI processes.

Parameters:

ratel_viewer – [in] RatelViewer context

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelViewerGetSequenceFilename(RatelViewer ratel_viewer, PetscInt steps, PetscSizeT filename_size, char filename[])¶

Get the filename for an entry in a sequence of files.

The filename is {ratel_viewer->monitor_file_name}_{steps}.{ratel_viewer->monitor_file_extension}.

Collective across MPI processes.

Parameters:

ratel_viewer – [in] RatelViewer context
steps – [in] Timestep number
filename_size – [in] Size of filename
filename – [out] String to store the filename, must be preallocated

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelViewerShouldWrite(RatelViewer viewer, TS ts, PetscInt steps, PetscBool *should_write)¶

Determine whether the RatelViewer should write at the current time step.

Not collective across MPI processes.

Parameters:

viewer – [in] RatelViewer object
ts – [in] TS object
steps – [in] Current number of time steps
should_write – [out] True if the viewer should write at the current time step

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelViewersCreateFromOptions(Ratel ratel, const char opt[], const char text[], PetscInt num_viewers, const char **names, RatelViewers *viewer_list, PetscBool *set)¶

Create a RatelViewers object from PetscOptions command line handling.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
opt – [in] TS monitor flag
text – [in] Description of the flag
num_viewers – [in] Number of viewers to create
names – [in] Names for each viewer
viewer_list – [out] RatelViewer object to create
set – [out] PetscBool indicating if the flag was set

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelViewersCreate(Ratel ratel, PetscViewer viewer, PetscViewerFormat viewer_format, PetscInt interval, PetscInt num_viewers, const char **names, RatelViewers *viewer_list)¶

Create a RatelViewers object.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
viewer – [in] PetscViewer object to use
viewer_format – [in] PetscViewerFormat object to use
interval – [in] Monitor interval
num_viewers – [in] Number of viewers to create
names – [in] Names for each viewer
viewer_list – [out] RatelViewers object to create

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelViewersDestroy(RatelViewers *viewer_list)¶

Destroy viewer list data for RatelViewers.

Collective across MPI processes.

Parameters:

viewer_list – [inout] RatelViewers object to destroy

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelHasMMS(Ratel ratel, PetscBool *has_mms)¶

Determine if Ratel context has MMS solution.

Output fields.

Not collective across MPI processes.

Parameters:

ratel – [in] Ratel context
has_mms – [out] Boolean flag indicating if Ratel context has MMS solution

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelIsCeedBP(Ratel ratel, PetscBool *is_ceed_bp)¶

Determine if Ratel context is using a single material with a Ceed BP material model.

Not collective across MPI processes.

Parameters:

ratel – [in] Ratel context
is_ceed_bp – [out] Boolean flag indicating if Ratel context is using single Ceed BP material model

Returns:

An error code: 0 - success, otherwise - failure

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

Compute the L2 error from the manufactured solution.

Caller is responsible for freeing l2_error.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
U – [in] Computed solution vector
time – [in] Final time value, or 1.0 for SNES solution
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 RatelViewMMSL2ErrorFromOptions(Ratel ratel, PetscScalar time, Vec U)¶

View MMS L2 error.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
time – [in] Final time value, or 1.0 for SNES solution
U – [in] Final solution vector

PetscErrorCode RatelGetExpectedStrainEnergy(Ratel ratel, PetscBool *has_expected, PetscScalar *expected_strain_energy)¶

Retrieve expected strain energy.

Not collective across MPI processes.

Parameters:

ratel – [in] Ratel context
has_expected – [out] PETSC_TRUE if expected strain energy was set
expected_strain_energy – [out] Expected strain energy

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelGetExpectedMaxDisplacement(Ratel ratel, PetscInt *num_components, PetscBool has_expected[], PetscScalar expected_max_displacement[])¶

Retrieve expected max displacements.

Not collective across MPI processes.

Parameters:

ratel – [in] Ratel context
num_components – [inout] Size of input arrays / number of output components
has_expected – [out] Boolean array, PETSC_TRUE at index if expected value set for component
expected_max_displacement – [out] Expected max displacement for component

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelGetExpectedFaceSurfaceForce(Ratel ratel, const char *face, PetscInt *num_components, PetscBool has_expected[], PetscScalar expected_surface_force[])¶

Retrieve expected surface forces on face.

Not collective across MPI processes.

Parameters:

ratel – [in] Ratel context
face – [in] Face name
num_components – [inout] Size of input arrays / number of output components
has_expected – [out] Boolean array, PETSC_TRUE at index if expected value set for component
expected_surface_force – [out] Expected surface forces

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelGetExpectedFaceCentroid(Ratel ratel, const char *face, PetscInt *num_components, PetscBool has_expected[], PetscScalar expected_centroid[])¶

Retrieve expected centroid of face.

Not collective across MPI processes.

Parameters:

ratel – [in] Ratel context
face – [in] Face name
num_components – [inout] Size of input arrays / number of output components
has_expected – [out] Boolean array, PETSC_TRUE at index if expected value set for component
expected_centroid – [out] Expected centroid values

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelComputeStrainEnergyError(Ratel ratel, PetscScalar strain_energy, PetscBool *has_expected, PetscScalar *strain_energy_error)¶

Compute the error between the expected and final strain energy.

Not collective across MPI processes.

Parameters:

ratel – [in] Ratel Context
strain_energy – [in] Computed final strain energy
has_expected – [out] PETSC_TRUE if expected strain energy provided
strain_energy_error – [out] Computed error in the final strain energy

PetscErrorCode RatelComputeMaxDisplacementError(Ratel ratel, PetscInt num_components, const PetscScalar max_displacement[], PetscBool *has_any_expected, PetscScalar max_displacement_error[])¶

Compute the error between the expected and final maximum displacements.

Not collective across MPI processes.

Parameters:

ratel – [in] Ratel Context
num_components – [in] Number of components of the input and output arrays
max_displacement – [in] Computed final maximum displacements
has_any_expected – [out] PETSC_TRUE if expected maximum displacement provided for any component
max_displacement_error – [out] Computed error in the final maximum displacements

PetscErrorCode RatelViewMaxSolutionValuesErrorFromOptions(Ratel ratel, PetscScalar time, Vec U)¶

Compute max solution error.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
time – [in] Final time value, or 1.0 for SNES solution
U – [in] Final solution vector

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelComputeFaceForceErrors(Ratel ratel, const char *face, PetscInt num_components, const PetscScalar centroid[], const PetscScalar surface_force[], PetscBool *has_any_expected_centroid, PetscBool *has_any_expected_surface_force, PetscScalar centroid_error[], PetscScalar surface_force_error[])¶

Compute the error between the expected and final face forces and centroids.

Not collective across MPI processes.

Parameters:

ratel – [in] Ratel Context
face – [in] Face name
num_components – [in] Number of components of the input and output arrays
centroid – [in] Computed final centroid for face
surface_force – [in] Computed final surface forces for face
has_any_expected_centroid – [out] PETSC_TRUE if expected centroid provided for face
has_any_expected_surface_force – [out] PETSC_TRUE if expected surface force provided for face
centroid_error – [out] Computed error in the final centroid for face
surface_force_error – [out] Computed error in the final surface force for face

PetscErrorCode RatelViewSurfaceForceAndCentroidErrorFromOptions(Ratel ratel, PetscScalar time, Vec U)¶

Compute surface force and centroid errors.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
time – [in] Final time value, or 1.0 for SNES solution
U – [in] Final solution vector

Returns:

An error code: 0 - success, otherwise - failure

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

Compute the final strain energy in the computed solution.

Collective across MPI processes.

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 RatelViewStrainEnergyErrorFromOptions(Ratel ratel, PetscScalar time, Vec U)¶

Compute strain energy error.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
time – [in] Final time
U – [in] Final solution vector

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelComputeMaxVectorValues(Ratel ratel, DM dm, Vec U, PetscReal time, PetscInt *num_fields, char ***field_names, PetscInt **num_components, PetscScalar max_values[])¶

Compute maximum values of global vector U.

Caller is responsible for freeing field_names and num_components.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
dm – [in] DM for U
U – [in] Global vector
time – [in] Current solution time
num_fields – [out] Number of field
field_names – [out] Name of the fields
num_components – [out] Size of output buffer/number of components
max_values – [out] Computed max values of all fields

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelComputeMaxSolutionValues(Ratel ratel, Vec U, PetscReal time, PetscInt *num_fields, char ***field_names, PetscInt **num_components, PetscScalar max_values[])¶

Compute maximum values of solution.

Caller is responsible for freeing field_names and num_components.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
U – [in] Computed solution vector
time – [in] Current solution time
num_fields – [out] Number of field
field_names – [out] Name of the fields
num_components – [out] Size of output buffer/number of components
max_values – [out] Computed max values of all fields

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelComputeMaxOutputFields(Ratel ratel, Vec U, PetscScalar time, PetscInt *num_output_fields_components, const char *output_fields_component_names[], PetscScalar max_output_fields[])¶

Compute requested maximum output_fields from options.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
U – [in] Final solution vector
time – [in] Final time value, or 1.0 for SNES solution
num_output_fields_components – [out] Number of output fields components
output_fields_component_names – [out] Names of output fields components, shared reference, do not free
max_output_fields – [out] Maximum output_fields

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelGetExpectedMaxOutputFields(Ratel ratel, PetscInt *num_expected, PetscScalar expected_max_output_fields[])¶

Get expected maximum output fields from options.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
num_expected – [out] Number of expected output fields components
expected_max_output_fields – [out] Expected maximum output fields

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelComputeMaxOutputFieldsError(Ratel ratel, PetscInt num_components, const PetscScalar max_output_fields[], PetscBool *has_any_expected, PetscScalar max_output_fields_error[])¶

Compute the error between the expected and final maximum output fields.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel Context
num_components – [in] Number of components of the input and output arrays
max_output_fields – [in] Computed final maximum output fields
has_any_expected – [out] PETSC_TRUE if expected maximum output fields provided for any component
max_output_fields_error – [out] Computed error in the final maximum output fields

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelViewMaxOutputFieldsErrorByNameFromOptions(Ratel ratel, PetscReal time, Vec U)¶

Compute maximum values of output fields by name from options.

Collective across MPI processes.

Note

This function may compute the output fields if they are not already computed for this timestep.

Parameters:

ratel – [in] Ratel context
time – [in] Final time
U – [in] Final solution vector

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelViewVolumeErrorFromOptions(Ratel ratel, PetscReal time, Vec U)¶

View the computed volume and error from options.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
time – [in] Current solution time
U – [in] Current solution vector

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelViewOutputFieldsFromOptions(Ratel ratel, PetscReal time, Vec U)¶

View the output fields vector from options.

Collective across MPI processes.

Note

This function may compute the output fields if they are not already computed for this timestep.

Parameters:

ratel – [in] Ratel context
time – [in] Current time
U – [in] Current solution vector

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelGetSurfaceForceFaces(Ratel ratel, PetscInt *num_faces, const char **faces[])¶

List mesh face numbers for output fields force computation.

Not collective across MPI processes.

Parameters:

ratel – [in] Ratel context
num_faces – [out] Number of faces where forces are computed
faces – [out] DMPlex mesh face numbers

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelComputeSurfaceForcesCellToFace(Ratel ratel, Vec U, PetscReal time, PetscInt *num_components, PetscScalar **surface_forces)¶

Compute surface forces on mesh faces.

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

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
U – [in] Computed solution vector
time – [in] Final time value, or 1.0 for SNES solution
num_components – [out] Number of force components in output buffer
surface_forces – [out] Computed face forces - caller is responsible for freeing

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelComputeSurfaceForces(Ratel ratel, Vec U, PetscReal time, PetscInt *num_components, PetscScalar **surface_forces)¶

Compute surface forces on mesh faces.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
U – [in] Computed solution vector
time – [in] Final time value, or 1.0 for SNES solution
num_components – [out] Number of force components in output buffer
surface_forces – [out] Computed face surface forces - caller is responsible for freeing

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelComputeSurfaceCentroids(Ratel ratel, Vec U, PetscReal time, PetscInt *num_components, PetscScalar **surface_centroids)¶

Compute centroids of mesh faces.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
U – [in] Computed solution vector
time – [in] Final time value, or 1.0 for SNES solution
num_components – [out] Number of centroid components in output buffer
surface_centroids – [out] Computed surface centroids - caller is responsible for freeing

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelComputeVolume(Ratel ratel, Vec U, PetscReal time, PetscScalar *volume)¶

Compute the total volume of the mesh using nodal output fields.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
U – [in] Current solution vector
time – [in] Current time value
volume – [out] Computed volume

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelGetOutputFields(Ratel ratel, Vec U, PetscReal time, Vec *D)¶

Get the output fields vector.

Collective across MPI processes.

Note

The user is responsible for restoring the vector with RatelRestoreOutputFields().

Parameters:

ratel – [in] Ratel context
U – [in] Computed solution vector
time – [in] Current time value
D – [out] output fields vector

Returns:

An error code: 0 - success, otherwise - failure

PetscErrorCode RatelRestoreOutputFields(Ratel ratel, Vec *F)¶

Restore the output fields vector.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
F – [out] output fields vector

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.

Solver management.

Note: Sets SNES defaults from RatelSNESSetup().

Collective across MPI processes.

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 viewer:filename.extension` sets TSMonitor function for strain energy
   `-ts_monitor_surface_force viewer:filename.extension` sets TSMonitor function for surface forces
   `-ts_monitor_surface_force_cell_to_face viewer:filename.extension` sets TSMonitor function for cell-to-face surface forces
   `-ts_monitor_output_fields viewer:filename.extension` sets TSMonitor function for output fields
   `-ts_monitor_checkpoint viewer:filename.extension` sets TSMonitor function for solution checkpoint binaries

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
ts – [inout] TS object to setup

Returns:

An error code: 0 - success, otherwise - failure

static PetscErrorCode RatelKSPSetup(Ratel ratel, KSP ksp)¶

Setup default KSP options.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
ksp – [inout] KSP 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.

Note: Sets default SNES line search to critical point method. Note: Sets default KSP to CG with natural norm for most problems. Sets default KSP to GMRES with preconditioned norm for problems with multiple active fields or contact boundary conditions. Note: Sets default PC to PCPMG most problems. Sets default PC to PCGAMG for problems one material and linear elements. Sets default PC to PCJACOBI for problems with multiple materials.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
snes – [inout] SNES object to setup

Returns:

An error code: 0 - success, otherwise - failure

static inline PetscErrorCode RatelSetupZeroInitialCondition(Ratel ratel, Vec U)¶

Setup zero initial condition with random noise, if needed.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
U – [out] Global vector to set with zero initial condition

Returns:

An error code: 0 - success, otherwise - failure

static inline PetscErrorCode RatelSetupNonZeroInitialConditionMMS(Ratel ratel, Vec U)¶

Compute non-zero initial conditions for time dependent MMS problem.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
U – [out] Computed non-zero MMS initial conditions vector

Returns:

An error code: 0 - success, otherwise - failure

static inline PetscErrorCode RatelSetupNonZeroInitialCondition(Ratel ratel, Vec U)¶

Compute non-zero initial conditions.

Collective across MPI processes.

Parameters:

ratel – [in] Ratel context
U – [out] Computed non-zero initial conditions vector

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.

Collective across MPI processes.

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.

Collective across MPI processes.

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.

Collective across MPI processes.

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.

Collective across MPI processes.

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.

Not collective across MPI processes.

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