From be2e43170a23675c36ce4c857262c6b645a2a18c Mon Sep 17 00:00:00 2001 From: Robert Harrison Date: Tue, 28 Jan 1997 02:08:31 +0000 Subject: [PATCH] First round of corrections to Judi's modifications --- doc/user/basis.tex | 301 ++++----- doc/user/ecp.tex | 216 ++----- doc/user/execution.tex | 2 +- doc/user/functionality.tex | 29 + doc/user/geometry.tex | 799 +++++++++++------------- doc/user/intro.tex | 1215 +++++++++++++++++------------------- doc/user/knownbas.tex | 2 +- doc/user/mcscf.tex | 8 +- doc/user/scf.tex | 17 +- doc/user/top-level.tex | 831 ++++++++++-------------- doc/user/user.tex | 5 + doc/user/zmat1.eps | 527 ++++++++++++++++ doc/user/zmat1.fig | 43 ++ doc/user/zmat2.eps | 533 ++++++++++++++++ doc/user/zmat2.fig | 47 ++ doc/user/zmat3.eps | 533 ++++++++++++++++ doc/user/zmat3.fig | 47 ++ 17 files changed, 3229 insertions(+), 1926 deletions(-) create mode 100644 doc/user/functionality.tex create mode 100644 doc/user/zmat1.eps create mode 100644 doc/user/zmat1.fig create mode 100644 doc/user/zmat2.eps create mode 100644 doc/user/zmat2.fig create mode 100644 doc/user/zmat3.eps create mode 100644 doc/user/zmat3.fig diff --git a/doc/user/basis.tex b/doc/user/basis.tex index b5e056d560..5e216aa607 100644 --- a/doc/user/basis.tex +++ b/doc/user/basis.tex @@ -1,21 +1,25 @@ -\label{sec:basis} -In NWChem, basis sets consist of sets of generally contracted Cartesian -Gaussian functions. (An optional functionality also exists that allows the -user to specify an effective core potential (ECP) basis set; see -section \ref{sec:ecp}.) The basis functions to be used for a given -calculation can be drawn from a standard set in the EMSL basis set library -that is included in the release of NWChem. (See Appendix \ref{knownbasis} -for a list of the standard basis sets currently supplied with the release -of the code.) Alternatively, the user can specify particular functions -explicitly in the input defining a particular basis set. +\label{sec:basis} + +NWChem currently supports basis sets consisting of generally +contracted Cartesian Gaussian functions. The {\tt BASIS} directive is +used to define these, and also to specify use of an effective core +potential (ECP) that is associated with a basis set; see section +\ref{sec:ecp}.) + +The basis functions to be used for a given calculation can be drawn +from a standard set in the EMSL basis set library that is included in +the release of NWChem. (See Appendix \ref{sec:knownbasis} for a list +of the standard basis sets currently supplied with the release of the +code.) Alternatively, the user can specify particular functions +explicitly in the input defining a particular basis set. The form of the \verb+BASIS+ directive is as follows; \begin{verbatim} BASIS [] \ - [spherical || cartesian default cartesian] \ - [segment || nosegment default segment] \ - [print || noprint default print] + [(spherical || cartesian) default cartesian] \ + [(segment || nosegment) default segment] \ + [(print || noprint) default print] library [] \ [file ] @@ -29,94 +33,84 @@ The form of the \verb+BASIS+ directive is as follows; END \end{verbatim} -The string \verb+name+ allows the user to identify a specific basis set -in the database for a calculation. The various modules in the code expect -to find the -basis set in the database under the name \verb+"ao basis"+. The user can -assign the string \verb+name+ to \verb+"ao basis"+ using the \verb+SET+ -directive (see Section \ref{sec:set}), in the same manner as that in -which different -\verb+geometry+ objects are assigned the default name \verb+geometry+ -for specific tasks. This indirection allows the user to assign different -basis sets to the same geometry object, or the same basis set to different -geometry objects, for different calculations in -the course of the same job. +Examining first the keywords on the \verb+BASIS+ directive line: + + +\begin{itemize} +\item {\tt NAME} + +By default the basis set is stored in the database with the name +\verb+"ao basis". By specifying another name in the \verb=BASIS= +directive, multiple basis sets may be stored at once in the database. +Also, the DFT (Section \ref{sec:dft}), RISCF (Section \ref{sec:riscf}) +and RIMP2 (Section \ref{sec:rimp2}) modules require multiple basis +sets with specific names. + +The user can associate the \verb+"ao basis" with another named basis +using the \verb+SET+ directive (see Section \ref{sec:set}). + +\item {\tt SPHERICAL} and {\tt CARTESIAN}} The keywords \verb+spherical+ and \verb+cartesian+ offer the option of -specifying the basis functions in either spherical or cartesian coordinates. -The keywords \verb+segment+ and \verb+nosegment+ allow the user to specify -whether or not the functions will be segmented. Currently, NWChem assumes -that all basis sets are segmented and cartesian, whether specified by the -user or taken from the standard library sets. -The options for spherical coordinates and unsegmented functions will become -usable in all calculations only when the derivative integral code is -extended to handle -general contractions and sphericals. Currently, only the energy codes are -able to handle these, which means that spherical basis functions can be used -only for (************???what sort of calculations???**********). +using either spherical-harmonic (5 d, 7 f, 9 g, \ldots) or Cartesian +(6 d, 10 f, 15 g, \ldota) angular functions. The default is +Cartesian because the current integral derivative program cannot +handle spherical functions. If only energy calculations are being +performed, then {\tt SPHERICAL} can be specified. + +Note that the correlation-consistent basis sets were designed using +spherical harmonics and to use these the \verb+SPHERICAL+ keyword +should be present on the \verb+BASIS+ directive (in energy +calculations). Use of spherical functions also helps eliminate +problems with linear dependence. + + +\item {{\tt SEGMENT} or {\tt NOSEGMENT}} + +By default NWChem forces all basis sets to be segmented, +even if they are input with either general contractions, or $L$ or sp +shells. This is because the current derivative integral package cannot +handle general contractions. If just computing energies a substantial +performance gain can result from exploiting generally contracted basis +sets, in which case {\tt NOSEGMENT} should be specified. + +\item {{\tt PRINT} and {\tt NOPRINT}} -The keywords \verb+print+ and \verb+noprint+ allow the user to override -instructions from the top level \verb+PRINT+ directive for the basis sets. The default is for the input module to print all basis sets encountered. Specifying the keyword \verb+noprint+ allows the user to supress this output. -% This directive describes a basis set of generally contracted Cartesian -% Gaussian functions. By default basis sets are automatically segmented -% and cartesian\footnote{This will change when the derivative integral -% code is extended to handle general contractions and sphericals. Only -% the energy codes can presently handle these.} even if general -% contractions are input. Basis functions are associated with centers -% in geometries through the tags or names of centers which must match -% exactly (including case) and are limited to sixteen (16) characters. -% Each center with the same tag will have the same basis set. By -% default the input module prints each basis set encountered; use the -% \verb+NOPRINT+ option to disable printing. -% -% In the same fashion as for geometries, basis sets are named, with the -% default name being \verb+"ao basis"+. It should be clear from the -% above discussion on geometries and database entries how indirection is -% supported. -% -% Basis functions may be either drawn from a standard set in the EMSL -% basis set library or specified explicitly. See Appendix -% \ref{knownbas} for the current list of standard basis sets. An -% installation default is provided for the path to the basis set -% library, which may be overridden in the input. The case of names of -% standard basis sets is ignored. By default the standard basis -% appropriate to the atom on which it is centered is used, however this -% may be overriden, for instance to place ghost functions on dummy -% centers in counterpoise calculations. When explicitly specifying -% generally contracted basis sets, simply specify on each line the -% exponent followed by the contraction coefficients for each contraction -% of that exponent. The following examples will make the use of this -% directive clear. +\end{itemize} -The input specified in lines beginning with the string \verb+tag+ -allows a particular center or atom in a calculation to be associated with -a particular set of basis functions. The values specified for \verb+tag+ -must correspond exactly with the names supplied for the \verb+tag+ entries -on the \verb+GEOMETRY+ directive for a particular calculation. Each atom -or center with the same \verb+tag+ will have the same basis set, which must -also be specified with the same name \verb+tag+. +Basis sets are associated with centers by using the tag of a center in +a geometry that has either been input by the user (Section +\ref{sec:geom}) or created automatically. Each atom or center with +the same \verb+tag+ will have the same basis set. All atoms must have +basis functions assigned to them --- only dummy centers may have no +basis functions. -The keyword \verb+library+ specifies that the calculation will use the +We examine next how to reference standard basis sets in the basis set +library, and, finally, how to define a basis using exponents and +coefficients. + +\subsection{Basis set library} + +The keyword \verb+library+ specifies that the calculation will use the standard basis sets in NWChem. The string \verb+standard_set+ is the -name that identifies the functions in the library. (See Appendix +name that identifies the functions in the library. The names of +standard basis sets are not case sensitive. See Appendix \ref{sec:knownbasis} for a complete list of the basis functions in the -NWChem library.) If the string \verb+tag+ corresponds to -a dummy center, the string \verb+tag_in_lib+ must also be entered on -this line, to identify -the correct name for the atom in the basis function library. +NWChem library and their specification. If basis functions are to be +placed upon a dummy center, the string \verb+tag_in_lib+ must also be +entered on this line, to identify the correct atom type to use in the +basis function library (see the ghost atom example in Section +(\ref{sec:set} and below). -A default path to the basis set library -is provided on installation of the code, and the user can specify a -particular standard set by supplying the name in the library -in the string \verb+tag_in_lib+. However, a different path can be defined -for the particular basis set by specifying the keyword \verb+file+ after -the keyword \verb+library+, and then explicitly naming the file to be -accessed for the basis functions. +A default path to the basis set library is provided on installation of +the code, but a different path can be defined by specifying the +keyword \verb+file+ and then explicitly naming the file to be accessed +for the basis functions. -For example, NWChem contains the Thom Dunning cc-pvdz basis sets for +For example, NWChem contains the Dunning cc-pvdz basis sets for oxygen and hydrogen in the standard basis set library. The \verb+BASIS+ directive to use these basis sets in a calculation of the water molecule could be formulated quite simply as follows; @@ -128,13 +122,6 @@ could be formulated quite simply as follows; end \end{verbatim} -\Large -***** -QUESTION: In Appendix A, this basis set is listed as ``cc-pVDZ''. Is -this input case-sensitive, or not? -****** -\normalsize - In this example, the cc-pvdz basis functions will be obtained from the NWChem library, as defined by the default path on installation. To obtain functions from some other library, such as the user's own experimental @@ -148,20 +135,14 @@ explicitly. An example illustrating this option is as follows, end \end{verbatim} -This directive tells the code to use the basis sets \verb+3-21g+ in the -file /usr/d3g681/nwchem/library for atoms or centers with \verb+tag+ -strings \verb+o+ and \verb+si+ , rather than looking for them in the -default library. +This directive tells the code to use the basis sets \verb+3-21g+ in +the file /usr/d3g681/nwchem/library for atoms \verb+o+ and \verb+si+ , +rather than looking for them in the default library. -The basis functions must be defined for dummy centers as well for -as atoms. Since the dummy centers are given \verb+tag+ names that begin -with \verb+bq+ to distinguish them from atoms (see the description of the -\verb+GEOMETRY+ directive in Section \ref{sec:geom}), the \verb+BASIS+ -directive must identify their corresponding functions explicitly. For -example, to specify the cc-pvdz basis for a calculation on the water -monomer in the dimer basis, where the dummy oxygen and dummy hydrogen -centers have been identified as \verb+bqo+ and \verb+bqh+ respectively, -the \verb+BASIS+ directive is as follows, +Another example. To specify the cc-pvdz basis for a calculation on +the water monomer in the dimer basis, where the dummy oxygen and dummy +hydrogen centers have been identified as \verb+bqo+ and \verb+bqh+ +respectively, the \verb+BASIS+ directive is as follows, \begin{verbatim} basis @@ -172,36 +153,27 @@ the \verb+BASIS+ directive is as follows, end \end{verbatim} +\subsection{Explicit basis set definition} -The user also has the option of explicitly specifying the generally -contracted basis functions for particular elements. This can be useful -as a means of specifying alternative basis functions for 'ghost' atoms -or dummy centers in counterpoise calculations, for instance. - -For those particular elements named in some string \verb+tag+ (and identified -appropriately on a \verb+GEOMETRY+ directive), the string \verb+tag+ input -line on the \verb+BASIS+ directive is of the form, - +A generally contracted Gaussian basis function is associated with a +center as follows \begin{verbatim} + ... \end{verbatim} -The string \verb+shell_type+ is used to specify the outer electron shell of -the atom, which may be \verb+s+ for the s-shell, \verb+p+ for the p-shell, -(***or whatever***). The user must then specify the real exponent for -each electron(?), followed by the contraction coefficients for each -contraction of that exponent. The input for the \verb+list_of_coefficients+ -is free-format, and assumed to be type 'real'. - -For example, the \verb+BASIS+ directive to use Thom Dunning's cc-pvdz basis -functions for the water molecule, as illustrated above, -can be modified to add a specific basis function that defines a diffuse -s-shell (specified by string {\em s} for \verb+shell_type+) for oxygen. -The modified directive is of the form, +The \verb+shell_type+ identifies the angular momentum of the shell, +$s$, $p$, $d$, \ldots. By default, NWChem is configured to handle up +to $i$ functions. Subsequent lines define the primitive function +exponents and contraction coefficients. General contractions are +specified by including multiple coefficients. +For example, the following \verb+BASIS+ directive augments the Dunning +cc-pvdz basis set for the water molecule with a diffuse s-shell on +oxygen \begin{verbatim} - basis + basis spherical nosegment oxygen library cc-pvdz hydrogen library cc-pvdz oxygen s @@ -209,42 +181,9 @@ The modified directive is of the form, end \end{verbatim} -In all of these examples, the basis set is given the default name -\verb+"ao basis"+. The functions are assumed segmented and cartesian, -and the input module will print a description of the basis set. The functions -of this basis set consist of the library functions for hydrogen, plus -the library functions for oxygen as modifed based on the specified contraction -coefficients. - -The basis functions for a molecule can be explicitly specified for all -atoms, with none of the functions drawn from the standard library. In such -a case, the \verb+shell_type+, \verb+exponent+, and \verb+list_of_coefficients+ -must be supplied for each atom or center in the molecule. (Note that -the name of -each atom or center must also correspond to an appropriate entry for -a \verb+tag+ string -identifying each atom or center of the molecule on the corresponding -\verb+GEOMETRY+ directive.) - -% The following directive specifies exactly the same basis set as the -% previous directive except that all basis functions are explicitly -% described (all input is free format --- the formatting here is just -% for readability). - -The following example illustrates this option for the water molecule. The -user must enter explicitly all the information that could be obtained -simply by specifying the NWChem library functions using the lines - +This is equivalent to the following explicit specification \begin{verbatim} - oxygen library cc-pvdz - hydrogen library cc-pvdz -\end{verbatim} - -The input for the \verb+BASIS+ directive in this example when the option -for specifying explicit functions is selected becomes, - -\begin{verbatim} - basis + basis spherical nosegment oxygen s 11720.0000 0.000710 -0.000160 1759.0000 0.005470 -0.001263 @@ -280,36 +219,6 @@ for specifying explicit functions is selected becomes, end \end{verbatim} -% Note that the correlation-consistent basis sets were designed using -% spherical harmonics and to use these the \verb+SPHERICAL+ keyword must -% be present on the \verb+BASIS+ directive. -% *******NOTE: the above paragraph is not consistent with what has -% already been said about the keywords spherical and -% cartesian. And it's not consistent with the directive. -% What is right here? -% ******************************************************************* -% -% This example uses a 3-21g basis set for centers \verb+o+ and \verb+si+ -% and explicitly specifies the path to the basis set library (perhaps -% because you cannot find the copy installed with NWChem). -% \begin{verbatim} -% basis -% o library 3-21g file /usr/d3g681/nwchem/library -% si library 3-21g file /usr/d3g681/nwchem/library -% end -% \end{verbatim} -% -% In order to perform counterpoise corrections in standard basis sets it -% is necessary to specify the atom type. The following input specifies a -% cc-pvdz basis for a calculation on the water monomer in the dimer basis. -% \begin{verbatim} -% basis -% o library cc-pvdz -% h library cc-pvdz -% bqo library o cc-pvdz -% bqh library h cc-pvdz -% end -% \end{verbatim} diff --git a/doc/user/ecp.tex b/doc/user/ecp.tex index a61f9d46e4..572ab422e6 100644 --- a/doc/user/ecp.tex +++ b/doc/user/ecp.tex @@ -1,124 +1,58 @@ \label{sec:ecp} -In addition to the standard basis sets that can be specified using the -\verb+BASIS+ directive, the basis functions can be described in NWChem -using a effective core potential (ECP) basis set. An ECP basis set -consists of contracted gaussian functions that are fit to gaussians by the -function, +This directive describes an effective core potential (ECP) basis set +of contracted gaussian functions. The ECPs are fit to Gaussians +with the form \[ -r^2V_l(r) = \sum_{k} A_{lk} r^{n_{lk}} e^{B_{lk}r^{2}} + r^2V_l(r) = \sum_{k} A_{lk} r^{n_{lk}} e^{B_{lk}r^{2}} \] where $A_{lk}$ is the contraction coefficient, $n_{lk}$ is the exponent of the ``r'' term (r-exponent), and $B_{lk}$ is the gaussian -exponent. (Note: to be consistent with most of the literature on ECP -functions, the r-exponent is shifted by 2; e.g., an r-exponent of 0 -implies $r^{-2}$). +exponent. The r-exponent is shifted by 2 as per most of the ECP +literature, e.g., an r-exponent of 0 implies $r^{-2}$. -The EMSL library does not currently support a standard set of ECP basis -functions. Basis sets using these functions must be specified explicitly -by user input in the \verb+ECP+ directive. This directive has -essentially the same form as the standard \verb+BASIS+ directive, -except for differences in the type of information to be supplied for -each atom or center using the ECP basis set. The form of the input for -the \verb+ECP+ directive is as follows; +By default ECP basis sets are automatically segmented and cartesian +even if general contractions are input. -\begin{verbatim} - ecp [] \ - [spherical || cartesian default cartesian] \ - [segment || nosegment default segment] \ - [print || noprint default print] -\end{verbatim} +ECP basis functions are associated with centers in geometries through +the tags or names of centers which must match exactly (including case) +and are limited to sixteen (16) characters. Each center with the same +tag will have the same ECP basis set. By default the input module +prints each ECP basis set encountered; use the \verb+NOPRINT+ option +to disable printing. There can be only one active ECP basis set even +though several may exist in the input deck. The ECP modules load +``ecp basis'' with any ``ao basis'' present. The ECP functionality +works for energy and gradients. -% library [] \ -% [file ] -% -% or -% -\begin{verbatim} - [nelec] - - ... +In the same fashion as for geometries or regular basis sets, ECP basis +sets are named, with the default name being \verb+"ecp basis"+. It +should be clear from the above discussion on geometries and database +entries how indirection is supported. - - - ... - - END -\end{verbatim} - - -% This directive describes an effective core potential (ECP) basis set -% of contracted gaussian functions. These are fit to gaussians by the -% function: -% \[ -% r^2V_l(r) = \sum_{k} A_{lk} r^{n_{lk}} e^{B_{lk}r^{2}} -% \] -% Where $A_{lk}$ is the contraction coefficient, $n_{lk}$ is the -% exponent of the ``r'' term (r-exponent), and $B_{lk}$ is the gaussian -% exponent. The r-exponent is shifted by 2 as per most of the ECP -% literature, e.g., an r-exponent of 0 implies $r^{-2}$. -% -% By default basis sets are automatically segmented and cartesian even -% if general contractions are input. Generally contracted ECP basis -% sets are not in wide use but the functionality is available. ECP -% basis functions are associated with centers in geometries through the -% tags or names of centers which must match exactly (including case) and -% are limited to sixteen (16) characters. Each center with the same tag -% will have the same ecp basis set. By default the input module prints -% each ecp basis set encountered; use the \verb+NOPRINT+ option to -% disable printing. There can be only one active ECP basis set even -% though several may exist in the input deck. The ECP modules load -% ``ecp basis'' with any ``ao basis'' present. The ECP functionality -% works for energy and gradients. -% -% In the same fashion as for geometries or regular basis sets, ecp basis -% sets are named, with the default name being \verb+"ecp basis"+. It -% should be clear from the above discussion on geometries and database -% entries how indirection is supported. -% -% Basis functions currently may not be drawn from a standard set in the -% EMSL basis set library; they must be specified explicitly. All -% directives that are in common with the standard gaussian basis set -% input have the same function and syntax. - -The string \verb+name+ allows the user to identify a specific ECP basis set -in the database for a calculation. If no name is specified explicitly, the -default name is \verb+"ecp basis"+ The various modules in the code expect -to find the -basis set in the database under the name \verb+"ao basis"+. The user can -assign the string \verb+name+ (or \verb+"ecp basis"+, if the default name -is used) to \verb+"ao basis"+ using the \verb+SET+ -directive (see Section \ref{sec:set}), in the same manner as that in -which standard basis sets of some (non-default) \verb+name+ -are assigned the default name \verb+"ao basis"+ -for specific tasks. This indirection allows the user to assign different -basis sets to the same geometry object, or assign the same basis set to -different geometry objects, for different calculations in -the course of the same job. Only one ECP basis set can be active for a -given task, although any number of such basis sets can be defined in the -input under names other than \verb+"ecp basis"+. +Basis functions currently may not be drawn from a standard set in the +EMSL basis set library; they must be specified explicitly. All +directives that are in common with the standard gaussian basis set +input have the same function and syntax. The keyword pairs \begin{verbatim} -spherical || cartesian -segment || nosegment -print || noprint + spherical || cartesian + segment || nosegment + print || noprint \end{verbatim} -are interpreted -in the \verb+ECP+ directive in the same manner as for the \verb+BASIS+ -directive, but only the defaults are currently available for -the coordinate system and segmentation in the \verb+ECP+ directive. -NWChem assumes -that all ecp basis sets are segmented and cartesian. -The keywords are included in the directive, however, because it is -expected that eventually the code will include the options for the -user to specify basis functions in either spherical or +are interpreted in the \verb+ECP+ directive in the same manner as for +the \verb+BASIS+ directive, but only the defaults are currently +available for the coordinate system and segmentation in the \verb+ECP+ +directive. NWChem assumes that all ECP basis sets are segmented and +cartesian. The keywords are included in the directive, however, +because it is expected that eventually the code will include the +options for the user to specify basis functions in either spherical or cartesian coordinates, segmented or unsegmented. The print keyword is currently active, and can be used to specify that the descriptions of -the functions will be printed or not printed by the input module, at the user's -discretion. +the functions will be printed or not printed by the input module, at +the user's discretion. % , whether specified by the % user or defined in the standard library sets. @@ -134,67 +68,55 @@ also be specified with the same name \verb+tag+. The keyword \verb+NELEC+ allows the user to specify the number of core electrons replaced by -the ecp basis specification for the atom represented by the tag. Additional +the ECP basis specification for the atom represented by the tag. Additional input lines can then be used to define the specific coefficients. The string \verb+shell_type+ is used to specify the components of the ECP basis function. The label \verb+ul+ entered for \verb+shell_type+ for a given atom or center (identified by the string \verb+tag+) denotes the local part of the ECP basis. This is equivalent to the highest angular momentum -functions specified in the literature for most ecp basis sets. The +functions specified in the literature for most ECP basis sets. The standard entries (\verb+s, p, d+, etc.) for \verb+shell_type+ delineate the angular momentum projector onto the local function. The shell type label of \verb+s+ indicates the \verb+ul-s+ projector input, \verb+p+ indicates the \verb+ul-p+, etc. An application of the \verb+ECP+ directive is illustrated in the following -example using the molecule H$_2$CO. This input defines an ECP basis set +example for the molecule H$_2$CO. This input defines an ECP basis set for the carbon and oxygen atoms in the molecule. -\Large -(*****What about the hydrogen molecule? What basis set does it use?******) -\normalsize - -% The following example illustrate the input of an ECP for H$_2$CO. % \centerline{{\bf H$_2$CO }} \begin{verbatim} -ecp print -C nelec 2 # ecp replaces 2 electrons on C -C ul # d - 1 80.0000000 -1.60000000 - 1 30.0000000 -0.40000000 - 2 0.5498205 -0.03990210 -C s # s - d - 0 0.7374760 0.63810832 - 0 135.2354832 11.00916230 - 2 8.5605569 20.13797020 -C p # p - d - 2 10.6863587 -3.24684280 - 2 23.4979897 0.78505765 -O nelec 2 # ecp replaces 2 electrons on O -O ul # d - 1 80.0000000 -1.60000000 - 1 30.0000000 -0.40000000 - 2 1.0953760 -0.06623814 -O s # s - d - 0 0.9212952 0.39552179 - 0 28.6481971 2.51654843 - 2 9.3033500 17.04478500 -O p # p - s - 2 52.3427019 27.97790770 - 2 30.7220233 -16.49630500 -end + ecp print + C nelec 2 # ecp replaces 2 electrons on C + C ul # d + 1 80.0000000 -1.60000000 + 1 30.0000000 -0.40000000 + 2 0.5498205 -0.03990210 + C s # s - d + 0 0.7374760 0.63810832 + 0 135.2354832 11.00916230 + 2 8.5605569 20.13797020 + C p # p - d + 2 10.6863587 -3.24684280 + 2 23.4979897 0.78505765 + O nelec 2 # ecp replaces 2 electrons on O + O ul # d + 1 80.0000000 -1.60000000 + 1 30.0000000 -0.40000000 + 2 1.0953760 -0.06623814 + O s # s - d + 0 0.9212952 0.39552179 + 0 28.6481971 2.51654843 + 2 9.3033500 17.04478500 + O p # p - s + 2 52.3427019 27.97790770 + 2 30.7220233 -16.49630500 + end \end{verbatim} Generally contracted ECP basis sets are not in wide use, but the -functionality has been included in NWChem for applications where -they might be useful. The user should be aware, however, that -the atomic SCF code does not currently handle the guess -generation for ECP centers. Therefore, it may not be possible to obtain -an initial set of orbitals for either the SCF or DFT when using an ECP -basis set. It may be necessary to use a smaller basis set and then -project those orbitals to the -basis set that will be used, (refer to Section \ref{sec:vectors}). Convergence -and starting orbital guesses are being addressed in ongoing development -work with the code. +functionality has been included in NWChem for applications where they +might be useful. + diff --git a/doc/user/execution.tex b/doc/user/execution.tex index b20c45012a..45f95b0550 100644 --- a/doc/user/execution.tex +++ b/doc/user/execution.tex @@ -12,7 +12,7 @@ specific resources, and differing services provided by the operating system.} . To run NWChem sequentially on nearly all UNIX-based platforms simply use the command \verb+nwchem+ and provide the name of the input file -as an argument (section \ref{sec:inputfilename}). +as an argument (section \ref{sec:inputstructure}). Output is to standard output, standard error and Fortran unit 6 (usually the same as standard output). Files are created by default diff --git a/doc/user/functionality.tex b/doc/user/functionality.tex new file mode 100644 index 0000000000..0b4c1fba0d --- /dev/null +++ b/doc/user/functionality.tex @@ -0,0 +1,29 @@ +\label{sec:functionality} + +Current functionality includes: +\begin{itemize} +\item Self Consistent Field or Hartree Fock energy and analytic + gradients (RHF, UHF, high-spin ROHF). Analytic second derivatives + under development. +\item Gaussian Density Functional Theory (DFT) energy and analytic + gradients with many local and non-local exchange-correlation potentials +\item MP2 semi-direct energy and analytic gradients for RHF and UHF + references (frozen core under development). Direct MP2 energy (RHF + only) and resolution of the identity (RI) integral approximation MP2 + (RHF and UHF). +\item Coupled-cluster (RHF) with linear triples (gradients under + development). +\item Complete active space SCF (CASSCF) energy (gradients under + development). +\item Selected-CI with perturbation correction energy. +\item First derivatives for all methods by numerical difference of the + energy if analytic derivative is not available. +\item Second derivatives by numerical difference of gradients if + analytic seconds are not available. +\item Geometry Optimization (Minimization and Transition State) for + all methods. +\item Generation of the electron density file for the {\em Insight} + graphical program. +\item Interface to the natural bond orbital package. +\item Interface to the COLUMBUS multi-reference CI package. +\end{itemize} diff --git a/doc/user/geometry.tex b/doc/user/geometry.tex index 420a16752d..c539756021 100644 --- a/doc/user/geometry.tex +++ b/doc/user/geometry.tex @@ -1,272 +1,223 @@ \label{sec:geom} -The \verb+GEOMETRY+ directive is used to define specific geometry objects -for a calculation or series of calculations. The input for this directive -allows the user to define the geometry of the molecule(s) to be considered -in the calculation(s). NWChem already has a fairly good idea of what most -atoms look like and the sort of molecular structures in which they might be -arranged. This information is stored in the basis sets, which can be specified -for a given task using the \verb+BASIS+ directive (see Section -\ref{sec:basis}). The \verb+GEOMETRY+ directive allows the user to specify -particular elements of the geometry objects, such as the coordinates of -the individual atoms in a molecule, and the appropriate symmetry group. -It is also possible to define multiple geometry objects for the same -molecule under different names, for use in different tasks of the same -calculation. - -The form of the \verb+GEOMETRY+ directive is as follows; - \begin{verbatim} GEOMETRY [] \ - [units ] \ + [units ] \ [bqbq] \ - [print [xyz] || noprint] + [print [xyz] || noprint] \ + [autoz] - [SYMMETRY GROUP [print]] + [SYMMETRY [GROUP] [print]] - + geometry specification (cartesian || Z-matrix) + + [ZCOORD ... END] END \end{verbatim} -% Cartesian geometry specification, as well as Z-matrix-like format is -% available. As mentioned above (section -% \ref{sec:arch}), multiple geometries may be stored in the database -% provided each is given an independent name. The default name of -% \verb+"geometry"+ is used by most application modules to access the -% geometry at which to perform a calculation. Associating a named -% geometry with the required name of \verb+"geometry"+ is described in -% section \ref{sec:arch}. Known names for units are \verb+au+, -% \verb+bohr+, or \verb+angstrom+ (the conversion factor used to convert -% from Angstr\"{o}m to Bohr is $1.8897265$). By default, the input -% module prints any geometry it encounters. Printing can be disabled -% with the \verb+PRINT+ option. The \verb+XYZ+ qualifier to print -% causes the geometry to also be printed in the \verb+XYZ+ format of -% XMol. - -This is a multiple directive and may contain many or few lines, -depending on the application. The input supplied with this directive -consists of three main sections; +The input supplied with this directive consists of three main +sections; \begin{itemize} -\item basic information to identify the geometry object in the code and -define how it will be processed -\item input to identify the symmetry group for the molecule -\item input to specify the geometric locations of the atoms in the - molecule (cartesian coordinates or Z-matrix) - +\item keywords on the the line of the geometry directive that specify + the name, units, etc. +\item symmetry information +\item input to specify the locations of the atoms and centers + (cartesian coordinates or Z-matrix) \end{itemize} -The input options and keywords for each of these sections are -discussed in detail in the following subsections. +These are examined in the following subsections. -\subsection{Geometry Object Identification Input} +\subsection{Keywords on the geometry directive} +\subsubsection*{{\tt NAME}} +The default \verb+name+ for a geometry object is \verb+geometry+, and +most modules in the code look for a geometry with this name. The user +can direct a module to a different geometry by assigning the string +\verb+geomery+ to \verb+name+ using the \verb+SET+ directive (see the +example in Section \ref{sec:set}). -The input for the first four lines of the directive allows the user to name -the object, specify the geometry input format, decide how to treat dummy -centers in the geometry, and tell the code what to do about printing -the geometry information. +\subsubsection*{{\tt UNITS}} +The default units for the geometry input unit is {\AA}ngstr\"{o}m +(\verb+bohr+ or \verb+au+), however atomic units or Bohr are used +internally. However, the geometric coordinates can also be supplied +in atomic units, nanometers and picometers by specifying the +appropriate value for the \verb+UNITS+ keyword. (Note: The default +conversion factor used in the code to convert from {\AA}ngstr\"{o}m to +Bohr is $1.8897265$.) -The default \verb+name+ for a geometry object is the string \verb+geometry+, -and most modules in the code look for an object with this name. -The user can redirect the module to a different geometry object by assigning -the string \verb+geomery+ to \verb+name+ using the \verb+SET+ directive -(see Section \ref{sec:set}). The default for the geometry input unit -is \verb+bohr+ (or \verb+au+), and this is the working unit for such -distances in the code. -However, the geometric coordinates can be supplied in -\verb+angstrom+ by specifying this keyword in the directive. -(Note: The conversion factor used in the code to convert from Angstr\"{o}m -to Bohr is $1.8897265$.) +Possible values for the \verb+UNITS+ keyword are (only the first two +characters need be specified) +\begin{itemize} + \item \verb+angstrom+ --- {\AA}ngstr\"{o}m, the default. Converts + to A.U. using the \AA\ to A.U. conversion factor. + \item \verb+au+ or \verb+atomic+ or \verb+bohr+ --- Atomic units + \item \verb+nm+ or \verb+nanometers+ --- nanometers (converts to + A.U. using a conversion factor computed as $10.0$ times the + \AA\ to A.U. conversion) + \item \verb+pm+ or \verb+picometers+ --- picometers (converts to + A.U. using a conversion factor computed as $0.01$ times the + \AA\ to A.U. conversion) +\end{itemize} -The default in NWChem is to ignore interactions between dummy centers. -Specifying the keyword \verb+bqbq+ forces the code to include these -interactions. The complimentary keywords \verb+print+ and \verb+noprint+ -allow the user to specify the print option for the geometry module, -independent of any specifications in the top-level \verb+PRINT+ directive. -The \verb+print+ keyword tells the code to print everything for this -module, regardless of other instructions. In addition, the keyword -\verb+xyz+ specifies that the coordinates will be printed in the XYZ -format of XMol. If the keyword \verb+noprint+ is specified, the printing -of all geometry output for this module is suppressed. +E.g., the following directives all specify the same geometry for $H_2$ +(a bond length of 0.732556\ \AA). +\begin{verbatim} + geometry + h 0 0 0 + h 0 0 0.732556 + end + + geometry units nm + h 0 0 0 + h 0 0 0.0732556 + end + + geometry units pm + h 0 0 0 + h 0 0 73.2556 + end + + geometry units atomic + h 0 0 0 + h 0 0 1.3843305 + end +\end{verbatim} + +\subsubsection*{{\tt BQBQ}} +The default in NWChem is to ignore interactions between dummy centers +(those beginning with \verb+bq+ or \verb+x+), +when computing energies or energy derivatives. These interactions +will be included if the keyword \verb+BQBQ+ is specified. + +\subsubsection*{{\tt PRINT} and {\tt NOPRINT}} +The complimentary keywords \verb+print+ and \verb+noprint+ +enable/disable printing of the geometry when it is read by the input +module. It is printed by default. In addition, the print keyword may +be qualitifed by the additional keyword \verb+XYZ+ which specifies +that the coordinates should be printed in the XYZ format of XMol. + +\subsubsection*{{\tt AUTOZ}} +By default the Cartesian or Z-matrix parameters provided by the user +in the body of the geometry directive are used in subsequent geometry +optimizations. If \verb+AUTOZ+ is specified then the user's input is +used {\em only} to define the starting geometry and NWChem will +automatically generate a set of internal coordinates suitable for +geometry optimization. See the Section \ref{sec:zcoord} for how to +force the definition of specific internal variables in combination +with automatically generated variables. \subsection{Symmetry Group Input} -The input following the keyword \verb+SYMMETRY GROUP+ is used to specify -the symmetry for the molecule modeled with this geometry object. -There is no default for this input in the current version of NWChem, since -the use of molecular symmetry is not yet automated in the code. -Examples of expected input for the string \verb+group_name+ include -such entries as +The symmetry directive is used to specify the point group for the +molecular geometry (space group information for 1-, 2-, and +3-dimensional periodic systems is not yet documented). The point +group name should be specified as the standard Sch\"{o}files symbol. -\begin{itemize} -\item \verb+c2v+ -- for molecular symmetry C\_{2v} -\item \verb+d2h+ -- for molecular symmetry D\_{2h} -\item \verb+Td+ -- for molecular symmetry T\_{d} -\item \verb+d6h+ -- for molecular symmetry D\_{6h} -\end{itemize} - -The user must know the symmetry of the molecule being modeled, and be able -to specify the -coordinates of the symmetry-unique atoms in a suitable orientation -relative to the rotation axes and symmetry planes. -Appendix \ref{symexamples} lists a number of examples of the \verb+geometry+ -directive input for specific molecules having symmetry patterns recognized -by NWChem. +The default is no symmetry ($C_1$ point group) and detection of point +group symmetry is not yet automated, though this is planned. The user +must also know the symmetry of the molecule being modeled, and be able +to specify the coordinates of the symmetry-unique atoms in a suitable +orientation relative to the rotation axes and symmetry planes. +Appendix \ref{symexamples} lists a number of examples of the +\verb+geometry+ directive input for specific molecules having symmetry +patterns recognized by NWChem. \subsection{Cartesian coordinate input} \label{sec:cart} -The default in NWChem is to specify the geometry information in Cartesian -coordinates. Each atom of the molecule being modeled by the geometry -object must be specified on a line in the directive. That is, each atom -or center -must be identified on a line of the following form; - +The default in NWChem is to specify the geometry information entirely +in Cartesian coordinates, and examples of this format have already +appeared above (e.g, Section \ref{sec:realsample}). Each center +(usually an atom) is identified on a line of the following form; \begin{verbatim} \ - [charge ] [mass ] [ghost] + [charge ] [mass ] \end{verbatim} -The string \verb+tag+ is the name of the atom or center. The string -is limited to -16 characters, and must correspond to the -name of an atom in one of the basis sets defined for the calculation. -Atoms or centers with the same \verb+tag+ will use the same basis set in -the calculation. -(See Section \ref{sec:basis} for a discussion of the input for the -\verb+BASIS+ directive). In most cases, the entry for \verb+tag+ is the -chemical symbol for the element, such as \verb+O+ for oxygen, \verb+H+ -for hydrogen, \verb+Fe+ for iron, etc. Dummy centers -are differentiated from atoms and centers by giving them a \verb+tag+ that -begins with the letters \verb+bq+. An atom must have basis functions -associated with it, and so must all centers. If the keyword \verb+bqbq+ -is specified, dummy centers must also have basis functions. +The string \verb+tag+ is the name of the atom or center and its case +(upper or lower) is important. The tag is limited to 16 characters +and is interpreted as follows +\begin{itemize} +\item If it begins with either the symbol or name of an element + (ignoring case) then it is thought to be an atom of that type + and the default charge is the atomic number adjusted for the + presence of ECPs (see \ref{sec:ecp}). Additional characters can + be used to distinguish between atoms of the same element. E.g., + the tags \verb+oxygen+, \verb+O+, \verb+o34+, \verb+olonepair+, + and \verb+Oxygen-ether+, will all be interpreted as being oxygen + atoms. Atoms {\em must} have basis functions associated with + them (Section \ref{sec:basis}). + \item If the tag begins with either \verb+BQ+ or \verb+X+ + (ignoring case) then it is treated as a dummy center with + default zero charge. Dummy centers may optionally have basis + functions or non-zero charge. Note, that in order to recogonize + the xenon atom (Xe) it is not possible to input a dummy atom + beginning with the characters \verb+XE+ --- an attempt to do + this will generate a xenon atom. + \item {\em If the tag begins with characters that cannot be + matched against an atom or \verb+BQ+ or \verb+X+ then a fatal + error is generated.} +\end{itemize} -The xyz coordinates of the atom in the molecule -are specified as real numbers -following the string \verb+tag+. The user also has the option of -specifying the charge of the atom (or center) and its mass. +It is {\em important} to be aware of the following points +\begin{itemize} +\item The tag of a center is used in the \verb+BASIS+ directive (Section +\ref{sec:basis}) to associate functions with centers. +\item All centers with the same tag will have the same basis +functions. +\item When automatic symmetry detection is functional only centers +with the same tag will be candidates for testing for symmetry +equivalence. +\item The user specified charges (of all centers, atomic and dummy) +and any net total charge of the system (Section \ref{sec:charge}) are +used to determine the number of electrons. +\end{itemize} -The default charge for an -atom is its atomic number, adjusted for the presence of ECPs (see Section -\ref{sec:ecp}). In order to specify a different value for the -charge on a particular atom, the user must enter -the keyword \verb+charge+, then enter a real number for the unit charge -of the atom in the real variable \verb+charge+. The values specified for the charges of -all atoms, centers, and -dummy centers are used in conjunction with the -total charge of the system (as specified with the \verb+CHARGE+ directive; -see Section -\ref{sec:charge}) to determine the total number of electrons in the system. +The Cartesian coordinates of the atom in the molecule are specified as real +numbers following the string \verb+tag+. The user also has the option +of specifying the charge of the atom (or center) and its mass. -The default mass for an atom is taken to be the mass of its highest naturally -occurring isotope. If the user wishes to model some other isotope of the -element, its mass must be defined explicitly by specifying the keyword -\verb+mass+ and entering the appropriate value for \verb+mass+. +The default charge for an atom is its atomic number, adjusted for the +presence of ECPs (see Section \ref{sec:ecp}). In order to specify a +different value for the charge on a particular atom, the user must +enter the keyword \verb+CHARGE+. + +The default mass for an atom is taken to be the mass of its highest +naturally occurring isotope. If the user wishes to model some other +isotope of the element, its mass must be defined explicitly by +specifying the keyword \verb+MASS+. -% Each line in the body of the directive specifies the name or tag, and -% the coordinates of one center or atom. The charge associated with the -% center is inferred from the atom type. The charge may be explicitly -% specified using the \verb+CHARGE+ keyword. Default masses may be -% overriden by specifying the mass. The default masses are those of the -% highest naturally abundant isotope for the given atom, not the average -% mass of the element. -% -% The tag associated with each center is interpreted as follows: -% \begin{itemize} -% \item If it begins with \verb+BQ+ (ignoring case) then it is treated -% as a dummy center with default zero charge. Dummy centers may -% optionally have basis functions or non-zero charge. -% \item If it begins with either the symbol or name of an element then -% it is thought to be an atom. Atoms {\em must} have basis -% functions associated with them and the default charge is the -% atomic number adjusted for the presence of ECPs (see -% \ref{sec:ecp}). The user provided charges (of all centers, -% atomic and dummy) and the total charge of the system are used to -% determine the number of electrons -% \item The tag of a center is used in the \verb+BASIS+ directive to -% associate functions with centers. All centers with the same tag -% will have the same basis functions. Atomic centers may have -% standard basis sets sited upon them. -% \item When automatic symmetry detection is functional only centers -% with the same tag will be candidates for testing for symmetry -% equivalence. -% \end{itemize} -% -% By default NWCHEM does not include the interaction between dummy -% centers. The \verb+BQBQ+ qualifier to the \verb+GEOMETRY+ directive -% causes these interactions to be included. -% -% The use of molecular symmetry in NWCHEM is not yet automated, thus, -% the user is responsible for detecting symmetry and specifying the -% coordinates of the symmetry unique atoms in a suitable orientation -% relative to the rotation axes and symmetry planes. Since it seems -% that only the original authors of the symmetry package seem to -% understand the latter, we provide many examples in Appendix -% \ref{symexamples}. \subsection{Z-matrix input} \label{sec:Z-matrix} -Using the - \begin{verbatim} - [zmt - [ghost] + (ZMT || ZMATRIX || ZMAT) + + [VARIABLES + ] - + [CONSTANTS + ] - - - zend] + (END || ZEND) \end{verbatim} -allows -the user to specify the structure of the molecule by means of its Z-matrix. -However, it is also possible to enter the coordinates of some of the atoms using -cartesian coordinates, even in the \verb+[zmt ... zend]+ environment. -The code is able to distinguish between -the two types of input by means of the input following the string \verb+tag+ -for the particular atom. If the Z-matrix input is specified for the atom, -the input consists of pairs numbers that define connectivity indices and -bond length, bond angle, or torsion angle. If the -input is in Cartesian coordinates, the input consists of three real numbers -defining the x,y,z coordinates of the atom. However, the x,y,z coordinates -must be specified in {\AA}ngstr{\"o}ms, regardless of the entry specified -for \verb+units+. +This allows the user to specify the structure of the system with a +Z-matrix which allows specification of the molecular structure using +either cartesian coordinates (see Section \ref{sec:zmcart})or internal +coordinates (bond lengths, bond angles and dihedral angles). The +Z-matrix input for a center consists of pairs numbers that define +connectivity indices and a bond length and bond or torsion angless. +Cartesian coordinate input consists of three real numbers defining the +x,y,z coordinates of the atom. {\em Within the Z-matrix input bond + lengths and cartesian coordinates must presently be specified in + {\AA}ngstr{\"o}ms, regardless of the entry specified for + \verb+units+.} Angles are specified in degrees. -The keyword \verb+ghost+ is used to denote a 'ghost' atom in the molecular -geometry. A 'ghost' atom is like an ordinary atom in that it has its -associated basis set, but it is assumed to have a nuclear charge of zero. -This is a useful property for such things as counterpoise calculations to assess basis set -superposition error. - -% If the \verb+GEOMETRY+ directive contains the \verb+zmat+ keyword, the -% structure of the molecule is defined by means of its Z-matrix, or -% the cartesian coordinates of the atoms, or a mixture of the two. A -% blank line terminates the list of the atoms. Bond lengths, bond -% angles, or torsion angles can be specified by means of numerical -% values assigned to variables. The list of variables and their -% assigned numerical values follow the list of atoms, and is also -% terminated with a blank line. Then comes the end of the data group -% input with a last line 'end' -% -% A second set of variables to be qualified as '{\bf frozen}' may be -% specified. They come after the blank line that indicates the end -% of the 'variables'. The second set is also terminated by a blank line. -% {\bf The 'frozen' specification is presently not active, but included -% to ensure compatibility with other codes. Only cartesian coordinates -% can be kept constant via the 'active atoms' list (see section -% \ref{sec:activeatoms})} -% -% 'Ghost' atoms, often used in the assessment of basis set superposition -% error for example, are atoms with their associated basis set, but -% for which the nuclear charge is set to zero. Specifying a 'ghost' atom -% may be accomplished appending the '{\tt ghost}' parameter at the end of the -% appropriate lines below. % % When two numerical values, separated by a comma, are given for some % variables, they are considered as the initial and final values for the @@ -274,187 +225,160 @@ superposition error. % geometries generated by linear interpolation between the initial and % final values. -The input supplied for the atoms describing the molecule by means of its -Z-matrix requires the following sequential approach. +The centers (denoted as \verb+i+, \verb+j+, and \verb+k+ below) used +to specify Z-matrix connectivity may be given either as integers +(indentifying the centers by number) or as the tag of the center. +{\em If the tag is used, this tag must be unique.} The use of +``dummy'' atoms is possible, by using \verb+X+ or \verb+BQ+ at the +start of the tag. + +Bond lengths, bond angles and dihedral angles (denoted below as {\tt + R}, {\tt alpha}, {\tt beta} respectively) may be specified either as +numerical values or as symbolic strings which are subsequently +defined. The same sybmolic string may be used several times. Any +mixture of numeric data and symbols may be given. + +The Z-matrix input is specified sequentially as follows +\begin{verbatim} + tag1 + tag2 i R + tag3 i R j alpha + tag4 i R j alpha k beta [l] + ... +\end{verbatim} + +We examine this in more detail. In the following, the tag or number +of the center being currently defined is labelled as \verb+C+ (``C'' +for current). Figures \ref{fig:zmat1}, \ref{fig:zmat2} and +\ref{fig:zmat3} display the relationship between the input data +and the definition of centers and angles. + +\begin{figure}[htbp] +\centering +\psfig{figure=zmat1.eps} + +\caption{\label{fig:zmat1} Relationship between the centers, bond angle +and dihedral angle in Z-matrix input.} +\end{figure} + +\begin{figure}[htbp] +\centering +\psfig{figure=zmat2.eps} + +\caption{\label{fig:zmat2} Relationship between the centers and two + bond angles in Z-matrix input with optional parameter specified as $+1$.} +\end{figure} + +\begin{figure}[htbp] +\centering +\psfig{figure=zmat3.eps} + +\caption{\label{fig:zmat3} Relationship between the centers and two + bond angles in Z-matrix input with optional parameter specified as $-1$.} +\end{figure} \begin{enumerate} - \item $<$atom$>$ [ghost] + \item \verb+tag1+ -% Only the name of the first atom is required. 'ghost' is used -% only when specifying a 'ghost' atom. - For the first atom in the molecule, the Z-matrix input requires only - the name of the atom at it appears in the basis set. This is usually - the chemical symbol for the atom. - However, if the atom is a 'dummy center', the chemical symbol must - be preceded by \verb+x+ or \verb+bq+. (The keyword 'ghost' is required - only when specifying that the atom is to be defined as a 'ghost' atom.) + Only the tag of the first center is required. - \item $<$atom$>$ $<$i1$>$ $<$blength$>$ [ghost] + \item \verb+tag2 i R+ -% Only a name and a bond distance is required for atom 2. For 'ghost', -% same remark applies as before. - For the second atom, the Z-matrix input requires the name of the atom - as it appears in the basis set, - plus the connectivity $<$i1$>$ and the bond distance $<$blength$>$ - connecting it to another atom. + The second center requires specification of its tag and the + bond-length ($R_{Ci}$) from the first atom which is identified by + \verb+i+. - (NOTE: The connectivity for any bond, {\tt i1, i2, i3} \ldots, - can be specified as an integer (1, 2, 3, \ldots) or as a string - which matches the name specified for one of the atoms in the molecule. - If the connectivity (such as {\tt i1}) is defined as a string, - and the same element appears more than once in the molecule, a number - must be added to the {\tt atom} string of the Z-matrix input for - subsequent appearances of that element in the molecule, to ensure - a unique \verb+tag+ for each occurance.) + \item \verb+tag3 i R j alpha+ - \item $<$atom$>$ $<$i1$>$ $<$blength$>$ $<$i2$>$ $<$alpha$>$ [ghost] + The third center requires specification of its tag, its distance + ($R_{Ci}$) to one of the previous two centers (identified by the + value of \verb+i+) and the angle $\widehat{Cij}$. -% Only a name, distance, and angle are required for atom 3. For -% 'ghost', same remark applies as before. - For the third atom of the molecule, the Z-matrix input requires the - name of the atom as it appears in the basis set and the connectivity - $<$i1$>$ and bond distance - $<$blength$>$ connecting it to atom 2, plus the connectivity $<$i2$>$ - and angle $<$alpha$>$ it makes with the plane of the first two atoms. + \item \verb+tag i R j alpha k beta []+ - \item $<$atom$>$ $<$i1$>$ $<$blength$>$ $<$i2$>$ $<$alpha$>$ $<$i3$>$ $<$beta$>$ $<$i4$>$ [ghost] % + The fourth, and all subsequent centers, require the tag, a bond + length ($R_{Ci}$) relative to center \verb+i+, the angle with + centers \verb+i+ and \verb+j+ ($\widehat{Cij}$), and {\em either} + \begin{enumerate} + \item the dihedral angle betwen the current center and centers + \verb+i+, \verb+j+ and \verb+k+ (Figure \ref{fig:zmat1}), or + \item a second bond angle $\widehat{Cik}$ and an orientation to + the plane containing the other three centers (Figure + \ref{fig:zmat2} and \ref{fig:zmat3}). + \end{enumerate} - For the fourth atom and all subsequent atoms in the molecule (if it - has more than four atoms), the Z-matrix input requires the name - of the atom as it appears in the basis set, - plus the connectivities and bond length, - bond angle, and either the dihedral angle or a second bond angle - for the atom. - - \begin{itemize} -% \item [$\bullet$] {\tt atom} is the chemical symbol of this -% atom; it can be followed -% by numbers if desired. The chemical symbol implies the nuclear -% charge. - \item [$\bullet$] {\tt i1} defines the connectivity of the following bond -% \item [$\bullet$] {\tt blength} is the bond length 'this atom-atom i1'. - \item [$\bullet$] {\tt blength} is the bond length between this atom and the atom denoted by {\tt i1} - \item [$\bullet$] {\tt i2} defines the connectivity of the following angle -% \item [$\bullet$] {\tt alpha} is the angle 'this atom-atom i1-atom i2'. - \item [$\bullet$] {\tt alpha} is the angle that the bond with this atom -makes with the plane of the bond between atom {\tt i1} and atom {\tt i2} - \item [$\bullet$] {\tt i3} defines the connectivity of the following angle -% \item [$\bullet$] {\tt beta} is either the dihedral angle -%'this atom-atom {\tt i1}-atom {\tt i2}-atom -% {\tt i3}', or perhaps a second bond angle, 'this atom-atom i1-atom {\t%t i3}' - \item [$\bullet$] {\tt beta} is the dihedral angle between -this atom and the plane containing atom {\tt i1} and atom {\tt i2} and atom - {\tt i3}; alternatively, it defines a second bond angle for - this atom, between this atom and the plane of the two atoms - atom {\tt i1} and atom {\tt i3}. -Which alternative is selected depends on the value specified for {\tt i4}, as explained below. -% \item [$\bullet$] {\tt i4} defines the nature of {\tt beta}. If -%{\tt beta} is a dihedral -% angle, {\tt i4}=0 ( default ). If {\tt beta} is a second bond angle, -% then {\tt i4}=+/-1 -% (sign specifies one of two possible directions). -% \item [$\bullet$] For 'ghost', same remark applies as before. - \item [$\bullet$] {\tt i4} defines the nature of the input for {\tt beta}. If {\tt i4} is zero, -{\tt beta} is interpreted as a dihedral - angle. (This is the default.) If {\tt i4} is entered as +1 or -1, {\tt beta} -is interpreted as a second bond angle. (The sign of {\tt i4} specifies the -direction of the bond angle relative to the plane described by the -three reference atoms). - \end{itemize} - -% \item Line no.\ 4 is repeated for each remaining atom. A blank line -% indicates the end of the atoms in the molecule. - -% \item The use of 'dummy' atoms is possible, by using 'X' or 'BQ' for the -%chemical symbol. -% -% \item The connectivity i1, i2, i3, may be given as integers, -% 1, 2, 3, 4, 5, \ldots or as strings which match one of the {\tt atom}s. -% In this case, numbers must be added to the {\tt atom} string to -% ensure uniqueness. -% -% \item Symbolic strings may be given in place of numeric values for -%{\tt blength}, {\tt alpha}, {\tt beta}. The same string may be repeated. Any mixture of -% numeric data and symbols may be given. -% -% \item All symbolic definitions follow the blank line that signals the -% end of the Z-matrix input. The list of symbolic definitions ends with a -% blank line, followed by an '{\tt end}' directive. If there are no symbolic -% definitions, and all the bond lengths, angles, and torsions are -% specified by their numeric values in the Z-matrix data, then the -% end of the Z-matrix data is detected through two blank lines, one -% to indicate the end of the Z-matrix proper, the other to indicate -% the end of the symbolic definitions. -% -% \item A second set of symbolic definitions, separated from the -% first set through a blank line, may be included to specify -% {\bf frozen} internal -% coordinates. A blank line again defines the end of the -% list of 'frozen' internal coordinates. -% -% \item Note that atoms in the Z-matrix data may be specified via Cartesian -% coordinates expressed in units of {\AA}ngstr{\o}ms, Each line has the -% following form: -% -% \begin{verbatim} -% [ghost] -% \end{verbatim} -% -% with {\tt atom} being the atomic name as before, x, y, z being the -% Cartesian coordinates, and {\tt ghost} used only when specifying a -% 'ghost' atom. + By default $\beta$ is interpreted as a dihedral angle (see Figure + \ref{fig:zmat1}), but if the optional last parameter (\verb+l+) is + specified with the value $\pm 1$ then $\beta$ is interpreted as + the angle $\widehat{Cik}$. The sign of \verb+l+ specifies the + direction of the bond angle relative to the plane described by the + three reference atoms. If \verb+l+ is $+1$ then the new center + (\verb+C+) is above the plane (Figures \ref{fig:zmat2}), and if + \verb+l+ is $-1$ then \verb+C+ is below the plane (Figure + \ref{fig:zmat3}). \end{enumerate} -The Z-matrix variables {\tt blength}, {\tt alpha}, and {\tt beta} can be -entered either as numeric values or symbolic strings, or as a mixture of -the two types for a given atom. The end of the Z-matrix input for the -molecule is signaled by a blank line in the directive, and all symbolic -definitions for the variables must be supplied following that blank line. -The list of symbolic definitions is terminated with another blank line. -If there are no symbolic definitions for the Z-matrix input (that is, -all of the bond lengths, angles, and torsions are specified by their -numeric values), then the end of the Z-matrix data is signaled by entering -two blank lines in the directive; one to indicate the end of the Z-matrix -input, and the other to indicate the end of the symbolic definitions. +Following the Z-matrix center definitions described above, may be two +optional sections which are described next. -The \verb+GEOMETRY+ directive also contains a feature that allows the user -to define symbolic definitions for a set of variables that will be -qualified as '{\bf frozen}'. A {\bf frozen} atom is one that will not -have any of its geometric parameters changed in the course of an optimization -or other calculation that would change the geometry of a molecule. -The ability to actually use this feature -for atoms defined by means of the Z-matrix input does not exist in NWChem -as yet, but the input option has been included to ensure compatibility with -other codes. Only atoms that have been specified using Cartesian coordinates -can retain their geometry parameters at the specified input values. This -is accomplished by means of the optional 'active atoms' list (refer to Section -\ref{sec:activeatoms}). - -If the user wishes to specify a set of {\bf frozen} variables, however, -% (we won't ask why...) -they must be specified following the blank line that signals the end of -the symbolic definitions for the Z-matrix input. The end of the input -for the {\bf frozen} variables is also signaled with a blank line. - -The following example illustrates the Z-matrix input for the molecule -$CH_3CF_3$. This input uses integer numbers for the connectivities {\tt i1}, -{\tt i2}, {\tt i3} \ldots, but has symbolic strings as entries for the Z-matrix -variables {\tt blength}, {\tt alpha}, and {\tt beta}. It therefore must -also include input lines defining the symbolic strings, following the blank -line that terminates the Z-matrix input. This example also includes a set -of {\bf frozen} variables, which are entered after the blank line terminating -the definitions of the symbolic strings used by the Z-matrix. - - -% \subsubsection*{example} - -% The following example is the z-matrix for $CH_3CF_3$, - -The \verb+GEOMETRY+ directive for this example is as follows; +The first must be prefaced by the directive \verb+VARIABLES+ and is +used to define initial values for the symbolic variables used within +the Z-matrix. \begin{verbatim} - zmt + VARIABLES + + ... +\end{verbatim} +Each line contains the name of a variable followed by its value. +Optionally, an equals sign (\verb+=+) may be included between the +symbol and its value. + +The second section, \verb+CONSTANTS+, is used to define Z-matrix symbolic +variables that remain unchanged during geometry optimizations. +\begin{verbatim} + CONSTANTS + + ... +\end{verbatim} +Each line contains the name of a variable followed by its value. +Optionally, an equals sign (\verb+=+) may be included between the +symbol and its value. +{\em Note that this functionality is not yet available and that all + Z-matrix parameters (Cartesian coordinates, numerically specified + bond-lengths and angles, and symbolic variables) will be modified + during geometry optimizations.} To freeze the Cartesian coordinates +of an atom refer to Section \ref{sec:activeatoms}). + +The end of the Z-matrix input signaled by either \verb+END+ or +\verb+ZEND+. + +A simple example is presented for water. All Z-matrix parameters are +specified numerically, and the symbolic tags are used to specify +connectivity information. This requires that all tags are unique, and +so different tags are used for the hydrogen atoms which might +otherwise be identical. +\begin{verbatim} + geometry + zmatrix + O + H1 O 1.08 + H2 O 1.08 H1 108.0 + end + end +\end{verbatim} + +The following example illustrates the Z-matrix input for the molecule +$CH_3CF_3$. This input uses the numbers of centers when specifying +the connectivity information (\verb+i+, \verb+j+ and \verb+k+) and +uses symbolic variables for the Z-matrix parameters {\tt R}, {\tt + alpha}, and {\tt beta} which are defined in \verb+VARIABLES+ and +\verb+CONSTANTS+ sections. + +\begin{verbatim} +geometry + zmatrix C C 1 CC H 1 CH1 2 HCH1 @@ -463,40 +387,75 @@ The \verb+GEOMETRY+ directive for this example is as follows; F 2 CF1 1 CCF1 3 TOR3 0 F 2 CF2 1 CCF2 6 FCH1 1 F 2 CF3 1 CCF3 6 FCH2 -1 - - CC = 1.4888 - CH1 = 1.0790 - CH2 = 1.0789 - CH3 = 1.0789 - CF1 = 1.3667 - CF2 = 1.3669 - CF3 = 1.3669 - - HCH1 = 10428 - HCH2 = 10474 - HCH3 = 1047 - CCF1 = 112.0713 - CCF2 = 112.0341 - CCF3 = 112.0340 - TOR1 = 109.3996 - TOR2 = 109.3997 - TOR3 = 180.0000 - FCH1 = 106.7846 - FCH2 = 106.7842 - - zend + variables + CC 1.4888 + CH1 1.0790 + CH2 1.0789 + CH3 1.0789 + CF1 1.3667 + CF2 1.3669 + CF3 1.3669 + constants + HCH1 10428 + HCH2 10474 + HCH3 1047 + CCF1 112.0713 + CCF2 112.0341 + CCF3 112.0340 + TOR1 109.3996 + TOR2 109.3997 + TOR3 180.0000 + FCH1 106.7846 + FCH2 106.7842 + end +end \end{verbatim} -% The separation of the symbolic definitions into two groups is what -% makes the internal coordinates of the second group 'frozen'. -% Removal of the blank line between the first and second set of -% symbolic definitions would remove the 'frozen' character of all the -% variables defined in the second group. +\subsubsection{Using Cartesian variables in Z-matrices} +\label{sec:zmcart} -In this example, the symbolic strings listed after the first blank line -(which signals the end of the Z-matrix input for the molecule) are defined -with the values listed ({\tt CC= 1.4888}, {\tt CH1 = 1.0790}, etc.). The -second blank line forces the symbolic definitions starting with {\tt HCH1 -= 10428} to be {\bf frozen}. Currently this has no effect on the -program, but is included for compatibility with other codes. +In order to specify Cartesian coordinates within the Z-matrix it is +necessary to understand the orientation of centers specified using +internal coordinates. These are arranged as follows: +\begin{itemize} +\item The first center is placed at the origin. +\item The second center is placed along the positive z-axis. +\item The third center is placed in the z-x plane. +\end{itemize} +\subsection{{\tt ZCOORD} --- Defining internal coordinates for {\tt AUTOZ}} +\label{sec:zcoord} + +The \verb+AUTOZ+ keyword forces automatic generation of internal +coordinates for use in geometry optimizations. Connectivity +is inferred by comparing inter-atomic distances with van de Waals +radii, and under some circumstances it may be necessary to augment the +automatically generated list of internal coordinates. This is +accomplished by including a {\tt ZCOORD} section within the geometry +directive. + +The centers \verb+i+, \verb+j+, \verb+k+ and \verb+l+ below {\em must} be +specified using number of the centers. +\begin{verbatim} + ZCOORD + ijbond i j + ijkang i j k + ijklto i j k l + ijklop i j k l + ijklnb i j k l + END +\end{verbatim} + +\begin{itemize} +\item {\tt ijbond} --- a bond between the two centers. +\item {\tt ijkang} --- a bond angle $\widehat{ijk}$. +\item {\tt ijklto} --- a torsion (or dihedral) angle. The + angle between the planes \verb+i-j-k+ and \verb+j-k-l+. +\item {\tt ijklop} --- an out-of-plane bend. The angle of center + \verb+l+ out of the plane \verb+i-j-k+. +\item {\tt ijklnb} --- a linear bend. This defines two angles + corresponding to the deformation of the centers \verb+i--j--k+ + which may initially be arranged (nearly) linearly. The center + \verb+l+ must not be colinear. The two bends are constructed to be + within and perpendicular to the plane containing the atoms. +\end{itemize} diff --git a/doc/user/intro.tex b/doc/user/intro.tex index 36f4371263..08bf1a5220 100644 --- a/doc/user/intro.tex +++ b/doc/user/intro.tex @@ -1,49 +1,38 @@ +\label{sec:intro} +NWChem is a computational chemistry package designed to run on +high-performance parallel supercomputers and workstation clusters. +Code capabilities include the calculation of molecular electronic +energies and analytic gradients using self-consistent field, Gaussian +density function theory (DFT), and second-order perturbation theory. +Geometry optimization for energy minimization and transition states is +available for all methods. Classical molecular dynamics capabilities +provide for the simulation of macromolecules and solutions, including +the computation of free energies, using a variety of forcefields. -NWChem is a quantum chemistry package -designed to run on high-performance parallel supercomputers and -workstation clusters. Examples of applications include studies -of affinities for trapping cations K+ and Na+ with crown ethers, and -geometry optimization of a lithium ion bound to an 18-crown-6 ether. -Code capabilities include the calculation of molecular energies and -analytic gradients using self-consistent field (RHF, UHF, and high-spin -ROHF) or Gaussian Density Function Theory (DFT) with many local and -non-local exchange-correlation potentials. +NWChem is scalable in both its ability to treat large problems +efficiently, and in its utilization of available parallel computing +resources. The code uses the parallel programming tools TCGMSG and +the Global Array library developed at PNNL for the High Performance +Computing and Communication Initiative (HPCCI) grand-challenge +software program and the Environmental Molecular Sciences Laboratory +(EMSL) Project. NWChem has been optimized to perform calculations on +large molecules using large parallel computers and it is unique in +this regard. In contrast, its performance on small calculations +running on small computers is unremarkable. -Molecular energies are solved for using MP2 with direct or -semi-direct algorithms, or MP2 with the Resolution of the Identity (RI) -integral approximation, for coupled-cluster singles and doubles -with linear triples. Geometry optimization for energy minimization -and transition states is available for all methods with analytic -gradients. Molecular dynamics for classical systems is implementedd -for both distributed data and replicated data. Mixed classical -and quantum molecular dynamics is also available. - -NWChem is scalable in both its ability to -treat large problems efficiently, and in its utilization of available -parallel computing resources. The code uses parallel programming -tools TCGMSG and the Global Array library developed at PNNL -for the High Performance Computing and -Communication Initiative (HPCCI) grand-challenge software program and -the Environmental Molecular Sciences Laboratory (EMSL) Project, which -has supplied the majority of the development costs. -NWChem has been optimized to perform calculations on large molecules -using large parallel computers and it is unique in this regard. In -contrast, its performance on small calculations running on -small computers is unremarkable. - -This document is intended as an aid to analytic chemists attempting -to use the code for their own and collaborative applications. Users -are not expected to have a detailed understanding of the code internals, -but some familiarity with the overall structure of the code, how -it handles information, and the nature of the algorithms it contains -will generally be helpful. The following sections describe the -structure of the input file, and a give a brief overview of the -code archetecture. All input directives recognized by the code are +This document is intended as an aid to analytic chemists attempting to +use the code for their own applications. Users are not expected to +have a detailed understanding of the code internals, but some +familiarity with the overall structure of the code, how it handles +information, and the nature of the algorithms it contains will +generally be helpful. The following sections describe the structure +of the input file, and a give a brief overview of the code +archetecture. All input directives recognized by the code are described in detail, with options, defaults, and recommended usage, where applicable. Additional information on the molecular geometry -and basis function libraries included in the code is presented -in the appendices. +and basis function libraries included in the code is presented in the +appendices. \subsection{Citation} @@ -96,13 +85,11 @@ including; \item contact name and telephone number \end{itemize} - -Users can also subscribe to an electronic mailing list of other users of - the code. This is intended as a general forum through which code users -can contact one another and the developers to share experience with the code -and discuss problems. Reports on specific bugs and problems should -be sent first to -{\tt nwchem-support@emsl.pnl.gov}, however. +Users can also subscribe to an electronic mailing list of other users +of the code. This is intended as a general forum through which code +users can contact one another and the developers to share experience +with the code and discuss problems. Announcements of new releases and +bug fixes will also be made to this list. To subscribe to the user list, send a message to @@ -116,100 +103,418 @@ The body of the message must contain the line \item {\tt subscribe nwchem-users} \end{itemize} -The automated list manager is capable of recognizing a number of commands, including -'subscribe', 'unsubscribe', 'get', 'index', 'which', 'who', 'info' and -'lists'. The command 'end' halts processing of commands. It will provide -some help if the message includes the line {\tt help} in the body. Messages -can be posted to the list by -sending mail to {\tt nwchem-users@emsl.pnl.gov}. Reports of problems can -be posted to this list, if the user wishes to do so, but they should also -be posted to {\tt nwchem-support@emsl.pnl.gov}. The NWChem developers -will monitor the user list to help them stay aprised of user traffic and - current problems, but -the tracking system for bug reports is based on reports to the - {\tt nwchem-support} address. Users are encouraged to use the support -address rather than the mailing list for -the initial report of any problems with the code. +The automated list manager is capable of recognizing a number of +commands, including 'subscribe', 'unsubscribe', 'get', 'index', +'which', 'who', 'info' and 'lists'. The command 'end' halts +processing of commands. It will provide some help if the message +includes the line {\tt help} in the body. Messages can be posted to +the list by sending mail to {\tt nwchem-users@emsl.pnl.gov}. Users +are encouraged to use the support address rather than the mailing list +to report problems since the support mailer interfaces to an automated +bug tracking mechanism. \section{Getting Started} \label{sec:getstart} -The input to NWChem is composed of commands, called directives, which define -functions, actions, and keywords telling the code where to look for needed -input information, what databases to use, and what to write to output files. -The top level directives (see Section \ref{sec:toplevel}) are global and -known to all modules. -Directives that are specific to a particular module in general define keywords -and other input that is local to that module only. -The input is free format, and -keywords or blocks of module-specific directives can, with certain -minor restrictions, appear in any order. Case is ignored except -for actual data (e.g., names/tags of centers, titles). This section describes -the input format and the syntax used for the directives -(see subsection \ref{sec:syntax}). -The structure of an NWChem input file is also described (see subsection -\ref{sec:simplesample}), and illustrated using a simple example. In -addition, a more realistic and therefore more complicated example input -file is also presented (see subsection \ref{sec:realsample}). +This section provides an overview of NWChem input and program +architecture, and the syntax used to describe the input. See Sections +\ref{sec:simplesample} and \ref{sec:realsample} for examples of NWChem +input files with detailed explanation. -Sections \ref{sec:toplevel} through \ref{sec:NWargos} present detailed -descriptions of the individual -directives, giving the format of each along with options and defaults. Where -appropriate, examples are presented to illustrate the features and options -available for the directive. The directives fall into four main categories; +NWChem consists of independent modules that perform the various +functions of the code. Examples of modules include the input parser, +SCF energy, SCF analytic gradient, DFT energy, etc.. Data is passed +between modules and saved for restart using a disk-resident database +or dumpfile (see Section \ref{sec:arch}). +The input to NWChem is composed of commands, called directives, which +define data (such as basis sets, geometries, and filenames), and the +actions to be performed. Directives are processed in the order +presented in the input file, with the exception of certain start-up +directives (see Section \ref{sec:inputstructure}) which provide +critical job control information and are processed before all other +input. Most directives are specific to a particular module and define +data that is used by that module only. A few directives (see Section +\ref{sec:toplevel}) potentially affect all modules, for instance by +specifying the total charge on the system. + +There are two types of directives. Simple directives consist of one +line of input which may contain multiple fields. Compound directives +group together multiple simple directives that are in some way +related and are terminated with an \verb+END+ directive. See the +sample inputs (Sections \ref{sec:simplesample}, \ref{sec:realsample}) +and the input syntax specification (Section \ref{sec:syntax}). + +All input is free format, and directives or blocks of module-specific +directives can appear in any order with the exception of the +\verb+TASK+ directive (see sections \ref{sec:inputstructure} and +\ref{sec:task}) which is used to invoke an NWChem module. Case is +ignored except for actual data (e.g., names/tags of centers, titles). + +To make the input as short and simple as possible, most options have +default values. The user needs to supply input only for those items that +have no defaults, or for items that must be different from the defaults +for the particular application. In the discussion of each directive, the +defaults are noted, where applicable. + +The following sections provide more detail. + +\subsection{Input File Structure} +\label{sec:inputstructure} + +The structure of an input file reflects the internal structure of +NWChem. At the beginning of a calculation NWChem needs to determine +how much memory to use, the name of the database, whether it is a new, +restarted, or continuing job, where to put scratch/permanent files, +etc.. It is not necessary to put this information at the top of the +input file, however. NWChem will read through the {\em entire} input +file looking for the start-up directives. In this pass, all other +directives are ignored. + +The start-up directives are \begin{itemize} -\item top level directives for setup and job control (see Section \ref{sec:toplevel}) -\item directives to describe the geometry of the problem (see Section \ref{sec:geom}) -\item directives to define the basis set(s) for the problem (see Sections -\ref{sec:basis} and \ref{sec:ecp}) -\item directives to define theory and operations to be used to solve the problem -(see Sections \ref{SCF} through \ref{sec:NWargos}) +\item START +\item CONTINUE +\item RESTART +\item SCRATCH{\verb+_+}DIR +\item PERMANENT{\verb+_+}DIR +\item MEMORY +\item ECHO \end{itemize} -To make the input as short and simple as possible, most of the options and -features in the code have default values. The user needs to supply input only -for those items that have no defaults, or for items that must be different -from the defaults for the particular application. In the discussion of each -directive, the defaults are noted, where applicable. +After the input file has been scanned for the start-up directives, it +is rewound and read sequentially. Input is processed either by the +top-level parser (for the directives listed in Section +\ref{sec:toplevel}, such as \verb+TITLE+, \verb+SET+, \ldots) or by +the parsers for specific computational modules (e.g., SCF, DFT, +\ldots). Any directives that have already been processed (e.g., +\verb+MEMORY+) are ignored. Input is read until a \verb+TASK+ +directive (see Section \ref{sec:task}) is encountered. A \verb+TASK+ +directive request a calculation to be peformed and specifies the level +of theory and the operation to be performed. Input processing then +stops and the specified task is executed. The position of the +\verb+TASK+ directive in effect marks the end of the input for that +task. Processing of the input resumes upon the successful completion +of the task and the results of that task are availble to subsequent +tasks in the same input file. + +The name of the input file is usually provided as an argument to the +execute command for NWChem. That is, the execute command looks +something like the following; + +\begin{verbatim} + nwchem input_file +\end{verbatim} + +The default name for the input file is \verb+nwchem.nw+. If an input +file name \verb+input_file+ is specified without an extension, the code +assumes a default extension of \verb+input_file.nw+. If the code cannot +locate a file named either \verb+nwchem.nw+ or \verb+input_file.nw+, an +error is reported and execution terminates. The following +subsection presents two input files to illustrate the directive syntax and +input file format for NWChem applications. + +\subsection{Simple N2 Input File} +\label{sec:simplesample} + +As a first simple example we examine the SCF geometry optimization of +the nitrogen molecule using a Dunning cc-pvdz basis set. This input +file contains the bare minimum of information the user must specify in +order to run this type of problem --- fewer than ten lines of input, +as follows; +\begin{verbatim} + title; Nitrogen cc-pvdz SCF geometry optimization + geometry + n 0 0 0 + n 0 0 2.1 + end + basis + n library cc-pvdz + end + task scf optimize +\end{verbatim} + +Examining the input line by line, it can be seen that it contains +only four directives; \verb+TITLE+, \verb+GEOMETRY+, \verb+BASIS+, and +\verb+TASK+. The \verb+TITLE+ directive is optional, and is used only +as a means for the user to more easily identify outputs from different +jobs. An initial geometry is specified in cartesian coordinates and +atomic units. The Dunning cc-pvdz basis is obtained from the NWChem +basis library. The \verb+TASK+ directive requests an SCF geometry +optimization. + +The \verb+GEOMETRY+ directive (\ref{sec:geom}) defaults to cartesian +coordinates and atomic units ({\AA}ngstr{\o}m may also be used and +also Z-matrix format, see Section \ref{sec:Z-matrix}). The basis +input block is structured like the geometry block (i.e., name, +keyword, \ldots, end) and {\em must} contain basis set information for +every atom type (or tag) in the geometry with which it will be used. +Refer to Sections \ref{sec:basis} and \ref{sec:basis} and Appendix +\ref{sec:knownbasis} for a description of available basis sets and a +discussion of how to define new ones. + +The last line of this sample input file ({\tt task scf optimize}), +tells the program to optimize the molecular geometry by minimization +of the SCF energy. For a description of possible tasks and the format +of the {\tt task} directive, refer to Section \ref{sec:task}. + +If the input is stored in the file \verb+n2.nw+, the command to run +the job on a typical UNIX workstation is as follows; + +\begin{verbatim} + nwchem n2 +\end{verbatim} + +NWChem output is to standard output, and error messages are sent to +both standard output and standard error. + +\subsection{Water Molecule Sample Input File} +\label{sec:realsample} + +A more complex sample problem is the optimization of a positively +charged water molecule at the MP2 level of theory and computation of +frequencies at the optimized geometry. A preliminary SCF geometry +optimization is performed using an inexpensive basis set (STO-3G). +This gives a good starting guess for the geometry and any Hessian +information generated will be used in the next optimization step. +Then the optimization is finished using second-order M{\o}ller-Plesset +perturbation theory and a basis set with polarization functions. The +final task is to calculate the vibrational frequencies. The input +file to accomplish these three tasks is as follows; + +\begin{verbatim} +start h2o_freq + +title; H2O+ frequencies with MP2 and 6-31g** + +geometry units angstrom + O 0.0 0.0 0.0 + H 0.0 0.0 1.0 + H 0.0 1.0 0.0 +end + +charge 1 + +basis "starting basis" + H library sto-3g + O library sto-3g +end + +basis "property basis" + H library 6-31g** + O library 6-31g** +end + +scf + uhf + doublet + print low +end + +stepper + trust 0.5 + convgg 0.01 +end + +set "ao basis" "starting basis" + +task scf optimize + +set "ao basis" "property basis" + +scf + vectors input atomic + print none +end + +set "mp2_grad:print" low + +stepper + convgg 1d-6 +end + +task mp2 optimize + +set "mp2_grad:print" none + +task mp2 freq + +eof +\end{verbatim} + +The {\tt start} directive (Section \ref{sec:start}) tells NWChem that +this run is to be started from the beginning. This directive need not +be at the beginning of the input, but it is commonly placed there. +Existing database or vector files are to be ignored or overwritten. +The entry \verb+h2o_freq+ on the \verb+START+ line is the prefix used +for all files created by the calculation. This convention allows +different jobs to run in the same directory or to share the same +scratch directory (see Section \ref{sec:dirs}) as long as they use +different names in this field. + +As in the first sample problem, the geometry is given in cartesian +coordinates. In this case, however, the units are specified as +{\AA}ngstr{\o}m instead of the default atomic units. The {\tt charge} +directive defines the total charge of the system. This calculation is +to be done on an ion with charge +1. Note that this is a top-level +directive, independent of other input blocks. + +The next two directives are the {\tt basis} directives. The names for +the basis sets are arbitrary, and they may be chosen so that they will +serve as a helpful mnemonic for later reference in subsequent input +directives. + +The multiple lines of the first {\tt scf} directive in the {\tt scf + \ldots end} block specify details about the scf calculation to be +performed. For open-shell systems, the spin multiplicity has to be +specified (using {\tt doublet} in this case), or it defaults to {\tt + singlet}. Unrestricted Hartree-Fock is chosen here (by specifying +the keyword {\tt uhf}), rather than the default high-spin ROHF. This +is necessary for the subsequent MP2 calculation, because only UMP2 is +available for open-shell systems currently (see Section +\ref{sec:functionality}). The print level is set to {\tt low} to +reduce the output from the scf module to a minimum during the geometry +optimization. + +For this calculation, the gradient convergence threshold for the +geometry optimization module {\tt STEPPER} is set to the +relaxed value of $10^{-2}$, rather than the default $10^{-4}$. This is +acceptable because the initial optimization only serves to provide a +starting guess. Increasing the trust radius (using the \verb+trust+ +directive) beyond the default of $0.1$ makes the optimization more +efficient (though less robust in hard to converge cases). + +The final step in setting up the input for the SCF calculation is to +specify that the ``starting basis'' should be used. All molecular +orbital (MO) methods look for the ``ao basis'' in which to expand the +MOs. The \verb+set+ directive specifies that the ``ao basis'' is the +``starting basis''. In the previous example this was not necessary +since we accepted the default name provided by the basis directive +(Section \ref{sec:basis}) which is ``ao basis''. An alternative +approach here which avoids the use of the basis set names and the +\verb+set+ directive is to defer definition of the property basis +until after the first SCF calculation is complete. + +All input up to this point affects only the settings in the run-time +database. The program takes its information from this data base, so +the sequence of directives up to the first \verb+task+ directive is +irrelevant. An exchange of order of the different blocks or +directives would not affect the result. The {\tt task} directive, +however, must be specified last of all in the list of input directives +for a given problem. The {\tt task} directive invokes the program and +directs the code to perform the specified calculation using the +parameters set in the previous directives. In this case, the first +task is an SCF calculation with geometry optimization, specified with +the input {\tt scf} and {\tt optimize}. (See Section \ref{sec:task} +for a list of available tasks and operations.) + +After the completetion of any task, settings in the database are used +in subsequent tasks without change, unless they are overridden by new +input directives. In this example, there are several important +changes between the first task (\verb+task scf optimize+) and the +second task (\verb+task mp2 optimize+). The {\tt "ao basis"} is set +to a better basis (i.e., {\tt "property basis"}) using the \verb+SET+ +directive. The SCF output is completely discarded (as a result of the +{\tt print none} input in the {\tt scf} directive), which means that +no output will be produced unless an error occurs. The SCF starting +guess vectors are reset to be the atomic guess, since the STO3G +vectors are not appropriate (see Section \ref{sec:vectors} for +details on the different possible starting guesses.) + +The convergence threshold for the geometry optimization +module is reset to $1.0d-6$, a value smaller than the default of +$1.0d-4$. The default is appropriate for determination of the +optimized geometry and minimum energy, but a higher accuracy is +required for subsequent computation of the frequencies. The second +{\tt task} directivee invokes an MP2 optimization, instead of the scf +optimization. + +There is currently no input block for the MP2 gradients, so parameters +for this module have to be set in the database via the {\tt set} +directive. Currently only print options are recognized, and in this +example, the \verb+SET+ directive is used to reduce the amount of +output a reasonable minimum. + +Once the MP2 optimization is completed, the geometry obtained in the +calculation is used to perform a frequency calculation. This task is +invoked by the keyword \verb+freq+ on the directive \verb+task mp2 +freq+. The second derivatives of the energy are calculated as +numerical derivatives of analytical gradients. The gradients as such +are not of interest in this case, so the output from the {\tt + mp2\_grad} program is completely discarded using the directive +\verb+set "mp2_grad:print" none+. + +The {\tt eof} directive marks the end of the input to be read. It is +not necessary to specify the end-of-file as an explicit directive at +the actual end of the file. However, using the directive allows the +user to have additional lines in the file that will not be processed +as input. For example, a description of the calculation(s) specified +in the input or notes on the purpose of the task(s), or other +informational comments can be included in the input file in this way. +The {\tt eof} directive can also be used to remove a task (or series +of tasks) from the calculation without actually removing the relevent +input directives from the file. Any lines in the file that occur +after the {\tt eof} directive are ignored by the program. \subsection{Input Format and Syntax for Directives} \label{sec:syntax} -The input format for the directives used for NWChem is similar to that -of UNIX shells, -which is also used in other chemistry packages, most notably GAMESS-UK. An -input line is parsed into whitespace (blanks or tabs) separating tokens -or fields. Any token that contains whitespace must be enclosed in -double quotes in order to be processed correctly. For example, the basis -set with the descriptive name -\verb+modified Dunning DZ+ must appear in a directive as -\verb+"modified Dunning DZ"+, since the name consists of three separate words. -Each logical or physical input line must be no longer than 1023 characters. -Data is read until an end-of-file is detected, or until an \verb+EOF+ -directive is encountered\footnote{The +This section describes the syntax used in the rest of this +documentation for describing the format of directives. Understanding +this in detail should not be necessary since there are many examples. + +The input format for the directives used for NWChem is similar to that +of UNIX shells, which is also used in other chemistry packages, most +notably GAMESS-UK. An input line is parsed into whitespace (blanks or +tabs) separating tokens or fields. Any token that contains whitespace +must be enclosed in double quotes in order to be processed correctly. +For example, the basis set with the descriptive name \verb+modified +Dunning DZ+ must appear in a directive as \verb+"modified Dunning +DZ"+, since the name consists of three separate words. + +A (physical) line in the input file is terminated with a newline +character. A semicolon (\verb+;+) may be also used to indicate the +end of an input line. Thus, each physical line of input may contain +multiple logical lines of input. For example, +\begin{verbatim} + geometry + O 0 0 0 + H 0 1.430 1.107 + H 0 -1.430 1.107 + end +\end{verbatim} +is the same as +\begin{verbatim} + geometry; O 0 0 0; H 0 1.430 1.107; H 0 -1.430 1.107; end +\end{verbatim} +which is one physical input line that corresponds to five logical +input lines. Each logical or physical input line must be no longer +than 1023 characters. Data is read until an end-of-file is detected, +or until an \verb+EOF+ directive is encountered\footnote{The free-format input library does not read past the string \verb+EOF+ (ignoring case) on a line by itself. This is a convenience so that unused input can be left in the same file.}. -Directives consist of a directive name, keywords, and optional input, and -may contain of one line or many. Simple directives -consist of a single -line of input with one or more fields. Compound directives can have -multiple input lines, and must be terminated with an END directive. The -directives START (see Section \ref{sec:start}) and ECHO (see Section \ref{sec:echo}) -are examples of simple directives. The directive GEOMETRY (see Section -\ref{sec:geom}) is -an example of a compound directive. +The comment character is \verb+#+ (the hash or pound symbol). All +characters after \verb+#+ up to the physical end of line are ignored. +Directives consist of a directive name, keywords, and optional input, +and may contain of one line or many. Simple directives consist of a +single line of input with one or more fields. Compound directives can +have multiple input lines, and must be terminated with an END +directive. The directives START (see Section \ref{sec:start}) and +ECHO (see Section \ref{sec:echo}) are examples of simple directives. +The directive GEOMETRY (see Section \ref{sec:geom}) is an example of a +compound directive. Some limited checking for self-consistency of the input is performed -by the input module, but most defaults are imposed by the -application modules at runtime. It is therefore usually impossible -to determine beforehand whether or not all selected options are -consist with each other. +by the input module, but most defaults are imposed by the application +modules at runtime. It is therefore usually impossible to determine +beforehand whether or not all selected options are consist with each +other. -The following notation and conventions are used in the definitions of the directives: +The following notation and conventions are used in the definitions of +the directives: \begin{itemize} \item a string, token, or field is a sequence of ASCII characters (NOTE: if @@ -244,8 +549,8 @@ i.e., If an input item is not prefaced by one of these type names, it is assumed to be of type 'real'. -Using the directive VECTORS as an example, -the generic input line is as follows; +Using the directive \verb+VECTORS+ (Section \ref{sec:vectors}) as an +example \begin{verbatim} VECTORS [input () || \ (project )] \ @@ -253,62 +558,42 @@ the generic input line is as follows; [output ] \end{verbatim} -A complete description of the keywords -and options for the VECTORS directive is given in Section \ref{sec:vectors}. -As an illustration of the general syntax of a directive, this example includes -three optional keywords, as indicated by -the three main sets of square brackets, which enclose the keywords \verb+input+, -\verb+swap+, and \verb+output+. The keyword \verb+input+ allows the user -to specify the source of the molecular orbital vectors. When this keyword -is invoked, there are two mutually exclusive options for specifying the -vectors, as indicated by the \verb+||+ symbol separating the two descriptions; +There are three optional keywords, indicated by the three main sets +of square brackets, which enclose the keywords \verb+input+, +\verb+swap+, and \verb+output+. The keyword \verb+input+ allows the +user to specify the source of the molecular orbital vectors. When +this keyword is invoked, there are two mutually exclusive options for +specifying the vectors, as indicated by the \verb+||+ symbol +separating the two descriptions; \begin{verbatim} -() || \ - (project )] \ - + () || \ + (project ) \ \end{verbatim} -The first option, \verb+()+, allows -the user to specify an ASCII character string for the parameter {\tt -input\_movecs}. -If no entry is specified, the code assumes a -standard source of the vectors with a default of \verb+atomic.movecs+ -(i.e., atomic guess). The second option, -\verb+(project )+, contains the -keyword \verb+project+, which takes two additional string arguments. -When this keyword is used, the vectors will be projected from the basis -\verb+basisname+ in the file \verb+filename+. +The first option, \verb+()+, +allows the user to specify an ASCII character string for the parameter +{\tt input\_movecs}. If no entry is specified, the code assumes a +standard source of the vectors with a default of \verb+atomic+ (i.e., +atomic guess). The second option, {\tt(project + )}, contains the keyword \verb+project+, which +takes two additional string arguments. When this keyword is used, the +vectors in file \verb+filename+ will be projected from the (smaller) +basis \verb+basisname+ into the current AO basis. -The second keyword, \verb+swap+, allows the user to re-order the starting -vector. The optional keyword \verb+[alpha|beta]+ allows the user to swap -the alpha and beta spin orbitals, and specify in pairs the integer numbers -of the vectors to be swapped. As many pairs as the user wishes to have -swapped can be listed for \verb++. +The second keyword, \verb+swap+, allows the user to re-order the +starting vectors. The optional keyword \verb+[alpha|beta]+ allows the +user to swap the alpha and beta spin orbitals, and specify in pairs +the integer numbers of the vectors to be swapped. As many pairs as +the user wishes to have swapped can be listed for {\tt }. -The third keyword, \verb+output+, allows the user to tell the code where -to put the output values of the vectors by specifying an ASCII string -for the parameter {\tt output\_movecs}. If no entry is specified for -this parameter, the default is to write them -back into the input file, \verb+$file\_prefix$+.movecs. - -% The keyword \verb+input+ is the default, -% which means that the directive expects some sort of input to specify the -% vectors. -% The \verb+input+ keyword is followed by two mutually exclusive -% options. One is to specify a standard source of the vectors, using the -% default keyword \verb+"atomic"+ for (atomic guess). The other option is -% to specify a projected set of vectors. This option is obtained by -% specifying -% the keyword \verb+project+ instead of the keyword \verb+''atomic''+. -% The keyword \verb+project+ takes two additional string arguments. -% These arguments indicate that vectors should be obtained by projecting -% from vectors in -% a smaller basis. The \verb+swap+ keyword may be optionally applied to -% the alpha or beta spin orbitals and takes as an argument a list of -% pairs of integers. The \verb+output+ keyword requires a string -% argument, which takes a de fault value constructed from the value of -% the file prefix appended with \verb+".movecs"+. +The third keyword, \verb+output+, allows the user to tell the code +where to store the vectors by specifying an ASCII string for the +parameter {\tt output\_movecs}. If no entry is specified for this +parameter, the default is to write them back into either the user +specified MO vectors input file or, if this is not available, the file +\verb+$file\_prefix$+.movecs. A particular example of the VECTOR directive is shown below. It specifies both the \verb+input+ and \verb+output+ keywords, but does not use the @@ -319,380 +604,52 @@ both the \verb+input+ and \verb+output+ keywords, but does not use the output large_basis.movecs \end{verbatim} -This directive tells the code to generate input vectors by projecting from a -smaller basis named \verb+"small basis"+, which is stored in file -\verb+small_basis.movecs+. The output vectors will be stored in the file - \verb+large_basis.movecs+. +This directive tells the code to generate input vectors by projecting +from vectors in a smaller basis named \verb+"small basis"+, which is +stored in file \verb+small_basis.movecs+. The output vectors will be +stored in the file \verb+large_basis.movecs+. The order of keyed optional entries within a directive should not matter, -unless noted otherwise in the specific instructions for a particular directive. - - -\subsection{Input File Structure} -\label{sec:inputstructure} - -The structure of an input file reflects the internal structure of -NWChem. At the beginning of a calculation NWChem needs to have a number -of start-up directives telling it such things as how much memory to use, -the name of the database, whether it is a new, restarted, or continuing job, -where to put scratch/permanent files, etc.. It is not necessary to put -this information at the top of the input file, however. The first (zeroth) -process in NWChem reads through the {\em entire} input file looking for -the start-up directives. In this pass, all other directives are ignored. - -The start-up directives are - -\begin{itemize} -\item START -\item CONTINUE -\item RESTART -\item SCRATCH{\verb+_+}DIR -\item PERMANENT{\verb+_+}DIR -\item MEMORY -\item ECHO - -% what about TITLE, PRINT/NOPRINT, SET/UNSET, STOP, TASK, and CHARGE? -% these appear in Section 4 Top Level Directives... - -\end{itemize} - -The input values for keywords, etc. for these start-up directives are -broadcast to the other nodes\footnote{Once the database has been opened -process zero can insert data into the database which may be -subsequently accessed directly by all processes.}. - -After the input file has been scanned for the start-up directives, it -is rewound and read sequentially. Input is -processed either by the top-level parser (for the directives listed in -Section \ref{sec:toplevel}; -\verb+TITLE+, \verb+SET+, \ldots) or by the specific computational modules -invoked for the particular case -(e.g., SCF, DFT, \ldots). Any directives that have already been processed -(e.g., \verb+MEMORY+) are ignored. Input is read until a \verb+TASK+ -directive (see Section \ref{sec:task}) is encountered, which specifies the -level of theory to be used to solve the problem and the operations to be -performed. Input processing then stops and the specified task is executed. -The TASK directive in effect defines the end of the input for a given job. -Processing of the input resumes upon the successful completion of the task, -however, and the results of that task can be used as input to a subsequent -problem in the same input file, as defined by a new \verb+TASK+ directive. - -The name of the input file is usually provided as an argument to the execute -command for NWChem. That is, the execute command looks something like the -following; - -\begin{verbatim} -nwchem input_file -\end{verbatim} - -The default name for the input file is \verb+nwchem.nw+. If an input -file name \verb+input_file+ is specified without an extension, the code -assumes a default extension of \verb+input_file.nw+. If the code cannot -locate a file named either \verb+nwchem.nw+ or \verb+input_file.nw+, an -error is reported and execution terminates. The following -subsection presents two input files to illustrate the directive syntax and -input file format for NWChem applications. - -\subsection{Simple N2 Input File} -\label{sec:simplesample} - -An example of a very simple problem that can be run with NWChem is the -SCF geometry optimization on the nitrogen molecule using the Dunning -cc-pvdz basis set. If this problem is run using the defaults in NWChem, -it requires only a very short input file. This input file contains -the bare minimum of information the user must specify in order to run -this type of problem. The file consists of fewer than ten lines of input, -as follows; - -\begin{verbatim} - title; Nitrogen cc-pvdz SCF geometry optimization - geometry - n 0 0 0 - n 0 0 2.1 - end - basis - n library cc-pvdz - end - task scf optimize -\end{verbatim} - -Examining the input file line by line, it can be seen that it contains -only four directives; TITLE, GEOMETRY, BASIS, and TASK. The TITLE directive -is optional, and is used only as a means for the user to more easily identify -outputs from different jobs. The TASK directive tells the code what to -do with the case, and the GEOMETRY and BASIS directives are needed -to define the problem. - -The default for the input geometry is cartesian coordinates. (The Z-matrix -can be selected by setting the keyword \verb+zmat+ on the \verb+GEOMETRY+ -directive (see Section \ref{sec:Z-matrix}). -The default for geometric units is the atomic unit (Bohr). Since no other -option is specified in this directive, the numbers provided on the lines -following the geometry directive are assumed to be in atomic units. -(See Section \ref{sec:geom} -for a complete discussion of available options for the -GEOMTERY directive.) - -The basis input block is structured like the geometry block (i.e., name, keyword, -\ldots, end) and contains basis set information for every atom type in -the geometry. In this case, a default basis set from the library is -chosen. (Refer to Sections \ref{sec:basis} and \ref{sec:basis} and -Appendix \ref{knownbasis} -for a description of available basis sets and a discussion of how to define -new ones.) - -The last line of this sample input file ({\tt task scf optimize}), -tells the program to calculate an optimized self-consistent field for the -N2 molecule as described by the cc-pvdz basis set. -(For a description of possible tasks and the format of the input -for the {\tt task} directive, refer to Section \ref{sec:task}.) - -If the input lines listed here are in the file \verb+n2.nw+, -the command to run the job on -a typical UNIX workstation is as follows; - -\begin{verbatim} - nwchem n2 -\end{verbatim} - -The result obtained in NWChem for this case would be output to the -default output file, with the default selection for output options. - -\subsection{Water Molecule Sample Input File} -\label{sec:realsample} - -A more complex sample problem can be obtained using the geometry of -a positively charged water molecule. This is also a more realistic example -of a NWChem input file. In this problem, a preliminary optimization -with SCF is performed using a relatively cheap basis set (sto-3g). Then -the optimization is finished using second-order M{\o}ller-Plesset -perturbation theory and a basis set with polarization functions. -The final task is to calculate the vibrational frequencies. -The input file to accomplish these three tasks is as follows; - -\begin{verbatim} -start h2o_freq - -title; H2O+ frequencies with MP2 and 6-31g** - -geometry units angstrom - O 0.0 0.0 0.0 - H 0.0 0.0 1.0 - H 0.0 1.0 0.0 -end - -charge 1 - -basis "starting basis" - H library sto-3g - O library sto-3g -end - -basis "property basis" print - H library 6-31g** - O library 6-31g** -end - -scf - uhf - doublet - maxiter 100 - print low -end - -stepper - convge 1.0d-6 -end - -set "ao basis" "starting basis" - -task scf optimize - -set "ao basis" "property basis" - -scf - vectors input atomic - print none -end - -set "mp2_grad:print" low - -stepper - convge 1.0d-10 -end - -task mp2 optimize - -set "mp2_grad:print" none - -task mp2 freq - -eof -\end{verbatim} - -This file beins with a {\tt start} directive, which tells NWChem that this -run is to be started from the beginning. Existing database or vector files -are to be ignored or overwritten. The entry \verb+h2o_freq+ on the -\verb+START+ line gives an internal name for the job and the database. -The name used for each temporary or permanent file -created bby the code that is associated with the -job will also contain the string \verb+h2o_freq+. -This convention allows -different jobs to run in the same directory or to share the same -scratch directory (see Section \ref{sec:dirs}) as long as they -use different names in this field. - -As in the first sample problem, the geometry is given in cartesian -coordinates. In this case, however, the units are specified as -{\AA}ngstr{\o}m instead of the default atomic units. -The {\tt charge} directive defines the total charge of the system. -This calculation is to be done on an ion with charge +1. Note that this is a top-level -directive, independent of other input blocks. - -The next two directives are the {\tt basis} directives. These are compound -directives that define the two basis sets to be used in the calculations. -The names for the basis sets are arbitrary, but they should be -chosen so that they will serve as a helpful mnemonic -for later reference in -subsequent input directives. The basis set name specified on the second -\verb+BASIS+ directive is the only one that will appear in the information -written to the output file, however. - -The multiple lines of the first {\tt scf} directive in the {\tt scf \ldots end} -block specify -details about the scf -calculation to be performed. Unrestricted Hartree-Fock is chosen -here (by specifying the keyword {\tt uhf}), -rather than the default high-spin ROHF. This is necessary for -the subsequent MP2 -calculation, because only UMP2 is available for -open-shell systems currently (refer to Section \ref{sec:function} for -a more complete discussion of code functionality). For open-shell -systems, the spin multiplicity has to be specified (using {\tt doublet} -in this case), -or it defaults to {\tt singlet}. The maximum -number of iterations is set to a high value -(using the directive \verb+maxiter 100+), to allow convergence in -difficult cases. The print level is set to {\tt low} to reduce the -output from the scf module to a minimum. - -For this calculation, the energy convergence threshold for the -geometry optimization module -{\tt stepper} is set to a somewhat relaxed value of $1.0d-6$, rather -than the default $1.0d-8$. This is acceptable -because the initial optimization with scf is not intended to find the -exact minimum. - -The final step in setting up the input for the SCF calculation is to -specify the starting basis as the {\tt"ao basis"} using the -{\tt set} directive. -This basis is the default -basis for all {\em ab initio} calculations. In this case, the {\tt -"ao basis"} is set to the string {\tt "starting basis"}. - -All input up to this point affects only the settings in the run-time database. -The program takes its information from this data base, so the -sequence of directives up to the first \verb+task+ directive is irrelevant. -An exchange of order of the -different blocks or -directives would not affect the result. -The {\tt task} directive, however, must be specified last of all in the -list of input directives for -a given problem. The {\tt task} directive invokes the program and -directs the code to perform the specified calculation -using the parameters set in the previous directives. In this case, the -first task is an SCF calculation with geometry optimization, specified -with the input {\tt scf} and {\tt optimize}. (See Section -\ref{sec:task} for a list of available -tasks and operations.) - -After the optimization task is done, settings in the database are used -in subsequent tasks without change, unless they are overridden by new -input directives. -In this example, there are several important changes between the first -task (\verb+task scf optimize+) and the second task (\verb+task mp2 optimize+). -The {\tt "ao basis"} is set to a -better basis (i.e., {\tt "property basis"}) using the \verb+SET+ directive, -for the final set of -calculations. The scf output is completely -discarded (as a result of the {\tt print none} input in the {\tt scf} directive), -which means that no output will be producedd unless an error occurs. -The convergence threshold for the geometry optimization module is reset -to $1.0d-10$, a value much smaller than the default of $1.0d-8$, and -the second {\tt task} directivee invokes an MP2 optimization, instead of -the scf optimization. - -The starting guess for the MP2 optimization task is to be the previous -SCF calculation -on the atoms, however. The input this second optimization -must be specified with a new {\tt scf} directive block, or the MP2 calculation -would use the existing MO vectors, by default. Since the basis -has been changed in this task, -the differences will be too large to make a projection of the old vectors -a reasonable representation on the new basis. (See Section \ref{sec:vectors} -for details on the different possible starting guesses.) - -There is currently no input block for the MP2 gradients, so parameters -for this module have to be set in the database via the {\tt set} -directive. Currently only print options are recognized, and in this -example, the \verb+SET+ directive is used to -reduce the amount of output a reasonable minimum. - -Once the MP2 optimization is completed, the geometry obtained in the -calculation is used to perform a frequency calculation. This task is -invoked by the keyword \verb+freq+ on the directive \verb+task mp2 freq+. -The second -derivatives of the energy are calculated as numerical derivatives of -analytical gradients. The gradients as such are not of interest -in this case, so -the output from the {\tt mp2\_grad} program is completely discarded -using the directive \verb+set "mp2_grad:print" none+. - -The {\tt eof} directive marks the end of the input to be read. It is not -necessary to specify the end-of-file as an explicit directive at the -actual end of the file. However, using the directive allows the user to -have additional lines in the file that will not be processed as input. For -example, a description of the calculation(s) specified in the input or -notes on the purpose of the task(s), or other informational comments can be -included in the input file in this way. The {\tt eof} directive can also -be used to remove a task (or series of tasks) from the calculation without -actually removing the relevent input directives from the file. Any lines in the file -that occur after the {\tt eof} directive are ignored by -the program. - - +unless noted otherwise in the specific instructions for a particular +directive. \section{NWChem Architecture} \label{sec:arch} -NWChem consists of independent modules that perform the various functions -of the code. These functions include input processing, creation of basis -sets and geometry sets, and solution operations using different theoretical -models. Different modules communicate through a database, using an approach -similar to that of the GAMESS dumpfile or the Gaussian checkpoint file. -This allows the modules to share data, or to share access to files containing -data. +As noted above, NWChem consists of independent modules that perform +the various functions of the code. Examples of modules include the +input parser, SCF energy, SCF analytic gradient, and DFT energy. The +independent NWChem modules can only share data through a disk-resident +database, which is a similiar to the GAMESS dumpfile or the Gaussian +checkpoint file. This allows the modules to share data, or to share +access to files containing data. -It is not necessary for the user to be intimately familiar with the contents -of the database in order to run NWChem. Nor is it necessary to fully -understand the theory and operation of the solution options in the code. -However, a nodding acquaintance with the structure of the database and -the functionality of the code would probably help clarify the logic behind -the input requirements of the code, in understanding the usefulness of the -defaults, and in determining which models and operation are most appropriate -for a given application. Section \ref{sec:database} gives a general -description of the database, and Section \ref{sec:functionality} describes -the theorical models and operations currently available in the code. +It is not necessary for the user to be intimately familiar with the +contents of the database in order to run NWChem. However, a nodding +acquaintance with the design of the code will help in clarifying the +logic behind the input requirements, especially when restarting jobs +or performing multiple tasks within one job. Section +\ref{sec:database} gives a general description of the database. + +As described above (Section \ref{sec:inputstructure}), when a job +begins any start-up directives are processed by the main program and +then the input module is invoked. Each input directive usually +results in one or more entries being made in the database. When a +\verb+TASK+ directive is encountered, control is passed to the +appropriate module which extracts relevant data from the database and +any associated files. Upon completion each module will store +significant results in the database, and may also modify other +database entries in order to modify the behaviour of subsequent +computations. \subsection{Database Structure} -\label{database} +\label{sec:database} Data is shared between modules of NWChem by means of the database. There are three main types of information stored in the data base; (1) arrays of data, (2) names of files that contain data, and (3) objects. Arrays are stored directly in the database, and contain the following information; - \begin{enumerate} \item the name of the array, which is a string of ASCII characters (e.g., \verb+"reference energies"+) @@ -701,53 +658,32 @@ information; \item the number (N) of data items in the array \item the N items of data of the specified type \end{enumerate} +A scalar is stored as an array of unit length. -Some of the arrays in the database are defined permanently within the code, and -cannot be changed except by altering the code itself. Many other arrays in the -database are defined in response to user-specified directives, and -others are created as part -of a calculation. The user can directly specify some arrays by means of -the input, using the \verb+SET+ directive (see Section \ref{sec:set}). -For example, to store a (64-bit precision) three-element real array -with the name \verb+"reference energies"+ in the database, the directive is -as follows; - +From the NWChem input deck it is possible to enter data directly into +the database using the \verb+SET+ directive (see Section +\ref{sec:set}). For example, to store a (64-bit precision) +three-element real array with the name \verb+"reference energies"+ in +the database, the directive is as follows; \begin{verbatim} - set "reference energies" real 0 1 -76.2 + set "reference energies" 0.0 1.0 -76.2 \end{verbatim} +NWChem automatically determines the data to be real, counts the number +of elements in the array, and enters the array into the database. -The code counts the number of elements in the array automatically when this input -directive is processed, and this information is entered -into the array in the database. +Much of the data stored in the database is internally managed by +NWChem and should not be modified by the user. However, other data, +including some NWChem input options, may be freely modified. -When an item in the database references a file containing data rather -than the data array itself, the structure of the entry is -similar to an ordinary array. It contains everything except -the actual data, and consists of the following -three items; - -\begin{enumerate} -\item the name of the file, which is a string of ASCII characters -\item the type of the data in the file (i.e., real, integer, logical, -or character), and -\item the number (N) of data items in the file -\end{enumerate} - -Objects in the database are in general more complex than simple arrays -or file references to arrays. -An object consists of a set of related data that different routines in -the code must read, manipulate, or write. Currently, the code has two -main objects; the basis sets and the geometry set. Sections -\ref{sec:geom}, \ref{sec:basis}, and \ref{sec:ecp} -present a complete discussion of the input to describe these objects. For -the purposes of this discussion, these objects can be understood simply -as related packets of information. These packets might be a description of a -basis set, or the history of a geometry optimization. A given object is -built up following an internally consistent naming convention and set of -structural specifications and array ordering for that object. For example, -a geometry -database with the default name \verb+"geometry"+ contains the following -entries; +Objects are built in the database by storing the associated data as +multiple entries using an internally consistent naming convention. +This data is exclusively managed by the subroutines (or methods) that +are associated with the object. Currently, the code has two main +objects; basis sets and geometries. ECPs are stored in the same +fashion as basis sets. Sections \ref{sec:geom}, \ref{sec:basis}, and +\ref{sec:ecp} present a complete discussion of the input to describe +these objects. For example, a geometry with the name +\verb+"test geom"+ contains the following entries; \begin{verbatim} Contents of RTDB h2o.db @@ -755,27 +691,25 @@ entries; Entry Type[nelem] --------------------------- ---------------------- - geometry:geometry:efield double[3] - geometry:geometry:coords double[9] - geometry:names char[10] - geometry:geometry:ncenter int[1] + geometry:test geom:efield double[3] + geometry:test geom:coords double[9] + geometry:names char[10] + geometry:test geom:ncenter int[1] geometry:ngeom int[1] - geometry:geometry:charges double[3] - geometry:geometry:tags char[6] + geometry:test geom:charges double[3] + geometry:test geom:tags char[6] ... \end{verbatim} - -Using this approach, multiple instances of the geometry object can be -stored under different names in the same database without confusion. -For example, if a user needs to do calculations considering alternative -geomteries for the water molecule, an input file can be constructed that -allows more than one geometry object to exist in the database. The -{\tt geometry} directive can be used to define an alternative geometry -object in the database, under a name different from the geometry object -for water already in the code. For example, the input directive to define -a geometry object in the database with the name -\verb+"test water geometry"+ can be specified as follows; +Using this approach, multiple instances of objects may be stored with +different names in the same database without confusion. For example, +if a user needs to do calculations considering alternative geomteries +for the water molecule, an input file can be constructed that provides +all of the geometries, storing them in the database. The {\tt + GEOMETRY} directive (Section \ref{sec:geom}) permits geometries to +be named (the default name is \verb+geometry+). For example, the +input directive to define a geometry object in the database with the +name \verb+"test water geometry"+ can be specified as follows; \begin{verbatim} geometry "test water geometry" @@ -785,72 +719,51 @@ a geometry object in the database with the name end \end{verbatim} -The geometry object contains more information than merely -the numerical input specified in the directive, of course. The geometry directive -allows the user to specify different values for the x,y,z coordinates of -the atoms (or centers), and identify that object under a unique name, but -the other information in the geometry oject remains unchanged for all -specifically named objects. (Refer to Section \ref{sec:geom} -for a complete description of the {\tt geometry} -directive.) +The geometry object contains more information than merely the +numerical input specified in the directive, of course. The geometry +directive allows the user to specify different values for the x,y,z +coordinates of the atoms (or centers), and identify that object under +a unique name, but the other information in the geometry oject remains +unchanged for all specifically named objects. (Refer to Section +\ref{sec:geom} for a complete description of the {\tt GEOMETRY} +directive.) -Unless a specific name is defined for the geometry object in the database -(such as the name \verb+"test water geometry"+ shown in the example), -the object in the database is -assigned the default name of \verb+geometry+. This is the geometry object name -that computational modules -will look for when executing a calculation. -The {\tt set} directive can be used in the input to force a -module (or modules) to look for a geometry object with -a different name than \verb+geometry+ for a particular task. For example, -to use the x,y,z coordinates specified for \verb+"my water geometry"+ -rather than those of the default geometry object \verb+geometry+, the -input line is as follows; +Unless a specific name is defined for the geometry object in the +database (such as the name \verb+"test water geometry"+ shown in the +example), the object in the database is assigned the default name of +\verb+geometry+. This is the geometry object name that computational +modules will look for when executing a calculation. The {\tt SET} +directive can be used in the input to force a module (or modules) to +look for a geometry object with a different name than \verb+geometry+ +for a particular task. For example, to specify use of the +\verb+"test water geometry"+ example above one would specify \begin{verbatim} - set geometry "my water geometry" + set geometry "test water geometry" \end{verbatim} -When the code for is asked to load a geometry object -with name \verb+geometry+, during the calculation, it will first check for -a \verb+SET+ directive on the geometry object name before actually attempting -to load the geometry. The basis set object -functions in an identical fashion -when using the default name \verb+"ao basis"+, and it is intended that all such -objects will do so. (Note: the naming conventions and internal mechanisms for -associating data with specific modules or tasks is expected to change in -the future, but the directive for specifying names should remain the same.) +NWChem will automatically check for such indirections when loading +geometries. The basis set object functions in an identical fashion, +using the default name \verb+"ao basis"+, and it is intended that all +future such objects will do so. (Note: the naming conventions and +internal mechanisms for associating data with specific modules or +tasks is expected to change in the future, but the directive for +specifying names should remain the same.) -\fussy +\subsection{Persistence of data and restart} -The database is persistent and nearly all input is permanently stored. -This makes the input for restart jobs very simple since very little -data must be provided. It also makes the behavior of successive -restart jobs {\em identical} to that of multiple tasks within one job. -However, sometimes this persistence is undesirable, and it is necessary to -return an NWChem module to its default (input-free) behavior. In such a case, the -\verb+UNSET+ directive (see Section \ref{sec:unset}) -can be used to delete all -database entries associated with a given module. +The database is persistent, meaning that all input data and results +that are not destroyed in the course of execution are permanently +stored. These data are therefore available to subsequent tasks or +jobs. This makes the input for restart jobs very simple since only +new or changed data must be provided. It also makes the behavior of +successive restart jobs {\em identical} to that of multiple tasks +within one job. + +Sometimes, however, this persistence is undesirable, and it is +necessary to return an NWChem module to its default (input-free) +behavior. In such a case, the \verb+UNSET+ directive (see Section +\ref{sec:unset}) can be used to delete all database entries associated +with a given module (including both inputs and outputs). -\subsection{Functionality} -\label{sec:functionality} - -Current functionality includes: -\begin{itemize} -\item Self Consistent Field or Hartree Fock energy and analytic - gradients (RHF, UHF, high-spin ROHF) -\item Gaussian Density Functional Theory (DFT) energy and analytic - gradients with many local and - non-local exchange-correlation potentials -\item MP2 energy using direct or semi-direct algorithms, or using the - resolution of the identity integral approximation. Analytic - gradients are under development. -\item Geometry Optimization (Minimization and Transition State). -\item Second-derivatives by numerical difference of gradients. -\item Generation of the electron density file for the {\em Insight} - graphical program. -\item Interface to the natural bond orbital package. -\end{itemize} - diff --git a/doc/user/knownbas.tex b/doc/user/knownbas.tex index 2e7ab62c71..86de0571ee 100644 --- a/doc/user/knownbas.tex +++ b/doc/user/knownbas.tex @@ -1,4 +1,4 @@ -\label{knownbasis} +\label{sec:knownbasis} Basis sets were obtained (8/12/96) from the Extensible Computational Chemistry Environment (ECCE) Basis Set Database, as developed and distributed diff --git a/doc/user/mcscf.tex b/doc/user/mcscf.tex index 8ea2e96759..db0146d807 100644 --- a/doc/user/mcscf.tex +++ b/doc/user/mcscf.tex @@ -1,9 +1,7 @@ \label{sec:mcscf} -\Large -***** -It would be really nice if someone could supply a '25 words or less' -description of the Multiconfiguration SCF module right here.******** -\normalsize +The NWChem MCSCF module can currently perform complete active space +SCF (CASSCF) calculations with at most 20 active orbitals and about +500 basis functions. The Multiconfiguration SCF program is invoked in NWChem by specifying the keyword \verb+mcscf+ on the compound directive, diff --git a/doc/user/scf.tex b/doc/user/scf.tex index 7c0d33c981..acc8646f7d 100644 --- a/doc/user/scf.tex +++ b/doc/user/scf.tex @@ -1,13 +1,9 @@ -\label{SCF} -\Large -*** -It would be really nice if someone could supply a '25-words-or-less' -description of the SCF program right here. -*** -\normalsize +\label{SCF} -The SCF program is invoked in NWChem -by specifying the keyword \verb+scf+ on the compound directive, +The NWChem self-consistent field (SCF) module computes closed-shell +restricted Hartree-Fock (RHF), restricted high-spin open-shell +Hartree-Fock (ROHF) and spin-unrestricted Hatree-FOck (UHF) +wavefunctions. \begin{verbatim} SCF @@ -52,7 +48,7 @@ total charge on the system and the nuclear charges of the specific atoms (which are by default their atomic numbers adjusted for the presence of ECPs, unless specified explicitly by input on the \verb+GEOMETRY+ directive -- see Section -\ref{sec:geometry}). The total charge on the system is zero by default, +\ref{sec:geom}). The total charge on the system is zero by default, unless specified at some value by input on the \verb+CHARGE+ directive -- see Section \ref{sec:toplevel}). @@ -1170,6 +1166,7 @@ Section \ref{sec:nrswitch} above.) \subsection{Printing Information from the SCF Module} +\label{sec:scfprint} All output from the SCF module is controlled using the \verb+PRINT+ directive described in Section \ref{sec:printcontrol}. The following diff --git a/doc/user/top-level.tex b/doc/user/top-level.tex index d3067fa29b..18e775def8 100644 --- a/doc/user/top-level.tex +++ b/doc/user/top-level.tex @@ -1,138 +1,90 @@ \label{sec:toplevel} -Top-level directives are directives that affect all modules in the code. In -general, they provide the user with the means to start a calculation, -allocate resources for the calculation, tell the code what to do with -the problem, when and how to write output describing the problem, and how -to stop a calculation. As the first step in the execution of a given case, -NWChem scans the entire input file looking for start-up directives. The -input file is then rewound and processed sequentially, and each directive -is processed in the order it is encountered. Top-level directives are -parsed by the top-level parser. With the exception of the {\tt task} -directive, the top-level directives are processed only once, the first time -they are encountered in the input stream. Subsequent occurances of the -same directive will be ignored. +Top-level directives are directives that potentially affect all +modules in the code. Some specify molecular properties (e.g., total +charge) or other data that should apply to all subsequent +calculations. However, most top-level directives provide the user +with the means to manage the resources for a calculation and to start +computations. As the first step in the execution of a job, NWChem +scans the entire input file looking for start-up directives which +NWChem must process before all other input. The input file is then +rewound and processed sequentially, and each directive is processed in +the order it is encountered. In this second pass start-up directives +are ignored. -The following subsections describe each of these -directives in detail, noting all keywords, options, required input, and -defaults. +The following subsections describe each of these directives in detail, +noting all keywords, options, required input, and defaults. \subsection{START, CONTINUE and RESTART} \label{sec:start} -Every calculation with NWChem requires either a {\tt start}, or a -{\tt continue}, or a {\tt restart} directive. If one of these three -directives is not specified explicitly, the code will infer one based on -the input for the other directives and the contents of the database. -When allowing NWChem to infer the start-up directive, the user must be -quite certain that the contents of the database will result in the -desired inference. It is usually more prudent to specify the directive -explicitly, using the following format; - -% A \verb+START+, \verb+CONTINUE+ or \verb+RESTART+ directive is -% optional but care must be taken if no directive is presented since the -% behaviour of the code will vary depending upon the existence of the -% database. +A {\tt START}, or {\tt CONTINUE}, or {\tt RESTART} directive is +optional. If one of these three directives is not specified +explicitly, the code will infer one based on upon the name of the +input file and the availability of the database. When allowing NWChem +to infer the start-up directive, the user must be quite certain that +the contents of the database will result in the desired inference. It +is usually more prudent to specify the directive explicitly, using the +following format. \begin{verbatim} (RESTART || CONTINUE || START) [] \ [rtdb ] \end{verbatim} -The \verb+START+ directive indicates that the calculation is one -in which the database is to be created. Any relevent information that -already exists in the database is destroyed. The string {\tt file\_prefix} -will be used as the prefix when naming any files created in the -course of the calculation. -The user can also specify a unique name for the database itself, using -the keyword {\tt rtdb}. When this keyword is entered, the -string {\tt rtdb\_file\_name} is used as the database name. If the keyword -{\tt rtbd} is omitted, the name of the database defaults to +The \verb+START+ directive indicates that the calculation is one in +which the database is to be created. Any relevent information that +already exists in a previous database of the same name is destroyed. +The string {\tt file\_prefix} will be used as the prefix when naming +any files created in the course of the calculation. The user can also +specify a unique name for the database itself, using the keyword {\tt + rtdb}. When this keyword is entered, the string {\tt + rtdb\_file\_name} is used as the database name. If the keyword {\tt + rtbd} is omitted, the name of the database defaults to \verb+.db+ in the directory for permanent files. If a calculation is to start from a previous calcultion and go on using the existing database, the \verb+RESTART+ directive or the -\verb+CONTINUE+ directive must be used. In such a case, the database -\verb+file_prefix+ must already exist. If a database with this name -does not exist, use of either of these directives will generate an error. -This also means that the name {\tt file\_prefix} usually should not be -changed when restarting a calculation. If the name {\tt file\_prefix} is -changed on the \verb+RESTART+ or \verb+CONTINUE+ directive, -NWChem will not be able to -find needed files automatically when going on with the calculation. -The user will have to explicitly name the file(s) to be accessed by each -directive that needs to look at something in the old database. +\verb+CONTINUE+ directive must be used. In such a case, the previous +database must already exist. The {\tt file\_prefix} usually should +not be changed when restarting a calculation otherwise NWChem will not +be able to find necessary files automatically when going on with the +calculation. -The \verb+RESTART+ and \verb+CONTINUE+ directives are very nearly identical -in their effect, except for one very important difference. When the -\verb+CONTINUE+ directive is used, no new input data is parsed before -carrying out the task stored in the database file. When the \verb+RESTART+ -directive is used, however, the input file is read and acted upon up to -the next \verb+TASK+ directive. This can result in the overwriting of -existing information in the database, and may result in the old task in -the database being discarded. -% indicate that an existing database should be used and -% an error will result if it does not exist. All files created by -% NWChem are by default prefixed with the string specified on the -% directive, which defaults to the basename of the input file (i.e., the -% input file name with the directory and any trailing \verb+.*+ stripped -% off). Note that if you change the file prefix in a restart job, -% NWChem will be unable to locate most files automatically. The -% \verb+RTDB+ keyword permits specification of the name of the database -% which otherwise defaults -% -% The difference between \verb+CONTINUE+ and \verb+RESTART+ is subtle -% but useful. \verb+CONTINUE+ will not parse any new input data before -% it does the task stored in the database file. \verb+RESTART+ will -% parse new input data and overwrite any existing data if appropriate. -The \verb+CONTINUE+ directive can be viewed as telling the code to -go ahead and finish the old task, then do any new tasks that are -specified by the input. The \verb+RESTART+ directive can -be viewed as telling the code to take instruction before continuing. The -new instructions may or may not require it to finish the old task before -it goes on and does the new task(s) specified. +There are two ways to restart a previous calculation. Most commonly +the previous calculation completed (with or without an error +condition) and it is desired to perform a new task or restart the +previous one, perhaps with some input changes. In these instances, +the \verb+RESTART+ directive should be used. This reuses the previous +database and associated files, and reads the input file for new input +and task information. -% restart with information available, new input is -% also parsed, and do the tasks outlined in the input so the old task -% may be discarded. \verb+CONTINUE+ implies restart the old task and -% \verb+RESTART+ implies restart with possibly a new task. +Less commonly, if the last task of the previous job terminated in such +a way that enables it to be continued (e.g., from an automatic +checkpoint in the molecular dynamics program) with no additional +input, then the \verb+CONTINUE+ directive should be used. This reuses +the previous database and associated files, continues the previous +task, and then reads the input file for additional input and task +information. -% For example, in a SCF energy calculation where you underestimated the -% time necessary and the job was killed by the scheduling software. -% You could use -% either the \verb+CONTINUE+ or the \verb+RESTART+ directive with the -% appropriate file prefix and database specifiction to restart the job. -% If, On the other hand if you wanted to finish the task and do an -% additional SCF energy computation with a new geometry you could use -% \verb+CONTINUE+ directive, input the new geometry and use a single -% task directive for the second energy point. Again, the difference is -% subtle but useful. +In summary, the \verb+CONTINUE+ directive tells NWChem to finish the +previous task, and then perform any new tasks that are specified by +the input. The \verb+RESTART+ directive immediately looks for new +input and task information. If the input file does not contain a \verb+START+ or a \verb+CONTINUE+ or a -\verb+RESTART+ directive, NWChem assumes the following defaults; - +\verb+RESTART+ directive, then \begin{itemize} - \item the name of the database for the calculation is {\tt file\_prefix.db} - \item the file prefix is {\tt file\_prefix} + \item the file prefix is the name of the input file with any + trailing \verb+.nw+ removed, and + \item the name of the database for the calculation is {\tt + file\_prefix.db} \end{itemize} - -If the database -with name {\tt file\_prefix.db} does {\it not} exist, then the calculation -is carried out as if a \verb+START+ directive had been encountered. -If the database with name {\tt file\_prefix.db} {\it does} exist, then -the calculation -is performed as if a \verb+RESTART+ directive had been encountered. That is, -the input file is parsed up to the first \verb+TASK+ directive, and that -task is executed using the contents of the database. NWChem cannot infer -a \verb+CONTINUE+ directive, but if the input makes no changes to the -database before the first \verb+TASK+ directive, the effect is the same as -if a \verb+CONTINUE+ directive had been specified. - -% It is not possible to infer a /verb+CONTINUE+ directive. -% \item if the default database exists, then the job is assumed to be -% a restart, otherwise it is assumed to be a startup. -% \item continue is never assumed. -% \end{itemize} +If the database with name {\tt file\_prefix.db} does {\it not} exist, +then the calculation is carried out as if a \verb+START+ directive had +been encountered. If the database with name {\tt file\_prefix.db} +{\it does} exist, then the calculation is performed as if a +\verb+RESTART+ directive had been encountered. For example, if the NWChem input file \verb+water.nw+ does not contain a \verb+START+, \verb+RESTART+, or \verb+CONTINUE+ directive, the default @@ -141,14 +93,14 @@ a \verb+START+, \verb+RESTART+, or \verb+CONTINUE+ directive, the default the code behaves as if the input file contained the directive, \begin{verbatim} - start water rtdb water.db + start water \end{verbatim} -If the database \verb+water.db+ {\it does} exist already, +If the database \verb+water.db+ {\it does} exist, the code behaves as if the input file contained the directive, \begin{verbatim} - restart water rtdb water.db + restart water \end{verbatim} @@ -157,43 +109,34 @@ the code behaves as if the input file contained the directive, % This is a startup directive (section \ref{sec:inputstructure}). -This is a startup directive that allows the user to specify the directory -location of permanent and scratch files created by NWChem. The programming -model and the local disk I/O access model used by the code are both installation -dependent, and the user should refer to the Programmer's Manual for a -complete discussion of these topics. -% NWChem distinguishes between permanent (or persistent) files and scratch (or -% temporary) files, and allows the user the option of putting them in -% different locations. -In most installations, however, permanent and scratch files are all -written to the current directory by default. This is at the discretion -of the specific installation, however, and may be different on different -machines. What constitutes 'local' disk space may also differ from -machine to machine. +These are startup directives that allow the user to specify the +directory location of permanent and scratch files created by NWChem. +NWChem distinguishes between permanent (or persistent) files and +scratch (or temporary) files, and allows the user the option of +putting them in different locations. In most installations, however, +permanent and scratch files are all written to the current directory +by default. This is at the discretion of the specific installation +and may be different on different machines. What constitutes 'local' +disk space may also differ from machine to machine. -% The default location of the scratch and permanent directories is -% installation specific, but most commonly both permanent and scratch -% files default to the current directory. - -For example, on the IBM SP and workstation clusters, machine/process -specific names -must be specified for both local and shared file systems. -On the KSR it is useful to specify scratch file directories with -automated striping across processors with round-robin allocation. SMP -clusters have both requirements. The anticipated usage of the EMSL -IBM SP has NWChem executing in \verb+scratch+ with all files -being created there by default. Files to be saved for restart -{\em must} be either explicitly redirected or copied. This has the +For example, on the IBM SP and workstation clusters, machine/process +specific names must be specified for both local and shared file +systems. On the KSR it is useful to specify scratch file directories +with automated striping across processors with round-robin allocation. +SMP clusters have both requirements. The anticipated usage of the +EMSL IBM SP has NWChem executing in \verb+scratch+ with all files +being created there by default. Files to be saved for restart {\em + must} be either explicitly redirected or copied. This has the advantages of minimizing very expensive network traffic on shared-file systems and also reduces the amount of data stored in the limited -shared-file space. However, this manual copying fails if the job crashes or -runs out of time, so it may be preferable to automatically store -{\em small} restart files directly to a persistent file space. +shared-file space. However, this manual copying fails if the job +crashes or runs out of time, so it may be preferable to automatically +store {\em small} restart files directly to a persistent file space. The \verb+SCRATCH_DIR+ and \verb+PERMANENT_DIR+ directives have -identical format and capability, and enable the user to specify a single -directory for all processes, or different directories for different -processes. The general form of the directive is as follows; +identical format and capability, and enable the user to specify a +single directory for all processes, or different directories for +different processes. The general form of the directive is as follows; \begin{verbatim} (PERMANENT_DIR || SCRATCH_DIR) [(|):] \ @@ -202,27 +145,24 @@ processes. The general form of the directive is as follows; \end{verbatim} Directories are extracted from the user input by executing the -following steps +following steps in order \begin{enumerate} \item Look for a directory qualified by the process number of the invoking process. \item If there is a list of directories qualified by the name of the host machine (as returned by \verb+util_hostname()+), then use round-robin allocation from the list for processes executing on the - given host. (NOTE: the user must know the logical I/O access model -for the current installation to determine the process numbering procedure, -and should refer to the NWChem Programmer's Manual for a complete -discussion of the hostname utility.) + given host. \item If there is a list of directories unqualified by any hostname or process ID, then use round-robin allocation from this list. \end{enumerate} -If directory allocation directive(s) are not specified in the -input file, or if no match is found to the directory names specified by -input using these directives, -then the above steps are executed using the installation specific -defaults. If the code cannot find a valid directory name based on the -input specified in either the directive(s) or the system defaults, files are -automatically written to the current working directory (\verb+"."+). +If directory allocation directive(s) are not specified in the input +file, or if no match is found to the directory names specified by +input using these directives, then the above steps are executed using +the installation specific defaults. If the code cannot find a valid +directory name based on the input specified in either the directive(s) +or the system defaults, files are automatically written to the current +working directory (\verb+"."+). The following is a list of examples of specific allocations of scratch directory locations: @@ -255,18 +195,13 @@ given list of directories; \subsection{MEMORY} -% This is a startup directive (section \ref{sec:inputstructure}). - -This is a start-up directive that allows the user to allocate the amount -of available memory that NWChem can have for a particular calculation. -If this directive is not specified explicitly in the input stream, memory -is allocated according to installation -dependent defaults. These generally should suffice for most calculations, -since in many cases they represent the total amount of memory available on -the machine. -The general form of the -directive is as follows; - +This is a start-up directive that allows the user to specify the +amount of memory that NWChem can use for the job. If this directive +is not specified, memory is allocated according to installation +dependent defaults. These generally should suffice for most +calculations, since the defaults usually correspond the total amount +of memory available on the machine. The general form of the directive +is as follows; \begin{verbatim} MEMORY [[total] ] \ @@ -278,16 +213,12 @@ directive is as follows; [(nohardfail||hardfail)] \ \end{verbatim} -The input for -this directive assumes that there are three distinct regions of -memory: stack, heap, and global. Stack and heap are node-private, -while the global region on all processors is used to provide -globally-shared memory. NWChem +There are three distinct regions of memory: stack, heap, and global. +Stack and heap are node-private, while the union of the global region +on all processors is used to provide globally-shared memory. NWChem recognizes the following memory units; - \begin{itemize} -\item \verb+real+ -\item \verb+double+ (synonyms) +\item \verb+real+ and \verb+double+ (synonyms) \item \verb+integer+ \item \verb+byte+ \item \verb+kb+ (kilobytes) @@ -295,23 +226,21 @@ recognizes the following memory units; \item \verb+mw+ (megawords, 64 bit word) \end{itemize} -In most cases the user needs to specify only the total memory limit, and -allow the limits on each category to be determined from a default -partitioning. (This is specified currently as 10\% for heap, 10\% for stack, -and 80\% for -global.) Alternatively, the keywords \verb+stack+, \verb+heap+, and +In most cases the user needs to specify only the total memory limit, +and allow the limits on each category to be determined from a default +partitioning (currently 25\% heap, 25\% stack, and 50\% global). +Alternatively, the keywords \verb+stack+, \verb+heap+, and \verb+global+ can be used to define specific allocations for each of -these categories. If the user sets only one of the stack, heap, or global -limits by input, the limits for the other two categories are obtained -by partitioning the remainder of the total memory available in proportion -to the weight of those two categories in the default memory -partitioning. If two of the category limits are given, the third is -obtained simply by subtracting the two given limits from the total limit -(which may have been specified or may be a default value). If all three -category limits are specified, they determine the total memory allocated. -However, if the -total memory is also specified, it must be larger than the sum of all -three categories. The code +these categories. If the user sets only one of the stack, heap, or +global limits by input, the limits for the other two categories are +obtained by partitioning the remainder of the total memory available +in proportion to the weight of those two categories in the default +memory partitioning. If two of the category limits are given, the +third is obtained by subtracting the two given limits from the total +limit (which may have been specified or may be a default value). If +all three category limits are specified, they determine the total +memory allocated. However, if the total memory is also specified, it +must be larger than the sum of all three categories. The code attempts to check for inconsistent memory specifications. The following specifications all provide eight megabytes (assuming 64 @@ -332,48 +261,43 @@ partitioning as well; memory stack 2 heap 2 global 4 mb \end{verbatim} -The optional keywords \verb+VERIFY+ and \verb+NOVERIFY+ -in the directive give the user the option -of enabling or disabling automatic -detection of corruption of allocated memory. The default is \verb+VERIFY+, -which enables the feature. This incurs a small overhead, which can be -eliminated by -specifying \verb+NOVERIFY+. +The optional keywords \verb+VERIFY+ and \verb+NOVERIFY+ in the +directive give the user the option of enabling or disabling automatic +detection of corruption of allocated memory. The default is +\verb+VERIFY+, which enables the feature. This incurs a small +overhead, which can be eliminated by specifying \verb+NOVERIFY+. -The keywords \verb+HARDFAIL+ and \verb+NOHARDFAIL+ give the user the +The keywords \verb+HARDFAIL+ and \verb+NOHARDFAIL+ give the user the option of forcing an internal fatal error to be generated by the local memory management routines if any memory operation fails. The default -in the code is \verb+NOHARDFAIL+, which allows the code to continue past -the memory operation failure, and perhaps generate a more meaningful error -message before terminating the calculation. This can be useful when -poorly coded applications do not check the return status of memory -management routines. - +in the code is \verb+NOHARDFAIL+, which allows the code to continue +past the memory operation failure, and perhaps generate a more +meaningful error message before terminating the calculation. This can +be useful when poorly coded applications do not check the return +status of memory management routines. When specifying the specific memory allocations using the keywords \verb+stack+, \verb+heap+, and \verb+global+ in the \verb+MEMORY+ -directive, the user should be aware that some of the distinctions between -these categories of memory have been blurred in their actual implementation -in the code. The memory allocator -(MA) allocates both the heap and the stack from a single memory region -of size {\em heap+stack} without enforcing the partition. The heap -vs. stack partition is meaningful only to applications -developers, and can be ignored by most users. Further complicating matters, -the global array (GA) toolkit is allocated from within the MA space on -distributed memory machines, while on shared-memory machines it is +directive, the user should be aware that some of the distinctions +between these categories of memory have been blurred in their actual +implementation in the code. The memory allocator (MA) allocates both +the heap and the stack from a single memory region of size {\em + heap+stack} without enforcing the partition. The heap vs. stack +partition is meaningful only to applications developers, and can be +ignored by most users. Further complicating matters, the global array +(GA) toolkit is allocated from within the MA space on distributed +memory machines, while on shared-memory machines it is separate\footnote{This is because on true shared-memory machines there -is no choice but to allocate GAs from within a shared-memory segment, -which is mangaged differently by the operating system.}. On -distributed memory platforms, the MA region is actually the total size of -{\tt stack+heap+global}. All three types of memory allocation compete -for the same pool of memory, with no limits except on the total -available memory. This relaxation of the memory category definitions -usually benefits the user since it can allow allocation requests to -succeed where a stricter memory model would cause the directive to fail. -These implementation characteristics must be kept in mind when -reading output from the program relating to memory usage, however, -particularly when interpreting output of jobs that have -failed due to memory limitations. + is no choice but to allocate GAs from within a shared-memory + segment, which is mangaged differently by the operating system.}. +On distributed memory platforms, the MA region is actually the total +size of {\tt stack+heap+global}. All three types of memory allocation +compete for the same pool of memory, with no limits except on the +total available memory. This relaxation of the memory category +definitions usually benefits the user since it can allow allocation +requests to succeed where a stricter memory model would cause the +directive to fail. These implementation characteristics must be kept +in mind when reading output from the program relating to memory usage. Current standard defaults for various platforms are listed in Table \ref{tbl:default-memory-limits}. On machines for which individual @@ -404,12 +328,11 @@ Sun & 48 \\ \subsection{ECHO} \label{sec:echo} -% This is a startup directive (section \ref{sec:inputstructure}). -This directive is provided as a convenient means to include a listing of -the input file in the output of a calculation. It causes the entire input -file to be printed to Fortran unit six. It has no keywords, arguments, or -options, and consists of the single line, +This start-up directive is provided as a convenient means to include a +listing of the input file in the output of a calculation. It causes +the entire input file to be printed to Fortran unit six. It has no +keywords, arguments, or options, and consists of the single line, \begin{verbatim} ECHO @@ -438,53 +361,54 @@ line following the \verb+TITLE+ directive. For example, This is the title of my first NWChem job \end{verbatim} -Alternatively, the character string can be specified on the same line -as the directive keyword. This option is obtained by placing a semicolon -after the directive keyword. In such case, the previous example would -appear as; +Alternatively, since semicolon may be used to end an input line +(Section \ref{sec:syntax}), we may write \begin{verbatim} - title; This is the title of my first NWChem job + title; This is the title of my first NWChem job \end{verbatim} The title is stored in the database and will be used in all subsequent -tasks/jobs unless redefined in the input. +tasks/jobs until redefined in the input. \subsection{PRINT and NOPRINT} \label{sec:printcontrol} -The \verb+PRINT+ and \verb+NOPRINT+ directives are top level directives -that allow the user to define how much information to write to the output -files. These two directives are special in that -{\em all} modules are supposed to recognize them. (If one does -not, this is probably an error, and should be reported to the developers. -Send email to \verb+nwchem-support@emsl+.) The directive has -a standard form. Each module can control both the print +The \verb+PRINT+ and \verb+NOPRINT+ directives allow the user to +control how much output is generated. These two directives are +special in that {\em all} modules are supposed to recognize +them.\footnote{If one does not, this is probably an error, and should + be reported to the developers. Send email to + \verb+nwchem-support@emsl+.} Each module can control both the print level and the printing of individual items. The standard form of the \verb+PRINT+ directive is as follows; \begin{verbatim} PRINT [none | low | medium | high | debug] \ [] + + NOPRINT \end{verbatim} +The default print level is medium. -The form for the \verb+NOPRINT+ directive is essentially the same, except that -there is no need for the optional keywords controlling the amount of -information to be printed. The \verb+NOPRINT+ directive has the form, +Everything that is printed by NWChem has a print threshold associated +with it. If this threshold is lower than the print level requested by +the user, then the output is generated. For instance, the threshold +for printing the SCF energy at convergence is \verb+low+ (Section +\ref{sec:scfprint}), meaning that if the user print level is +\verb+low+ or higher, then it will be printed. The print level is +intended to be a convenient way contolling how verbose NWChem is. +Setting print to \verb+high+ might be helpful to diagnose convergence +problems, whereas \verb+low+ might be better for geometry +optimizations which will perform many steps in which you are not +interested. A print level of \verb+debug+ can generate huge amounts +of output and is best avoided. -\begin{verbatim} - NOPRINT [] -\end{verbatim} +In addition, it is possible to enable/disable the printing of items by +name regardless of the print level. The list of items that each +module can print is documented with the rest of that modules input. -The items that are to be printed (or not printed, in the case of the -\verb+NOPRINT+ directive) can be listed explicitly in the input, or the -users can rely on the defaults. There -is a specific set of items that each module can control the output for -by means of the \verb+PRINT/NOPRINT+ directives. -% could we tell the user what these are? Or do we want to make them guess? -The top level of the code recognizes 7 specific items that will be printed -(or not printed) according to the input specified for these two directives. -These items are as follows; +The top level of the code recognizes these items: \begin{tabbing} Very\_long\_descriptive\_name \= Print level space \= \kill Name \> Print Level \> Description \\ @@ -498,60 +422,22 @@ These items are as follows; ``version'' \> debug \> Prints version of all compiled routines \\ \end{tabbing} -The \verb+PRINT+ directive can be used to assign a print threshold to -each of the items that the given module controls. The print threshold is -specified with the optional keywords \verb+none+, \verb+low+, \verb+medium+, -\verb+high+, and \verb+debug+. The keyword applies to all items listed -in the \verb+list_of_names+ following that keyword. If no items are listed -explicitly, the keyword applies to all print items in the module. -The keywords are interpreted as follows; - -\begin{itemize} -\item \verb+none+ -- none of the items will be printed except for those -specifically listed in the directive -\item \verb+low+ -- all named items will be printed with a 'low' print level -\item \verb+medium+ -- all named items will be printed with a 'medium' print -level, as well as all items that have a 'low' print level -\item \verb+high+ -- all named items will be printed with a 'high' print -level, as well as all items that have 'low' or 'medium' print level -\item \verb+debug+ -- all named items will be printed with a special debug print level -\end{itemize} - -If the \verb+PRINT+ directive appears without a list of names, then the -selected print level applies to all items that the module can print. -Multiple \verb+PRINT+ directives can be used within a given module. Naming -specific strings with a particular print level in a directive will force the -items to be printed, regardless of the print level specified in any other -\verb+PRINT+ directive(s) that apply to all items in the module. - - -% Items that are under standard print control are -% assigned a print threshold which is one of none, low, medium, high and -% debug. -% An example will help. If the print level is medium (which is the -% default) all items with a print threshold less than or equal to medium -% (i.e., low or medium) will be printed. In addition, the printing of -% items can be explicitly enabled or disabled by name. - -The following example shows how a print directive for the top level process -can be used to limit printout to only essential information. +The following example shows how a print directive for the top level +process can be used to limit printout to only essential information. The directive is, \begin{verbatim} - print none 'ma stats' rtdb + print none "ma stats" rtdb \end{verbatim} -This directive instructs the NWChem driver routine to print nothing, except -for the memory usage statistics stored in \verb+'ma stats'+ and the entire -contents of the database at the end of the job. +This directive instructs the NWChem main program to print nothing, +except for the memory usage statistics (\verb+ma stats+) and +the names of all items stored in the database at the end of the job. -%Look in the documentation of each module to learn about -The Programmer's Manual lists the printout item names specific to each -module in the code. -Currently, the print level is local to each module -and defaults to 'medium' within each module. It is also possible to -change the implementation so that a module inherits the default print level +Currently, the print level is local to each module and defaults to +medium at the beginning of each module. It is also possible to change +the implementation so that a module inherits the default print level of its calling layer. (Users should send their preferences for these defaults via email to \verb+nwchem-support@emsl+, for consideration in future releases of the code.) @@ -560,134 +446,103 @@ future releases of the code.) \label{sec:set} The \verb+SET+ directive allows the user to enter data directly into the -database. It also permits the user to substitute new objects for named -objects in the database. The format of the directive is -as follows; +database (see Section \ref{sec:database} for details of the database). \begin{verbatim} SET [] <$type$ data> \end{verbatim} -The \verb++ is the name of some array or object that exists in -the database. This must be specified explicitly; there is no default. -The second item allows the user to define a string specifying the type -of data in the array \verb++. The data type can be explicitly -specified as \verb+integer+, -\verb+real+, \verb+double+, \verb+logical+, or \verb+string+. If -this item is omitted from the directive, the value for \verb+type+ is -inferred from the data type of the {\em first} element of -\verb+<$type$ data>+. In such a case, floating-point data entered in -\verb+<$type$ data>+ using this directive must include either an -exponent or decimal point to ensure that the correct default type will -be assumed. The correct default type will be inferred for logical values -if logical-true values are specified as \verb+.true.+, \verb+true+, or -\verb+t+, and logical-false values are entered as \verb+.false.+, -\verb+false+, or \verb+f+. +The \verb++ is the name of some array or object to be entered +into the database. This must be specified explicitly; there is no +default. -The main purpose of the \verb+SET+ directive is to allow the user to -define indirect links between different objects or arrays in the database. -Indirection is a very useful -feature in that it allows the user to have multiple objects, such as -basis sets and geometry objects, in the same database under unique -names. These objects can then be assigned to the default basis set or -object names for different tasks, at the -user's discretion. For example, if the user wants the \verb+GEOMETRY+ -directive to load a different geometry object for two different tasks in -the course of a calculation, it is necessary only to assign the appropriate -object name, using the \verb+SET+ directive, for each task. To use two -different geometry objects for a calculation with the water molecule, one -task might have the directive, +The second, optional, item allows the user to define a string +specifying the type of data in the array \verb++. The data type +can be explicitly specified as \verb+integer+, \verb+real+, +\verb+double+, \verb+logical+, or \verb+string+. If this item is +omitted from the directive, the value for \verb+type+ is inferred from +the data type of the {\em first} data element. In such a case, +floating-point data entered using this directive must include either +an exponent or decimal point to ensure that the correct default type +will be assumed. The correct default type will be inferred for +logical values if logical-true values are specified as \verb+.true.+, +\verb+true+, or \verb+t+, and logical-false values are entered as +\verb+.false.+, \verb+false+, or \verb+f+. + +The \verb+SET+ directive is useful for providing indirection by +associating the name of a basis set or geometry with the standard +names (\verb+ao basis+ and \verb+geometry+ respectively) that are used +by NWChem. See one of the sample inputs (Section \ref{sec:realsample}) for +an example of this with basis sets. Another example using multiple geometries + follows. \begin{verbatim} -SET geometry "my water geometry" -\end{verbatim} - -A subsequent task might contain the directive, - -\begin{verbatim} -SET geometry "my other water geometry" -\end{verbatim} - -Similar indirection can be used when different basis set objects -are specified in the data base. For example, two different basis -sets representing the molecular orbitals could be specified in the input -using the following directives; - -\begin{verbatim} - basis "trial basis" - o library sto-3g - h library sto-3g + title; Ar dimer BSSE corrected MP2 interaction energy + geometry "Ar+Ar" + Ar1 0 0 0 + Ar2 0 0 2 end - basis "production basis" - o library cc-pvqz - h library cc-pvqz + geometry "Ar+ghost" + Ar1 0 0 0 + Bq2 0 0 2 end + + basis + Ar1 library aug-cc-pvdz + Ar2 library aug-cc-pvdz + Bq2 library Ar aug-cc-pvdz + end + + set geometry "Ar+Ar" + task mp2 + + scf; vectors atomic; end + + set geometry "Ar+ghost" + task mp2 \end{verbatim} -The code expects the basis set to have the name \verb+"ao basis"+. -The \verb+SET+ directive can be used to assign the basis set named -\verb+"trial basis"+ to the \verb+"ao basis"+, using the input line, +The above input performs MP2 energy calculations on an Argon dimer and +on the Argon atom in the presence of the ``ghost'' basis of the other +atom at the same geometry. -\begin{verbatim} - set "ao basis" "trial basis" -\end{verbatim} - -In a subsequent task in the same input stream, the basis can be redefined -using the directive - -\begin{verbatim} - set "ao basis" "production basis" -\end{verbatim} - -The \verb+SET+ directive can be used as an indirect means of -supplying input to modules under development. It can also allow the more -intrepid users of the code to access modules that do not yet have -input routines. Some of the parameters used to tune the -integral evaluation routines may be adjusted in this fashion. -For example, the directive -to set the variable \verb+int:cando_sp+ to a -logical-false value is as follows, -% The other common circumstance in which \verb+SET+ is used is for -% modules under development. \verb+SET+ can be used to provide a -% rudimentary input mechanism for options that do not yet have more -% friendly input routines, or for options that are very infrequently -% exercised. For instance, some of the parameters - -\begin{verbatim} - set int:cando_sp logical false -\end{verbatim} +The \verb+SET+ directive can also be used as an indirect means of +supplying input to modules under development, that do not yet have +user friendly input. \subsection{UNSET} \label{sec:unset} This directive gives the user a way to delete simple entries from the -database. It is especially useful as a means to undo the assignment -of an array that has been specified using the \verb+SET+ directive. -The form of the \verb+UNSET+ directive is as follows; +database. \begin{verbatim} UNSET [*] \end{verbatim} -This directive cannot be used with complex objects such as geometries and -basis sets, however. The input string \verb+name+ must be an array, not -an object name. A wildcard (*) specified at the end of the -string \verb+name+ will cause {\em all} -entries beginning with that name to be deleted. This is very useful as a -way to reset modules to their default behaviour, since modules typically store -information in the database with names that begin with -\verb+module:+. +This directive cannot be used with complex objects such as geometries +and basis sets. The input string \verb+name+ must be an array, not an +object name. A wildcard (*) specified at the end of the string +\verb+name+ will cause {\em all} entries beginning with that string to +be deleted. This is very useful as a way to reset modules to their +default behaviour, since modules typically store information in the +database with names that begin with \verb+module:+. -An example illustrating how to reverse the above example of the -\verb+SET+ directive setting the logical variable \verb+int:cando_sp+ -to the value 'false' is as follows; +The following example makes an entry in the database using \verb+SET+ +and then immediately deletes it using \verb+UNSET+. \begin{verbatim} - unset int:cando_sp + set mylist 1 2 3 4 + unset mylist \end{verbatim} -This will cause \verb+int:cando_sp+ to resume its default value. +This example restores the SCF program to its default behaviour by +deleting all database entries beginning with \verb+scf:+ + +\begin{verbatim} + unset scf:* +\end{verbatim} \subsection{STOP} @@ -702,31 +557,39 @@ verifying input. \subsection{TASK} \label{sec:task} -The \verb+TASK+ directive is used to tell the code what to do with the input. -The input directives are parsed -sequentially until a \verb+TASK+ directive is encountered, as described -in Section \ref{sec:inputstructure} At that -point, the calculation or operation specified in the \verb+TASK+ directive -is performed. When that task is completed, -the code looks for additional input to process until the next -\verb+TASK+ directive is encountered, which is then executed. This -process continues until the end of the input file, or an \verb+EOF+ -directive is encountered. The code expects the last directive before the -end-of-file to be a \verb+TASK+ directive. If it not, a warning message -is printed. Since the +The \verb+TASK+ directive is used to tell the code what to do with the +input. The input directives are parsed sequentially until a +\verb+TASK+ directive is encountered, as described in Section +\ref{sec:inputstructure}. At that point, the calculation or operation +specified in the \verb+TASK+ directive is performed. When that task +is completed, the code looks for additional input to process until the +next \verb+TASK+ directive is encountered, which is then executed. +This process continues to the end of the input file. NWChem expects +the last directive before the end-of-file to be a \verb+TASK+ +directive. If it is not, a warning message is printed. Since the database is persistent, multiple tasks within one job behave {\em exactly} the same as multiple restart jobs with the same sequence of input. -In NWChem, a 'task' is some operation or calculation performed on the -database using some particular theory or module. There are three forms -of the the \verb+TASK+ directive, corresponding to the three main uses -of the code. One is used to perform most elctronic structure calculations. -Another is used to perform tasks such as printing the contents of the -database, or performing propety evaluations. The third is used to -execute UNIX commands on machines having a Bourne shell. The input options, -keywords, and defaults for each of these three forms for the \verb+TASK+ -directive are discussed in the following subsections. +There are three main forms of the the \verb+TASK+ directive. One is +used to perform most elctronic structure and molecular dynamics +calculations. The second form is used to perform tasks such as +printing the contents of the database, or performing simple property +evaluations. The third is used to execute UNIX commands on machines +having a Bourne shell. Additional forms will be added in the near +future to accomodate mixed molecular-mechanics and quantum-mechanics +(MM/QM) calculations. + +By default, the program terminates when a task does not complete +successfully. The keyword \verb+IGNORE+ can be used to prevent this +and is recognized by all forms of the \verb+TASK+ directive. When a +\verb+TASK+ directive includes the keyword \verb+IGNORE+, task failure +results in only a warning message being printed, and code execution +continues with the next task. + +The input options, keywords, and defaults for each of +these three forms for the \verb+TASK+ directive are discussed in the +following subsections. \subsubsection{TASK Directive for Electronic Structure Calculations} @@ -739,11 +602,7 @@ it has the following form; The string \verb+theory+ specifies the level of theory to be used in the calculations for this task. NWChem currently supports eleven different -options for this function. the following list briefly describes the -choices and gives the string input to identify each selection. - -\begin{itemize} -\item \verb+theory+ \newline +options: \begin{itemize} \item \verb+SCF+ --- Hartree-Fock \item \verb+DFT+ --- Density functional theory for molecules @@ -755,18 +614,15 @@ choices and gives the string input to identify each selection. \item \verb+MCSCF+ --- Multiconfiguration SCF \item \verb+SELCI+ --- Selected configuration interaction with perturbation correction - \item \verb+MD+ --- Molecular dynamics simulation using NWARGOS - \item \verb+MD_IDEAZ+ --- Molecular dynamics simulation using IDEAZ + \item \verb+MD+ --- Classical molecular dynamics simulation using NWARGOS + \item \verb+MD_IDEAZ+ --- Classical molecular dynamics simulation + using IDEAZ \end{itemize} - The string \verb+operation+ is used to specify the calculation that will be performed in the task. The default operation is a single point energy evaluation. The following list gives the selection of operations currently available in NWChem, and the string entry for \verb+operation+ for each one. - - -\item \verb+operation+ \newline \begin{itemize} \item \verb+ENERGY+ --- single point energy evaluation \item \verb+GRADIENT+ --- evaluate the derivative of the energy with respect to\ @@ -779,56 +635,46 @@ available in NWChem, and the string entry for \verb+operation+ for each one. \item \verb+DYNAMICS+ --- molecular dynamics using NWArgos. \item \verb+THERMODYNAMICS+ --- multiconfiguration thermodynamic integration using NWArgos. -\end{itemize} \end{itemize} -The user should be aware that some of these operations require -computation of derivatives of the energy. -%Shall we tell them which ones, or was everyone born knowing this? -If analytical derivatives are not available, they must be -computed numerically, which can be very expensive. - -Here are some examples of the \verb+TASK+ directive, to illustrate -the input needed to specify particular calculations with the code. -To perform a single point energy evaluation using Hartree-Fock theory, -the directive is very simple, since the energy evaluation is the default -for the string \verb+operation+. The input line is simply, +The user should be aware that some of these operations (gradient, +optimization, dynamics, thermodynamics) require computation of +derivatives of the energy with respect to the molecular coordinates. +If analytical derivatives are not available (Section +\ref{sec:functionality}), they must be computed numerically, which can +be very expensive. +Here are some examples of the \verb+TASK+ directive, to illustrate the +input needed to specify particular calculations with the code. To +perform a single point energy evaluation using any level of theory the +directive is very simple, since the energy evaluation is the default +for the string \verb+operation+. For an SCF energy calculation the +input line is simply, \begin{verbatim} task scf \end{verbatim} - -Alternatively, in case the string \verb+operation+ could have -been reset to some other value by an earlier \verb+TASK+ directive, the -current \verb+TASK+ directive can be specified as - +or equivalently, \begin{verbatim} task scf energy \end{verbatim} Similarly, to perform a geometry optimization using density functional theory, the \verb+TASK+ directive is - \begin{verbatim} task dft optimize \end{verbatim} - -By default, the program terminates when a task does not complete -successfully. The keyword \verb+IGNORE+ can be used to prevent this. -When a \verb+TASK+ directive includes the keyword \verb+IGNORE+, -task failure results in only a warning message being printed, and -code execution continues with the next task. +The keyword \verb+IGNORE+ allows execution to continue even if the +task fails, as discussed above. \subsubsection{TASK Directive for Special Operations} -This form of the \verb+TASK+ directive is used in instances where -the task to be performed does not fit the model of the previous -version (e.g., print the contents of the -database) or if the operation has not yet been implemented in a -fashion that applies to a wide range of theories (e.g., property -evaluation). Instead of requiring \verb+theory+ and \verb+operation+ -as input, the directive needs only a string identifying the task. The form of the +This form of the \verb+TASK+ directive is used in instances where the +task to be performed does not fit the model of the previous version or +if the operation has not yet been implemented in a fashion that +applies to a wide range of theories (e.g., property evaluation). +Instead of requiring \verb+theory+ and \verb+operation+ as input, the +directive needs only a string identifying the task. The form of the directive in such cases is as follows; \begin{verbatim} @@ -840,7 +686,6 @@ below, with the corresponding string entry for \verb+task+. \begin{itemize} \item \verb+RTDBPRINT+ --- print the contents of the database - \item \verb+MD+ --- molecular dynamics using Ideaz \item \verb+CPHF+ --- invoke the CPHF module \item \verb+PROPERTY+ --- miscellaneous property calculations \end{itemize} @@ -850,27 +695,25 @@ execution to continue after a task has failed. \subsubsection{TASK Directive for the Bourne Shell} -This form of the \verb+TASK+ directive is supported only on machines -with a fully UNIX-style operating system. This directive causes specified -processes to be executed using the Bourne shell. The final form of this -version of the task directive is as follows; +This form of the \verb+TASK+ directive is supported only on machines +with a fully UNIX-style operating system. This directive causes +specified processes to be executed using the Bourne shell. This form +of the task directive is as follows; \begin{verbatim} TASK shell [(|all)] [ignore] \end{verbatim} The keyword \verb+SHELL+ is required for this directive. It specifies -that the task defined by the string \verb+command+ will be executed in -the Bourne shell. The user can also specify which processor(s) will be -executed in the Bourne shell, by entering values for \verb+processor+ on -the directive. The default is to execute only processor zero in the -Bourne shell. A range of processors may be specified, using Fortran -triple notation. Alternatively, all processors can be specified simply -by entering the keyword -\verb+all+. -The input entered for \verb+command+ must form a single string, and comprise -valid UNIX command(s). If the string includes white space, it must be -enclosed in double quotes. +that the given command will be executed in the Bourne shell. The user +can also specify which process(es) will be execute this command by +entering values for \verb+processor+ on the directive. The default is +for only process zero to execute the command. A range of processors +may be specified, using Fortran triplet notation. Alternatively, all +processes can be specified simply by entering the keyword \verb+all+. +The input entered for \verb+command+ must form a single string, and +comprise valid UNIX command(s). If the string includes white space, +it must be enclosed in double quotes. For example, the \verb+TASK+ directive to tell process zero to copy the molecular orbitals file to a backup location can be input as follows; @@ -893,11 +736,11 @@ contents of the current directory is as follows; task shell 0:10:1 "/bin/rm -f *" \end{verbatim} -Note that NWChem's ability to quote -special input characters is {\em very} limited when compared with that -of the Bourne shell. When executing all -but the simplest commands, it is usually much easier to put the shell -script in a file and execute the file from within NWChem. +Note that NWChem's ability to quote special input characters is {\em + very} limited when compared with that of the Bourne shell. When +executing all but the simplest commands, it is usually much easier to +put the shell script in a file and execute the file from within +NWChem. \subsection{CHARGE} \label{sec:charge} @@ -912,6 +755,4 @@ For example, to run a doubly charged cation charge 2 \end{verbatim} -The default charge is zero. If this is the desired charge configuration -for a given task, this directive can be omitted. - +The default charge is zero. diff --git a/doc/user/user.tex b/doc/user/user.tex index 1d11e96344..f736536eb0 100644 --- a/doc/user/user.tex +++ b/doc/user/user.tex @@ -5,6 +5,8 @@ \newcommand{\nwchemversion}{2.0} \newcommand{\nwchemyear}{1996} +\input{psfig} + \begin{document} \title{\bf\Large NWChem User Documentation, Alpha Release \nwchemversion} @@ -24,6 +26,9 @@ \section{Introduction} \input{intro.tex} +\subsection{Functionality} +\input{functionality.tex} + \section{Top-level directives} \input{top-level} diff --git a/doc/user/zmat1.eps b/doc/user/zmat1.eps new file mode 100644 index 0000000000..93534cae8c --- /dev/null +++ b/doc/user/zmat1.eps @@ -0,0 +1,527 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: zmat1.fig +%%Creator: fig2dev Version 3.1 Patchlevel 1 +%%CreationDate: Mon Jan 27 12:33:28 1997 +%%For: d3g681@fermi (Robert J Harrison) +%%Orientation: Landscape +%%BoundingBox: 0 0 201 509 +%%Pages: 0 +%%BeginSetup +%%IncludeFeature: *PageSize Letter +%%EndSetup +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {} def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +-9.0 -18.0 translate + 90 rotate +1 -1 scale +.9 .9 scale % to make patterns same scale as in xfig + +% This junk string is used by the show operators +/PATsstr 1 string def +/PATawidthshow { % cx cy cchar rx ry string + % Loop over each character in the string + { % cx cy cchar rx ry char + % Show the character + dup % cx cy cchar rx ry char char + PATsstr dup 0 4 -1 roll put % cx cy cchar rx ry char (char) + false charpath % cx cy cchar rx ry char + /clip load PATdraw + % Move past the character (charpath modified the + % current point) + currentpoint % cx cy cchar rx ry char x y + newpath + moveto % cx cy cchar rx ry char + % Reposition by cx,cy if the character in the string is cchar + 3 index eq { % cx cy cchar rx ry + 4 index 4 index rmoveto + } if + % Reposition all characters by rx ry + 2 copy rmoveto % cx cy cchar rx ry + } forall + pop pop pop pop pop % - + currentpoint + newpath + moveto +} bind def +/PATcg { + 7 dict dup begin + /lw currentlinewidth def + /lc currentlinecap def + /lj currentlinejoin def + /ml currentmiterlimit def + /ds [ currentdash ] def + /cc [ currentrgbcolor ] def + /cm matrix currentmatrix def + end +} bind def +% PATdraw - calculates the boundaries of the object and +% fills it with the current pattern +/PATdraw { % proc + save exch + PATpcalc % proc nw nh px py + 5 -1 roll exec % nw nh px py + newpath + PATfill % - + restore +} bind def +% PATfill - performs the tiling for the shape +/PATfill { % nw nh px py PATfill - + PATDict /CurrentPattern get dup begin + setfont + % Set the coordinate system to Pattern Space + PatternGState PATsg + % Set the color for uncolored pattezns + PaintType 2 eq { PATDict /PColor get PATsc } if + % Create the string for showing + 3 index string % nw nh px py str + % Loop for each of the pattern sources + 0 1 Multi 1 sub { % nw nh px py str source + % Move to the starting location + 3 index 3 index % nw nh px py str source px py + moveto % nw nh px py str source + % For multiple sources, set the appropriate color + Multi 1 ne { dup PC exch get PATsc } if + % Set the appropriate string for the source + 0 1 7 index 1 sub { 2 index exch 2 index put } for pop + % Loop over the number of vertical cells + 3 index % nw nh px py str nh + { % nw nh px py str + currentpoint % nw nh px py str cx cy + 2 index show % nw nh px py str cx cy + YStep add moveto % nw nh px py str + } repeat % nw nh px py str + } for + 5 { pop } repeat + end +} bind def + +% PATkshow - kshow with the current pattezn +/PATkshow { % proc string + exch bind % string proc + 1 index 0 get % string proc char + % Loop over all but the last character in the string + 0 1 4 index length 2 sub { + % string proc char idx + % Find the n+1th character in the string + 3 index exch 1 add get % string proe char char+1 + exch 2 copy % strinq proc char+1 char char+1 char + % Now show the nth character + PATsstr dup 0 4 -1 roll put % string proc chr+1 chr chr+1 (chr) + false charpath % string proc char+1 char char+1 + /clip load PATdraw + % Move past the character (charpath modified the current point) + currentpoint newpath moveto + % Execute the user proc (should consume char and char+1) + mark 3 1 roll % string proc char+1 mark char char+1 + 4 index exec % string proc char+1 mark... + cleartomark % string proc char+1 + } for + % Now display the last character + PATsstr dup 0 4 -1 roll put % string proc (char+1) + false charpath % string proc + /clip load PATdraw + neewath + pop pop % - +} bind def +% PATmp - the makepattern equivalent +/PATmp { % patdict patmtx PATmp patinstance + exch dup length 7 add % We will add 6 new entries plus 1 FID + dict copy % Create a new dictionary + begin + % Matrix to install when painting the pattern + TilingType PATtcalc + /PatternGState PATcg def + PatternGState /cm 3 -1 roll put + % Check for multi pattern sources (Level 1 fast color patterns) + currentdict /Multi known not { /Multi 1 def } if + % Font dictionary definitions + /FontType 3 def + % Create a dummy encoding vector + /Encoding 256 array def + 3 string 0 1 255 { + Encoding exch dup 3 index cvs cvn put } for pop + /FontMatrix matrix def + /FontBBox BBox def + /BuildChar { + mark 3 1 roll % mark dict char + exch begin + Multi 1 ne {PaintData exch get}{pop} ifelse % mark [paintdata] + PaintType 2 eq Multi 1 ne or + { XStep 0 FontBBox aload pop setcachedevice } + { XStep 0 setcharwidth } ifelse + currentdict % mark [paintdata] dict + /PaintProc load % mark [paintdata] dict paintproc + end + gsave + false PATredef exec true PATredef + grestore + cleartomark % - + } bind def + currentdict + end % newdict + /foo exch % /foo newlict + definefont % newfont +} bind def +% PATpcalc - calculates the starting point and width/height +% of the tile fill for the shape +/PATpcalc { % - PATpcalc nw nh px py + PATDict /CurrentPattern get begin + gsave + % Set up the coordinate system to Pattern Space + % and lock down pattern + PatternGState /cm get setmatrix + BBox aload pop pop pop translate + % Determine the bounding box of the shape + pathbbox % llx lly urx ury + grestore + % Determine (nw, nh) the # of cells to paint width and height + PatHeight div ceiling % llx lly urx qh + 4 1 roll % qh llx lly urx + PatWidth div ceiling % qh llx lly qw + 4 1 roll % qw qh llx lly + PatHeight div floor % qw qh llx ph + 4 1 roll % ph qw qh llx + PatWidth div floor % ph qw qh pw + 4 1 roll % pw ph qw qh + 2 index sub cvi abs % pw ph qs qh-ph + exch 3 index sub cvi abs exch % pw ph nw=qw-pw nh=qh-ph + % Determine the starting point of the pattern fill + %(px, py) + 4 2 roll % nw nh pw ph + PatHeight mul % nw nh pw py + exch % nw nh py pw + PatWidth mul exch % nw nh px py + end +} bind def + +% Save the original routines so that we can use them later on +/oldfill /fill load def +/oldeofill /eofill load def +/oldstroke /stroke load def +/oldshow /show load def +/oldashow /ashow load def +/oldwidthshow /widthshow load def +/oldawidthshow /awidthshow load def +/oldkshow /kshow load def + +% These defs are necessary so that subsequent procs don't bind in +% the originals +/fill { oldfill } bind def +/eofill { oldeofill } bind def +/stroke { oldstroke } bind def +/show { oldshow } bind def +/ashow { oldashow } bind def +/widthshow { oldwidthshow } bind def +/awidthshow { oldawidthshow } bind def +/kshow { oldkshow } bind def +/PATredef { + userdict begin + { + /fill { /clip load PATdraw newpath } bind def + /eofill { /eoclip load PATdraw newpath } bind def + /stroke { PATstroke } bind def + /show { 0 0 null 0 0 6 -1 roll PATawidthshow } bind def + /ashow { 0 0 null 6 3 roll PATawidthshow } + bind def + /widthshow { 0 0 3 -1 roll PATawidthshow } + bind def + /awidthshow { PATawidthshow } bind def + /kshow { PATkshow } bind def + } { + /fill { oldfill } bind def + /eofill { oldeofill } bind def + /stroke { oldstroke } bind def + /show { oldshow } bind def + /ashow { oldashow } bind def + /widthshow { oldwidthshow } bind def + /awidthshow { oldawidthshow } bind def + /kshow { oldkshow } bind def + } ifelse + end +} bind def +false PATredef +% Conditionally define setcmykcolor if not available +/setcmykcolor where { pop } { + /setcmykcolor { + 1 sub 4 1 roll + 3 { + 3 index add neg dup 0 lt { pop 0 } if 3 1 roll + } repeat + setrgbcolor - pop + } bind def +} ifelse +/PATsc { % colorarray + aload length % c1 ... cn length + dup 1 eq { pop setgray } { 3 eq { setrgbcolor } { setcmykcolor + } ifelse } ifelse +} bind def +/PATsg { % dict + begin + lw setlinewidth + lc setlinecap + lj setlinejoin + ml setmiterlimit + ds aload pop setdash + cc aload pop setrgbcolor + cm setmatrix + end +} bind def + +/PATDict 3 dict def +/PATsp { + true PATredef + PATDict begin + /CurrentPattern exch def + % If it's an uncolored pattern, save the color + CurrentPattern /PaintType get 2 eq { + /PColor exch def + } if + /CColor [ currentrgbcolor ] def + end +} bind def +% PATstroke - stroke with the current pattern +/PATstroke { + countdictstack + save + mark + { + currentpoint strokepath moveto + PATpcalc % proc nw nh px py + clip newpath PATfill + } stopped { + (*** PATstroke Warning: Path is too complex, stroking + with gray) = + cleartomark + restore + countdictstack exch sub dup 0 gt + { { end } repeat } { pop } ifelse + gsave 0.5 setgray oldstroke grestore + } { pop restore pop } ifelse + newpath +} bind def +/PATtcalc { % modmtx tilingtype PATtcalc tilematrix + % Note: tiling types 2 and 3 are not supported + gsave + exch concat % tilingtype + matrix currentmatrix exch % cmtx tilingtype + % Tiling type 1 and 3: constant spacing + 2 ne { + % Distort the pattern so that it occupies + % an integral number of device pixels + dup 4 get exch dup 5 get exch % tx ty cmtx + XStep 0 dtransform + round exch round exch % tx ty cmtx dx.x dx.y + XStep div exch XStep div exch % tx ty cmtx a b + 0 YStep dtransform + round exch round exch % tx ty cmtx a b dy.x dy.y + YStep div exch YStep div exch % tx ty cmtx a b c d + 7 -3 roll astore % { a b c d tx ty } + } if + grestore +} bind def +/PATusp { + false PATredef + PATDict begin + CColor PATsc + end +} bind def + +% vertical sawtooth lines +11 dict begin +/PaintType 1 def +/PatternType 1 def +/TilingType 1 def +/BBox [0 0 1 1] def +/XStep 1 def +/YStep 1 def +/PatWidth 1 def +/PatHeight 1 def +/Multi 2 def +/PaintData [ + { clippath } bind + { 16 32 true [ 16 0 0 -32 0 32 ] + {<400020001000080004000200010000800100020004000800 + 100020004000800040002000100008000400020001000080 + 01000200040008001000200040008000>} + imagemask } bind +] def +/PaintProc { + pop + exec fill +} def +currentdict +end +/P22 exch def +1.1111 1.1111 scale %restore scale + +/clp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/l {lineto} bind def +/m {moveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def + /DrawEllipse { + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y tr xrad yrad sc 0 0 1 startangle endangle arc + closepath + savematrix setmatrix + } def + +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def +%%EndProlog + +$F2psBegin +10 setmiterlimit + 0.06000 0.06000 sc +7.500 slw +% Polyline +n 5626 2251 m 5026 1051 l 7426 451 l 8026 1651 l gs col-1 s gr +% Ellipse +n 5026 1051 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 330.07 65.07] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Polyline +n 5626 2251 m 6226 1051 l 8626 451 l 8026 1651 l 5626 2251 l gs col7 1.00 shd ef gr gs col-1 s gr +% Ellipse +n 452 2252 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 25.13 145.13] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Ellipse +n 1652 1052 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 105.13 65.13] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Ellipse +n 2852 2252 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 185.13 145.13] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Ellipse +n 4052 1052 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 265.13 65.13] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Polyline +n 1652 1052 m 452 2252 l gs col-1 s gr +% Polyline +n 2852 2252 m 4052 1052 l gs col-1 s gr +/Times-Roman findfont 270.00 scalefont setfont +1577 902 m +gs 1 -1 sc (i) col-1 show gr +/Symbol findfont 270.00 scalefont setfont +1577 1352 m +gs 1 -1 sc (a) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +2777 2627 m +gs 1 -1 sc (j) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +3977 902 m +gs 1 -1 sc (k) col-1 show gr +% Polyline +n 1652 1052 m 2852 2252 l gs col-1 s gr +% Arc +n 5881.00 1606.00 m 5851.00 1726.00 l 5821.00 1606.00 l 5851.50 1606.50 l 5881.00 1606.00 l clp gs 0.00 setgray ef gr gs col-1 s gr +n 5626.00 1726.00 225.00 180.00 0.00 arc +gs col-1 s gr + +/Times-Roman findfont 270.00 scalefont setfont +302 2627 m +gs 1 -1 sc (C) col-1 show gr +% Ellipse +n 5626 2251 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 370.07 145.07] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Ellipse +n 8626 451 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 570.07 25.07] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Ellipse +n 8026 1651 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 530.07 105.07] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Arc +n 1922.00 1472.00 m 1952.00 1352.00 l 1982.00 1472.00 l 1952.50 1472.50 l 1922.00 1472.00 l clp gs 0.00 setgray ef gr gs col-1 s gr +n 1652.00 1352.00 300.00 180.00 0.00 arcn +gs col-1 s gr + +/Times-Roman findfont 270.00 scalefont setfont +827 1577 m +gs 1 -1 sc (R) col-1 show gr +/Symbol findfont 270.00 scalefont setfont +5626 1951 m +gs 1 -1 sc (b) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +4726 1051 m +gs 1 -1 sc (C) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +5476 2626 m +gs 1 -1 sc (i) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +8101 1951 m +gs 1 -1 sc (j) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +8776 301 m +gs 1 -1 sc (k) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +2250 3450 m +gs 1 -1 sc (Input line: C i R j alpha k beta ) col-1 show gr +$F2psEnd +restore diff --git a/doc/user/zmat1.fig b/doc/user/zmat1.fig new file mode 100644 index 0000000000..f190a35340 --- /dev/null +++ b/doc/user/zmat1.fig @@ -0,0 +1,43 @@ +#FIG 3.1 +Landscape +Center +Inches +1200 2 +6 300 675 4200 2700 +5 1 0 1 -1 7 0 0 -1 0.000 0 1 1 0 1652.000 1352.000 1352 1352 1652 1652 1952 1352 + 1 1 1.00 60.00 120.00 +1 3 0 1 -1 0 0 0 62 0.0000000 1 0.000 452 2252 75 75 452 2252 452 2327 +1 3 0 1 -1 0 0 0 62 0.0000000 1 0.000 1652 1052 75 75 1652 1052 1652 1127 +1 3 0 1 -1 0 0 0 62 0.0000000 1 0.000 2852 2252 75 75 2852 2252 2852 2327 +1 3 0 1 -1 0 0 0 62 0.0000000 1 0.000 4052 1052 75 75 4052 1052 4052 1127 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 + 1652 1052 452 2252 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 + 2852 2252 4052 1052 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 + 1652 1052 2852 2252 +4 0 -1 0 0 32 18 0.0000000 4 120 165 1577 1352 a\001 +4 0 -1 0 0 0 18 0.0000000 4 180 180 302 2627 C\001 +4 0 -1 0 0 0 18 0.0000000 4 180 75 1577 902 i\001 +4 0 -1 0 0 0 18 0.0000000 4 240 75 2777 2627 j\001 +4 0 -1 0 0 0 18 0.0000000 4 180 135 3977 902 k\001 +4 0 -1 0 0 0 18 0.0000000 4 180 180 827 1577 R\001 +-6 +6 4724 74 8924 2699 +5 1 0 1 -1 7 0 0 -1 0.000 0 0 1 0 5626.000 1726.000 5401 1726 5626 1501 5851 1726 + 1 1 1.00 60.00 120.00 +1 3 0 1 -1 0 2 0 62 0.0000000 1 0.000 5026 1051 75 75 5026 1051 5101 1126 +1 3 0 1 -1 0 0 0 62 0.0000000 1 0.000 5626 2251 75 75 5626 2251 5701 2326 +1 3 0 1 -1 0 0 0 62 0.0000000 1 0.000 8626 451 75 75 8626 451 8701 526 +1 3 0 1 -1 0 0 0 62 0.0000000 1 0.000 8026 1651 75 75 8026 1651 8101 1726 +2 1 0 1 -1 7 1 0 20 0.000 0 0 7 0 0 5 + 5626 2251 6226 1051 8626 451 8026 1651 5626 2251 +2 1 0 1 -1 0 10 0 -1 0.000 0 0 -1 0 0 4 + 5626 2251 5026 1051 7426 451 8026 1651 +4 0 -1 0 0 32 18 0.0000000 4 240 150 5626 1951 b\001 +4 0 -1 0 0 0 18 0.0000000 4 180 180 4726 1051 C\001 +4 0 -1 0 0 0 18 0.0000000 4 180 75 5476 2626 i\001 +4 0 -1 0 0 0 18 0.0000000 4 240 75 8101 1951 j\001 +4 0 -1 0 0 0 18 0.0000000 4 180 135 8776 301 k\001 +-6 +4 0 -1 0 0 0 18 0.0000000 4 240 4290 2250 3450 Input line: C i R j alpha k beta \001 diff --git a/doc/user/zmat2.eps b/doc/user/zmat2.eps new file mode 100644 index 0000000000..5e36f77116 --- /dev/null +++ b/doc/user/zmat2.eps @@ -0,0 +1,533 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: zmat2.fig +%%Creator: fig2dev Version 3.1 Patchlevel 1 +%%CreationDate: Mon Jan 27 12:33:12 1997 +%%For: d3g681@fermi (Robert J Harrison) +%%Orientation: Landscape +%%BoundingBox: 0 0 266 485 +%%Pages: 0 +%%BeginSetup +%%IncludeFeature: *PageSize Letter +%%EndSetup +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {} def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +-45.0 -118.0 translate + 90 rotate +1 -1 scale +.9 .9 scale % to make patterns same scale as in xfig + +% This junk string is used by the show operators +/PATsstr 1 string def +/PATawidthshow { % cx cy cchar rx ry string + % Loop over each character in the string + { % cx cy cchar rx ry char + % Show the character + dup % cx cy cchar rx ry char char + PATsstr dup 0 4 -1 roll put % cx cy cchar rx ry char (char) + false charpath % cx cy cchar rx ry char + /clip load PATdraw + % Move past the character (charpath modified the + % current point) + currentpoint % cx cy cchar rx ry char x y + newpath + moveto % cx cy cchar rx ry char + % Reposition by cx,cy if the character in the string is cchar + 3 index eq { % cx cy cchar rx ry + 4 index 4 index rmoveto + } if + % Reposition all characters by rx ry + 2 copy rmoveto % cx cy cchar rx ry + } forall + pop pop pop pop pop % - + currentpoint + newpath + moveto +} bind def +/PATcg { + 7 dict dup begin + /lw currentlinewidth def + /lc currentlinecap def + /lj currentlinejoin def + /ml currentmiterlimit def + /ds [ currentdash ] def + /cc [ currentrgbcolor ] def + /cm matrix currentmatrix def + end +} bind def +% PATdraw - calculates the boundaries of the object and +% fills it with the current pattern +/PATdraw { % proc + save exch + PATpcalc % proc nw nh px py + 5 -1 roll exec % nw nh px py + newpath + PATfill % - + restore +} bind def +% PATfill - performs the tiling for the shape +/PATfill { % nw nh px py PATfill - + PATDict /CurrentPattern get dup begin + setfont + % Set the coordinate system to Pattern Space + PatternGState PATsg + % Set the color for uncolored pattezns + PaintType 2 eq { PATDict /PColor get PATsc } if + % Create the string for showing + 3 index string % nw nh px py str + % Loop for each of the pattern sources + 0 1 Multi 1 sub { % nw nh px py str source + % Move to the starting location + 3 index 3 index % nw nh px py str source px py + moveto % nw nh px py str source + % For multiple sources, set the appropriate color + Multi 1 ne { dup PC exch get PATsc } if + % Set the appropriate string for the source + 0 1 7 index 1 sub { 2 index exch 2 index put } for pop + % Loop over the number of vertical cells + 3 index % nw nh px py str nh + { % nw nh px py str + currentpoint % nw nh px py str cx cy + 2 index show % nw nh px py str cx cy + YStep add moveto % nw nh px py str + } repeat % nw nh px py str + } for + 5 { pop } repeat + end +} bind def + +% PATkshow - kshow with the current pattezn +/PATkshow { % proc string + exch bind % string proc + 1 index 0 get % string proc char + % Loop over all but the last character in the string + 0 1 4 index length 2 sub { + % string proc char idx + % Find the n+1th character in the string + 3 index exch 1 add get % string proe char char+1 + exch 2 copy % strinq proc char+1 char char+1 char + % Now show the nth character + PATsstr dup 0 4 -1 roll put % string proc chr+1 chr chr+1 (chr) + false charpath % string proc char+1 char char+1 + /clip load PATdraw + % Move past the character (charpath modified the current point) + currentpoint newpath moveto + % Execute the user proc (should consume char and char+1) + mark 3 1 roll % string proc char+1 mark char char+1 + 4 index exec % string proc char+1 mark... + cleartomark % string proc char+1 + } for + % Now display the last character + PATsstr dup 0 4 -1 roll put % string proc (char+1) + false charpath % string proc + /clip load PATdraw + neewath + pop pop % - +} bind def +% PATmp - the makepattern equivalent +/PATmp { % patdict patmtx PATmp patinstance + exch dup length 7 add % We will add 6 new entries plus 1 FID + dict copy % Create a new dictionary + begin + % Matrix to install when painting the pattern + TilingType PATtcalc + /PatternGState PATcg def + PatternGState /cm 3 -1 roll put + % Check for multi pattern sources (Level 1 fast color patterns) + currentdict /Multi known not { /Multi 1 def } if + % Font dictionary definitions + /FontType 3 def + % Create a dummy encoding vector + /Encoding 256 array def + 3 string 0 1 255 { + Encoding exch dup 3 index cvs cvn put } for pop + /FontMatrix matrix def + /FontBBox BBox def + /BuildChar { + mark 3 1 roll % mark dict char + exch begin + Multi 1 ne {PaintData exch get}{pop} ifelse % mark [paintdata] + PaintType 2 eq Multi 1 ne or + { XStep 0 FontBBox aload pop setcachedevice } + { XStep 0 setcharwidth } ifelse + currentdict % mark [paintdata] dict + /PaintProc load % mark [paintdata] dict paintproc + end + gsave + false PATredef exec true PATredef + grestore + cleartomark % - + } bind def + currentdict + end % newdict + /foo exch % /foo newlict + definefont % newfont +} bind def +% PATpcalc - calculates the starting point and width/height +% of the tile fill for the shape +/PATpcalc { % - PATpcalc nw nh px py + PATDict /CurrentPattern get begin + gsave + % Set up the coordinate system to Pattern Space + % and lock down pattern + PatternGState /cm get setmatrix + BBox aload pop pop pop translate + % Determine the bounding box of the shape + pathbbox % llx lly urx ury + grestore + % Determine (nw, nh) the # of cells to paint width and height + PatHeight div ceiling % llx lly urx qh + 4 1 roll % qh llx lly urx + PatWidth div ceiling % qh llx lly qw + 4 1 roll % qw qh llx lly + PatHeight div floor % qw qh llx ph + 4 1 roll % ph qw qh llx + PatWidth div floor % ph qw qh pw + 4 1 roll % pw ph qw qh + 2 index sub cvi abs % pw ph qs qh-ph + exch 3 index sub cvi abs exch % pw ph nw=qw-pw nh=qh-ph + % Determine the starting point of the pattern fill + %(px, py) + 4 2 roll % nw nh pw ph + PatHeight mul % nw nh pw py + exch % nw nh py pw + PatWidth mul exch % nw nh px py + end +} bind def + +% Save the original routines so that we can use them later on +/oldfill /fill load def +/oldeofill /eofill load def +/oldstroke /stroke load def +/oldshow /show load def +/oldashow /ashow load def +/oldwidthshow /widthshow load def +/oldawidthshow /awidthshow load def +/oldkshow /kshow load def + +% These defs are necessary so that subsequent procs don't bind in +% the originals +/fill { oldfill } bind def +/eofill { oldeofill } bind def +/stroke { oldstroke } bind def +/show { oldshow } bind def +/ashow { oldashow } bind def +/widthshow { oldwidthshow } bind def +/awidthshow { oldawidthshow } bind def +/kshow { oldkshow } bind def +/PATredef { + userdict begin + { + /fill { /clip load PATdraw newpath } bind def + /eofill { /eoclip load PATdraw newpath } bind def + /stroke { PATstroke } bind def + /show { 0 0 null 0 0 6 -1 roll PATawidthshow } bind def + /ashow { 0 0 null 6 3 roll PATawidthshow } + bind def + /widthshow { 0 0 3 -1 roll PATawidthshow } + bind def + /awidthshow { PATawidthshow } bind def + /kshow { PATkshow } bind def + } { + /fill { oldfill } bind def + /eofill { oldeofill } bind def + /stroke { oldstroke } bind def + /show { oldshow } bind def + /ashow { oldashow } bind def + /widthshow { oldwidthshow } bind def + /awidthshow { oldawidthshow } bind def + /kshow { oldkshow } bind def + } ifelse + end +} bind def +false PATredef +% Conditionally define setcmykcolor if not available +/setcmykcolor where { pop } { + /setcmykcolor { + 1 sub 4 1 roll + 3 { + 3 index add neg dup 0 lt { pop 0 } if 3 1 roll + } repeat + setrgbcolor - pop + } bind def +} ifelse +/PATsc { % colorarray + aload length % c1 ... cn length + dup 1 eq { pop setgray } { 3 eq { setrgbcolor } { setcmykcolor + } ifelse } ifelse +} bind def +/PATsg { % dict + begin + lw setlinewidth + lc setlinecap + lj setlinejoin + ml setmiterlimit + ds aload pop setdash + cc aload pop setrgbcolor + cm setmatrix + end +} bind def + +/PATDict 3 dict def +/PATsp { + true PATredef + PATDict begin + /CurrentPattern exch def + % If it's an uncolored pattern, save the color + CurrentPattern /PaintType get 2 eq { + /PColor exch def + } if + /CColor [ currentrgbcolor ] def + end +} bind def +% PATstroke - stroke with the current pattern +/PATstroke { + countdictstack + save + mark + { + currentpoint strokepath moveto + PATpcalc % proc nw nh px py + clip newpath PATfill + } stopped { + (*** PATstroke Warning: Path is too complex, stroking + with gray) = + cleartomark + restore + countdictstack exch sub dup 0 gt + { { end } repeat } { pop } ifelse + gsave 0.5 setgray oldstroke grestore + } { pop restore pop } ifelse + newpath +} bind def +/PATtcalc { % modmtx tilingtype PATtcalc tilematrix + % Note: tiling types 2 and 3 are not supported + gsave + exch concat % tilingtype + matrix currentmatrix exch % cmtx tilingtype + % Tiling type 1 and 3: constant spacing + 2 ne { + % Distort the pattern so that it occupies + % an integral number of device pixels + dup 4 get exch dup 5 get exch % tx ty cmtx + XStep 0 dtransform + round exch round exch % tx ty cmtx dx.x dx.y + XStep div exch XStep div exch % tx ty cmtx a b + 0 YStep dtransform + round exch round exch % tx ty cmtx a b dy.x dy.y + YStep div exch YStep div exch % tx ty cmtx a b c d + 7 -3 roll astore % { a b c d tx ty } + } if + grestore +} bind def +/PATusp { + false PATredef + PATDict begin + CColor PATsc + end +} bind def + +% vertical sawtooth lines +11 dict begin +/PaintType 1 def +/PatternType 1 def +/TilingType 1 def +/BBox [0 0 1 1] def +/XStep 1 def +/YStep 1 def +/PatWidth 1 def +/PatHeight 1 def +/Multi 2 def +/PaintData [ + { clippath } bind + { 16 32 true [ 16 0 0 -32 0 32 ] + {<400020001000080004000200010000800100020004000800 + 100020004000800040002000100008000400020001000080 + 01000200040008001000200040008000>} + imagemask } bind +] def +/PaintProc { + pop + exec fill +} def +currentdict +end +/P22 exch def +1.1111 1.1111 scale %restore scale + +/clp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/l {lineto} bind def +/m {moveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def + /DrawEllipse { + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y tr xrad yrad sc 0 0 1 startangle endangle arc + closepath + savematrix setmatrix + } def + +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def +%%EndProlog + +$F2psBegin +10 setmiterlimit + 0.06000 0.06000 sc +7.500 slw +% Ellipse +n 8946 2749 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 591.40 178.27] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Ellipse +n 8250 2160 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 545.00 139.00] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Ellipse +n 7035 2745 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 464.00 178.00] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Ellipse +n 6435 1560 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 424.00 99.00] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Polyline +n 3603 2433 m 2115 3300 l gs col-1 s gr +% Ellipse +n 3603 2433 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 235.20 157.20] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Ellipse +n 3600 975 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 235.00 60.00] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Ellipse +n 2111 3322 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 135.73 216.47] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Polyline +n 4803 3633 m 4803 3633 l gs col-1 s gr +% Polyline +n 3603 2433 m 4803 3633 l gs col-1 s gr +% Polyline +n 3600 2370 m 3600 945 l gs col-1 s gr +/Times-Roman findfont 270.00 scalefont setfont +3750 2325 m +gs 1 -1 sc (i) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +3375 900 m +gs 1 -1 sc (k) col-1 show gr +/Symbol findfont 270.00 scalefont setfont +3375 2400 m +gs 1 -1 sc (b) col-1 show gr +% Ellipse +n 4803 3633 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 315.20 237.20] PATmp PATsp ef gr PATusp gs col-1 s gr + +/Times-Roman findfont 270.00 scalefont setfont +1983 3708 m +gs 1 -1 sc (C) col-1 show gr +% Arc +n 7391.98 2424.01 m 7470.00 2520.00 l 7355.99 2472.02 l 7374.49 2448.52 l 7391.98 2424.01 l clp gs 0.00 setgray ef gr gs col-1 s gr +n 7019.66 3120.68 750.75 -101.50 -53.14 arc +gs col-1 s gr + +/Times-Roman findfont 270.00 scalefont setfont +4728 4008 m +gs 1 -1 sc (j) col-1 show gr +/Symbol findfont 270.00 scalefont setfont +3528 2733 m +gs 1 -1 sc (a) col-1 show gr +% Arc +n 3866.17 2878.78 m 3975.00 2820.00 l 3906.63 2923.08 l 3886.90 2901.43 l 3866.17 2878.78 l clp gs 0.00 setgray ef gr gs col-1 s gr +n 3480.82 1781.90 m 3600.00 1815.00 l 3479.26 1841.88 l 3480.54 1812.39 l 3480.82 1781.90 l clp gs 0.00 setgray ef gr gs col-1 s gr +n 3585.00 2393.06 578.25 -88.51 47.59 arcn +gs col-1 s gr + +/Times-Roman findfont 270.00 scalefont setfont +2643 2823 m +gs 1 -1 sc (R) col-1 show gr +% Polyline +n 7035 2760 m 8235 2160 l 10035 2160 l 8910 2760 l 7035 2760 l gs col-1 s gr +% Polyline +n 7035 2760 m 6435 1560 l gs col-1 s gr +/Times-Roman findfont 270.00 scalefont setfont +8880 3075 m +gs 1 -1 sc (j) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +8250 1980 m +gs 1 -1 sc (k) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +6270 1470 m +gs 1 -1 sc (C) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +7005 3075 m +gs 1 -1 sc (i) col-1 show gr +/Symbol findfont 270.00 scalefont setfont +7065 2625 m +gs 1 -1 sc (b) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +3195 5130 m +gs 1 -1 sc (Input line: C i R j alpha k beta +1) col-1 show gr +$F2psEnd +restore diff --git a/doc/user/zmat2.fig b/doc/user/zmat2.fig new file mode 100644 index 0000000000..e12a8ee223 --- /dev/null +++ b/doc/user/zmat2.fig @@ -0,0 +1,47 @@ +#FIG 3.1 +Landscape +Center +Inches +1200 2 +6 1983 720 4878 4068 +5 1 0 1 -1 7 0 0 -1 0.000 0 1 1 1 3585.000 2393.060 3600 1815 3195 2820 3975 2820 + 1 1 1.00 60.00 120.00 + 1 1 1.00 60.00 120.00 +1 3 0 1 -1 0 0 0 62 0.0000000 1 0.000 4803 3633 75 75 4803 3633 4803 3708 +1 3 0 1 -1 0 0 0 62 0.0000000 1 0.000 3603 2433 75 75 3603 2433 3603 2508 +1 3 0 1 -1 0 0 0 62 0.0000000 1 0.000 3600 975 75 75 3600 975 3600 1050 +1 3 0 1 -1 0 0 0 62 0.0000000 1 0.000 2111 3322 75 75 2111 3322 2111 3397 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 1 + 4803 3633 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 + 3603 2433 4803 3633 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 + 3600 2370 3600 945 +2 1 0 1 -1 7 1 0 -1 0.000 0 0 -1 0 0 2 + 3603 2433 2115 3300 +4 0 -1 0 0 32 18 0.0000000 4 120 165 3528 2733 a\001 +4 0 -1 0 0 0 18 0.0000000 4 240 75 4728 4008 j\001 +4 0 -1 0 0 0 18 0.0000000 4 180 75 3750 2325 i\001 +4 0 -1 0 0 0 18 0.0000000 4 180 135 3375 900 k\001 +4 0 -1 0 0 32 18 0.0000000 4 240 150 3375 2400 b\001 +4 0 -1 0 0 0 18 0.0000000 4 180 180 2643 2823 R\001 +4 0 -1 0 0 0 18 0.0000000 4 180 180 1983 3708 C\001 +-6 +6 6270 1290 10035 3135 +5 1 0 1 -1 7 0 0 -1 0.000 0 0 1 0 7019.659 3120.682 6870 2385 7230 2400 7470 2520 + 1 1 1.00 60.00 120.00 +1 3 0 1 -1 0 2 0 62 0.0000000 1 0.000 8250 2160 75 75 8250 2160 8325 2235 +1 3 0 1 -1 0 2 0 62 0.0000000 1 0.000 8946 2749 75 75 8946 2749 9021 2824 +1 3 0 1 -1 0 2 0 62 0.0000000 1 0.000 6435 1560 75 75 6435 1560 6510 1635 +1 3 0 1 -1 0 2 0 62 0.0000000 1 0.000 7035 2745 75 75 7035 2745 7110 2820 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 + 7035 2760 8235 2160 10035 2160 8910 2760 7035 2760 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 + 7035 2760 6435 1560 +4 0 -1 0 0 0 18 0.0000000 4 240 75 8880 3075 j\001 +4 0 -1 0 0 0 18 0.0000000 4 180 135 8250 1980 k\001 +4 0 -1 0 0 0 18 0.0000000 4 180 180 6270 1470 C\001 +4 0 -1 0 0 0 18 0.0000000 4 180 75 7005 3075 i\001 +4 0 -1 0 0 32 18 0.0000000 4 240 150 7065 2625 b\001 +-6 +4 0 -1 0 0 0 18 0.0000000 4 240 4575 3195 5130 Input line: C i R j alpha k beta +1\001 diff --git a/doc/user/zmat3.eps b/doc/user/zmat3.eps new file mode 100644 index 0000000000..9525052c4f --- /dev/null +++ b/doc/user/zmat3.eps @@ -0,0 +1,533 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: zmat3.fig +%%Creator: fig2dev Version 3.1 Patchlevel 1 +%%CreationDate: Mon Jan 27 12:32:13 1997 +%%For: d3g681@fermi (Robert J Harrison) +%%Orientation: Landscape +%%BoundingBox: 0 0 266 482 +%%Pages: 0 +%%BeginSetup +%%IncludeFeature: *PageSize Letter +%%EndSetup +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {} def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +-45.0 -118.0 translate + 90 rotate +1 -1 scale +.9 .9 scale % to make patterns same scale as in xfig + +% This junk string is used by the show operators +/PATsstr 1 string def +/PATawidthshow { % cx cy cchar rx ry string + % Loop over each character in the string + { % cx cy cchar rx ry char + % Show the character + dup % cx cy cchar rx ry char char + PATsstr dup 0 4 -1 roll put % cx cy cchar rx ry char (char) + false charpath % cx cy cchar rx ry char + /clip load PATdraw + % Move past the character (charpath modified the + % current point) + currentpoint % cx cy cchar rx ry char x y + newpath + moveto % cx cy cchar rx ry char + % Reposition by cx,cy if the character in the string is cchar + 3 index eq { % cx cy cchar rx ry + 4 index 4 index rmoveto + } if + % Reposition all characters by rx ry + 2 copy rmoveto % cx cy cchar rx ry + } forall + pop pop pop pop pop % - + currentpoint + newpath + moveto +} bind def +/PATcg { + 7 dict dup begin + /lw currentlinewidth def + /lc currentlinecap def + /lj currentlinejoin def + /ml currentmiterlimit def + /ds [ currentdash ] def + /cc [ currentrgbcolor ] def + /cm matrix currentmatrix def + end +} bind def +% PATdraw - calculates the boundaries of the object and +% fills it with the current pattern +/PATdraw { % proc + save exch + PATpcalc % proc nw nh px py + 5 -1 roll exec % nw nh px py + newpath + PATfill % - + restore +} bind def +% PATfill - performs the tiling for the shape +/PATfill { % nw nh px py PATfill - + PATDict /CurrentPattern get dup begin + setfont + % Set the coordinate system to Pattern Space + PatternGState PATsg + % Set the color for uncolored pattezns + PaintType 2 eq { PATDict /PColor get PATsc } if + % Create the string for showing + 3 index string % nw nh px py str + % Loop for each of the pattern sources + 0 1 Multi 1 sub { % nw nh px py str source + % Move to the starting location + 3 index 3 index % nw nh px py str source px py + moveto % nw nh px py str source + % For multiple sources, set the appropriate color + Multi 1 ne { dup PC exch get PATsc } if + % Set the appropriate string for the source + 0 1 7 index 1 sub { 2 index exch 2 index put } for pop + % Loop over the number of vertical cells + 3 index % nw nh px py str nh + { % nw nh px py str + currentpoint % nw nh px py str cx cy + 2 index show % nw nh px py str cx cy + YStep add moveto % nw nh px py str + } repeat % nw nh px py str + } for + 5 { pop } repeat + end +} bind def + +% PATkshow - kshow with the current pattezn +/PATkshow { % proc string + exch bind % string proc + 1 index 0 get % string proc char + % Loop over all but the last character in the string + 0 1 4 index length 2 sub { + % string proc char idx + % Find the n+1th character in the string + 3 index exch 1 add get % string proe char char+1 + exch 2 copy % strinq proc char+1 char char+1 char + % Now show the nth character + PATsstr dup 0 4 -1 roll put % string proc chr+1 chr chr+1 (chr) + false charpath % string proc char+1 char char+1 + /clip load PATdraw + % Move past the character (charpath modified the current point) + currentpoint newpath moveto + % Execute the user proc (should consume char and char+1) + mark 3 1 roll % string proc char+1 mark char char+1 + 4 index exec % string proc char+1 mark... + cleartomark % string proc char+1 + } for + % Now display the last character + PATsstr dup 0 4 -1 roll put % string proc (char+1) + false charpath % string proc + /clip load PATdraw + neewath + pop pop % - +} bind def +% PATmp - the makepattern equivalent +/PATmp { % patdict patmtx PATmp patinstance + exch dup length 7 add % We will add 6 new entries plus 1 FID + dict copy % Create a new dictionary + begin + % Matrix to install when painting the pattern + TilingType PATtcalc + /PatternGState PATcg def + PatternGState /cm 3 -1 roll put + % Check for multi pattern sources (Level 1 fast color patterns) + currentdict /Multi known not { /Multi 1 def } if + % Font dictionary definitions + /FontType 3 def + % Create a dummy encoding vector + /Encoding 256 array def + 3 string 0 1 255 { + Encoding exch dup 3 index cvs cvn put } for pop + /FontMatrix matrix def + /FontBBox BBox def + /BuildChar { + mark 3 1 roll % mark dict char + exch begin + Multi 1 ne {PaintData exch get}{pop} ifelse % mark [paintdata] + PaintType 2 eq Multi 1 ne or + { XStep 0 FontBBox aload pop setcachedevice } + { XStep 0 setcharwidth } ifelse + currentdict % mark [paintdata] dict + /PaintProc load % mark [paintdata] dict paintproc + end + gsave + false PATredef exec true PATredef + grestore + cleartomark % - + } bind def + currentdict + end % newdict + /foo exch % /foo newlict + definefont % newfont +} bind def +% PATpcalc - calculates the starting point and width/height +% of the tile fill for the shape +/PATpcalc { % - PATpcalc nw nh px py + PATDict /CurrentPattern get begin + gsave + % Set up the coordinate system to Pattern Space + % and lock down pattern + PatternGState /cm get setmatrix + BBox aload pop pop pop translate + % Determine the bounding box of the shape + pathbbox % llx lly urx ury + grestore + % Determine (nw, nh) the # of cells to paint width and height + PatHeight div ceiling % llx lly urx qh + 4 1 roll % qh llx lly urx + PatWidth div ceiling % qh llx lly qw + 4 1 roll % qw qh llx lly + PatHeight div floor % qw qh llx ph + 4 1 roll % ph qw qh llx + PatWidth div floor % ph qw qh pw + 4 1 roll % pw ph qw qh + 2 index sub cvi abs % pw ph qs qh-ph + exch 3 index sub cvi abs exch % pw ph nw=qw-pw nh=qh-ph + % Determine the starting point of the pattern fill + %(px, py) + 4 2 roll % nw nh pw ph + PatHeight mul % nw nh pw py + exch % nw nh py pw + PatWidth mul exch % nw nh px py + end +} bind def + +% Save the original routines so that we can use them later on +/oldfill /fill load def +/oldeofill /eofill load def +/oldstroke /stroke load def +/oldshow /show load def +/oldashow /ashow load def +/oldwidthshow /widthshow load def +/oldawidthshow /awidthshow load def +/oldkshow /kshow load def + +% These defs are necessary so that subsequent procs don't bind in +% the originals +/fill { oldfill } bind def +/eofill { oldeofill } bind def +/stroke { oldstroke } bind def +/show { oldshow } bind def +/ashow { oldashow } bind def +/widthshow { oldwidthshow } bind def +/awidthshow { oldawidthshow } bind def +/kshow { oldkshow } bind def +/PATredef { + userdict begin + { + /fill { /clip load PATdraw newpath } bind def + /eofill { /eoclip load PATdraw newpath } bind def + /stroke { PATstroke } bind def + /show { 0 0 null 0 0 6 -1 roll PATawidthshow } bind def + /ashow { 0 0 null 6 3 roll PATawidthshow } + bind def + /widthshow { 0 0 3 -1 roll PATawidthshow } + bind def + /awidthshow { PATawidthshow } bind def + /kshow { PATkshow } bind def + } { + /fill { oldfill } bind def + /eofill { oldeofill } bind def + /stroke { oldstroke } bind def + /show { oldshow } bind def + /ashow { oldashow } bind def + /widthshow { oldwidthshow } bind def + /awidthshow { oldawidthshow } bind def + /kshow { oldkshow } bind def + } ifelse + end +} bind def +false PATredef +% Conditionally define setcmykcolor if not available +/setcmykcolor where { pop } { + /setcmykcolor { + 1 sub 4 1 roll + 3 { + 3 index add neg dup 0 lt { pop 0 } if 3 1 roll + } repeat + setrgbcolor - pop + } bind def +} ifelse +/PATsc { % colorarray + aload length % c1 ... cn length + dup 1 eq { pop setgray } { 3 eq { setrgbcolor } { setcmykcolor + } ifelse } ifelse +} bind def +/PATsg { % dict + begin + lw setlinewidth + lc setlinecap + lj setlinejoin + ml setmiterlimit + ds aload pop setdash + cc aload pop setrgbcolor + cm setmatrix + end +} bind def + +/PATDict 3 dict def +/PATsp { + true PATredef + PATDict begin + /CurrentPattern exch def + % If it's an uncolored pattern, save the color + CurrentPattern /PaintType get 2 eq { + /PColor exch def + } if + /CColor [ currentrgbcolor ] def + end +} bind def +% PATstroke - stroke with the current pattern +/PATstroke { + countdictstack + save + mark + { + currentpoint strokepath moveto + PATpcalc % proc nw nh px py + clip newpath PATfill + } stopped { + (*** PATstroke Warning: Path is too complex, stroking + with gray) = + cleartomark + restore + countdictstack exch sub dup 0 gt + { { end } repeat } { pop } ifelse + gsave 0.5 setgray oldstroke grestore + } { pop restore pop } ifelse + newpath +} bind def +/PATtcalc { % modmtx tilingtype PATtcalc tilematrix + % Note: tiling types 2 and 3 are not supported + gsave + exch concat % tilingtype + matrix currentmatrix exch % cmtx tilingtype + % Tiling type 1 and 3: constant spacing + 2 ne { + % Distort the pattern so that it occupies + % an integral number of device pixels + dup 4 get exch dup 5 get exch % tx ty cmtx + XStep 0 dtransform + round exch round exch % tx ty cmtx dx.x dx.y + XStep div exch XStep div exch % tx ty cmtx a b + 0 YStep dtransform + round exch round exch % tx ty cmtx a b dy.x dy.y + YStep div exch YStep div exch % tx ty cmtx a b c d + 7 -3 roll astore % { a b c d tx ty } + } if + grestore +} bind def +/PATusp { + false PATredef + PATDict begin + CColor PATsc + end +} bind def + +% vertical sawtooth lines +11 dict begin +/PaintType 1 def +/PatternType 1 def +/TilingType 1 def +/BBox [0 0 1 1] def +/XStep 1 def +/YStep 1 def +/PatWidth 1 def +/PatHeight 1 def +/Multi 2 def +/PaintData [ + { clippath } bind + { 16 32 true [ 16 0 0 -32 0 32 ] + {<400020001000080004000200010000800100020004000800 + 100020004000800040002000100008000400020001000080 + 01000200040008001000200040008000>} + imagemask } bind +] def +/PaintProc { + pop + exec fill +} def +currentdict +end +/P22 exch def +1.1111 1.1111 scale %restore scale + +/clp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/l {lineto} bind def +/m {moveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def + /DrawEllipse { + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y tr xrad yrad sc 0 0 1 startangle endangle arc + closepath + savematrix setmatrix + } def + +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def +%%EndProlog + +$F2psBegin +10 setmiterlimit + 0.06000 0.06000 sc +7.500 slw +% Ellipse +n 8886 2104 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 587.40 135.27] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Ellipse +n 8190 1515 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 541.00 96.00] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Ellipse +n 6135 3345 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 404.00 218.00] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Ellipse +n 6975 2100 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 460.00 135.00] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Polyline +n 3603 2433 m 2115 3300 l gs col-1 s gr +% Ellipse +n 3603 2433 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 235.20 157.20] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Ellipse +n 3600 975 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 235.00 60.00] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Ellipse +n 2111 3322 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 135.73 216.47] PATmp PATsp ef gr PATusp gs col-1 s gr + +% Polyline +n 4803 3633 m 4803 3633 l gs col-1 s gr +% Polyline +n 3603 2433 m 4803 3633 l gs col-1 s gr +% Polyline +n 3600 2370 m 3600 945 l gs col-1 s gr +/Times-Roman findfont 270.00 scalefont setfont +3750 2325 m +gs 1 -1 sc (i) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +3375 900 m +gs 1 -1 sc (k) col-1 show gr +/Symbol findfont 270.00 scalefont setfont +3375 2400 m +gs 1 -1 sc (b) col-1 show gr +% Ellipse +n 4803 3633 75 75 0 360 DrawEllipse gs /PC [[0.00 0.00 0.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P22 [8 0 0 -16 315.20 237.20] PATmp PATsp ef gr PATusp gs col-1 s gr + +/Times-Roman findfont 270.00 scalefont setfont +1983 3708 m +gs 1 -1 sc (C) col-1 show gr +% Arc +n 7428.80 1995.89 m 7455.00 1875.00 l 7488.77 1993.99 l 7459.29 1995.44 l 7428.80 1995.89 l clp gs 0.00 setgray ef gr gs col-1 s gr +n 6863.09 1893.70 592.20 101.01 -1.81 arcn +gs col-1 s gr + +/Times-Roman findfont 270.00 scalefont setfont +4728 4008 m +gs 1 -1 sc (j) col-1 show gr +/Symbol findfont 270.00 scalefont setfont +3528 2733 m +gs 1 -1 sc (a) col-1 show gr +% Arc +n 3866.17 2878.78 m 3975.00 2820.00 l 3906.63 2923.08 l 3886.90 2901.43 l 3866.17 2878.78 l clp gs 0.00 setgray ef gr gs col-1 s gr +n 3480.82 1781.90 m 3600.00 1815.00 l 3479.26 1841.88 l 3480.54 1812.39 l 3480.82 1781.90 l clp gs 0.00 setgray ef gr gs col-1 s gr +n 3585.00 2393.06 578.25 -88.51 47.59 arcn +gs col-1 s gr + +/Times-Roman findfont 270.00 scalefont setfont +2643 2823 m +gs 1 -1 sc (R) col-1 show gr +% Polyline +n 6975 2115 m 8175 1515 l 9975 1515 l 8850 2115 l 6975 2115 l gs col-1 s gr +% Polyline +n 6975 2115 m 6135 3330 l gs col-1 s gr +/Times-Roman findfont 270.00 scalefont setfont +8820 2430 m +gs 1 -1 sc (j) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +8190 1335 m +gs 1 -1 sc (k) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +6795 1950 m +gs 1 -1 sc (i) col-1 show gr +/Symbol findfont 270.00 scalefont setfont +7035 2400 m +gs 1 -1 sc (b) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +5910 3225 m +gs 1 -1 sc (C) col-1 show gr +/Times-Roman findfont 270.00 scalefont setfont +3195 5130 m +gs 1 -1 sc (Input line: C i R j alpha k beta -1) col-1 show gr +$F2psEnd +restore diff --git a/doc/user/zmat3.fig b/doc/user/zmat3.fig new file mode 100644 index 0000000000..a577cf1ca2 --- /dev/null +++ b/doc/user/zmat3.fig @@ -0,0 +1,47 @@ +#FIG 3.1 +Landscape +Center +Inches +1200 2 +6 1983 720 4878 4068 +5 1 0 1 -1 7 0 0 -1 0.000 0 1 1 1 3585.000 2393.060 3600 1815 3195 2820 3975 2820 + 1 1 1.00 60.00 120.00 + 1 1 1.00 60.00 120.00 +1 3 0 1 -1 0 0 0 62 0.0000000 1 0.000 4803 3633 75 75 4803 3633 4803 3708 +1 3 0 1 -1 0 0 0 62 0.0000000 1 0.000 3603 2433 75 75 3603 2433 3603 2508 +1 3 0 1 -1 0 0 0 62 0.0000000 1 0.000 3600 975 75 75 3600 975 3600 1050 +1 3 0 1 -1 0 0 0 62 0.0000000 1 0.000 2111 3322 75 75 2111 3322 2111 3397 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 1 + 4803 3633 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 + 3603 2433 4803 3633 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 + 3600 2370 3600 945 +2 1 0 1 -1 7 1 0 -1 0.000 0 0 -1 0 0 2 + 3603 2433 2115 3300 +4 0 -1 0 0 32 18 0.0000000 4 120 165 3528 2733 a\001 +4 0 -1 0 0 0 18 0.0000000 4 240 75 4728 4008 j\001 +4 0 -1 0 0 0 18 0.0000000 4 180 75 3750 2325 i\001 +4 0 -1 0 0 0 18 0.0000000 4 180 135 3375 900 k\001 +4 0 -1 0 0 32 18 0.0000000 4 240 150 3375 2400 b\001 +4 0 -1 0 0 0 18 0.0000000 4 180 180 2643 2823 R\001 +4 0 -1 0 0 0 18 0.0000000 4 180 180 1983 3708 C\001 +-6 +6 5910 1155 9975 3420 +5 1 0 1 -1 7 0 0 -1 0.000 0 1 1 0 6863.093 1893.697 6750 2475 7215 2370 7455 1875 + 1 1 1.00 60.00 120.00 +1 3 0 1 -1 0 2 0 62 0.0000000 1 0.000 8190 1515 75 75 8190 1515 8265 1590 +1 3 0 1 -1 0 2 0 62 0.0000000 1 0.000 8886 2104 75 75 8886 2104 8961 2179 +1 3 0 1 -1 0 2 0 62 0.0000000 1 0.000 6975 2100 75 75 6975 2100 7050 2175 +1 3 0 1 -1 0 2 0 62 0.0000000 1 0.000 6135 3345 75 75 6135 3345 6210 3420 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 5 + 6975 2115 8175 1515 9975 1515 8850 2115 6975 2115 +2 1 0 1 -1 7 0 0 -1 0.000 0 0 -1 0 0 2 + 6975 2115 6135 3330 +4 0 -1 0 0 0 18 0.0000000 4 240 75 8820 2430 j\001 +4 0 -1 0 0 0 18 0.0000000 4 180 135 8190 1335 k\001 +4 0 -1 0 0 0 18 0.0000000 4 180 75 6795 1950 i\001 +4 0 -1 0 0 32 18 0.0000000 4 240 150 7035 2400 b\001 +4 0 -1 0 0 0 18 0.0000000 4 180 180 5910 3225 C\001 +-6 +4 0 -1 0 0 0 18 0.0000000 4 240 4575 3195 5130 Input line: C i R j alpha k beta -1\001