/*@
MatFDColoringSetParameters - Sets the parameters for the sparse approximation of
a Jacobian matrix using finite differences.
Logically Collective on MatFDColoring
The Jacobian is estimated with the differencing approximation
.vb
F'(u)_{:,i} = [F(u+h*dx_{i}) - F(u)]/h where
h = error_rel*u[i] if abs(u[i]) > umin
= +/- error_rel*umin otherwise, with +/- determined by the sign of u[i]
dx_{i} = (0, ... 1, .... 0)
.ve
Input Parameters:
+ coloring - the coloring context
. error_rel - relative error
- umin - minimum allowable u-value magnitude
Level: advanced
.keywords: Mat, finite differences, coloring, set, parameters
.seealso: MatFDColoringCreate(), MatFDColoringSetFromOptions()
@*/
PetscErrorCode MatFDColoringSetParameters(MatFDColoring matfd,PetscReal error,PetscReal umin)
{
PetscFunctionBegin;
PetscValidHeaderSpecific(matfd,MAT_FDCOLORING_CLASSID,1);
PetscValidLogicalCollectiveReal(matfd,error,2);
PetscValidLogicalCollectiveReal(matfd,umin,3);
if (error != PETSC_DEFAULT) matfd->error_rel = error;
if (umin != PETSC_DEFAULT) matfd->umin = umin;
PetscFunctionReturn(0);
}
/*@
KSPChebyshevSetEigenvalues - Sets estimates for the extreme eigenvalues
of the preconditioned problem.
Logically Collective on KSP
Input Parameters:
+ ksp - the Krylov space context
- emax, emin - the eigenvalue estimates
Options Database:
. -ksp_chebyshev_eigenvalues emin,emax
Note: If you run with the Krylov method of KSPCG with the option -ksp_monitor_singular_value it will
for that given matrix and preconditioner an estimate of the extreme eigenvalues.
Level: intermediate
.keywords: KSP, Chebyshev, set, eigenvalues
@*/
PetscErrorCode KSPChebyshevSetEigenvalues(KSP ksp,PetscReal emax,PetscReal emin)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(ksp,KSP_CLASSID,1);
PetscValidLogicalCollectiveReal(ksp,emax,2);
PetscValidLogicalCollectiveReal(ksp,emin,3);
ierr = PetscTryMethod(ksp,"KSPChebyshevSetEigenvalues_C",(KSP,PetscReal,PetscReal),(ksp,emax,emin));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
EPSSetInterval - Defines the computational interval for spectrum slicing.
Logically Collective on EPS
Input Parameters:
+ eps - eigensolver context
. inta - left end of the interval
- intb - right end of the interval
Options Database Key:
. -eps_interval <a,b> - set [a,b] as the interval of interest
Notes:
Spectrum slicing is a technique employed for computing all eigenvalues of
symmetric eigenproblems in a given interval. This function provides the
interval to be considered. It must be used in combination with EPS_ALL, see
EPSSetWhichEigenpairs().
In the command-line option, two values must be provided. For an open interval,
one can give an infinite, e.g., -eps_interval 1.0,inf or -eps_interval -inf,1.0.
An open interval in the programmatic interface can be specified with
PETSC_MAX_REAL and -PETSC_MAX_REAL.
Level: intermediate
.seealso: EPSGetInterval(), EPSSetWhichEigenpairs()
@*/
PetscErrorCode EPSSetInterval(EPS eps,PetscReal inta,PetscReal intb)
{
PetscFunctionBegin;
PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
PetscValidLogicalCollectiveReal(eps,inta,2);
PetscValidLogicalCollectiveReal(eps,intb,3);
if (inta>=intb) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_WRONG,"Badly defined interval, must be inta<intb");
eps->inta = inta;
eps->intb = intb;
eps->state = EPS_STATE_INITIAL;
PetscFunctionReturn(0);
}
/*@
TSAdaptSetClip - Sets the admissible decrease/increase factor in step size
Logically collective on TSAdapt
Input Arguments:
+ adapt - adaptive controller context
. low - admissible decrease factor
- high - admissible increase factor
Options Database Keys:
. -ts_adapt_clip <low>,<high> - to set admissible time step decrease and increase factors
Level: intermediate
.seealso: TSAdaptChoose(), TSAdaptGetClip()
@*/
PetscErrorCode TSAdaptSetClip(TSAdapt adapt,PetscReal low,PetscReal high)
{
PetscFunctionBegin;
PetscValidHeaderSpecific(adapt,TSADAPT_CLASSID,1);
PetscValidLogicalCollectiveReal(adapt,low,2);
PetscValidLogicalCollectiveReal(adapt,high,3);
if (low != PETSC_DEFAULT && low < 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Decrease factor %g must be non negative",(double)low);
if (low != PETSC_DEFAULT && low > 1) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Decrease factor %g must be less than one",(double)low);
if (high != PETSC_DEFAULT && high < 1) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Increase factor %g must be geather than one",(double)high);
if (low != PETSC_DEFAULT) adapt->clip[0] = low;
if (high != PETSC_DEFAULT) adapt->clip[1] = high;
PetscFunctionReturn(0);
}
/*@
KSPChebyshevSetEstimateEigenvalues - Automatically estimate the eigenvalues to use for Chebyshev
Logically Collective on KSP
Input Parameters:
+ ksp - the Krylov space context
. a - multiple of min eigenvalue estimate to use for min Chebyshev bound (or PETSC_DECIDE)
. b - multiple of max eigenvalue estimate to use for min Chebyshev bound (or PETSC_DECIDE)
. c - multiple of min eigenvalue estimate to use for max Chebyshev bound (or PETSC_DECIDE)
- d - multiple of max eigenvalue estimate to use for max Chebyshev bound (or PETSC_DECIDE)
Options Database:
. -ksp_chebyshev_estimate_eigenvalues a,b,c,d
Notes:
The Chebyshev bounds are estimated using
.vb
minbound = a*minest + b*maxest
maxbound = c*minest + d*maxest
.ve
The default configuration targets the upper part of the spectrum for use as a multigrid smoother, so only the maximum eigenvalue estimate is used.
The minimum eigenvalue estimate obtained by Krylov iteration is typically not accurate until the method has converged.
If 0.0 is passed for all transform arguments (a,b,c,d), eigenvalue estimation is disabled.
The default transform is (0,0.1; 0,1.1) which targets the "upper" part of the spectrum, as desirable for use with multigrid.
Level: intermediate
.keywords: KSP, Chebyshev, set, eigenvalues, PCMG
@*/
PetscErrorCode KSPChebyshevSetEstimateEigenvalues(KSP ksp,PetscReal a,PetscReal b,PetscReal c,PetscReal d)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(ksp,KSP_CLASSID,1);
PetscValidLogicalCollectiveReal(ksp,a,2);
PetscValidLogicalCollectiveReal(ksp,b,3);
PetscValidLogicalCollectiveReal(ksp,c,4);
PetscValidLogicalCollectiveReal(ksp,d,5);
ierr = PetscTryMethod(ksp,"KSPChebyshevSetEstimateEigenvalues_C",(KSP,PetscReal,PetscReal,PetscReal,PetscReal),(ksp,a,b,c,d));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
TSAlpha2SetParams - sets the algorithmic parameters for TSALPHA2
Logically Collective on TS
Second-order accuracy can be obtained so long as:
\gamma = 1/2 + alpha_m - alpha_f
\beta = 1/4 (1 + alpha_m - alpha_f)^2
Unconditional stability requires:
\alpha_m >= \alpha_f >= 1/2
Input Parameter:
+ ts - timestepping context
. \alpha_m - algorithmic paramenter
. \alpha_f - algorithmic paramenter
. \gamma - algorithmic paramenter
- \beta - algorithmic paramenter
Options Database:
+ -ts_alpha_alpha_m <alpha_m>
. -ts_alpha_alpha_f <alpha_f>
. -ts_alpha_gamma <gamma>
- -ts_alpha_beta <beta>
Note:
Use of this function is normally only required to hack TSALPHA2 to
use a modified integration scheme. Users should call
TSAlpha2SetRadius() to set the desired spectral radius of the methods
(i.e. high-frequency damping) in order so select optimal values for
these parameters.
Level: advanced
.seealso: TSAlpha2SetRadius(), TSAlpha2GetParams()
@*/
PetscErrorCode TSAlpha2SetParams(TS ts,PetscReal alpha_m,PetscReal alpha_f,PetscReal gamma,PetscReal beta)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(ts,TS_CLASSID,1);
PetscValidLogicalCollectiveReal(ts,alpha_m,2);
PetscValidLogicalCollectiveReal(ts,alpha_f,3);
PetscValidLogicalCollectiveReal(ts,gamma,4);
PetscValidLogicalCollectiveReal(ts,beta,5);
ierr = PetscTryMethod(ts,"TSAlpha2SetParams_C",(TS,PetscReal,PetscReal,PetscReal,PetscReal),(ts,alpha_m,alpha_f,gamma,beta));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
TSAdaptSetSafety - Set safety factors
Logically collective on TSAdapt
Input Arguments:
+ adapt - adaptive controller context
. safety - safety factor relative to target error/stability goal
- reject_safety - extra safety factor to apply if the last step was rejected
Options Database Keys:
+ -ts_adapt_safety <safety> - to set safety factor
- -ts_adapt_reject_safety <reject_safety> - to set reject safety factor
Level: intermediate
.seealso: TSAdapt, TSAdaptGetSafety(), TSAdaptChoose()
@*/
PetscErrorCode TSAdaptSetSafety(TSAdapt adapt,PetscReal safety,PetscReal reject_safety)
{
PetscFunctionBegin;
PetscValidHeaderSpecific(adapt,TSADAPT_CLASSID,1);
PetscValidLogicalCollectiveReal(adapt,safety,2);
PetscValidLogicalCollectiveReal(adapt,reject_safety,3);
if (safety != PETSC_DEFAULT && safety < 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Safety factor %g must be non negative",(double)safety);
if (safety != PETSC_DEFAULT && safety > 1) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Safety factor %g must be less than one",(double)safety);
if (reject_safety != PETSC_DEFAULT && reject_safety < 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Reject safety factor %g must be non negative",(double)reject_safety);
if (reject_safety != PETSC_DEFAULT && reject_safety > 1) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Reject safety factor %g must be less than one",(double)reject_safety);
if (safety != PETSC_DEFAULT) adapt->safety = safety;
if (reject_safety != PETSC_DEFAULT) adapt->reject_safety = reject_safety;
PetscFunctionReturn(0);
}
/*@
NEPSetRefine - Specifies the refinement type (and options) to be used
after the solve.
Logically Collective on NEP
Input Parameters:
+ nep - the nonlinear eigensolver context
. refine - refinement type
. tol - the convergence tolerance
- its - maximum number of refinement iterations
Options Database Keys:
+ -nep_refine <type> - refinement type, one of <none,simple,multiple>
. -nep_refine_tol <tol> - the tolerance
- -nep_refine_its <its> - number of iterations
Notes:
By default, iterative refinement is disabled, since it may be very
costly. There are two possible refinement strategies: simple and multiple.
The simple approach performs iterative refinement on each of the
converged eigenpairs individually, whereas the multiple strategy works
with the invariant pair as a whole, refining all eigenpairs simultaneously.
The latter may be required for the case of multiple eigenvalues.
The tol and its parameters specify the stopping criterion. In the simple
method, refinement continues until the residual of each eigenpair is
below the tolerance (tol defaults to the NEP tol, but may be set to a
different value). In contrast, the multiple method simply performs its
refinement iterations (just one by default).
Level: intermediate
.seealso: NEPGetRefine()
@*/
PetscErrorCode NEPSetRefine(NEP nep,NEPRefine refine,PetscReal tol,PetscInt its)
{
PetscFunctionBegin;
PetscValidHeaderSpecific(nep,NEP_CLASSID,1);
PetscValidLogicalCollectiveEnum(nep,refine,2);
PetscValidLogicalCollectiveReal(nep,tol,3);
PetscValidLogicalCollectiveInt(nep,its,4);
nep->refine = refine;
if (refine) { /* process parameters only if not REFINE_NONE */
if (tol == PETSC_DEFAULT || tol == PETSC_DECIDE) {
nep->reftol = nep->rtol;
} else {
if (tol<=0.0) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
nep->reftol = tol;
}
if (its==PETSC_DECIDE || its==PETSC_DEFAULT) {
nep->rits = PETSC_DEFAULT;
} else {
if (its<=0) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be > 0");
nep->rits = its;
}
}
nep->state = NEP_STATE_INITIAL;
PetscFunctionReturn(0);
}
/*@
TSAdaptSetStepLimits - Set the minimum and maximum step sizes to be considered by the controller
Logically collective on TSAdapt
Input Arguments:
+ adapt - time step adaptivity context, usually gotten with TSGetAdapt()
. hmin - minimum time step
- hmax - maximum time step
Options Database Keys:
+ -ts_adapt_dt_min <min> - to set minimum time step
- -ts_adapt_dt_max <max> - to set maximum time step
Level: intermediate
.seealso: TSAdapt, TSAdaptGetStepLimits(), TSAdaptChoose()
@*/
PetscErrorCode TSAdaptSetStepLimits(TSAdapt adapt,PetscReal hmin,PetscReal hmax)
{
PetscFunctionBegin;
PetscValidHeaderSpecific(adapt,TSADAPT_CLASSID,1);
PetscValidLogicalCollectiveReal(adapt,hmin,2);
PetscValidLogicalCollectiveReal(adapt,hmax,3);
if (hmin != PETSC_DEFAULT && hmin < 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Minimum time step %g must be non negative",(double)hmin);
if (hmax != PETSC_DEFAULT && hmax < 0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Minimum time step %g must be non negative",(double)hmax);
if (hmin != PETSC_DEFAULT) adapt->dt_min = hmin;
if (hmax != PETSC_DEFAULT) adapt->dt_max = hmax;
hmin = adapt->dt_min;
hmax = adapt->dt_max;
if (hmax <= hmin) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Maximum time step %g must geather than minimum time step %g",(double)hmax,(double)hmin);
PetscFunctionReturn(0);
}
EXTERN_C_END
#undef __FUNCT__
#define __FUNCT__ "TSRKSetTolerance"
/*@
TSRKSetTolerance - Sets the total error the RK explicit time integrators
will allow over the given time interval.
Logically Collective on TS
Input parameters:
+ ts - the time-step context
- aabs - the absolute tolerance
Level: intermediate
.keywords: RK, tolerance
.seealso: TSSundialsSetTolerance()
@*/
PetscErrorCode TSRKSetTolerance(TS ts,PetscReal aabs)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidLogicalCollectiveReal(ts,aabs,2);
ierr = PetscTryMethod(ts,"TSRKSetTolerance_C",(TS,PetscReal),(ts,aabs));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
EPSSetBalance - Specifies the balancing technique to be employed by the
eigensolver, and some parameters associated to it.
Logically Collective on EPS
Input Parameters:
+ eps - the eigensolver context
. bal - the balancing method, one of EPS_BALANCE_NONE, EPS_BALANCE_ONESIDE,
EPS_BALANCE_TWOSIDE, or EPS_BALANCE_USER
. its - number of iterations of the balancing algorithm
- cutoff - cutoff value
Options Database Keys:
+ -eps_balance <method> - the balancing method, where <method> is one of
'none', 'oneside', 'twoside', or 'user'
. -eps_balance_its <its> - number of iterations
- -eps_balance_cutoff <cutoff> - cutoff value
Notes:
When balancing is enabled, the solver works implicitly with matrix DAD^-1,
where D is an appropriate diagonal matrix. This improves the accuracy of
the computed results in some cases. See the SLEPc Users Manual for details.
Balancing makes sense only for non-Hermitian problems when the required
precision is high (i.e. a small tolerance such as 1e-15).
By default, balancing is disabled. The two-sided method is much more
effective than the one-sided counterpart, but it requires the system
matrices to have the MatMultTranspose operation defined.
The parameter 'its' is the number of iterations performed by the method. The
cutoff value is used only in the two-side variant. Use PETSC_DEFAULT to assign
a reasonably good value.
User-defined balancing is allowed provided that the corresponding matrix
is set via STSetBalanceMatrix.
Level: intermediate
.seealso: EPSGetBalance(), EPSBalance, STSetBalanceMatrix()
@*/
PetscErrorCode EPSSetBalance(EPS eps,EPSBalance bal,PetscInt its,PetscReal cutoff)
{
PetscFunctionBegin;
PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
PetscValidLogicalCollectiveEnum(eps,bal,2);
PetscValidLogicalCollectiveInt(eps,its,3);
PetscValidLogicalCollectiveReal(eps,cutoff,4);
switch (bal) {
case EPS_BALANCE_NONE:
case EPS_BALANCE_ONESIDE:
case EPS_BALANCE_TWOSIDE:
case EPS_BALANCE_USER:
eps->balance = bal;
break;
default:
SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Invalid value of argument 'bal'");
}
if (its==PETSC_DECIDE || its==PETSC_DEFAULT) eps->balance_its = 5;
else {
if (its <= 0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be > 0");
eps->balance_its = its;
}
if (cutoff==PETSC_DECIDE || cutoff==PETSC_DEFAULT) eps->balance_cutoff = 1e-8;
else {
if (cutoff <= 0.0) SETERRQ(PetscObjectComm((PetscObject)eps),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of cutoff. Must be > 0");
eps->balance_cutoff = cutoff;
}
PetscFunctionReturn(0);
}
EXTERN_C_END
#undef __FUNCT__
#define __FUNCT__ "MatPartitioningPartySetCoarseLevel"
/*@
MatPartitioningPartySetCoarseLevel - Set the coarse level parameter for the
Party partitioner.
Collective on MatPartitioning
Input Parameters:
+ part - the partitioning context
- level - the coarse level in range [0.0,1.0]
Options Database:
. -mat_partitioning_party_coarse <l> - Coarse level
Level: advanced
@*/
PetscErrorCode MatPartitioningPartySetCoarseLevel(MatPartitioning part,PetscReal level)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(part,MAT_PARTITIONING_CLASSID,1);
PetscValidLogicalCollectiveReal(part,level,2);
ierr = PetscTryMethod(part,"MatPartitioningPartySetCoarseLevel_C",(MatPartitioning,PetscReal),(part,level));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
MatComputeBandwidth - Calculate the full bandwidth of the matrix, meaning the width 2k+1 where k diagonals on either side are sufficient to contain all the matrix nonzeros.
Collective on Mat
Input Parameters:
+ A - The Mat
- fraction - An optional percentage of the Frobenius norm of the matrix that the bandwidth should enclose
Output Parameter:
. bw - The matrix bandwidth
Level: beginner
.seealso: DMPlexCreate(), DMPlexSetConeSize(), DMPlexSetChart()
@*/
PetscErrorCode MatComputeBandwidth(Mat A, PetscReal fraction, PetscInt *bw)
{
PetscInt lbw[2] = {0, 0}, gbw[2];
PetscInt rStart, rEnd, r;
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(A, MAT_CLASSID, 1);
PetscValidLogicalCollectiveReal(A,fraction,2);
PetscValidPointer(bw, 3);
if ((fraction > 0.0) && (fraction < 1.0)) SETERRQ(PetscObjectComm((PetscObject) A), PETSC_ERR_SUP, "We do not yet support a fractional bandwidth");
ierr = MatGetOwnershipRange(A, &rStart, &rEnd);CHKERRQ(ierr);
for (r = rStart; r < rEnd; ++r) {
const PetscInt *cols;
PetscInt ncols;
ierr = MatGetRow(A, r, &ncols, &cols, NULL);CHKERRQ(ierr);
if (ncols) {
lbw[0] = PetscMax(lbw[0], r - cols[0]);
lbw[1] = PetscMax(lbw[1], cols[ncols-1] - r);
}
ierr = MatRestoreRow(A, r, &ncols, &cols, NULL);CHKERRQ(ierr);
}
ierr = MPI_Allreduce(lbw, gbw, 2, MPIU_INT, MPI_MAX, PetscObjectComm((PetscObject) A));CHKERRQ(ierr);
*bw = 2*PetscMax(gbw[0], gbw[1]) + 1;
PetscFunctionReturn(0);
}
/*@
TSAdaptSetMaxIgnore - Set error estimation threshold. Solution components below this threshold value will not be considered when computing error norms for time step adaptivity (in absolute value). A negative value (default) of the threshold leads to considering all solution components.
Logically collective on TSAdapt
Input Arguments:
+ adapt - adaptive controller context
- max_ignore - threshold for solution components that are ignored during error estimation
Options Database Keys:
. -ts_adapt_max_ignore <max_ignore> - to set the threshold
Level: intermediate
.seealso: TSAdapt, TSAdaptGetMaxIgnore(), TSAdaptChoose()
@*/
PetscErrorCode TSAdaptSetMaxIgnore(TSAdapt adapt,PetscReal max_ignore)
{
PetscFunctionBegin;
PetscValidHeaderSpecific(adapt,TSADAPT_CLASSID,1);
PetscValidLogicalCollectiveReal(adapt,max_ignore,2);
adapt->ignore_max = max_ignore;
PetscFunctionReturn(0);
}
PetscErrorCode MatMFFDSetFunctionError_MFFD(Mat mat,PetscReal error)
{
MatMFFD ctx = (MatMFFD)mat->data;
PetscFunctionBegin;
PetscValidLogicalCollectiveReal(mat,error,2);
if (error != PETSC_DEFAULT) ctx->error_rel = error;
PetscFunctionReturn(0);
}
/*@
KSPGMRESSetHapTol - Sets tolerance for determining happy breakdown in GMRES, FGMRES and LGMRES.
Logically Collective on KSP
Input Parameters:
+ ksp - the Krylov space context
- tol - the tolerance
Options Database:
. -ksp_gmres_haptol <positive real value>
Note: Happy breakdown is the rare case in GMRES where an 'exact' solution is obtained after
a certain number of iterations. If you attempt more iterations after this point unstable
things can happen hence very occasionally you may need to set this value to detect this condition
Level: intermediate
.keywords: KSP, GMRES, tolerance
.seealso: KSPSetTolerances()
@*/
PetscErrorCode KSPGMRESSetHapTol(KSP ksp,PetscReal tol)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidLogicalCollectiveReal(ksp,tol,2);
ierr = PetscTryMethod((ksp),"KSPGMRESSetHapTol_C",(KSP,PetscReal),((ksp),(tol)));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
TSSundialsSetLinearTolerance - Sets the tolerance used to solve the linear
system by SUNDIALS.
Logically Collective on TS
Input parameters:
+ ts - the time-step context
- tol - the factor by which the tolerance on the nonlinear solver is
multiplied to get the tolerance on the linear solver, .05 by default.
Level: advanced
.keywords: GMRES, linear convergence tolerance, SUNDIALS
.seealso: TSSundialsGetIterations(), TSSundialsSetType(), TSSundialsSetMaxl(),
TSSundialsSetGramSchmidtType(), TSSundialsSetTolerance(),
TSSundialsGetIterations(), TSSundialsSetType(),
TSSundialsSetLinearTolerance(), TSSundialsSetTolerance(), TSSundialsGetPC(),
TSSetExactFinalTime()
@*/
PetscErrorCode TSSundialsSetLinearTolerance(TS ts,double tol)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidLogicalCollectiveReal(ts,tol,2);
ierr = PetscTryMethod(ts,"TSSundialsSetLinearTolerance_C",(TS,double),(ts,tol));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
PCFactorReorderForNonzeroDiagonal - reorders rows/columns of matrix to remove zeros from diagonal
Logically Collective on PC
Input Parameters:
+ pc - the preconditioner context
- tol - diagonal entries smaller than this in absolute value are considered zero
Options Database Key:
. -pc_factor_nonzeros_along_diagonal
Level: intermediate
.keywords: PC, set, factorization, direct, fill
.seealso: PCFactorSetFill(), PCFactorSetShiftNonzero(), PCFactorSetZeroPivot(), MatReorderForNonzeroDiagonal()
@*/
PetscErrorCode PCFactorReorderForNonzeroDiagonal(PC pc,PetscReal rtol)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(pc,PC_CLASSID,1);
PetscValidLogicalCollectiveReal(pc,rtol,2);
ierr = PetscTryMethod(pc,"PCFactorReorderForNonzeroDiagonal_C",(PC,PetscReal),(pc,rtol));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
PCFactorSetShiftAmount - adds a quantity to the diagonal of the matrix during
numerical factorization, thus the matrix has nonzero pivots
Logically Collective on PC
Input Parameters:
+ pc - the preconditioner context
- shiftamount - amount of shift
Options Database Key:
. -pc_factor_shift_amount <shiftamount> - Sets shift amount or PETSC_DECIDE for the default
Level: intermediate
.keywords: PC, set, factorization,
.seealso: PCFactorSetZeroPivot(), PCFactorSetShiftType()
@*/
PetscErrorCode PCFactorSetShiftAmount(PC pc,PetscReal shiftamount)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(pc,PC_CLASSID,1);
PetscValidLogicalCollectiveReal(pc,shiftamount,2);
ierr = PetscTryMethod(pc,"PCFactorSetShiftAmount_C",(PC,PetscReal),(pc,shiftamount));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
PCFactorSetZeroPivot - Sets the size at which smaller pivots are declared to be zero
Logically Collective on PC
Input Parameters:
+ pc - the preconditioner context
- zero - all pivots smaller than this will be considered zero
Options Database Key:
. -pc_factor_zeropivot <zero> - Sets tolerance for what is considered a zero pivot
Level: intermediate
.keywords: PC, set, factorization, direct, fill
.seealso: PCFactorSetShiftType(), PCFactorSetShiftAmount()
@*/
PetscErrorCode PCFactorSetZeroPivot(PC pc,PetscReal zero)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(pc,PC_CLASSID,1);
PetscValidLogicalCollectiveReal(pc,zero,2);
ierr = PetscTryMethod(pc,"PCFactorSetZeroPivot_C",(PC,PetscReal),(pc,zero));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
MatPartitioningChacoSetEigenTol - Sets the tolerance for the eigensolver.
Collective on MatPartitioning
Input Parameters:
+ part - the partitioning context
- tol - the tolerance
Options Database:
. -mat_partitioning_chaco_eigen_tol <tol>: Tolerance for eigensolver
Note:
Must be positive. The default value is 0.001.
Level: advanced
.seealso: MatPartitioningChacoSetEigenSolver(), MatPartitioningChacoGetEigenTol()
@*/
PetscErrorCode MatPartitioningChacoSetEigenTol(MatPartitioning part,PetscReal tol)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(part,MAT_PARTITIONING_CLASSID,1);
PetscValidLogicalCollectiveReal(part,tol,2);
ierr = PetscTryMethod(part,"MatPartitioningChacoSetEigenTol_C",(MatPartitioning,PetscReal),(part,tol));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
NEPSetTolerances - Sets various parameters used in convergence tests.
Logically Collective on NEP
Input Parameters:
+ nep - the nonlinear eigensolver context
. abstol - absolute convergence tolerance
. rtol - relative convergence tolerance
. stol - convergence tolerance in terms of the norm of the change in the
solution between steps, || delta x || < stol*|| x ||
. maxit - maximum number of iterations
- maxf - maximum number of function evaluations
Options Database Keys:
+ -nep_atol <abstol> - Sets abstol
. -nep_rtol <rtol> - Sets rtol
. -nep_stol <stol> - Sets stol
. -nep_max_it <maxit> - Sets maxit
- -nep_max_funcs <maxf> - Sets maxf
Notes:
Use PETSC_DEFAULT for either argument to assign a reasonably good value.
Level: intermediate
.seealso: NEPGetTolerances()
@*/
PetscErrorCode NEPSetTolerances(NEP nep,PetscReal abstol,PetscReal rtol,PetscReal stol,PetscInt maxit,PetscInt maxf)
{
PetscFunctionBegin;
PetscValidHeaderSpecific(nep,NEP_CLASSID,1);
PetscValidLogicalCollectiveReal(nep,abstol,2);
PetscValidLogicalCollectiveReal(nep,rtol,3);
PetscValidLogicalCollectiveReal(nep,stol,4);
PetscValidLogicalCollectiveInt(nep,maxit,5);
PetscValidLogicalCollectiveInt(nep,maxf,6);
if (abstol == PETSC_DEFAULT) {
nep->abstol = PETSC_DEFAULT;
} else {
if (abstol < 0.0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Absolute tolerance %g must be non-negative",(double)abstol);
nep->abstol = abstol;
}
if (rtol == PETSC_DEFAULT) {
nep->rtol = PETSC_DEFAULT;
} else {
if (rtol < 0.0 || 1.0 <= rtol) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Relative tolerance %g must be non-negative and less than 1.0",(double)rtol);
nep->rtol = rtol;
}
if (stol == PETSC_DEFAULT) {
nep->stol = PETSC_DEFAULT;
} else {
if (stol < 0.0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Step tolerance %g must be non-negative",(double)stol);
nep->stol = stol;
}
if (maxit == PETSC_DEFAULT || maxit == PETSC_DECIDE) {
nep->max_it = 0;
nep->state = NEP_STATE_INITIAL;
} else {
if (maxit < 0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Maximum number of iterations %D must be non-negative",maxit);
nep->max_it = maxit;
}
if (maxf == PETSC_DEFAULT || maxf == PETSC_DECIDE) {
nep->max_it = 0;
nep->state = NEP_STATE_INITIAL;
} else {
if (maxf < 0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Maximum number of function evaluations %D must be non-negative",maxf);
nep->max_funcs = maxf;
}
PetscFunctionReturn(0);
}
/*@
TSPseudoSetMaxTimeStep - Sets the maximum time step
when using the TSPseudoTimeStepDefault() routine.
Logically Collective on TS
Input Parameters:
+ ts - the timestep context
- maxdt - the maximum time step, use a non-positive value to deactivate
Options Database Key:
$ -ts_pseudo_max_dt <increment>
Level: advanced
.keywords: timestep, pseudo, set
.seealso: TSPseudoSetTimeStep(), TSPseudoTimeStepDefault()
@*/
PetscErrorCode TSPseudoSetMaxTimeStep(TS ts,PetscReal maxdt)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(ts,TS_CLASSID,1);
PetscValidLogicalCollectiveReal(ts,maxdt,2);
ierr = PetscTryMethod(ts,"TSPseudoSetMaxTimeStep_C",(TS,PetscReal),(ts,maxdt));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
EPSKrylovSchurSetRestart - Sets the restart parameter for the Krylov-Schur
method, in particular the proportion of basis vectors that must be kept
after restart.
Logically Collective on EPS
Input Parameters:
+ eps - the eigenproblem solver context
- keep - the number of vectors to be kept at restart
Options Database Key:
. -eps_krylovschur_restart - Sets the restart parameter
Notes:
Allowed values are in the range [0.1,0.9]. The default is 0.5.
Level: advanced
.seealso: EPSKrylovSchurGetRestart()
@*/
PetscErrorCode EPSKrylovSchurSetRestart(EPS eps,PetscReal keep)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
PetscValidLogicalCollectiveReal(eps,keep,2);
ierr = PetscTryMethod(eps,"EPSKrylovSchurSetRestart_C",(EPS,PetscReal),(eps,keep));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
EPSJDSetFix - Sets the threshold for changing the target in the correction
equation.
Logically Collective on EPS
Input Parameters:
+ eps - the eigenproblem solver context
- fix - threshold for changing the target
Options Database Key:
. -eps_jd_fix - the fix value
Note:
The target in the correction equation is fixed at the first iterations.
When the norm of the residual vector is lower than the fix value,
the target is set to the corresponding eigenvalue.
Level: advanced
.seealso: EPSJDGetFix()
@*/
PetscErrorCode EPSJDSetFix(EPS eps,PetscReal fix)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
PetscValidLogicalCollectiveReal(eps,fix,2);
ierr = PetscTryMethod(eps,"EPSJDSetFix_C",(EPS,PetscReal),(eps,fix));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
TSPseudoSetTimeStepIncrement - Sets the scaling increment applied to
dt when using the TSPseudoTimeStepDefault() routine.
Logically Collective on TS
Input Parameters:
+ ts - the timestep context
- inc - the scaling factor >= 1.0
Options Database Key:
$ -ts_pseudo_increment <increment>
Level: advanced
.keywords: timestep, pseudo, set, increment
.seealso: TSPseudoSetTimeStep(), TSPseudoTimeStepDefault()
@*/
PetscErrorCode TSPseudoSetTimeStepIncrement(TS ts,PetscReal inc)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(ts,TS_CLASSID,1);
PetscValidLogicalCollectiveReal(ts,inc,2);
ierr = PetscTryMethod(ts,"TSPseudoSetTimeStepIncrement_C",(TS,PetscReal),(ts,inc));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
MatPartitioningPTScotchSetImbalance - Sets the value of the load imbalance
ratio to be used during strategy selection.
Collective on MatPartitioning
Input Parameters:
+ part - the partitioning context
- imb - the load imbalance ratio
Options Database:
. -mat_partitioning_ptscotch_imbalance <imb>
Note:
Must be in the range [0,1]. The default value is 0.01.
Level: advanced
.seealso: MatPartitioningPTScotchSetStrategy(), MatPartitioningPTScotchGetImbalance()
@*/
PetscErrorCode MatPartitioningPTScotchSetImbalance(MatPartitioning part,PetscReal imb)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(part,MAT_PARTITIONING_CLASSID,1);
PetscValidLogicalCollectiveReal(part,imb,2);
ierr = PetscTryMethod(part,"MatPartitioningPTScotchSetImbalance_C",(MatPartitioning,PetscReal),(part,imb));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
MatMFFDSetFunctionError - Sets the error_rel for the approximation of
matrix-vector products using finite differences.
Logically Collective on Mat
Input Parameters:
+ mat - the matrix free matrix created via MatCreateMFFD() or MatCreateSNESMF()
- error_rel - relative error (should be set to the square root of
the relative error in the function evaluations)
Options Database Keys:
+ -mat_mffd_err <error_rel> - Sets error_rel
Level: advanced
Notes:
The default matrix-free matrix-vector product routine computes
.vb
F'(u)*a = [F(u+h*a) - F(u)]/h where
h = error_rel*u'a/||a||^2 if |u'a| > umin*||a||_{1}
= error_rel*umin*sign(u'a)*||a||_{1}/||a||^2 else
.ve
.keywords: SNES, matrix-free, parameters
.seealso: MatCreateSNESMF(),MatMFFDGetH(), MatCreateMFFD(), MATMFFD
MatMFFDSetHHistory(), MatMFFDResetHHistory()
@*/
PetscErrorCode MatMFFDSetFunctionError(Mat mat,PetscReal error)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(mat,MAT_CLASSID,1);
PetscValidLogicalCollectiveReal(mat,error,2);
ierr = PetscTryMethod(mat,"MatMFFDSetFunctionError_C",(Mat,PetscReal),(mat,error));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
TSAlpha2SetRadius - sets the desired spectral radius of the method
(i.e. high-frequency numerical damping)
Logically Collective on TS
The algorithmic parameters \alpha_m and \alpha_f of the
generalized-\alpha method can be computed in terms of a specified
spectral radius \rho in [0,1] for infinite time step in order to
control high-frequency numerical damping:
\alpha_m = (2-\rho)/(1+\rho)
\alpha_f = 1/(1+\rho)
Input Parameter:
+ ts - timestepping context
- radius - the desired spectral radius
Options Database:
. -ts_alpha_radius <radius>
Level: intermediate
.seealso: TSAlpha2SetParams(), TSAlpha2GetParams()
@*/
PetscErrorCode TSAlpha2SetRadius(TS ts,PetscReal radius)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(ts,TS_CLASSID,1);
PetscValidLogicalCollectiveReal(ts,radius,2);
if (radius < 0 || radius > 1) SETERRQ1(((PetscObject)ts)->comm,PETSC_ERR_ARG_OUTOFRANGE,"Radius %g not in range [0,1]",(double)radius);
ierr = PetscTryMethod(ts,"TSAlpha2SetRadius_C",(TS,PetscReal),(ts,radius));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
KSPSTCGSetRadius - Sets the radius of the trust region.
Logically Collective on KSP
Input Parameters:
+ ksp - the iterative context
- radius - the trust region radius (Infinity is the default)
Options Database Key:
. -ksp_stcg_radius <r>
Level: advanced
.keywords: KSP, STCG, set, trust region radius
@*/
PetscErrorCode KSPSTCGSetRadius(KSP ksp, PetscReal radius)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(ksp, KSP_CLASSID, 1);
if (radius < 0.0) SETERRQ(PetscObjectComm((PetscObject)ksp),PETSC_ERR_ARG_OUTOFRANGE, "Radius negative");
PetscValidLogicalCollectiveReal(ksp,radius,2);
ierr = PetscUseMethod(ksp,"KSPSTCGSetRadius_C",(KSP,PetscReal),(ksp,radius));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
