Skip to main content
`Ctrl`+`K`

# petsc4py.PETSc.DMSwarm

class petsc4py.PETSc.DMSwarm

  Bases: `DM`

  A `DM` object used to represent arrays of data (fields) of arbitrary type.

  Enumerations

  `CollectType` | Swarm collection types.
  `MigrateType` | Swarm migration types.
  `PICLayoutType` | Swarm PIC layout types.
  `Type` | Swarm types.

  Methods Summary

  `addCellDM`(celldm) | Add a cell DM to the `DMSwarm`.
  `addNPoints`(npoints) | Add space for a number of new points in the `DMSwarm`.
  `addPoint`() | Add space for one new point in the `DMSwarm`.
  `collectViewCreate`() | Apply a collection method and gather points in neighbor ranks.
  `collectViewDestroy`() | Reset the `DMSwarm` to the size prior to calling `collectViewCreate`.
  `computeMoments`(coord, weight) | Return the moments defined in the active cell DM.
  `copyPoint`(pi, pj) | Copy point pi to point pj in the `DMSwarm`.
  `create`([comm]) | Create an empty DM object and set its type to `DM.Type.SWARM`.
  `createGlobalVectorFromField`(fieldname) | Create a global `Vec` object associated with a given field.
  `createGlobalVectorFromFields`(fieldnames) | Create a global `Vec` object associated with a given set of fields.
  `createLocalVectorFromField`(fieldname) | Create a local `Vec` object associated with a given field.
  `createLocalVectorFromFields`(fieldnames) | Create a local `Vec` object associated with a given set of fields.
  `destroyGlobalVectorFromField`(fieldname) | Destroy the global `Vec` object associated with a given field.
  `destroyGlobalVectorFromFields`(fieldnames) | Destroy the global `Vec` object associated with a given set of fields.
  `destroyLocalVectorFromField`(fieldname) | Destroy the local `Vec` object associated with a given field.
  `destroyLocalVectorFromFields`(fieldnames) | Destroy the local `Vec` object associated with a given set of fields.
  `finalizeFieldRegister`() | Finalize the registration of fields to a `DMSwarm`.
  `getCellDM`() | Return `DM` cell attached to `DMSwarm`.
  `getCellDMActive`() | Return the active cell DM in the `DMSwarm`.
  `getCellDMByName`(name) | Return the cell DM with the given name in the `DMSwarm`.
  `getCellDMNames`() | Return the names of all cell DMs in the `DMSwarm`.
  `getField`(fieldname) | Return arrays storing all entries associated with a field.
  `getLocalSize`() | Return the local length of fields registered.
  `getSize`() | Return the total length of fields registered.
  `initializeFieldRegister`() | Initiate the registration of fields to a `DMSwarm`.
  `insertPointUsingCellDM`(layoutType, fill_param) | Insert point coordinates within each cell.
  `migrate`([remove_sent_points]) | Relocate points defined in the `DMSwarm` to other MPI ranks.
  `projectFields`(dm, fieldnames, vecs[, mode]) | Project a set of `DMSwarm` fields onto the cell `DM`.
  `registerField`(fieldname, blocksize[, dtype]) | Register a field to a `DMSwarm` with a native PETSc data type.
  `removePoint`() | Remove the last point from the `DMSwarm`.
  `removePointAtIndex`(index) | Remove a specific point from the `DMSwarm`.
  `restoreField`(fieldname) | Restore accesses associated with a registered field.
  `setCellDM`(dm) | Attach a `DM` to a `DMSwarm`.
  `setCellDMActive`(name) | Activate a cell DM in the `DMSwarm`.
  `setLocalSizes`(nlocal, buffer) | Set the length of all registered fields on the `DMSwarm`.
  `setPointCoordinates`(coordinates[, ...]) | Set point coordinates in a `DMSwarm` from a user-defined list.
  `setPointCoordinatesCellwise`(coordinates) | Insert point coordinates within each cell.
  `setPointsUniformCoordinates`(min, max, npoints) | Set point coordinates in a `DMSwarm` on a regular (ijk) grid.
  `setType`(dmswarm_type) | Set particular flavor of `DMSwarm`.
  `sortGetAccess`() | Setup up a `DMSwarm` point sort context.
  `sortGetIsValid`() | Return whether the sort context is up-to-date.
  `sortGetNumberOfPointsPerCell`(e) | Return the number of points in a cell.
  `sortGetPointsPerCell`(e) | Create an array of point indices for all points in a cell.
  `sortGetSizes`() | Return the sizes associated with a `DMSwarm` point sorting context.
  `sortRestoreAccess`() | Invalidate the `DMSwarm` point sorting context.
  `vectorDefineField`(fieldname) | Set the fields from which to define a `Vec` object.
  `viewFieldsXDMF`(filename, fieldnames) | Write a selection of `DMSwarm` fields to an XDMF3 file.
  `viewXDMF`(filename) | Write this `DMSwarm` fields to an XDMF3 file.

  Methods Documentation

  addCellDM(celldm)

    Add a cell DM to the `DMSwarm`.

    Logically collective.

    Parameters:

      - cellDM (`CellDM`) – The cell DM object

      - celldm (CellDM)

    Return type:

      None

    See also

    `DMSwarmAddCellDM`

    Source code at petsc4py/PETSc/DMSwarm.pyx:956

  addNPoints(npoints)

    Add space for a number of new points in the `DMSwarm`.

    Not collective.

    Parameters:

      npoints (int) – The number of new points to add.

    Return type:

      None

    See also

    `DMSwarmAddNPoints`

    Source code at petsc4py/PETSc/DMSwarm.pyx:443

  addPoint()

    Add space for one new point in the `DMSwarm`.

    Not collective.

    See also

    `DMSwarmAddPoint`

    Source code at petsc4py/PETSc/DMSwarm.pyx:431

    Return type:

      None

  collectViewCreate()

    Apply a collection method and gather points in neighbor ranks.

    Collective.

    See also

    `collectViewDestroy`, `DMSwarmCollectViewCreate`

    Source code at petsc4py/PETSc/DMSwarm.pyx:559

    Return type:

      None

  collectViewDestroy()

    Reset the `DMSwarm` to the size prior to calling `collectViewCreate`.

    Collective.

    See also

    `collectViewCreate`, `DMSwarmCollectViewDestroy`

    Source code at petsc4py/PETSc/DMSwarm.pyx:571

    Return type:

      None

  computeMoments(coord, weight)

    Return the moments defined in the active cell DM.

    Collective.

    Notes

    We integrate the given weight field over the given coordinate

    See also

    `DMSwarmComputeMoments`

    Source code at petsc4py/PETSc/DMSwarm.pyx:1046

    Parameters:

      - coord (str)

      - weight (str)

    Return type:

      list[float]

  copyPoint(pi, pj)

    Copy point pi to point pj in the `DMSwarm`.

    Not collective.

    Parameters:

      - pi (int) – The index of the point to copy (source).

      - pj (int) – The point index where the copy should be located (destination).

    Return type:

      None

    See also

    `DMSwarmCopyPoint`

    Source code at petsc4py/PETSc/DMSwarm.pyx:491

  create(comm=None)

    Create an empty DM object and set its type to `DM.Type.SWARM`.

    Collective.

    DMs are the abstract objects in PETSc that mediate between meshes and discretizations and the algebraic solvers, time integrators, and optimization algorithms.

    Parameters:

      comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    See also

    `DMCreate`, `DMSetType`

    Source code at petsc4py/PETSc/DMSwarm.pyx:39

  createGlobalVectorFromField(fieldname)

    Create a global `Vec` object associated with a given field.

    Collective.

    The vector must be returned to the `DMSwarm` using a matching call to `destroyGlobalVectorFromField`.

    Parameters:

      fieldname (str) – The textual name given to a registered field.

    Return type:

      Vec

    See also

    `destroyGlobalVectorFromField`, `DMSwarmCreateGlobalVectorFromField`

    Source code at petsc4py/PETSc/DMSwarm.pyx:65

  createGlobalVectorFromFields(fieldnames)

    Create a global `Vec` object associated with a given set of fields.

    Collective.

    The vector must be returned to the `DMSwarm` using a matching call to `destroyGlobalVectorFromFields`.

    Parameters:

      fieldnames (Sequence[str]) – The textual name given to each registered field.

    Return type:

      Vec

    See also

    `destroyGlobalVectorFromFields`, `DMSwarmCreateGlobalVectorFromFields`

    Source code at petsc4py/PETSc/DMSwarm.pyx:109

  createLocalVectorFromField(fieldname)

    Create a local `Vec` object associated with a given field.

    Collective.

    The vector must be returned to the `DMSwarm` using a matching call to `destroyLocalVectorFromField`.

    Parameters:

      fieldname (str) – The textual name given to a registered field.

    Return type:

      Vec

    See also

    `destroyLocalVectorFromField`, `DMSwarmCreateLocalVectorFromField`

    Source code at petsc4py/PETSc/DMSwarm.pyx:165

  createLocalVectorFromFields(fieldnames)

    Create a local `Vec` object associated with a given set of fields.

    Collective.

    The vector must be returned to the `DMSwarm` using a matching call to `destroyLocalVectorFromFields`.

    Parameters:

      fieldnames (Sequence[str]) – The textual name given to each registered field.

    Return type:

      Vec

    See also

    `destroyLocalVectorFromFields`, `DMSwarmCreateLocalVectorFromFields`

    Source code at petsc4py/PETSc/DMSwarm.pyx:209

  destroyGlobalVectorFromField(fieldname)

    Destroy the global `Vec` object associated with a given field.

    Collective.

    Parameters:

      fieldname (str) – The textual name given to a registered field.

    Return type:

      None

    See also

    `createGlobalVectorFromField`, `DMSwarmDestroyGlobalVectorFromField`

    Source code at petsc4py/PETSc/DMSwarm.pyx:89

  destroyGlobalVectorFromFields(fieldnames)

    Destroy the global `Vec` object associated with a given set of fields.

    Collective.

    Parameters:

      fieldnames (Sequence[str]) – The textual name given to each registered field.

    Return type:

      None

    See also

    `createGlobalVectorFromFields`, `DMSwarmDestroyGlobalVectorFromFields`

    Source code at petsc4py/PETSc/DMSwarm.pyx:139

  destroyLocalVectorFromField(fieldname)

    Destroy the local `Vec` object associated with a given field.

    Collective.

    Parameters:

      fieldname (str) – The textual name given to a registered field.

    Return type:

      None

    See also

    `createLocalVectorFromField`, `DMSwarmDestroyLocalVectorFromField`

    Source code at petsc4py/PETSc/DMSwarm.pyx:189

  destroyLocalVectorFromFields(fieldnames)

    Destroy the local `Vec` object associated with a given set of fields.

    Collective.

    Parameters:

      fieldnames (Sequence[str]) – The textual name given to each registered field.

    Return type:

      None

    See also

    `createLocalVectorFromFields`, `DMSwarmDestroyLocalVectorFromFields`

    Source code at petsc4py/PETSc/DMSwarm.pyx:239

  finalizeFieldRegister()

    Finalize the registration of fields to a `DMSwarm`.

    Collective.

    See also

    `initializeFieldRegister`, `DMSwarmFinalizeFieldRegister`

    Source code at petsc4py/PETSc/DMSwarm.pyx:279

    Return type:

      None

  getCellDM()

    Return `DM` cell attached to `DMSwarm`.

    Collective.

    See also

    `setCellDM`, `DMSwarmGetCellDM`

    Source code at petsc4py/PETSc/DMSwarm.pyx:600

    Return type:

      DM

  getCellDMActive()

    Return the active cell DM in the `DMSwarm`.

    Not collective.

    See also

    `DMSwarmGetCellDMActive`

    Source code at petsc4py/PETSc/DMSwarm.pyx:992

    Return type:

      CellDM

  getCellDMByName(name)

    Return the cell DM with the given name in the `DMSwarm`.

    Not collective.

    See also

    `DMSwarmGetCellDMByName`

    Source code at petsc4py/PETSc/DMSwarm.pyx:1009

    Parameters:

      name (str)

    Return type:

      CellDM

  getCellDMNames()

    Return the names of all cell DMs in the `DMSwarm`.

    Not collective.

    See also

    `DMSwarmGetCellDMNames`

    Source code at petsc4py/PETSc/DMSwarm.pyx:1028

    Return type:

      list[str]

  getField(fieldname)

    Return arrays storing all entries associated with a field.

    Not collective.

    The returned array contains underlying values of the field.

    The array must be returned to the `DMSwarm` using a matching call to `restoreField`.

    Parameters:

      fieldname (str) – The textual name to identify this field.

    Returns:

      The type of the entries in the array will match the type of the field. The array is two dimensional with shape `(num_points, blocksize)`.

    Return type:

      `numpy.ndarray`

    See also

    `restoreField`, `DMSwarmGetField`

    Source code at petsc4py/PETSc/DMSwarm.pyx:343

  getLocalSize()

    Return the local length of fields registered.

    Not collective.

    See also

    `DMSwarmGetLocalSize`

    Source code at petsc4py/PETSc/DMSwarm.pyx:512

    Return type:

      int

  getSize()

    Return the total length of fields registered.

    Collective.

    See also

    `DMSwarmGetSize`

    Source code at petsc4py/PETSc/DMSwarm.pyx:526

    Return type:

      int

  initializeFieldRegister()

    Initiate the registration of fields to a `DMSwarm`.

    Collective.

    After all fields have been registered, you must call `finalizeFieldRegister`.

    See also

    `finalizeFieldRegister`, `DMSwarmInitializeFieldRegister`

    Source code at petsc4py/PETSc/DMSwarm.pyx:265

    Return type:

      None

  insertPointUsingCellDM(layoutType, fill_param)

    Insert point coordinates within each cell.

    Not collective.

    Parameters:

      - layout_type – Method used to fill each cell with the cell DM.

      - fill_param (int) – Parameter controlling how many points per cell are added (the meaning of this parameter is dependent on the layout type).

      - layoutType (PICLayoutType)

    Return type:

      None

    See also

    `DMSwarmInsertPointsUsingCellDM`

    Source code at petsc4py/PETSc/DMSwarm.pyx:715

  migrate(remove_sent_points=False)

    Relocate points defined in the `DMSwarm` to other MPI ranks.

    Collective.

    Parameters:

      remove_sent_points (bool) – Flag indicating if sent points should be removed from the current MPI rank.

    Return type:

      None

    See also

    `DMSwarmMigrate`

    Source code at petsc4py/PETSc/DMSwarm.pyx:540

  projectFields(dm, fieldnames, vecs, mode=None)

    Project a set of `DMSwarm` fields onto the cell `DM`.

    Collective.

    Parameters:

      - dm (DM) – The continuum `DM`.

      - fieldnames (Sequence[str]) – The textual names of the swarm fields to project.

      - vecs (Sequence[Vec])

      - mode (ScatterModeSpec)

    Return type:

      None

    See also

    `DMSwarmProjectFields`

    Source code at petsc4py/PETSc/DMSwarm.pyx:924

  registerField(fieldname, blocksize, dtype=ScalarType)

    Register a field to a `DMSwarm` with a native PETSc data type.

    Collective.

    Parameters:

      - fieldname (str) – The textual name to identify this field.

      - blocksize (int) – The number of each data type.

      - dtype (type | dtype) – A valid PETSc data type.

    Return type:

      None

    See also

    `DMSwarmRegisterPetscDatatypeField`

    Source code at petsc4py/PETSc/DMSwarm.pyx:313

  removePoint()

    Remove the last point from the `DMSwarm`.

    Not collective.

    See also

    `DMSwarmRemovePoint`

    Source code at petsc4py/PETSc/DMSwarm.pyx:461

    Return type:

      None

  removePointAtIndex(index)

    Remove a specific point from the `DMSwarm`.

    Not collective.

    Parameters:

      index (int) – Index of point to remove

    Return type:

      None

    See also

    `DMSwarmRemovePointAtIndex`

    Source code at petsc4py/PETSc/DMSwarm.pyx:473

  restoreField(fieldname)

    Restore accesses associated with a registered field.

    Not collective.

    Parameters:

      fieldname (str) – The textual name to identify this field.

    Return type:

      None

    See also

    `getField`, `DMSwarmRestoreField`

    Source code at petsc4py/PETSc/DMSwarm.pyx:388

  setCellDM(dm)

    Attach a `DM` to a `DMSwarm`.

    Collective.

    Parameters:

      dm (DM) – The `DM` to attach to the `DMSwarm`.

    Return type:

      None

    See also

    `getCellDM`, `DMSwarmSetCellDM`

    Source code at petsc4py/PETSc/DMSwarm.pyx:583

  setCellDMActive(name)

    Activate a cell DM in the `DMSwarm`.

    Logically collective.

    Parameters:

      name (`str`) – The name of the cell DM to activate

    Return type:

      None

    See also

    `DMSwarmSetCellDMActive`

    Source code at petsc4py/PETSc/DMSwarm.pyx:973

  setLocalSizes(nlocal, buffer)

    Set the length of all registered fields on the `DMSwarm`.

    Not collective.

    Parameters:

      - nlocal (int) – The length of each registered field.

      - buffer (int) – The length of the buffer used for efficient dynamic resizing.

    Return type:

      Self

    See also

    `DMSwarmSetLocalSizes`

    Source code at petsc4py/PETSc/DMSwarm.pyx:291

  setPointCoordinates(coordinates, redundant=False, mode=None)

    Set point coordinates in a `DMSwarm` from a user-defined list.

    Collective.

    Parameters:

      - coordinates (Sequence[float]) – The coordinate values.

      - redundant (bool) – If set to `True`, it is assumed that coordinates are only valid on rank 0 and should be broadcast to other ranks.

      - mode (InsertMode | None) – Indicates whether to append points to the swarm (`InsertMode.ADD`), or override existing points (`InsertMode.INSERT`).

    Return type:

      None

    See also

    `DMSwarmSetPointCoordinates`

    Source code at petsc4py/PETSc/DMSwarm.pyx:679

  setPointCoordinatesCellwise(coordinates)

    Insert point coordinates within each cell.

    Not collective.

    Point coordinates are defined over the reference cell.

    Parameters:

      coordinates (Sequence[float]) – The coordinates (defined in the local coordinate system for each cell) to insert.

    Return type:

      None

    See also

    `DMSwarmSetPointCoordinatesCellwise`

    Source code at petsc4py/PETSc/DMSwarm.pyx:737

  setPointsUniformCoordinates(min, max, npoints, mode=None)

    Set point coordinates in a `DMSwarm` on a regular (ijk) grid.

    Collective.

    Parameters:

      - min (Sequence[float]) – Minimum coordinate values in the x, y, z directions (array of length `dim`).

      - max (Sequence[float]) – Maximum coordinate values in the x, y, z directions (array of length `dim`).

      - npoints (Sequence[int]) – Number of points in each spatial direction (array of length `dim`).

      - mode (InsertMode | None) – Indicates whether to append points to the swarm (`InsertMode.ADD`), or override existing points (`InsertMode.INSERT`).

    Return type:

      Self

    See also

    `DMSwarmSetPointsUniformCoordinates`

    Source code at petsc4py/PETSc/DMSwarm.pyx:635

  setType(dmswarm_type)

    Set particular flavor of `DMSwarm`.

    Collective.

    Parameters:

      dmswarm_type (Type | str) – The `DMSwarm` type.

    Return type:

      None

    See also

    `DMSwarmSetType`

    Source code at petsc4py/PETSc/DMSwarm.pyx:617

  sortGetAccess()

    Setup up a `DMSwarm` point sort context.

    Not collective.

    The point sort context is used for efficient traversal of points within a cell.

    You must call `sortRestoreAccess` when you no longer need access to the sort context.

    See also

    `sortRestoreAccess`, `DMSwarmSortGetAccess`

    Source code at petsc4py/PETSc/DMSwarm.pyx:812

    Return type:

      None

  sortGetIsValid()

    Return whether the sort context is up-to-date.

    Not collective.

    Returns the flag associated with a `DMSwarm` point sorting context.

    See also

    `DMSwarmSortGetIsValid`

    Source code at petsc4py/PETSc/DMSwarm.pyx:886

    Return type:

      bool

  sortGetNumberOfPointsPerCell(e)

    Return the number of points in a cell.

    Not collective.

    Parameters:

      e (int) – The index of the cell.

    Return type:

      int

    See also

    `DMSwarmSortGetNumberOfPointsPerCell`

    Source code at petsc4py/PETSc/DMSwarm.pyx:866

  sortGetPointsPerCell(e)

    Create an array of point indices for all points in a cell.

    Not collective.

    Parameters:

      e (int) – The index of the cell.

    Return type:

      list[int]

    See also

    `DMSwarmSortGetPointsPerCell`

    Source code at petsc4py/PETSc/DMSwarm.pyx:842

  sortGetSizes()

    Return the sizes associated with a `DMSwarm` point sorting context.

    Not collective.

    Returns:

      - ncells (`int`) – Number of cells within the sort context.

      - npoints (`int`) – Number of points used to create the sort context.

    Return type:

      tuple[int, int]

    See also

    `DMSwarmSortGetSizes`

    Source code at petsc4py/PETSc/DMSwarm.pyx:902

  sortRestoreAccess()

    Invalidate the `DMSwarm` point sorting context.

    Not collective.

    See also

    `sortGetAccess`, `DMSwarmSortRestoreAccess`

    Source code at petsc4py/PETSc/DMSwarm.pyx:830

    Return type:

      None

  vectorDefineField(fieldname)

    Set the fields from which to define a `Vec` object.

    Collective.

    The field will be used when `DM.createLocalVec`, or `DM.createGlobalVec` is called.

    Parameters:

      fieldname (str) – The textual names given to a registered field.

    Return type:

      None

    See also

    `DMSwarmVectorDefineField`

    Source code at petsc4py/PETSc/DMSwarm.pyx:409

  viewFieldsXDMF(filename, fieldnames)

    Write a selection of `DMSwarm` fields to an XDMF3 file.

    Collective.

    Parameters:

      - filename (str) – The file name of the XDMF file (must have the extension .xmf).

      - fieldnames (Sequence[str]) – Array containing the textual names of fields to write.

    Return type:

      None

    See also

    `DMSwarmViewFieldsXDMF`

    Source code at petsc4py/PETSc/DMSwarm.pyx:764

  viewXDMF(filename)

    Write this `DMSwarm` fields to an XDMF3 file.

    Collective.

    Parameters:

      filename (str) – The file name of the XDMF file (must have the extension .xmf).

    Return type:

      None

    See also

    `DMSwarmViewXDMF`

    Source code at petsc4py/PETSc/DMSwarm.pyx:793

  __init__()
  classmethod __new__(*args, **kwargs)