Skip to main content
`Ctrl`+`K`

# petsc4py.PETSc.Scatter

class petsc4py.PETSc.Scatter

  Bases: `Object`

  Scatter object.

  The object used to perform data movement between vectors. Scatter is described in the `PETSc manual`.

  See also

  `Vec`, `SF`, `VecScatter`

  Enumerations

  `Mode` | Scatter mode.
  `Type` | Scatter type.

  Methods Summary

  `begin`(vec_from, vec_to[, addv, mode]) | Begin a generalized scatter from one vector into another.
  `copy`() | Return a copy of the scatter.
  `create`(vec_from, is_from, vec_to, is_to) | Create a scatter object.
  `destroy`() | Destroy the scatter.
  `end`(vec_from, vec_to[, addv, mode]) | Complete a generalized scatter from one vector into another.
  `getType`() | Return the type of the scatter.
  `scatter`(vec_from, vec_to[, addv, mode]) | Perform a generalized scatter from one vector into another.
  `setFromOptions`() | Configure the scatter from the options database.
  `setType`(scatter_type) | Set the type of the scatter.
  `setUp`() | Set up the internal data structures for using the scatter.
  `toAll`(vec) | Create a scatter that communicates a vector to all sharing processes.
  `toZero`(vec) | Create a scatter that communicates a vector to rank zero.
  `view`([viewer]) | View the scatter.

  Methods Documentation

  begin(vec_from, vec_to, addv=None, mode=None)

    Begin a generalized scatter from one vector into another.

    Collective.

    This call has to be concluded with a call to `end`. For additional details on the Parameters, see `scatter`.

    See also

    `create`, `end`, `VecScatterBegin`

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

    Parameters:

      - vec_from (Vec)

      - vec_to (Vec)

      - addv (InsertModeSpec)

      - mode (ScatterModeSpec)

    Return type:

      None

  copy()

    Return a copy of the scatter.

    Source code at petsc4py/PETSc/Scatter.pyx:199

    Return type:

      Scatter

  create(vec_from, is_from, vec_to, is_to)

    Create a scatter object.

    Collective.

    Parameters:

      - vec_from (Vec) – Representative vector from which to scatter the data.

      - is_from (IS) – Indices of `vec_from` to scatter. If `None`, use all indices.

      - vec_to (Vec) – Representative vector to which scatter the data.

      - is_to (IS) – Indices of `vec_to` where to receive. If `None`, use all indices.

    Return type:

      Self

    Examples

    The scatter object can be used to repeatedly perform data movement. It is the PETSc equivalent of NumPy-like indexing and slicing, with support for parallel communications:

        >>> revmode = PETSc.Scatter.Mode.REVERSE
        >>> v1 = PETSc.Vec().createWithArray([1, 2, 3])
        >>> v2 = PETSc.Vec().createWithArray([0, 0, 0])
        >>> sct = PETSc.Scatter().create(v1,None,v2,None)
        >>> sct.scatter(v1,v2) # v2[:] = v1[:]
        >>> sct.scatter(v2,v1,mode=revmode) # v1[:] = v2[:]

        >>> revmode = PETSc.Scatter.Mode.REVERSE
        >>> v1 = PETSc.Vec().createWithArray([1, 2, 3, 4])
        >>> v2 = PETSc.Vec().createWithArray([0, 0])
        >>> is1 = PETSc.IS().createStride(2, 3, -2)
        >>> sct = PETSc.Scatter().create(v1,is1,v2,None)
        >>> sct.scatter(v1,v2) # v2[:] = v1[3:0:-2]
        >>> sct.scatter(v2,v1,mode=revmode) # v1[3:0:-2] = v2[:]

    See also

    `IS`, `VecScatterCreate`

    Source code at petsc4py/PETSc/Scatter.pyx:90

  destroy()

    Destroy the scatter.

    Collective.

    See also

    `VecScatterDestroy`

    Source code at petsc4py/PETSc/Scatter.pyx:77

    Return type:

      Self

  end(vec_from, vec_to, addv=None, mode=None)

    Complete a generalized scatter from one vector into another.

    Collective.

    This call has to be preceded by a call to `begin`. For additional details on the Parameters, see `scatter`.

    See also

    `create`, `begin`, `VecScatterEnd`

    Source code at petsc4py/PETSc/Scatter.pyx:285

    Parameters:

      - vec_from (Vec)

      - vec_to (Vec)

      - addv (InsertModeSpec)

      - mode (ScatterModeSpec)

    Return type:

      None

  getType()

    Return the type of the scatter.

    Not collective.

    See also

    `setType`, `VecScatterGetType`

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

    Return type:

      str

  scatter(vec_from, vec_to, addv=None, mode=None)

    Perform a generalized scatter from one vector into another.

    Collective.

    Parameters:

      - vec_from (Vec) – The source vector.

      - vec_to (Vec) – The destination vector.

      - addv (InsertModeSpec) – Insertion mode.

      - mode (ScatterModeSpec) – Scatter mode.

    Return type:

      None

    See also

    `create`, `begin`, `end`, `VecScatterBegin`, `VecScatterEnd`

    Source code at petsc4py/PETSc/Scatter.pyx:308

  setFromOptions()

    Configure the scatter from the options database.

    Collective.

    See also

    Working with PETSc options, `VecScatterSetFromOptions`

    Source code at petsc4py/PETSc/Scatter.pyx:174

    Return type:

      None

  setType(scatter_type)

    Set the type of the scatter.

    Logically collective.

    See also

    `getType`, `VecScatterSetType`

    Source code at petsc4py/PETSc/Scatter.pyx:146

    Parameters:

      scatter_type (Type | str)

    Return type:

      None

  setUp()

    Set up the internal data structures for using the scatter.

    Collective.

    See also

    `VecScatterSetUp`

    Source code at petsc4py/PETSc/Scatter.pyx:186

    Return type:

      Self

  classmethod toAll(vec)

    Create a scatter that communicates a vector to all sharing processes.

    Collective.

    Parameters:

      vec (Vec) – The vector to scatter from.

    Return type:

      tuple[Scatter, Vec]

    Notes

    The created scatter will have the same communicator of `vec`. The method also returns an output vector of appropriate size to contain the result of the operation.

    See also

    `toZero`, `VecScatterCreateToAll`

    Source code at petsc4py/PETSc/Scatter.pyx:205

  classmethod toZero(vec)

    Create a scatter that communicates a vector to rank zero.

    Collective.

    Parameters:

      vec (Vec) – The vector to scatter from.

    Return type:

      tuple[Scatter, Vec]

    Notes

    The created scatter will have the same communicator of `vec`. The method also returns an output vector of appropriate size to contain the result of the operation.

    See also

    `toAll`, `VecScatterCreateToZero`

    Source code at petsc4py/PETSc/Scatter.pyx:233

  view(viewer=None)

    View the scatter.

    Collective.

    Parameters:

      viewer (Viewer | None) – A `Viewer` instance or `None` for the default viewer.

    Return type:

      None

    See also

    `VecScatterView`

    Source code at petsc4py/PETSc/Scatter.pyx:58

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