petsc4py.PETSc.SF#

class petsc4py.PETSc.SF#

Bases: Object

Star Forest object for communication.

SF is used for setting up and managing the communication of certain entries of arrays and Vec between MPI processes.

Enumerations

Type

Methods Summary

bcastBegin(unit, rootdata, leafdata, op)

Begin pointwise broadcast.

bcastEnd(unit, rootdata, leafdata, op)

End a broadcast & reduce operation started with bcastBegin.

compose(sf)

Compose a new SF.

computeDegree()

Compute and return the degree of each root vertex.

create([comm])

Create a star forest communication context.

createEmbeddedLeafSF(selected)

Remove edges from all but the selected leaves.

createEmbeddedRootSF(selected)

Remove edges from all but the selected roots.

createInverse()

Create the inverse map.

createSectionSF(rootSection, remoteOffsets, ...)

Create an expanded SF of DOFs.

destroy()

Destroy the star forest.

distributeSection(rootSection[, leafSection])

Create a new, reorganized Section.

fetchAndOpBegin(unit, rootdata, leafdata, ...)

Begin fetch and update operation.

fetchAndOpEnd(unit, rootdata, leafdata, ...)

End operation started in a matching call to fetchAndOpBegin.

gatherBegin(unit, leafdata, multirootdata)

Begin pointwise gather of all leaves into multi-roots.

gatherEnd(unit, leafdata, multirootdata)

End gather operation that was started with gatherBegin.

getGraph()

Return star forest graph.

getMulti()

Return the inner SF implementing gathers and scatters.

getType()

Return the type name of the star forest.

reduceBegin(unit, leafdata, rootdata, op)

Begin reduction of leafdata into rootdata.

reduceEnd(unit, leafdata, rootdata, op)

End a reduction operation started with reduceBegin.

reset()

Reset a star forest so that different sizes or neighbors can be used.

scatterBegin(unit, multirootdata, leafdata)

Begin pointwise scatter operation.

scatterEnd(unit, multirootdata, leafdata)

End scatter operation that was started with scatterBegin.

setFromOptions()

Set options using the options database.

setGraph(nroots, local, remote)

Set star forest graph.

setRankOrder(flag)

Sort multi-points for gathers and scatters by rank order.

setType(sf_type)

Set the type of the star forest.

setUp()

Set up communication structures.

view([viewer])

View a star forest.

Methods Documentation

bcastBegin(unit, rootdata, leafdata, op)#

Begin pointwise broadcast.

Collective.

Root values are reduced to leaf values. This call has to be concluded with a call to bcastEnd.

Parameters:
  • unit (Datatype) – MPI datatype.

  • rootdata (ndarray) – Buffer to broadcast.

  • leafdata (ndarray) – Buffer to be reduced with values from each leaf’s respective root.

  • op (Op) – MPI reduction operation.

Return type:

None

Source code at petsc4py/PETSc/SF.pyx:436

bcastEnd(unit, rootdata, leafdata, op)#

End a broadcast & reduce operation started with bcastBegin.

Collective.

Parameters:
  • unit (Datatype) – MPI datatype.

  • rootdata (ndarray) – Buffer to broadcast.

  • leafdata (ndarray) – Buffer to be reduced with values from each leaf’s respective root.

  • op (Op) – MPI reduction operation.

Return type:

None

Source code at petsc4py/PETSc/SF.pyx:465

compose(sf)#

Compose a new SF.

Collective.

Puts the sf under this object in a top (roots) down (leaves) view.

Parameters:

sf (SF) – SF to put under this object.

Return type:

SF

See also

PetscSFCompose

Source code at petsc4py/PETSc/SF.pyx:415

computeDegree()#

Compute and return the degree of each root vertex.

Collective.

Source code at petsc4py/PETSc/SF.pyx:281

Return type:

ArrayInt

create(comm=None)#

Create a star forest communication context.

Collective.

Parameters:

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

Return type:

Self

See also

PetscSFCreate

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

createEmbeddedLeafSF(selected)#

Remove edges from all but the selected leaves.

Collective.

Does not remap indices.

Parameters:

selected (Sequence[int]) – Indices of the selected roots on this process.

Return type:

SF

Source code at petsc4py/PETSc/SF.pyx:323

createEmbeddedRootSF(selected)#

Remove edges from all but the selected roots.

Collective.

Does not remap indices.

Parameters:

selected (Sequence[int]) – Indices of the selected roots on this process.

Return type:

SF

Source code at petsc4py/PETSc/SF.pyx:299

createInverse()#

Create the inverse map.

Collective.

Create the inverse map given a PetscSF in which all vertices have degree 1.

Source code at petsc4py/PETSc/SF.pyx:264

Return type:

SF

createSectionSF(rootSection, remoteOffsets, leafSection)#

Create an expanded SF of DOFs.

Collective.

Assumes the input SF relates points.

Parameters:
  • rootSection (Section) – Data layout of remote points for outgoing data (this is usually the serial section).

  • remoteOffsets (Sequence[int] | None) – Offsets for point data on remote processes (these are offsets from the root section), or None.

  • leafSection (Section) – Data layout of local points for incoming data (this is the distributed section).

Return type:

SF

Source code at petsc4py/PETSc/SF.pyx:347

destroy()#

Destroy the star forest.

Collective.

See also

PetscSFDestroy

Source code at petsc4py/PETSc/SF.pyx:52

Return type:

Self

distributeSection(rootSection, leafSection=None)#

Create a new, reorganized Section.

Collective.

Moves from the root to the leaves of the SF.

Parameters:
  • rootSection (Section) – Section defined on root space.

  • leafSection (Section | None) – Section defined on the leaf space.

Return type:

tuple[ArrayInt, Section]

Source code at petsc4py/PETSc/SF.pyx:380

fetchAndOpBegin(unit, rootdata, leafdata, leafupdate, op)#

Begin fetch and update operation.

Collective.

This operation fetches values from root and updates atomically by applying an operation using the leaf value.

This call has to be completed with fetchAndOpEnd.

Parameters:
  • unit (Datatype) – MPI datatype.

  • rootdata (ndarray) – Root values to be updated, input state is seen by first process to perform an update.

  • leafdata (ndarray) – Leaf values to use in reduction.

  • leafupdate (ndarray) – State at each leaf’s respective root immediately prior to my atomic update.

  • op (Op) – MPI reduction operation.

Return type:

None

Source code at petsc4py/PETSc/SF.pyx:644

fetchAndOpEnd(unit, rootdata, leafdata, leafupdate, op)#

End operation started in a matching call to fetchAndOpBegin.

Collective.

Parameters:
  • unit (Datatype) – MPI datatype.

  • rootdata (ndarray) – Root values to be updated, input state is seen by first process to perform an update.

  • leafdata (ndarray) – Leaf values to use in reduction.

  • leafupdate (ndarray) – State at each leaf’s respective root immediately prior to my atomic update.

  • op (Op) – MPI reduction operation.

Return type:

None

Source code at petsc4py/PETSc/SF.pyx:680

gatherBegin(unit, leafdata, multirootdata)#

Begin pointwise gather of all leaves into multi-roots.

Collective.

This call has to be completed with gatherEnd.

Parameters:
  • unit (Datatype) – MPI datatype.

  • leafdata (ndarray) – Leaf data to gather to roots.

  • multirootdata (ndarray) – Root buffer to gather into, amount of space per root is equal to its degree.

Return type:

None

Source code at petsc4py/PETSc/SF.pyx:594

gatherEnd(unit, leafdata, multirootdata)#

End gather operation that was started with gatherBegin.

Collective.

Parameters:
  • unit (Datatype) – MPI datatype.

  • leafdata (ndarray) – Leaf data to gather to roots.

  • multirootdata (ndarray) – Root buffer to gather into, amount of space per root is equal to its degree.

Return type:

None

Source code at petsc4py/PETSc/SF.pyx:620

getGraph()#

Return star forest graph.

Not collective.

The number of leaves can be determined from the size of ilocal.

Returns:

  • nroots (int) – Number of root vertices on the current process (these are possible targets for other process to attach leaves).

  • ilocal (ArrayInt) – Locations of leaves in leafdata buffers.

  • iremote (ArrayInt) – Remote locations of root vertices for each leaf on the current process.

Return type:

tuple[int, ArrayInt, ArrayInt]

See also

PetscSFGetGraph

Source code at petsc4py/PETSc/SF.pyx:157

getMulti()#

Return the inner SF implementing gathers and scatters.

Collective.

Source code at petsc4py/PETSc/SF.pyx:249

Return type:

SF

getType()#

Return the type name of the star forest.

Collective.

See also

PetscSFGetType

Source code at petsc4py/PETSc/SF.pyx:105

Return type:

str

reduceBegin(unit, leafdata, rootdata, op)#

Begin reduction of leafdata into rootdata.

Collective.

This call has to be completed with call to reduceEnd.

Parameters:
  • unit (Datatype) – MPI datatype.

  • leafdata (ndarray) – Values to reduce.

  • rootdata (ndarray) – Result of reduction of values from all leaves of each root.

  • op (Op) – MPI reduction operation.

Return type:

None

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

reduceEnd(unit, leafdata, rootdata, op)#

End a reduction operation started with reduceBegin.

Collective.

Parameters:
  • unit (Datatype) – MPI datatype.

  • leafdata (ndarray) – Values to reduce.

  • rootdata (ndarray) – Result of reduction of values from all leaves of each root.

  • op (Op) – MPI reduction operation.

Return type:

None

Source code at petsc4py/PETSc/SF.pyx:519

reset()#

Reset a star forest so that different sizes or neighbors can be used.

Collective.

See also

PetscSFReset

Source code at petsc4py/PETSc/SF.pyx:143

Return type:

None

scatterBegin(unit, multirootdata, leafdata)#

Begin pointwise scatter operation.

Collective.

Operation is from multi-roots to leaves. This call has to be completed with scatterEnd.

Parameters:
  • unit (Datatype) – MPI datatype.

  • multirootdata (ndarray) – Root buffer to send to each leaf, one unit of data per leaf.

  • leafdata (ndarray) – Leaf data to be updated with personal data from each respective root.

Return type:

None

Source code at petsc4py/PETSc/SF.pyx:545

scatterEnd(unit, multirootdata, leafdata)#

End scatter operation that was started with scatterBegin.

Collective.

Parameters:
  • unit (Datatype) – MPI datatype.

  • multirootdata (ndarray) – Root buffer to send to each leaf, one unit of data per leaf.

  • leafdata (ndarray) – Leaf data to be updated with personal data from each respective root.

Return type:

None

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

setFromOptions()#

Set options using the options database.

Logically collective.

Source code at petsc4py/PETSc/SF.pyx:119

Return type:

None

setGraph(nroots, local, remote)#

Set star forest graph.

Collective.

The number of leaves argument can be determined from the size of local and/or remote.

Parameters:
  • nroots (int) – Number of root vertices on the current process (these are possible targets for other process to attach leaves).

  • local (Sequence[int]) – Locations of leaves in leafdata buffers, pass None for contiguous storage.

  • remote (Sequence[int]) – Remote locations of root vertices for each leaf on the current process. Should be 2*nleaves long as (rank, index) pairs.

Return type:

None

See also

PetscSFSetGraph

Source code at petsc4py/PETSc/SF.pyx:192

setRankOrder(flag)#

Sort multi-points for gathers and scatters by rank order.

Logically collective.

Parameters:

flag (bool) – True to sort, False to skip sorting.

Return type:

None

Source code at petsc4py/PETSc/SF.pyx:231

setType(sf_type)#

Set the type of the star forest.

Collective.

Parameters:

sf_type (Type | str) – The star forest type.

Return type:

None

See also

PetscSFSetType

Source code at petsc4py/PETSc/SF.pyx:86

setUp()#

Set up communication structures.

Collective.

See also

PetscSFSetUp

Source code at petsc4py/PETSc/SF.pyx:131

Return type:

None

view(viewer=None)#

View a star forest.

Collective.

Parameters:

viewer (Viewer | None) – A Viewer to display the graph.

Return type:

None

See also

PetscSFView

Source code at petsc4py/PETSc/SF.pyx:33