Skip to main content
`Ctrl`+`K`

# 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` | The star forest types.

  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

    See also

    `bcastEnd`, `PetscSFBcastBegin`

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

  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

    See also

    `bcastBegin`, `PetscSFBcastEnd`

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

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

  computeDegree()

    Compute and return the degree of each root vertex.

    Collective.

    See also

    `PetscSFComputeDegreeBegin`, `PetscSFComputeDegreeEnd`

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

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

  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

    See also

    `PetscSFCreateEmbeddedLeafSF`

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

  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

    See also

    `PetscSFCreateEmbeddedRootSF`

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

  createInverse()

    Create the inverse map.

    Collective.

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

    See also

    `PetscSFCreateInverseSF`

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

    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

    See also

    `PetscSFCreateSectionSF`

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

  destroy()

    Destroy the star forest.

    Collective.

    See also

    `PetscSFDestroy`

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

    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]

    See also

    `PetscSFDistributeSection`

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

  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

    See also

    `fetchAndOpEnd`, `PetscSFFetchAndOpBegin`

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

  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

    See also

    `fetchAndOpBegin`, `PetscSFFetchAndOpEnd`

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

  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

    See also

    `gatherEnd`, `PetscSFGatherBegin`

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

  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

    See also

    `gatherBegin`, `PetscSFGatherEnd`

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

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

  getMulti()

    Return the inner SF implementing gathers and scatters.

    Collective.

    See also

    `PetscSFGetMultiSF`

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

    Return type:

      SF

  getType()

    Return the type name of the star forest.

    Collective.

    See also

    `PetscSFGetType`

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

    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

    See also

    `reduceEnd`, `PetscSFReduceBegin`

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

  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

    See also

    `reduceBegin`, `PetscSFReduceEnd`

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

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

    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

    See also

    `scatterEnd`, `PetscSFScatterBegin`

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

  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

    See also

    `scatterBegin`, `PetscSFScatterEnd`

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

  setFromOptions()

    Set options using the options database.

    Logically collective.

    See also

    Working with PETSc options, `PetscSFSetFromOptions`

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

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

  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

    See also

    `PetscSFSetRankOrder`

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

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

  setUp()

    Set up communication structures.

    Collective.

    See also

    `PetscSFSetUp`

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

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

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