DMSWARM — PETSc 3.21.4 documentation

Skip to main content
`Ctrl`+`K`

# DMSWARM

“swarm” - A `DM` object used to represent arrays of data (fields) of arbitrary data type. This implementation was designed for particle methods in which the underlying data required to be represented is both (i) dynamic in length, (ii) and of arbitrary data type.

## Notes

User data can be represented by `DMSWARM` through a registering “fields”. To register a field, the user must provide; (a) a unique name; (b) the data type (or size in bytes); (c) the block size of the data.

For example, suppose the application requires a unique id, energy, momentum and density to be stored on a set of particles. Then the following code could be used

        DMSwarmInitializeFieldRegister(dm)
        DMSwarmRegisterPetscDatatypeField(dm,"uid",1,PETSC_LONG);
        DMSwarmRegisterPetscDatatypeField(dm,"energy",1,PETSC_REAL);
        DMSwarmRegisterPetscDatatypeField(dm,"momentum",3,PETSC_REAL);
        DMSwarmRegisterPetscDatatypeField(dm,"density",1,PETSC_FLOAT);
        DMSwarmFinalizeFieldRegister(dm)

The fields represented by `DMSWARM` are dynamic and can be re-sized at any time. The only restriction imposed by `DMSWARM` is that all fields contain the same number of points.

To support particle methods, “migration” techniques are provided. These methods migrate data between ranks.

`DMSWARM` supports the methods `DMCreateGlobalVector()` and `DMCreateLocalVector()`. As a `DMSWARM` may internally define and store values of different data types, before calling `DMCreateGlobalVector()` or `DMCreateLocalVector()`, the user must inform `DMSWARM` which fields should be used to define a `Vec` object via `DMSwarmVectorDefineField()` The specified field can be changed at any time - thereby permitting vectors compatible with different fields to be created.

A dual representation of fields in the `DMSWARM` and a Vec object is permitted via `DMSwarmCreateGlobalVectorFromField()` Here the data defining the field in the `DMSWARM` is shared with a Vec. This is inherently unsafe if you alter the size of the field at any time between calls to `DMSwarmCreateGlobalVectorFromField()` and `DMSwarmDestroyGlobalVectorFromField()`. If the local size of the `DMSWARM` does not match the local size of the global vector when `DMSwarmDestroyGlobalVectorFromField()` is called, an error is thrown.

Additional high-level support is provided for Particle-In-Cell methods. Please refer to `DMSwarmSetType()`.

## See Also

`DM`, `DMSWARM`, `DMType`, `DMCreate()`, `DMSetType()`

## Level

intermediate

## Location

src/dm/impls/swarm/swarm.c

## Examples

src/dm/impls/swarm/tutorials/ex1.c
src/dm/impls/swarm/tutorials/ex1f90.F90
src/dm/tutorials/swarm_ex1.c
src/dm/tutorials/ex21.c
src/dm/tutorials/swarm_ex2.c
src/ksp/ksp/tutorials/ex70.c
src/snes/tutorials/ex63.c
src/dm/tutorials/swarm_ex3.c
src/dm/tutorials/ex20.c

Index of all DMSwarm routines
Table of Contents for all manual pages
Index of all manual pages