# 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. 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
```none
DMSwarmInitializeFieldRegister(dm)
```
```none
DMSwarmRegisterPetscDatatypeField(dm,"uid",1,PETSC_LONG);
```
```none
DMSwarmRegisterPetscDatatypeField(dm,"energy",1,PETSC_REAL);
```
```none
DMSwarmRegisterPetscDatatypeField(dm,"momentum",3,PETSC_REAL);
```
```none
DMSwarmRegisterPetscDatatypeField(dm,"density",1,PETSC_FLOAT);
```
```none
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 the man page for DMSwarmSetType().
## See Also
`DMType`, `DMCreate()`, `DMSetType()`
## Level
beginner
## Location
src/dm/impls/swarm/swarm.c
## Examples
src/dm/impls/swarm/tutorials/ex1.c.html
src/dm/impls/swarm/tutorials/ex1f90.F90.html
src/dm/tutorials/ex20.c.html
src/dm/tutorials/ex21.c.html
src/dm/tutorials/swarm_ex1.c.html
src/dm/tutorials/swarm_ex2.c.html
src/dm/tutorials/swarm_ex3.c.html
src/ksp/ksp/tutorials/ex70.c.html
src/snes/tutorials/ex63.c.html
src/ts/tutorials/ex77.c.html
---
[Edit on GitLab](https://gitlab.com/petsc/petsc/-/edit/release/src/dm/impls/swarm/swarm.c)
[Index of all DMSwarm routines](index.md)
[Table of Contents for all manual pages](/docs/manualpages/index.md)
[Index of all manual pages](/docs/manualpages/singleindex.md)