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:
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

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.

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

Return type:

None

collectViewDestroy()

Reset the DMSwarm to the size prior to calling collectViewCreate.

Collective.

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

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

Parameters:
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

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

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

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

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

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

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

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

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

finalizeFieldRegister()

Finalize the registration of fields to a DMSwarm.

Collective.

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

Return type:

None

getCellDM()

Return DM cell attached to DMSwarm.

Collective.

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

Return type:

DM

getCellDMActive()

Return the active cell DM in the DMSwarm.

Not collective.

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.

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.

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

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

getLocalSize()

Return the local length of fields registered.

Not collective.

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.

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

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:
Return type:

None

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 (dtype) – A valid PETSc data type.

Return type:

None

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

removePoint()

Remove the last point from the DMSwarm.

Not collective.

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

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

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

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

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

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

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

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

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.

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.

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

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]

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]

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

sortRestoreAccess()

Invalidate the DMSwarm point sorting context.

Not collective.

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

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

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