.. include:: autodoc_abbr_options_c.rst .. index:: Cfour .. _`sec:cfour`: Interface to CFOUR by J. Stanton and J. Gauss ============================================= .. codeauthor:: Lori A. Burns .. sectionauthor:: Lori A. Burns *Module:* :ref:`Keywords `, :ref:`PSI Variables `, :ref:`Samples ` |PSIfour| contains code to interface to the Cfour quantum chemistry suite of John F. Stanton (U. Texas, Austin) and J\ |u_dots|\ rgen Gauss (U. Mainz), which is available after a license agreement from `http://www.cfour.de/ `_. Installation ~~~~~~~~~~~~ Follow the instructions provided with the Cfour download to install the executable or to build the source. To by used by |PSIfour|, the program binary (:program:`xcfour`) must be found in your :envvar:`PATH` or :envvar:`PSIPATH`. The ``GENBAS`` file containing basis sets in Cfour format is not necessary for this interface, but if you prefer to access basis sets the "Cfour way" using a custom ``GENBAS`` file (the distributed one is included with the interface), it, too, must be in :envvar:`PATH` or :envvar:`PSIPATH`. If |PSIfour| is unable to execute the binary, an error will be reported. .. .. caution:: The p4c4 interface isn't in the master branch nor will it be in .. the near future. To run this code, (1) build the ``c4`` branch of psi4, .. (2) find a copy of cfour and put it in :envvar:`PATH` or .. :envvar:`PSIPATH`, and (3) clone https://github.com/loriab/qcdb.git .. python module and prepend :envvar:`PYTHONPATH` with the top qcdb .. directory (the path added to PYTHONPATH should have one "qcdb" in it; .. the cloned qcdb is what needs to be imported in preference to the one .. already in psi4). Execute psi4 as usual. .. caution:: The p4c4 interface hasn't been fully adapted for the new March 2014 version. Cfour for |PSIfour| Users ~~~~~~~~~~~~~~~~~~~~~~~~~ * Set memory as usual * Set molecule as usual * Set basis set as usual (Cfour only cares about orbital basis, no fitting bases) * Set the task as usual, indicating Cfour as the intended code by prepending "c4-" to the method argument. So ``energy('scf')`` becomes ``energy('c4-scf')`` and ``optimize('ccsd(t)')`` becomes ``optimize('c4-ccsd(t)')``. Find available methods for :py:func:`~driver.energy` at :ref:`Energy (CFOUR) ` and for :py:func:`~driver.optimize` at :ref:`Gradient (CFOUR) `. * Generally, the p4c4 interface will handle best practices for path of execution: ``vcc``/``ecc``, derivative type, *etc.* The user is still responsible for setting convergence, frozen core, guess, diis, *etc.* For the moment, so-called "best-practices" keywords are summarized at :ref:`Best Practices `. * For the type of computation intended, find appropriate options at :ref:`Keywords `. These keyword summaries contain the same information as the `proper CFOUR options list `_ plus notes on keyword relevance when run through |PSIfour|. Information at the `CFOUR manual `_ may also be useful, as may the many samples at :source:`samples/cfour`. * Set Cfour keywords just like |PSIfour| keywords. The names of keywords are unchanged beyond a prepended "cfour\_". (Though be aware that common abbreviations like CALC and REF must be fully spelled out as |cfour__cfour_calc_level| and |cfour__cfour_reference| when used in |PSIfour|.) * In limited trial cases, keywords nominally directed at non-Cfour modules are translated into their Cfour counterparts. For example, setting |scf__reference| will appropriately set |cfour__cfour_reference|. For a list of applicable keywords, see source of :py:func:`qcdb.cfour.muster_psi4options`. * Consult :ref:`sec:cfourFunctionality` for information on what Cfour functionality is accessible through |PSIfour|. |PSIfour| for Cfour Users ~~~~~~~~~~~~~~~~~~~~~~~~~ In the simplest use of the Psi4/Cfour interface, a |PSIfour| input file can simply "wrap" a ``ZMAT`` file and execute :program:`xcfour`. This is illustrated in the following example:: cfour { UHF-SCF energy calculation N H 1 R H 1 R 2 A R=1.008 A=105.0 *ACES2(CALC=HF,BASIS=qz2p MULT=2,REF=UHF OCCUPATION=3-1-1-0/3-0-1-0 SCF_CONV=12 MEMORY=20000000) } energy('cfour') Here, the contents of the ``cfour {...}`` block are written directly to a ``ZMAT`` file. This is joined by a default ``GENBAS`` file (:source:`share/basis/GENBAS`). To preferentially use your own ``GENBAS``, place it in :envvar:`PATH` or :envvar:`PSIPATH`. The line calling :py:func:`~driver.energy` with argument ``'cfour'`` invokes :program:`xcfour`. After execution of the ``energy('cfour')`` line completes, Cfour results are read back into |PSIfour| format and are thereafter accessible for further processing in the input file. See :ref:`sec:cfourOutput` for details. This storage of results in variables and arrays *in memory* for the duration of the |PSIfour| instance (as opposed to solely *in files*) is the only advantage thus far incurred by the P4C4 interface. We'll call this mode of basic utility the "sandwich" mode. Molecule specification in |PSIfour| allows Cartesians, Z-matrices, mixed Cartesian/Z-matrix, negation of variables, delayed specification of variables, specification of fragments, etc., all in a whitespace-tolerant format. See :ref:`sec:moleculeSpecification` for details and :srcsample:`cfour/mints5` for examples. When a |PSIfour|-style molecule is supplied, its geometry is written to ``ZMAT`` in Cartesian form and the |cfour__cfour_coordinates|\ =CARTESIAN, |cfour__cfour_units|\ =ANGSTROM, |cfour__cfour_charge|, and |cfour__cfour_multiplicity| keywords are set appropriately in the ``*CFOUR(...)`` directive. .. warning:: There exist molecules (*e.g.*, allene) where the inertial frame is not unique (planes along atoms or between atoms). The orientation reconciling machinery currently does not handle these cases and will fail with "Axis unreconcilable between QC programs". I will get to this soon. Whenever the molecule is supplied in |PSIfour| format, the job control keywords must be too. All :ref:`Cfour keywords ` are the usual ones, prepended by ``cfour_`` to avoid any possible name conflicts. As detailed in :ref:`sec:jobControl`, setting keywords is flexible in format. The previous example translates to:: # UHF-SCF energy calculation molecule { 0 2 # multiplicity from the MULT keyword N H 1 R H 1 R 2 A R=1.008 A=105.0 } set { cfour_CALC_level=HF # only full keyword names allowed cfour_BASIS=qz2p #MULT=2 # now in molecule {...} block cfour_REFerence=UHF cfour_OCCUPATION [[3, 1, 1, 0], [3,0,1,0] ] # arrays in python notation cfour_SCF_CONV=12 cfour_MEMORY=20000000 } energy('cfour') Here, note that none of capitalization, equals sign, or whitespace matter for the keyword commands. Specifcation of strings and integers requires no translation; :ref:`booleans ` have extended freedom of format; arrays must be translated into Python-style (square-bracket bounded and comma delimited) of appropriate dimension. There are many sample inputs in :source:`tests/cfour/` starting with ``sp-`` that take examples from the Cfour manual and first run them in sandwich mode and then run them as translated into |PSIfour| format. .. note:: |PSIfour| only recognizes keywords by their full name, so the common Cfour keyword abbreviations CALC, REF, etc. must be replaced by their proper names of |cfour__cfour_calc_level|, |cfour__cfour_reference|, etc. Whenever the molecule is supplied in |PSIfour| format, it is possible to perform geometry optimizations where Cfour supplies the gradient and the |PSIfour| module :ref:`optking ` drives the structural changes. Because of the limitations on geometry specification for optimizations in Cfour, optking-driven optimizations are the *only* optimizations allowed in the P4C4 interface. (The exception is sandwich mode, which, of course, permits optimizations with the Cfour optimizer.) Below is an example of a geometry optimization:: memory 200 mb molecule { O H 1 R H 1 R 2 A R=0.958 A=104.5 } set { cfour_CALC_level CCSD(T) cfour_BASIS DZP cfour_CC_CONV 12 cfour_LINEQ_CONV 12 cfour_SCF_CONV 12 g_convergence cfour } optimize('cfour') Note that the primary change is the exchange of :py:func:`~driver.energy` for :py:func:`~driver.optimize` to trigger an optimization. Setting |optking__g_convergence|\ =CFOUR provides a good imitation of Cfour default convergence criteria. Although Cfour produces gradients only in its standard orientation and atom ordering, these are transformed back to input orientation by the P4C4 interface. Several sample inputs in :source:`tests/cfour/` starting with ``opt-`` show basic geometry optimizations. :srcsample:`cfour/mints5-grad` shows optimizations from a variety of molecule input formats, and :srcsample:`cfour/psi-ghost-grad` shows an optimization with ghosted atoms. To obtain a single gradient *sans* optimization, call instead :py:func:`~driver.gradient`. Note that it can be convenient to monitor the progress of a geometry optimization by grepping the tilde ``~`` character. :: Measures of convergence in internal coordinates in au. Criteria marked as inactive (o), active & met (*), and active & unmet ( ). --------------------------------------------------------------------------------------------- ~ Step Total Energy Delta E MAX Force RMS Force MAX Disp RMS Disp ~ --------------------------------------------------------------------------------------------- ~ Convergence Criteria 1.00e-06 * 3.00e-04 * 1.00e-06 * 1.20e-03 * o ~ --------------------------------------------------------------------------------------------- ~ 1 -76.33224285 -7.63e+01 2.41e-03 1.60e-03 1.51e-02 8.82e-03 o ~ 2 -76.33226097 -1.81e-05 4.84e-04 4.03e-04 7.71e-04 * 7.04e-04 o ~ 3 -76.33226140 -4.39e-07 * 4.31e-05 * 3.58e-05 9.89e-05 * 8.93e-05 o ~ 4 -76.33226141 -4.26e-09 * 9.76e-07 * 6.58e-07 * 6.22e-06 * 3.71e-06 o ~ --------------------------------------------------------------------------------------------------------------- ~ Step Total Energy Delta E MAX Force RMS Force MAX Disp RMS Disp ~ --------------------------------------------------------------------------------------------------------------- ~ 1 -76.332242848098 -76.332242848098 0.00241281 0.00160359 0.01507630 0.00881949 ~ 2 -76.332260965382 -0.000018117284 0.00048446 0.00040256 0.00077146 0.00070447 ~ 3 -76.332261404452 -0.000000439070 0.00004307 0.00003577 0.00009889 0.00008926 ~ 4 -76.332261408714 -0.000000004262 0.00000098 0.00000066 0.00000622 0.00000371 ~ --------------------------------------------------------------------------------------------------------------- ~ The above example also shows the total memory for the computation being set in |PSIfour| format. See :ref:`sec:memory` for details. When specified, the memory value is passed on to Cfour by setting keywords |cfour__cfour_memory_size| and |cfour__cfour_mem_unit|\ =MB. |PSIfour| has an extensive :ref:`basis set library ` in Gaussian94 format. See :ref:`sec:basisSets` for details. Contrasts to Cfour basis handling include identifying basis sets by standard name (aug-cc-pVDZ instead of AUG-PVDZ), direct handles for diffuse-function-pruned sets (*e.g.*, jun-cc-pVDZ), case insensitivity, appropriate setting of spherical/Cartesian depending on basis set design, and syntax to set different basis sets to different classes of atoms without listing each atom. All of these features are available to Cfour by using the |mints__basis| keyword instead of |cfour__cfour_basis| (accompanied, of course, by specifying the molecule |PSIfour|-style). Internally, |PSIfour| processes the basis set as usual, then translates the basis set format and writes out a ``GENBAS`` file with an entry for each atom. The P4C4 interface sets keyword |cfour__cfour_basis|\ =SPECIAL and |cfour__cfour_spherical| as appropriate, then writes the basis section necessary for SPECIAL below the ``*CFOUR(...)`` block. (I'm sorry that the name of the basis doesn't appear in ``ZMAT``, but the combination of the ~14 character basis name limit and the absence of a comment line marker rather precludes that helpful label.) The input below employs a |PSIfour| library basis set and also introduces the final stage of conversion toward |PSIfour| format. Instead of the generic ``'cfour'``, the computational method is specified as the first argument to the :py:func:`~driver.optimize` call. In the computational command below, the string argument ``'c4-ccsd(t)'`` directs that a CCSD(T) computation be run using Cfour (as opposed to ``'ccsd(t)'`` which would call |PSIfour| CC code). Specifying computational method in this manner sets |cfour__cfour_calc_level| from the argument and |cfour__cfour_deriv_level| as appropriate from the function call: :py:func:`~driver.energy`, :py:func:`~driver.gradient`, or :py:func:`~driver.optimize`. If those keywords are also set explicitly to contradictory values, the interface will complain. :: memory 2 gb molecule CH2F2 { units au C 0.0000000000 -0.0000000000 1.0890958457 F 0.0000000000 -2.1223155812 -0.4598161475 F -0.0000000000 2.1223155812 -0.4598161475 H 1.7084139850 0.0000000000 2.1841068002 H -1.7084139850 -0.0000000000 2.1841068002 } set basis aug-cc-pvdz set rms_force_g_convergence 6 set cfour_abcdtype aobasis set cfour_scf_conv 12 set cfour_cc_conv 12 set cfour_lineq_conv 12 optimize('c4-ccsd(t)') The utility of this method specification is that examination can be made of the reference, the derivative level, the excitation level, *etc.* and some options can be set according to best practices. Practically speaking, |cfour__cfour_cc_program| (and eventually |cfour__cfour_abcdtype|) will always be set to the :ref:`fastest safe value `. For example, the input above will run with |cfour__cfour_cc_program|\ =ECC unless explicitly set to VCC. An advantage of |PSIfours| Python driver is that any number of common work-up procedures can be automated and wrapped around the the conventional single-point and optimization procedures at the heart of all quantum chemistry codes. Three core "wrappers" available in |PSIfour| are :py:func:`~driver_nbody._nbody_gufunc`, :py:func:`~wrapper_database.database`, and :py:func:`~driver_cbs.complete_basis_set`; read their respective sections for details, but an overview is provided here. :py:func:`~driver_nbody._nbody_gufunc` computes the interaction energy of a bimolecular complex (counterpoise-corrected, not, or both). :: molecule dimer { Ne -- Ne 1 R symmetry c1 } Rvals=[2.5, 3.0, 4.0] set basis aug-cc-pVDZ for R in Rvals: dimer.R = R ecp = cp('c4-mp2') print_stdout('R [A] = %.1f IE [kcal/mol] = %.3f\n' % (R, psi_hartree2kcalmol * ecp)) yields :: R [A] = 2.5 IE [kcal/mol] = 0.804 R [A] = 3.0 IE [kcal/mol] = 0.030 R [A] = 4.0 IE [kcal/mol] = -0.014 Next, the :py:func:`~wrapper_database.database` wrapper allows any computational model chemistry to be applied a predefined collection of molecules. Thus an input :: set { basis jun-cc-pvdz d_convergence 9 } database('c4-mp2','nbc10',cp='on',subset='MeMe') yields the counterpoise-corrected interaction energy for several points along the dissociation curve of methane dimer, which is a member of the :srcdb:`NBC10` database:: //>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>// // Database nbc10 Results // //<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< Requested Energy <== ---------------------------------------------------------------------------------------------- Reaction Reaction Energy Error Reagent 1 Reagent 2 Ref Calc [kcal/mol] [H] Wt [H] Wt ---------------------------------------------------------------------------------------------- NBC1-MeMe-3.2 0.0690 1.1639 1.0949 -80.72700202 1 -40.36442840 -2 NBC1-MeMe-3.3 -0.2390 0.6709 0.9099 -80.72764911 1 -40.36435916 -2 NBC1-MeMe-3.4 -0.4170 0.3407 0.7577 -80.72806043 1 -40.36430165 -2 NBC1-MeMe-3.5 -0.5080 0.1244 0.6324 -80.72831099 1 -40.36425461 -2 NBC1-MeMe-3.6 -0.5410 -0.0129 0.5281 -80.72845373 1 -40.36421659 -2 NBC1-MeMe-3.7 -0.5390 -0.0961 0.4429 -80.72852567 1 -40.36418623 -2 NBC1-MeMe-3.8 -0.5150 -0.1430 0.3720 -80.72855247 1 -40.36416227 -2 NBC1-MeMe-3.9 -0.4800 -0.1659 0.3141 -80.72855167 1 -40.36414365 -2 NBC1-MeMe-4.0 -0.4390 -0.1733 0.2657 -80.72853498 1 -40.36412938 -2 NBC1-MeMe-4.1 -0.3960 -0.1712 0.2248 -80.72850993 1 -40.36411859 -2 NBC1-MeMe-4.2 -0.3540 -0.1633 0.1907 -80.72848118 1 -40.36411044 -2 NBC1-MeMe-4.3 -0.3150 -0.1525 0.1625 -80.72845143 1 -40.36410422 -2 NBC1-MeMe-4.4 -0.2790 -0.1403 0.1387 -80.72842215 1 -40.36409932 -2 NBC1-MeMe-4.6 -0.2170 -0.1155 0.1015 -80.72836761 1 -40.36409177 -2 NBC1-MeMe-4.8 -0.1680 -0.0933 0.0747 -80.72831991 1 -40.36408563 -2 NBC1-MeMe-5.0 -0.1300 -0.0747 0.0553 -80.72827951 1 -40.36408021 -2 NBC1-MeMe-5.4 -0.0800 -0.0479 0.0321 -80.72821875 1 -40.36407122 -2 NBC1-MeMe-5.8 -0.0500 -0.0312 0.0188 -80.72817678 1 -40.36406353 -2 ---------------------------------------------------------------------------------------------- Minimal Dev 0.0188 Maximal Dev 1.0949 Mean Signed Dev 0.3509 Mean Absolute Dev 0.3509 RMS Dev 0.4676 ---------------------------------------------------------------------------------------------- Thirdly, the :py:func:`~driver_cbs.complete_basis_set` wrapper allows any compound computational method that can be expressed through :ref:`CBS ` to be applied to a molecule while employing the minimum number of calculations. For example, the job below computes a triple-quadruple-zeta Helgaker extrapolation of the mp2 correlation energy atop a quadruple zeta reference to which is appended a double-triple-zeta Helgaker extrapolated ccsd(t) - mp2 delta correction. Since the mp2 has been requested through |PSIfour| and the ccsd(t) through Cfour, the wrapper runs only MP2/cc-pVQZ (P4), CCSD(T)/cc-pVDZ (C4), and CCSD(T)/cc-pVTZ (C4) single-points. :: molecule { H 0.0 0.0 0.0 H 1.0 0.0 0.0 } set mp2_type conv cbs('mp2', corl_basis='cc-pV[TQ]Z', delta_wfn='c4-ccsd(t)', delta_basis='cc-pV[DT]Z') This yields:: ==> CBS <== --------------------------------------------------------------------------------------------------------- Stage Method / Basis Energy [H] Scheme --------------------------------------------------------------------------------------------------------- scf scf / cc-pvqz -1.10245974 highest_1 corl mp2 / cc-pv[tq]z -0.03561890 corl_xtpl_helgaker_2 delta c4-ccsd(t) - mp2 / cc-pv[dt]z 0.03507767 corl_xtpl_helgaker_2 total CBS -1.10300098 --------------------------------------------------------------------------------------------------------- Note that especially for :py:func:`~driver_cbs.complete_basis_set`, the basis set needs to be specified through |mints__basis|, not |cfour__cfour_basis|. Many of the wrappers can be used in combination to, for example, apply a compound method to every molecule in a database or to optimize a molecule with an extrapolated basis set (findif only for the moment- analytics coming). Finally, any number and combination of jobs can be run from a single |PSIfour| input file. Depending on the nature of preceeding or following jobs, it is prudent to separate them with the following:: clean() # removes Psi4 scratch files clean_variables() # empties the PSI variables list cfour {} # empties the cfour block .. warning:: Because p4c4 does not inspect the contents of the ``cfour {...}`` block, once the user specifies a |PSIfour|-style molecule, the interface cannot judge whether a sandwich mode (drop the |PSIfour| molecule and use the cfour block as the entirety of the ``ZMAT``) or a standard mode (translate the |PSIfour| molecule and append additional input from the cfour block) is intended. The latter is what actually occurs. If there is both a |PSIfour| molecule and a molecule in the cfour block, ``ZMAT`` *will* end up with multiple molecules and multiple ``*CFOUR(...)`` blocks, and it *will not* run. Therefore, if mixing sandwich and standard or pure-\ |PSIfour| computations in an input file, place all the sandwich jobs at the beginning before declaring |PSIfour| molecules. If necessary, clear the cfour block with ``cfour {}`` before commencing standard P4C4 jobs. .. _`sec:cfourOutput`: Output ~~~~~~ The output of :program:`xcfour` invoked from a |PSIfour| input file is written to the |PSIfour| output file as the computation progresses. If a Cfour module terminates with a non-zero error code, the value will show up in :psivar:`CFOUR ERROR CODE `. .. rubric:: Energies & Scalars After execution of :program:`xcfour` has completed, the output string is extensively parsed and appropriate results are stored in :ref:`PSI Variables `. All gleaned variables are printed in the Cfour output section of the |PSIfour| output file, as shown below. :: //>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>// // Cfour c4-ccsd(t) Energy Results // //<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< -0.007263598030 "CCSD CORRELATION ENERGY" => -0.275705492359 "CCSD TOTAL ENERGY" => -76.338453952539 "CCSD(T) CORRELATION ENERGY" => -0.007263598030 "CCSD(T) TOTAL ENERGY" => -76.345717550569 "CFOUR ERROR CODE" => 0.000000000000 "CURRENT CORRELATION ENERGY" => -0.007263598030 "CURRENT ENERGY" => -76.345717550569 "CURRENT REFERENCE ENERGY" => -76.062748460180 "MP2 CORRELATION ENERGY" => -0.270191667755 "MP2 OPPOSITE-SPIN ENERGY" => -0.204890356651 "MP2 SAME-SPIN ENERGY" => -0.065301311104 "MP2 TOTAL ENERGY" => -76.332940127935 "NUCLEAR REPULSION ENERGY" => 9.187331653300 "SCF TOTAL ENERGY" => -76.062748460180 The PSI Variables are also available from the input file for manipulation. For instance, to compute the MBPT 2 3/4 energy from MBPT 3 results, the following could be used. :: energy('c4-mp3') mp2p75_corl = 0.75 * get_variable('mp3 correlation energy') + \ 0.25 * get_variable('MP2 correlation energy') print mp2p75_corl + get_variable('scf total energy') .. caution:: Some features are not yet implemented. Buy a developer a coffee. - No PSI Variables for properties: *e.g.*, :psivar:`SCF DIPOLE X` - No PSI Variables for excited state energies The formation of further regexes for properties, excited states, etc. is one of the primary areas in which this interface requires further work. .. rubric:: Gradients and Arrays In addition to parsing the output stream, results are collected from files written to the scratch directory. Presently, the ``GRD`` file is parsed and printed to the output file, as shown below. Also printed is the Cfour gradient after manipulation by the P4C4 interface and used by |PSIfour| going forward. Manipulation is necessary because Cfour determinedly uses its own internal orientation and atom ordering while |PSIfour| naturally expects the gradient to be aligned with the active molecule. The geometry in ``GRD`` and the geometry of |PSIfours| active molecule are shifted, rotated, flipped, and otherwise badgered into coincidence, then the same manipulations are applied to the gradient in ``GRD``, the result of which is printed below and passed on to Optking. :: //>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>// // Cfour c4-scf Gradient Results // //<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<` object through :py:func:`psi4.get_gradient`. .. rubric:: Cfour Files The contents of all files associated with Cfour are accessible from the input file through the Python dictionary ``P4C4_INFO``. That is, ``P4C4_INFO['zmat']`` returns a string of the input file sent to Cfour. Accessible arguments are ``zmat``, ``output``, and any that have been produced of ``grd``. For example, to print to the screen if CC convergence is reached, the following could be placed in the |PSIfour| input file. :: energy('c4-ccsd') print 'miracle?', 'miracle' in P4C4_INFO['output'] .. rubric:: Scratch Files By default, a separate subdirectory for each Cfour call is created within the job's scratch directory. To explicitly specify the location of the the Cfour scratch, execute with, for example, ``energy('cfour', path='/full/path/to/cfour/scratch')``. Regardless of whether the location is specified or default, whether to preserve the scratch directory after the computation can be specified with ``energy('cfour', keep=True)`` or (the default) ``energy('cfour', keep=False)``. *path* and *keep* are keyword arguments that get interpreted by the :py:func:`~procedures.interface_cfour.run_cfour` function documented below. .. autofunction:: procedures.interface_cfour.run_cfour(name [, keep, path]) .. _`sec:cfourFunctionality`: Functionality ~~~~~~~~~~~~~ Through clever use of the ``cfour {...}`` block, one could run most any Cfour computation through the P4C4 interface. In contrast, enumerated below are tested functionalities where results from Cfour are collected into |PSIfour| data objects. .. rubric:: Implemented * Single-point :py:func:`~driver.energy` commands for :ref:`ground state methods `. Examples: :srcsample:`cfour/sp-rhf-ccsd_t_-ao-ecc`, :srcsample:`cfour/scf4`, :srcsample:`cfour/mints5`. * Analytic :py:func:`~driver.gradient` and :py:func:`~driver.optimize` commands for :ref:`ground state methods `. Real and Ghost atoms permitted (though the latter will naturally collapse after several cycles). Examples: :srcsample:`cfour/opt-rhf-ccsd_t_`, :srcsample:`cfour/mp2-1`, and :srcsample:`cfour/mints5-grad`. .. warning:: There exist molecules (*e.g.*, allene) where the inertial frame is not unique (planes along atoms or between atoms). The orientation reconciling machinery currently does not handle these cases and will fail with "Axis unreconcilable between QC programs". I will get to this soon. * Finite difference of energy :py:func:`~driver.gradient` and :py:func:`~driver.optimize` for :ref:`methods `. Force with ``gradient('name', dertype=0)``, *etc.*. * :py:func:`~driver_nbody._nbody_gufunc` for computation of interaction energies with or without counterpoise correction. Example: :srcsample:`cfour/dfmp2-1`. * :py:func:`~wrapper_database.database` for computation of a collection of molecules in a single input, with summarization of results. Examples: :srcsample:`cfour/pywrap-db1` and :srcsample:`cfour/psi-a24-grad`. * :py:func:`~driver_cbs.complete_basis_set` for computation of compound methods involving basis set extrapolations and/or delta corrections with any combination of |PSIfour| and Cfour computational methods and |PSIfour| basis sets. Example: :srcsample:`cfour/pywrap-cbs1`. .. rubric:: Not Yet Implemented * Ground state CI energies and optimizations * Excited state energies and optimizations * Properties are not yet regex-ed, transformed into input frame, and stowed in PSI Variables. * Property calls that required extra computation not yet translated into :py:func:`~driver.property` computation command * Frequencies Energy methods available through P4C4 interface .. include:: cfour_table_energy.rst Gradient methods available through P4C4 interface .. include:: cfour_table_grad.rst .. _`table:cfour_cc_program`: .. notes on preferred modules from JFS .. comment always abcdtype = aobasis (but sometimes .. comment ncc does rhf ccsdt(q) .. comment reccommended code to do with, not only code (b/c mrcc can do much of this) .. comment .. table:: Cfour coupled-cluster program defaults by calculation type .. comment .. comment +-----------------------------------------+---------------------------------+-----------------------+--------+--------+---------+ .. comment | | | | RHF | UHF | ROHF | .. comment | | | +--------+--------+---------+ .. comment | Driver Call, |cfour__cfour_deriv_level| | name, |cfour__cfour_calc_level| | |cfour__cfour_excite| | |cfour__cfour_cc_program| | .. comment +=========================================+=================================+=======================+========+========+=========+ .. comment | :py:func:`~driver.energy`, zero | cc2 | none | vcc | vcc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | _cc | _cc | _cc | .. comment | |vcc for everything +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | _cc | _cc | _cc | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | ccsd | none | ecc | ecc | ecc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | vcc | vcc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | vcc | vcc | vcc | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | ccsd(t) | none | ecc | ecc | ecc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | | | | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | | | | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | cc3 | none | vcc | vcc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | vcc | vcc | | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | | | | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | ccsdt (no aobasis sp or opt, also prob for cc3, or for eomea grad) .. comment ecc / vcc / vcc .. comment | none | ecc | ecc | ecc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | ecc | mrcc | mr_cc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomeano/eomipyes | ecc | | | .. comment +-----------------------------------------+---------------------------------+-----------------------+--------+--------+---------+ .. comment | :py:func:`~driver.optimize`, first | cc2 | none | vcc | vcc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | vcc | vcc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip not sure ask | vcc | vcc | vcc | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | ccsd | none | ecc | ecc | ecc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | vcc | vcc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | vcc | vcc | vcc | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | ccsd(t) | none | ecc | ecc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | | | | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | | | | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | cc3 | none | vcc | | | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | vcc | | | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | vcc | | | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | ccsdt | none | ecc | mrcc | mrc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | mrcc | mrcc | mrcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | mrcc | mrcc | mrcc | .. comment +-----------------------------------------+---------------------------------+-----------------------+--------+--------+---------+ .. comment properties same as grad .. comment 2nd deriv ecc only for ccsd(t) Specification Details ~~~~~~~~~~~~~~~~~~~~~ The above narrative introduction to the P4C4 interface should be sufficient to get started. Issues of competition between |PSIfour| and Cfour specification format are generally resolved behind the scenes: not according to a *simple* rule but according to sensible, sometimes intricate, rules governed by user intent (and integration of Cfour to behave like a |PSIfour| module). Much can be gleaned by just running inputs and inspecting the ``ZMAT`` passed to Cfour, but when questions arise, here are the specifics, the governing laws. * Specifying a piece of input in |PSIfour| format is entering into a contract that you mean it. In particular this applies to molecule (including charge/multiplicity through :samp:`molecule {optional_molecule_name} \\{...\\}`), memory (through :samp:`memory {value} {unit}`), computational method (through . If Cfour keywords are specified with values that contradict the |PSIfour| input, execution is halted. As an example, the input below is set up to fail in four ways: contradictory specification of memory, multiplicity, computational method, and derivative level. Note, though, that the ``cfour_units angstrom`` setting is permissible, since it concurs with the value implied in the molecule block. :: memory 300 mb molecule { H H 1 0.7 } set basis 6-31g set cfour_multiplicity 3 # clash with implicit singlet in molecule {} above set cfour_units angstrom # no problem, consistent with molecule {} above set cfour_memory_size 100000000 # clash with 300 mb above set cfour_calc_level ccsd # clash with 'c4-scf' below set cfour_deriv_level first # clash with energy() below (use gradient('c4-scf') to achieve this) energy('c4-scf') * Specifying anything in |PSIfour| format (molecule, basis, options, method call) starts building a ``*CFOUR(...)`` directive for the ``ZMAT`` file. Since the contents of the ``cfour {...}`` block are blindly appended to any input interpreted from |PSIfour| format, mixing of |PSIfour| and Cfour input formats likely *will* give rise to multiple ``*CFOUR(...)`` directives in the prospective ``ZMAT``, execution of which *will* be trapped and halted. Proper uses for the ``cfour {...}`` block are for the sandwich mode, where the entire ``ZMAT`` is enclosed, or for extra directives like ``%excite*``, which presently have no other specification route. * Specifying the basis is perhaps the regulated piece of input. Since basis set names differ between |PSIfour| and Cfour and it's not practical to compare exponent-to-exponent, any input file with both |mints__basis| and |cfour__cfour_basis| keywords present will halt. Once a basis set has been requested through |mints__basis|, overriding the default spherical/Cartesian setting must be done through |globals__puream| (as opposed to |cfour__cfour_spherical|). * Specifying keywords that control geometry optimization is straightforward. Unless the optimization is invoked in sandwich mode, all Cfour optimization keywords (*e.g.*, |cfour__cfour_geo_maxcyc|) are ineffective, as the Cfour optimizer is never invoked. |PSIfour| optimization keywords (*e.g.*, |optking__geom_maxiter|) instead fill these roles. * Specifying the computational method (through, for instance, ``energy('c4-ccsd')`` instead of ``energy('cfour')``) often sets additional keywords consistent with best practices (*e.g.*, |cfour__cfour_cc_program|). Since those settings are implicit, any explicit setting of those those keywords, whether contradicting or concurring, takes priority (halts never generated). The following are some concrete examples. For the moment, click the source button at :py:func:`qcdb.cfour.muster_modelchem` for details of what keywords get set. * runs in vcc since that's Cfour's default for cc_program :: set cfour_calc_level ccsd energy('cfour') * runs in ecc since Cfour's default overwritten by keyword :: set cfour_calc_level ccsd set cfour_cc_program ecc energy('cfour') * runs in ecc since that's best practice for the requested ccsd :: energy('c4-ccsd') * runs in vcc since *hidden* default overwritten by keyword :: set cfour_cc_program vcc energy('c4-ccsd') * Specifying certain keywords that are nominally applicable for pure-\ |PSIfour| modules directs them to fulfil analogous roles in the Cfour program (*e.g.*, |scf__maxiter| is used to set |cfour__cfour_scf_maxcyc|). This keyword translation only takes place if the keywords are explicitly set in the input file (part of that contract that you mean it), meaning that |PSIfours| defaults don't get imposed on Cfour. Also, in the case where a translatable pure-\ |PSIfour| keyword and its translation Cfour keyword are both set, the value attached to the latter is always used. Below are a few clarifying examples. * uses :math:`10^{-7}` SCF conv crit since that's Cfour's default for |cfour__cfour_scf_conv| :: energy('c4-scf') * uses :math:`10^{-6}` SCF conv crit since default overwritten by keyword :: set cfour_scf_conv 6 energy('c4-scf') * uses :math:`10^{-5}` SCF conv crit since default overwritten by :ref:`SCF module` keyword :: set d_convergence 5 energy('c4-scf') * uses :math:`10^{-6}` SCF conv crit since default overwritten by :ref:`SCF module` keyword (local scope works, too) where the |PSIfours| more flexible float input has been rounded down to the integer required by Cfour :: set scf d_convergence 5e-6 energy('c4-scf') * uses :math:`10^{-6}` SCF conv crit since default overwritten and Cfour module keyword trumps |PSIfour| SCF module keyword :: set cfour_scf_conv 6 set d_convergence 8 energy('c4-scf') The keyword translation feature is still in the proof-of-principle stage, so only a handful (found here) of keywords participate. .. note:: Longtime Cfour users who may consider this keyword translation a flaw rather than a feature can avoid it entirely by confining keywords to the :ref:`Cfour module` along with |mints__basis| and |globals__puream| (opt, too?) Misc. Running ~~~~~~~~~~~~~ Naturally, in |PSIfour| multiple jobs can be run in succession from the input file. Control optimizations with optking keywords HERE. Cfour ``GRD`` file is written to |PSIfour| output file. Gradient transformed back into the frame in which it was shipped off to Cfour is also written to the |PSIfour| output file and is available from input as :py:func:`~psi4.get_gradient`. sandwich mode := molecule and cfour list within Naturally, additional jobs can follow in the input file. Depending on the nature of preceeding or following jobs, it is prudent to separate them with the following:: clean() # removes Psi4 scratch files clean_variables() # empties the PSI variables list cfour {} # empties In this scheme, the contents of the ``cfour {...}`` block are tacked onto the end of the ``ZMAT`` file that is otherwise written from psi style format. It is by this route that, for example ``%excite*`` sections can at present be spcified. The execution of :program:`xcfour` can be modified by a few parameters. Setting the option |cfour__cfour_omp_num_threads| sets the environment variable :envvar:`OMP_NUM_THREADS` for only the duration of the Cfour computation. That is, portions of an input file that run |PSIfour| modules are unaffected. Additionally, there are a few arguments to the function :py:func:`~procedures.interface_cfour.run_cfour` that control the Cfour scratch directory. .. comment Notes to Self .. comment ~~~~~~~~~~~~~ .. comment .. comment Test checked-in GENBAS on installed copy .. comment .. comment Reference still not factoroed into cc_program! .. comment .. comment optimize on a sandwich calc? errors out .. comment .. comment .. comment .. _`table:cfour_cc_program`: .. comment .. comment .. table:: Cfour coupled-cluster program defaults by calculation type .. comment .. comment +-----------------------------------------+---------------------------------+-----------------------+--------+--------+---------+ .. comment | | | | RHF | UHF | ROHF | .. comment | | | +--------+--------+---------+ .. comment | Driver Call, |cfour__cfour_deriv_level| | name, |cfour__cfour_calc_level| | |cfour__cfour_excite| | |cfour__cfour_cc_program| | .. comment +=========================================+=================================+=======================+========+========+=========+ .. comment | :py:func:`~driver.energy`, zero | cc2 | none | vcc | vcc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | _cc | _cc | _cc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | _cc | _cc | _cc | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | ccsd | none | ecc | ecc | ecc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | ecc | _cc | _cc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | _cc | _cc | _cc | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | ccsd(t) | none | ecc | ecc | ecc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | _cc | _cc | _cc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | _cc | _cc | _cc | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | cc3 | none | vcc | vcc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | _cc | _cc | _cc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | _cc | _cc | _cc | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | ccsdt | none | ecc | ecc | ecc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | _cc | _cc | _cc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | _cc | _cc | _cc | .. comment +-----------------------------------------+---------------------------------+-----------------------+--------+--------+---------+ .. comment | :py:func:`~driver.optimize`, first | cc2 | none | _cc | _cc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | _cc | _cc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | _cc | _cc | vcc | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | ccsd | none | _cc | _cc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | _cc | _cc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | _cc | _cc | vcc | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | ccsd(t) | none | ecc | _cc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | _cc | _cc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | _cc | _cc | vcc | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | cc3 | none | _cc | _cc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | _cc | _cc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | _cc | _cc | vcc | .. comment | +---------------------------------+-----------------------+--------+--------+---------+ .. comment | | ccsdt | none | ecc | _cc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomee | _cc | _cc | vcc | .. comment | | +-----------------------+--------+--------+---------+ .. comment | | | eomea/eomip | _cc | _cc | vcc | .. comment +-----------------------------------------+---------------------------------+-----------------------+--------+--------+---------+ .. comment .. comment