Skip to main content
`Ctrl`+`K`

# petsc4py.PETSc.IS

class petsc4py.PETSc.IS

  Bases: `Object`

  A collection of indices.

  IS objects are used to index into vectors and matrices and to set up vector scatters.

  See also

  `IS`

  Enumerations

  `Type` | The index set types.

  Methods Summary

  `allGather`() | Concatenate index sets stored across processors.
  `buildTwoSided`([toindx]) | Create an index set describing a global mapping.
  `complement`(nmin, nmax) | Create a complement index set.
  `copy`([result]) | Copy the contents of the index set into another.
  `create`([comm]) | Create an IS.
  `createBlock`(bsize, indices[, comm]) | Create a blocked index set.
  `createGeneral`(indices[, comm]) | Create an IS with indices.
  `createStride`(size[, first, step, comm]) | Create an index set consisting of evenly spaced values.
  `destroy`() | Destroy the index set.
  `difference`(iset) | Return the difference between two index sets.
  `duplicate`() | Create a copy of the index set.
  `embed`(iset, drop) | Embed `self` into `iset`.
  `equal`(iset) | Return whether the index sets have the same set of indices or not.
  `expand`(iset) | Return the union of two (possibly unsorted) index sets.
  `getBlockIndices`() | Return the indices of an index set with type `IS.Type.BLOCK`.
  `getBlockSize`() | Return the number of elements in a block.
  `getIndices`() | Return the indices of the index set.
  `getInfo`() | Return stride information for an index set with type `IS.Type.STRIDE`.
  `getLocalSize`() | Return the process-local length of the index set.
  `getSize`() | Return the global length of an index set.
  `getSizes`() | Return the local and global sizes of the index set.
  `getStride`() | Return size and stride information.
  `getType`() | Return the index set type associated with the IS.
  `invertPermutation`([nlocal]) | Invert the index set.
  `isIdentity`() | Return whether the index set has been declared as an identity.
  `isPermutation`() | Return whether an index set has been declared to be a permutation.
  `isSorted`() | Return whether the indices have been sorted.
  `load`(viewer) | Load a stored index set.
  `partitioningCount`([npart]) | Return the number of elements per process after a partitioning.
  `partitioningToNumbering`() | Return the new global numbering after a partitioning.
  `renumber`([mult]) | Renumber the non-negative entries of an index set, starting from 0.
  `setBlockIndices`(bsize, indices) | Set the indices for an index set with type `IS.Type.BLOCK`.
  `setBlockSize`(bs) | Set the block size of the index set.
  `setIdentity`() | Mark the index set as being an identity.
  `setIndices`(indices) | Set the indices of an index set.
  `setPermutation`() | Mark the index set as being a permutation.
  `setStride`(size[, first, step]) | Set the stride information for an index set with type `IS.Type.STRIDE`.
  `setType`(is_type) | Set the type of the index set.
  `sort`() | Sort the indices of an index set.
  `sum`(iset) | Return the union of two (sorted) index sets.
  `toGeneral`() | Convert the index set type to `IS.Type.GENERAL`.
  `union`(iset) | Return the union of two (possibly unsorted) index sets.
  `view`([viewer]) | Display the index set.

  Attributes Summary

  `array` | View of the index set as an array of integers.
  `block_size` | The number of elements in a block.
  `identity` | `True` if index set is an identity, `False` otherwise.
  `indices` | The indices of the index set.
  `local_size` | The local size of the index set.
  `permutation` | `True` if index set is a permutation, `False` otherwise.
  `size` | The global size of the index set.
  `sizes` | The local and global sizes of the index set.
  `sorted` | `True` if index set is sorted, `False` otherwise.

  Methods Documentation

  allGather()

    Concatenate index sets stored across processors.

    Collective.

    The returned index set will be the same on every processor.

    See also

    `ISAllGather`

    Source code at petsc4py/PETSc/IS.pyx:304

    Return type:

      IS

  buildTwoSided(toindx=None)

    Create an index set describing a global mapping.

    Collective.

    This function generates an index set that contains new numbers from remote or local on the index set.

    Parameters:

      toindx (IS | None) – Index set describing which indices to send, default is to send natural numbering.

    Returns:

      New index set containing the new numbers from remote or local.

    Return type:

      `IS`

    See also

    `ISBuildTwoSided`

    Source code at petsc4py/PETSc/IS.pyx:333

  complement(nmin, nmax)

    Create a complement index set.

    Collective.

    The complement set of indices is all indices that are not in the provided set (and within the provided bounds).

    Parameters:

      - nmin (int) – Minimum index that can be found in the local part of the complement index set.

      - nmax (int) – One greater than the maximum index that can be found in the local part of the complement index set.

    Return type:

      IS

    Notes

    For a parallel index set, this will generate the local part of the complement on each process.

    To generate the entire complement (on each process) of a parallel index set, first call `IS.allGather` and then call this method.

    See also

    `IS.allGather`, `ISComplement`

    Source code at petsc4py/PETSc/IS.pyx:723

  copy(result=None)

    Copy the contents of the index set into another.

    Collective.

    Parameters:

      result (IS | None) – The target index set. If `None` then `IS.duplicate` is called first.

    Returns:

      The copied index set. If `result` is not `None` then this is returned here.

    Return type:

      `IS`

    See also

    `IS.duplicate`, `ISCopy`

    Source code at petsc4py/PETSc/IS.pyx:253

  create(comm=None)

    Create an IS.

    Collective.

    Parameters:

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

    Return type:

      Self

    See also

    `ISCreate`

    Source code at petsc4py/PETSc/IS.pyx:88

  createBlock(bsize, indices, comm=None)

    Create a blocked index set.

    Collective.

    Parameters:

      - bsize (int) – Block size.

      - indices (Sequence[int]) – Integer array of indices.

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

    Return type:

      Self

    See also

    `ISCreateBlock`

    Source code at petsc4py/PETSc/IS.pyx:171

  createGeneral(indices, comm=None)

    Create an IS with indices.

    Collective.

    Parameters:

      - indices (Sequence[int]) – Integer array.

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

    Return type:

      Self

    See also

    `ISCreateGeneral`

    Source code at petsc4py/PETSc/IS.pyx:142

  createStride(size, first=0, step=1, comm=None)

    Create an index set consisting of evenly spaced values.

    Collective.

    Parameters:

      - size (int) – The length of the locally owned portion of the index set.

      - first (int) – The first element of the index set.

      - step (int) – The difference between adjacent indices.

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

    Return type:

      Self

    See also

    `ISCreateStride`

    Source code at petsc4py/PETSc/IS.pyx:204

  destroy()

    Destroy the index set.

    Collective.

    See also

    `ISDestroy`

    Source code at petsc4py/PETSc/IS.pyx:75

    Return type:

      Self

  difference(iset)

    Return the difference between two index sets.

    Collective.

    Parameters:

      iset (IS) – Index set to compute the difference with.

    Returns:

      Index set representing the difference between `self` and `iset`.

    Return type:

      `IS`

    See also

    `ISDifference`

    Source code at petsc4py/PETSc/IS.pyx:699

  duplicate()

    Create a copy of the index set.

    Collective.

    See also

    `IS.copy`, `ISDuplicate`

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

    Return type:

      IS

  embed(iset, drop)

    Embed `self` into `iset`.

    Not collective.

    The embedding is performed by finding the locations in `iset` that have the same indices as `self`.

    Parameters:

      - iset (IS) – The index set to embed into.

      - drop (bool) – Flag indicating whether to drop indices from `self` that are not in `iset`.

    Returns:

      The embedded index set.

    Return type:

      `IS`

    See also

    `ISEmbed`

    Source code at petsc4py/PETSc/IS.pyx:759

  equal(iset)

    Return whether the index sets have the same set of indices or not.

    Collective.

    Parameters:

      iset (IS) – The index set to compare indices with.

    Return type:

      bool

    See also

    `ISEqual`

    Source code at petsc4py/PETSc/IS.pyx:599

  expand(iset)

    Return the union of two (possibly unsorted) index sets.

    Collective.

    To compute the union, `expand` concatenates the two index sets and removes any duplicates.

    Parameters:

      iset (IS) – Index set to compute the union with.

    Returns:

      The new, combined, index set.

    Return type:

      `IS`

    See also

    `ISExpand`

    Source code at petsc4py/PETSc/IS.pyx:637

  getBlockIndices()

    Return the indices of an index set with type `IS.Type.BLOCK`.

    Not collective.

    See also

    `ISBlockGetIndices`

    Source code at petsc4py/PETSc/IS.pyx:882

    Return type:

      ArrayInt

  getBlockSize()

    Return the number of elements in a block.

    Not collective.

    See also

    `ISGetBlockSize`

    Source code at petsc4py/PETSc/IS.pyx:486

    Return type:

      int

  getIndices()

    Return the indices of the index set.

    Not collective.

    See also

    `ISGetIndices`

    Source code at petsc4py/PETSc/IS.pyx:838

    Return type:

      ArrayInt

  getInfo()

    Return stride information for an index set with type `IS.Type.STRIDE`.

    Not collective.

    Returns:

      - first (`int`) – First element of the index set.

      - step (`int`) – Difference between adjacent indices.

    Return type:

      tuple[int, int]

    See also

    `IS.getStride`, `ISStrideGetInfo`

    Source code at petsc4py/PETSc/IS.pyx:952

  getLocalSize()

    Return the process-local length of the index set.

    Not collective.

    See also

    `ISGetLocalSize`

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

    Return type:

      int

  getSize()

    Return the global length of an index set.

    Not collective.

    See also

    `ISGetSize`

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

    Return type:

      int

  getSizes()

    Return the local and global sizes of the index set.

    Not collective.

    Returns:

      - local_size (`int`) – The local size.

      - global_size (`int`) – The global size.

    Return type:

      tuple[int, int]

    See also

    `IS.getLocalSize`, `IS.getSize`

    Source code at petsc4py/PETSc/IS.pyx:464

  getStride()

    Return size and stride information.

    Not collective.

    Returns:

      - size (`int`) – Length of the locally owned portion of the index set.

      - first (`int`) – First element of the index set.

      - step (`int`) – Difference between adjacent indices.

    Return type:

      tuple[int, int, int]

    See also

    `ISGetLocalSize`, `ISStrideGetInfo`

    Source code at petsc4py/PETSc/IS.pyx:928

  getType()

    Return the index set type associated with the IS.

    Not collective.

    See also

    `ISGetType`

    Source code at petsc4py/PETSc/IS.pyx:128

    Return type:

      str

  invertPermutation(nlocal=None)

    Invert the index set.

    Collective.

    For this to be correct the index set must be a permutation.

    Parameters:

      nlocal (int | None) – The number of indices on this processor in the resulting index set, defaults to `PETSC_DECIDE`.

    Return type:

      IS

    See also

    `ISInvertPermutation`

    Source code at petsc4py/PETSc/IS.pyx:363

  isIdentity()

    Return whether the index set has been declared as an identity.

    Collective.

    See also

    `ISIdentity`

    Source code at petsc4py/PETSc/IS.pyx:585

    Return type:

      bool

  isPermutation()

    Return whether an index set has been declared to be a permutation.

    Logically collective.

    See also

    `ISPermutation`

    Source code at petsc4py/PETSc/IS.pyx:558

    Return type:

      bool

  isSorted()

    Return whether the indices have been sorted.

    Collective.

    See also

    `ISSorted`

    Source code at petsc4py/PETSc/IS.pyx:531

    Return type:

      bool

  load(viewer)

    Load a stored index set.

    Collective.

    Parameters:

      viewer (Viewer) – Binary file viewer, either `Viewer.Type.BINARY` or `Viewer.Type.HDF5`.

    Return type:

      Self

    See also

    `ISLoad`

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

  partitioningCount(npart=None)

    Return the number of elements per process after a partitioning.

    Collective.

    Assuming that the index set represents a partitioning, determine the number of elements on each (partition) rank.

    Parameters:

      npart (int | None) – The number of partitions, defaults to the size of the communicator.

    Return type:

      ArrayInt

    See also

    `ISPartitioningCount`

    Source code at petsc4py/PETSc/IS.pyx:404

  partitioningToNumbering()

    Return the new global numbering after a partitioning.

    Collective.

    Assuming that the index set represents a partitioning, generate another index set with the new global node number in the new ordering.

    See also

    `ISPartitioningToNumbering`

    Source code at petsc4py/PETSc/IS.pyx:387

    Return type:

      IS

  renumber(mult=None)

    Renumber the non-negative entries of an index set, starting from 0.

    Collective.

    Parameters:

      mult (IS | None) – The multiplicity of each entry in `self`, default implies a multiplicity of 1.

    Returns:

      - `int` – One past the largest entry of the new index set.

      - `IS` – The renumbered index set.

    Return type:

      tuple[int, IS]

    See also

    `ISRenumber`

    Source code at petsc4py/PETSc/IS.pyx:790

  setBlockIndices(bsize, indices)

    Set the indices for an index set with type `IS.Type.BLOCK`.

    Collective.

    Parameters:

      - bsize (int) – Number of elements in each block.

      - indices (Sequence[int]) – List of integers.

    Return type:

      None

    See also

    `ISBlockSetIndices`

    Source code at petsc4py/PETSc/IS.pyx:859

  setBlockSize(bs)

    Set the block size of the index set.

    Logically collective.

    Parameters:

      bs (int) – Block size.

    Return type:

      None

    See also

    `ISSetBlockSize`

    Source code at petsc4py/PETSc/IS.pyx:500

  setIdentity()

    Mark the index set as being an identity.

    Logically collective.

    See also

    `ISSetIdentity`

    Source code at petsc4py/PETSc/IS.pyx:572

    Return type:

      Self

  setIndices(indices)

    Set the indices of an index set.

    Logically collective.

    The index set is assumed to be of type `IS.Type.GENERAL`.

    See also

    `ISGeneralSetIndices`

    Source code at petsc4py/PETSc/IS.pyx:821

    Parameters:

      indices (Sequence[int])

    Return type:

      None

  setPermutation()

    Mark the index set as being a permutation.

    Logically collective.

    See also

    `ISSetPermutation`

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

    Return type:

      Self

  setStride(size, first=0, step=1)

    Set the stride information for an index set with type `IS.Type.STRIDE`.

    Logically collective.

    Parameters:

      - size (int) – Length of the locally owned portion of the index set.

      - first (int) – First element of the index set.

      - step (int) – Difference between adjacent indices.

    Return type:

      None

    See also

    `ISStrideSetStride`

    Source code at petsc4py/PETSc/IS.pyx:904

  setType(is_type)

    Set the type of the index set.

    Collective.

    Parameters:

      is_type (Type | str) – The index set type.

    Return type:

      None

    See also

    `ISSetType`

    Source code at petsc4py/PETSc/IS.pyx:109

  sort()

    Sort the indices of an index set.

    Collective.

    See also

    `ISSort`

    Source code at petsc4py/PETSc/IS.pyx:518

    Return type:

      Self

  sum(iset)

    Return the union of two (sorted) index sets.

    Collective.

    Parameters:

      iset (IS) – The index set to compute the union with.

    Return type:

      IS

    See also

    `ISSum`

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

  toGeneral()

    Convert the index set type to `IS.Type.GENERAL`.

    Collective.

    See also

    `ISToGeneral`, `ISType`

    Source code at petsc4py/PETSc/IS.pyx:320

    Return type:

      Self

  union(iset)

    Return the union of two (possibly unsorted) index sets.

    Collective.

    This function will call either `ISSum` or `ISExpand` depending on whether or not the input sets are already sorted.

    Sequential only (as `ISSum` is sequential only).

    Parameters:

      iset (IS) – Index set to compute the union with.

    Returns:

      The new, combined, index set.

    Return type:

      `IS`

    See also

    `IS.expand`, `IS.sum`

    Source code at petsc4py/PETSc/IS.pyx:664

  view(viewer=None)

    Display the index set.

    Collective.

    Parameters:

      viewer (Viewer | None) – Viewer used to display the IS.

    Return type:

      None

    See also

    `ISView`

    Source code at petsc4py/PETSc/IS.pyx:56

  Attributes Documentation

  array

    View of the index set as an array of integers.

    Not collective.

    Source code at petsc4py/PETSc/IS.pyx:1081

  block_size

    The number of elements in a block.

    Not collective.

    See also

    `IS.getBlockSize`

    Source code at petsc4py/PETSc/IS.pyx:1055

  identity

    `True` if index set is an identity, `False` otherwise.

    Collective.

    See also

    `IS.isIdentity`

    Source code at petsc4py/PETSc/IS.pyx:988

  indices

    The indices of the index set.

    Not collective.

    See also

    `IS.getIndices`

    Source code at petsc4py/PETSc/IS.pyx:1068

  local_size

    The local size of the index set.

    Not collective.

    See also

    `IS.getLocalSize`

    Source code at petsc4py/PETSc/IS.pyx:1042

  permutation

    `True` if index set is a permutation, `False` otherwise.

    Logically collective.

    See also

    `IS.isPermutation`

    Source code at petsc4py/PETSc/IS.pyx:975

  size

    The global size of the index set.

    Not collective.

    See also

    `IS.getSize`

    Source code at petsc4py/PETSc/IS.pyx:1029

  sizes

    The local and global sizes of the index set.

    Not collective.

    See also

    `IS.getSizes`

    Source code at petsc4py/PETSc/IS.pyx:1016

  sorted

    `True` if index set is sorted, `False` otherwise.

    Collective.

    See also

    `IS.isSorted`

    Source code at petsc4py/PETSc/IS.pyx:1001