Command Line Submission

It is possible (although not necessarily suggested) to run computational jobs without using the Spartan Graphical User Interface (Spartan GUI). Spartan can be run from the command line with the "--submit <moleculename>" where "moleculename" is a Spartan molecule created by the GUI. One can also use the "--foreground-submit <moleculename>" which will not return until the job is completed. (This is useful when used in shell scripts.) An example on how to do this on a PC can be found here and under Linux here.

It is advised to use the Spartan GUI to build molecules. This is a good way to ensure that the molecule is correct and that valid submissions will occur. However, it is possible to create molecules without the Spartan GUI; these methods assume that the user has significant programming and system skills.

Assuming one is willing to experiment with homegrown shell submission the remaining part of this FAQ will discuss the internal Spartan file format. It is important to note that this description is not complete, but should be enough for simple submission scripts.

Other command line options
Platform specific considerations:
- Windows
- Linux
- Macintosh
Document Structure
Input File format
Archive file format
Property archive file format

Other Command Line Options
There are a number of other command line options that may be useful in batch mode
- --submit <Document-Name>
  Submit a job to the Spartan queue.
- --foreground-submit <Document-Name>
  Submit a job to the Spartan queue, but will not return until the job is complete.
- --convert <ImportFile.ext>
  To convert selected file formats to Spartan documents. (A "dot-spardir" document/directory will be created.) An extension is necessary to determine the file type. Not all import formats supported by the GUI are supported by this command. For a list of supported file formats use "--convert --ext". To override an extension one can use
  --unpack -e <ext> -o <newDocument> <ImportFile>
- --unpack <SpartanDocument> <NewDocument>
  To convert the packed (single file) Spartan Document to a "Spartan Document Directory". (The single file Spartan Document is the default format on for Windows).
- --help
  A listing of other options will be given.

^Back to Top^

Windows specific considerations
To run under a "DOS" window you need to supply the absolute path to where Spartan is installed. For example at the DOS prompt on my Windows machine I type:
> set SP="C:\Program Files\Wavefunction\Spartan18v100" > cd C:\MyMolecules > %SP%\spartanx --path %SP% --submit My-methane.spardir
There is a sample 'bat' file called spartan-win.bat which may be used as a template for this procedure.

It should be noted that spartanx only submits to the 'Local' machine, ignoring any 'servers' which may have been set up in the Option -> Preferences -> Available Servers tab. The values set in the Option/Preferences/Jobs pane are adhered to. However you must make sure to click the 'Apply' button (or close & reopen the Spartan GUI) in order for the spartanx program to recognize changes.

For those with a Bourne shell installed on a PC (i.e. Cygwin) there is a Bourne shell script spartan-win.sh that can be used. We advise to copy this file to '/usr/local/bin', rename it spartan, and edit the SPARTAN_PATH line to be the install path for Spartan.
^Back to Top^

Linux specific considerations
To automate scripts from a Bourne shell use the same command you use to launch the GUI. For example:
> cd ~/MyMolecules > spartan --foreground-submit My-methane.spardir ^Back to Top^

Macintosh specific considerations
To run Spartan from the command line we supply a shell wrapper. We suggest you place this to a directory bin in your path, such as /usr/local/bin. Assuming you installed Spartan in the default location, you would create this file via:
$ cp /Applications/Spartan\ 20.app/Contents/SharedSupport/Spartan.sh /usr/local/bin You will then need to edit this file to set the internal variable SPARTAN_PATH to the correct location of your application. You can now run Spartan from the command line as described above. For example: $ spartan --submit my-methane.spardir
^Back to Top^

Document Structure
Spartan can read and write a number of file formats. The format described here can be thought of a "directory based dot-Spartan file format" and by tradition has the extension ".spardir". To ensure this is the default file format in the GUI check the 'Directory Based' radio button found in "Options / Preferences /Miscellaneous Platform / Document Style" pane. Once this is set, new files created by the Spartan GUI will be readable by common shell tools.

Each Spartan molecule-list will now be a directory on the disk. For example, if the user created a Spartan document containing methane and saved it as "My-Methane" a new directory will appear on the disk called "My-Methane.spardir/". I will refer to this as a "Spartan Document Directory". Each Spartan Document Directory can contain multiple molecules. There will be a number of files and sub-directories in this directory. Only those relevant to backend submission will be discussed here but other files created by the GUI should not be deleted or edited by the user.

Assuming one is looking at the "My-Methane" document mentioned previously, the important files in the directory are:
Top-Directory | +- My-Methane.spardir/ ! Spartan treats this as 1 document in "File/Open" | + _spartandir ! Must exist, can be empty + sheet ! Spreadsheet information | +- M0001/ ! one directory for each Molecule in list | +- _spartan ! Must exist, can be empty +- input ! the input file, Must exist +- archive ! contains wavefunction, result of calculation +- proparc ! contains result of property calculations +- output ! contains the text results of the calculation +- voutput ! contains more verbose text results | +- Graphics/ ! directory holds volumes and surfaces | +- Graphic1 +- Graphic2
There are some other files that Spartan will create that you should be aware of
- _locked, _inuse :
  Files Spartan uses to indicate that Spartan has this document open. Do not delete or create unless you know what you are doing. Do not edit any of the files in a directory in which these files are present as you can cause the Spartan GUI to crash.
- Calculations, Commands, Geometry, JobLog :
  Binary files used by Spartan. If you edit the input file you should delete these files as they are dependent on each other, and if they are not in sync, the Spartan GUI can crash.

^Back to Top^

Input File Format
The input file is the file which you will most likely edit. It contains initial geometry, bonding information, and all keywords used to control the calculation. The best way to discuss this format is via example, in this case the water molecule. (The exclamation point and the characters following are not part of the file, and are shown only to document the file).
```
C MP2 STO-3G FREQ                     ! line 1
  mp2den                              ! line 2
Sample Water Calculation              ! line 3
0 1                                   ! line 4
 1   0.7758166   0.0000000  0.4665839 ! cartesian section
 8   0.0000000   0.0000000 -0.0816959
 1  -0.7758166  -0.0000000  0.4665839
ENDCART
ATOMLABELS                            ! label section(optional)
"H1"
"O1"
"H2"
ENDATOMLABELS
HESSIAN                               ! bonding information
   -1   -2   -1                       ! ..atom info
    1    2    1                       ! ..bond info
    2    3    1
ENDHESS
BEGINPROPIN                           ! property keywords
  PRINTIR
ENDPROPIN
BEGINPREFERENCES                      ! preference section 
  MM:CONF_SELECTION_RULE=3
  PROP:KEEPVERBOSE
ENDPREFERENCES
```
- Line 1:
  Contains the main keywords. Must begin with a 'C'.
- Line 2:
  Contains extra keywords, may be empty.
- Line 3:
  A comment, is ignored.
- Line 4: Charge and Multiplicity of the whole molecule/system.
- Cartesian section
  atomic number and Cartesian coordinates of each atom. The units of the coordinates are Angstroms. Section must end with the ENDHESS line.
- Label Section
  Names for each atom. This section is optional
- Bonding information
  This section is optional. It is required for molecular mechanics calculations, mechanics Hessian (used in nearly all geometry optimization, when the HESS= keyword is not used). If it exists it consists of two parts
  1. Atom information: one integer for each atom, but no more than 12 values one a single line. These numbers are used internally by the GUI in building. In most cases these can be ignored. Setting to each negative one (-1) is a good default.
  2. Bond information: 3 integers per line, the first two are the atom index of the bonded atoms. (One is the first atom in the geometry section, two is the second etc.) The third integer on the line is the bond type; 1, 2 and 3 for single, double, and triple bonds respectively. We use 5 to indicate aromatic or delocalized bonds.
- Property Section
  Property keywords are placed here. The BEGINPROPIN and ENDPROPIN lines are mandatory.
- Preference Section
  Keywords which are set via the preferences dialog in the GUI.
- Other optional sections
  - Constraint section:
  - Energy Profile section:
    First and last lines are DYNCON and ENDDYNCON respectively.
  - Torsion section:
    First and last lines are CONFORMER and ENDCONFORMER respectively.
  - Frozen atoms:
    First and last lines are FROZEN and ENDFROZEN respectively. A list of atoms which are marked as frozen follow. No more than 12 atom indices per line.
There are many keywords mentioned in the manual. The best way to decide which keyword goes where is to experiment with the Spartan GUI: Enter a keyword, or toggle a check-box in the Calculations dialogue, write the molecule, and see what the keyword is and where it goes in the input file.

This input file is the "Spartan input (*.spinput)" file type which you can export via the "File/Save As.../Save as type:" GUI command.

^Back to Top^

Archive File Format

This file contains the archive of a quantum or molecular mechanics calculation: various counters, the atomic numbers and coordinates (in Bohr) and the energy (HF/classical and post-HF). If quantum mechanics was used, the file also contains the complete basis set, wavefunction, post-HF density matrix correction and the Hessian matrix. If an open-shell calculation was performed, both alpha and beta spin information is included. A sample archive for water is described below:


SPARTAN AB INITIO PROGRAM: SGI/R4K      Release 5.0.0                          
SAMPLE WATER CALCULATION                                                       
   3   7   4  12   0   1   7  -1 RMP2(FC) STO-3G          NOOPT    FREQ C2V
GEOMETRY
  1     1.4660815     0.0000000     0.8288795
  8     0.0000000     0.0000000    -0.2072199
  1    -1.4660815     0.0000000     0.8288795
BASIS   
   0   3   1   1   0
   0   3   4   2   0
   1   3   7   2   0
   0   3  10   3   0
   3.4252509140D+00
   2.7693435508D-01   0.0000000000D+00   0.0000000000D+00   0.0000000000D+00
   6.2391372977D-01
   2.6783885160D-01   0.0000000000D+00   0.0000000000D+00   0.0000000000D+00
   1.6885540399D-01
   8.3473671127D-02   0.0000000000D+00   0.0000000000D+00   0.0000000000D+00
   1.3070932136D+02
   4.2519432768D+00   0.0000000000D+00   0.0000000000D+00   0.0000000000D+00
   2.3808866053D+01
   4.1122944245D+00   0.0000000000D+00   0.0000000000D+00   0.0000000000D+00
   6.4436083132D+00
   1.2816225515D+00   0.0000000000D+00   0.0000000000D+00   0.0000000000D+00
   5.0331513186D+00
  -2.3941300493D-01   1.6754501959D+00   0.0000000000D+00   0.0000000000D+00
   1.1695961248D+00
   3.2023423540D-01   1.0535680438D+00   0.0000000000D+00   0.0000000000D+00
   3.8038896000D-01
   2.4168555455D-01   1.6690287909D-01   0.0000000000D+00   0.0000000000D+00
   3.4252509140D+00
   2.7693435508D-01   0.0000000000D+00   0.0000000000D+00   0.0000000000D+00
   6.2391372977D-01
   2.6783885160D-01   0.0000000000D+00   0.0000000000D+00   0.0000000000D+00
   1.6885540399D-01
   8.3473671127D-02   0.0000000000D+00   0.0000000000D+00   0.0000000000D+00
ENERGY  
  -7.4959271540D+01  -7.4993411582D+01
WAVEFUNC
  -2.0233344751D+01  -1.2657988180D+00  -6.2940743815D-01  -4.4164943623D-01
  -3.8764493539D-01   6.0301540490D-01   7.6622899695D-01
  -6.0840634470D-03   9.9409981344D-01   2.6780239994D-02   0.0000000000D+00
   0.0000000000D+00   4.2442216736D-03  -6.0840634470D-03
  -1.6023099960D-01   2.3289125928D-01  -8.3179307465D-01   0.0000000000D+00
   0.0000000000D+00  -1.2654175095D-01  -1.6023099960D-01
  -4.4152455494D-01   0.0000000000D+00   0.0000000000D+00  -6.0023108135D-01
   0.0000000000D+00   0.0000000000D+00   4.4152455494D-01
   2.6904896098D-01   1.0021468939D-01  -5.2332421061D-01   0.0000000000D+00
   0.0000000000D+00   7.9404871325D-01   2.6904896098D-01
   0.0000000000D+00   0.0000000000D+00   0.0000000000D+00   0.0000000000D+00
   1.0000000000D+00   0.0000000000D+00   0.0000000000D+00
   8.0736305459D-01   1.3564493939D-01  -9.0864445567D-01   0.0000000000D+00
   0.0000000000D+00  -7.1421030455D-01   8.0736305459D-01
  -8.4260085185D-01   0.0000000000D+00   0.0000000000D+00   1.0090439443D+00
   0.0000000000D+00   0.0000000000D+00   8.4260085185D-01
MP2DENS 
   2.3184583611D-02   2.5913220898D-03   3.0087759217D-04  -1.6059300399D-02
  -2.3995529227D-03   1.6948091254D-02  -1.3757260484D-02   4.2859180983D-18
   2.5651694571D-17   2.1915354611D-03   5.0171046792D-17   1.1207150667D-17
  -1.0352974904D-16   2.6415614202D-16  -1.0032754107D-03  -4.1929556069D-03
  -1.5151371818D-04   2.6493252235D-03  -3.0909447624D-17  -2.4496630088D-16
  -1.2896121937D-02   2.0541175527D-03   2.5913220898D-03  -1.6059300399D-02
   1.3757260484D-02   1.6877514720D-16  -4.1929556069D-03   2.3184583611D-02
HESSIAN 
   9
   5.6340005314D-01
   0.0000000000D+00  -2.9381622667D-02
   3.4957608866D-01   0.0000000000D+00   2.9295870043D-01
  -5.4424379245D-01   0.0000000000D+00  -4.1467164881D-01   1.0884872880D+00
   0.0000000000D+00   4.2508057046D-02   0.0000000000D+00   0.0000000000D+00
  -8.5015340480D-02
  -2.8448038281D-01   0.0000000000D+00  -3.0912987652D-01   0.0000000000D+00
   0.0000000000D+00   6.1825756686D-01
  -1.9156112227D-02   0.0000000000D+00   6.5095525140D-02  -5.4424379245D-01
   0.0000000000D+00   2.8448038281D-01   5.6340005314D-01
   0.0000000000D+00  -1.3126821189D-02   0.0000000000D+00   0.0000000000D+00
   4.2508057050D-02   0.0000000000D+00   0.0000000000D+00  -2.9381622667D-02
  -6.5095525140D-02   0.0000000000D+00   1.6172269185D-02   4.1467164881D-01
   0.0000000000D+00  -3.0912987652D-01  -3.4957608866D-01   0.0000000000D+00
   2.9295870043D-01

Line 1 & 2 The first line specifies which program generated the archive. If a Spartan module is used, the version number is included. The second line is the molecule's title (or blank if omitted).

Line 3
The third line contains various control information:

Number of Atoms.
Number of basis functions (NBASIS).
Number of shells.
Number of primitive gaussians.
Molecular charge.
Multiplicity.
Number of molecular orbitals (NORB).
Error flag, 0 means archive is ok for analysis.
String containing level. i.e. RHF, UMP2(FC), SVWN, etc.
String containing basis. i.e. STO-3G, 6-31G(*) etc.
Job type. A short string, i.e. NOOPT,OPT,TSOPT,XOPT.
Frequency flag, either "FREQ" or empty.
Symmetry group, i.e. C1, C2, D2H, etc.

In Fortran, the following format statement is used: format(8i4,1x,a8,1x,a15,1x,a8,1x,a4,1x,a3) The corresponding C printf would be: printf("%4d%4d%4d%4d%4d%4d%4d%4d %8s %15s %8s %4s %3s\n",...

GEOMETRY
The fourth line contains the GEOMETRY header, with the atomic numbers and coordinates given on successive lines (same order as the .input file). It is VERY important to note that the coordinates in the archive file are in BOHR, not in ANGSTROM for both classical and quantum chemical calculations.

BASIS
If a quantum calculation was performed, the next line contains the BASIS header. Two types of entries follow this header, shell definitions and gaussian definitions (paired entries):

Shell type: 0=S, 1=SP or P, 2-D
Number of primitives
Gaussian index (1-based)
Atomic center
Pure Flag: 0=SP or 6D, 1=P or 5D(pure)

After these indices, the shell paired entries contain the exponent on the first line and the exponents on the second.

ENERGY
Following the ENERGY header the HF/classical and post-HF energies (zero if unavailable). These are in whatever units the program which generated the archive uses, so care must be taken to make sure all units are consistent when working with archives.

WAVEFUNCTION
The wavefunction section, indicated by the WAVEFUNC header, contains thermo-energies and the mo-coefficients (real numbers, 4 to a line). There are NBASIS mo-energies, and NORB*NBASIS mo-coefficients. If an open-shell calculation was performed, these are the alpha-spin values - there will be a BETA keyword separating the beta-spin values.

MP2DENS
The next header, MP2DENS, appears when the post-HF density matrix correction was saved (MP2DEN keyword in Spartan's ab initio module for example). This header is followed by the lower-triangular correction matrix (real numbers, 4 to a line, dimensioned (NBASIS*(NBASIS+1)/2)). Again, if an open-shell calculation was performed, these are the alpha-spin values - there will be a BETA keyword separating the beta-spin values.

HESSIAN
Finally, the HESSIAN header identifies the second-derivative matrix. This is generated in one of two ways: as accumulated during an optimization and as obtained via a frequency calculation. The first line contains a single integer, NVAR - the number of variables associated with the Hessian matrix. The Hessian itself is stored as a lower-triangular matrix.

^Back to Top^

Property archive file format

A file which contains most 'property values' calculated in Spartan. These are accessible from the "Properties dialogue" and from the spreadsheet function of the Spartan GUI. It is a relatively simple text file with a simple BEGIN ... END structure. The first two lines of the proparc file used as version information and should be ignored. The standard format should be relatively easy to parse by 3rd party programs but a quick BNF of the format is as follows

  PROP <typeDesc>  <name> {
     {    =     { <number>  |  <string> }            }  |
     { <length> [ <vec-len> ]  BEGIN $ <values> $END }   }

  <values>   == { <value>^n                       |
                  <number> <number> <value>^(v-2)  |
                  <string> <value>^(v-1)           }
  <value>    == { <number> | <string> }
  <typeDesc> == <BaseType>[:<modifier>]*
  <BaseType> == { VALUE  | STRING }
  <Modifier> == { BYATOM | BYBOND | STATIC | <name> }
  <string>   == { <name> | "any-characters-with-escaped-quote" }
  <name>     == a word with no spaces
where:
    white space : spaces or new lines
    $           : newline
    [..]        : optional
    [..]*       : optional repeating
    { a | b }   : one of 'a' or 'b' is allowed
    n           : <length>*<vec-len|1>
    v           : <vecl_len|1>
    a^m         : 'a' is repeated 'm' times
    {}[]        : braces simply group values, not printed

  PROP .. BEGIN and PROP .. = <value> are all grouped on 1 line.

By convention, first column should be a space, except for lines beginning with PROP and END. There are also a number of deprecated formats which might be found in older Spartan files.

^Back to Top^

Phil Klunzinger

Author: Phil Klunzinger