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/snes/tutorials/ex63.c

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