LCOV - code coverage report
Current view: top level - lme/interface - lmebasic.c (source / functions) Hit Total Coverage
Test: coverage.info Lines: 136 153 88.9 %
Date: 2019-11-15 09:58:42 Functions: 11 12 91.7 %

          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             :    Basic LME routines
      12             : */
      13             : 
      14             : #include <slepc/private/lmeimpl.h>      /*I "slepclme.h" I*/
      15             : 
      16             : PetscFunctionList LMEList = 0;
      17             : PetscBool         LMERegisterAllCalled = PETSC_FALSE;
      18             : PetscClassId      LME_CLASSID = 0;
      19             : PetscLogEvent     LME_SetUp = 0,LME_Solve = 0,LME_ComputeError = 0;
      20             : 
      21             : /*@C
      22             :    LMEView - Prints the LME data structure.
      23             : 
      24             :    Collective on lme
      25             : 
      26             :    Input Parameters:
      27             : +  lme - the linear matrix equation solver context
      28             : -  viewer - optional visualization context
      29             : 
      30             :    Options Database Key:
      31             : .  -lme_view -  Calls LMEView() at end of LMESolve()
      32             : 
      33             :    Note:
      34             :    The available visualization contexts include
      35             : +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
      36             : -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
      37             :          output where only the first processor opens
      38             :          the file.  All other processors send their
      39             :          data to the first processor to print.
      40             : 
      41             :    The user can open an alternative visualization context with
      42             :    PetscViewerASCIIOpen() - output to a specified file.
      43             : 
      44             :    Level: beginner
      45             : @*/
      46           1 : PetscErrorCode LMEView(LME lme,PetscViewer viewer)
      47             : {
      48             :   PetscErrorCode ierr;
      49             :   PetscBool      isascii;
      50           1 :   const char     *eqname[] = {
      51             :                    "continuous-time Lyapunov",
      52             :                    "continuous-time Sylvester",
      53             :                    "generalized Lyapunov",
      54             :                    "generalized Sylvester",
      55             :                    "Stein",
      56             :                    "discrete-time Lyapunov"
      57             :   };
      58             : 
      59           1 :   PetscFunctionBegin;
      60           1 :   PetscValidHeaderSpecific(lme,LME_CLASSID,1);
      61           1 :   if (!viewer) {
      62           0 :     ierr = PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)lme),&viewer);CHKERRQ(ierr);
      63             :   }
      64           1 :   PetscValidHeaderSpecific(viewer,PETSC_VIEWER_CLASSID,2);
      65           1 :   PetscCheckSameComm(lme,1,viewer,2);
      66             : 
      67           1 :   ierr = PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);CHKERRQ(ierr);
      68           1 :   if (isascii) {
      69           1 :     ierr = PetscObjectPrintClassNamePrefixType((PetscObject)lme,viewer);CHKERRQ(ierr);
      70           1 :     if (lme->ops->view) {
      71           0 :       ierr = PetscViewerASCIIPushTab(viewer);CHKERRQ(ierr);
      72           0 :       ierr = (*lme->ops->view)(lme,viewer);CHKERRQ(ierr);
      73           0 :       ierr = PetscViewerASCIIPopTab(viewer);CHKERRQ(ierr);
      74             :     }
      75           1 :     ierr = PetscViewerASCIIPrintf(viewer,"  equation type: %s\n",eqname[lme->problem_type]);CHKERRQ(ierr);
      76           1 :     ierr = PetscViewerASCIIPrintf(viewer,"  number of column vectors (ncv): %D\n",lme->ncv);CHKERRQ(ierr);
      77           1 :     ierr = PetscViewerASCIIPrintf(viewer,"  maximum number of iterations: %D\n",lme->max_it);CHKERRQ(ierr);
      78           1 :     ierr = PetscViewerASCIIPrintf(viewer,"  tolerance: %g\n",(double)lme->tol);CHKERRQ(ierr);
      79             :   } else {
      80           0 :     if (lme->ops->view) {
      81           0 :       ierr = (*lme->ops->view)(lme,viewer);CHKERRQ(ierr);
      82             :     }
      83             :   }
      84           1 :   ierr = PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_INFO);CHKERRQ(ierr);
      85           1 :   if (!lme->V) { ierr = LMEGetBV(lme,&lme->V);CHKERRQ(ierr); }
      86           1 :   ierr = BVView(lme->V,viewer);CHKERRQ(ierr);
      87           1 :   ierr = PetscViewerPopFormat(viewer);CHKERRQ(ierr);
      88           1 :   PetscFunctionReturn(0);
      89             : }
      90             : 
      91             : /*@C
      92             :    LMEViewFromOptions - View from options
      93             : 
      94             :    Collective on LME
      95             : 
      96             :    Input Parameters:
      97             : +  lme  - the linear matrix equation context
      98             : .  obj  - optional object
      99             : -  name - command line option
     100             : 
     101             :    Level: intermediate
     102             : 
     103             : .seealso: LMEView(), LMECreate()
     104             : @*/
     105          10 : PetscErrorCode LMEViewFromOptions(LME lme,PetscObject obj,const char name[])
     106             : {
     107             :   PetscErrorCode ierr;
     108             : 
     109          10 :   PetscFunctionBegin;
     110          10 :   PetscValidHeaderSpecific(lme,LME_CLASSID,1);
     111          10 :   ierr = PetscObjectViewFromOptions((PetscObject)lme,obj,name);CHKERRQ(ierr);
     112          10 :   PetscFunctionReturn(0);
     113             : }
     114             : /*@C
     115             :    LMEReasonView - Displays the reason an LME solve converged or diverged.
     116             : 
     117             :    Collective on lme
     118             : 
     119             :    Input Parameters:
     120             : +  lme - the linear matrix equation context
     121             : -  viewer - the viewer to display the reason
     122             : 
     123             :    Options Database Keys:
     124             : .  -lme_converged_reason - print reason for convergence, and number of iterations
     125             : 
     126             :    Level: intermediate
     127             : 
     128             : .seealso: LMESetTolerances(), LMEGetIterationNumber()
     129             : @*/
     130           1 : PetscErrorCode LMEReasonView(LME lme,PetscViewer viewer)
     131             : {
     132             :   PetscErrorCode ierr;
     133             :   PetscBool      isAscii;
     134             : 
     135           1 :   PetscFunctionBegin;
     136           1 :   ierr = PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isAscii);CHKERRQ(ierr);
     137           1 :   if (isAscii) {
     138           1 :     ierr = PetscViewerASCIIAddTab(viewer,((PetscObject)lme)->tablevel);CHKERRQ(ierr);
     139           1 :     if (lme->reason > 0) {
     140           1 :       ierr = PetscViewerASCIIPrintf(viewer,"%s Linear matrix equation solve converged due to %s; iterations %D\n",((PetscObject)lme)->prefix?((PetscObject)lme)->prefix:"",LMEConvergedReasons[lme->reason],lme->its);CHKERRQ(ierr);
     141             :     } else {
     142           0 :       ierr = PetscViewerASCIIPrintf(viewer,"%s Linear matrix equation solve did not converge due to %s; iterations %D\n",((PetscObject)lme)->prefix?((PetscObject)lme)->prefix:"",LMEConvergedReasons[lme->reason],lme->its);CHKERRQ(ierr);
     143             :     }
     144           1 :     ierr = PetscViewerASCIISubtractTab(viewer,((PetscObject)lme)->tablevel);CHKERRQ(ierr);
     145             :   }
     146           1 :   PetscFunctionReturn(0);
     147             : }
     148             : 
     149             : /*@
     150             :    LMEReasonViewFromOptions - Processes command line options to determine if/how
     151             :    the LME converged reason is to be viewed.
     152             : 
     153             :    Collective on lme
     154             : 
     155             :    Input Parameter:
     156             : .  lme - the linear matrix equation context
     157             : 
     158             :    Level: developer
     159             : @*/
     160           5 : PetscErrorCode LMEReasonViewFromOptions(LME lme)
     161             : {
     162             :   PetscErrorCode    ierr;
     163             :   PetscViewer       viewer;
     164             :   PetscBool         flg;
     165             :   static PetscBool  incall = PETSC_FALSE;
     166             :   PetscViewerFormat format;
     167             : 
     168           5 :   PetscFunctionBegin;
     169           5 :   if (incall) PetscFunctionReturn(0);
     170           5 :   incall = PETSC_TRUE;
     171           5 :   ierr = PetscOptionsGetViewer(PetscObjectComm((PetscObject)lme),((PetscObject)lme)->options,((PetscObject)lme)->prefix,"-lme_converged_reason",&viewer,&format,&flg);CHKERRQ(ierr);
     172           5 :   if (flg) {
     173           1 :     ierr = PetscViewerPushFormat(viewer,format);CHKERRQ(ierr);
     174           1 :     ierr = LMEReasonView(lme,viewer);CHKERRQ(ierr);
     175           1 :     ierr = PetscViewerPopFormat(viewer);CHKERRQ(ierr);
     176           1 :     ierr = PetscViewerDestroy(&viewer);CHKERRQ(ierr);
     177             :   }
     178           5 :   incall = PETSC_FALSE;
     179           5 :   PetscFunctionReturn(0);
     180             : }
     181             : 
     182             : /*@
     183             :    LMECreate - Creates the default LME context.
     184             : 
     185             :    Collective
     186             : 
     187             :    Input Parameter:
     188             : .  comm - MPI communicator
     189             : 
     190             :    Output Parameter:
     191             : .  lme - location to put the LME context
     192             : 
     193             :    Note:
     194             :    The default LME type is LMEKRYLOV
     195             : 
     196             :    Level: beginner
     197             : 
     198             : .seealso: LMESetUp(), LMESolve(), LMEDestroy(), LME
     199             : @*/
     200           5 : PetscErrorCode LMECreate(MPI_Comm comm,LME *outlme)
     201             : {
     202             :   PetscErrorCode ierr;
     203             :   LME            lme;
     204             : 
     205           5 :   PetscFunctionBegin;
     206           5 :   PetscValidPointer(outlme,2);
     207           5 :   *outlme = 0;
     208           5 :   ierr = LMEInitializePackage();CHKERRQ(ierr);
     209           5 :   ierr = SlepcHeaderCreate(lme,LME_CLASSID,"LME","Linear Matrix Equation","LME",comm,LMEDestroy,LMEView);CHKERRQ(ierr);
     210             : 
     211           5 :   lme->A               = NULL;
     212           5 :   lme->B               = NULL;
     213           5 :   lme->D               = NULL;
     214           5 :   lme->E               = NULL;
     215           5 :   lme->C               = NULL;
     216           5 :   lme->X               = NULL;
     217           5 :   lme->problem_type    = LME_LYAPUNOV;
     218           5 :   lme->max_it          = 0;
     219           5 :   lme->ncv             = 0;
     220           5 :   lme->tol             = PETSC_DEFAULT;
     221           5 :   lme->errorifnotconverged = PETSC_FALSE;
     222             : 
     223           5 :   lme->numbermonitors  = 0;
     224             : 
     225           5 :   lme->V               = NULL;
     226           5 :   lme->nwork           = 0;
     227           5 :   lme->work            = NULL;
     228           5 :   lme->data            = NULL;
     229             : 
     230           5 :   lme->its             = 0;
     231           5 :   lme->errest          = 0;
     232           5 :   lme->setupcalled     = 0;
     233           5 :   lme->reason          = LME_CONVERGED_ITERATING;
     234             : 
     235           5 :   *outlme = lme;
     236           5 :   PetscFunctionReturn(0);
     237             : }
     238             : 
     239             : /*@C
     240             :    LMESetType - Selects the particular solver to be used in the LME object.
     241             : 
     242             :    Logically Collective on lme
     243             : 
     244             :    Input Parameters:
     245             : +  lme  - the linear matrix equation context
     246             : -  type - a known method
     247             : 
     248             :    Options Database Key:
     249             : .  -lme_type <method> - Sets the method; use -help for a list
     250             :     of available methods
     251             : 
     252             :    Notes:
     253             :    See "slepc/include/slepclme.h" for available methods. The default
     254             :    is LMEKRYLOV
     255             : 
     256             :    Normally, it is best to use the LMESetFromOptions() command and
     257             :    then set the LME type from the options database rather than by using
     258             :    this routine.  Using the options database provides the user with
     259             :    maximum flexibility in evaluating the different available methods.
     260             :    The LMESetType() routine is provided for those situations where it
     261             :    is necessary to set the iterative solver independently of the command
     262             :    line or options database.
     263             : 
     264             :    Level: intermediate
     265             : 
     266             : .seealso: LMEType
     267             : @*/
     268           5 : PetscErrorCode LMESetType(LME lme,LMEType type)
     269             : {
     270             :   PetscErrorCode ierr,(*r)(LME);
     271             :   PetscBool      match;
     272             : 
     273           5 :   PetscFunctionBegin;
     274           5 :   PetscValidHeaderSpecific(lme,LME_CLASSID,1);
     275           5 :   PetscValidCharPointer(type,2);
     276             : 
     277           5 :   ierr = PetscObjectTypeCompare((PetscObject)lme,type,&match);CHKERRQ(ierr);
     278           5 :   if (match) PetscFunctionReturn(0);
     279             : 
     280           5 :   ierr = PetscFunctionListFind(LMEList,type,&r);CHKERRQ(ierr);
     281           5 :   if (!r) SETERRQ1(PetscObjectComm((PetscObject)lme),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unknown LME type given: %s",type);
     282             : 
     283           5 :   if (lme->ops->destroy) { ierr = (*lme->ops->destroy)(lme);CHKERRQ(ierr); }
     284           5 :   ierr = PetscMemzero(lme->ops,sizeof(struct _LMEOps));CHKERRQ(ierr);
     285             : 
     286           5 :   lme->setupcalled = 0;
     287           5 :   ierr = PetscObjectChangeTypeName((PetscObject)lme,type);CHKERRQ(ierr);
     288           5 :   ierr = (*r)(lme);CHKERRQ(ierr);
     289           5 :   PetscFunctionReturn(0);
     290             : }
     291             : 
     292             : /*@C
     293             :    LMEGetType - Gets the LME type as a string from the LME object.
     294             : 
     295             :    Not Collective
     296             : 
     297             :    Input Parameter:
     298             : .  lme - the linear matrix equation context
     299             : 
     300             :    Output Parameter:
     301             : .  name - name of LME method
     302             : 
     303             :    Level: intermediate
     304             : 
     305             : .seealso: LMESetType()
     306             : @*/
     307           3 : PetscErrorCode LMEGetType(LME lme,LMEType *type)
     308             : {
     309           3 :   PetscFunctionBegin;
     310           3 :   PetscValidHeaderSpecific(lme,LME_CLASSID,1);
     311           3 :   PetscValidPointer(type,2);
     312           3 :   *type = ((PetscObject)lme)->type_name;
     313           3 :   PetscFunctionReturn(0);
     314             : }
     315             : 
     316             : /*@C
     317             :    LMERegister - Adds a method to the linear matrix equation solver package.
     318             : 
     319             :    Not Collective
     320             : 
     321             :    Input Parameters:
     322             : +  name - name of a new user-defined solver
     323             : -  function - routine to create the solver context
     324             : 
     325             :    Notes:
     326             :    LMERegister() may be called multiple times to add several user-defined solvers.
     327             : 
     328             :    Sample usage:
     329             : .vb
     330             :     LMERegister("my_solver",MySolverCreate);
     331             : .ve
     332             : 
     333             :    Then, your solver can be chosen with the procedural interface via
     334             : $     LMESetType(lme,"my_solver")
     335             :    or at runtime via the option
     336             : $     -lme_type my_solver
     337             : 
     338             :    Level: advanced
     339             : 
     340             : .seealso: LMERegisterAll()
     341             : @*/
     342           6 : PetscErrorCode LMERegister(const char *name,PetscErrorCode (*function)(LME))
     343             : {
     344             :   PetscErrorCode ierr;
     345             : 
     346           6 :   PetscFunctionBegin;
     347           6 :   ierr = LMEInitializePackage();CHKERRQ(ierr);
     348           6 :   ierr = PetscFunctionListAdd(&LMEList,name,function);CHKERRQ(ierr);
     349           6 :   PetscFunctionReturn(0);
     350             : }
     351             : 
     352             : /*@
     353             :    LMEReset - Resets the LME context to the initial state (prior to setup)
     354             :    and destroys any allocated Vecs and Mats.
     355             : 
     356             :    Collective on lme
     357             : 
     358             :    Input Parameter:
     359             : .  lme - linear matrix equation context obtained from LMECreate()
     360             : 
     361             :    Level: advanced
     362             : 
     363             : .seealso: LMEDestroy()
     364             : @*/
     365           5 : PetscErrorCode LMEReset(LME lme)
     366             : {
     367             :   PetscErrorCode ierr;
     368             : 
     369           5 :   PetscFunctionBegin;
     370           5 :   if (lme) PetscValidHeaderSpecific(lme,LME_CLASSID,1);
     371           5 :   if (!lme) PetscFunctionReturn(0);
     372           5 :   if (lme->ops->reset) { ierr = (lme->ops->reset)(lme);CHKERRQ(ierr); }
     373           5 :   ierr = MatDestroy(&lme->A);CHKERRQ(ierr);
     374           5 :   ierr = MatDestroy(&lme->B);CHKERRQ(ierr);
     375           5 :   ierr = MatDestroy(&lme->D);CHKERRQ(ierr);
     376           5 :   ierr = MatDestroy(&lme->E);CHKERRQ(ierr);
     377           5 :   ierr = MatDestroy(&lme->C);CHKERRQ(ierr);
     378           5 :   ierr = MatDestroy(&lme->X);CHKERRQ(ierr);
     379           5 :   ierr = BVDestroy(&lme->V);CHKERRQ(ierr);
     380           5 :   ierr = VecDestroyVecs(lme->nwork,&lme->work);CHKERRQ(ierr);
     381           5 :   lme->nwork = 0;
     382           5 :   lme->setupcalled = 0;
     383           5 :   PetscFunctionReturn(0);
     384             : }
     385             : 
     386             : /*@
     387             :    LMEDestroy - Destroys the LME context.
     388             : 
     389             :    Collective on lme
     390             : 
     391             :    Input Parameter:
     392             : .  lme - linear matrix equation context obtained from LMECreate()
     393             : 
     394             :    Level: beginner
     395             : 
     396             : .seealso: LMECreate(), LMESetUp(), LMESolve()
     397             : @*/
     398           5 : PetscErrorCode LMEDestroy(LME *lme)
     399             : {
     400             :   PetscErrorCode ierr;
     401             : 
     402           5 :   PetscFunctionBegin;
     403           5 :   if (!*lme) PetscFunctionReturn(0);
     404           5 :   PetscValidHeaderSpecific(*lme,LME_CLASSID,1);
     405           5 :   if (--((PetscObject)(*lme))->refct > 0) { *lme = 0; PetscFunctionReturn(0); }
     406           5 :   ierr = LMEReset(*lme);CHKERRQ(ierr);
     407           5 :   if ((*lme)->ops->destroy) { ierr = (*(*lme)->ops->destroy)(*lme);CHKERRQ(ierr); }
     408           5 :   ierr = LMEMonitorCancel(*lme);CHKERRQ(ierr);
     409           5 :   ierr = PetscHeaderDestroy(lme);CHKERRQ(ierr);
     410           5 :   PetscFunctionReturn(0);
     411             : }
     412             : 
     413             : /*@
     414             :    LMESetBV - Associates a basis vectors object to the linear matrix equation solver.
     415             : 
     416             :    Collective on lme
     417             : 
     418             :    Input Parameters:
     419             : +  lme - linear matrix equation context obtained from LMECreate()
     420             : -  bv  - the basis vectors object
     421             : 
     422             :    Note:
     423             :    Use LMEGetBV() to retrieve the basis vectors context (for example,
     424             :    to free it at the end of the computations).
     425             : 
     426             :    Level: advanced
     427             : 
     428             : .seealso: LMEGetBV()
     429             : @*/
     430           0 : PetscErrorCode LMESetBV(LME lme,BV bv)
     431             : {
     432             :   PetscErrorCode ierr;
     433             : 
     434           0 :   PetscFunctionBegin;
     435           0 :   PetscValidHeaderSpecific(lme,LME_CLASSID,1);
     436           0 :   PetscValidHeaderSpecific(bv,BV_CLASSID,2);
     437           0 :   PetscCheckSameComm(lme,1,bv,2);
     438           0 :   ierr = PetscObjectReference((PetscObject)bv);CHKERRQ(ierr);
     439           0 :   ierr = BVDestroy(&lme->V);CHKERRQ(ierr);
     440           0 :   lme->V = bv;
     441           0 :   ierr = PetscLogObjectParent((PetscObject)lme,(PetscObject)lme->V);CHKERRQ(ierr);
     442           0 :   PetscFunctionReturn(0);
     443             : }
     444             : 
     445             : /*@
     446             :    LMEGetBV - Obtain the basis vectors object associated to the matrix
     447             :    function solver.
     448             : 
     449             :    Not Collective
     450             : 
     451             :    Input Parameters:
     452             : .  lme - linear matrix equation context obtained from LMECreate()
     453             : 
     454             :    Output Parameter:
     455             : .  bv - basis vectors context
     456             : 
     457             :    Level: advanced
     458             : 
     459             : .seealso: LMESetBV()
     460             : @*/
     461           5 : PetscErrorCode LMEGetBV(LME lme,BV *bv)
     462             : {
     463             :   PetscErrorCode ierr;
     464             : 
     465           5 :   PetscFunctionBegin;
     466           5 :   PetscValidHeaderSpecific(lme,LME_CLASSID,1);
     467           5 :   PetscValidPointer(bv,2);
     468           5 :   if (!lme->V) {
     469           5 :     ierr = BVCreate(PetscObjectComm((PetscObject)lme),&lme->V);CHKERRQ(ierr);
     470           5 :     ierr = PetscObjectIncrementTabLevel((PetscObject)lme->V,(PetscObject)lme,0);CHKERRQ(ierr);
     471           5 :     ierr = PetscLogObjectParent((PetscObject)lme,(PetscObject)lme->V);CHKERRQ(ierr);
     472           5 :     ierr = PetscObjectSetOptions((PetscObject)lme->V,((PetscObject)lme)->options);CHKERRQ(ierr);
     473             :   }
     474           5 :   *bv = lme->V;
     475           5 :   PetscFunctionReturn(0);
     476             : }
     477             : 

Generated by: LCOV version 1.13