Actual source code: petscdmswarm.h
1: #pragma once
3: #include <petscdm.h>
4: #include <petscdt.h>
6: /* MANSEC = DM */
7: /* SUBMANSEC = DMSwarm */
9: /*S
10: DMSwarmDataField - Opaque handle to a single named field of particle data stored inside a `DMSwarmDataBucket`
12: Level: developer
14: Note:
15: Each `DMSwarmDataField` records the field name, the per-particle data type and a contiguous storage block whose length matches the number of particles in the parent `DMSwarmDataBucket`.
17: .seealso: `DMSWARM`, `DMSwarmDataBucket`, `DMSwarmDataBucketGetDMSwarmDataFieldByName()`, `DMSwarmDataFieldGetEntries()`
18: S*/
19: typedef struct _p_DMSwarmDataField *DMSwarmDataField;
21: /*S
22: DMSwarmDataBucket - Opaque internal container that groups all of a `DMSWARM`'s per-particle fields (`DMSwarmDataField`) and the current particle count
24: Level: developer
26: Note:
27: Used internally by `DMSWARM` to store the particle state; user code normally interacts with the
28: `DMSWARM` API rather than this container directly.
30: .seealso: `DMSWARM`, `DMSwarmDataField`, `DMSwarmRegisterPetscDatatypeField()`
31: S*/
32: typedef struct _p_DMSwarmDataBucket *DMSwarmDataBucket;
34: /*S
35: DMSwarmSort - PETSc object for sorting `DMSWARM` particles into `DM` cells. Sort particles by their background cell index for fast cell-to-particle lookups.
37: Level: developer
39: .seealso: [](ch_dmbase), `DM`, `DMSWARM`, `DMSwarmSortGetAccess()`, `DMSwarmSortRestoreAccess()`, `DMSwarmSortGetIsValid()`, `DMSwarmSortCreate()`, `DMSwarmSortDestroy()`
40: S*/
41: typedef struct _p_DMSwarmSort *DMSwarmSort;
42: PETSC_EXTERN PetscClassId DMSWARMSORT_CLASSID;
44: /*E
45: DMSwarmType - Defines the type of `DMSWARM`
47: Values:
48: + `DMSWARM_BASIC` - defines N entries of varied data-types which the user may register.
49: - `DMSWARM_PIC` - suitable for particle-in-cell methods. Configured as `DMSWARM_PIC`, the swarm will be aware of, another `DM` which serves as the background mesh.
51: Fields specific to particle-in-cell methods are registered by default. These include spatial coordinates, a unique identifier, a cell index and an index for
52: the owning rank. The background mesh will (by default) define the spatial decomposition of the points defined in the swarm. `DMSWARM_PIC` provides support
53: for particle-in-cell operations such as defining initial point coordinates, communicating particles between sub-domains, projecting particle data fields on to the mesh.
55: Level: beginner
57: .seealso: [](ch_dmbase), `DMSWARM`, `DMSwarmSetType()`
58: E*/
59: typedef enum {
60: DMSWARM_BASIC,
61: DMSWARM_PIC
62: } DMSwarmType;
63: PETSC_EXTERN const char *DMSwarmTypeNames[];
65: /*E
66: DMSwarmMigrateType - Selects the algorithm used by `DMSwarmMigrate()` to move particles between MPI processes
68: Values:
69: + `DMSWARM_MIGRATE_BASIC` - inspect each particle's owner rank and send it to that rank; assumes the user (or another code path) has already set the rank field correctly
70: . `DMSWARM_MIGRATE_DMCELLNSCATTER` - use the background `DM` to determine the target rank approximately, then scatter without verifying that the destination cell
71: contains the point (cheaper, can leave particles in neighbors)
72: . `DMSWARM_MIGRATE_DMCELLEXACT` - use the background `DM` and perform an exact point-location step before sending (more expensive, guarantees correct placement)
73: - `DMSWARM_MIGRATE_USER` - call a user-supplied migration function rather than one of the built-in strategies
75: Level: intermediate
77: .seealso: [](ch_dmbase), `DM`, `DMSWARM`, `DMSwarmMigrate()`, `DMSwarmSetMigrateType()`, `DMSwarmGetMigrateType()`
78: E*/
79: typedef enum {
80: DMSWARM_MIGRATE_BASIC,
81: DMSWARM_MIGRATE_DMCELLNSCATTER,
82: DMSWARM_MIGRATE_DMCELLEXACT,
83: DMSWARM_MIGRATE_USER
84: } DMSwarmMigrateType;
85: PETSC_EXTERN const char *DMSwarmMigrateTypeNames[];
87: /*E
88: DMSwarmCollectType - Selects the algorithm used by `DMSwarmCollectViewCreate()` to gather particles from neighboring subdomains into a temporary view
90: Values:
91: + `DMSWARM_COLLECT_BASIC` - simply concatenate every particle from every other process (used mainly for testing)
92: . `DMSWARM_COLLECT_DMDABOUNDINGBOX` - collect particles that lie inside the local subdomain bounding box of an attached `DMDA`
93: . `DMSWARM_COLLECT_GENERAL` - collect particles that lie inside a user-specified region of space
94: - `DMSWARM_COLLECT_USER` - call a user-supplied collection function
96: Level: intermediate
98: .seealso: [](ch_dmbase), `DM`, `DMSWARM`, `DMSwarmCollectViewCreate()`, `DMSwarmMigrate()`
99: E*/
100: typedef enum {
101: DMSWARM_COLLECT_BASIC,
102: DMSWARM_COLLECT_DMDABOUNDINGBOX,
103: DMSWARM_COLLECT_GENERAL,
104: DMSWARM_COLLECT_USER
105: } DMSwarmCollectType;
106: PETSC_EXTERN const char *DMSwarmCollectTypeNames[];
108: /*E
109: DMSwarmRemapType - Selects the remapping (resampling) scheme applied to a `DMSWARM` to maintain particle distribution quality
111: Values:
112: + `DMSWARM_REMAP_NONE` - do not remap particles
113: . `DMSWARM_REMAP_PFAK` - the particle remapping method that uses projection to a continuum preserving the moments {cite}`adamsfinnknepleypusztay2025`
114: - `DMSWARM_REMAP_COLELLA` - the Colella remap that uses an interpolation-based redistribution suited to particle-in-cell methods
116: Level: intermediate
118: .seealso: [](ch_dmbase), `DM`, `DMSWARM`
119: E*/
120: typedef enum {
121: DMSWARM_REMAP_NONE = 0,
122: DMSWARM_REMAP_PFAK = 1,
123: DMSWARM_REMAP_COLELLA = 2
124: } DMSwarmRemapType;
125: PETSC_EXTERN const char *DMSwarmRemapTypeNames[];
127: /*E
128: DMSwarmPICLayoutType - Defines the method used to define particle coordinates within each cell. The layouts are constructured using the reference cell geometry
130: Values:
131: + `DMSWARMPIC_LAYOUT_REGULAR` - defines points on a regular ijk mesh. In this case
132: the `fill_param` argument of `DMSwarmInsertPointsUsingCellDM()` defines the number of points in each spatial direction.
133: . `DMSWARMPIC_LAYOUT_GAUSS` - defines points using an npoint Gauss-Legendre tensor product quadrature rule. In this case
134: the `fill_param` argument of `DMSwarmInsertPointsUsingCellDM()` defines the number of quadrature points in each spatial direction.
135: - `DMSWARMPIC_LAYOUT_SUBDIVISION` - defines points on the centroid of a sub-divided reference cell. In this case
136: the `fill_param` argument of `DMSwarmInsertPointsUsingCellDM()` defines the number times the reference cell is sub-divided.
138: Level: beginner
140: .seealso: [](ch_dmbase), `DMSWARM`, `DM`, `DMSwarmInsertPointsUsingCellDM()`
141: E*/
142: typedef enum {
143: DMSWARMPIC_LAYOUT_REGULAR,
144: DMSWARMPIC_LAYOUT_GAUSS,
145: DMSWARMPIC_LAYOUT_SUBDIVISION
146: } DMSwarmPICLayoutType;
148: /*S
149: DMSwarmCellDM - PETSc object for defining a background `DM` for the `DMSWARM` particles
151: Level: intermediate
153: .seealso: [](ch_dmbase), `DM`, `DMSwarmAddCellDM()`, `DMSwarmCellDMCreate()`
154: S*/
155: typedef struct _p_DMSwarmCellDM *DMSwarmCellDM;
156: PETSC_EXTERN PetscClassId DMSWARMCELLDM_CLASSID;
158: PETSC_EXTERN const char DMSwarmField_pid[];
159: PETSC_EXTERN const char DMSwarmField_rank[];
160: PETSC_EXTERN const char DMSwarmPICField_coor[];
162: PETSC_EXTERN PetscErrorCode DMSwarmCreateGlobalVectorFromField(DM, const char[], Vec *);
163: PETSC_EXTERN PetscErrorCode DMSwarmDestroyGlobalVectorFromField(DM, const char[], Vec *);
164: PETSC_EXTERN PetscErrorCode DMSwarmCreateLocalVectorFromField(DM, const char[], Vec *);
165: PETSC_EXTERN PetscErrorCode DMSwarmDestroyLocalVectorFromField(DM, const char[], Vec *);
166: PETSC_EXTERN PetscErrorCode DMSwarmCreateGlobalVectorFromFields(DM, PetscInt, const char *[], Vec *);
167: PETSC_EXTERN PetscErrorCode DMSwarmDestroyGlobalVectorFromFields(DM, PetscInt, const char *[], Vec *);
168: PETSC_EXTERN PetscErrorCode DMSwarmCreateLocalVectorFromFields(DM, PetscInt, const char *[], Vec *);
169: PETSC_EXTERN PetscErrorCode DMSwarmDestroyLocalVectorFromFields(DM, PetscInt, const char *[], Vec *);
171: PETSC_EXTERN PetscErrorCode DMSwarmInitializeFieldRegister(DM);
172: PETSC_EXTERN PetscErrorCode DMSwarmFinalizeFieldRegister(DM);
173: PETSC_EXTERN PetscErrorCode DMSwarmSetLocalSizes(DM, PetscInt, PetscInt);
174: PETSC_EXTERN PetscErrorCode DMSwarmRegisterPetscDatatypeField(DM, const char[], PetscInt, PetscDataType);
175: PETSC_EXTERN PetscErrorCode DMSwarmRegisterUserStructField(DM, const char[], size_t);
176: PETSC_EXTERN PetscErrorCode DMSwarmRegisterUserDatatypeField(DM, const char[], size_t, PetscInt);
177: PETSC_EXTERN PetscErrorCode DMSwarmGetField(DM, const char[], PetscInt *, PetscDataType *, void **);
178: PETSC_EXTERN PetscErrorCode DMSwarmRestoreField(DM, const char[], PetscInt *, PetscDataType *, void **);
179: PETSC_EXTERN PetscErrorCode DMSwarmGetFieldInfo(DM, const char[], PetscInt *, PetscDataType *);
181: PETSC_EXTERN PetscErrorCode DMSwarmVectorDefineField(DM, const char[]);
182: PETSC_EXTERN PetscErrorCode DMSwarmVectorDefineFields(DM, PetscInt, const char *[]);
183: PETSC_EXTERN PetscErrorCode DMSwarmVectorGetField(DM, PetscInt *, const char **[]);
185: PETSC_EXTERN PetscErrorCode DMSwarmAddPoint(DM);
186: PETSC_EXTERN PetscErrorCode DMSwarmAddNPoints(DM, PetscInt);
187: PETSC_EXTERN PetscErrorCode DMSwarmRemovePoint(DM);
188: PETSC_EXTERN PetscErrorCode DMSwarmRemovePointAtIndex(DM, PetscInt);
189: PETSC_EXTERN PetscErrorCode DMSwarmCopyPoint(DM, PetscInt, PetscInt);
191: PETSC_EXTERN PetscErrorCode DMSwarmGetLocalSize(DM, PetscInt *);
192: PETSC_EXTERN PetscErrorCode DMSwarmGetSize(DM, PetscInt *);
193: PETSC_EXTERN PetscErrorCode DMSwarmGetMigrateType(DM, DMSwarmMigrateType *);
194: PETSC_EXTERN PetscErrorCode DMSwarmSetMigrateType(DM, DMSwarmMigrateType);
195: PETSC_EXTERN PetscErrorCode DMSwarmMigrate(DM, PetscBool);
197: PETSC_EXTERN PetscErrorCode DMSwarmCollectViewCreate(DM);
198: PETSC_EXTERN PetscErrorCode DMSwarmCollectViewDestroy(DM);
199: PETSC_EXTERN PetscErrorCode DMSwarmSetCellDM(DM, DM);
200: PETSC_EXTERN PetscErrorCode DMSwarmGetCellDM(DM, DM *);
201: PETSC_EXTERN PetscErrorCode DMSwarmGetCellDMByName(DM, const char[], DMSwarmCellDM *);
202: PETSC_EXTERN PetscErrorCode DMSwarmGetCellDMNames(DM, PetscInt *, const char **[]);
203: PETSC_EXTERN PetscErrorCode DMSwarmSetCellDMActive(DM, const char[]);
204: PETSC_EXTERN PetscErrorCode DMSwarmGetCellDMActive(DM, DMSwarmCellDM *);
205: PETSC_EXTERN PetscErrorCode DMSwarmAddCellDM(DM, DMSwarmCellDM);
207: PETSC_EXTERN PetscErrorCode DMSwarmGetType(DM, DMSwarmType *);
208: PETSC_EXTERN PetscErrorCode DMSwarmSetType(DM, DMSwarmType);
210: PETSC_EXTERN PetscErrorCode DMSwarmSetPointsUniformCoordinates(DM, PetscReal *, PetscReal *, PetscInt *, InsertMode);
211: PETSC_EXTERN PetscErrorCode DMSwarmSetPointCoordinates(DM, PetscInt, PetscReal *, PetscBool, InsertMode);
212: PETSC_EXTERN PetscErrorCode DMSwarmInsertPointsUsingCellDM(DM, DMSwarmPICLayoutType, PetscInt);
213: PETSC_EXTERN PetscErrorCode DMSwarmSetPointCoordinatesCellwise(DM, PetscInt, PetscReal *);
214: PETSC_EXTERN PetscErrorCode DMSwarmSetPointCoordinatesRandom(DM, PetscInt);
215: PETSC_EXTERN PetscErrorCode DMSwarmViewFieldsXDMF(DM, const char *, PetscInt, const char *[]);
216: PETSC_EXTERN PetscErrorCode DMSwarmViewXDMF(DM, const char *);
218: PETSC_EXTERN PetscErrorCode DMSwarmSortDestroy(DMSwarmSort *);
219: PETSC_EXTERN PetscErrorCode DMSwarmSortView(DMSwarmSort, PetscViewer);
220: PETSC_EXTERN PetscErrorCode DMSwarmSortGetAccess(DM);
221: PETSC_EXTERN PetscErrorCode DMSwarmSortRestoreAccess(DM);
222: PETSC_EXTERN PetscErrorCode DMSwarmSortGetPointsPerCell(DM, PetscInt, PetscInt *, PetscInt **);
223: PETSC_EXTERN PetscErrorCode DMSwarmSortRestorePointsPerCell(DM, PetscInt, PetscInt *, PetscInt **);
224: PETSC_EXTERN PetscErrorCode DMSwarmSortGetNumberOfPointsPerCell(DM, PetscInt, PetscInt *);
225: PETSC_EXTERN PetscErrorCode DMSwarmSortGetIsValid(DM, PetscBool *);
226: PETSC_EXTERN PetscErrorCode DMSwarmSortGetSizes(DM, PetscInt *, PetscInt *);
228: PETSC_EXTERN PetscErrorCode DMSwarmCreateMassMatrixSquare(DM, DM, Mat *);
230: PETSC_EXTERN PetscErrorCode DMSwarmGetCellSwarm(DM, PetscInt, DM);
231: PETSC_EXTERN PetscErrorCode DMSwarmRestoreCellSwarm(DM, PetscInt, DM);
232: PETSC_EXTERN PetscErrorCode DMSwarmGetNumSpecies(DM, PetscInt *);
233: PETSC_EXTERN PetscErrorCode DMSwarmSetNumSpecies(DM, PetscInt);
234: PETSC_EXTERN PetscErrorCode DMSwarmGetCoordinateFunction(DM, PetscErrorCode (**)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
235: PETSC_EXTERN PetscErrorCode DMSwarmSetCoordinateFunction(DM, PetscErrorCode (*)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
236: PETSC_EXTERN PetscErrorCode DMSwarmGetVelocityFunction(DM, PetscErrorCode (**)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
237: PETSC_EXTERN PetscErrorCode DMSwarmSetVelocityFunction(DM, PetscErrorCode (*)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
238: PETSC_EXTERN PetscErrorCode DMSwarmComputeLocalSize(DM, PetscInt, PetscProbFn *);
239: PETSC_EXTERN PetscErrorCode DMSwarmComputeLocalSizeFromOptions(DM);
240: PETSC_EXTERN PetscErrorCode DMSwarmInitializeCoordinates(DM);
241: PETSC_EXTERN PetscErrorCode DMSwarmInitializeVelocities(DM, PetscProbFn *, const PetscReal[]);
242: PETSC_EXTERN PetscErrorCode DMSwarmInitializeVelocitiesFromOptions(DM, const PetscReal[]);
244: PETSC_EXTERN PetscErrorCode DMSwarmCreatePointPerCellCount(DM, PetscInt *, PetscInt **);
246: // Interface to internal storage
247: PETSC_EXTERN PetscErrorCode DMSwarmDataFieldGetEntries(const DMSwarmDataField, void **);
248: PETSC_EXTERN PetscErrorCode DMSwarmDataFieldRestoreEntries(const DMSwarmDataField, void **);
249: PETSC_EXTERN PetscErrorCode DMSwarmDataBucketGetDMSwarmDataFieldByName(DMSwarmDataBucket, const char[], DMSwarmDataField *);
250: PETSC_EXTERN PetscErrorCode DMSwarmDataBucketGetDMSwarmDataFieldIdByName(DMSwarmDataBucket, const char[], PetscInt *);
251: PETSC_EXTERN PetscErrorCode DMSwarmDataBucketQueryDMSwarmDataFieldByName(DMSwarmDataBucket, const char[], PetscBool *);
253: PETSC_EXTERN PetscErrorCode DMSwarmDuplicate(DM, DM *);
254: PETSC_EXTERN PetscErrorCode DMSwarmRemap(DM);
255: PETSC_EXTERN PetscErrorCode DMSwarmReplace(DM, DM *);
257: PETSC_EXTERN PetscErrorCode DMSwarmComputeMoments(DM, const char[], const char[], PetscReal[]);
259: PETSC_EXTERN PetscErrorCode DMSwarmCellDMCreate(DM, PetscInt, const char *[], PetscInt, const char *[], DMSwarmCellDM *);
260: PETSC_EXTERN PetscErrorCode DMSwarmCellDMDestroy(DMSwarmCellDM *);
261: PETSC_EXTERN PetscErrorCode DMSwarmCellDMView(DMSwarmCellDM, PetscViewer);
262: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetDM(DMSwarmCellDM, DM *);
263: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetFields(DMSwarmCellDM, PetscInt *, const char **[]);
264: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetCoordinateFields(DMSwarmCellDM, PetscInt *, const char **[]);
265: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetCellID(DMSwarmCellDM, const char *[]);
266: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetSort(DMSwarmCellDM, DMSwarmSort *);
267: PETSC_EXTERN PetscErrorCode DMSwarmCellDMSetSort(DMSwarmCellDM, DMSwarmSort);
268: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetBlockSize(DMSwarmCellDM, DM, PetscInt *);
270: PETSC_EXTERN PetscErrorCode DMSwarmPreallocateMassMatrix(DM, DM, Mat, PetscInt *, PetscInt *, PetscCtx);
271: PETSC_EXTERN PetscErrorCode DMSwarmFillMassMatrix(DM, DM, Mat, PetscInt, PetscInt, PetscBool, PetscInt, const PetscInt[], PetscReal *[], PetscCtx);