I. Installation
   Usage:   build.mrcc compilersystem [-i32|64] [-pMPI|OMP] [-g]
    where 'compilersystem' can be:
      Intel       - Intel compiler (recommended);
      GNU         - GNU compiler;
      PGF         - Portland Group Fortran compiler;
      HP          - HP Fortran Compiler;
      DEC         - Compaq Fortran Compiler (DEC machines);
      XLF         - XL Fortran Compiler (IBM machines);
      Solaris10   - Sun Solaris10 and Studio10 Fortran Compiler (AMD64).
   
   Optional arguments:
      -i Length of integer variables: 32 or 64 bits. Default: 64
         for PGF, HP, Solaris10; 32 otherwise.
      -p Generates parallel code using MPI (available with PGF and
         Solaris10) or OpenMP (available with PGF) technologies.
         Default: no parallelization.
      -g Compiles codes with debugging option

   On PCs the usage of Intel compiler is strongly recommended, the
   program is 2-3x faster with this compiler even on Athlon PCs.
   Please use the 7.1 or latter version of Intel compiler. Earlier 
   versions may produce defective executables.

II. Usage
   Note that if you use the last version of ACESII, you need to
   prepare only the ACESII input file (ZMAT) and run ACESII. This 
   program system can be called directly by setting the corresponding
   keywords in the ZMAT file (see the ACESII manual, www.aces2.de). 
   In this case you may skip the rest of this manual.

   1. Prepare input files for the program generating the MO integrals
      (ACES2 or Columbus) and for this program (vide infra).
      For ACES2 users: For technical reasons the DERIV=FIRST flag is 
      necessary for the interface. For open shells please also use 
      ORBITALS=STANDARD if REFERENCE=ROHF is specified. For open shell 
      systems it is also recommended to specify the occupation of the 
      reference determinant in the ZMAT file.
   2. Execute the program which calculates the MO integrals:
      (i) ACES2 - run the xtest script.
      (ii) Columbus - execute Columbus and run the colto55 program
                      in the WORK directory
      It is important to set a calculation in the input of these 
      programs which requires a complete integral transformation (e.g.
      CALC=CCSD in ACES2 input, CI for Columbus).
      These programs save MO integrals and other necessary information
      into unit 55 for the subsequent calculation. Note that the 
      recalculation of MO integrals is unnecessary if the following
      calculations are performed at the same geometry.
      It is recommended to execute first some inexpensive calculation 
      (e.g. CCSD, CISD) with the parent program (ACES2,...) and with 
      this code in order to test your input files.
   3. Execute dmrcc. This is the driver for the suite. It calls the
      other programs: goldstone, xmrcc, and mrcc. (The advanced users
      may execute these programs on-by-one, for a detailed description
      see Sec. IV.)

III. Structure of the input file (fort.56, unformatted)
   First line - options:
     1. (ex.lev) - maximal excitation level.
        Single-reference case: all excitations up to this level are 
        included, e.g. 2 for CCSD, 3 for CCSDT, 4 for CCSDTQ etc.
        Multi-reference case:  all excitations up to this level from
        reference determinants are included (usually 2 in this case).
     2. (nsing) - number of singlet roots. (Strictly speaking number of
        of roots with M_s=0 and S is even.) Use this option only with 
        closed shell reference determinant, it must be zero otherwise.
        In case of closed shell ref. det. a partial spin-adaptation is 
        possible, see Ref. 2. This enables us to search for singlet
        and triplet roots separately.
     3. (ntrip) - number of triplet roots. (Strictly speaking number of
        of roots with M_s=0 and S is odd.) See notes at option 2.
     4. (rest) Restart option. The program restarts from the previously
        calculated parameters if it is 1. In case it is 2, the program
        executes automatically the lower-level calculations of the same
        type consecutively and restarts each calculation from the 
        previous one (available only for energy calculations). 
        Use the restart option, e.g.:
        (i)   after system crash;
        (ii)  if the iteration procedure did not converge in the given
              steps;
        (iii) geometry optimization;
        (iv)  potential curve calculations;
        (v)   it is worth restarting the calculations with higher
              excitations using the converged vectors of the same
              method including lower excitations, e.g., CCSDT using
              CCSD, CCSDTQ using CCSDT vectors and so on. Using this 
              trick 1-3 iteration steps can be saved usually, but more 
              ones in the case of strong static correlation (i.e., 
              large T amplitudes). Use rest=2 in this case.
        The program always needs fort.16 for the restart and fort.17, 
        too, if more than one root is sought or for geom. optimization.

        If this options is 0, the program applies unit vectors as 
        initial guess. For CC calculations all cluster amplitudes are 
        set to zero. In case of CI and LR-CC calculations the unit 
        vectors are determined on the basis of the diagonal elements of
        the Hamiltonian: if n roots are requested, n unit vectors
        corresponding to the n lowest diagonals will be used. In some
        cases this initial guess is not sufficient. Then initial trial
        vectors (for single excitations) can be specified in unit 57 
        (unformatted). Structure:
        First line: irrep of virt. orbital, relative number of virt. orb
                    within the irrep
        Second line: irrep of occ. orbital, relative number of occ. orb.
                     within the irrep
        E.g: 2 3
             1 4
        This specifies the following single excitation: the 4th occupied
        hole in irrep 1 is annihilated and an electron is created on the
        3rd virtual orbital in irrep 2. The corresponding unit vector 
        will be loaded as initial guess.
     5. (CC/CI) Method: 0 - CI
                        1 - CC
                        2 - CC(n-1)[n]
                        3 - CC(n-1)(n)    (CC(n-1)[n] energy is also 
                                           calculated)
                        4 - CC(n-1)(n)_L  (CC(n-1)[n] and CC(n-1)(n)
                                           energies are also calculated)
                        5 - CC(n)-1a
                        6 - CC(n)-1b
                        7 - CCn
                        8 - CC(n)-3
        If more than one root is requested and calc=1, LR-CC (EOM-CC) 
        calculation is performed automatically for the excited states.
     6. (dens) Density matrix calculations. One- [mod(dens,2)=1] or both
        one- and two-particle [mod(dens,2)=0] density-matrices 
        (derivatives) are constructed:
        1, 2 - density-matrix calculation (for geometry optimization,
               first-order properties etc.)
        3, 4 - density-matrix derivatives (for second-order property
               calculation, available only with ACES2, currently not 
               available for LR-CC)
        5, 6 - transition density matrices (transition moments will be
               evaluated, currently only in dipole-length approximation)
        If its sign is positive, density-matrices are printed for ACES2,
        if negative, for Columbus.
        If this flag is turned on, the corresponding equations (lambda
        equations, derivative amplitude equations etc.) are solved 
        automatically.
     7. (conver) 0 - default.
                 1 - do not use, buggy
                 2 - reduces memory requirement for perturbative
                     approaches, it is set by xmrcc automatically.
     8. (symm) Spatial symmetry. For the numbering of irreducible 
        representations see the program calculating the integrals.
        Type zero to neglect spatial symmetry.
     9. (diag) Type of diagonalization algorithm in case of CI: 
        0 - standard Davidson diagonalization; 1 - other algorithm
        using only two expansion vectors (see Refs. 1 and 2), useful for
        very large CI vectors; 2 - Davidson diagonalization with root-
        following.
    10. (CS) 1 - closed shell reference determinant, 0 - open shell.
    11. (spatial) Type of orbitals: 1 - spatial orbitals, 0 - 
        unrestricted orbitals (available only with ACES2)
    12. (HF) 1 if the Restricted Hartree-Fock determinant is applied
         as the Fermi vacuum, 0 otherwise.
    13. (ndoub) Number of roots in case of open shell system.
    14. (nacto) Number of active occupied orbitals.
    15. (nactv) Number of active virtual orbitals. Up to n-fold 
        excitations from the determinants in the nacto x nactv CAS 
        reference space are included where n is flag 1. See Ref 3.
        for details. The nacto pieces of orbitals under and nactv pieces
        of orbitals above the Fermi level are supposed to be active
        if the active MOs are not specified in the fourth line (see 
        bellow). For single-reference calculations option 14 and 15
        equal simply zero.
    16. (tol) Tolerance parameter: the accuracy of the calculated energy
        is 10^(-tol).
    17. (maxex) Level of highest excitation included in the cluster 
        operator in case of MR calculations. In an MR calculation all
        single, double (or higher) excitations out of the reference 
        determinants are included in the cluster operator, however,
        the very high excitations are usually irrelevant. With this
        option they can be dropped. If this flag is set to n, only up 
        to n-fold clusters are included in the MR calculation. The 
        excitation manifold can be further selected by imposing 
        constrains on the number of active/inactive labels of the
        cluster operator (see the remarks for line 5). If the value of
        this option is 0, the excitation manifold is not truncated.
        Use this option also to reduce the memory requirement in case
        of SR calculations (see below).
    18. (sacc) Spin-adapted CC (under construction)
    19. (freq) Frequency for frequency-dependent properties.
    20. (dboc) Diagonal Born-Oppenheimer correction (DBOC), available
        for CI with ACESII.
    21. (memory) Available memory in MBytes (as an integer number)
   Second line - dummy line, for information.
   Third line (optional) - occupation of Fermi-vacuum. Type as many
        integers as the number of correlated orbitals: 2 for doubly 
        occupied orbitals, 1 for open shell orbitals with alpha 
        electron, -1 for open shell orbitals with beta electron, 0 
        otherwise.
        Note that the numbering of orbitals is different from that of
        the parent programs. Here the order of MOs: doubly occupied,
        open shell, virtual and in each of this blocks the MOs are 
        reordered according to the orbital energies (natural orbital
        occupations in case of MCSCF orbitals).
        Frozen orbitals are not passed to the program (they are
        "integrated out") and there is no explicit reference to them 
        any more.
        If this line is omitted, the program will fill the orbitals
        with electrons from the bottom automatically. In this manner
        we do not need this line for closed shells or a doublet ref.
        det., but e.g. for high spin states the Fermi vacuum must be
        defined here.
    Fourth line (optional) - active orbitals. Use this line if the
        automatic selection of active orbitals described at flag 15
        is not sufficient. Type 1 for active orbitals and 0 for inactive
        ones. This is useful for defining complicated active spaces.
    Fifth line (optional) - maximum number of inactive labels. One can
        impose restrictions on the cluster operator using this line.
        The maximum number of virtual/occupied inactive labels on the
        singly, doubly, ... excited clusters can be specified here. 
        E.g.:   1 2 2 1 
        In this case the single, double, triple and quadruple 
        excitations are allowed to have maximum of 1 2 2 1 inactive
        virtual and occupied labels, respectively. (For examples see 
        Ref. 4).

IV. The programs of the suite (for advanced users only)

      dmrcc - Driver for the program system. It calls goldstone, xmrcc,
        and mrcc. It suffices to run only dmrcc but advanced users may
        run these programs one-by-one (e.g. for the purpose of 
        debugging) in the following order: goldstone -> [xmrcc] -> 
        mrcc (note that execution of xmrcc is optional, see below).
      goldstone - This program generates the formula files. Note
        that it is sufficient to run it once if the same type of 
        calculation is repeated (e.g. potential energy curve, geometry
        optimization, etc). The program goldstone estimates the memory
        usage of the calculation. This is a crude (the symmetry is not 
        treated exactly) but quick estimate. The real memory 
        requirement, which is usually smaller, can be calculated by 
        running xmrcc after goldstone. 
      xmrcc - Calculate the correct memory requirement. Note that it may
        take a couple of minutes for complicated wave functions (e.g. 
        MRCC derivatives). It prints out 5 numbers at the end (MBytes):
          Total -  Real*8 + Integer = the minimal and the optimal amount
               of total required memory, it isn't worth starting the 
               calculation if the real physical mem. of the machine is 
               smaller than the minimal value.
          Real*8 - minimal and optimal memory for real*8 arrays, it is
               allocated at the beginning and it is estimated by
               goldstone. By running xmrcc, the goldstone estimate is
               automatically replaced by the 'optimal' value. If the
               physical mem. of the machine is smaller than the 'Total
               optimal' value, a number between the minimal and 
               optimal 'Real*8' value should be written manually to the 
               first line of the formula file (fort.14) instead
               of the optimal value (of course, the performance of the
               program is optimal with the 'optimal' value);
          Integer - memory allocated by mrcc later for integer arrays,
               nothing to do with it;
        The memory requirement can be further reduced by special tricks
        (see section 'Memory requirement').
      mrcc - It performs the numerical calculations.

V. Memory requirements (for advanced users only)

     Please note that dmrcc carries out the optimization of memory 
     requirements described in this section, so you do not need to do it
     manually if you use dmrcc and you can skip this section.

     If the memory requirement is too large, it can be reduced by 
     dirty tricks. By setting the number of active orbitals to some 
     non-zero value the set of orbitals is divided into active and
     inactive parts and all quantities are split up into several parts
     according to the number of active/inactive indices. In this case
     only one type must be stored in the memory which reduces the memory
     requirement. In this case practically a MR calculation is 
     performed, but the result is the same. Of course, the program
     slows down due to the increased IO.
     Recipe:
     1) Set the number of active occupied orbitals (nacto) to approx.
        half of the number of the electrons (but always to an even 
        number).
     2) If the memory requirement is still too large, set the number of 
        active virtual orbitals (nactv) to approx. half of the number of
        the virtual spin-orbitals (always to an even number) and set 
        maxex to the excitation level (flag 1).

     If these tricks are applied with the restart facility, the lower
     level calculations must also be performed with the same nacto/nactv
     values, but maxex must be equal to ex.lev.

     See 'conver' for reducing memory requirement for perturbative 
     approaches.

VI. Support
     kallay@mail.bme.hu

VII. References
     1. J. Chem. Phys. 113, 1359 (2000)
     2. J. Chem. Phys. 115, 2945 (2001)
     3. J. Chem. Phys. 117,  980 (2002)
     4. J. Chem. Phys. 119, 2991 (2003)
     5. J. Chem. Phys. 120, 6841 (2004)
     6. J. Chem. Phys. 121, 9257 (2004)
     7. J. Chem. Phys. 123, 214105 (2005)