petsc4py.PETSc.DMSwarm#

class petsc4py.PETSc.DMSwarm#

Bases: DM

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

Enumerations

CollectType

MigrateType

PICLayoutType

Type

Methods Summary

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.

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.

createLocalVectorFromField(fieldname)

Create a local Vec object associated with a given field.

destroyGlobalVectorFromField(fieldname)

Destroy the global Vec object associated with a given field.

destroyLocalVectorFromField(fieldname)

Destroy the local Vec object associated with a given field.

finalizeFieldRegister()

Finalize the registration of fields to a DMSwarm.

getCellDM()

Return DM cell attached to 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(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.

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

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

addPoint()#

Add space for one new point in the DMSwarm.

Not collective.

See also

DMSwarmAddPoint

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

Return type:

None

collectViewCreate()#

Apply a collection method and gather points in neighbor ranks.

Collective.

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

Return type:

None

collectViewDestroy()#

Reset the DMSwarm to the size prior to calling collectViewCreate.

Collective.

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

Return type:

None

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

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

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

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

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

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

finalizeFieldRegister()#

Finalize the registration of fields to a DMSwarm.

Collective.

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

Return type:

None

getCellDM()#

Return DM cell attached to DMSwarm.

Collective.

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

Return type:

DM

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.

Return type:

numpy.ndarray

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

getLocalSize()#

Return the local length of fields registered.

Not collective.

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

Return type:

int

getSize()#

Return the total length of fields registered.

Collective.

See also

DMSwarmGetSize

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

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

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

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

projectFields(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:805

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

removePoint()#

Remove the last point from the DMSwarm.

Not collective.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

sortRestoreAccess()#

Invalidate the DMSwarm point sorting context.

Not collective.

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

Return type:

None

vectorDefineField(fieldname)#

Set the field 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 name given to a registered field.

Return type:

None

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

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

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