Date: 2026-03-31T13:22:59+00:00

Actual source code: slepcsc.h

      1: /*
      2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      4:    Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain

      6:    This file is part of SLEPc.
      7:    SLEPc is distributed under a 2-clause BSD license (see LICENSE).
      8:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      9: */
     10: /*
     11:    Sorting criterion for various solvers
     12: */

     14: #pragma once

     16: #include <slepcsys.h>
     17: #include <slepcrgtypes.h>

     19: /* SUBMANSEC = Sys */

     21: /*S
     22:    SlepcEigenvalueComparisonFn - A prototype of an eigenvalue comparison function that would
     23:    be passed to `EPSSetEigenvalueComparison()` and analogue functions in other solver types.

     25:    Calling Sequence:
     26: +  ar     - real part of the 1st eigenvalue
     27: .  ai     - imaginary part of the 1st eigenvalue
     28: .  br     - real part of the 2nd eigenvalue
     29: .  bi     - imaginary part of the 2nd eigenvalue
     30: .  res    - [output] result of comparison
     31: -  ctx    - [optional] user-defined context for private data for the
     32:             eigenvalue comparison routine (may be `NULL`)

     34:    Note:
     35:    The return value `res` can be
     36: +  negative - if the 1st value is preferred to the 2st one
     37: .  zero     - if both values are equally preferred
     38: -  positive - if the 2st value is preferred to the 1st one

     40:    Level: advanced

     42: .seealso: `SlepcSC`, `EPSSetEigenvalueComparison()`
     43: S*/
     44: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode SlepcEigenvalueComparisonFn(PetscScalar ar,PetscScalar ai,PetscScalar br,PetscScalar bi,PetscInt *res,PetscCtx ctx);

     46: /*S
     47:    SlepcArbitrarySelectionFn - A prototype of an arbitrary selection function that would be
     48:    passed to `EPSSetArbitrarySelection()` and analogue functions in other solver types.

     50:    Calling Sequence:
     51: +  er     - real part of the current eigenvalue approximation
     52: .  ei     - imaginary part of the current eigenvalue approximation
     53: .  xr     - real part of the current eigenvector approximation
     54: .  xi     - imaginary part of the current eigenvector approximation
     55: .  rr     - result of evaluation (real part)
     56: .  ri     - result of evaluation (imaginary part)
     57: -  ctx    - [optional] user-defined context for private data for the
     58:             arbitrary selection routine (may be `NULL`)

     60:    Notes:
     61:    Given a scalar and a vector (usually an approximate eigenvalue and the corresponding
     62:    eigenvector) this function evaluates the result `rr`, `ri` which is the value that
     63:    will be used in a subsequent sorting.

     65:    This evaluation function is collective, that is, all processes call it and
     66:    it can use collective operations; furthermore, the computed result must
     67:    be the same in all processes.

     69:    The result is expressed as a complex number so that it is possible to
     70:    use the standard eigenvalue sorting functions, but normally only `rr` is used.
     71:    Set `ri` to zero unless it is meaningful in your application.

     73:    Level: advanced

     75: .seealso: `SlepcSC`, `SlepcEigenvalueComparisonFn`, `EPSSetArbitrarySelection()`
     76: S*/
     77: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode SlepcArbitrarySelectionFn(PetscScalar er,PetscScalar ei,Vec xr,Vec xi,PetscScalar *rr,PetscScalar *ri,PetscCtx ctx);

     79: /*S
     80:    SlepcSC - Data structure (a C `struct`) for storing information about the sorting
     81:    criterion used by different eigensolver objects.

     83:    Notes:
     84:    The `SlepcSC` structure contains a mapping function and a comparison
     85:    function (with associated contexts).
     86:    The mapping function usually calls the backtransform operation of an `ST` object.
     87:    An optional region can also be used to give higher priority to values inside it.

     89:    The member `comparison` typically points to a predefined comparison function
     90:    such as `SlepcCompareLargestMagnitude`, though it can also be user-defined.

     92:    Fortran Note:
     93:    Fortran usage is not supported.

     95:    Developer Notes:
     96:    This is a low-level data structure common to all solver classes for the task of
     97:    sorting a list of scalars, typically computed eigenvalues.

     99:    The main operation associated to this data structure is `SlepcSCCompare()` to
    100:    compare two scalar values, which in turn is called from `SlepcSortEigenvalues()`.

    102:    Level: developer

    104: .seealso: `SlepcEigenvalueComparisonFn`, `SlepcSortEigenvalues()`, `SlepcSCCompare()`
    105: S*/
    106: struct _n_SlepcSC {
    107:   /* map values before sorting, typically a call to STBackTransform (mapctx=ST) */
    108:   PetscErrorCode (*map)(PetscObject,PetscInt,PetscScalar*,PetscScalar*);
    109:   PetscObject    mapobj;
    110:   /* comparison function such as SlepcCompareLargestMagnitude */
    111:   SlepcEigenvalueComparisonFn *comparison;
    112:   void           *comparisonctx;
    113:   /* optional region for filtering */
    114:   RG             rg;
    115: };
    116: typedef struct _n_SlepcSC* SlepcSC;

    118: SLEPC_EXTERN PetscErrorCode SlepcSCCompare(SlepcSC,PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*);
    119: SLEPC_EXTERN PetscErrorCode SlepcSortEigenvalues(SlepcSC,PetscInt,PetscScalar[],PetscScalar[],PetscInt[]);
    120: SLEPC_EXTERN PetscErrorCode SlepcSortEigenvaluesSpecial(SlepcSC,PetscInt,PetscScalar[],PetscScalar[],PetscInt[]);

    122: SLEPC_EXTERN PetscErrorCode SlepcMap_ST(PetscObject,PetscInt,PetscScalar*,PetscScalar*);

    124: SLEPC_EXTERN PetscErrorCode SlepcCompareLargestMagnitude(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,PetscCtx);
    125: SLEPC_EXTERN PetscErrorCode SlepcCompareSmallestMagnitude(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,PetscCtx);
    126: SLEPC_EXTERN PetscErrorCode SlepcCompareLargestReal(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,PetscCtx);
    127: SLEPC_EXTERN PetscErrorCode SlepcCompareSmallestReal(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,PetscCtx);
    128: SLEPC_EXTERN PetscErrorCode SlepcCompareLargestImaginary(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,PetscCtx);
    129: SLEPC_EXTERN PetscErrorCode SlepcCompareSmallestImaginary(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,PetscCtx);
    130: SLEPC_EXTERN PetscErrorCode SlepcCompareTargetMagnitude(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,PetscCtx);
    131: SLEPC_EXTERN PetscErrorCode SlepcCompareTargetReal(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,PetscCtx);
    132: SLEPC_EXTERN PetscErrorCode SlepcCompareTargetImaginary(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,PetscCtx);
    133: SLEPC_EXTERN PetscErrorCode SlepcCompareSmallestPosReal(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,PetscCtx);