$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.                       
 --- 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.                      
             --- 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.                                             
              --- next apply only to CGGCRO:                                    
ITERA  = the number of (linear) CG iterations to apply                          
         before alternation to the GCRO converger.                              
ITERB  = the number of GCRO iterations to apply                                 
         before alternation to the (linear) CG converger.                       

generated on 7/7/2017