LCOV - code coverage report
Current view: top level - sys/classes/st/interface - stfunc.c (source / functions) Hit Total Coverage
Test: coverage.info Lines: 257 280 91.8 %
Date: 2019-09-16 06:01:52 Functions: 23 25 92.0 %

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

Generated by: LCOV version 1.13