/*@
BVMult - Computes Y = beta*Y + alpha*X*Q.
Logically Collective on BV
Input Parameters:
+ Y,X - basis vectors
. alpha,beta - scalars
- Q - a sequential dense matrix
Output Parameter:
. Y - the modified basis vectors
Notes:
X and Y must be different objects. The case X=Y can be addressed with
BVMultInPlace().
The matrix Q must be a sequential dense Mat, with all entries equal on
all processes (otherwise each process will compute a different update).
The dimensions of Q must be at least m,n where m is the number of active
columns of X and n is the number of active columns of Y.
The leading columns of Y are not modified. Also, if X has leading
columns specified, then these columns do not participate in the computation.
Hence, only rows (resp. columns) of Q starting from lx (resp. ly) are used,
where lx (resp. ly) is the number of leading columns of X (resp. Y).
Level: intermediate
.seealso: BVMultVec(), BVMultColumn(), BVMultInPlace(), BVSetActiveColumns()
@*/
PetscErrorCode BVMult(BV Y,PetscScalar alpha,PetscScalar beta,BV X,Mat Q)
{
PetscErrorCode ierr;
PetscBool match;
PetscInt m,n;
PetscFunctionBegin;
PetscValidHeaderSpecific(Y,BV_CLASSID,1);
PetscValidLogicalCollectiveScalar(Y,alpha,2);
PetscValidLogicalCollectiveScalar(Y,beta,3);
PetscValidHeaderSpecific(X,BV_CLASSID,4);
PetscValidHeaderSpecific(Q,MAT_CLASSID,5);
PetscValidType(Y,1);
BVCheckSizes(Y,1);
PetscValidType(X,4);
BVCheckSizes(X,4);
PetscValidType(Q,5);
PetscCheckSameTypeAndComm(Y,1,X,4);
if (X==Y) SETERRQ(PetscObjectComm((PetscObject)Y),PETSC_ERR_ARG_WRONG,"X and Y arguments must be different");
ierr = PetscObjectTypeCompare((PetscObject)Q,MATSEQDENSE,&match);CHKERRQ(ierr);
if (!match) SETERRQ(PetscObjectComm((PetscObject)Y),PETSC_ERR_SUP,"Mat argument must be of type seqdense");
ierr = MatGetSize(Q,&m,&n);CHKERRQ(ierr);
if (m<X->k) SETERRQ2(PetscObjectComm((PetscObject)Y),PETSC_ERR_ARG_SIZ,"Mat argument has %D rows, should have at least %D",m,X->k);
if (n<Y->k) SETERRQ2(PetscObjectComm((PetscObject)Y),PETSC_ERR_ARG_SIZ,"Mat argument has %D columns, should have at least %D",n,Y->k);
if (X->n!=Y->n) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Mismatching local dimension X %D, Y %D",X->n,Y->n);
if (!X->n) PetscFunctionReturn(0);
ierr = PetscLogEventBegin(BV_Mult,X,Y,0,0);CHKERRQ(ierr);
ierr = (*Y->ops->mult)(Y,alpha,beta,X,Q);CHKERRQ(ierr);
ierr = PetscLogEventEnd(BV_Mult,X,Y,0,0);CHKERRQ(ierr);
ierr = PetscObjectStateIncrease((PetscObject)Y);CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
BVMultVec - Computes y = beta*y + alpha*X*q.
Logically Collective on BV and Vec
Input Parameters:
+ X - a basis vectors object
. alpha,beta - scalars
. y - a vector
- q - an array of scalars
Output Parameter:
. y - the modified vector
Notes:
This operation is the analogue of BVMult() but with a BV and a Vec,
instead of two BV. Note that arguments are listed in different order
with respect to BVMult().
If X has leading columns specified, then these columns do not participate
in the computation.
The length of array q must be equal to the number of active columns of X
minus the number of leading columns, i.e. the first entry of q multiplies
the first non-leading column.
Level: intermediate
.seealso: BVMult(), BVMultColumn(), BVMultInPlace(), BVSetActiveColumns()
@*/
PetscErrorCode BVMultVec(BV X,PetscScalar alpha,PetscScalar beta,Vec y,PetscScalar *q)
{
PetscErrorCode ierr;
PetscInt n,N;
PetscFunctionBegin;
PetscValidHeaderSpecific(X,BV_CLASSID,1);
PetscValidLogicalCollectiveScalar(X,alpha,2);
PetscValidLogicalCollectiveScalar(X,beta,3);
PetscValidHeaderSpecific(y,VEC_CLASSID,4);
PetscValidPointer(q,5);
PetscValidType(X,1);
BVCheckSizes(X,1);
PetscValidType(y,4);
PetscCheckSameComm(X,1,y,4);
ierr = VecGetSize(y,&N);CHKERRQ(ierr);
ierr = VecGetLocalSize(y,&n);CHKERRQ(ierr);
if (N!=X->N || n!=X->n) SETERRQ4(PetscObjectComm((PetscObject)X),PETSC_ERR_ARG_INCOMP,"Vec sizes (global %D, local %D) do not match BV sizes (global %D, local %D)",N,n,X->N,X->n);
if (!X->n) PetscFunctionReturn(0);
ierr = PetscLogEventBegin(BV_Mult,X,y,0,0);CHKERRQ(ierr);
ierr = (*X->ops->multvec)(X,alpha,beta,y,q);CHKERRQ(ierr);
ierr = PetscLogEventEnd(BV_Mult,X,y,0,0);CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
BVMultColumn - Computes y = beta*y + alpha*X*q, where y is the j-th column
of X.
Logically Collective on BV
Input Parameters:
+ X - a basis vectors object
. alpha,beta - scalars
. j - the column index
- q - an array of scalars
Notes:
This operation is equivalent to BVMultVec() but it uses column j of X
rather than taking a Vec as an argument. The number of active columns of
X is set to j before the computation, and restored afterwards.
If X has leading columns specified, then these columns do not participate
in the computation. Therefore, the length of array q must be equal to j
minus the number of leading columns.
Level: advanced
.seealso: BVMult(), BVMultVec(), BVMultInPlace(), BVSetActiveColumns()
@*/
PetscErrorCode BVMultColumn(BV X,PetscScalar alpha,PetscScalar beta,PetscInt j,PetscScalar *q)
{
PetscErrorCode ierr;
PetscInt ksave;
Vec y;
PetscFunctionBegin;
PetscValidHeaderSpecific(X,BV_CLASSID,1);
PetscValidLogicalCollectiveScalar(X,alpha,2);
PetscValidLogicalCollectiveScalar(X,beta,3);
PetscValidLogicalCollectiveInt(X,j,4);
PetscValidPointer(q,5);
PetscValidType(X,1);
BVCheckSizes(X,1);
if (j<0) SETERRQ(PetscObjectComm((PetscObject)X),PETSC_ERR_ARG_OUTOFRANGE,"Index j must be non-negative");
if (j>=X->m) SETERRQ2(PetscObjectComm((PetscObject)X),PETSC_ERR_ARG_OUTOFRANGE,"Index j=%D but BV only has %D columns",j,X->m);
ierr = PetscLogEventBegin(BV_Mult,X,0,0,0);CHKERRQ(ierr);
ksave = X->k;
X->k = j;
ierr = BVGetColumn(X,j,&y);CHKERRQ(ierr);
ierr = (*X->ops->multvec)(X,alpha,beta,y,q);CHKERRQ(ierr);
ierr = BVRestoreColumn(X,j,&y);CHKERRQ(ierr);
X->k = ksave;
ierr = PetscLogEventEnd(BV_Mult,X,0,0,0);CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
MatAXPY - Computes Y = a*X + Y.
Logically Collective on Mat
Input Parameters:
+ a - the scalar multiplier
. X - the first matrix
. Y - the second matrix
- str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN
or SUBSET_NONZERO_PATTERN (nonzeros of X is a subset of Y's)
Level: intermediate
.keywords: matrix, add
.seealso: MatAYPX()
@*/
PetscErrorCode MatAXPY(Mat Y,PetscScalar a,Mat X,MatStructure str)
{
PetscErrorCode ierr;
PetscInt m1,m2,n1,n2;
PetscFunctionBegin;
PetscValidHeaderSpecific(X,MAT_CLASSID,3);
PetscValidHeaderSpecific(Y,MAT_CLASSID,1);
PetscValidLogicalCollectiveScalar(Y,a,2);
ierr = MatGetSize(X,&m1,&n1);CHKERRQ(ierr);
ierr = MatGetSize(Y,&m2,&n2);CHKERRQ(ierr);
if (m1 != m2 || n1 != n2) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"Non conforming matrix add: %D %D %D %D",m1,m2,n1,n2);
ierr = PetscLogEventBegin(MAT_AXPY,Y,0,0,0);CHKERRQ(ierr);
if (Y->ops->axpy) {
ierr = (*Y->ops->axpy)(Y,a,X,str);CHKERRQ(ierr);
} else {
ierr = MatAXPY_Basic(Y,a,X,str);CHKERRQ(ierr);
}
ierr = PetscLogEventEnd(MAT_AXPY,Y,0,0,0);CHKERRQ(ierr);
#if defined(PETSC_HAVE_CUSP)
if (Y->valid_GPU_matrix != PETSC_CUSP_UNALLOCATED) {
Y->valid_GPU_matrix = PETSC_CUSP_CPU;
}
#endif
PetscFunctionReturn(0);
}
/*@
MFNSetScaleFactor - Sets the scale factor to multiply the matrix (the
argument of the function).
Logically Collective on MFN
Input Parameters:
+ mfn - the matrix function context
- alpha - the scaling factor
Options Database Keys:
. -mfn_scale <alpha> - the scaling factor
Notes:
The computed result is f(alpha*A)*b. The default is alpha=1.0.
In the case of complex scalars, a complex value can be provided in the
command line with [+/-][realnumber][+/-]realnumberi with no spaces, e.g.
-mfn_scale 1.0+2.0i
Level: intermediate
.seealso: MFNGetScaleFactor(), MFNSolve()
@*/
PetscErrorCode MFNSetScaleFactor(MFN mfn,PetscScalar alpha)
{
PetscFunctionBegin;
PetscValidHeaderSpecific(mfn,MFN_CLASSID,1);
PetscValidLogicalCollectiveScalar(mfn,alpha,2);
mfn->sfactor = alpha;
PetscFunctionReturn(0);
}
/*@
KSPPIPEFGMRESSetShift - Set the shift parameter for the flexible, pipelined GMRES solver.
A heuristic is to set this to be comparable to the largest eigenvalue of the preconditioned operator. This can be acheived with PETSc itself by using a few iterations of a Krylov method. See KSPComputeEigenvalues (and note the caveats there).
Logically Collective on KSP
Input Parameters:
+ ksp - the Krylov space context
- shift - the shift
Level: intermediate
Options Database:
. -ksp_pipefgmres_shift <shift>
.seealso: KSPComputeEigenvalues()
@*/
PetscErrorCode KSPPIPEFGMRESSetShift(KSP ksp,PetscScalar shift)
{
KSP_PIPEFGMRES *pipefgmres = (KSP_PIPEFGMRES*)ksp->data;
PetscFunctionBegin;
PetscValidHeaderSpecific(ksp,KSP_CLASSID,1);
PetscValidLogicalCollectiveScalar(ksp,shift,2);
pipefgmres->shift = shift;
PetscFunctionReturn(0);
}
/*@
PCCompositeSpecialSetAlpha - Sets alpha for the special composite preconditioner
for alphaI + R + S
Logically Collective on PC
Input Parameter:
+ pc - the preconditioner context
- alpha - scale on identity
Level: Developer
.keywords: PC, set, type, composite preconditioner, additive, multiplicative
@*/
PetscErrorCode PCCompositeSpecialSetAlpha(PC pc,PetscScalar alpha)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(pc,PC_CLASSID,1);
PetscValidLogicalCollectiveScalar(pc,alpha,2);
ierr = PetscTryMethod(pc,"PCCompositeSpecialSetAlpha_C",(PC,PetscScalar),(pc,alpha));CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
EPSSetTarget - Sets the value of the target.
Logically Collective on EPS
Input Parameters:
+ eps - eigensolver context
- target - the value of the target
Options Database Key:
. -eps_target <scalar> - the value of the target
Notes:
The target is a scalar value used to determine the portion of the spectrum
of interest. It is used in combination with EPSSetWhichEigenpairs().
In the case of complex scalars, a complex value can be provided in the
command line with [+/-][realnumber][+/-]realnumberi with no spaces, e.g.
-eps_target 1.0+2.0i
Level: beginner
.seealso: EPSGetTarget(), EPSSetWhichEigenpairs()
@*/
PetscErrorCode EPSSetTarget(EPS eps,PetscScalar target)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(eps,EPS_CLASSID,1);
PetscValidLogicalCollectiveScalar(eps,target,2);
eps->target = target;
if (!eps->st) {
ierr = EPSGetST(eps,&eps->st);
CHKERRQ(ierr);
}
ierr = STSetDefaultShift(eps->st,target);
CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
BVScale - Multiply the BV entries by a scalar value.
Logically Collective on BV
Input Parameters:
+ bv - basis vectors
- alpha - scaling factor
Note:
All active columns (except the leading ones) are scaled.
Level: intermediate
.seealso: BVScaleColumn(), BVSetActiveColumns()
@*/
PetscErrorCode BVScale(BV bv,PetscScalar alpha)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(bv,BV_CLASSID,1);
PetscValidLogicalCollectiveScalar(bv,alpha,2);
PetscValidType(bv,1);
BVCheckSizes(bv,1);
if (!bv->n || alpha == (PetscScalar)1.0) PetscFunctionReturn(0);
ierr = PetscLogEventBegin(BV_Scale,bv,0,0,0);CHKERRQ(ierr);
ierr = (*bv->ops->scale)(bv,-1,alpha);CHKERRQ(ierr);
ierr = PetscLogEventEnd(BV_Scale,bv,0,0,0);CHKERRQ(ierr);
ierr = PetscObjectStateIncrease((PetscObject)bv);CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
MatAYPX - Computes Y = a*Y + X.
Logically on Mat
Input Parameters:
+ a - the PetscScalar multiplier
. Y - the first matrix
. X - the second matrix
- str - either SAME_NONZERO_PATTERN, DIFFERENT_NONZERO_PATTERN or SUBSET_NONZERO_PATTERN
Level: intermediate
.keywords: matrix, add
.seealso: MatAXPY()
@*/
PetscErrorCode MatAYPX(Mat Y,PetscScalar a,Mat X,MatStructure str)
{
PetscScalar one = 1.0;
PetscErrorCode ierr;
PetscInt mX,mY,nX,nY;
PetscFunctionBegin;
PetscValidHeaderSpecific(X,MAT_CLASSID,3);
PetscValidHeaderSpecific(Y,MAT_CLASSID,1);
PetscValidLogicalCollectiveScalar(Y,a,2);
ierr = MatGetSize(X,&mX,&nX);CHKERRQ(ierr);
ierr = MatGetSize(X,&mY,&nY);CHKERRQ(ierr);
if (mX != mY || nX != nY) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"Non conforming matrices: %D %D first %D %D second",mX,mY,nX,nY);
ierr = MatScale(Y,a);CHKERRQ(ierr);
ierr = MatAXPY(Y,one,X,str);CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
STMatSetUp - Build the preconditioner matrix used in STMatSolve().
Collective on ST
Input Parameters:
+ st - the spectral transformation context
. sigma - the shift
- coeffs - the coefficients
Note:
This function is not intended to be called by end users, but by SLEPc
solvers that use ST. It builds matrix st->P as follows, then calls KSPSetUp().
.vb
If (coeffs): st->P = Sum_{i=0:nmat-1} coeffs[i]*sigma^i*A_i.
else st->P = Sum_{i=0:nmat-1} sigma^i*A_i
.ve
Level: developer
.seealso: STMatSolve()
@*/
PetscErrorCode STMatSetUp(ST st,PetscScalar sigma,PetscScalar *coeffs)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(st,ST_CLASSID,1);
PetscValidLogicalCollectiveScalar(st,sigma,2);
PetscValidScalarPointer(coeffs,2);
STCheckMatrices(st,1);
ierr = PetscLogEventBegin(ST_MatSetUp,st,0,0,0);CHKERRQ(ierr);
ierr = STMatMAXPY_Private(st,sigma,0.0,0,coeffs,PETSC_TRUE,&st->P);CHKERRQ(ierr);
if (!st->ksp) { ierr = STGetKSP(st,&st->ksp);CHKERRQ(ierr); }
ierr = KSPSetOperators(st->ksp,st->P,st->P);CHKERRQ(ierr);
ierr = KSPSetUp(st->ksp);CHKERRQ(ierr);
ierr = PetscLogEventEnd(ST_MatSetUp,st,0,0,0);CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@
BVScaleColumn - Scale one column of a BV.
Logically Collective on BV
Input Parameters:
+ bv - basis vectors
. j - column number to be scaled
- alpha - scaling factor
Level: intermediate
.seealso: BVScale(), BVSetActiveColumns()
@*/
PetscErrorCode BVScaleColumn(BV bv,PetscInt j,PetscScalar alpha)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(bv,BV_CLASSID,1);
PetscValidLogicalCollectiveInt(bv,j,2);
PetscValidLogicalCollectiveScalar(bv,alpha,3);
PetscValidType(bv,1);
BVCheckSizes(bv,1);
if (j<0 || j>=bv->m) SETERRQ2(PetscObjectComm((PetscObject)bv),PETSC_ERR_ARG_OUTOFRANGE,"Argument j has wrong value %D, the number of columns is %D",j,bv->m);
if (!bv->n || alpha == (PetscScalar)1.0) PetscFunctionReturn(0);
ierr = PetscLogEventBegin(BV_Scale,bv,0,0,0);CHKERRQ(ierr);
ierr = (*bv->ops->scale)(bv,j,alpha);CHKERRQ(ierr);
ierr = PetscLogEventEnd(BV_Scale,bv,0,0,0);CHKERRQ(ierr);
ierr = PetscObjectStateIncrease((PetscObject)bv);CHKERRQ(ierr);
PetscFunctionReturn(0);
}
/*@C
BVAXPY - Computes Y = Y + alpha*X.
Logically Collective on BV
Input Parameters:
+ Y,X - basis vectors
- alpha - scalar
Output Parameter:
. Y - the modified basis vectors
Notes:
X and Y must be different objects, with compatible dimensions.
The effect is the same as doing a VecAXPY for each of the active
columns (excluding the leading ones).
Level: intermediate
.seealso: BVMult(), BVSetActiveColumns()
@*/
PetscErrorCode BVAXPY(BV Y,PetscScalar alpha,BV X)
{
PetscErrorCode ierr;
PetscFunctionBegin;
PetscValidHeaderSpecific(Y,BV_CLASSID,1);
PetscValidLogicalCollectiveScalar(Y,alpha,2);
PetscValidHeaderSpecific(X,BV_CLASSID,3);
PetscValidType(Y,1);
BVCheckSizes(Y,1);
PetscValidType(X,3);
BVCheckSizes(X,3);
PetscCheckSameTypeAndComm(Y,1,X,3);
if (X==Y) SETERRQ(PetscObjectComm((PetscObject)Y),PETSC_ERR_ARG_WRONG,"X and Y arguments must be different");
if (X->n!=Y->n) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Mismatching local dimension X %D, Y %D",X->n,Y->n);
if (X->k-X->l!=Y->k-Y->l) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"Y has %D non-leading columns, while X has %D",Y->m-Y->l,X->k-X->l);
if (!X->n) PetscFunctionReturn(0);
ierr = PetscLogEventBegin(BV_AXPY,X,Y,0,0);CHKERRQ(ierr);
ierr = (*Y->ops->axpy)(Y,alpha,X);CHKERRQ(ierr);
ierr = PetscLogEventEnd(BV_AXPY,X,Y,0,0);CHKERRQ(ierr);
ierr = PetscObjectStateIncrease((PetscObject)Y);CHKERRQ(ierr);
PetscFunctionReturn(0);
}
