README MANUAL FOR q3 v2.1 ========================= Prerequisites ------------- Review the license agreement in the "EULA.txt" file. If you do not agree with the terms and conditions of the license agreement, then do not use the software. Check for updates. The latest version can be downloaded from our website https://3ions.com. This manual assumes familiarity with the basic concepts of quantum chemistry calculations. Submit feedback, feature requests, bug reports using the "FEEDBACK" form at https://3ions.com. Installation ------------ There are several ways to run q3: 1. The q3 program "bin/q3" may be used like a standard command-line utility. Input settings are described below. Make sure to download the correct package for your CPU architecture (ARM64 or x86-64). ARM64 edition is optimized to work on latest cloud CPUs like GCP Axion and AWS Graviton. See "examples/0tutorial.in" to get started. 2. The pyq3 wrapper is a thin Python interface to q3. The Mole object stores all state. Its attributes closely correspond to the q3 input settings. Pyq3 is a convenient way to integrate with compute pipelines in Python. See "py/pyq3.py" for details. 3. Large-scale remote calculations using the Cloud Platform service. Command-line q3 and pyq3 Python interfaces are supported on any client OS. Visit https://3ions.com to sign up. To make Python modules available from the interpreter, add "py" subdirectory to the search path: export PYTHONPATH="$(pwd)/py:$PYTHONPATH" The q3 Cloud and q3 Enterprise editions support running jobs across multiple compute nodes. Sample timings using "examples/caffeine.in" are in the table. Note that the "Usage (CPU*hr)" value and correspondingly the dollar cost of a calculation stays nearly constant. This is due to the fact that doubling number of processors cuts job time in half. It is usually advantageous to use as many compute nodes as available. +----------------+-----+-----+-----+-----+-----+-----+-----+-----+ | Nodes | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | +----------------+-----+-----+-----+-----+-----+-----+-----+-----+ | CPUs | 64 | 128 | 192 | 256 | 320 | 384 | 448 | 512 | +----------------+-----+-----+-----+-----+-----+-----+-----+-----+ | Time (sec) |1021 | 517 | 350 | 269 | 213 | 176 | 152 | 133 | +----------------+-----+-----+-----+-----+-----+-----+-----+-----+ | Speedup | 1 | 2 | 2.9 | 3.8 | 4.8 | 5.8 | 6.7 | 7.7 | +----------------+-----+-----+-----+-----+-----+-----+-----+-----+ | Usage (CPU*hr) | 18 | 18 | 19 | 19 | 19 | 19 | 19 | 19 | +----------------+-----+-----+-----+-----+-----+-----+-----+-----+ Input description ----------------- The q3 program reads input from standard input and writes output to standard output: q3 < input.in > output.out or q3 input.in output.out Quick jobs can be performed directly from the command line: $ ./q3 -mb3lyp -jopt > O 0 0 0 631g > H 1 0 0 > H 0 1 0 > press Ctrl-D to finish input This will perform geometry optimization of a water molecule using Density Functional Theory with B3LYP functional and 6-31g basis set. All values in the program output are in ATOMIC UNITS unless specified explicitly. To see the list of all settings along with short descriptions and default values, issue: q3 -h To see over 100 available methods, use: q3 -X Basis sets are specified in the input file per-atom as shown in the example. Standard basis sets are supported: - Pople basis sets: 3-21g 6-31g* 6-311+g** ... - Correlation consistent basis sets: cc-pvdz aug-cc-pvqz cc-pcv5z ... - Karlsruhe basis sets: def2-svp def2-qzvpp ... - Polarization consistent basis sets: pc-0 aug-pc-2 aug-pcseg-1 ... - Miscellaneous basis sets: sto-3g sto-6g tzp ... See examples for various use cases in the "examples" directory. File "examples/0tutorial.in" describes input format in detail. Atom record format ------------------ The first non-comment line of input contains options (it can be omitted in q3 v2.1 and later). It is followed by one or more atom records. Atom records must be in format described below. Values in [] are optional. [] [|defgrid] [m=] [v=] H 0 0 -0.5 sto-6g 20/266 10/302 m=1.1 v= 0 0 0.02 1 0 0 0.5 defgrid m=2 v= 0 0 -0.02 There must be no space in "m=" and "v=". symbol or atomic number 3-vector atom position in selected units (see -U option) basis set name for atom; default "sto-3g" DFT grid spec list /; default based on grid level atom mass in Dalton; default for element if not specified 3-vector atom initial velocity in atomic units; default zero If specified, basis and grid are auto-filled for all atoms of same element. Most jobs use only some of the values. For example, grid has no effect on Hartree-Fock calculations and velocity is not used for geometry optimization. List of options --------------- The following settings are recognised both in the input file as well as command-line arguments. Command-line arguments override settings specified in the input file. q3 argument: -c integer pyq3 attribute: pyq3.Mole.charge Total charge of the molecular system. q3 argument: -D integer pyq3 attribute: pyq3.Mole.diismaxsp and pyq3.Mole.diisoff Maximum size of DIIS subspace. Set to 0 to disable DIIS. q3 argument: -G integer pyq3 attribute: pyq3.Mole.gridlevel Grid density level for Density Functional Theory. Must be a value in range [0,4]. Use higher value for a more dense grid. Grid may also be manually specified per-atom in the input file. q3 argument: -g string pyq3 attribute: pyq3.Mole.guess Initial density matrix guess for SCF procedure. Can be one of the following: "sad" for superposition of atomic densities or "hcore" for core Hamiltonian. q3 argument: -h or -? pyq3 attribute: none Print help message and exit. q3 argument: -I integer pyq3 attribute: pyq3.Mole.maxsteps Maximum number of optimization iterations or maximum number of molecular dynamics steps depending on the job type. q3 argument: -i integer pyq3 attribute: pyq3.Mole.scfmaxit Maximum number of SCF iterations. q3 argument: -J pyq3 attribute: none Print output in JSON format to stderr in the end of calculation. q3 argument: -j string pyq3 attribute: pyq3.Mole.job Job to perform: "sp" single point energy "grad" energy gradient "opt" geometry optimization (energy minimization) "nve" NVE molecular dynamics; output is xyz trajectory format when run with default verbosity "hs" analytical Hessian (energy second derivatives) "nhs" numerical Hessian (energy second derivatives) "nop" no-op: check input and do nothing; this is useful with increased verbosity (-vvv) q3 argument: -M integer pyq3 attribute: pyq3.Mole.memory Per-node memory limit in megabytes. The value will be used to determine whether optimal algorithms can be used during calculation. This parameter is automatically calculated from total amount of RAM by default. This value is not a strict limit. The program may allocate more memory for temporary storage. In case of multi-node calculations, the limit is per-node and the total limit is M*N where M is memory limit and N is number of nodes. Having enough memory for optimal algorithms can drastically improve performance. See white paper for more details: https://3ions.com/papers/distributed-in-core.pdf q3 argument: -m string pyq3 attribute: pyq3.Mole.method Method to use for the calculation. Method string may be "hf" for Hartree-Fock theory or one of DFT functionals. DFT method can be specified using one of two forms. The first form is a single common name of the exchange-correlation (XC) functional, e.g., "b3lyp", "pbeh", "tpss0", "wb97". The second form is comma-separated "exchange,correlation", e.g., "slater,vwn" or "tpss,tpss". If exchange name matches correlation, the setting can be shortened to a single string, i.e., "tpss,tpss" is the same as "tpss". Use "q3 -X" to see the list of all possible values. q3 argument: -P integer pyq3 attribute: pyq3.Mole.np Number of parallel threads to use. By default, all logical CPU cores available on the computer will be used. q3 argument: -S integer pyq3 attribute: pyq3.Mole.timestep Timestep for molecular dynamics in atomic units. The default value 50 is about 1.21 femtoseconds. q3 argument: -s integer pyq3 attribute: pyq3.Mole.spin Total spin of the molecular system. The value is the difference between number of alpha and beta electrons, i.e., spin = 2S = nalpha-nbeta = multiplicity-1. Use negative values to swap alpha/beta. q3 argument: -T integer pyq3 attribute: pyq3.Mole.opttol Geometry optimization tolerance for "opt" jobs. The integer argument will be used as a negative power of 10 to calculate the tolerance. E.g., "-T7" will result in tolerance value of 1e-7. Larger values result in smaller tolerance. Optimization is converged when energy difference for successive steps is less than tolerance and maximum/RMS gradient/displacement is less than square root of tolerance. q3 argument: -t integer pyq3 attribute: pyq3.Mole.scftol SCF convergence tolerance. The integer argument will be used as a negative power of 10 to calculate the tolerance. E.g., "-t9" will result in tolerance value of 1e-9. Convergence condition is met when energy difference for successive SCF iterations is less than tolerance and norm of orbital gradient is less than square root of tolerance. q3 argument: -U string pyq3 attribute: "unit" argument of pyq3.Mole constructor Units for XYZ positions of atoms in the input file. Use "ang" for Angstrom or "bohr" for Bohr atomic units. q3 argument: -u pyq3 attribute: pyq3.Mole.unrestricted Perform unrestricted UHF or UKS calculation. q3 argument: -V pyq3 attribute: none Print version and exit. q3 argument: -v pyq3 attribute: pyq3.Mole.verbose Increase verbosity to print additional information like list of basis set shells, MO energies, etc. Can be specified multiple times as -vv or -vvv. q3 argument: -X pyq3 attribute: none List all XC functionals that are available to be used as method. Naming of functionals follows Libxc. End of file.