Actual source code: petscdmswarm.h

      1: #pragma once

      3: #include <petscdm.h>
      4: #include <petscdt.h>

      6: typedef struct _p_DMSwarmDataField  *DMSwarmDataField;
      7: typedef struct _p_DMSwarmDataBucket *DMSwarmDataBucket;
      8: typedef struct _p_DMSwarmSort       *DMSwarmSort;

     10: /* SUBMANSEC = DMSwarm */

     12: /*E
     13:    DMSwarmType - Defines the type of `DMSWARM`

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

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

     23:    Level: beginner

     25: .seealso: [](ch_dmbase), `DMSWARM`, `DMSwarmSetType()`
     26: E*/
     27: typedef enum {
     28:   DMSWARM_BASIC = 0,
     29:   DMSWARM_PIC
     30: } DMSwarmType;

     32: typedef enum {
     33:   DMSWARM_MIGRATE_BASIC = 0,
     34:   DMSWARM_MIGRATE_DMCELLNSCATTER,
     35:   DMSWARM_MIGRATE_DMCELLEXACT,
     36:   DMSWARM_MIGRATE_USER
     37: } DMSwarmMigrateType;

     39: typedef enum {
     40:   DMSWARM_COLLECT_BASIC = 0,
     41:   DMSWARM_COLLECT_DMDABOUNDINGBOX,
     42:   DMSWARM_COLLECT_GENERAL,
     43:   DMSWARM_COLLECT_USER
     44: } DMSwarmCollectType;

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

     49:    Values:
     50: +  `DMSWARMPIC_LAYOUT_REGULAR`     - defines points on a regular ijk mesh. In this case
     51:                                      the `fill_param` argument of `DMSwarmInsertPointsUsingCellDM()` defines the number of points in each spatial direction.
     52: .  `DMSWARMPIC_LAYOUT_GAUSS`       - defines points using an npoint Gauss-Legendre tensor product quadrature rule. In this case
     53:                                      the `fill_param` argument of `DMSwarmInsertPointsUsingCellDM()` defines the number of quadrature points in each spatial direction.
     54: -  `DMSWARMPIC_LAYOUT_SUBDIVISION` - defines points on the centroid of a sub-divided reference cell. In this case
     55:                                      the `fill_param` argument of `DMSwarmInsertPointsUsingCellDM()` defines the number times the reference cell is sub-divided.

     57:    Level: beginner

     59: .seealso: [](ch_dmbase), `DMSWARM`, `DM`, `DMSwarmInsertPointsUsingCellDM()`
     60: E*/
     61: typedef enum {
     62:   DMSWARMPIC_LAYOUT_REGULAR = 0,
     63:   DMSWARMPIC_LAYOUT_GAUSS,
     64:   DMSWARMPIC_LAYOUT_SUBDIVISION
     65: } DMSwarmPICLayoutType;

     67: PETSC_EXTERN const char *DMSwarmTypeNames[];
     68: PETSC_EXTERN const char *DMSwarmMigrateTypeNames[];
     69: PETSC_EXTERN const char *DMSwarmCollectTypeNames[];

     71: PETSC_EXTERN const char DMSwarmField_pid[];
     72: PETSC_EXTERN const char DMSwarmField_rank[];
     73: PETSC_EXTERN const char DMSwarmPICField_coor[];
     74: PETSC_EXTERN const char DMSwarmPICField_cellid[];

     76: PETSC_EXTERN PetscErrorCode DMSwarmCreateGlobalVectorFromField(DM, const char[], Vec *);
     77: PETSC_EXTERN PetscErrorCode DMSwarmDestroyGlobalVectorFromField(DM, const char[], Vec *);
     78: PETSC_EXTERN PetscErrorCode DMSwarmCreateLocalVectorFromField(DM, const char[], Vec *);
     79: PETSC_EXTERN PetscErrorCode DMSwarmDestroyLocalVectorFromField(DM, const char[], Vec *);

     81: PETSC_EXTERN PetscErrorCode DMSwarmInitializeFieldRegister(DM);
     82: PETSC_EXTERN PetscErrorCode DMSwarmFinalizeFieldRegister(DM);
     83: PETSC_EXTERN PetscErrorCode DMSwarmSetLocalSizes(DM, PetscInt, PetscInt);
     84: PETSC_EXTERN PetscErrorCode DMSwarmRegisterPetscDatatypeField(DM, const char[], PetscInt, PetscDataType);
     85: PETSC_EXTERN PetscErrorCode DMSwarmRegisterUserStructField(DM, const char[], size_t);
     86: PETSC_EXTERN PetscErrorCode DMSwarmRegisterUserDatatypeField(DM, const char[], size_t, PetscInt);
     87: PETSC_EXTERN PetscErrorCode DMSwarmGetField(DM, const char[], PetscInt *, PetscDataType *, void **);
     88: PETSC_EXTERN PetscErrorCode DMSwarmRestoreField(DM, const char[], PetscInt *, PetscDataType *, void **);
     89: PETSC_EXTERN PetscErrorCode DMSwarmGetFieldInfo(DM, const char[], PetscInt *, PetscDataType *);

     91: PETSC_EXTERN PetscErrorCode DMSwarmVectorDefineField(DM, const char[]);
     92: PETSC_EXTERN PetscErrorCode DMSwarmVectorGetField(DM, const char *[]);

     94: PETSC_EXTERN PetscErrorCode DMSwarmAddPoint(DM);
     95: PETSC_EXTERN PetscErrorCode DMSwarmAddNPoints(DM, PetscInt);
     96: PETSC_EXTERN PetscErrorCode DMSwarmRemovePoint(DM);
     97: PETSC_EXTERN PetscErrorCode DMSwarmRemovePointAtIndex(DM, PetscInt);
     98: PETSC_EXTERN PetscErrorCode DMSwarmCopyPoint(DM dm, PetscInt, PetscInt);

    100: PETSC_EXTERN PetscErrorCode DMSwarmGetLocalSize(DM, PetscInt *);
    101: PETSC_EXTERN PetscErrorCode DMSwarmGetSize(DM, PetscInt *);
    102: PETSC_EXTERN PetscErrorCode DMSwarmGetMigrateType(DM, DMSwarmMigrateType *);
    103: PETSC_EXTERN PetscErrorCode DMSwarmSetMigrateType(DM, DMSwarmMigrateType);
    104: PETSC_EXTERN PetscErrorCode DMSwarmMigrate(DM, PetscBool);

    106: PETSC_EXTERN PetscErrorCode DMSwarmCollectViewCreate(DM);
    107: PETSC_EXTERN PetscErrorCode DMSwarmCollectViewDestroy(DM);
    108: PETSC_EXTERN PetscErrorCode DMSwarmSetCellDM(DM, DM);
    109: PETSC_EXTERN PetscErrorCode DMSwarmGetCellDM(DM, DM *);

    111: PETSC_EXTERN PetscErrorCode DMSwarmSetType(DM, DMSwarmType);

    113: PETSC_EXTERN PetscErrorCode DMSwarmSetPointsUniformCoordinates(DM, PetscReal *, PetscReal *, PetscInt *, InsertMode);
    114: PETSC_EXTERN PetscErrorCode DMSwarmSetPointCoordinates(DM, PetscInt, PetscReal *, PetscBool, InsertMode);
    115: PETSC_EXTERN PetscErrorCode DMSwarmInsertPointsUsingCellDM(DM, DMSwarmPICLayoutType, PetscInt);
    116: PETSC_EXTERN PetscErrorCode DMSwarmSetPointCoordinatesCellwise(DM, PetscInt, PetscReal *);
    117: PETSC_EXTERN PetscErrorCode DMSwarmSetPointCoordinatesRandom(DM, PetscInt);
    118: PETSC_EXTERN PetscErrorCode DMSwarmViewFieldsXDMF(DM, const char *, PetscInt, const char **);
    119: PETSC_EXTERN PetscErrorCode DMSwarmViewXDMF(DM, const char *);

    121: PETSC_EXTERN PetscErrorCode DMSwarmSortGetAccess(DM);
    122: PETSC_EXTERN PetscErrorCode DMSwarmSortRestoreAccess(DM);
    123: PETSC_EXTERN PetscErrorCode DMSwarmSortGetPointsPerCell(DM, PetscInt, PetscInt *, PetscInt **);
    124: PETSC_EXTERN PetscErrorCode DMSwarmSortGetNumberOfPointsPerCell(DM, PetscInt, PetscInt *);
    125: PETSC_EXTERN PetscErrorCode DMSwarmSortGetIsValid(DM, PetscBool *);
    126: PETSC_EXTERN PetscErrorCode DMSwarmSortGetSizes(DM, PetscInt *, PetscInt *);

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

    130: PETSC_EXTERN PetscErrorCode DMSwarmGetCellSwarm(DM, PetscInt, DM);
    131: PETSC_EXTERN PetscErrorCode DMSwarmRestoreCellSwarm(DM, PetscInt, DM);
    132: PETSC_EXTERN PetscErrorCode DMSwarmGetNumSpecies(DM, PetscInt *);
    133: PETSC_EXTERN PetscErrorCode DMSwarmSetNumSpecies(DM, PetscInt);
    134: PETSC_EXTERN PetscErrorCode DMSwarmGetCoordinateFunction(DM, PetscErrorCode (**)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
    135: PETSC_EXTERN PetscErrorCode DMSwarmSetCoordinateFunction(DM, PetscErrorCode (*)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
    136: PETSC_EXTERN PetscErrorCode DMSwarmGetVelocityFunction(DM, PetscErrorCode (**)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
    137: PETSC_EXTERN PetscErrorCode DMSwarmSetVelocityFunction(DM, PetscErrorCode (*)(PetscInt, PetscReal, const PetscReal[], PetscInt, PetscScalar[], void *));
    138: PETSC_EXTERN PetscErrorCode DMSwarmComputeLocalSize(DM, PetscInt, PetscProbFunc);
    139: PETSC_EXTERN PetscErrorCode DMSwarmComputeLocalSizeFromOptions(DM);
    140: PETSC_EXTERN PetscErrorCode DMSwarmInitializeCoordinates(DM);
    141: PETSC_EXTERN PetscErrorCode DMSwarmInitializeVelocities(DM, PetscProbFunc, const PetscReal[]);
    142: PETSC_EXTERN PetscErrorCode DMSwarmInitializeVelocitiesFromOptions(DM, const PetscReal[]);

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

    146: // Interface to internal storage
    147: PETSC_EXTERN PetscErrorCode DMSwarmDataFieldGetEntries(const DMSwarmDataField, void **);
    148: PETSC_EXTERN PetscErrorCode DMSwarmDataFieldRestoreEntries(const DMSwarmDataField, void **);
    149: PETSC_EXTERN PetscErrorCode DMSwarmDataBucketGetDMSwarmDataFieldByName(DMSwarmDataBucket, const char[], DMSwarmDataField *);
    150: PETSC_EXTERN PetscErrorCode DMSwarmDataBucketGetDMSwarmDataFieldIdByName(DMSwarmDataBucket, const char[], PetscInt *);
    151: PETSC_EXTERN PetscErrorCode DMSwarmDataBucketQueryDMSwarmDataFieldByName(DMSwarmDataBucket, const char[], PetscBool *);