Skip to main content
`Ctrl`+`K`

# DMSWARM

“swarm” - A `DM` object for particle methods, such as particle-in-cell (PIC), in which the underlying data is both (i) dynamic in length, (ii) and of arbitrary data type.

## Notes

User data can be represented by `DMSWARM` through a registering “fields” which are to be stored on particles. 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 particles.

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. Refer to `DMSwarmSetType()`.

## See Also

`DM`, `DMSWARM`, `DMType`, `DMCreate()`, `DMSetType()`, `DMSwarmSetType()`, `DMSwarmType`, `DMSwarmCreateGlobalVectorFromField()`, `DMCreateGlobalVector()`, `DMCreateLocalVector()`

## Level

intermediate

## Location

src/dm/impls/swarm/swarm.c

## Examples

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

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