Subversion Repositories slepc-dev

/*

      EPS routines related to options that can be set via the command-line

      or procedurally.

   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

   SLEPc - Scalable Library for Eigenvalue Problem Computations

   Copyright (c) 2002-2010, Universidad Politecnica de Valencia, Spain

   This file is part of SLEPc.

   SLEPc is free software: you can redistribute it and/or modify it under  the

   terms of version 3 of the GNU Lesser General Public License as published by

   the Free Software Foundation.

   SLEPc  is  distributed in the hope that it will be useful, but WITHOUT  ANY

   WARRANTY;  without even the implied warranty of MERCHANTABILITY or  FITNESS

   FOR  A  PARTICULAR PURPOSE. See the GNU Lesser General Public  License  for

   more details.

   You  should have received a copy of the GNU Lesser General  Public  License

   along with SLEPc. If not, see <http://www.gnu.org/licenses/>.

   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

*/

#include <private/epsimpl.h>   /*I "slepceps.h" I*/

#undef __FUNCT__  

#define __FUNCT__ "EPSSetFromOptions"

/*@

   EPSSetFromOptions - Sets EPS options from the options database.

   This routine must be called before EPSSetUp() if the user is to be

   allowed to set the solver type.

   Collective on EPS

   Input Parameters:

.  eps - the eigensolver context

   Notes:  

   To see all options, run your program with the -help option.

   Level: beginner

@*/

PetscErrorCode EPSSetFromOptions(EPS eps)

{

  PetscErrorCode   ierr;

  char             type[256],monfilename[PETSC_MAX_PATH_LEN];

  PetscBool        flg,val;

  PetscReal        r,nrma,nrmb,array[2];

  PetscScalar      s;

  PetscInt         i,j,k;

  const char       *bal_list[4] = {"none","oneside","twoside","user"};

  PetscViewer      monviewer;

  SlepcConvMonitor ctx;

  PetscFunctionBegin;

  PetscValidHeaderSpecific(eps,EPS_CLASSID,1);

  if (!EPSRegisterAllCalled) { ierr = EPSRegisterAll(PETSC_NULL);CHKERRQ(ierr); }

  ierr = PetscOptionsBegin(((PetscObject)eps)->comm,((PetscObject)eps)->prefix,"Eigenproblem Solver (EPS) Options","EPS");CHKERRQ(ierr);

    ierr = PetscOptionsList("-eps_type","Eigenproblem Solver method","EPSSetType",EPSList,(char*)(((PetscObject)eps)->type_name?((PetscObject)eps)->type_name:EPSKRYLOVSCHUR),type,256,&flg);CHKERRQ(ierr);

    if (flg) {

      ierr = EPSSetType(eps,type);CHKERRQ(ierr);

    }

    /*

      Set the type if it was never set.

    */

    if (!((PetscObject)eps)->type_name) {

      ierr = EPSSetType(eps,EPSKRYLOVSCHUR);CHKERRQ(ierr);

    }

    ierr = PetscOptionsBoolGroupBegin("-eps_hermitian","hermitian eigenvalue problem","EPSSetProblemType",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetProblemType(eps,EPS_HEP);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_gen_hermitian","generalized hermitian eigenvalue problem","EPSSetProblemType",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetProblemType(eps,EPS_GHEP);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_non_hermitian","non-hermitian eigenvalue problem","EPSSetProblemType",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetProblemType(eps,EPS_NHEP);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_gen_non_hermitian","generalized non-hermitian eigenvalue problem","EPSSetProblemType",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetProblemType(eps,EPS_GNHEP);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_pos_gen_non_hermitian","generalized non-hermitian eigenvalue problem with positive semi-definite B","EPSSetProblemType",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetProblemType(eps,EPS_PGNHEP);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroupEnd("-eps_gen_indefinite","generalized hermitian-indefinite eigenvalue problem","EPSSetProblemType",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetProblemType(eps,EPS_GHIEP);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroupBegin("-eps_ritz","Rayleigh-Ritz extraction","EPSSetExtraction",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetExtraction(eps,EPS_RITZ);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_harmonic","harmonic Ritz extraction","EPSSetExtraction",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetExtraction(eps,EPS_HARMONIC);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_harmonic_relative","relative harmonic Ritz extraction","EPSSetExtraction",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetExtraction(eps,EPS_HARMONIC_RELATIVE);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_harmonic_right","right harmonic Ritz extraction","EPSSetExtraction",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetExtraction(eps,EPS_HARMONIC_RIGHT);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_harmonic_largest","largest harmonic Ritz extraction","EPSSetExtraction",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetExtraction(eps,EPS_HARMONIC_LARGEST);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_refined","refined Ritz extraction","EPSSetExtraction",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetExtraction(eps,EPS_REFINED);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroupEnd("-eps_refined_harmonic","refined harmonic Ritz extraction","EPSSetExtraction",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetExtraction(eps,EPS_REFINED_HARMONIC);CHKERRQ(ierr);}

    if (!eps->balance) eps->balance = EPS_BALANCE_NONE;

    ierr = PetscOptionsEList("-eps_balance","Balancing method","EPSSetBalance",bal_list,4,bal_list[eps->balance-EPS_BALANCE_NONE],&i,&flg);CHKERRQ(ierr);

    if (flg) { eps->balance = (EPSBalance)(i+EPS_BALANCE_NONE); }

    r = j = PETSC_IGNORE;

    ierr = PetscOptionsInt("-eps_balance_its","Number of iterations in balancing","EPSSetBalance",eps->balance_its,&j,PETSC_NULL);CHKERRQ(ierr);

    ierr = PetscOptionsReal("-eps_balance_cutoff","Cutoff value in balancing","EPSSetBalance",eps->balance_cutoff,&r,PETSC_NULL);CHKERRQ(ierr);

    ierr = EPSSetBalance(eps,(EPSBalance)PETSC_IGNORE,j,r);CHKERRQ(ierr);

    r = i = PETSC_IGNORE;

    ierr = PetscOptionsInt("-eps_max_it","Maximum number of iterations","EPSSetTolerances",eps->max_it,&i,PETSC_NULL);CHKERRQ(ierr);

    ierr = PetscOptionsReal("-eps_tol","Tolerance","EPSSetTolerances",eps->tol,&r,PETSC_NULL);CHKERRQ(ierr);

    ierr = EPSSetTolerances(eps,r,i);CHKERRQ(ierr);

    ierr = PetscOptionsBoolGroupBegin("-eps_conv_eig","relative error convergence test","EPSSetConvergenceTest",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetConvergenceTest(eps,EPS_CONV_EIG);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_conv_norm","Convergence test relative to the eigenvalue and the matrix norms","EPSSetConvergenceTest",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetConvergenceTest(eps,EPS_CONV_NORM);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroupEnd("-eps_conv_abs","Absolute error convergence test","EPSSetConvergenceTest",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetConvergenceTest(eps,EPS_CONV_ABS);CHKERRQ(ierr);}

    i = j = k = PETSC_IGNORE;

    ierr = PetscOptionsInt("-eps_nev","Number of eigenvalues to compute","EPSSetDimensions",eps->nev,&i,PETSC_NULL);CHKERRQ(ierr);

    ierr = PetscOptionsInt("-eps_ncv","Number of basis vectors","EPSSetDimensions",eps->ncv,&j,PETSC_NULL);CHKERRQ(ierr);

    ierr = PetscOptionsInt("-eps_mpd","Maximum dimension of projected problem","EPSSetDimensions",eps->mpd,&k,PETSC_NULL);CHKERRQ(ierr);

    ierr = EPSSetDimensions(eps,i,j,k);CHKERRQ(ierr);

    /* -----------------------------------------------------------------------*/

    /*

      Cancels all monitors hardwired into code before call to EPSSetFromOptions()

    */

    flg  = PETSC_FALSE;

    ierr = PetscOptionsBool("-eps_monitor_cancel","Remove any hardwired monitor routines","EPSMonitorCancel",flg,&flg,PETSC_NULL);CHKERRQ(ierr);

    if (flg) {

      ierr = EPSMonitorCancel(eps);CHKERRQ(ierr);

    }

    /*

      Prints approximate eigenvalues and error estimates at each iteration

    */

    ierr = PetscOptionsString("-eps_monitor","Monitor first unconverged approximate eigenvalue and error estimate","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);CHKERRQ(ierr);

    if (flg) {

      ierr = PetscViewerASCIIOpen(((PetscObject)eps)->comm,monfilename,&monviewer);CHKERRQ(ierr);

      ierr = EPSMonitorSet(eps,EPSMonitorFirst,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);CHKERRQ(ierr);

    }

    ierr = PetscOptionsString("-eps_monitor_conv","Monitor approximate eigenvalues and error estimates as they converge","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);CHKERRQ(ierr);

    if (flg) {

      ierr = PetscNew(struct _n_SlepcConvMonitor,&ctx);CHKERRQ(ierr);

      ierr = PetscViewerASCIIOpen(((PetscObject)eps)->comm,monfilename,&ctx->viewer);CHKERRQ(ierr);

      ierr = EPSMonitorSet(eps,EPSMonitorConverged,ctx,(PetscErrorCode (*)(void**))SlepcConvMonitorDestroy);CHKERRQ(ierr);

    }

    ierr = PetscOptionsString("-eps_monitor_all","Monitor approximate eigenvalues and error estimates","EPSMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);CHKERRQ(ierr);

    if (flg) {

      ierr = PetscViewerASCIIOpen(((PetscObject)eps)->comm,monfilename,&monviewer);CHKERRQ(ierr);

      ierr = EPSMonitorSet(eps,EPSMonitorAll,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);CHKERRQ(ierr);

      ierr = EPSSetTrackAll(eps,PETSC_TRUE);CHKERRQ(ierr);

    }

    flg = PETSC_FALSE;

    ierr = PetscOptionsBool("-eps_monitor_draw","Monitor first unconverged approximate eigenvalue and error estimate graphically","EPSMonitorSet",flg,&flg,PETSC_NULL);CHKERRQ(ierr);

    if (flg) {

      ierr = EPSMonitorSet(eps,EPSMonitorLG,PETSC_NULL,PETSC_NULL);CHKERRQ(ierr);

    }

    flg = PETSC_FALSE;

    ierr = PetscOptionsBool("-eps_monitor_draw_all","Monitor error estimates graphically","EPSMonitorSet",flg,&flg,PETSC_NULL);CHKERRQ(ierr);

    if (flg) {

      ierr = EPSMonitorSet(eps,EPSMonitorLGAll,PETSC_NULL,PETSC_NULL);CHKERRQ(ierr);

      ierr = EPSSetTrackAll(eps,PETSC_TRUE);CHKERRQ(ierr);

    }

  /* -----------------------------------------------------------------------*/

    ierr = PetscOptionsScalar("-eps_target","Value of the target","EPSSetTarget",eps->target,&s,&flg);CHKERRQ(ierr);

    if (flg) {

      ierr = EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);CHKERRQ(ierr);

      ierr = EPSSetTarget(eps,s);CHKERRQ(ierr);

    }

    k = 2;

    ierr = PetscOptionsRealArray("-eps_interval","Computational interval (two real values separated with a comma without spaces)","EPSSetInterval",array,&k,&flg);CHKERRQ(ierr);

    if (flg) {

      if (k<2) SETERRQ(((PetscObject)eps)->comm,PETSC_ERR_ARG_SIZ,"Must pass two values in -eps_interval (comma-separated without spaces)");

      ierr = EPSSetWhichEigenpairs(eps,EPS_ALL);CHKERRQ(ierr);

      ierr = EPSSetInterval(eps,array[0],array[1]);CHKERRQ(ierr);

    }

    ierr = PetscOptionsBoolGroupBegin("-eps_largest_magnitude","compute largest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetWhichEigenpairs(eps,EPS_LARGEST_MAGNITUDE);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_smallest_magnitude","compute smallest eigenvalues in magnitude","EPSSetWhichEigenpairs",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetWhichEigenpairs(eps,EPS_SMALLEST_MAGNITUDE);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_largest_real","compute largest real parts","EPSSetWhichEigenpairs",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetWhichEigenpairs(eps,EPS_LARGEST_REAL);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_smallest_real","compute smallest real parts","EPSSetWhichEigenpairs",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetWhichEigenpairs(eps,EPS_SMALLEST_REAL);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_largest_imaginary","compute largest imaginary parts","EPSSetWhichEigenpairs",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetWhichEigenpairs(eps,EPS_LARGEST_IMAGINARY);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_smallest_imaginary","compute smallest imaginary parts","EPSSetWhichEigenpairs",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetWhichEigenpairs(eps,EPS_SMALLEST_IMAGINARY);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_target_magnitude","compute nearest eigenvalues to target","EPSSetWhichEigenpairs",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetWhichEigenpairs(eps,EPS_TARGET_MAGNITUDE);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_target_real","compute eigenvalues with real parts close to target","EPSSetWhichEigenpairs",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetWhichEigenpairs(eps,EPS_TARGET_REAL);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroup("-eps_target_imaginary","compute eigenvalues with imaginary parts close to target","EPSSetWhichEigenpairs",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetWhichEigenpairs(eps,EPS_TARGET_IMAGINARY);CHKERRQ(ierr);}

    ierr = PetscOptionsBoolGroupEnd("-eps_all","compute all eigenvalues in an interval","EPSSetWhichEigenpairs",&flg);CHKERRQ(ierr);

    if (flg) {ierr = EPSSetWhichEigenpairs(eps,EPS_ALL);CHKERRQ(ierr);}

    ierr = PetscOptionsBool("-eps_left_vectors","Compute left eigenvectors also","EPSSetLeftVectorsWanted",eps->leftvecs,&val,&flg);CHKERRQ(ierr);

    if (flg) {

      ierr = EPSSetLeftVectorsWanted(eps,val);CHKERRQ(ierr);

    }

    ierr = PetscOptionsBool("-eps_true_residual","Compute true residuals explicitly","EPSSetTrueResidual",eps->trueres,&val,&flg);CHKERRQ(ierr);

    if (flg) {

      ierr = EPSSetTrueResidual(eps,val);CHKERRQ(ierr);

    }

    nrma = nrmb = PETSC_IGNORE;

    ierr = PetscOptionsReal("-eps_norm_a","Norm of matrix A","EPSSetMatrixNorms",eps->nrma,&nrma,PETSC_NULL);CHKERRQ(ierr);

    ierr = PetscOptionsReal("-eps_norm_b","Norm of matrix B","EPSSetMatrixNorms",eps->nrmb,&nrmb,PETSC_NULL);CHKERRQ(ierr);

    ierr = EPSSetMatrixNorms(eps,nrma,nrmb,eps->adaptive);CHKERRQ(ierr);

    ierr = PetscOptionsBool("-eps_norms_adaptive","Update the value of matrix norms adaptively","EPSSetMatrixNorms",eps->adaptive,&val,&flg);CHKERRQ(ierr);

    if (flg) {

      ierr = EPSSetMatrixNorms(eps,PETSC_IGNORE,PETSC_IGNORE,val);CHKERRQ(ierr);

    }

    ierr = PetscOptionsName("-eps_view","Print detailed information on solver used","EPSView",0);CHKERRQ(ierr);

    ierr = PetscOptionsName("-eps_view_binary","Save the matrices associated to the eigenproblem","EPSSetFromOptions",0);CHKERRQ(ierr);

    ierr = PetscOptionsName("-eps_plot_eigs","Make a plot of the computed eigenvalues","EPSSolve",0);CHKERRQ(ierr);

    if (eps->ops->setfromoptions) {

      ierr = (*eps->ops->setfromoptions)(eps);CHKERRQ(ierr);

    }

    ierr = PetscObjectProcessOptionsHandlers((PetscObject)eps);CHKERRQ(ierr);

  ierr = PetscOptionsEnd();CHKERRQ(ierr);

  if (!eps->ip) { ierr = EPSGetIP(eps,&eps->ip);CHKERRQ(ierr); }

  ierr = IPSetFromOptions(eps->ip);CHKERRQ(ierr);

  ierr = STSetFromOptions(eps->OP);CHKERRQ(ierr);

  PetscFunctionReturn(0);

}

#undef __FUNCT__  

#define __FUNCT__ "EPSGetTolerances"

/*@

   EPSGetTolerances - Gets the tolerance and maximum iteration count used

   by the EPS convergence tests.

   Not Collective

   Input Parameter:

.  eps - the eigensolver context

   Output Parameters:

+  tol - the convergence tolerance

-  maxits - maximum number of iterations

   Notes:

   The user can specify PETSC_NULL for any parameter that is not needed.

   Level: intermediate

.seealso: EPSSetTolerances()

@*/

PetscErrorCode EPSGetTolerances(EPS eps,PetscReal *tol,PetscInt *maxits)

{

  PetscFunctionBegin;

  PetscValidHeaderSpecific(eps,EPS_CLASSID,1);

  if (tol)    *tol    = eps->tol;

  if (maxits) *maxits = eps->max_it;

  PetscFunctionReturn(0);

}

#undef __FUNCT__  

#define __FUNCT__ "EPSSetTolerances"

/*@

   EPSSetTolerances - Sets the tolerance and maximum iteration count used

   by the EPS convergence tests.

   Logically Collective on EPS

   Input Parameters:

+  eps - the eigensolver context

.  tol - the convergence tolerance

-  maxits - maximum number of iterations to use

   Options Database Keys:

+  -eps_tol <tol> - Sets the convergence tolerance

-  -eps_max_it <maxits> - Sets the maximum number of iterations allowed

   Notes:

   Use PETSC_IGNORE for an argument that need not be changed.

   Use PETSC_DECIDE for maxits to assign a reasonably good value, which is

   dependent on the solution method.

   Level: intermediate

.seealso: EPSGetTolerances()

@*/

PetscErrorCode EPSSetTolerances(EPS eps,PetscReal tol,PetscInt maxits)

{

  PetscFunctionBegin;

  PetscValidHeaderSpecific(eps,EPS_CLASSID,1);

  PetscValidLogicalCollectiveReal(eps,tol,2);

  PetscValidLogicalCollectiveInt(eps,maxits,3);

  if (tol != PETSC_IGNORE) {

    if (tol == PETSC_DEFAULT) {

      eps->tol = 1e-7;

    } else {

      if (tol < 0.0) SETERRQ(((PetscObject)eps)->comm,PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");

      eps->tol = tol;

    }

  }

  if (maxits != PETSC_IGNORE) {

    if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {

      eps->max_it = 0;

      eps->setupcalled = 0;

    } else {

      if (maxits < 0) SETERRQ(((PetscObject)eps)->comm,PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");

      eps->max_it = maxits;

    }

  }

  PetscFunctionReturn(0);

}

#undef __FUNCT__  

#define __FUNCT__ "EPSGetDimensions"

/*@

   EPSGetDimensions - Gets the number of eigenvalues to compute

   and the dimension of the subspace.

   Not Collective

   Input Parameter:

.  eps - the eigensolver context

   Output Parameters:

+  nev - number of eigenvalues to compute

.  ncv - the maximum dimension of the subspace to be used by the solver

-  mpd - the maximum dimension allowed for the projected problem

   Notes:

   The user can specify PETSC_NULL for any parameter that is not needed.

   Level: intermediate

.seealso: EPSSetDimensions()

@*/

PetscErrorCode EPSGetDimensions(EPS eps,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)

{

  PetscFunctionBegin;

  PetscValidHeaderSpecific(eps,EPS_CLASSID,1);

  if (nev) *nev = eps->nev;

  if (ncv) *ncv = eps->ncv;

  if (mpd) *mpd = eps->mpd;

  PetscFunctionReturn(0);

}

#undef __FUNCT__  

#define __FUNCT__ "EPSSetDimensions"

/*@

   EPSSetDimensions - Sets the number of eigenvalues to compute

   and the dimension of the subspace.

   Logically Collective on EPS

   Input Parameters:

+  eps - the eigensolver context

.  nev - number of eigenvalues to compute

.  ncv - the maximum dimension of the subspace to be used by the solver

-  mpd - the maximum dimension allowed for the projected problem

   Options Database Keys:

+  -eps_nev <nev> - Sets the number of eigenvalues

.  -eps_ncv <ncv> - Sets the dimension of the subspace

-  -eps_mpd <mpd> - Sets the maximum projected dimension

   Notes:

   Use PETSC_IGNORE to retain the previous value of any parameter.

   Use PETSC_DECIDE for ncv and mpd to assign a reasonably good value, which is

   dependent on the solution method.

   The parameters ncv and mpd are intimately related, so that the user is advised

   to set one of them at most. Normal usage is the following:

   (a) In cases where nev is small, the user sets ncv (a reasonable default is 2*nev).

   (b) In cases where nev is large, the user sets mpd.

   The value of ncv should always be between nev and (nev+mpd), typically

   ncv=nev+mpd. If nev is not too large, mpd=nev is a reasonable choice, otherwise

   a smaller value should be used.

   When computing all eigenvalues in an interval, see EPSSetInterval(), the

   meaning of nev changes. In that case, the number of eigenvalues in the

   interval is not known a priori; the meaning of nev is then the number of

   eigenvalues that are computed at a time when sweeping the interval from one

   end to the other. The value of nev in this case may have an impact on overall

   performance. The value of ncv should not be assigned in this case.

   Level: intermediate

.seealso: EPSGetDimensions(), EPSSetInterval()

@*/

PetscErrorCode EPSSetDimensions(EPS eps,PetscInt nev,PetscInt ncv,PetscInt mpd)

{

  PetscFunctionBegin;

  PetscValidHeaderSpecific(eps,EPS_CLASSID,1);

  PetscValidLogicalCollectiveInt(eps,nev,2);

  PetscValidLogicalCollectiveInt(eps,ncv,3);

  PetscValidLogicalCollectiveInt(eps,mpd,4);

  if (nev != PETSC_IGNORE) {

    if (nev<1) SETERRQ(((PetscObject)eps)->comm,PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");

    eps->nev = nev;

    eps->setupcalled = 0;

  }

  if (ncv != PETSC_IGNORE) {

    if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {

      eps->ncv = 0;

    } else {

      if (ncv<1) SETERRQ(((PetscObject)eps)->comm,PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");

      eps->ncv = ncv;

    }

    eps->setupcalled = 0;

  }

  if (mpd != PETSC_IGNORE) {

    if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {

      eps->mpd = 0;

    } else {

      if (mpd<1) SETERRQ(((PetscObject)eps)->comm,PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");

      eps->mpd = mpd;

    }

  }

  PetscFunctionReturn(0);

}

#undef __FUNCT__  

#define __FUNCT__ "EPSSetWhichEigenpairs"

/*@

   EPSSetWhichEigenpairs - Specifies which portion of the spectrum is

   to be sought.

   Logically Collective on EPS

   Input Parameters:

+  eps   - eigensolver context obtained from EPSCreate()

-  which - the portion of the spectrum to be sought

   Possible values:

   The parameter 'which' can have one of these values

+     EPS_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)

.     EPS_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude

.     EPS_LARGEST_REAL - largest real parts

.     EPS_SMALLEST_REAL - smallest real parts

.     EPS_LARGEST_IMAGINARY - largest imaginary parts

.     EPS_SMALLEST_IMAGINARY - smallest imaginary parts

.     EPS_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)

.     EPS_TARGET_REAL - eigenvalues with real part closest to target

.     EPS_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target

.     EPS_ALL - all eigenvalues contained in a given interval

-     EPS_WHICH_USER - user defined ordering set with EPSSetEigenvalueComparison()

   Options Database Keys:

+   -eps_largest_magnitude - Sets largest eigenvalues in magnitude

.   -eps_smallest_magnitude - Sets smallest eigenvalues in magnitude

.   -eps_largest_real - Sets largest real parts

.   -eps_smallest_real - Sets smallest real parts

.   -eps_largest_imaginary - Sets largest imaginary parts

.   -eps_smallest_imaginary - Sets smallest imaginary parts

.   -eps_target_magnitude - Sets eigenvalues closest to target

.   -eps_target_real - Sets real parts closest to target

.   -eps_target_imaginary - Sets imaginary parts closest to target

-   -eps_all - Sets all eigenvalues in an interval

   Notes:

   Not all eigensolvers implemented in EPS account for all the possible values

   stated above. Also, some values make sense only for certain types of

   problems. If SLEPc is compiled for real numbers EPS_LARGEST_IMAGINARY

   and EPS_SMALLEST_IMAGINARY use the absolute value of the imaginary part

   for eigenvalue selection.

   The target is a scalar value provided with EPSSetTarget().

   The criterion EPS_TARGET_IMAGINARY is available only in case PETSc and

   SLEPc have been built with complex scalars.

   EPS_ALL is intended for use in combination with an interval (see

   EPSSetInterval()), when all eigenvalues within the interval are requested.

   In that case, the number of eigenvalues is unknown, so the nev parameter

   has a different sense, see EPSSetDimensions().

   Level: intermediate

.seealso: EPSGetWhichEigenpairs(), EPSSetTarget(), EPSSetInterval(),

          EPSSetDimensions(), EPSSetEigenvalueComparison(),

          EPSSortEigenvalues(), EPSWhich

@*/

PetscErrorCode EPSSetWhichEigenpairs(EPS eps,EPSWhich which)

{

  PetscFunctionBegin;

  PetscValidHeaderSpecific(eps,EPS_CLASSID,1);

  PetscValidLogicalCollectiveEnum(eps,which,2);

  if (which!=PETSC_IGNORE) {

    if (which==PETSC_DECIDE || which==PETSC_DEFAULT) eps->which = (EPSWhich)0;

    else switch (which) {

      case EPS_LARGEST_MAGNITUDE:

      case EPS_SMALLEST_MAGNITUDE:

      case EPS_LARGEST_REAL:

      case EPS_SMALLEST_REAL:

      case EPS_LARGEST_IMAGINARY:

      case EPS_SMALLEST_IMAGINARY:

      case EPS_TARGET_MAGNITUDE:

      case EPS_TARGET_REAL:

#if defined(PETSC_USE_COMPLEX)

      case EPS_TARGET_IMAGINARY:

#endif

      case EPS_ALL:

      case EPS_WHICH_USER:

        if (eps->which != which) {

          eps->setupcalled = 0;

          eps->which = which;

        }

        break;

      default:

        SETERRQ(((PetscObject)eps)->comm,PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");

    }

  }

  PetscFunctionReturn(0);

}

#undef __FUNCT__  

#define __FUNCT__ "EPSGetWhichEigenpairs"

/*@C

   EPSGetWhichEigenpairs - Returns which portion of the spectrum is to be

   sought.

   Not Collective

   Input Parameter:

.  eps - eigensolver context obtained from EPSCreate()

   Output Parameter:

.  which - the portion of the spectrum to be sought

   Notes:

   See EPSSetWhichEigenpairs() for possible values of 'which'.

   Level: intermediate

.seealso: EPSSetWhichEigenpairs(), EPSWhich

@*/

PetscErrorCode EPSGetWhichEigenpairs(EPS eps,EPSWhich *which)

{

  PetscFunctionBegin;

  PetscValidHeaderSpecific(eps,EPS_CLASSID,1);

  PetscValidPointer(which,2);

  *which = eps->which;

  PetscFunctionReturn(0);

}

#undef __FUNCT__  

#define __FUNCT__ "EPSSetLeftVectorsWanted"

/*@

   EPSSetLeftVectorsWanted - Specifies which eigenvectors are required.

   Logically Collective on EPS

   Input Parameters:

+  eps      - the eigensolver context

-  leftvecs - whether left eigenvectors are required or not

   Options Database Keys:

.  -eps_left_vectors <boolean> - Sets/resets the boolean flag 'leftvecs'

   Notes:

   If the user sets leftvecs=PETSC_TRUE then the solver uses a variant of

   the algorithm that computes both right and left eigenvectors. This is

   usually much more costly. This option is not available in all solvers.

   Level: intermediate

.seealso: EPSGetLeftVectorsWanted(), EPSGetEigenvectorLeft()

@*/

PetscErrorCode EPSSetLeftVectorsWanted(EPS eps,PetscBool leftvecs)

{

  PetscFunctionBegin;

  PetscValidHeaderSpecific(eps,EPS_CLASSID,1);

  PetscValidLogicalCollectiveBool(eps,leftvecs,2);

  if (eps->leftvecs != leftvecs) {

    eps->leftvecs = leftvecs;

    eps->setupcalled = 0;

  }

  PetscFunctionReturn(0);

}

#undef __FUNCT__  

#define __FUNCT__ "EPSGetLeftVectorsWanted"

/*@

   EPSGetLeftVectorsWanted - Returns the flag indicating whether left

   eigenvectors are required or not.

   Not Collective

   Input Parameter:

.  eps - the eigensolver context

   Output Parameter:

.  leftvecs - the returned flag

   Level: intermediate

.seealso: EPSSetLeftVectorsWanted(), EPSWhich

@*/

PetscErrorCode EPSGetLeftVectorsWanted(EPS eps,PetscBool *leftvecs)

{

  PetscFunctionBegin;

  PetscValidHeaderSpecific(eps,EPS_CLASSID,1);

  PetscValidPointer(leftvecs,2);

  *leftvecs = eps->leftvecs;

  PetscFunctionReturn(0);

}

#undef __FUNCT__  

#define __FUNCT__ "EPSSetMatrixNorms"

/*@

   EPSSetMatrixNorms - Gives the reference values of the matrix norms

   and specifies whether these values should be improved adaptively.

   Logically Collective on EPS

   Input Parameters:

+  eps      - the eigensolver context

.  nrma     - a reference value for the norm of matrix A

.  nrmb     - a reference value for the norm of matrix B

-  adaptive - whether matrix norms are improved adaptively

   Options Database Keys:

+  -eps_norm_a <nrma> - norm of A

.  -eps_norm_b <nrma> - norm of B

-  -eps_norms_adaptive <boolean> - Sets/resets the boolean flag 'adaptive'

   Notes:

   If the user sets adaptive=PETSC_FALSE then the solver uses the values

   of nrma and nrmb for the matrix norms, and these values do not change

   throughout the iteration.

   If the user sets adaptive=PETSC_TRUE then the solver tries to adaptively

   improve the supplied values, with the numerical information generated

   during the iteration. This option is not available in all solvers.

   If a passed value is PETSC_DEFAULT, the corresponding norm will be set to 1.

   If a passed value is PETSC_DETERMINE, the corresponding norm will be computed

   as the NORM_INFINITY with MatNorm().

   Level: intermediate

.seealso: EPSGetMatrixNorms()

@*/

PetscErrorCode EPSSetMatrixNorms(EPS eps,PetscReal nrma,PetscReal nrmb,PetscBool adaptive)

{

  PetscFunctionBegin;

  PetscValidHeaderSpecific(eps,EPS_CLASSID,1);

  PetscValidLogicalCollectiveReal(eps,nrma,2);

  PetscValidLogicalCollectiveReal(eps,nrmb,3);