LCOV - code coverage report
Current view: top level - sys/classes/st/interface - stfunc.c (source / functions) Hit Total Coverage
Test: coverage.info Lines: 257 285 90.2 %
Date: 2019-11-15 09:58:42 Functions: 23 26 88.5 %

          Line data    Source code
       1             : /*
       2             :    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
       3             :    SLEPc - Scalable Library for Eigenvalue Problem Computations
       4             :    Copyright (c) 2002-2019, Universitat Politecnica de Valencia, Spain
       5             : 
       6             :    This file is part of SLEPc.
       7             :    SLEPc is distributed under a 2-clause BSD license (see LICENSE).
       8             :    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
       9             : */
      10             : /*
      11             :    The ST interface routines, callable by users
      12             : */
      13             : 
      14             : #include <slepc/private/stimpl.h>            /*I "slepcst.h" I*/
      15             : 
      16             : PetscClassId     ST_CLASSID = 0;
      17             : PetscLogEvent    ST_SetUp = 0,ST_Apply = 0,ST_ApplyTranspose = 0,ST_MatSetUp = 0,ST_MatMult = 0,ST_MatMultTranspose = 0,ST_MatSolve = 0,ST_MatSolveTranspose = 0;
      18             : static PetscBool STPackageInitialized = PETSC_FALSE;
      19             : 
      20             : const char *STMatModes[] = {"COPY","INPLACE","SHELL","STMatMode","ST_MATMODE_",0};
      21             : 
      22             : /*@C
      23             :    STFinalizePackage - This function destroys everything in the Slepc interface
      24             :    to the ST package. It is called from SlepcFinalize().
      25             : 
      26             :    Level: developer
      27             : 
      28             : .seealso: SlepcFinalize()
      29             : @*/
      30         516 : PetscErrorCode STFinalizePackage(void)
      31             : {
      32             :   PetscErrorCode ierr;
      33             : 
      34         516 :   PetscFunctionBegin;
      35         516 :   ierr = PetscFunctionListDestroy(&STList);CHKERRQ(ierr);
      36         516 :   STPackageInitialized = PETSC_FALSE;
      37         516 :   STRegisterAllCalled  = PETSC_FALSE;
      38         516 :   PetscFunctionReturn(0);
      39             : }
      40             : 
      41             : /*@C
      42             :    STInitializePackage - This function initializes everything in the ST package.
      43             :    It is called from PetscDLLibraryRegister() when using dynamic libraries, and
      44             :    on the first call to STCreate() when using static libraries.
      45             : 
      46             :    Level: developer
      47             : 
      48             : .seealso: SlepcInitialize()
      49             : @*/
      50        3667 : PetscErrorCode STInitializePackage(void)
      51             : {
      52             :   char           logList[256];
      53             :   PetscBool      opt,pkg;
      54             :   PetscErrorCode ierr;
      55             : 
      56        3667 :   PetscFunctionBegin;
      57        3667 :   if (STPackageInitialized) PetscFunctionReturn(0);
      58         516 :   STPackageInitialized = PETSC_TRUE;
      59             :   /* Register Classes */
      60         516 :   ierr = PetscClassIdRegister("Spectral Transform",&ST_CLASSID);CHKERRQ(ierr);
      61             :   /* Register Constructors */
      62         516 :   ierr = STRegisterAll();CHKERRQ(ierr);
      63             :   /* Register Events */
      64         516 :   ierr = PetscLogEventRegister("STSetUp",ST_CLASSID,&ST_SetUp);CHKERRQ(ierr);
      65         516 :   ierr = PetscLogEventRegister("STApply",ST_CLASSID,&ST_Apply);CHKERRQ(ierr);
      66         516 :   ierr = PetscLogEventRegister("STApplyTranspose",ST_CLASSID,&ST_ApplyTranspose);CHKERRQ(ierr);
      67         516 :   ierr = PetscLogEventRegister("STMatSetUp",ST_CLASSID,&ST_MatSetUp);CHKERRQ(ierr);
      68         516 :   ierr = PetscLogEventRegister("STMatMult",ST_CLASSID,&ST_MatMult);CHKERRQ(ierr);
      69         516 :   ierr = PetscLogEventRegister("STMatMultTranspose",ST_CLASSID,&ST_MatMultTranspose);CHKERRQ(ierr);
      70         516 :   ierr = PetscLogEventRegister("STMatSolve",ST_CLASSID,&ST_MatSolve);CHKERRQ(ierr);
      71         516 :   ierr = PetscLogEventRegister("STMatSolveTranspose",ST_CLASSID,&ST_MatSolveTranspose);CHKERRQ(ierr);
      72             :   /* Process info exclusions */
      73         516 :   ierr = PetscOptionsGetString(NULL,NULL,"-info_exclude",logList,sizeof(logList),&opt);CHKERRQ(ierr);
      74         516 :   if (opt) {
      75           8 :     ierr = PetscStrInList("st",logList,',',&pkg);CHKERRQ(ierr);
      76           8 :     if (pkg) { ierr = PetscInfoDeactivateClass(ST_CLASSID);CHKERRQ(ierr); }
      77             :   }
      78             :   /* Process summary exclusions */
      79         516 :   ierr = PetscOptionsGetString(NULL,NULL,"-log_exclude",logList,sizeof(logList),&opt);CHKERRQ(ierr);
      80         516 :   if (opt) {
      81           8 :     ierr = PetscStrInList("st",logList,',',&pkg);CHKERRQ(ierr);
      82           8 :     if (pkg) { ierr = PetscLogEventDeactivateClass(ST_CLASSID);CHKERRQ(ierr); }
      83             :   }
      84             :   /* Register package finalizer */
      85         516 :   ierr = PetscRegisterFinalize(STFinalizePackage);CHKERRQ(ierr);
      86         516 :   PetscFunctionReturn(0);
      87             : }
      88             : 
      89             : /*@
      90             :    STReset - Resets the ST context to the initial state (prior to setup)
      91             :    and destroys any allocated Vecs and Mats.
      92             : 
      93             :    Collective on st
      94             : 
      95             :    Input Parameter:
      96             : .  st - the spectral transformation context
      97             : 
      98             :    Level: advanced
      99             : 
     100             : .seealso: STDestroy()
     101             : @*/
     102        1235 : PetscErrorCode STReset(ST st)
     103             : {
     104             :   PetscErrorCode ierr;
     105             : 
     106        1235 :   PetscFunctionBegin;
     107        1235 :   if (st) PetscValidHeaderSpecific(st,ST_CLASSID,1);
     108        1235 :   if (!st) PetscFunctionReturn(0);
     109        1235 :   if (st->ops->reset) { ierr = (*st->ops->reset)(st);CHKERRQ(ierr); }
     110        1235 :   if (st->ksp) { ierr = KSPReset(st->ksp);CHKERRQ(ierr); }
     111        1235 :   ierr = MatDestroyMatrices(PetscMax(2,st->nmat),&st->T);CHKERRQ(ierr);
     112        1235 :   ierr = MatDestroyMatrices(PetscMax(2,st->nmat),&st->A);CHKERRQ(ierr);
     113        1235 :   ierr = PetscFree(st->Astate);CHKERRQ(ierr);
     114        1235 :   ierr = MatDestroy(&st->P);CHKERRQ(ierr);
     115        1235 :   ierr = VecDestroyVecs(st->nwork,&st->work);CHKERRQ(ierr);
     116        1235 :   st->nwork = 0;
     117        1235 :   ierr = VecDestroy(&st->wb);CHKERRQ(ierr);
     118        1235 :   ierr = VecDestroy(&st->D);CHKERRQ(ierr);
     119        1235 :   st->state = ST_STATE_INITIAL;
     120        1235 :   PetscFunctionReturn(0);
     121             : }
     122             : 
     123             : /*@
     124             :    STDestroy - Destroys ST context that was created with STCreate().
     125             : 
     126             :    Collective on st
     127             : 
     128             :    Input Parameter:
     129             : .  st - the spectral transformation context
     130             : 
     131             :    Level: beginner
     132             : 
     133             : .seealso: STCreate(), STSetUp()
     134             : @*/
     135         574 : PetscErrorCode STDestroy(ST *st)
     136             : {
     137             :   PetscErrorCode ierr;
     138             : 
     139         574 :   PetscFunctionBegin;
     140         574 :   if (!*st) PetscFunctionReturn(0);
     141         572 :   PetscValidHeaderSpecific(*st,ST_CLASSID,1);
     142         572 :   if (--((PetscObject)(*st))->refct > 0) { *st = 0; PetscFunctionReturn(0); }
     143         570 :   ierr = STReset(*st);CHKERRQ(ierr);
     144         570 :   if ((*st)->ops->destroy) { ierr = (*(*st)->ops->destroy)(*st);CHKERRQ(ierr); }
     145         570 :   ierr = KSPDestroy(&(*st)->ksp);CHKERRQ(ierr);
     146         570 :   ierr = PetscHeaderDestroy(st);CHKERRQ(ierr);
     147         570 :   PetscFunctionReturn(0);
     148             : }
     149             : 
     150             : /*@
     151             :    STCreate - Creates a spectral transformation context.
     152             : 
     153             :    Collective
     154             : 
     155             :    Input Parameter:
     156             : .  comm - MPI communicator
     157             : 
     158             :    Output Parameter:
     159             : .  st - location to put the spectral transformation context
     160             : 
     161             :    Level: beginner
     162             : 
     163             : .seealso: STSetUp(), STApply(), STDestroy(), ST
     164             : @*/
     165         570 : PetscErrorCode STCreate(MPI_Comm comm,ST *newst)
     166             : {
     167             :   PetscErrorCode ierr;
     168             :   ST             st;
     169             : 
     170         570 :   PetscFunctionBegin;
     171         570 :   PetscValidPointer(newst,2);
     172         570 :   *newst = 0;
     173         570 :   ierr = STInitializePackage();CHKERRQ(ierr);
     174         570 :   ierr = SlepcHeaderCreate(st,ST_CLASSID,"ST","Spectral Transformation","ST",comm,STDestroy,STView);CHKERRQ(ierr);
     175             : 
     176         570 :   st->A            = NULL;
     177         570 :   st->nmat         = 0;
     178         570 :   st->sigma        = 0.0;
     179         570 :   st->defsigma     = 0.0;
     180         570 :   st->matmode      = ST_MATMODE_COPY;
     181         570 :   st->str          = DIFFERENT_NONZERO_PATTERN;
     182         570 :   st->transform    = PETSC_FALSE;
     183         570 :   st->D            = NULL;
     184             : 
     185         570 :   st->ksp          = NULL;
     186         570 :   st->usesksp      = PETSC_FALSE;
     187         570 :   st->nwork        = 0;
     188         570 :   st->work         = NULL;
     189         570 :   st->wb           = NULL;
     190         570 :   st->state        = ST_STATE_INITIAL;
     191         570 :   st->Astate       = NULL;
     192         570 :   st->T            = NULL;
     193         570 :   st->P            = NULL;
     194         570 :   st->sigma_set    = PETSC_FALSE;
     195         570 :   st->data         = NULL;
     196             : 
     197         570 :   *newst = st;
     198         570 :   PetscFunctionReturn(0);
     199             : }
     200             : 
     201             : /*@
     202             :    STSetMatrices - Sets the matrices associated with the eigenvalue problem.
     203             : 
     204             :    Collective on st
     205             : 
     206             :    Input Parameters:
     207             : +  st - the spectral transformation context
     208             : .  n  - number of matrices in array A
     209             : -  A  - the array of matrices associated with the eigensystem
     210             : 
     211             :    Notes:
     212             :    It must be called before STSetUp(). If it is called again after STSetUp() then
     213             :    the ST object is reset.
     214             : 
     215             :    Level: intermediate
     216             : 
     217             : .seealso: STGetMatrix(), STGetNumMatrices(), STSetUp(), STReset()
     218             :  @*/
     219         630 : PetscErrorCode STSetMatrices(ST st,PetscInt n,Mat A[])
     220             : {
     221             :   PetscInt       i;
     222             :   PetscErrorCode ierr;
     223         630 :   PetscBool      same=PETSC_TRUE;
     224             : 
     225         630 :   PetscFunctionBegin;
     226         630 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     227        1260 :   PetscValidLogicalCollectiveInt(st,n,2);
     228         630 :   if (n <= 0) SETERRQ1(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"Must have one or more matrices, you have %D",n);
     229         630 :   PetscValidPointer(A,3);
     230         630 :   PetscCheckSameComm(st,1,*A,3);
     231         630 :   if (st->state) {
     232          41 :     if (n!=st->nmat) same = PETSC_FALSE;
     233          54 :     for (i=0;same&&i<n;i++) {
     234          54 :       if (A[i]!=st->A[i]) same = PETSC_FALSE;
     235             :     }
     236          41 :     if (!same) { ierr = STReset(st);CHKERRQ(ierr); }
     237             :   } else same = PETSC_FALSE;
     238         630 :   if (!same) {
     239         609 :     ierr = MatDestroyMatrices(PetscMax(2,st->nmat),&st->A);CHKERRQ(ierr);
     240         609 :     ierr = PetscCalloc1(PetscMax(2,n),&st->A);CHKERRQ(ierr);
     241         609 :     ierr = PetscLogObjectMemory((PetscObject)st,PetscMax(2,n)*sizeof(Mat));CHKERRQ(ierr);
     242         609 :     ierr = PetscFree(st->Astate);CHKERRQ(ierr);
     243         609 :     ierr = PetscMalloc1(PetscMax(2,n),&st->Astate);CHKERRQ(ierr);
     244         609 :     ierr = PetscLogObjectMemory((PetscObject)st,PetscMax(2,n)*sizeof(PetscInt));CHKERRQ(ierr);
     245             :   }
     246        1209 :   for (i=0;i<n;i++) {
     247        1209 :     PetscValidHeaderSpecific(A[i],MAT_CLASSID,3);
     248        1209 :     ierr = PetscObjectReference((PetscObject)A[i]);CHKERRQ(ierr);
     249        1209 :     ierr = MatDestroy(&st->A[i]);CHKERRQ(ierr);
     250        1209 :     st->A[i] = A[i];
     251        1209 :     st->Astate[i] = ((PetscObject)A[i])->state;
     252             :   }
     253         630 :   if (n==1) {
     254         364 :     st->A[1] = NULL;
     255         364 :     st->Astate[1] = 0;
     256             :   }
     257         630 :   st->nmat = n;
     258         630 :   if (same) st->state = ST_STATE_UPDATED;
     259         609 :   else st->state = ST_STATE_INITIAL;
     260         630 :   PetscFunctionReturn(0);
     261             : }
     262             : 
     263             : /*@
     264             :    STGetMatrix - Gets the matrices associated with the original eigensystem.
     265             : 
     266             :    Not collective, though parallel Mats are returned if the ST is parallel
     267             : 
     268             :    Input Parameter:
     269             : +  st - the spectral transformation context
     270             : -  k  - the index of the requested matrix (starting in 0)
     271             : 
     272             :    Output Parameters:
     273             : .  A - the requested matrix
     274             : 
     275             :    Level: intermediate
     276             : 
     277             : .seealso: STSetMatrices(), STGetNumMatrices()
     278             : @*/
     279        6633 : PetscErrorCode STGetMatrix(ST st,PetscInt k,Mat *A)
     280             : {
     281        6633 :   PetscFunctionBegin;
     282        6633 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     283       13266 :   PetscValidLogicalCollectiveInt(st,k,2);
     284        6633 :   PetscValidPointer(A,3);
     285        6633 :   STCheckMatrices(st,1);
     286        6633 :   if (k<0 || k>=st->nmat) SETERRQ1(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"k must be between 0 and %D",st->nmat-1);
     287        6633 :   if (((PetscObject)st->A[k])->state!=st->Astate[k]) SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_SUP,"Cannot retrieve original matrices (have been modified)");
     288        6633 :   *A = st->A[k];
     289        6633 :   PetscFunctionReturn(0);
     290             : }
     291             : 
     292             : /*@
     293             :    STGetMatrixTransformed - Gets the matrices associated with the transformed eigensystem.
     294             : 
     295             :    Not collective, though parallel Mats are returned if the ST is parallel
     296             : 
     297             :    Input Parameter:
     298             : +  st - the spectral transformation context
     299             : -  k  - the index of the requested matrix (starting in 0)
     300             : 
     301             :    Output Parameters:
     302             : .  T - the requested matrix
     303             : 
     304             :    Level: developer
     305             : 
     306             : .seealso: STGetMatrix(), STGetNumMatrices()
     307             : @*/
     308         212 : PetscErrorCode STGetMatrixTransformed(ST st,PetscInt k,Mat *T)
     309             : {
     310         212 :   PetscFunctionBegin;
     311         212 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     312         424 :   PetscValidLogicalCollectiveInt(st,k,2);
     313         212 :   PetscValidPointer(T,3);
     314         212 :   STCheckMatrices(st,1);
     315         212 :   if (k<0 || k>=st->nmat) SETERRQ1(PetscObjectComm((PetscObject)st),PETSC_ERR_ARG_OUTOFRANGE,"k must be between 0 and %D",st->nmat-1);
     316         212 :   if (!st->T) SETERRQ(PetscObjectComm((PetscObject)st),PETSC_ERR_POINTER,"There are no transformed matrices");
     317         212 :   *T = st->T[k];
     318         212 :   PetscFunctionReturn(0);
     319             : }
     320             : 
     321             : /*@
     322             :    STGetNumMatrices - Returns the number of matrices stored in the ST.
     323             : 
     324             :    Not collective
     325             : 
     326             :    Input Parameter:
     327             : .  st - the spectral transformation context
     328             : 
     329             :    Output Parameters:
     330             : .  n - the number of matrices passed in STSetMatrices()
     331             : 
     332             :    Level: intermediate
     333             : 
     334             : .seealso: STSetMatrices()
     335             : @*/
     336        5001 : PetscErrorCode STGetNumMatrices(ST st,PetscInt *n)
     337             : {
     338        5001 :   PetscFunctionBegin;
     339        5001 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     340        5001 :   PetscValidIntPointer(n,2);
     341        5001 :   *n = st->nmat;
     342        5001 :   PetscFunctionReturn(0);
     343             : }
     344             : 
     345             : /*@
     346             :    STResetMatrixState - Resets the stored state of the matrices in the ST.
     347             : 
     348             :    Logically Collective on st
     349             : 
     350             :    Input Parameter:
     351             : .  st - the spectral transformation context
     352             : 
     353             :    Note:
     354             :    This is useful in solvers where the user matrices are modified during
     355             :    the computation, as in nonlinear inverse iteration. The effect is that
     356             :    STGetMatrix() will retrieve the modified matrices as if they were
     357             :    the matrices originally provided by the user.
     358             : 
     359             :    Level: developer
     360             : 
     361             : .seealso: STGetMatrix(), EPSPowerSetNonlinear()
     362             : @*/
     363          81 : PetscErrorCode STResetMatrixState(ST st)
     364             : {
     365             :   PetscInt i;
     366             : 
     367          81 :   PetscFunctionBegin;
     368          81 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     369         162 :   for (i=0;i<st->nmat;i++) st->Astate[i] = ((PetscObject)st->A[i])->state;
     370          81 :   PetscFunctionReturn(0);
     371             : }
     372             : 
     373             : /*@
     374             :    STSetShift - Sets the shift associated with the spectral transformation.
     375             : 
     376             :    Logically Collective on st
     377             : 
     378             :    Input Parameters:
     379             : +  st - the spectral transformation context
     380             : -  shift - the value of the shift
     381             : 
     382             :    Notes:
     383             :    In some spectral transformations, changing the shift may have associated
     384             :    a lot of work, for example recomputing a factorization.
     385             : 
     386             :    This function is normally not directly called by users, since the shift is
     387             :    indirectly set by EPSSetTarget().
     388             : 
     389             :    Level: intermediate
     390             : 
     391             : .seealso: EPSSetTarget(), STGetShift(), STSetDefaultShift()
     392             : @*/
     393         308 : PetscErrorCode STSetShift(ST st,PetscScalar shift)
     394             : {
     395             :   PetscErrorCode ierr;
     396             : 
     397         308 :   PetscFunctionBegin;
     398         308 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     399         308 :   PetscValidType(st,1);
     400         616 :   PetscValidLogicalCollectiveScalar(st,shift,2);
     401         590 :   if (st->state==ST_STATE_SETUP && st->sigma != shift) {
     402         282 :     if (st->ops->setshift) {
     403         282 :       ierr = (*st->ops->setshift)(st,shift);CHKERRQ(ierr);
     404             :     }
     405             :   }
     406         308 :   st->sigma = shift;
     407         308 :   st->sigma_set = PETSC_TRUE;
     408         308 :   PetscFunctionReturn(0);
     409             : }
     410             : 
     411             : /*@
     412             :    STGetShift - Gets the shift associated with the spectral transformation.
     413             : 
     414             :    Not Collective
     415             : 
     416             :    Input Parameter:
     417             : .  st - the spectral transformation context
     418             : 
     419             :    Output Parameter:
     420             : .  shift - the value of the shift
     421             : 
     422             :    Level: intermediate
     423             : 
     424             : .seealso: STSetShift()
     425             : @*/
     426        2788 : PetscErrorCode STGetShift(ST st,PetscScalar* shift)
     427             : {
     428        2788 :   PetscFunctionBegin;
     429        2788 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     430        2788 :   PetscValidScalarPointer(shift,2);
     431        2788 :   *shift = st->sigma;
     432        2788 :   PetscFunctionReturn(0);
     433             : }
     434             : 
     435             : /*@
     436             :    STSetDefaultShift - Sets the value of the shift that should be employed if
     437             :    the user did not specify one.
     438             : 
     439             :    Logically Collective on st
     440             : 
     441             :    Input Parameters:
     442             : +  st - the spectral transformation context
     443             : -  defaultshift - the default value of the shift
     444             : 
     445             :    Level: developer
     446             : 
     447             : .seealso: STSetShift()
     448             : @*/
     449         273 : PetscErrorCode STSetDefaultShift(ST st,PetscScalar defaultshift)
     450             : {
     451         273 :   PetscFunctionBegin;
     452         273 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     453         546 :   PetscValidLogicalCollectiveScalar(st,defaultshift,2);
     454         273 :   st->defsigma = defaultshift;
     455         546 :   PetscFunctionReturn(0);
     456             : }
     457             : 
     458             : /*@
     459             :    STScaleShift - Multiply the shift with a given factor.
     460             : 
     461             :    Logically Collective on st
     462             : 
     463             :    Input Parameters:
     464             : +  st     - the spectral transformation context
     465             : -  factor - the scaling factor
     466             : 
     467             :    Note:
     468             :    This function does not update the transformation matrices, as opposed to
     469             :    STSetShift().
     470             : 
     471             :    Level: developer
     472             : 
     473             : .seealso: STSetShift()
     474             : @*/
     475         197 : PetscErrorCode STScaleShift(ST st,PetscScalar factor)
     476             : {
     477         197 :   PetscFunctionBegin;
     478         197 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     479         394 :   PetscValidLogicalCollectiveScalar(st,factor,2);
     480         197 :   st->sigma *= factor;
     481         394 :   PetscFunctionReturn(0);
     482             : }
     483             : 
     484             : /*@
     485             :    STSetBalanceMatrix - Sets the diagonal matrix to be used for balancing.
     486             : 
     487             :    Collective on st
     488             : 
     489             :    Input Parameters:
     490             : +  st - the spectral transformation context
     491             : -  D  - the diagonal matrix (represented as a vector)
     492             : 
     493             :    Notes:
     494             :    If this matrix is set, STApply will effectively apply D*OP*D^{-1}. Use NULL
     495             :    to reset a previously passed D.
     496             : 
     497             :    Balancing is usually set via EPSSetBalance, but the advanced user may use
     498             :    this function to bypass the usual balancing methods.
     499             : 
     500             :    Level: developer
     501             : 
     502             : .seealso: EPSSetBalance(), STApply(), STGetBalanceMatrix()
     503             : @*/
     504         549 : PetscErrorCode STSetBalanceMatrix(ST st,Vec D)
     505             : {
     506             :   PetscErrorCode ierr;
     507             : 
     508         549 :   PetscFunctionBegin;
     509         549 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     510         549 :   if (D) {
     511          10 :     PetscValidHeaderSpecific(D,VEC_CLASSID,2);
     512          10 :     PetscCheckSameComm(st,1,D,2);
     513          10 :     ierr = PetscObjectReference((PetscObject)D);CHKERRQ(ierr);
     514             :   }
     515         549 :   ierr = VecDestroy(&st->D);CHKERRQ(ierr);
     516         549 :   st->D = D;
     517         549 :   st->state = ST_STATE_INITIAL;
     518         549 :   PetscFunctionReturn(0);
     519             : }
     520             : 
     521             : /*@
     522             :    STGetBalanceMatrix - Gets the balance matrix used by the spectral transformation.
     523             : 
     524             :    Not collective, but vector is shared by all processors that share the ST
     525             : 
     526             :    Input Parameter:
     527             : .  st - the spectral transformation context
     528             : 
     529             :    Output Parameter:
     530             : .  D  - the diagonal matrix (represented as a vector)
     531             : 
     532             :    Note:
     533             :    If the matrix was not set, a null pointer will be returned.
     534             : 
     535             :    Level: developer
     536             : 
     537             : .seealso: STSetBalanceMatrix()
     538             : @*/
     539           0 : PetscErrorCode STGetBalanceMatrix(ST st,Vec *D)
     540             : {
     541           0 :   PetscFunctionBegin;
     542           0 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     543           0 :   PetscValidPointer(D,2);
     544           0 :   *D = st->D;
     545           0 :   PetscFunctionReturn(0);
     546             : }
     547             : 
     548             : /*@C
     549             :    STMatCreateVecs - Get vector(s) compatible with the ST matrices.
     550             : 
     551             :    Collective on st
     552             : 
     553             :    Input Parameter:
     554             : .  st - the spectral transformation context
     555             : 
     556             :    Output Parameters:
     557             : +  right - (optional) vector that the matrix can be multiplied against
     558             : -  left  - (optional) vector that the matrix vector product can be stored in
     559             : 
     560             :    Level: developer
     561             : @*/
     562         256 : PetscErrorCode STMatCreateVecs(ST st,Vec *right,Vec *left)
     563             : {
     564             :   PetscErrorCode ierr;
     565             : 
     566         256 :   PetscFunctionBegin;
     567         256 :   STCheckMatrices(st,1);
     568         256 :   ierr = MatCreateVecs(st->A[0],right,left);CHKERRQ(ierr);
     569         256 :   PetscFunctionReturn(0);
     570             : }
     571             : 
     572             : /*@C
     573             :    STMatCreateVecsEmpty - Get vector(s) compatible with the ST matrices, i.e. with the same
     574             :    parallel layout, but without internal array.
     575             : 
     576             :    Collective on st
     577             : 
     578             :    Input Parameter:
     579             : .  st - the spectral transformation context
     580             : 
     581             :    Output Parameters:
     582             : +  right - (optional) vector that the matrix can be multiplied against
     583             : -  left  - (optional) vector that the matrix vector product can be stored in
     584             : 
     585             :    Level: developer
     586             : 
     587             : .seealso: MatCreateVecsEmpty()
     588             : @*/
     589         587 : PetscErrorCode STMatCreateVecsEmpty(ST st,Vec *right,Vec *left)
     590             : {
     591             :   PetscErrorCode ierr;
     592             : 
     593         587 :   PetscFunctionBegin;
     594         587 :   STCheckMatrices(st,1);
     595         587 :   ierr = MatCreateVecsEmpty(st->A[0],right,left);CHKERRQ(ierr);
     596         587 :   PetscFunctionReturn(0);
     597             : }
     598             : 
     599             : /*@
     600             :    STMatGetSize - Returns the number of rows and columns of the ST matrices.
     601             : 
     602             :    Not Collective
     603             : 
     604             :    Input Parameter:
     605             : .  st - the spectral transformation context
     606             : 
     607             :    Output Parameters:
     608             : +  m - the number of global rows
     609             : -  n - the number of global columns
     610             : 
     611             :    Level: developer
     612             : @*/
     613         539 : PetscErrorCode STMatGetSize(ST st,PetscInt *m,PetscInt *n)
     614             : {
     615             :   PetscErrorCode ierr;
     616             : 
     617         539 :   PetscFunctionBegin;
     618         539 :   STCheckMatrices(st,1);
     619         539 :   ierr = MatGetSize(st->A[0],m,n);CHKERRQ(ierr);
     620         539 :   PetscFunctionReturn(0);
     621             : }
     622             : 
     623             : /*@
     624             :    STMatGetLocalSize - Returns the number of local rows and columns of the ST matrices.
     625             : 
     626             :    Not Collective
     627             : 
     628             :    Input Parameter:
     629             : .  st - the spectral transformation context
     630             : 
     631             :    Output Parameters:
     632             : +  m - the number of local rows
     633             : -  n - the number of local columns
     634             : 
     635             :    Level: developer
     636             : @*/
     637         539 : PetscErrorCode STMatGetLocalSize(ST st,PetscInt *m,PetscInt *n)
     638             : {
     639             :   PetscErrorCode ierr;
     640             : 
     641         539 :   PetscFunctionBegin;
     642         539 :   STCheckMatrices(st,1);
     643         539 :   ierr = MatGetLocalSize(st->A[0],m,n);CHKERRQ(ierr);
     644         539 :   PetscFunctionReturn(0);
     645             : }
     646             : 
     647             : /*@C
     648             :    STSetOptionsPrefix - Sets the prefix used for searching for all
     649             :    ST options in the database.
     650             : 
     651             :    Logically Collective on st
     652             : 
     653             :    Input Parameters:
     654             : +  st     - the spectral transformation context
     655             : -  prefix - the prefix string to prepend to all ST option requests
     656             : 
     657             :    Notes:
     658             :    A hyphen (-) must NOT be given at the beginning of the prefix name.
     659             :    The first character of all runtime options is AUTOMATICALLY the
     660             :    hyphen.
     661             : 
     662             :    Level: advanced
     663             : 
     664             : .seealso: STAppendOptionsPrefix(), STGetOptionsPrefix()
     665             : @*/
     666         101 : PetscErrorCode STSetOptionsPrefix(ST st,const char *prefix)
     667             : {
     668             :   PetscErrorCode ierr;
     669             : 
     670         101 :   PetscFunctionBegin;
     671         101 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     672         101 :   if (!st->ksp) { ierr = STGetKSP(st,&st->ksp);CHKERRQ(ierr); }
     673         101 :   ierr = KSPSetOptionsPrefix(st->ksp,prefix);CHKERRQ(ierr);
     674         101 :   ierr = KSPAppendOptionsPrefix(st->ksp,"st_");CHKERRQ(ierr);
     675         101 :   ierr = PetscObjectSetOptionsPrefix((PetscObject)st,prefix);CHKERRQ(ierr);
     676         101 :   PetscFunctionReturn(0);
     677             : }
     678             : 
     679             : /*@C
     680             :    STAppendOptionsPrefix - Appends to the prefix used for searching for all
     681             :    ST options in the database.
     682             : 
     683             :    Logically Collective on st
     684             : 
     685             :    Input Parameters:
     686             : +  st     - the spectral transformation context
     687             : -  prefix - the prefix string to prepend to all ST option requests
     688             : 
     689             :    Notes:
     690             :    A hyphen (-) must NOT be given at the beginning of the prefix name.
     691             :    The first character of all runtime options is AUTOMATICALLY the
     692             :    hyphen.
     693             : 
     694             :    Level: advanced
     695             : 
     696             : .seealso: STSetOptionsPrefix(), STGetOptionsPrefix()
     697             : @*/
     698          99 : PetscErrorCode STAppendOptionsPrefix(ST st,const char *prefix)
     699             : {
     700             :   PetscErrorCode ierr;
     701             : 
     702          99 :   PetscFunctionBegin;
     703          99 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     704          99 :   ierr = PetscObjectAppendOptionsPrefix((PetscObject)st,prefix);CHKERRQ(ierr);
     705          99 :   if (!st->ksp) { ierr = STGetKSP(st,&st->ksp);CHKERRQ(ierr); }
     706          99 :   ierr = KSPSetOptionsPrefix(st->ksp,((PetscObject)st)->prefix);CHKERRQ(ierr);
     707          99 :   ierr = KSPAppendOptionsPrefix(st->ksp,"st_");CHKERRQ(ierr);
     708          99 :   PetscFunctionReturn(0);
     709             : }
     710             : 
     711             : /*@C
     712             :    STGetOptionsPrefix - Gets the prefix used for searching for all
     713             :    ST options in the database.
     714             : 
     715             :    Not Collective
     716             : 
     717             :    Input Parameters:
     718             : .  st - the spectral transformation context
     719             : 
     720             :    Output Parameters:
     721             : .  prefix - pointer to the prefix string used, is returned
     722             : 
     723             :    Note:
     724             :    On the Fortran side, the user should pass in a string 'prefix' of
     725             :    sufficient length to hold the prefix.
     726             : 
     727             :    Level: advanced
     728             : 
     729             : .seealso: STSetOptionsPrefix(), STAppendOptionsPrefix()
     730             : @*/
     731           0 : PetscErrorCode STGetOptionsPrefix(ST st,const char *prefix[])
     732             : {
     733             :   PetscErrorCode ierr;
     734             : 
     735           0 :   PetscFunctionBegin;
     736           0 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     737           0 :   PetscValidPointer(prefix,2);
     738           0 :   ierr = PetscObjectGetOptionsPrefix((PetscObject)st,prefix);CHKERRQ(ierr);
     739           0 :   PetscFunctionReturn(0);
     740             : }
     741             : 
     742             : /*@C
     743             :    STView - Prints the ST data structure.
     744             : 
     745             :    Collective on st
     746             : 
     747             :    Input Parameters:
     748             : +  st - the ST context
     749             : -  viewer - optional visualization context
     750             : 
     751             :    Note:
     752             :    The available visualization contexts include
     753             : +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
     754             : -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
     755             :          output where only the first processor opens
     756             :          the file.  All other processors send their
     757             :          data to the first processor to print.
     758             : 
     759             :    The user can open an alternative visualization contexts with
     760             :    PetscViewerASCIIOpen() (output to a specified file).
     761             : 
     762             :    Level: beginner
     763             : 
     764             : .seealso: EPSView()
     765             : @*/
     766          10 : PetscErrorCode STView(ST st,PetscViewer viewer)
     767             : {
     768             :   PetscErrorCode ierr;
     769             :   STType         cstr;
     770          10 :   const char*    pat=NULL;
     771             :   char           str[50];
     772             :   PetscBool      isascii,isstring;
     773             : 
     774          10 :   PetscFunctionBegin;
     775          10 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     776          10 :   if (!viewer) {
     777           2 :     ierr = PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)st),&viewer);CHKERRQ(ierr);
     778             :   }
     779          10 :   PetscValidHeaderSpecific(viewer,PETSC_VIEWER_CLASSID,2);
     780          10 :   PetscCheckSameComm(st,1,viewer,2);
     781             : 
     782          10 :   ierr = PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);CHKERRQ(ierr);
     783          10 :   ierr = PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERSTRING,&isstring);CHKERRQ(ierr);
     784          10 :   if (isascii) {
     785          10 :     ierr = PetscObjectPrintClassNamePrefixType((PetscObject)st,viewer);CHKERRQ(ierr);
     786          10 :     if (st->ops->view) {
     787           0 :       ierr = PetscViewerASCIIPushTab(viewer);CHKERRQ(ierr);
     788           0 :       ierr = (*st->ops->view)(st,viewer);CHKERRQ(ierr);
     789           0 :       ierr = PetscViewerASCIIPopTab(viewer);CHKERRQ(ierr);
     790             :     }
     791          10 :     ierr = SlepcSNPrintfScalar(str,50,st->sigma,PETSC_FALSE);CHKERRQ(ierr);
     792          10 :     ierr = PetscViewerASCIIPrintf(viewer,"  shift: %s\n",str);CHKERRQ(ierr);
     793          10 :     ierr = PetscViewerASCIIPrintf(viewer,"  number of matrices: %D\n",st->nmat);CHKERRQ(ierr);
     794          10 :     switch (st->matmode) {
     795             :     case ST_MATMODE_COPY:
     796             :       break;
     797             :     case ST_MATMODE_INPLACE:
     798           0 :       ierr = PetscViewerASCIIPrintf(viewer,"  shifting the matrix and unshifting at exit\n");CHKERRQ(ierr);
     799             :       break;
     800             :     case ST_MATMODE_SHELL:
     801           1 :       ierr = PetscViewerASCIIPrintf(viewer,"  using a shell matrix\n");CHKERRQ(ierr);
     802             :       break;
     803             :     }
     804          10 :     if (st->nmat>1 && st->matmode != ST_MATMODE_SHELL) {
     805           2 :       switch (st->str) {
     806           0 :         case SAME_NONZERO_PATTERN:      pat = "same nonzero pattern";break;
     807           2 :         case DIFFERENT_NONZERO_PATTERN: pat = "different nonzero pattern";break;
     808           0 :         case SUBSET_NONZERO_PATTERN:    pat = "subset nonzero pattern";break;
     809             :       }
     810           2 :       ierr = PetscViewerASCIIPrintf(viewer,"  all matrices have %s\n",pat);CHKERRQ(ierr);
     811             :     }
     812          10 :     if (st->transform && st->nmat>2) {
     813           0 :       ierr = PetscViewerASCIIPrintf(viewer,"  computing transformed matrices\n");CHKERRQ(ierr);
     814             :     }
     815           0 :   } else if (isstring) {
     816           0 :     ierr = STGetType(st,&cstr);CHKERRQ(ierr);
     817           0 :     ierr = PetscViewerStringSPrintf(viewer," %-7.7s",cstr);CHKERRQ(ierr);
     818           0 :     if (st->ops->view) { ierr = (*st->ops->view)(st,viewer);CHKERRQ(ierr); }
     819             :   }
     820          10 :   if (st->usesksp) {
     821           5 :     if (!st->ksp) { ierr = STGetKSP(st,&st->ksp);CHKERRQ(ierr); }
     822           5 :     ierr = PetscViewerASCIIPushTab(viewer);CHKERRQ(ierr);
     823           5 :     ierr = KSPView(st->ksp,viewer);CHKERRQ(ierr);
     824           5 :     ierr = PetscViewerASCIIPopTab(viewer);CHKERRQ(ierr);
     825             :   }
     826          10 :   PetscFunctionReturn(0);
     827             : }
     828             : 
     829             : /*@C
     830             :    STViewFromOptions - View from options
     831             : 
     832             :    Collective on ST
     833             : 
     834             :    Input Parameters:
     835             : +  st   - the spectral transformation context
     836             : .  obj  - optional object
     837             : -  name - command line option
     838             : 
     839             :    Level: intermediate
     840             : 
     841             : .seealso: STView(), STCreate()
     842             : @*/
     843           0 : PetscErrorCode STViewFromOptions(ST st,PetscObject obj,const char name[])
     844             : {
     845             :   PetscErrorCode ierr;
     846             : 
     847           0 :   PetscFunctionBegin;
     848           0 :   PetscValidHeaderSpecific(st,ST_CLASSID,1);
     849           0 :   ierr = PetscObjectViewFromOptions((PetscObject)st,obj,name);CHKERRQ(ierr);
     850           0 :   PetscFunctionReturn(0);
     851             : }
     852             : 
     853             : /*@C
     854             :    STRegister - Adds a method to the spectral transformation package.
     855             : 
     856             :    Not collective
     857             : 
     858             :    Input Parameters:
     859             : +  name - name of a new user-defined transformation
     860             : -  function - routine to create method context
     861             : 
     862             :    Notes:
     863             :    STRegister() may be called multiple times to add several user-defined
     864             :    spectral transformations.
     865             : 
     866             :    Sample usage:
     867             : .vb
     868             :     STRegister("my_transform",MyTransformCreate);
     869             : .ve
     870             : 
     871             :    Then, your spectral transform can be chosen with the procedural interface via
     872             : $     STSetType(st,"my_transform")
     873             :    or at runtime via the option
     874             : $     -st_type my_transform
     875             : 
     876             :    Level: advanced
     877             : 
     878             : .seealso: STRegisterAll()
     879             : @*/
     880        3096 : PetscErrorCode STRegister(const char *name,PetscErrorCode (*function)(ST))
     881             : {
     882             :   PetscErrorCode ierr;
     883             : 
     884        3096 :   PetscFunctionBegin;
     885        3096 :   ierr = STInitializePackage();CHKERRQ(ierr);
     886        3096 :   ierr = PetscFunctionListAdd(&STList,name,function);CHKERRQ(ierr);
     887        3096 :   PetscFunctionReturn(0);
     888             : }
     889             : 

Generated by: LCOV version 1.13