LCOV - code coverage report
Current view: top level - lme/interface - lmebasic.c (source / functions) Hit Total Coverage
Test: coverage.info Lines: 131 148 88.5 %
Date: 2019-09-16 06:01:52 Functions: 10 11 90.9 %

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

Generated by: LCOV version 1.13