| 1 |
\documentclass[letterpaper]{book} |
| 2 |
\usepackage{amssymb,amsmath,latexsym,hyperref,graphics,color} |
| 3 |
|
| 4 |
\setlength{\parindent}{0pt} |
| 5 |
\setlength{\parskip}{2ex plus 0.5ex minus 0.2ex} |
| 6 |
|
| 7 |
\begin{document} |
| 8 |
|
| 9 |
% Title Page |
| 10 |
\title{MADNESS Molecular electronic structure calculations} |
| 11 |
\date{Last Modification: 7/7/2016} |
| 12 |
\maketitle |
| 13 |
|
| 14 |
% Copyright Page |
| 15 |
\pagestyle{empty} |
| 16 |
\null\vfill |
| 17 |
\noindent |
| 18 |
This file is part of MADNESS. |
| 19 |
|
| 20 |
|
| 21 |
Copyright (C) 2007, 2010 Oak Ridge National Laboratory |
| 22 |
|
| 23 |
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public |
| 24 |
License as published by the Free Software Foundation; either version 2 of the License, or(at your option) any later |
| 25 |
version. |
| 26 |
|
| 27 |
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied |
| 28 |
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. |
| 29 |
|
| 30 |
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free |
| 31 |
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 32 |
|
| 33 |
For more information please contact: |
| 34 |
\begin{quote} |
| 35 |
Robert J. Harrison \\ |
| 36 |
Oak Ridge National Laboratory \\ |
| 37 |
One Bethel Valley Road \\ |
| 38 |
P.O. Box 2008, MS-6367 \\ |
| 39 |
Oak Ridge, TN 37831 \\ |
| 40 |
\\ |
| 41 |
email: [email protected] \\ |
| 42 |
tel: 865-241-3937 \\ |
| 43 |
fax: 865-572-0680 |
| 44 |
\end{quote} |
| 45 |
\newpage |
| 46 |
|
| 47 |
|
| 48 |
% Table of Contents Pages |
| 49 |
\clearpage |
| 50 |
\setcounter{page}{1} |
| 51 |
\pagenumbering{roman} |
| 52 |
|
| 53 |
\setcounter{tocdepth}{10} |
| 54 |
\renewcommand\contentsname{Table of Contents} |
| 55 |
\tableofcontents |
| 56 |
|
| 57 |
|
| 58 |
\clearpage |
| 59 |
\setcounter{page}{1} |
| 60 |
\pagenumbering{arabic} |
| 61 |
|
| 62 |
\chapter{Overview} |
| 63 |
|
| 64 |
\section{Capabilities} |
| 65 |
|
| 66 |
|
| 67 |
|
| 68 |
\section{Current status} |
| 69 |
|
| 70 |
The software is still in what might best described as pre-production |
| 71 |
quality. Most things mostly work, but there are enough quirks that |
| 72 |
unfortunately it is far from being a black box like most Gaussian |
| 73 |
codes. |
| 74 |
|
| 75 |
Using the code to do actual science is the most effective mechanism |
| 76 |
for us to find and fix issues, as well as to prioritize implementation |
| 77 |
effort. Please report problems, issues and functionality requests to the |
| 78 |
MADNESS issue tracker at XXXXXXXXXXXXXXX. |
| 79 |
|
| 80 |
\chapter{Configuring and building} |
| 81 |
|
| 82 |
This is just for LI-red for the purposes of the summer school. |
| 83 |
MADNESS should build out of the box on most Linux and Apple Macintosh |
| 84 |
boxes. Intel MKL is now free so you should alway use that (download |
| 85 |
from Intel), and there is an open source version of Intel TBB (Linux |
| 86 |
distributions should have that in their package managers). If you are |
| 87 |
building to run on a virtual machine you should configure with the |
| 88 |
never spin option. |
| 89 |
|
| 90 |
\begin{enumerate} |
| 91 |
\item Copy the modules from section \ref{sec:pbslired} below into your |
| 92 |
\verb+.bashrc+ file. You will be using the Intel compiler, MPI, MKL |
| 93 |
and TBB which is the recommended stack when running on a cluster. |
| 94 |
|
| 95 |
\item Clone MADNESS from |
| 96 |
\url{https://github.com/m-a-d-n-e-s-s/madness}. I (RJH) used |
| 97 |
revision {\tt a1b4bae8acf57ae363f24cb8a7ea9e7229a0d95f} for testing. |
| 98 |
|
| 99 |
\item {\tt cd madness} |
| 100 |
|
| 101 |
\item \verb+sh autogen.sh+ --- only need to do this after initial checkout |
| 102 |
|
| 103 |
\item \verb+autoreconf+ --- only need to do this if a configure script has changed |
| 104 |
|
| 105 |
\item Configure with this command |
| 106 |
\begin{verbatim} |
| 107 |
./configure --disable-shared \ |
| 108 |
CC=mpiicc CXX=mpiicpc +\verb+ MPICC=mpiicc MPICXX=mpiicpc |
| 109 |
\end{verbatim} |
| 110 |
If you have installed LIBXC you can specify it with option |
| 111 |
\begin{verbatim} |
| 112 |
--with-libxc=full-path-to-libxc+. |
| 113 |
\end{verbatim} |
| 114 |
|
| 115 |
\item \verb+make -j 10 libraries+ --- using just 10 processes on |
| 116 |
LI-red is to be social. Also, if building on your own machine note |
| 117 |
that some of the files can use over 2GB of memory to compile, so if |
| 118 |
you have limited memory you may need to restrict the number of |
| 119 |
processes. If compiling on {\tt cn-mem} I always use |
| 120 |
\verb+make -j libraries+ which uses maximum parallelism (since {\tt |
| 121 |
cn-mem} has 72 cores and 3 TB of memory. |
| 122 |
|
| 123 |
\item \verb+cd src/apps/moldft+ |
| 124 |
|
| 125 |
\item \verb+make moldft+ |
| 126 |
|
| 127 |
\item \verb+MAD_NUM_THREADS=10 ./moldft+ --- run a quick test (the {\tt input} file by default does LDA water which is quick). |
| 128 |
|
| 129 |
\end{enumerate} |
| 130 |
|
| 131 |
|
| 132 |
\chapter{Execution} |
| 133 |
|
| 134 |
To run {\tt moldft} with a single, multi-threaded process simply |
| 135 |
invoke the name of the executable with the name of the input file on |
| 136 |
the command line. If the input file is ommited, it defaults to a file |
| 137 |
named {\tt input}. E.g., |
| 138 |
|
| 139 |
\begin{verbatim} |
| 140 |
./moldft inputfilename |
| 141 |
\end{verbatim} |
| 142 |
|
| 143 |
|
| 144 |
Recommendations: |
| 145 |
\begin{itemize} |
| 146 |
\item Use Intel TBB if it is available since it is more scalable than the old task pool. |
| 147 |
\item By default, MADNESS will create one thread for every core in the |
| 148 |
computer, but even with TBB it may be more effective to use fewer threads |
| 149 |
(see the environment variable \verb+MAD_NUM_THREADS+). E.g., |
| 150 |
\begin{verbatim} |
| 151 |
MAD_NUM_THREADS=10 ./moldft inputfile |
| 152 |
\end{verbatim} |
| 153 |
\item Oversubscribing the cores can lead to very poor performance due to |
| 154 |
cache contention and locks/mutexes being held by de-scheduled |
| 155 |
threads. Oversubscription can happen due to other processes (of yourself or other users) |
| 156 |
running at the same time, or from use of hyperthreading (which on Intel processors |
| 157 |
makes one phyiscal core appear to the system as two cores). |
| 158 |
\item Many threads seem to interact badly with how we are using MPI. |
| 159 |
Thus, it can help both robustness and performance to use multiple |
| 160 |
MPI processes per node with fewer threads per processes. As a side benefit you |
| 161 |
can bind the threads associated with each process to execute on the same |
| 162 |
socket, which improves thread scaling. See the SeaWulf batch script below |
| 163 |
for an example. |
| 164 |
\end{itemize} |
| 165 |
|
| 166 |
To run in parallel using MPI to create multiple, multi-threaded |
| 167 |
processes use the command {\tt mpirun} (or on some systems {\tt |
| 168 |
mpiexec}) --- this is very system dependent so you may need |
| 169 |
additional options to specify where and how many processes are created |
| 170 |
(see below for use on SeaWulf and LI-red). E.g., |
| 171 |
|
| 172 |
\begin{verbatim} |
| 173 |
export MAD_NUM_THREADS=10 |
| 174 |
mpirun -np 12 ./moldft inputfilename |
| 175 |
\end{verbatim} |
| 176 |
|
| 177 |
\subsection{Environment variables} |
| 178 |
|
| 179 |
\verb+MAD_NUM_THREADS+ --- Sets the total number of threads to be used |
| 180 |
by MADNESS. When running with just one process all threads are |
| 181 |
devoted to computation (1 main thread with the remainder in the thread |
| 182 |
pool). When running with multiple MPI processes, one of the threads |
| 183 |
is devoted to communication. If you have 8 or more cores per node, it |
| 184 |
is recommended to leave at least one free for use by the O/S and MPI. |
| 185 |
|
| 186 |
\verb+MRA_DATA_DIR+ --- Full path to the directory containing the MRA |
| 187 |
data files (twoscale and autocorrelation coefficients; Gauss-Legendre |
| 188 |
quadrature weights). This is usually not needed unless you have moved |
| 189 |
the build/installation directory. |
| 190 |
|
| 191 |
\verb+MAD_BUFFER_SIZE+ --- Sets the buffer size (in bytes) used by the |
| 192 |
active messages (default is 1.5MBytes). Never needed by moldft? |
| 193 |
|
| 194 |
\verb+MAD_RECV_BUFFERS+ --- Sets the number of receive buffers used by |
| 195 |
the communication thread (default is 128 and a minimum of 32 is |
| 196 |
enforced). If you are experiencing hangs when running with MPI, |
| 197 |
making this number a bit larger (e.g., 256) can sometimes help. Too |
| 198 |
many buffers can cause performance problems. |
| 199 |
|
| 200 |
\verb+MAD_SEND_BUFFERS+ --- Sets the number of outstanding |
| 201 |
asynchronous send buffers (default 128 and a minimum of 32 is |
| 202 |
enforced). If you are experiencing hangs when running with MPI try |
| 203 |
making this smaller (to throttle the volume communication). |
| 204 |
|
| 205 |
\verb+MAD_NSSEND+ --- Every \verb+MAD_NSSEND+ messages, MADNESS |
| 206 |
requests a receipt acknowledgment from the receiver in an attempt to |
| 207 |
throttle the volume of communication. The default is the number of |
| 208 |
send buffers. Set to the value \verb+1+ to force receipt every |
| 209 |
message to be acknowledged. This makes things a bit slower but can |
| 210 |
workaround MPI hangs. |
| 211 |
|
| 212 |
\subsection{PBS script for LI-red} |
| 213 |
\label{sec:pbslired} |
| 214 |
|
| 215 |
This example makes a 2 hour job running in the short queue on 8 nodes |
| 216 |
with one process per node and job name {\tt moldft}. Each process |
| 217 |
will use 20 threads. |
| 218 |
|
| 219 |
\begin{verbatim} |
| 220 |
#!/bin/bash |
| 221 |
#PBS -l nodes=8:ppn=1,walltime=02:00:00 |
| 222 |
#PBS -q short |
| 223 |
#PBS -N moldft |
| 224 |
|
| 225 |
export EXE=/home/rjh/madness/src/apps/moldft/moldft |
| 226 |
export INPUT=benzenehf.in |
| 227 |
export OUTPUT=benzenehf.out |
| 228 |
|
| 229 |
export I_MPI_FABRICS=shm:ofa |
| 230 |
export MAD_NUM_THREADS=20 |
| 231 |
|
| 232 |
cd $PBS_O_WORKDIR |
| 233 |
|
| 234 |
mpirun -ppn 1 $EXE $INPUT >& $OUTPUT |
| 235 |
\end{verbatim} |
| 236 |
|
| 237 |
The modules I (RJH) used for testing were (put the following in your \verb+.bashrc+) |
| 238 |
\begin{verbatim} |
| 239 |
module load shared |
| 240 |
module load torque/5.1.0 |
| 241 |
module load maui/3.3.1 |
| 242 |
module load gcc/4.9.2 |
| 243 |
module load intel/compiler/64/16.0.2/2016.2.181 |
| 244 |
module load intel/mkl/64/11.3.2/2016.2.181 |
| 245 |
module load intel-mpi/64/5.1.2/5.1.2.150.XXX |
| 246 |
module load intel/tbb/64/4.4.3/2016.2.181 |
| 247 |
module load intel/vtune/2016/2016.1.1.434111 |
| 248 |
\end{verbatim} |
| 249 |
|
| 250 |
\subsection{PBS script for SeaWulf} |
| 251 |
|
| 252 |
On SeaWulf the PBS option {\tt ppn} is presently not consistent with |
| 253 |
that on LI-red --- this will change soon. In the meantime the script |
| 254 |
is a little more complicated in order to get just two MADNESS |
| 255 |
processes per node with threads able to use all cores. |
| 256 |
|
| 257 |
ASIDE: SeaWulf has 28 cores per node and a 40 Gbit/s InfiniBand |
| 258 |
network whereas LI-red has 24 cores per node and a 56 Gbit/s network. |
| 259 |
Somehow these factors (or others?) combine to make MADNESS execution |
| 260 |
on SeaWulf with 1 MPI process that uses 26 MADNESS threads/node not |
| 261 |
reliable. Hence, the job below uses two MPI processes per node each |
| 262 |
with 11 MADNESS threads. |
| 263 |
|
| 264 |
\begin{verbatim} |
| 265 |
#!/bin/bash |
| 266 |
#PBS -l nodes=12:ppn=28,walltime=10:00:00 |
| 267 |
#PBS -q default |
| 268 |
#PBS -N geomopt |
| 269 |
|
| 270 |
# Probably best to put these in your .bashrc so don't need here |
| 271 |
module load intel/compiler/64/16.0/2016.1.056.XXX |
| 272 |
module load intel/mkl/64/11.3/2016.1.056.XXX |
| 273 |
module load intel-mpi/64/5.1.2/5.1.2.150.XXX |
| 274 |
module load intel/tbb/64/4.4.3/2016.2.181 |
| 275 |
export [email protected] |
| 276 |
|
| 277 |
# Intel MPI should use shared-memory and OFED for communication |
| 278 |
export I_MPI_FABRICS=shm:ofa |
| 279 |
|
| 280 |
# We will create two processes per node --- bind to separate sockets |
| 281 |
export I_MPI_PIN_DOMAIN=socket |
| 282 |
|
| 283 |
# Should be set elsewhere but may not be |
| 284 |
export I_MPI_HYDRA_BOOTSTRAP=rsh |
| 285 |
|
| 286 |
# 14 cores per socket = Linux+MPI+unknown+madness |
| 287 |
export MAD_NUM_THREADS=11 |
| 288 |
|
| 289 |
# Change to the directory from which the job was submitted |
| 290 |
cd $PBS_O_WORKDIR |
| 291 |
|
| 292 |
# Presently SeaWulf is configured so that to get a dedicated node we |
| 293 |
# need to set ppn=28 above which gives us 28 processes per node, but we |
| 294 |
# want two. So need to make our own host file. |
| 295 |
sort < $PBS_NODEFILE | uniq > $$.hosts |
| 296 |
let NPROC=$PBS_NUM_NODES*2 |
| 297 |
|
| 298 |
# Paths to files |
| 299 |
MOLDFT=/gpfs/home/rharrison/madness/src/apps/moldft/moldft |
| 300 |
INPUTFILE=input |
| 301 |
OUTPUTFILE=output |
| 302 |
|
| 303 |
# Redirect output to a file so that can see it while job is running |
| 304 |
|
| 305 |
mpirun -f $$.hosts -ppn 2 -n $NPROC $MOLDFT $INPUTFILE >& $OUTPUTFILE |
| 306 |
|
| 307 |
\end{verbatim} |
| 308 |
|
| 309 |
|
| 310 |
\section{Input structure} |
| 311 |
|
| 312 |
Presently the input {\em must} contain both a \verb+dft+ and a |
| 313 |
\verb+geometry+ input block. The file is scanned for the first such |
| 314 |
block (so you can have multiple blocks in a file --- just the first is |
| 315 |
used). Within these blocks, lines beginning with \verb+#+ are read as comments. |
| 316 |
Outside these blocks, data is ignored. |
| 317 |
|
| 318 |
\section{Reproducibility} |
| 319 |
|
| 320 |
For small molecules, the calculations should usually be fully |
| 321 |
reprodicible from run to run or with different numbers of threads or |
| 322 |
processes. However, for larger molecules, the different rounding |
| 323 |
error arising from different order of parallel execution can cause |
| 324 |
different execution paths. So results may vary in the last digit or |
| 325 |
so, and sometimes more especially if additional/fewer iterations are |
| 326 |
made. However, results at convergence should {\em always} agree to |
| 327 |
the that expected from the truncation and convergence thresholds, and |
| 328 |
the number of iterations between runs should only differ by about one. |
| 329 |
If you are seeing worse behavior than this, then please send the input |
| 330 |
and output to the MADNESS issue tracker. |
| 331 |
|
| 332 |
\chapter{Geometry specification} |
| 333 |
|
| 334 |
\begin{verbatim} |
| 335 |
geometry |
| 336 |
units atomic or angstrom (default atomic) |
| 337 |
eprec precision (default 1e-4) |
| 338 |
tag x y z |
| 339 |
pstag x y z charge |
| 340 |
end |
| 341 |
\end{verbatim} |
| 342 |
|
| 343 |
The units and energy precision ({\tt eprec}) must presently be specified {\em before} coordinates of atoms are specified. |
| 344 |
|
| 345 |
{\tt units} --- E.g., {\tt units angstrom} --- The user input units which can be {\tt atomic} or {\tt angstrom} (default is {\tt atomic}). Beware --- presently, the output file always contains atomic units. |
| 346 |
|
| 347 |
{\tt eprec} --- E.g., {\tt eprec 1e-5} --- The energy error per atom |
| 348 |
in atomic units due to smoothing the nuclear potential (default is |
| 349 |
{\tt 1e-4}). The default is adequate for most chemical purposes |
| 350 |
(giving energy differences to at least {\tt 1e-5} atomic units per atom |
| 351 |
and geometries accurate to about {\tt 1e-3} atomic units) unless you |
| 352 |
are doing very high accuracy benchmark studies. Gradients may get |
| 353 |
noisy if you make {\tt eprec} too small, though we don't have much |
| 354 |
experience with this yet. |
| 355 |
|
| 356 |
{\tt tag x y z} --- E.g., {\tt Be 0.3 -0.1 3.1} --- Specifies an atom using its atomic symbol (case insensitive) and Cartesian coordinates. |
| 357 |
|
| 358 |
{\tt bqtag x y z charge} --- E.g., {\tt Bq9 20.0 20.0 20.0 -10.0} --- The tag must begin with {\tt Bq} (case insensitive). It is used to place a charge at an arbitrary location (e.g., to simulate an external field). |
| 359 |
|
| 360 |
{\tt pstag x y z charge} --- E.g., {\tt psBe 0.3 -0.1 3.1} --- The tag must begin with {\tt ps} (case insensitive). It is used to put a pseudopotential on selected atoms ({\em I think ???????}). |
| 361 |
|
| 362 |
|
| 363 |
\chapter{Ground state molecular DFT and HF} |
| 364 |
|
| 365 |
\begin{verbatim} |
| 366 |
dft |
| 367 |
directives/keywords |
| 368 |
end |
| 369 |
\end{verbatim} |
| 370 |
|
| 371 |
{\tt nopen value} --- E.g., {\tt nopen 3} --- The number of unpaired spin orbitals, $n_\alpha - n_\beta$ (default {\tt 0}) |
| 372 |
|
| 373 |
{\tt unrestricted} --- Selects a spin-unrestricted calculation (default is spin restricted) |
| 374 |
|
| 375 |
{\tt xc value} --- E.g., {\tt xc HF} --- Selects the exchange correlation potential (default is {\tt LDA}). See XC section for more details. |
| 376 |
|
| 377 |
{\tt aobasis value} --- E.g., {\tt aobasis sto-3g} --- Sets the atomic orbital basis used for the initial guess. Options are {\tt sto-3g} (down to Iodine) or {\tt 6-31g} (down to Zinc, default). |
| 378 |
|
| 379 |
{\tt charge value} --- E.g., {\tt charge -1.0} --- Total charge (default {\tt 0}) on the molecule. Atomic units. |
| 380 |
|
| 381 |
{\tt nvalpha value} --- E.g., {\tt nvalpha 2} --- The number of alpha spin virtual orbitals to solve for (default {\tt 0}) --- is this working now? |
| 382 |
|
| 383 |
{\tt nvbeta value} --- E.g., {\tt nvbeta 2} --- The number of beta spin virtual orbitals to solve for (default {\tt 0}) --- is this working now? |
| 384 |
|
| 385 |
{\tt no\_orient} --- Do not reorient/translate the molecule to orientation/center. |
| 386 |
|
| 387 |
{\tt core\_type value} --- E.g., {\tt What is available?} Selects the pseudopotential to be used on all atoms (can also do mixed all-electron/pseudopotential calculation). Not heavily tested and unoptimized. (default is all electron). |
| 388 |
|
| 389 |
{\tt psp\_calc} --- Perform pseusopotential calculation on all atoms. Not heavily tested and unoptimized. (default is all-electron) |
| 390 |
|
| 391 |
{\tt L value} --- E.g., {\tt L 50} --- Sets the computational box size to $[-L,L]^3$ atomic units (mostly for testing). Default is to find cube that contains all nuclei and to add 50 atomic units. |
| 392 |
|
| 393 |
\section{XC --- DFT exchange correlation} |
| 394 |
|
| 395 |
Without LIBXC, the code just provides either Hartree-Fock ({\tt xc HF}) or local (spin) density approximation ({\tt xc LDA}, the default). |
| 396 |
|
| 397 |
With LIBXC, in addition to HF and LDA (default) there are wide varity of GGA and hybrid functionals available --- the ones that have been tested (to some extent) have been provided with simple input formats |
| 398 |
\begin{itemize} |
| 399 |
\item Becke-Perdew (91?) --- \verb+xc bp+ |
| 400 |
\item Becke-Perdew 86 --- \verb+xc bp86+ |
| 401 |
\item PBE --- \verb+xc pbe+ |
| 402 |
\item PBE-0 --- \verb+xc pbe0+ |
| 403 |
\item B3LYP --- \verb+xc b3lyp+ |
| 404 |
\end{itemize} |
| 405 |
|
| 406 |
There is also a more general input format in which you can provide a list of functional names (using LIBXC's naming scheme) and the coefficient by which to scale it. For instance, to get PBE-0 you could specify |
| 407 |
\verb+xc GGA_X_PBE .75 GGA_C_PBE 1. HF_X .25+. |
| 408 |
|
| 409 |
We have not yet implemented the near linear-scaling algorithm for HF |
| 410 |
exchange, which as a consequence is fairly slow and may require a lot |
| 411 |
of memory (there is low-memory algorithm in the code but I don't think |
| 412 |
it is yet available as an input option). |
| 413 |
|
| 414 |
\section{Restarting} |
| 415 |
|
| 416 |
At completion of an HF or DFT calculation, the molecular orbitals are |
| 417 |
saved in the files \verb+restartdata.*+ (with one file per I/O server |
| 418 |
process). The projection of the orbtials onto the {\tt sto-3G} AO basis |
| 419 |
set is saved into the file {\tt restartaodata}. |
| 420 |
|
| 421 |
{\tt restart} --- Restart from numerical orbitals from a previous calculation (default is no) |
| 422 |
|
| 423 |
{\tt restartao} --- Restart from projection of orbitals onto AO basis |
| 424 |
set from a previous calculation (default is no unless doing geometry |
| 425 |
optimization). If a restart file is not found, or the file contains |
| 426 |
incompatible data then the default atomic guess is used. |
| 427 |
|
| 428 |
{\tt save value} --- E.g., {\tt save false} --- Boolean flag to save (or not) orbitals at completion (default is true). |
| 429 |
|
| 430 |
\section{Controlling convergence and accuracy} |
| 431 |
|
| 432 |
The default convergence test is on both the 2-norm of change in density per atom (separately for each spin) between iterations and the residual error in each wave function. |
| 433 |
|
| 434 |
\begin{verbatim} |
| 435 |
converged = (da < dconv * molecule.natom()) && |
| 436 |
(db < dconv * molecule.natom()) && |
| 437 |
(conv_only_dens || (max_residual < 5.0 * dconv)) |
| 438 |
\end{verbatim} |
| 439 |
|
| 440 |
{\tt dconv value} --- E.g., {\tt dconv 1e-5} --- SCF convergence criterion (default 1e-4 atomic units). Suggest decreasing this to {\tt 1e-5} for geometry optimization or property calculations. |
| 441 |
|
| 442 |
{\tt canon} --- Solves for canonical orbitals or eigenfunctions (default is localized orbitals except for atoms and diatomics). |
| 443 |
|
| 444 |
{\tt pm} --- Selects use of the Pipek-Mezy localized orbitals (default). |
| 445 |
|
| 446 |
{\tt boys} --- Selects use of the Boys localized orbitals. |
| 447 |
|
| 448 |
{\tt maxrotn value} --- E.g., {\tt maxrotn 0.1} --- Used to restrict maximum rotation of orbitals (default {\tt 0.25}) |
| 449 |
|
| 450 |
{\tt maxiter value} --- E.g., {\tt maxiter 20} --- The maximum number of iterations (default is {\tt 20}) |
| 451 |
|
| 452 |
{\tt maxsub value} --- E.g., {\tt maxsub 5} --- The size of the iterative subspace (default is {\tt 5}). Sometimes it helps to make this larger. |
| 453 |
|
| 454 |
{\tt protocol valuelist} --- E.g., {\tt protocol 1e-4 1e-6 1e-8} --- Sets the solution protocol. The default is `{\tt 1e-4 1e-6} which means solve first using a truncation threshold of {\tt 1e-4} (using $k=6$) and with a threshold of {\tt 1e-6} (using $k=8$). |
| 455 |
|
| 456 |
{\tt orbitalshift} --- E.g., {\tt orbitalshift 0.1} --- Shifts the occupied orbitals down in energy by the given amount (default {\tt 0}). Is this working? |
| 457 |
|
| 458 |
{\tt k value} --- E.g., {\tt k 8} --- Sets the wavelet order to a fixed value (mostly only used for testing) |
| 459 |
|
| 460 |
{\tt convonlydens} --- Just test on the change in the density for convergence. |
| 461 |
|
| 462 |
|
| 463 |
\section{Geometry optimization} |
| 464 |
|
| 465 |
By default geometry optimization is performed using the BFGS Hessian update algorithm. The convergence test is on all of the 2-norm of the gradient, the change in the energy between iterations, and the maximum change in Cartesian coordinates (all in atomic units). The |
| 466 |
|
| 467 |
For geometry optimization it is recommended to select {\tt dconv 1e-5} to obtain more accurate gradients. |
| 468 |
|
| 469 |
{\tt gopt} --- Requests optimization of the geometry |
| 470 |
|
| 471 |
{\tt gtol value} --- E.g., {\tt gtol 1e-4} --- Sets the convergence threshold for the 2-norm of the gradient (default {\tt 1e-3}). |
| 472 |
|
| 473 |
{\tt gtest value} --- E.g., {\tt gtest 1e-4} --- Sets the convergence threshold for the maximum change in Cartesian coordinates (default {\tt 1e-3} atomic units). |
| 474 |
|
| 475 |
{\tt gval value} --- E.g., {\tt gval 1e-6} --- Sets the available precision in the energy (default is {\tt 1e-5} atomic units). |
| 476 |
|
| 477 |
{\tt gprec value} --- E.g., {\tt gtest 1e-6} --- Sets the available precision in the gradient (default is {\tt 1e-5} atomic units). |
| 478 |
|
| 479 |
{\tt gmaxiter value} --- E.g., {\tt gmaxiter 100} --- Sets the maximum number of geometry optimization iterations (default is 20). |
| 480 |
|
| 481 |
{\tt algopt value} --- E.g., {\tt algopt SR1} --- Selects the quasi-Newton update method (default is ). Options are {\tt BFGS} (default) or {\tt SR1} (not heavily tested). Case sensitive. |
| 482 |
|
| 483 |
\section{Properties} |
| 484 |
|
| 485 |
{\tt derivatives} --- Compute the derivates (default is false). |
| 486 |
|
| 487 |
{\tt dipole} --- Compute the molecular dipole moment (default is false --- why?). |
| 488 |
|
| 489 |
{\tt response} --- TBD |
| 490 |
|
| 491 |
{\tt response\_freq} --- TBD |
| 492 |
|
| 493 |
{\tt response\_axis} --- TBD |
| 494 |
|
| 495 |
{\tt rconv} --- TBD |
| 496 |
|
| 497 |
{\tt efield} --- TBD |
| 498 |
|
| 499 |
{\tt efield\_axis x y z} --- TBD |
| 500 |
|
| 501 |
{\tt print\_dipole\_matels} --- TBD |
| 502 |
|
| 503 |
\section{Plotting} |
| 504 |
|
| 505 |
Plots are generated to OpenDX files. In the {\tt moldft} source directory are two useful files |
| 506 |
|
| 507 |
\begin{itemize} |
| 508 |
\item {\tt vizit.net} --- An OpenDX visual program that displays a |
| 509 |
molecule (from file {\tt molecule.dx}) along with positive+negative |
| 510 |
isosurfaces (with adjustable value)for a scalar field read from a |
| 511 |
file. |
| 512 |
|
| 513 |
\item {\tt moldx.py} --- A Python program you can run with your {\em |
| 514 |
output} file as standard input to produce a {\tt molecule.dx} file. |
| 515 |
It is important to use your output file since {\tt moldft} will (by |
| 516 |
default) translate and rotate the molecular coordinates. |
| 517 |
|
| 518 |
\end{itemize} |
| 519 |
|
| 520 |
{\tt plotmos lo hi} --- E.g., {\tt plotmos 10 12} --- Plots the molecular orbitals in the given inclusive range (default is none). Orbitals are numbered from zero. Seems like this needs extending to accomodate unrestricted calculations. |
| 521 |
|
| 522 |
{\tt plotdens} --- Plots the total electronic charge density and, if spin unrestricted, the spin density (default is off). |
| 523 |
|
| 524 |
{\tt plotcoul} --- Plots the total (electronic + nuclear) electrostatic potential (default is off). |
| 525 |
|
| 526 |
{\tt plotnpt value } --- E.g., {\tt plotnpt 501} --- Sets the number of plots used per dimension in the cube of points (default 101). |
| 527 |
|
| 528 |
{\tt plotcell xlo xhi ylo yhi zlo zhi} --- E.g., {\tt plotcell -10 10 -15 15 -10 5} --- Sets the cell (in atomic units) used for plotting (default is the entire simulation cell). |
| 529 |
|
| 530 |
\section{Parallel execution} |
| 531 |
|
| 532 |
{\tt loadbal vnucfac parts} --- E.g., {\tt loadbal 12 2} --- Adjusts data/loadbalance when running in parallel with MPI. {\tt vnucfac} (default 12) is extra weight associated with nuclear potential and {\tt parts} (default 2) is the number of partitions (or subtrees) per node. SCF |
| 533 |
|
| 534 |
{\tt nio value} --- E.g., {\tt nio 10} --- The number of MPI processes to use as I/O servers (default is 1) |
| 535 |
|
| 536 |
|
| 537 |
\end{document} |