Date: 2026-06-01T23:13:16+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: typedef enum {
     65:   DMSWARM_MIGRATE_BASIC,
     66:   DMSWARM_MIGRATE_DMCELLNSCATTER,
     67:   DMSWARM_MIGRATE_DMCELLEXACT,
     68:   DMSWARM_MIGRATE_USER
     69: } DMSwarmMigrateType;
     70: PETSC_EXTERN const char *DMSwarmMigrateTypeNames[];

     72: typedef enum {
     73:   DMSWARM_COLLECT_BASIC,
     74:   DMSWARM_COLLECT_DMDABOUNDINGBOX,
     75:   DMSWARM_COLLECT_GENERAL,
     76:   DMSWARM_COLLECT_USER
     77: } DMSwarmCollectType;
     78: PETSC_EXTERN const char *DMSwarmCollectTypeNames[];

     80: typedef enum {
     81:   DMSWARM_REMAP_NONE    = 0,
     82:   DMSWARM_REMAP_PFAK    = 1,
     83:   DMSWARM_REMAP_COLELLA = 2
     84: } DMSwarmRemapType;
     85: PETSC_EXTERN const char *DMSwarmRemapTypeNames[];

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

     90:    Values:
     91: +  `DMSWARMPIC_LAYOUT_REGULAR`     - defines points on a regular ijk mesh. In this case
     92:                                      the `fill_param` argument of `DMSwarmInsertPointsUsingCellDM()` defines the number of points in each spatial direction.
     93: .  `DMSWARMPIC_LAYOUT_GAUSS`       - defines points using an npoint Gauss-Legendre tensor product quadrature rule. In this case
     94:                                      the `fill_param` argument of `DMSwarmInsertPointsUsingCellDM()` defines the number of quadrature points in each spatial direction.
     95: -  `DMSWARMPIC_LAYOUT_SUBDIVISION` - defines points on the centroid of a sub-divided reference cell. In this case
     96:                                      the `fill_param` argument of `DMSwarmInsertPointsUsingCellDM()` defines the number times the reference cell is sub-divided.

     98:    Level: beginner

    100: .seealso: [](ch_dmbase), `DMSWARM`, `DM`, `DMSwarmInsertPointsUsingCellDM()`
    101: E*/
    102: typedef enum {
    103:   DMSWARMPIC_LAYOUT_REGULAR,
    104:   DMSWARMPIC_LAYOUT_GAUSS,
    105:   DMSWARMPIC_LAYOUT_SUBDIVISION
    106: } DMSwarmPICLayoutType;

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

    111:     Level: intermediate

    113: .seealso: [](ch_dmbase), `DM`, `DMSwarmAddCellDM()`, `DMSwarmCellDMCreate()`
    114: S*/
    115: typedef struct _p_DMSwarmCellDM *DMSwarmCellDM;
    116: PETSC_EXTERN PetscClassId        DMSWARMCELLDM_CLASSID;

    118: PETSC_EXTERN const char DMSwarmField_pid[];
    119: PETSC_EXTERN const char DMSwarmField_rank[];
    120: PETSC_EXTERN const char DMSwarmPICField_coor[];

    122: PETSC_EXTERN PetscErrorCode DMSwarmCreateGlobalVectorFromField(DM, const char[], Vec *);
    123: PETSC_EXTERN PetscErrorCode DMSwarmDestroyGlobalVectorFromField(DM, const char[], Vec *);
    124: PETSC_EXTERN PetscErrorCode DMSwarmCreateLocalVectorFromField(DM, const char[], Vec *);
    125: PETSC_EXTERN PetscErrorCode DMSwarmDestroyLocalVectorFromField(DM, const char[], Vec *);
    126: PETSC_EXTERN PetscErrorCode DMSwarmCreateGlobalVectorFromFields(DM, PetscInt, const char *[], Vec *);
    127: PETSC_EXTERN PetscErrorCode DMSwarmDestroyGlobalVectorFromFields(DM, PetscInt, const char *[], Vec *);
    128: PETSC_EXTERN PetscErrorCode DMSwarmCreateLocalVectorFromFields(DM, PetscInt, const char *[], Vec *);
    129: PETSC_EXTERN PetscErrorCode DMSwarmDestroyLocalVectorFromFields(DM, PetscInt, const char *[], Vec *);

    131: PETSC_EXTERN PetscErrorCode DMSwarmInitializeFieldRegister(DM);
    132: PETSC_EXTERN PetscErrorCode DMSwarmFinalizeFieldRegister(DM);
    133: PETSC_EXTERN PetscErrorCode DMSwarmSetLocalSizes(DM, PetscInt, PetscInt);
    134: PETSC_EXTERN PetscErrorCode DMSwarmRegisterPetscDatatypeField(DM, const char[], PetscInt, PetscDataType);
    135: PETSC_EXTERN PetscErrorCode DMSwarmRegisterUserStructField(DM, const char[], size_t);
    136: PETSC_EXTERN PetscErrorCode DMSwarmRegisterUserDatatypeField(DM, const char[], size_t, PetscInt);
    137: PETSC_EXTERN PetscErrorCode DMSwarmGetField(DM, const char[], PetscInt *, PetscDataType *, void **);
    138: PETSC_EXTERN PetscErrorCode DMSwarmRestoreField(DM, const char[], PetscInt *, PetscDataType *, void **);
    139: PETSC_EXTERN PetscErrorCode DMSwarmGetFieldInfo(DM, const char[], PetscInt *, PetscDataType *);

    141: PETSC_EXTERN PetscErrorCode DMSwarmVectorDefineField(DM, const char[]);
    142: PETSC_EXTERN PetscErrorCode DMSwarmVectorDefineFields(DM, PetscInt, const char *[]);
    143: PETSC_EXTERN PetscErrorCode DMSwarmVectorGetField(DM, PetscInt *, const char **[]);

    145: PETSC_EXTERN PetscErrorCode DMSwarmAddPoint(DM);
    146: PETSC_EXTERN PetscErrorCode DMSwarmAddNPoints(DM, PetscInt);
    147: PETSC_EXTERN PetscErrorCode DMSwarmRemovePoint(DM);
    148: PETSC_EXTERN PetscErrorCode DMSwarmRemovePointAtIndex(DM, PetscInt);
    149: PETSC_EXTERN PetscErrorCode DMSwarmCopyPoint(DM, PetscInt, PetscInt);

    151: PETSC_EXTERN PetscErrorCode DMSwarmGetLocalSize(DM, PetscInt *);
    152: PETSC_EXTERN PetscErrorCode DMSwarmGetSize(DM, PetscInt *);
    153: PETSC_EXTERN PetscErrorCode DMSwarmGetMigrateType(DM, DMSwarmMigrateType *);
    154: PETSC_EXTERN PetscErrorCode DMSwarmSetMigrateType(DM, DMSwarmMigrateType);
    155: PETSC_EXTERN PetscErrorCode DMSwarmMigrate(DM, PetscBool);

    157: PETSC_EXTERN PetscErrorCode DMSwarmCollectViewCreate(DM);
    158: PETSC_EXTERN PetscErrorCode DMSwarmCollectViewDestroy(DM);
    159: PETSC_EXTERN PetscErrorCode DMSwarmSetCellDM(DM, DM);
    160: PETSC_EXTERN PetscErrorCode DMSwarmGetCellDM(DM, DM *);
    161: PETSC_EXTERN PetscErrorCode DMSwarmGetCellDMByName(DM, const char[], DMSwarmCellDM *);
    162: PETSC_EXTERN PetscErrorCode DMSwarmGetCellDMNames(DM, PetscInt *, const char **[]);
    163: PETSC_EXTERN PetscErrorCode DMSwarmSetCellDMActive(DM, const char[]);
    164: PETSC_EXTERN PetscErrorCode DMSwarmGetCellDMActive(DM, DMSwarmCellDM *);
    165: PETSC_EXTERN PetscErrorCode DMSwarmAddCellDM(DM, DMSwarmCellDM);

    167: PETSC_EXTERN PetscErrorCode DMSwarmGetType(DM, DMSwarmType *);
    168: PETSC_EXTERN PetscErrorCode DMSwarmSetType(DM, DMSwarmType);

    170: PETSC_EXTERN PetscErrorCode DMSwarmSetPointsUniformCoordinates(DM, PetscReal *, PetscReal *, PetscInt *, InsertMode);
    171: PETSC_EXTERN PetscErrorCode DMSwarmSetPointCoordinates(DM, PetscInt, PetscReal *, PetscBool, InsertMode);
    172: PETSC_EXTERN PetscErrorCode DMSwarmInsertPointsUsingCellDM(DM, DMSwarmPICLayoutType, PetscInt);
    173: PETSC_EXTERN PetscErrorCode DMSwarmSetPointCoordinatesCellwise(DM, PetscInt, PetscReal *);
    174: PETSC_EXTERN PetscErrorCode DMSwarmSetPointCoordinatesRandom(DM, PetscInt);
    175: PETSC_EXTERN PetscErrorCode DMSwarmViewFieldsXDMF(DM, const char *, PetscInt, const char **);
    176: PETSC_EXTERN PetscErrorCode DMSwarmViewXDMF(DM, const char *);

    178: PETSC_EXTERN PetscErrorCode DMSwarmSortDestroy(DMSwarmSort *);
    179: PETSC_EXTERN PetscErrorCode DMSwarmSortGetAccess(DM);
    180: PETSC_EXTERN PetscErrorCode DMSwarmSortRestoreAccess(DM);
    181: PETSC_EXTERN PetscErrorCode DMSwarmSortGetPointsPerCell(DM, PetscInt, PetscInt *, PetscInt **);
    182: PETSC_EXTERN PetscErrorCode DMSwarmSortRestorePointsPerCell(DM, PetscInt, PetscInt *, PetscInt **);
    183: PETSC_EXTERN PetscErrorCode DMSwarmSortGetNumberOfPointsPerCell(DM, PetscInt, PetscInt *);
    184: PETSC_EXTERN PetscErrorCode DMSwarmSortGetIsValid(DM, PetscBool *);
    185: PETSC_EXTERN PetscErrorCode DMSwarmSortGetSizes(DM, PetscInt *, PetscInt *);

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

    189: PETSC_EXTERN PetscErrorCode DMSwarmGetCellSwarm(DM, PetscInt, DM);
    190: PETSC_EXTERN PetscErrorCode DMSwarmRestoreCellSwarm(DM, PetscInt, DM);
    191: PETSC_EXTERN PetscErrorCode DMSwarmGetNumSpecies(DM, PetscInt *);
    192: PETSC_EXTERN PetscErrorCode DMSwarmSetNumSpecies(DM, PetscInt);
    193: PETSC_EXTERN PetscErrorCode DMSwarmGetCoordinateFunction(DM, PetscErrorCode (**)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
    194: PETSC_EXTERN PetscErrorCode DMSwarmSetCoordinateFunction(DM, PetscErrorCode (*)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
    195: PETSC_EXTERN PetscErrorCode DMSwarmGetVelocityFunction(DM, PetscErrorCode (**)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
    196: PETSC_EXTERN PetscErrorCode DMSwarmSetVelocityFunction(DM, PetscErrorCode (*)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
    197: PETSC_EXTERN PetscErrorCode DMSwarmComputeLocalSize(DM, PetscInt, PetscProbFn *);
    198: PETSC_EXTERN PetscErrorCode DMSwarmComputeLocalSizeFromOptions(DM);
    199: PETSC_EXTERN PetscErrorCode DMSwarmInitializeCoordinates(DM);
    200: PETSC_EXTERN PetscErrorCode DMSwarmInitializeVelocities(DM, PetscProbFn *, const PetscReal[]);
    201: PETSC_EXTERN PetscErrorCode DMSwarmInitializeVelocitiesFromOptions(DM, const PetscReal[]);

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

    205: // Interface to internal storage
    206: PETSC_EXTERN PetscErrorCode DMSwarmDataFieldGetEntries(const DMSwarmDataField, void **);
    207: PETSC_EXTERN PetscErrorCode DMSwarmDataFieldRestoreEntries(const DMSwarmDataField, void **);
    208: PETSC_EXTERN PetscErrorCode DMSwarmDataBucketGetDMSwarmDataFieldByName(DMSwarmDataBucket, const char[], DMSwarmDataField *);
    209: PETSC_EXTERN PetscErrorCode DMSwarmDataBucketGetDMSwarmDataFieldIdByName(DMSwarmDataBucket, const char[], PetscInt *);
    210: PETSC_EXTERN PetscErrorCode DMSwarmDataBucketQueryDMSwarmDataFieldByName(DMSwarmDataBucket, const char[], PetscBool *);

    212: PETSC_EXTERN PetscErrorCode DMSwarmDuplicate(DM, DM *);
    213: PETSC_EXTERN PetscErrorCode DMSwarmRemap(DM);
    214: PETSC_EXTERN PetscErrorCode DMSwarmReplace(DM, DM *);

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

    218: PETSC_EXTERN PetscErrorCode DMSwarmCellDMCreate(DM, PetscInt, const char *[], PetscInt, const char *[], DMSwarmCellDM *);
    219: PETSC_EXTERN PetscErrorCode DMSwarmCellDMDestroy(DMSwarmCellDM *);
    220: PETSC_EXTERN PetscErrorCode DMSwarmCellDMView(DMSwarmCellDM, PetscViewer);
    221: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetDM(DMSwarmCellDM, DM *);
    222: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetFields(DMSwarmCellDM, PetscInt *, const char **[]);
    223: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetCoordinateFields(DMSwarmCellDM, PetscInt *, const char **[]);
    224: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetCellID(DMSwarmCellDM, const char *[]);
    225: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetSort(DMSwarmCellDM, DMSwarmSort *);
    226: PETSC_EXTERN PetscErrorCode DMSwarmCellDMSetSort(DMSwarmCellDM, DMSwarmSort);
    227: PETSC_EXTERN PetscErrorCode DMSwarmCellDMGetBlockSize(DMSwarmCellDM, DM, PetscInt *);