Skip to main content
`Ctrl`+`K`

# petsc4py.PETSc.DMLabel

class petsc4py.PETSc.DMLabel

  Bases: `Object`

  An object representing a subset of mesh entities from a `DM`.

  Methods Summary

  `addStrata`(strata) | Add new stratum values in a `DMLabel`.
  `addStrataIS`(iset) | Add new stratum values in a `DMLabel`.
  `addStratum`(value) | Add a new stratum value in a `DMLabel`.
  `clearStratum`(stratum) | Remove a stratum.
  `clearValue`(point, value) | Clear the value a label assigns to a point.
  `computeIndex`() | Create an index structure for membership determination.
  `convertToSection`() | Return a `Section` and `IS` that encode the label.
  `create`(name[, comm]) | Create a `DMLabel` object, which is a multimap.
  `createIndex`(pStart, pEnd) | Create an index structure for membership determination.
  `destroy`() | Destroy the label.
  `destroyIndex`() | Destroy the index structure.
  `distribute`(sf) | Create a new label pushed forward over the `SF`.
  `duplicate`() | Duplicate the `DMLabel`.
  `filter`(start, end) | Remove all points outside of [start, end).
  `gather`(sf) | Gather all label values from leaves into roots.
  `getBounds`() | Return the smallest and largest point in the label.
  `getDefaultValue`() | Return the default value returned by `getValue`.
  `getNonEmptyStratumValuesIS`() | Return an `IS` of all values that the `DMLabel` takes.
  `getNumValues`() | Return the number of values that the `DMLabel` takes.
  `getStratumIS`(stratum) | Return an `IS` with the stratum points.
  `getStratumSize`(stratum) | Return the size of a stratum.
  `getValue`(point) | Return the value a label assigns to a point.
  `getValueIS`() | Return an `IS` of all values that the `DMLabel` takes.
  `hasPoint`(point) | Determine whether the label contains a point.
  `hasStratum`(value) | Determine whether points exist with the given value.
  `hasValue`(value) | Determine whether a label assigns the value to any point.
  `insertIS`(iset, value) | Set all points in the `IS` to a value.
  `permute`(permutation) | Create a new label with permuted points.
  `reset`() | Destroy internal data structures in the `DMLabel`.
  `setDefaultValue`(value) | Set the default value returned by `getValue`.
  `setStratumIS`(stratum, iset) | Set the stratum points using an `IS`.
  `setValue`(point, value) | Set the value a label assigns to a point.
  `stratumHasPoint`(value, point) | Return whether the stratum contains a point.
  `view`([viewer]) | View the label.

  Methods Documentation

  addStrata(strata)

    Add new stratum values in a `DMLabel`.

    Not collective.

    Parameters:

      strata (Sequence[int]) – The stratum values.

    Return type:

      None

    See also

    `addStrataIS`, `addStratum`, `DMLabelAddStrata`

    Source code at petsc4py/PETSc/DMLabel.pyx:238

  addStrataIS(iset)

    Add new stratum values in a `DMLabel`.

    Not collective.

    Parameters:

      iset (IS) – Index set with stratum values.

    Return type:

      None

    See also

    `addStrata`, `addStratum`, `DMLabelAddStrataIS`

    Source code at petsc4py/PETSc/DMLabel.pyx:258

  addStratum(value)

    Add a new stratum value in a `DMLabel`.

    Not collective.

    Parameters:

      value (int) – The stratum value.

    Return type:

      None

    See also

    `addStrata`, `addStrataIS`, `DMLabelAddStratum`

    Source code at petsc4py/PETSc/DMLabel.pyx:220

  clearStratum(stratum)

    Remove a stratum.

    Not collective.

    Parameters:

      stratum (int) – The stratum value.

    Return type:

      None

    See also

    `DMLabelClearStratum`

    Source code at petsc4py/PETSc/DMLabel.pyx:406

  clearValue(point, value)

    Clear the value a label assigns to a point.

    Not collective.

    Parameters:

      - point (int) – The point.

      - value (int) – The point value.

    Return type:

      None

    See also

    `DMLabelClearValue`

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

  computeIndex()

    Create an index structure for membership determination.

    Not collective.

    Automatically determines the bounds.

    See also

    `DMLabelComputeIndex`

    Source code at petsc4py/PETSc/DMLabel.pyx:424

    Return type:

      None

  convertToSection()

    Return a `Section` and `IS` that encode the label.

    Not collective.

    See also

    `DMLabelConvertToSection`

    Source code at petsc4py/PETSc/DMLabel.pyx:607

    Return type:

      tuple[Section, IS]

  create(name, comm=None)

    Create a `DMLabel` object, which is a multimap.

    Collective.

    Parameters:

      - name (str) – The label name.

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

    Return type:

      Self

    See also

    `DMLabelCreate`

    Source code at petsc4py/PETSc/DMLabel.pyx:40

  createIndex(pStart, pEnd)

    Create an index structure for membership determination.

    Not collective.

    Parameters:

      - pStart (int) – The smallest point.

      - pEnd (int) – The largest point + 1.

    Return type:

      None

    See also

    `destroyIndex`, `DMLabelCreateIndex`

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

  destroy()

    Destroy the label.

    Collective.

    See also

    `DMLabelDestroy`

    Source code at petsc4py/PETSc/DMLabel.pyx:8

    Return type:

      Self

  destroyIndex()

    Destroy the index structure.

    Not collective.

    See also

    `createIndex`, `DMLabelDestroyIndex`

    Source code at petsc4py/PETSc/DMLabel.pyx:458

    Return type:

      None

  distribute(sf)

    Create a new label pushed forward over the `SF`.

    Collective.

    Parameters:

      sf (SF) – The map from old to new distribution.

    Return type:

      DMLabel

    See also

    `gather`, `DMLabelDistribute`

    Source code at petsc4py/PETSc/DMLabel.pyx:567

  duplicate()

    Duplicate the `DMLabel`.

    Collective.

    See also

    `DMLabelDuplicate`

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

    Return type:

      DMLabel

  filter(start, end)

    Remove all points outside of [start, end).

    Not collective.

    Parameters:

      - start (int) – The first point kept.

      - end (int) – One more than the last point kept.

    Return type:

      None

    See also

    `DMLabelFilter`

    Source code at petsc4py/PETSc/DMLabel.pyx:528

  gather(sf)

    Gather all label values from leaves into roots.

    Collective.

    This is the inverse operation to `distribute`.

    Parameters:

      sf (SF) – The `SF` communication map.

    Return type:

      DMLabel

    See also

    `distribute`, `DMLabelGather`

    Source code at petsc4py/PETSc/DMLabel.pyx:586

  getBounds()

    Return the smallest and largest point in the label.

    Not collective.

    The returned values are the smallest point and the largest point + 1.

    See also

    `DMLabelGetBounds`

    Source code at petsc4py/PETSc/DMLabel.pyx:512

    Return type:

      tuple[int, int]

  getDefaultValue()

    Return the default value returned by `getValue`.

    Not collective.

    The default value is returned if a point has not been explicitly given a value. When a label is created, it is initialized to `-1`.

    See also

    `setDefaultValue`, `DMLabelGetDefaultValue`

    Source code at petsc4py/PETSc/DMLabel.pyx:161

    Return type:

      int

  getNonEmptyStratumValuesIS()

    Return an `IS` of all values that the `DMLabel` takes.

    Not collective.

    See also

    `DMLabelGetNonEmptyStratumValuesIS`

    Source code at petsc4py/PETSc/DMLabel.pyx:622

    Return type:

      IS

  getNumValues()

    Return the number of values that the `DMLabel` takes.

    Not collective.

    See also

    `DMLabelGetNumValues`

    Source code at petsc4py/PETSc/DMLabel.pyx:275

    Return type:

      int

  getStratumIS(stratum)

    Return an `IS` with the stratum points.

    Not collective.

    Parameters:

      stratum (int) – The stratum value.

    Return type:

      IS

    See also

    `setStratumIS`, `DMLabelGetStratumIS`

    Source code at petsc4py/PETSc/DMLabel.pyx:366

  getStratumSize(stratum)

    Return the size of a stratum.

    Not collective.

    Parameters:

      stratum (int) – The stratum value.

    Return type:

      int

    See also

    `DMLabelGetStratumSize`

    Source code at petsc4py/PETSc/DMLabel.pyx:346

  getValue(point)

    Return the value a label assigns to a point.

    Not collective.

    If no value was assigned, a default value will be returned The default value, initially `-1`, can be changed with `setDefaultValue`.

    Parameters:

      point (int) – The point.

    Return type:

      int

    See also

    `setValue`, `setDefaultValue`, `DMLabelGetValue`

    Source code at petsc4py/PETSc/DMLabel.pyx:137

  getValueIS()

    Return an `IS` of all values that the `DMLabel` takes.

    Not collective.

    See also

    `DMLabelGetValueIS`

    Source code at petsc4py/PETSc/DMLabel.pyx:289

    Return type:

      IS

  hasPoint(point)

    Determine whether the label contains a point.

    Not collective.

    The user must call `createIndex` before this function.

    Parameters:

      point (int) – The point.

    Return type:

      bool

    See also

    `hasValue`, `DMLabelHasPoint`

    Source code at petsc4py/PETSc/DMLabel.pyx:490

  hasStratum(value)

    Determine whether points exist with the given value.

    Not collective.

    Parameters:

      value (int) – The stratum value.

    Return type:

      bool

    See also

    `DMLabelHasStratum`

    Source code at petsc4py/PETSc/DMLabel.pyx:326

  hasValue(value)

    Determine whether a label assigns the value to any point.

    Not collective.

    Parameters:

      value (int) – The value.

    Return type:

      bool

    See also

    `hasPoint`, `DMLabelHasValue`

    Source code at petsc4py/PETSc/DMLabel.pyx:470

  insertIS(iset, value)

    Set all points in the `IS` to a value.

    Not collective.

    Parameters:

      - iset (IS) – The point IS.

      - value (int) – The point value.

    Return type:

      Self

    See also

    `DMLabelInsertIS`

    Source code at petsc4py/PETSc/DMLabel.pyx:91

  permute(permutation)

    Create a new label with permuted points.

    Not collective.

    Parameters:

      permutation (IS) – The point permutation.

    Return type:

      DMLabel

    See also

    `DMLabelPermute`

    Source code at petsc4py/PETSc/DMLabel.pyx:548

  reset()

    Destroy internal data structures in the `DMLabel`.

    Not collective.

    See also

    `DMLabelReset`

    Source code at petsc4py/PETSc/DMLabel.pyx:79

    Return type:

      None

  setDefaultValue(value)

    Set the default value returned by `getValue`.

    Not collective.

    The value is used if a point has not been explicitly given a value. When a label is created, the default value is initialized to `-1`.

    Parameters:

      value (int) – The default value.

    Return type:

      None

    See also

    `getDefaultValue`, `DMLabelSetDefaultValue`

    Source code at petsc4py/PETSc/DMLabel.pyx:178

  setStratumIS(stratum, iset)

    Set the stratum points using an `IS`.

    Not collective.

    Parameters:

      - stratum (int) – The stratum value.

      - iset (IS) – The stratum points.

    Return type:

      None

    See also

    `getStratumIS`, `DMLabelSetStratumIS`

    Source code at petsc4py/PETSc/DMLabel.pyx:386

  setValue(point, value)

    Set the value a label assigns to a point.

    Not collective.

    If the value is the same as the label’s default value (which is initially `-1`, and can be changed with `setDefaultValue`), this function will do nothing.

    Parameters:

      - point (int) – The point.

      - value (int) – The point value.

    Return type:

      None

    See also

    `getValue`, `setDefaultValue`, `DMLabelSetValue`

    Source code at petsc4py/PETSc/DMLabel.pyx:112

  stratumHasPoint(value, point)

    Return whether the stratum contains a point.

    Not collective.

    Parameters:

      - value (int) – The stratum value.

      - point (int) – The point.

    Return type:

      bool

    See also

    `DMLabelStratumHasPoint`

    Source code at petsc4py/PETSc/DMLabel.pyx:303

  view(viewer=None)

    View the label.

    Collective.

    Parameters:

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

    Return type:

      None

    See also

    `DMLabelView`

    Source code at petsc4py/PETSc/DMLabel.pyx:21

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