$CPMCHF group
      (relevant for analytic RUNTYP=HESSIAN,NACME,CONICAL)
 
    This group controls the solution of the response
equations, also called coupled perturbed multiconfiguration
Hartree-Fock, for MCSCF wavefunctions.  These are needed
for analytic hessians (CISTEP=ALDET or ORMAS), or for
state-averaged gradients or non-adiabatic coupling matrix
element calculations.  The full response equations are
solved for hessians, while Z-vector equations are used for
NACME and SA-gradients.
 
    The default converger is a (linear) conjugate gradient
(CG) method, but three others may be chosen.  Difficult
cases might work upwards from the default CG method by:
 $cpmchf $end
 $cpmchf ipdir=50 $end
 $cpmchf gcro=.t.   micit=5  kicit=10 $end
 $cpmchf gcrodr=.t. micit=10 kicit=5  $end
 $cpmchf gcrodr=.t. micit=30 kicit=10 reclin=.false. $end
 $cpmchf gcrodr=.t. micit=20 kicit=10 reclin=.false.
         prcchg=.true. prctol=1.0 $end
 $cpmchf gcro=.t.   micit=50 kicit=100
         prcchg=.true. prctol=1.0 $end
where the last one is "the sledgehammer".  The options
shown in the next to last case very often work, and will be
considerably faster than the last set, which should always
work.  GCRO will typically take many fewer iterations than
CG, a measure of its robustness, but will use more machine
time due to its microiterations.
 
   --- the next set apply to any CP-MCHF converger ---
 
MAXIT   = maximum iterations.   (default=300)
 
CPTOL   = accuracy tolerance for cpmchf equations Ax=b.
          (compared to r/||b||, within orbital, CI, and
          state averaged components)   (default=1.0D-07)
 
PRCCHG  = a flag to adjust the linear equation's
          preconditioning.  (Default=.FALSE.)
          For ORMAS runs in particular, the standard
          preconditioner might lead to ill-conditioning
          with very small elements.  If selected, any
          preconditioner elements below PRCTOL will be
          reset to a value of 1.0
 
PRCTOL = a tolerance to keep preconditioner elements,
         if PRCCHG is chosen.  Default=1.0D-6
 
                --- for RUNTYP=NACME ---
 
NAPICK  = a flag to select running through z-vector setup
          and choose which linear equations to solve.
          .TRUE. leads to z-vector linear equations.
          .FALSE. leads to non-z-vector linear equations.
          The z-vector equations are advantageous when the
          degrees of freedom exceeds the no. of electronic
          states involved in the state-averaging.
          (The defaults are set to enforce this option.)
          The z-vector equations are also advantageous
          when only a few NA couplings out of the total
          total possible couplings are of interest.
          If CISTEP=ORMAS, NAPICK=.TRUE. is forced.
          Selecting NAPICK=.TRUE. requires the choice of
          NA couplings in the NACST array (see below).
          (default=varies... see ROUTINE NACMEX for notes)
 
NACST   = an array that indicates which NA couplings to
          Calculate, if NAPICK is chosen.  For example, if
          WSTATE in $DET contains at least four states,
          the NACME can be limited to state pairs 1(-)2 and
          3(-)4 by NACST(1)=3,4, 1,2.  Note that you should
          pick increasing order within any pair of states!
          The program always generates the state-specific
          gradient of every state with a non-zero WSTATE.
          (default=none)
 
 
 --- the next three choose the other CPMCHF convergers ---
   If none is selected, conjugate gradient (CG) is used.
 
GCRODR  = a flag to select Generalized Conjugate Residual
          with inner Orthogonalization with Deflated
          Restarting.  (default=.FALSE.)
 
GCRO    = a flag to select Generalized Conjugate Residual
          with inner Orthogonalization.  (default=.FALSE.)
 
CGGCRO  = a flag to alternate between GCRO and CG solvers.
          (default=.FALSE.)
 
 
 
             --- next apply only to GCRODR:
 
RECLIN  = a flag to select recycling of Krylov subspaces
          from the first linear equation. (recycle linear).
          The first CP-MCHF linear equation is solved
          and a recyclable subspace is generated.
          Then, after a projection of approximate solution
          across the subspace from the first system,
          the rest of the linear equations are solved.
          The recycled subspace may or may not give rapid
          convergence with fewer iterations.  See MICIT and
          KICIT.  (default=.TRUE.)
 
 
              --- next apply only to GCRODR,GCRO,CGGCRO:
 
MICIT   = total size of the Krylov expansion space, namely
          the number of micro-iterations within an overall
          iteration. While the MICIT variable has no limit,
          fifty or more micro-iterations start to become
          computationally unmanagable for larger systems.
          The default often must be increased for large
          systems or for geometries far from equilibrium.
          In addition, the GCRODR converger has a slightly
          modified scheme for the micro-iterations.
          In the first iteration, MICIT micro-iterations
          are performed in a GMRES(MICIT) iteration.
          However, for subsequent iterations, (MICIT-KICIT)
          micro-iterations are performed.
          (default=5, often increased to 20 or 30)
KICIT   = the size of the recyclable Krylov basis saved and
          modified from iteration to iteration, created
          from eigenvectors with small eigenvalues.  If
          this space is too small, the run will experience
          ill-conditioning, but if too large, the search
          space includes ineffective parts.
          In case PRCCHG is chosen, make sure the number of
          vectors reset from small values does not exceed
          KICIT, if it does, increase KICIT.
          (default=5, usually small, e.g. 5-10 for GCRODR)
 
          (MICIT> KICIT for GCRODR)
          (KICIT>=MICIT for GCRO and CGGCRO)
 
 
              --- next apply only to (linear) CG:
 
NACFAC =  number of iterations before softening the current
          convergence tolerance by 1/3, for CG only.  Use
          NACFAC=0 (or MAXIT) to prevent raising the
          from the initial CPTOL.    (default=50)
 
IPDIR  =  number of iterations before resetting the
          residual from a pseudo-residual to the true
          residual. This reset also resets the search
          directions, since keeping the old 'ill-rounded'
          directions is not very beneficial.
          If a run almost convergences but struggles in
          later iterations, IPDIR=50 is recommended.
          This option appears more useful for NACME
          rather than Hessian runs.
          (default=MAXIT)
 
 
              --- next apply only to CGGCRO:
 
ITERA  = the number of (linear) CG iterations to apply
         before alternation to the GCRO converger.
          (default=5)
 
ITERB  = the number of GCRO iterations to apply
         before alternation to the (linear) CG converger.
          (default=5)
==========================================================
 
 
 
==========================================================