Skip to main content
`Ctrl`+`K`

# slepc4py.SLEPc.RG

class slepc4py.SLEPc.RG

  Bases: `Object`

  Region.

  The `RG` package provides a way to define a region of the complex plane. This is used in various eigensolvers to specify where the wanted eigenvalues are located.

  Enumerations

  `QuadRule` | RG quadrature rule for contour integral methods.
  `Type` | RG type.

  Methods Summary

  `appendOptionsPrefix`([prefix]) | Append to the prefix used for searching for all RG options in the database.
  `canUseConjugates`([realmats]) | Half of integration points can be avoided (use their conjugates).
  `checkInside`(a) | Determine if a set of given points are inside the region or not.
  `computeBoundingBox`() | Compute box containing the region.
  `computeContour`(n) | Compute points on the contour of the region.
  `computeQuadrature`(quad, n) | Compute the values of the parameters used in a quadrature rule.
  `create`([comm]) | Create the RG object.
  `destroy`() | Destroy the RG object.
  `getComplement`() | Get the flag indicating whether the region is complemented or not.
  `getEllipseParameters`() | Get the parameters that define the ellipse region.
  `getIntervalEndpoints`() | Get the parameters that define the interval region.
  `getOptionsPrefix`() | Get the prefix used for searching for all RG options in the database.
  `getPolygonVertices`() | Get the parameters that define the interval region.
  `getRingParameters`() | Get the parameters that define the ring region.
  `getScale`() | Get the scaling factor.
  `getType`() | Get the RG type of this object.
  `isAxisymmetric`([vertical]) | Determine if the region is axisymmetric.
  `isTrivial`() | Tell whether it is the trivial region (whole complex plane).
  `setComplement`([comp]) | Set a flag to indicate that the region is the complement of the specified one.
  `setEllipseParameters`(center, radius[, vscale]) | Set the parameters defining the ellipse region.
  `setFromOptions`() | Set RG options from the options database.
  `setIntervalEndpoints`(a, b, c, d) | Set the parameters defining the interval region.
  `setOptionsPrefix`([prefix]) | Set the prefix used for searching for all RG options in the database.
  `setPolygonVertices`(v) | Set the vertices that define the polygon region.
  `setRingParameters`(center, radius, vscale, ...) | Set the parameters defining the ring region.
  `setScale`([sfactor]) | Set the scaling factor to be used.
  `setType`(rg_type) | Set the type for the RG object.
  `view`([viewer]) | Print the RG data structure.

  Attributes Summary

  `complement` | If the region is the complement of the specified one.
  `scale` | The scaling factor to be used.

  Methods Documentation

  appendOptionsPrefix(prefix=None)

    Append to the prefix used for searching for all RG options in the database.

    Logically collective.

    Parameters:

      prefix (str | None) – The prefix string to prepend to all RG option requests.

    Return type:

      None

    See also

    `setOptionsPrefix`, `getOptionsPrefix`, `RGAppendOptionsPrefix`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:190 <slepc4py/SLEPc/RG.pyx#L190>`

  canUseConjugates(realmats=True)

    Half of integration points can be avoided (use their conjugates).

    Not collective.

    Used in contour integral methods to determine whether half of integration points can be avoided (use their conjugates).

    Parameters:

      realmats (bool) – `True` if the problem matrices are real.

    Returns:

      Whether it is possible to use conjugates.

    Return type:

      `bool`

    Notes

    If some integration points are the conjugates of other points, then the associated computational cost can be saved. This depends on the problem matrices being real and also the region being symmetric with respect to the horizontal axis. The result is `false` if using real arithmetic or in the case of a flat region (height equal to zero).

    See also

    `isAxisymmetric`, `RGCanUseConjugates`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:458 <slepc4py/SLEPc/RG.pyx#L458>`

  checkInside(a)

    Determine if a set of given points are inside the region or not.

    Not collective.

    Parameters:

      a (Sequence[complex]) – The coordinates of the points.

    Returns:

      Computed result for each point (1=inside, 0=on the contour, -1=outside).

    Return type:

      `ArrayInt`

    Notes

    If a scaling factor was set, the points are scaled before checking.

    See also

    `setScale`, `setComplement`, `RGCheckInside`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:355 <slepc4py/SLEPc/RG.pyx#L355>`

  computeBoundingBox()

    Compute box containing the region.

    Not collective.

    Determine the endpoints of a rectangle in the complex plane that contains the region.

    Returns:

      - a (`float`) – The left endpoint of the bounding box in the real axis.

      - b (`float`) – The right endpoint of the bounding box in the real axis.

      - c (`float`) – The bottom endpoint of the bounding box in the imaginary axis.

      - d (`float`) – The top endpoint of the bounding box in the imaginary axis.

    Return type:

      tuple[float, float, float, float]

    See also

    `computeContour`, `setScale`, `RGComputeBoundingBox`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:430 <slepc4py/SLEPc/RG.pyx#L430>`

  computeContour(n)

    Compute points on the contour of the region.

    Not collective.

    Compute the coordinates of several points lying on the contour of the region.

    Parameters:

      n (int) – The number of points to compute.

    Returns:

      Computed points.

    Return type:

      `list` of `complex`

    See also

    `computeBoundingBox`, `setScale`, `RGComputeContour`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:395 <slepc4py/SLEPc/RG.pyx#L395>`

  computeQuadrature(quad, n)

    Compute the values of the parameters used in a quadrature rule.

    Not collective.

    Compute the values of the parameters used in a quadrature rule for a contour integral around the boundary of the region.

    Parameters:

      - quad (QuadRule) – The type of quadrature.

      - n (int) – The number of quadrature points to compute.

    Returns:

      - z (`ArrayScalar`) – Quadrature points.

      - zn (`ArrayScalar`) – Normalized quadrature points.

      - w (`ArrayScalar`) – Quadrature weights.

    Return type:

      tuple[ArrayScalar, ArrayScalar, ArrayScalar]

    Notes

    In complex scalars, the values returned in `z` are often the same as those computed by `computeContour()`, but this is not the case in real scalars where all output arguments are real.

    The computed values change for different quadrature rules.

    See also

    `computeContour`, `RGComputeQuadrature`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:494 <slepc4py/SLEPc/RG.pyx#L494>`

  create(comm=None)

    Create the RG object.

    Collective.

    Parameters:

      comm (Comm | None) – MPI communicator; if not provided, it defaults to all processes.

    Return type:

      Self

    See also

    `RGCreate`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:87 <slepc4py/SLEPc/RG.pyx#L87>`

  destroy()

    Destroy the RG object.

    Collective.

    See also

    `RGDestroy`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:73 <slepc4py/SLEPc/RG.pyx#L73>`

    Return type:

      Self

  getComplement()

    Get the flag indicating whether the region is complemented or not.

    Not collective.

    Returns:

      Whether the region is complemented or not.

    Return type:

      `bool`

    See also

    `setComplement`, `RGGetComplement`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:277 <slepc4py/SLEPc/RG.pyx#L277>`

  getEllipseParameters()

    Get the parameters that define the ellipse region.

    Not collective.

    Returns:

      - center (`Scalar`) – The center.

      - radius (`float`) – The radius.

      - vscale (`float`) – The vertical scale.

    Return type:

      tuple[Scalar, float, float]

    See also

    `setEllipseParameters`, `RGEllipseGetParameters`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:572 <slepc4py/SLEPc/RG.pyx#L572>`

  getIntervalEndpoints()

    Get the parameters that define the interval region.

    Not collective.

    Returns:

      - a (`float`) – The left endpoint in the real axis.

      - b (`float`) – The right endpoint in the real axis.

      - c (`float`) – The bottom endpoint in the imaginary axis.

      - d (`float`) – The top endpoint in the imaginary axis.

    Return type:

      tuple[float, float, float, float]

    See also

    `setIntervalEndpoints`, `RGIntervalGetEndpoints`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:634 <slepc4py/SLEPc/RG.pyx#L634>`

  getOptionsPrefix()

    Get the prefix used for searching for all RG options in the database.

    Not collective.

    Returns:

      The prefix string set for this RG object.

    Return type:

      `str`

    See also

    `setOptionsPrefix`, `appendOptionsPrefix`, `RGGetOptionsPrefix`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:171 <slepc4py/SLEPc/RG.pyx#L171>`

  getPolygonVertices()

    Get the parameters that define the interval region.

    Not collective.

    Returns:

      The vertices.

    Return type:

      `ArrayComplex`

    See also

    `setPolygonVertices`, `RGPolygonGetVertices`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:690 <slepc4py/SLEPc/RG.pyx#L690>`

  getRingParameters()

    Get the parameters that define the ring region.

    Not collective.

    Returns:

      - center (`Scalar`) – The center.

      - radius (`float`) – The radius.

      - vscale (`float`) – The vertical scale.

      - start_ang (`float`) – The right-hand side angle.

      - end_ang (`float`) – The left-hand side angle.

      - width (`float`) – The width of the ring.

    Return type:

      tuple[Scalar, float, float, float, float, float]

    See also

    `setRingParameters`, `RGRingGetParameters`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:775 <slepc4py/SLEPc/RG.pyx#L775>`

  getScale()

    Get the scaling factor.

    Not collective.

    Returns:

      The scaling factor.

    Return type:

      `float`

    See also

    `setScale`, `RGGetScale`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:336 <slepc4py/SLEPc/RG.pyx#L336>`

  getType()

    Get the RG type of this object.

    Not collective.

    Returns:

      The region type currently being used.

    Return type:

      `str`

    See also

    `setType`, `RGGetType`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:127 <slepc4py/SLEPc/RG.pyx#L127>`

  isAxisymmetric(vertical=False)

    Determine if the region is axisymmetric.

    Not collective.

    Determine if the region is symmetric with respect to the real or imaginary axis.

    Parameters:

      vertical (bool) – `True` if symmetry must be checked against the vertical axis.

    Returns:

      `True` if the region is axisymmetric.

    Return type:

      `bool`

    See also

    `canUseConjugates`, `RGIsAxisymmetric`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:249 <slepc4py/SLEPc/RG.pyx#L249>`

  isTrivial()

    Tell whether it is the trivial region (whole complex plane).

    Not collective.

    Returns:

      `True` if the region is equal to the whole complex plane, e.g., an interval region with all four endpoints unbounded or an ellipse with infinite radius.

    Return type:

      `bool`

    See also

    `checkInside`, `RGIsTrivial`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:228 <slepc4py/SLEPc/RG.pyx#L228>`

  setComplement(comp=True)

    Set a flag to indicate that the region is the complement of the specified one.

    Logically collective.

    Parameters:

      comp (bool) – Activate/deactivate the complementation of the region.

    Return type:

      None

    See also

    `getComplement`, `RGSetComplement`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:296 <slepc4py/SLEPc/RG.pyx#L296>`

  setEllipseParameters(center, radius, vscale=None)

    Set the parameters defining the ellipse region.

    Logically collective.

    Parameters:

      - center (Scalar) – The center.

      - radius (float) – The radius.

      - vscale (float | None) – The vertical scale.

    Return type:

      None

    Notes

    When PETSc is built with real scalars, the center is restricted to a real value.

    See also

    `getEllipseParameters`, `RGEllipseSetParameters`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:542 <slepc4py/SLEPc/RG.pyx#L542>`

  setFromOptions()

    Set RG options from the options database.

    Collective.

    Notes

    To see all options, run your program with the `-help` option.

    See also

    `setOptionsPrefix`, `RGSetFromOptions`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:209 <slepc4py/SLEPc/RG.pyx#L209>`

    Return type:

      None

  setIntervalEndpoints(a, b, c, d)

    Set the parameters defining the interval region.

    Logically collective.

    Parameters:

      - a (float) – The left endpoint in the real axis.

      - b (float) – The right endpoint in the real axis.

      - c (float) – The bottom endpoint in the imaginary axis.

      - d (float) – The top endpoint in the imaginary axis.

    Return type:

      None

    Notes

    The region is defined as \([a,b] x [c,d]\). Particular cases are an interval on the real axis (\(c=d=0\)), similarly for the imaginary axis (\(a=b=0\)), the whole complex plane (\(a=-\infty,b=\infty,c=-\infty,d=\infty\)), and so on.

    When PETSc is built with real scalars, the region must be symmetric with respect to the real axis.

    See also

    `getIntervalEndpoints`, `RGIntervalSetEndpoints`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:597 <slepc4py/SLEPc/RG.pyx#L597>`

  setOptionsPrefix(prefix=None)

    Set the prefix used for searching for all RG options in the database.

    Logically collective.

    Parameters:

      prefix (str | None) – The prefix string to prepend to all RG option requests.

    Return type:

      None

    Notes

    A hyphen (`-`) must NOT be given at the beginning of the prefix name. The first character of all runtime options is AUTOMATICALLY the hyphen.

    See also

    `appendOptionsPrefix`, `getOptionsPrefix`, `RGGetOptionsPrefix`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:146 <slepc4py/SLEPc/RG.pyx#L146>`

  setPolygonVertices(v)

    Set the vertices that define the polygon region.

    Logically collective.

    Parameters:

      v (Sequence[float] | Sequence[Scalar]) – The vertices.

    Return type:

      None

    See also

    `getPolygonVertices`, `RGPolygonSetVertices`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:662 <slepc4py/SLEPc/RG.pyx#L662>`

  setRingParameters(center, radius, vscale, start_ang, end_ang, width)

    Set the parameters defining the ring region.

    Logically collective.

    Parameters:

      - center (Scalar) – The center.

      - radius (float) – The radius.

      - vscale (float) – The vertical scale.

      - start_ang (float) – The right-hand side angle.

      - end_ang (float) – The left-hand side angle.

      - width (float) – The width of the ring.

    Return type:

      None

    Notes

    The values of `center`, `radius` and `vscale` have the same meaning as in the ellipse region. The `start_ang` and `end_ang` define the span of the ring (by default it is the whole ring), while the `width` is the separation between the two concentric ellipses (above and below the radius by `width/2`).

    The start and end angles are expressed as a fraction of the circumference. The allowed range is \([0,\dots,1]\), with `0` corresponding to 0 radians, `0.25` to \(\pi/2\) radians, and so on. It is allowed to have `start_ang` > `end_ang`, in which case the ring region crosses over the zero angle.

    When PETSc is built with real scalars, the center is restricted to a real value, and the start and end angles must be such that the region is symmetric with respect to the real axis.

    See also

    `getRingParameters`, `RGRingSetParameters`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:716 <slepc4py/SLEPc/RG.pyx#L716>`

  setScale(sfactor=None)

    Set the scaling factor to be used.

    Logically collective.

    Set the scaling factor to be used when checking that a point is inside the region and when computing the contour.

    Parameters:

      sfactor (float) – The scaling factor (default=1).

    Return type:

      None

    See also

    `getScale`, `checkInside`, `computeContour`, `RGSetScale`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:314 <slepc4py/SLEPc/RG.pyx#L314>`

  setType(rg_type)

    Set the type for the RG object.

    Logically collective.

    Parameters:

      rg_type (Type | str) – The region type to be used.

    Return type:

      None

    See also

    `getType`, `RGSetType`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:108 <slepc4py/SLEPc/RG.pyx#L108>`

  view(viewer=None)

    Print the RG data structure.

    Collective.

    Parameters:

      viewer (Viewer | None) – Visualization context; if not provided, the standard output is used.

    Return type:

      None

    See also

    `RGView`

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:54 <slepc4py/SLEPc/RG.pyx#L54>`

  Attributes Documentation

  complement

    If the region is the complement of the specified one.

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:811 <slepc4py/SLEPc/RG.pyx#L811>`

  scale

    The scaling factor to be used.

    :sources:`Source code at slepc4py/SLEPc/RG.pyx:818 <slepc4py/SLEPc/RG.pyx#L818>`

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