Date: 2024-10-28T09:13:09+00:00

Actual source code: slepcsc.h
slepc-3.22.1 2024-10-28
Report Typos and Errors

      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 be passed to EPSSetEigenvalueComparison() and analogue functions in other solver types

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

     33:   Level: advanced

     35: .seealso: EPSSetEigenvalueComparison()
     36: S*/
     37: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SlepcEigenvalueComparisonFn)(PetscScalar ar,PetscScalar ai,PetscScalar br,PetscScalar bi,PetscInt *res,void *ctx);

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

     42:   Calling Sequence:
     43: +   er     - real part of the current eigenvalue approximation
     44: .   ei     - imaginary part of the current eigenvalue approximation
     45: .   xr     - real part of the current eigenvector approximation
     46: .   xi     - imaginary part of the current eigenvector approximation
     47: .   rr     - result of evaluation (real part)
     48: .   ri     - result of evaluation (imaginary part)
     49: -   ctx    - [optional] user-defined context for private data for the
     50:              arbitrary selection routine (may be NULL)

     52:   Level: advanced

     54: .seealso: EPSSetArbitrarySelection()
     55: S*/
     56: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SlepcArbitrarySelectionFn)(PetscScalar er,PetscScalar ei,Vec xr,Vec xi,PetscScalar *rr,PetscScalar *ri,void *ctx);

     58: /*S
     59:     SlepcSC - Data structure (C struct) for storing information about
     60:         the sorting criterion used by different eigensolver objects.

     62:    Notes:
     63:    The SlepcSC structure contains a mapping function and a comparison
     64:    function (with associated contexts).
     65:    The mapping function usually calls ST's backtransform.
     66:    An optional region can also be used to give higher priority to values inside it.

     68:    The comparison function must have the following calling sequence

     70: $  comparison(PetscScalar ar,PetscScalar ai,PetscScalar br,PetscScalar bi,PetscInt *res,void *ctx)

     72: +  ar  - real part of the 1st eigenvalue
     73: .  ai  - imaginary part of the 1st eigenvalue
     74: .  br  - real part of the 2nd eigenvalue
     75: .  bi  - imaginary part of the 2nd eigenvalue
     76: .  res - result of comparison
     77: -  ctx - optional context, stored in comparisonctx

     79:    The returning parameter 'res' can be
     80: +  negative - if the 1st value is preferred to the 2st one
     81: .  zero     - if both values are equally preferred
     82: -  positive - if the 2st value is preferred to the 1st one

     84:    Fortran usage is not supported.

     86:    Level: developer

     88: .seealso: SlepcSCCompare()
     89: S*/
     90: struct _n_SlepcSC {
     91:   /* map values before sorting, typically a call to STBackTransform (mapctx=ST) */
     92:   PetscErrorCode (*map)(PetscObject,PetscInt,PetscScalar*,PetscScalar*);
     93:   PetscObject    mapobj;
     94:   /* comparison function such as SlepcCompareLargestMagnitude */
     95:   SlepcEigenvalueComparisonFn *comparison;
     96:   void           *comparisonctx;
     97:   /* optional region for filtering */
     98:   RG             rg;
     99: };
    100: typedef struct _n_SlepcSC* SlepcSC;

    102: SLEPC_EXTERN PetscErrorCode SlepcSCCompare(SlepcSC,PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*);
    103: SLEPC_EXTERN PetscErrorCode SlepcSortEigenvalues(SlepcSC,PetscInt n,PetscScalar *eigr,PetscScalar *eigi,PetscInt *perm);

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

    107: SLEPC_EXTERN PetscErrorCode SlepcCompareLargestMagnitude(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*);
    108: SLEPC_EXTERN PetscErrorCode SlepcCompareSmallestMagnitude(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*);
    109: SLEPC_EXTERN PetscErrorCode SlepcCompareLargestReal(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*);
    110: SLEPC_EXTERN PetscErrorCode SlepcCompareSmallestReal(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*);
    111: SLEPC_EXTERN PetscErrorCode SlepcCompareLargestImaginary(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*);
    112: SLEPC_EXTERN PetscErrorCode SlepcCompareSmallestImaginary(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*);
    113: SLEPC_EXTERN PetscErrorCode SlepcCompareTargetMagnitude(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*);
    114: SLEPC_EXTERN PetscErrorCode SlepcCompareTargetReal(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*);
    115: #if defined(PETSC_USE_COMPLEX)
    116: SLEPC_EXTERN PetscErrorCode SlepcCompareTargetImaginary(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*);
    117: #endif
    118: SLEPC_EXTERN PetscErrorCode SlepcCompareSmallestPosReal(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*);