:orphan:
# 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
```none
    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
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/dm/impls/swarm/swarm.c.html#DMSWARM">src/dm/impls/swarm/swarm.c</A>

## Examples
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/dm/impls/swarm/tutorials/ex1.c.html">src/dm/impls/swarm/tutorials/ex1.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/dm/impls/swarm/tutorials/ex1f90.F90.html">src/dm/impls/swarm/tutorials/ex1f90.F90</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/dm/tutorials/ex20.c.html">src/dm/tutorials/ex20.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/dm/tutorials/ex21.c.html">src/dm/tutorials/ex21.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/dm/tutorials/swarm_ex1.c.html">src/dm/tutorials/swarm_ex1.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/dm/tutorials/swarm_ex2.c.html">src/dm/tutorials/swarm_ex2.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/dm/tutorials/swarm_ex3.c.html">src/dm/tutorials/swarm_ex3.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/tutorials/ex70.c.html">src/ksp/ksp/tutorials/ex70.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/snes/tutorials/ex63.c.html">src/snes/tutorials/ex63.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ts/tutorials/ex77.c.html">src/ts/tutorials/ex77.c</A><BR>


---
[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](/manualpages/index.md)  
[Index of all manual pages](/manualpages/singleindex.md)