Date: 2026-07-30T21:13:58+00:00

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;

     43: /*E
     44:    DMSwarmType - Defines the type of `DMSWARM`

     46:    Values:
     47: +  `DMSWARM_BASIC` - defines N entries of varied data-types which the user may register.
     48: -  `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.

     50:    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
     51:    the owning rank. The background mesh will (by default) define the spatial decomposition of the points defined in the swarm. `DMSWARM_PIC` provides support
     52:    for particle-in-cell operations such as defining initial point coordinates, communicating particles between sub-domains, projecting particle data fields on to the mesh.

     54:    Level: beginner

     56: .seealso: [](ch_dmbase), `DMSWARM`, `DMSwarmSetType()`
     57: E*/
     58: typedef enum {
     59:   DMSWARM_BASIC,
     60:   DMSWARM_PIC
     61: } DMSwarmType;
     62: PETSC_EXTERN const char *DMSwarmTypeNames[];

     64: /*E
     65:    DMSwarmMigrateType - Selects the algorithm used by `DMSwarmMigrate()` to move particles between MPI processes

     67:    Values:
     68: +   `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
     69: .   `DMSWARM_MIGRATE_DMCELLNSCATTER` - use the background `DM` to determine the target rank approximately, then scatter without verifying that the destination cell
     70:                                        contains the point (cheaper, can leave particles in neighbors)
     71: .   `DMSWARM_MIGRATE_DMCELLEXACT`    - use the background `DM` and perform an exact point-location step before sending (more expensive, guarantees correct placement)
     72: -   `DMSWARM_MIGRATE_USER`           - call a user-supplied migration function rather than one of the built-in strategies

     74:    Level: intermediate

     76: .seealso: [](ch_dmbase), `DM`, `DMSWARM`, `DMSwarmMigrate()`, `DMSwarmSetMigrateType()`, `DMSwarmGetMigrateType()`
     77: E*/
     78: typedef enum {
     79:   DMSWARM_MIGRATE_BASIC,
     80:   DMSWARM_MIGRATE_DMCELLNSCATTER,
     81:   DMSWARM_MIGRATE_DMCELLEXACT,
     82:   DMSWARM_MIGRATE_USER
     83: } DMSwarmMigrateType;
     84: PETSC_EXTERN const char *DMSwarmMigrateTypeNames[];

     86: /*E
     87:    DMSwarmCollectType - Selects the algorithm used by `DMSwarmCollectViewCreate()` to gather particles from neighboring subdomains into a temporary view

     89:    Values:
     90: +   `DMSWARM_COLLECT_BASIC`           - simply concatenate every particle from every other process (used mainly for testing)
     91: .   `DMSWARM_COLLECT_DMDABOUNDINGBOX` - collect particles that lie inside the local subdomain bounding box of an attached `DMDA`
     92: .   `DMSWARM_COLLECT_GENERAL`         - collect particles that lie inside a user-specified region of space
     93: -   `DMSWARM_COLLECT_USER`            - call a user-supplied collection function

     95:    Level: intermediate

     97: .seealso: [](ch_dmbase), `DM`, `DMSWARM`, `DMSwarmCollectViewCreate()`, `DMSwarmMigrate()`
     98: E*/
     99: typedef enum {
    100:   DMSWARM_COLLECT_BASIC,
    101:   DMSWARM_COLLECT_DMDABOUNDINGBOX,
    102:   DMSWARM_COLLECT_GENERAL,
    103:   DMSWARM_COLLECT_USER
    104: } DMSwarmCollectType;
    105: PETSC_EXTERN const char *DMSwarmCollectTypeNames[];

    107: /*E
    108:    DMSwarmRemapType - Selects the remapping (resampling) scheme applied to a `DMSWARM` to maintain particle distribution quality

    110:    Values:
    111: +   `DMSWARM_REMAP_NONE`    - do not remap particles
    112: .   `DMSWARM_REMAP_PFAK`    - the particle remapping method that uses projection to a continuum preserving the moments {cite}`adamsfinnknepleypusztay2025`
    113: -   `DMSWARM_REMAP_COLELLA` - the Colella remap that uses an interpolation-based redistribution suited to particle-in-cell methods

    115:    Level: intermediate

    117: .seealso: [](ch_dmbase), `DM`, `DMSWARM`
    118: E*/
    119: typedef enum {
    120:   DMSWARM_REMAP_NONE    = 0,
    121:   DMSWARM_REMAP_PFAK    = 1,
    122:   DMSWARM_REMAP_COLELLA = 2
    123: } DMSwarmRemapType;
    124: PETSC_EXTERN const char *DMSwarmRemapTypeNames[];

    126: /*E
    127:    DMSwarmPICLayoutType - Defines the method used to define particle coordinates within each cell. The layouts are constructured using the reference cell geometry

    129:    Values:
    130: +  `DMSWARMPIC_LAYOUT_REGULAR`     - defines points on a regular ijk mesh. In this case
    131:                                      the `fill_param` argument of `DMSwarmInsertPointsUsingCellDM()` defines the number of points in each spatial direction.
    132: .  `DMSWARMPIC_LAYOUT_GAUSS`       - defines points using an npoint Gauss-Legendre tensor product quadrature rule. In this case
    133:                                      the `fill_param` argument of `DMSwarmInsertPointsUsingCellDM()` defines the number of quadrature points in each spatial direction.
    134: -  `DMSWARMPIC_LAYOUT_SUBDIVISION` - defines points on the centroid of a sub-divided reference cell. In this case
    135:                                      the `fill_param` argument of `DMSwarmInsertPointsUsingCellDM()` defines the number times the reference cell is sub-divided.

    137:    Level: beginner

    139: .seealso: [](ch_dmbase), `DMSWARM`, `DM`, `DMSwarmInsertPointsUsingCellDM()`
    140: E*/
    141: typedef enum {
    142:   DMSWARMPIC_LAYOUT_REGULAR,
    143:   DMSWARMPIC_LAYOUT_GAUSS,
    144:   DMSWARMPIC_LAYOUT_SUBDIVISION
    145: } DMSwarmPICLayoutType;

    147: /*S
    148:     DMSwarmCellDM - PETSc object for defining a background `DM` for the `DMSWARM` particles

    150:     Level: intermediate

    152: .seealso: [](ch_dmbase), `DM`, `DMSwarmAddCellDM()`, `DMSwarmCellDMCreate()`
    153: S*/
    154: typedef struct _p_DMSwarmCellDM *DMSwarmCellDM;
    155: PETSC_EXTERN PetscClassId        DMSWARMCELLDM_CLASSID;

    157: PETSC_EXTERN const char DMSwarmField_pid[];
    158: PETSC_EXTERN const char DMSwarmField_rank[];
    159: PETSC_EXTERN const char DMSwarmPICField_coor[];

    161: PETSC_EXTERN PetscErrorCode DMSwarmCreateGlobalVectorFromField(DM, const char[], Vec *);
    162: PETSC_EXTERN PetscErrorCode DMSwarmDestroyGlobalVectorFromField(DM, const char[], Vec *);
    163: PETSC_EXTERN PetscErrorCode DMSwarmCreateLocalVectorFromField(DM, const char[], Vec *);
    164: PETSC_EXTERN PetscErrorCode DMSwarmDestroyLocalVectorFromField(DM, const char[], Vec *);
    165: PETSC_EXTERN PetscErrorCode DMSwarmCreateGlobalVectorFromFields(DM, PetscInt, const char *[], Vec *);
    166: PETSC_EXTERN PetscErrorCode DMSwarmDestroyGlobalVectorFromFields(DM, PetscInt, const char *[], Vec *);
    167: PETSC_EXTERN PetscErrorCode DMSwarmCreateLocalVectorFromFields(DM, PetscInt, const char *[], Vec *);
    168: PETSC_EXTERN PetscErrorCode DMSwarmDestroyLocalVectorFromFields(DM, PetscInt, const char *[], Vec *);

    170: PETSC_EXTERN PetscErrorCode DMSwarmInitializeFieldRegister(DM);
    171: PETSC_EXTERN PetscErrorCode DMSwarmFinalizeFieldRegister(DM);
    172: PETSC_EXTERN PetscErrorCode DMSwarmSetLocalSizes(DM, PetscInt, PetscInt);
    173: PETSC_EXTERN PetscErrorCode DMSwarmRegisterPetscDatatypeField(DM, const char[], PetscInt, PetscDataType);
    174: PETSC_EXTERN PetscErrorCode DMSwarmRegisterUserStructField(DM, const char[], size_t);
    175: PETSC_EXTERN PetscErrorCode DMSwarmRegisterUserDatatypeField(DM, const char[], size_t, PetscInt);
    176: PETSC_EXTERN PetscErrorCode DMSwarmGetField(DM, const char[], PetscInt *, PetscDataType *, void **);
    177: PETSC_EXTERN PetscErrorCode DMSwarmRestoreField(DM, const char[], PetscInt *, PetscDataType *, void **);
    178: PETSC_EXTERN PetscErrorCode DMSwarmGetFieldInfo(DM, const char[], PetscInt *, PetscDataType *);

    180: PETSC_EXTERN PetscErrorCode DMSwarmVectorDefineField(DM, const char[]);
    181: PETSC_EXTERN PetscErrorCode DMSwarmVectorDefineFields(DM, PetscInt, const char *[]);
    182: PETSC_EXTERN PetscErrorCode DMSwarmVectorGetField(DM, PetscInt *, const char **[]);

    184: PETSC_EXTERN PetscErrorCode DMSwarmAddPoint(DM);
    185: PETSC_EXTERN PetscErrorCode DMSwarmAddNPoints(DM, PetscInt);
    186: PETSC_EXTERN PetscErrorCode DMSwarmRemovePoint(DM);
    187: PETSC_EXTERN PetscErrorCode DMSwarmRemovePointAtIndex(DM, PetscInt);
    188: PETSC_EXTERN PetscErrorCode DMSwarmCopyPoint(DM, PetscInt, PetscInt);

    190: PETSC_EXTERN PetscErrorCode DMSwarmGetLocalSize(DM, PetscInt *);
    191: PETSC_EXTERN PetscErrorCode DMSwarmGetSize(DM, PetscInt *);
    192: PETSC_EXTERN PetscErrorCode DMSwarmGetMigrateType(DM, DMSwarmMigrateType *);
    193: PETSC_EXTERN PetscErrorCode DMSwarmSetMigrateType(DM, DMSwarmMigrateType);
    194: PETSC_EXTERN PetscErrorCode DMSwarmMigrate(DM, PetscBool);

    196: PETSC_EXTERN PetscErrorCode DMSwarmCollectViewCreate(DM);
    197: PETSC_EXTERN PetscErrorCode DMSwarmCollectViewDestroy(DM);
    198: PETSC_EXTERN PetscErrorCode DMSwarmSetCellDM(DM, DM);
    199: PETSC_EXTERN PetscErrorCode DMSwarmGetCellDM(DM, DM *);
    200: PETSC_EXTERN PetscErrorCode DMSwarmGetCellDMByName(DM, const char[], DMSwarmCellDM *);
    201: PETSC_EXTERN PetscErrorCode DMSwarmGetCellDMNames(DM, PetscInt *, const char **[]);
    202: PETSC_EXTERN PetscErrorCode DMSwarmSetCellDMActive(DM, const char[]);
    203: PETSC_EXTERN PetscErrorCode DMSwarmGetCellDMActive(DM, DMSwarmCellDM *);
    204: PETSC_EXTERN PetscErrorCode DMSwarmAddCellDM(DM, DMSwarmCellDM);

    206: PETSC_EXTERN PetscErrorCode DMSwarmGetType(DM, DMSwarmType *);
    207: PETSC_EXTERN PetscErrorCode DMSwarmSetType(DM, DMSwarmType);

    209: PETSC_EXTERN PetscErrorCode DMSwarmSetPointsUniformCoordinates(DM, PetscReal *, PetscReal *, PetscInt *, InsertMode);
    210: PETSC_EXTERN PetscErrorCode DMSwarmSetPointCoordinates(DM, PetscInt, PetscReal *, PetscBool, InsertMode);
    211: PETSC_EXTERN PetscErrorCode DMSwarmInsertPointsUsingCellDM(DM, DMSwarmPICLayoutType, PetscInt);
    212: PETSC_EXTERN PetscErrorCode DMSwarmSetPointCoordinatesCellwise(DM, PetscInt, PetscReal *);
    213: PETSC_EXTERN PetscErrorCode DMSwarmSetPointCoordinatesRandom(DM, PetscInt);
    214: PETSC_EXTERN PetscErrorCode DMSwarmViewFieldsXDMF(DM, const char *, PetscInt, const char **);
    215: PETSC_EXTERN PetscErrorCode DMSwarmViewXDMF(DM, const char *);

    217: PETSC_EXTERN PetscErrorCode DMSwarmSortDestroy(DMSwarmSort *);
    218: PETSC_EXTERN PetscErrorCode DMSwarmSortGetAccess(DM);
    219: PETSC_EXTERN PetscErrorCode DMSwarmSortRestoreAccess(DM);
    220: PETSC_EXTERN PetscErrorCode DMSwarmSortGetPointsPerCell(DM, PetscInt, PetscInt *, PetscInt **);
    221: PETSC_EXTERN PetscErrorCode DMSwarmSortRestorePointsPerCell(DM, PetscInt, PetscInt *, PetscInt **);
    222: PETSC_EXTERN PetscErrorCode DMSwarmSortGetNumberOfPointsPerCell(DM, PetscInt, PetscInt *);
    223: PETSC_EXTERN PetscErrorCode DMSwarmSortGetIsValid(DM, PetscBool *);
    224: PETSC_EXTERN PetscErrorCode DMSwarmSortGetSizes(DM, PetscInt *, PetscInt *);

    226: PETSC_EXTERN PetscErrorCode DMSwarmCreateMassMatrixSquare(DM, DM, Mat *);

    228: PETSC_EXTERN PetscErrorCode DMSwarmGetCellSwarm(DM, PetscInt, DM);
    229: PETSC_EXTERN PetscErrorCode DMSwarmRestoreCellSwarm(DM, PetscInt, DM);
    230: PETSC_EXTERN PetscErrorCode DMSwarmGetNumSpecies(DM, PetscInt *);
    231: PETSC_EXTERN PetscErrorCode DMSwarmSetNumSpecies(DM, PetscInt);
    232: PETSC_EXTERN PetscErrorCode DMSwarmGetCoordinateFunction(DM, PetscErrorCode (**)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
    233: PETSC_EXTERN PetscErrorCode DMSwarmSetCoordinateFunction(DM, PetscErrorCode (*)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
    234: PETSC_EXTERN PetscErrorCode DMSwarmGetVelocityFunction(DM, PetscErrorCode (**)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
    235: PETSC_EXTERN PetscErrorCode DMSwarmSetVelocityFunction(DM, PetscErrorCode (*)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
    236: PETSC_EXTERN PetscErrorCode DMSwarmComputeLocalSize(DM, PetscInt, PetscProbFn *);
    237: PETSC_EXTERN PetscErrorCode DMSwarmComputeLocalSizeFromOptions(DM);
    238: PETSC_EXTERN PetscErrorCode DMSwarmInitializeCoordinates(DM);
    239: PETSC_EXTERN PetscErrorCode DMSwarmInitializeVelocities(DM, PetscProbFn *, const PetscReal[]);
    240: PETSC_EXTERN PetscErrorCode DMSwarmInitializeVelocitiesFromOptions(DM, const PetscReal[]);

    242: PETSC_EXTERN PetscErrorCode DMSwarmCreatePointPerCellCount(DM, PetscInt *, PetscInt **);

    244: // Interface to internal storage
    245: PETSC_EXTERN PetscErrorCode DMSwarmDataFieldGetEntries(const DMSwarmDataField, void **);
    246: PETSC_EXTERN PetscErrorCode DMSwarmDataFieldRestoreEntries(const DMSwarmDataField, void **);
    247: PETSC_EXTERN PetscErrorCode DMSwarmDataBucketGetDMSwarmDataFieldByName(DMSwarmDataBucket, const char[], DMSwarmDataField *);
    248: PETSC_EXTERN PetscErrorCode DMSwarmDataBucketGetDMSwarmDataFieldIdByName(DMSwarmDataBucket, const char[], PetscInt *);
    249: PETSC_EXTERN PetscErrorCode DMSwarmDataBucketQueryDMSwarmDataFieldByName(DMSwarmDataBucket, const char[], PetscBool *);

    251: PETSC_EXTERN PetscErrorCode DMSwarmDuplicate(DM, DM *);
    252: PETSC_EXTERN PetscErrorCode DMSwarmRemap(DM);
    253: PETSC_EXTERN PetscErrorCode DMSwarmReplace(DM, DM *);

    255: PETSC_EXTERN PetscErrorCode DMSwarmComputeMoments(DM, const char[], const char[], PetscReal[]);

    257: PETSC_EXTERN PetscErrorCode DMSwarmCellDMCreate(DM, PetscInt, const char *[], PetscInt, const char *[], DMSwarmCellDM *);
    258: PETSC_EXTERN PetscErrorCode DMSwarmCellDMDestroy(DMSwarmCellDM *);
    259: PETSC_EXTERN PetscErrorCode DMSwarmCellDMView(DMSwarmCellDM, PetscViewer);
    260: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetDM(DMSwarmCellDM, DM *);
    261: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetFields(DMSwarmCellDM, PetscInt *, const char **[]);
    262: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetCoordinateFields(DMSwarmCellDM, PetscInt *, const char **[]);
    263: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetCellID(DMSwarmCellDM, const char *[]);
    264: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetSort(DMSwarmCellDM, DMSwarmSort *);
    265: PETSC_EXTERN PetscErrorCode DMSwarmCellDMSetSort(DMSwarmCellDM, DMSwarmSort);
    266: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetBlockSize(DMSwarmCellDM, DM, PetscInt *);