PETSc#

Implementation that interfaces with PETSc and DMPlex.

DMPlex Helper#

Functions Helper functions for working with DMPlex meshes.

void generic_distribute(
DM *dm,
MPI_Comm comm = MPI_COMM_WORLD,
const PetscInt overlap = 0,
PetscSF *sf = nullptr
)#

If there are more than 1 MPI ranks distribute the mesh.

Parameters:

  • dm – [inout] DMPlex to distribute, original DMPlex is destroyed.

  • comm – [in] MPI communicator, default MPI_COMM_WORLD.

  • overlap – [in] Optional overlap to pass to PETSc (default 0).

  • sf – [inout] Star forest that PETSc returns describing the new parallel decomposition.

void setup_coordinate_section(
DM &dm,
const PetscInt vertex_start,
const PetscInt vertex_end
)#

Setup the coordinate section for a DMPlex. See DMPlexBuildCoordinatesFromCellList.

Parameters:

  • dm – DMPlex to setup coordinate section for.

  • vertex_start – Coordinate index for first coordinate.

  • vertex_end – Coordinate index +1 for last coordinate.

void print_transitive_closure(DM &dm, const PetscInt point)#

Helper function to print transitive closure and orientations.

Parameters:

  • dm – Input DMPlex.

  • point – PETSc DMPlex pointin DM.

std::vector<PetscInt> get_global_distributed_points_map(
DM &dm_distributed,
PetscSF &sf
)#

Get the global map from old point indices to new point indices after DMPlexDistribute has been called. Must be called collectively on the communicator.

Parameters:

  • dm_distributed – DMPlex output from a DMPlexDistribute call.

  • sf – PetscSF returned from a DMPlexDistribute call.

Returns:

Vector where the entry at index i is the new global point index for the global point i in the DMPlex before the distribute call.

std::tuple<std::shared_ptr<CellDatConst<int>>, std::shared_ptr<CellDatConst<REAL>>> get_cell_vertices_cdc(
SYCLTargetSharedPtr sycl_target,
std::shared_ptr<DMPlexHelper> dmh
)#

Get the number of cell vertices and cell vertices in a CellDatConst.

Returns:

CellDatConst for number of cell vertices and cell vertices.

std::pair<int, std::vector<int>> get_map_from_global_cell_points_to_ranks(
DM dm
)#

Get the map from global cell index to owning rank. Assumes that the N global cell indices live in [a, a+N) and returns a vector of MPI ranks and a. Must be called collectively on the communicator of the DMPlex.

Parameters:

dm – DMPlex to retrieve owning ranks for.

Returns:

The offset a and the vector that holds the MPI rank that owns cell i

  • a in element i.

inline PetscErrorCode NP_DMPlexCreateBoxMesh(
MPI_Comm comm,
PetscInt dim,
PetscBool simplex,
const PetscInt faces[],
const PetscReal lower[],
const PetscReal upper[],
const DMBoundaryType periodicity[],
PetscBool interpolate,
DM *dm
)#

Wraps DMPlexCreateBoxMesh to work pre and post petsc v3.22.

Parameters:

  • comm – [in] Communicator for mesh.

  • dim – [in] Number of spatial dimensions.

  • simplex – [in] Create a mesh consisting of triangles.

  • faces – [in] Number of faces in each dimension.

  • lower – [in] Origin for each dimension.

  • upper – [in] Extent plus origin for each dimension.

  • periodicity – [in] Periodicity of each dimension.

  • interpolate – [in] Should PETSc interpolate the mesh.

  • dm – [inout] Output DM.

class DMPlexHelper#
#include <dmplex_helper.hpp>

Helper class that wraps a PETSc DMPlex and simplifies common operations.

Public Functions

template<typename T>
inline void get_cell_petsc_indices(
std::vector<T> &indices
)#
Parameters:

indices – [inout] Populated with PETSc point indices for locally owned cells.

DMPlexCellSerialise get_copyable_cell(const PetscInt local_index)#

Get a serialisable representation of a cell in the DMPlex.

Parameters:

local_index – Local index of the cell to get a representation of.

Returns:

Serialisable representation of the cell.

void free()#

Free the helper. Must be called collectively on the communicator.

DMPlexHelper(MPI_Comm comm, DM dm)#

Construct helper class from DMPlex. Collective on the communicator.

Parameters:

  • comm – MPI communicator the DMPlex is constructed on.

  • dm – Input DMPlex to wrap.

int get_cell_count()#
Returns:

the number of cells.

int get_global_cell_count()#
Returns:

the total number of cells. Collective on the communicator.

PetscInt get_dmplex_cell_index(const PetscInt local_index)#

Convert a local cell id into a DMPlex cell id.

Parameters:

local_index – Local index in [0, num_cells).

Returns:

DMPlex point index in [cell_start, cell_end).

PetscInt get_local_cell_index(const PetscInt petsc_index)#

Convert a DMPlex cell id into a local cell id.

Parameters:

petsc_index – Local index in [cell_start, cell_end).

Returns:

Local point index in [0, num_cells).

PetscInt signed_global_id_to_global_id(const PetscInt c)#

Remove the negation from point indices which DMPlex uses to denote global vs local indices.

Parameters:

c – Input index.

Returns:

c if c > -1 else ((c * (-1)) - 1)

PetscInt get_point_global_index(
const PetscInt point,
const bool signed_point = false
)#

Get the global index of a point from the local point index.

Parameters:

  • point – Local point index.

  • signed_point – Optionally return the original signed global point index.

Returns:

Global point index.

PetscInt get_local_point_from_global_point(
const PetscInt global_point_index
)#

Get the local point index from a global point index if the point is owned by this rank.

Parameters:

global_point_index – Global point index to retrieve local point index for.

Returns:

Local point index.

ExternalCommon::BoundingBoxSharedPtr get_bounding_box()#

Get a bounding box for the cells on this MPI rank.

Returns:

Bounding box for cells in DMPlex.

ExternalCommon::BoundingBoxSharedPtr get_point_bounding_box(
const PetscInt petsc_index
)#

Get a bounding box for a mesh point (assumes linear mesh).

Parameters:

petsc_index – Local point index.

Returns:

Bounding box for the point.

ExternalCommon::BoundingBoxSharedPtr get_cell_bounding_box(
const PetscInt cell
)#

Get a bounding box for a mesh cell (assumes linear mesh).

Parameters:

cell – Local cell index.

Returns:

Bounding box for cell.

void get_point_vertices(
const PetscInt petsc_index,
std::vector<std::vector<REAL>> &vertices
)#

Get the vertices of a point using a PETSc index.

Parameters:

  • petsc_index – [in] PETSc point index.

  • vertices – [inout] Vector of vertices.

void get_point_vertices_graph_ordering(
const PetscInt petsc_index,
std::vector<std::vector<REAL>> &vertices
)#

Get the vertices of a point using a PETSc index in the graph ordering.

Parameters:

  • petsc_index – [in] PETSc point index.

  • vertices – [inout] Vector of vertices.

void get_cell_vertices(
const PetscInt cell,
std::vector<std::vector<REAL>> &vertices
)#

Get the vertices of a cell.

Parameters:

  • cell – [in] Local cell index.

  • vertices – [inout] Vector of vertices.

void get_cell_vertex_average(
const PetscInt cell,
std::vector<REAL> &average
)#

Get average of the vertices of a cell.

Parameters:

  • cell – [in] Local cell index.

  • average – [inout] Vector of average of vertices.

DMPolytopeType get_point_type(const PetscInt point_index)#

Get the point type.

Parameters:

point_index – Local point index.

Returns:

PETSc description of cell type.

DMPolytopeType get_cell_type(const PetscInt cell)#

Get the cell type.

Parameters:

cell – Local cell index.

Returns:

PETSc description of cell type.

int contains_point(std::vector<PetscScalar> &point)#

Determine if mesh contains a point.

Parameters:

point – [in] Point to test.

Returns:

Negative value if point not located, otherwise owning cell.

bool cell_contains_point_2d(
const PetscInt index,
std::vector<PetscScalar> &point
)#

Determine if a 2D mesh cell contains a point.

Parameters:

  • index – [in] Local cell index.

  • point – [in] Point to test.

Returns:

true if point contains cell.

bool cell_contains_point_3d(
const PetscInt index,
std::vector<PetscScalar> &point
)#

Determine if a 3D mesh cell contains a point.

Parameters:

  • index – [in] Local cell index.

  • point – [in] Point to test.

Returns:

true if point contains cell.

bool cell_contains_point(
const PetscInt index,
std::vector<PetscScalar> &point
)#

Determine if mesh cell contains a point.

Parameters:

  • index – [in] Local cell index.

  • point – [in] Point to test.

Returns:

true if point contains cell.

PetscInt get_num_labels()#
Returns:

The number of labels in the DMPlex.

DMLabel get_face_sets_label()#
Returns:

The DMLabel for “Face Sets”

std::string get_label_name(const PetscInt index)#
Parameters:

index – Index of label to get name of.

Returns:

The label name corresponding to an index.

void get_boundary_stratum(PetscInt *start, PetscInt *end)#

Get boundary points start and end. In 2D the boundary point types are edges. In 3D the boundary point types are faces. Returns [start, end).

Parameters:

  • start – [inout] First boundary point.

  • end – [inout] Last boundary point plus one.

std::map<PetscInt, std::vector<PetscInt>> get_face_sets()#
Returns:

Map from face sets int label to DMPlex points with that label. Only returns points which are owned by the calling MPI rank.

void write_vtk(const std::string filename)#

Write the DM to a file for visualisation in paraview.

Parameters:

filename – Filename for VTK file.

const VTK::UnstructuredCell &get_vtk_point_data(
const PetscInt index
)#

Get VTK data for a point index.

Parameters:

index – PETSc point index of object to get unstructured cell representation of.

Returns:

VTK data which can be passed to our VTKHDF implementation.

std::vector<VTK::UnstructuredCell> get_vtk_cell_data()#

Get VTK data for all cells.

Returns:

Vector of VTK data which can be passed to our VTKHDF implementation.

void get_vtk_point_vertex_order(
const PetscInt index,
std::vector<PetscInt> &order
)#

Get VTK vertex order for a point. Returned array gives order such that For VTK vertex i, order[i] gives the DMPlex vertex.

Parameters:

  • index – [in] Local PETSc index.

  • order – [inout] Vector containing reordering.

void print()#

Print to stdout information about the held DMPlex.

REAL get_point_volume(const PetscInt point_index)#

Get the volume of a point in the local mesh.

Parameters:

point_index – Local point index.

Returns:

Volume of object.

REAL get_cell_volume(const int index)#

Get the volume of a cell in the local mesh.

Parameters:

index – Local index of cell.

Returns:

Volume of cell.

REAL get_volume()#
Returns:

The total volume of the mesh. Must be called collectively on the communicator.

void get_linear_normal_vector(
const PetscInt point_index,
std::vector<REAL> &normal_vector
)#

Get the normal vector for a linear quadrilateral or linear triangle. The direction is determined to be the outward direction of the first element in the support of the quadrilateral or triangle.

Parameters:

  • point_index – [in] PETSc point index of the face.

  • normal_vector – [inout] Output normal vector.

void get_global_face_index_bounds(INT &bound_lower, INT &bound_upper)#

Get the bounds of global face indices over the entire mesh.

Parameters:

  • bound_lower – [inout] Lowest global face index.

  • bound_upper – [inout] Largest global face index plus one.

bool normal_points_towards_point(
const PetscInt p0,
const PetscInt p1,
const PetscInt p2,
const PetscInt point
)#

Test if the normal vector formed by the vectors p0->p1 and p0->p2 points towards point.

Parameters:

  • p0 – Local point index of origin.

  • p1 – Local point index of point p1.

  • p2 – Local point index of point p2.

  • point – Local point index of test point.

Returns:

True if the normal points towards the test point.

void get_vertex_neighbours(
const PetscInt point_index,
std::vector<PetscInt> &neighbours
)#

For an input vertex local point return the local point indices of neigbouring vertices.

Parameters:

  • point_index – [in] Point index of a vertex.

  • neighbours – [inout] Point vertices of neighbours.

void get_canonical_vertex_order(
const PetscInt point,
std::vector<PetscInt> &order
)#

Get the local point indices of the vertices of a point in an ordering consistent with “Computational Meshing: Practical Application of PETSc’s

DMPlex”.

Parameters:

  • point – [in] Local point index to retrieve vertices for.

  • order – [inout] Vector of point indices in the order for the geometry type.

DMPlex Mesh Interface#

Implementation which allows particles to exist on and interact with DMPlex meshes.

class DMPlexInterface : public NESO::Particles::HMesh#
#include <dmplex_interface.hpp>

This is the HMesh interface for DMPlex unstructured meshes. It can be used to create a Domain instance.

Public Functions

DMPlexInterface(
DM dm,
const int subdivision_order_offset = 0,
MPI_Comm comm = MPI_COMM_WORLD
)#

Create a DMPlex interface object from a DMPlex. Collective on the passed communicator.

Parameters:

  • dm – DMPlex to create interface from.

  • subdivision_order_offset – Offset to the subdivision order used to create the mesh hierarchy (default 0).

  • comm – MPI communicator to use (default MPI_COMM_WORLD).

virtual void free() override#

Free the mesh and associated communicators.

virtual void get_point_in_subdomain(double *point) override#

Get a point in the domain that should be in, or at least close to, the sub-domain on this MPI process. Useful for parallel initialisation.

Parameters:

point – Pointer to array of size equal to at least the number of mesh dimensions.

virtual std::vector<int> &get_local_communication_neighbours(
) override#

Get a std::vector of MPI ranks which should be used to setup local communication patterns.

Returns:

std::vector of MPI ranks.

virtual MPI_Comm get_comm() override#

Get the MPI communicator of the mesh.

Returns:

MPI communicator.

virtual int get_ndim() override#

Get the number of dimensions of the mesh.

Returns:

Number of mesh dimensions.

virtual std::vector<int> &get_dims() override#

Get the Mesh dimensions.

Returns:

Mesh dimensions.

virtual int get_subdivision_order() override#

Get the subdivision order of the mesh.

Returns:

Subdivision order.

virtual int get_cell_count() override#

Get the total number of cells in the mesh.

Returns:

Total number of mesh cells.

virtual double get_cell_width_coarse() override#

Get the mesh width of the coarse cells in the MeshHierarchy.

Returns:

MeshHierarchy coarse cell width.

virtual double get_cell_width_fine() override#

Get the mesh width of the fine cells in the MeshHierarchy.

Returns:

MeshHierarchy fine cell width.

virtual double get_inverse_cell_width_coarse() override#

Get the inverse mesh width of the coarse cells in the MeshHierarchy.

Returns:

MeshHierarchy inverse coarse cell width.

virtual double get_inverse_cell_width_fine() override#

Get the inverse mesh width of the fine cells in the MeshHierarchy.

Returns:

MeshHierarchy inverse fine cell width.

virtual int get_ncells_coarse() override#

Get the global number of coarse cells.

Returns:

Global number of coarse cells.

virtual int get_ncells_fine() override#

Get the number of fine cells per coarse cell.

Returns:

Number of fine cells per coarse cell.

virtual std::shared_ptr<MeshHierarchy> get_mesh_hierarchy(
) override#

Get the MeshHierarchy instance placed over the mesh.

Returns:

MeshHierarchy placed over the mesh.

bool validate_halos(const bool fatal = true)#

This is a helper function to test that the halos are valid when comparing the topology and coordinates of the halo DMPlex with the original DMPlex the interface was constructed with. Collective on the communicator.

Parameters:

fatal – If true then an error in the validation is fatal.

Returns:

True if no errors are discovered otherwise false.

class DMPlexLocalMapper : public NESO::Particles::LocalMapper#
#include <dmplex_local_mapper.hpp>

Top level interface for mapping particles into DMPlex cells. This mapper corresponds to the DMPlexInterface mesh interface and can be used to create a Domain instance.

Public Functions

inline DMPlexLocalMapper(
SYCLTargetSharedPtr sycl_target,
DMPlexInterfaceSharedPtr dmplex_interface
)#

Create mappers for a DMPlex.

Parameters:

  • sycl_target – Compute target for mappers.

  • dmplex_interface – DMPlexInterface for which to create particle to cell mappers for.

inline virtual void map(
ParticleGroup &particle_group,
const int map_cell = -1
) override#

This function maps particle positions to cells on the underlying mesh.

Parameters:

  • particle_group – ParticleGroup containing particle positions.

  • map_cell – Cell to map particles in.

inline virtual void particle_group_callback(
ParticleGroup &particle_group
) override#

Callback for ParticleGroup to execute for additional setup of the LocalMapper that may involve the ParticleGroup.

Parameters:

particle_group – ParticleGroup instance.

DMPlex DSMC#

Implementation relating to DSMC simulations on DMPlex meshes.

void estimate_voronoi_cell_volume(
DMPlexInterfaceSharedPtr mesh,
SubdivideCellsVoronoiSharedPtr voronoi_cells,
std::size_t &num_samples,
REAL &stol,
std::size_t max_num_samples,
NDLocalArraySharedPtr<REAL, 2> &volumes,
std::mt19937 *rng_in = nullptr,
const int default_block_size = 256
)#

Estimate the volume of Voronoi cells that sub-divide DMPlex cells using Monte Carlo.

Parameters:

  • mesh – [in] DMPlex mesh interface that describes the base mesh.

  • voronoi_cells – [in] Voronoi cell instance that describes the Voronoi cells in each mesh cell.

  • num_samples – [inout] On call defines the minimum number of samples that must be made per Voronoi cell in each mesh cell. On return contains the number of samples made for each mesh cell.

  • stol – [inout] On call sets the tolerance between blocks of samples to use as an exit condition after the number of samples has exceeded the minimum number of samples. On return contains the achieved maximum seen difference between the samples [0,…., i-1] and samples [0,….,i] where i is the number of blocks of samples.

  • max_num_samples – [in] Maximum number of samples per Voronoi cell to perform.

  • volumes – [inout] Output NDLocalArray of Voronoi cell volumes. Will be allocated if too small or nullptr.

  • rng_in – [inout] Optionally pass an RNG instance to use for samples.

  • default_block_size – [in] Optionally specify the desired block size per Voronoi cell for samples.

DMPlex Boundary Intersection#

Types and functions for detecting interactions between particle trajectories and the boundary of the DMPlex mesh.

std::shared_ptr<BoundaryInteractionCommon> create_boundary_interaction(
SYCLTargetSharedPtr sycl_target,
DMPlexInterfaceSharedPtr mesh,
std::map<PetscInt, std::vector<PetscInt>> &boundary_groups,
const REAL tol = 0.0,
std::optional<Sym<REAL>> previous_position_sym = std::nullopt
)#

Create a BoundaryInteraction3D or BoundaryInteraction2D instance and cast it to a BoundaryInteractionCommon.

Parameters:

  • sycl_target – Compute device to use to identify intersections of trajectories and the boundary.

  • mesh – 3D or 2D DMPlex mesh interface to use.

  • boundary_groups – Map from group IDs to the boundary labels (i.e. gmsh physical lines) that form the group.

  • tol – Tolerance for intersection of trajectories and the line segments that form the boundary. If particles are passing through corners try increasing this value (default 0.0).

  • previous_position_sym – The Sym for the particle property which holds the position of each particle before the positions were updated in a time stepping loop. These positions are populated on call to pre_integration.

class BoundaryInteractionCommon#
#include <boundary_interaction_common.hpp>

Common implementation elements for identifying intersections between particle trajectories and the mesh boundary. Users probably want to create an instance of classes which inherit from this base, e.g. BoundaryInteraction2D.

Subclassed by NESO::Particles::PetscInterface::BoundaryInteraction2D, NESO::Particles::PetscInterface::BoundaryInteraction3D

Public Functions

virtual void free() = 0#

Free the instance. Must be called. Collective on the communicator.

std::map<PetscInt, ParticleSubGroupSharedPtr> post_integration(
std::shared_ptr<ParticleGroup> particles
)#

Call after updating to find particles whose trajectories intersect the DMPlex boundary.

Parameters:

particles – Collection of particles, either a ParticleGroup or ParticleSubGroup, to identify trajectory-boundary intersections of.

Returns:

Map from boundary groups ids, which were passed in the constructor, to a ParticleSubGroup of particles which crossed the boundary elements which form the boundary group.

std::map<PetscInt, ParticleSubGroupSharedPtr> post_integration(
std::shared_ptr<ParticleSubGroup> particles
)#

Call after updating to find particles whose trajectories intersect the DMPlex boundary.

Parameters:

particles – Collection of particles, either a ParticleGroup or ParticleSubGroup, to identify trajectory-boundary intersections of.

Returns:

Map from boundary groups ids, which were passed in the constructor, to a ParticleSubGroup of particles which crossed the boundary elements which form the boundary group.

void pre_integration(std::shared_ptr<ParticleGroup> particles)#

This method should be called with a collection of particles prior to updating the positions of these particles.

Parameters:

particles – ParticleGroup or ParticleSubGroup of particles whose positions are about to be updated, e.g. in a time stepping operation.

void pre_integration(std::shared_ptr<ParticleSubGroup> particles)#

This method should be called with a collection of particles prior to updating the positions of these particles.

Parameters:

particles – ParticleGroup or ParticleSubGroup of particles whose positions are about to be updated, e.g. in a time stepping operation.

DMPlexFunctionSharedPtr create_function(
const int group,
const std::string function_space,
const int polynomial_order
)#

Create a function on a boundary group. Must be called collectively on the communicator.

Parameters:

  • group – ID of boundary group to create function on.

  • function_space – Family of function to create, e.g. “DG”.

  • polynomial_order – Order of function to create, e.g. 0.

Returns:

Function object on boundary.

void function_project(
ParticleSubGroupSharedPtr particle_sub_group,
Sym<REAL> sym,
const int component,
const bool is_ephemeral,
DMPlexFunctionSharedPtr func
)#

Project particle data onto a function defined on the surface. Uses the standardarised boundary interface on the sub group. This function call is equivalent to calling:

function_project_initialise(func); function_project_contribute(particle_sub_group, sym, component,

is_ephemeral, func); function_project_finalise(func);

Must be called collectively on the communicator.

Parameters:

  • particle_sub_group – ParticleSubGroup to project onto function.

  • sym – Sym<REAL> Particle property to use as source weights.

  • component – Component of particle property to use as source weights.

  • is_ephemeral – Indicate if the particle weights are in an EphemeralDat or ParticleDat.

  • func – Function to project onto.

void function_project_initialise(DMPlexFunctionSharedPtr func)#

A function_project call is equivalent to calling:

function_project_initialise(func); function_project_contribute(particle_sub_group, sym, component,

is_ephemeral, func); function_project_finalise(func);

This method initialises the destination function for projection. Must be called collectively on the communicator.

Parameters:

func – Function to project onto.

void function_project_contribute(
ParticleSubGroupSharedPtr particle_sub_group,
Sym<REAL> sym,
const int component,
const bool is_ephemeral,
DMPlexFunctionSharedPtr func
)#

A function_project call is equivalent to calling:

function_project_initialise(func); function_project_contribute(particle_sub_group, sym, component,

is_ephemeral, func); function_project_finalise(func);

This method adds the contributions from the particles in the particle_sub_group to the projection. Must be called collectively on the communicator.

Parameters:

  • particle_sub_group – ParticleSubGroup to project onto function.

  • sym – Sym<REAL> Particle property to use as source weights.

  • component – Component of particle property to use as source weights.

  • is_ephemeral – Indicate if the particle weights are in an EphemeralDat or ParticleDat.

  • func – Function to project onto.

void function_project_finalise(DMPlexFunctionSharedPtr func)#

A function_project call is equivalent to calling:

function_project_initialise(func); function_project_contribute(particle_sub_group, sym, component,

is_ephemeral, func); function_project_finalise(func);

This method must be called after all contributions to the projection have been made with function_project_contribute. Must be called collectively on the communicator.

Parameters:

func – Function to project onto.

void function_evaluate(
ParticleSubGroupSharedPtr particle_sub_group,
Sym<REAL> sym,
const int component,
const bool is_ephemeral,
DMPlexFunctionSharedPtr func
)#

Evaluate particle data from a function defined on the surface. Uses the standardarised boundary interface on the sub group. Must be called collectively on the communicator.

Parameters:

  • particle_sub_group – ParticleSubGroup to containing destination particles for evaluation.

  • sym – Sym<REAL> Particle property to overwrite with function evaluations.

  • component – Component of particle property to write evalauations to.

  • is_ephemeral – Indicate if the particle evaluations are in an EphemeralDat or ParticleDat.

  • func – Function to evaluate at particle locations.

Public Members

SYCLTargetSharedPtr sycl_target#

The compute device used to find intersections.

DMPlexInterfaceSharedPtr mesh#

The interface to a DMPlex mesh.

std::map<PetscInt, std::vector<PetscInt>> boundary_groups#

The map from boundary groups to the labels which form the group.

Sym<REAL> previous_position_sym#

The Sym for the particle property which holds the position of each particle before the positions were updated in a time stepping loop. These positions are populated on call to pre_integration.

DMPlex Function Projection and Evaluation#

Implementation for projection (deposition) onto functions defined on DMPlex meshes and evaluating functions defined on DMPlex meshes. Please visit the boundary intersection section for methods that implement surface function interaction.

class DMPlexProjectEvaluate#
#include <dmplex_project_evaluate.hpp>

Type to handle projection/deposition onto and evaluation from a set of quadrature (nodal) points.

Public Functions

inline DMPlexProjectEvaluate(
ExternalCommon::QuadraturePointMapperSharedPtr qpm,
std::string function_space,
int polynomial_order
)#

Create a handler for projection/deposition onto and evaluation from a set of quadrature (nodal) points. The currently implemented function spaces and polynomial orders are:

function_space=”DG”, polynomial_order=0 function_space=”Barycentric”, polynomial_order=1

Parameters:

  • qpm – QuadraturePointMapper which describes the quadrature points on which to deposit and from which functions are evaluated.

  • function_space – String which specifies the type of deposition and evaluation.

  • polynomial_order – Polynomial order to use with the specified function space.

inline std::vector<VTK::UnstructuredCell> get_vtk_data()#

Get a representation of the internal state which can be passed to the VTKHDF writer. This method returns a representation that corresponds to the last projection or evaluation which occured with this instance.

Returns:

Data for VTKHDF unstructured grid writer.

inline void project(
ParticleGroupSharedPtr particle_group,
Sym<REAL> sym
)#

Projects values from particle data onto the values in the QuadraturePointMapper.

Parameters:

  • particle_group – ParticleGroup of particles containing data to deposit onto the grid.

  • sym – Sym objects which indices which particle data to deposit. This projects into the QuadraturePointMapper particle group into the particle properties given by calling QuadraturePointMapper::get_sym(ncomp).

inline void project(
ParticleSubGroupSharedPtr particle_sub_group,
Sym<REAL> sym
)#

Projects values from particle data onto the values in the QuadraturePointMapper.

Parameters:

  • particle_sub_group – ParticleSubGroup of particles containing data to deposit onto the grid.

  • sym – Sym objects which indices which particle data to deposit. This projects into the QuadraturePointMapper particle group into the particle properties given by calling QuadraturePointMapper::get_sym(ncomp).

inline void evaluate(
ParticleGroupSharedPtr particle_group,
Sym<REAL> sym
)#

If the output sym has ncomp components then this method evaluates the function defined in the point properties given by QuadraturePointMapper::get_sym(ncomp) at the location of each particle.

Parameters:

  • particle_group – Set of particles to evaluate the deposited function at.

  • sym – Output particle property on which to place evaluations.

inline void evaluate(
ParticleSubGroupSharedPtr particle_sub_group,
Sym<REAL> sym
)#

If the output sym has ncomp components then this method evaluates the function defined in the point properties given by QuadraturePointMapper::get_sym(ncomp) at the location of each particle.

Parameters:

  • particle_sub_group – Set of particles to evaluate the deposited function at.

  • sym – Output particle property on which to place evaluations.

class DMPlexFunction : public NESO::Particles::GenericFunction#
#include <dmplex_function.hpp>

Generic type for functions on DMPlex volumes and surfaces.

Public Functions

DMPlexFunction(
DMPlexInterfaceSharedPtr mesh,
SYCLTargetSharedPtr sycl_target,
const int ndim,
const std::vector<INT> &cells_local,
const std::string function_space,
const int polynomial_order,
const int boundary_group
)#

Create a function on a mesh on the passed entities.

Parameters:

  • mesh – Host mesh to create function on.

  • sycl_target – Compute device holding the DOFs.

  • ndim – Number of spatial dimensions function exists in.

  • cells_local – Locally owned mesh entities to create function over. These must be point indices not cell indices.

  • function_space – Type of function to create.

  • polynomial_order – Polynomial order of function to create.

  • boundary_group – Label, e.g. boundary group, for subset of the mesh this function is defined over.

virtual void write_vtkhdf(const std::string filename) override#

Write the function to a vtkhdf file. This function must be called collectively on the communicator.

Parameters:

filename – Output file name which should have vtkhdf extension.

class DMPlexProjectEvaluateBarycentric : public NESO::Particles::PetscInterface::DMPlexProjectEvaluateBase#
#include <dmplex_project_evaluate_barycentric.hpp>

Implementation to deposit particle data into and evalute from DG1 function spaces by using Barycentric interpolation.

Public Functions

virtual std::vector<VTK::UnstructuredCell> get_vtk_data(
const std::string name = "value"
) override#

Get a representation of the internal state which can be passed to the VTKHDF writer.

Parameters:

name – Name to assign to field in output data. Default “value”.

Returns:

Data for VTKHDF unstructured grid writer.

DMPlexProjectEvaluateBarycentric(
ExternalCommon::QuadraturePointMapperSharedPtr qpm,
std::string function_space,
int polynomial_order,
const bool testing = false
)#

Create a DG1 project/evaluate instance from a QuadraturePointMapper which uses Barycentric interpolation.

Parameters:

  • qpm – QuadraturePointMapper with a single point per cell.

  • function_space – Should be “Barycentric”.

  • polynomial_order – Should be 1.

  • testing – Enable testing mode.

virtual void project(
ParticleGroupSharedPtr particle_group,
Sym<REAL> sym
) override#

Projects values from particle data onto the values in the QuadraturePointMapper.

Parameters:

  • particle_group – ParticleGroup of particles containing data to deposit onto the grid.

  • sym – Sym objects which indices which particle data to deposit. This projects into the QuadraturePointMapper particle group into the particle properties given by calling QuadraturePointMapper::get_sym(ncomp).

virtual void project(
ParticleSubGroupSharedPtr particle_sub_group,
Sym<REAL> sym
) override#

Projects values from particle data onto the values in the QuadraturePointMapper.

Parameters:

  • particle_sub_group – ParticleSubGroup of particles containing data to deposit onto the grid.

  • sym – Sym objects which indices which particle data to deposit. This projects into the QuadraturePointMapper particle group into the particle properties given by calling QuadraturePointMapper::get_sym(ncomp).

virtual void evaluate(
ParticleGroupSharedPtr particle_group,
Sym<REAL> sym
) override#

If the output sym has ncomp components then this method evaluates the function defined in the point properties given by QuadraturePointMapper::get_sym(ncomp) at the location of each particle.

Parameters:

  • particle_group – Set of particles to evaluate the deposited function at.

  • sym – Output particle property on which to place evaluations.

virtual void evaluate(
ParticleSubGroupSharedPtr particle_sub_group,
Sym<REAL> sym
) override#

If the output sym has ncomp components then this method evaluates the function defined in the point properties given by QuadraturePointMapper::get_sym(ncomp) at the location of each particle.

Parameters:

  • particle_sub_group – Set of particles to evaluate the deposited function at.

  • sym – Output particle property on which to place evaluations.

class DMPlexProjectEvaluateDG : public NESO::Particles::PetscInterface::DMPlexProjectEvaluateBase#
#include <dmplex_project_evaluate_dg.hpp>

Implementation to deposit particle data into and evalute from DG0 function spaces. This implementation can have an internal state (cdc_project) which is a CellDatConst that holds the DOFs. This cell dat is resized whenever set_dofs is called with a greater number of components or when project is called with a greater number of components. Calling project or set_dofs will overwrite the existing DOFs. Calling get_dofs or evaluate will use or retrieve the existing DOFs.

Alternatively this implementation can consider a DOF per local mesh cell.

Public Functions

virtual std::vector<VTK::UnstructuredCell> get_vtk_data(
const std::string name = "value"
) override#

Get a representation of the internal state which can be passed to the VTKHDF writer.

Parameters:

name – Name to assign to field in output data. Default “value”.

Returns:

Data for VTKHDF unstructured grid writer.

DMPlexProjectEvaluateDG(
ExternalCommon::QuadraturePointMapperSharedPtr qpm,
std::string function_space,
int polynomial_order
)#

Create a DG0 project/evaluate instance from a QuadraturePointMapper.

Parameters:

  • qpm – QuadraturePointMapper with a single point per cell.

  • function_space – Should be “DG”.

  • polynomial_order – Should be 0.

DMPlexProjectEvaluateDG(
DMPlexInterfaceSharedPtr mesh,
SYCLTargetSharedPtr sycl_target,
std::string function_space,
int polynomial_order
)#

Create a DG project/evaluate instance on a mesh. This constructor will create an instance that assumes that the MPI rank that owns a cell also owns all DOFs associated with that cell. i.e. there is no QuadraturePointMapper moving values around.

Parameters:

  • mesh – DMPlexInterface mesh object to use as domain for functions.

  • sycl_target – Compute device that will be used.

  • function_space – Function space to use, e.g. “DG”.

  • polynomial_order – Polynomial order to use, e.g. 0.

virtual void project(
ParticleGroupSharedPtr particle_group,
Sym<REAL> sym
) override#

Projects values from particle data onto the values in the QuadraturePointMapper.

Parameters:

  • particle_group – ParticleGroup of particles containing data to deposit onto the grid.

  • sym – Sym objects which indices which particle data to deposit. This projects into the QuadraturePointMapper particle group into the particle properties given by calling QuadraturePointMapper::get_sym(ncomp).

virtual void project(
ParticleSubGroupSharedPtr particle_sub_group,
Sym<REAL> sym
) override#

Projects values from particle data onto the values in the QuadraturePointMapper.

Parameters:

  • particle_sub_group – ParticleSubGroup of particles containing data to deposit onto the grid.

  • sym – Sym objects which indices which particle data to deposit. This projects into the QuadraturePointMapper particle group into the particle properties given by calling QuadraturePointMapper::get_sym(ncomp).

virtual void evaluate(
ParticleGroupSharedPtr particle_group,
Sym<REAL> sym
) override#

If the output sym has ncomp components then this method evaluates the function defined in the point properties given by QuadraturePointMapper::get_sym(ncomp) at the location of each particle.

Parameters:

  • particle_group – Set of particles to evaluate the deposited function at.

  • sym – Output particle property on which to place evaluations.

virtual void evaluate(
ParticleSubGroupSharedPtr particle_sub_group,
Sym<REAL> sym
) override#

If the output sym has ncomp components then this method evaluates the function defined in the point properties given by QuadraturePointMapper::get_sym(ncomp) at the location of each particle.

Parameters:

  • particle_sub_group – Set of particles to evaluate the deposited function at.

  • sym – Output particle property on which to place evaluations.

void get_dofs(const int ncomp, std::vector<REAL> &dofs)#

Get the DOFs for all cells and all components from the last project or set_dofs call. DOF ordering is the per cell components running fastest then cells.

Parameters:

  • ncomp – [in] Number of components/functions to retrieve DOFs for. e.g. if project has been called for a particle property with two components then there are two DOFs per cell in the internal representation.

  • dofs – [inout] DOFs in std::vector<REAL> form. This array may be resized and zeroed by the implementation.

void set_dofs(const int ncomp, const std::vector<REAL> &dofs)#

Set the DOFs for the internal representation, e.g. prior to an evaluate call. DOF ordering is the per cell components running fastest then cells.

Parameters:

  • ncomp – [in] Number of components/functions to retrieve DOFs for. e.g. if project has been called for a particle property with two components then there are two DOFs per cell in the internal representation.

  • dofs – [in] DOFs in std::vector<REAL> form.

DMPlex Mesh Coupling#

Types and functions for coupling DMPlex meshes with other meshes.

struct DMPlexMeshCouplerDG0MapEntry#
#include <dmplex_mesh_coupler_dg0.hpp>

Type that holds a cell index and a pair of weights for combining data when sent/received.

class DMPlexMeshCouplerDG0#
#include <dmplex_mesh_coupler_dg0.hpp>

Class for transporting DG0/Finite Volume fields/quantites between overlapping meshes.

Consider two meshes A and B. Assume that N local cells a in A are indexed locally by [0, N). Mesh B is a distributed DMPlex mesh with global indices b in [0, M). For each a in [0, N) the user provides a map from a to a vector of DMPlexMeshCouplerDG0MapEntry instances where the cell index of each entry is a global cell index b in [0, M).

The forward direction is defined as the direction which transfers data from A to B. The backward direction is the direction which transfers data from B to A.

The forward direction computes

\(x_b = \sum_a w_{a,b} y_a\)

where \(x_b\) is the DOF in cell b in B, \(w_{a,b}\) is the forward direction weight for source cell a and destination cell b and \(y_a\) is the source DOF. The backward direction is identical with the direction of data transport reversed.

Public Functions

DMPlexMeshCouplerDG0(
DM dmplex_B,
std::vector<std::vector<DMPlexMeshCouplerDG0MapEntry>> &coupling_map
)#

Create a coupler with the provided forward and backward maps. This constructor is collective on the communicator.

Parameters:

  • dmplex_B – DMPlex representation of mesh B.

  • coupling_map – Vector of entries which describe the non-zero adjacency matrix weights for the forward and backward directions. The cell indices in this map are global indices of PETSc DMPlex cells. This vector should have length equal the number of locally owned cells in mesh B, i.e. N. This vector can be freed after construction of the instance.

void forward_transfer(
std::vector<REAL> &dofs_A,
const int ncomp,
std::vector<REAL> &dofs_B
)#

Perform the forward transfer. This method is collective on the communicator.

Parameters:

  • dofs_A – Source DOFs to send and combine.

  • ncomp – Number of components per cell.

  • dofs_B – Destination DOFS.

void backward_transfer(
std::vector<REAL> &dofs_B,
const int ncomp,
std::vector<REAL> &dofs_A
)#

Perform the backward transfer. This method is collective on the communicator.

Parameters:

  • dofs_B – Source DOFs to send and combine.

  • ncomp – Number of components per cell.

  • dofs_A – Destination DOFS.

On this page
Show Source