One of the more powerful tools in Spartan is the equation evaluator. This is used heavily in the spreadsheet, but also has important uses for atom labels and in plots. By default these equations are hidden, but one can use these equations to customize the look of spreadsheets and plots. For example, any cell and column header in the spreadsheet can be double-clicked and edited.
Equations in Spartan should be familiar to most Excel or Lotus users. The standard operators (+,-,*,/) are recognized and other columns can be referenced by name. If the column name has a space in it the name must be quoted using the double quote ("). Strings are quoted with single quotes ('). Built in functions are preceded by the @ symbol. The result of a function can be a real number or a string. For example the equation
The remaining part of this document provides in-depth discussions on particular strategies for using equations in Spartan.
The most common use of equations is in the spreadsheet. Column headers should begin with a name, optionally followed by an equal sign and an eqution. For example:
The first character of a cell should be an equal sign. An equation or a value should follow. If the cell is empty the equation in its column header is used.
0.0 for 'false'
1.0 for 'true'
|-||subtraction||>=||greater than or equal to|
|/||division||<=||less than or equal to|
|^||raise to a power||==||equal to|
|!=||not equal to|
|@ABS(x)||absolute value||@SQRT(x)||square root|
|@LOG(x)||base 10 logarithm|
A conditional operator can be used as an "If/Then/Else"
branch. The expression before the question mark "?" is
evaluated, and if it is true (not equal to zero) the
expression between the question mark "?" and the colon ":"
is returned. If the first expression is equal to zero, the
expression after the colon ":" is evaluated.
|@CPKAREA||Area of molecule using CPK radii||Å3|
|@ELECTRONEGATIVITYEV||QSAR descriptor, -(HOMO+LUMO)/2||eV|
|@HARDNESSEV||QSAR descriptor, -(HOMO-LUMO)/2||eV|
|@POLARIZABILITY||the alpha polarizability parameter|
|@HYPERPOLARIZABILITY||beta hyperpolarizability parameter|
|Energy of the HOMO, or the n/th orbital below the HOMO||eV|
|Energy of the HOMO, or the n/th orbital below the beta HOMO. Only available for open shell systems.||eV|
|Energy of the LUMO, or the n/th orbital above the LUMO||eV|
|Energy of the β LUMO, or the n/th orbital above the LUMO||eV|
|@INERTIA(i)||The principal moments of inertia from largest (i=1) to smallest (i=3)|
|@LOGPC||LogP from the Ghose-Crippen model|
|@LOGPV||LogP from the Villar model|
|@LABEL||The name of the molecule given by the user.|
|@NAME||The name of the molecule used in the SMD database|
|@STOR||The internal label for the molecule|
|@SCORE||The alignment score calculated from the similarity package.|
|"Align Scores"||As a column header (with no equation) will display the score for the most recent interactive alignment.|
The arguments to the following functions are the names of specific atoms. For Example:
|@ANGLE(i,j,k)||Angle involving atoms i,j,k||degrees|
|@DIHEDRAL(i,j,k,l)||The torsion angle involving atoms i,j,k,l||degrees|
|@DISTANCE(i,j)||Distance involving atoms i,j||Å|
|@LENGTH(bond_name)||The distance of the bond||Å|
|@ISOTOPE(i)||mass number of atom i|
|@OVALITY||A measure of how asymmetric the molecule is. A sphere is 1.0.|
|@PAREA(A,B,...)||partial surface area of a space-filling model due to all atoms of type "A,B, ...", where "A,B, ..." are element symbols. If a colon follows the atom symbol (i.e. "O:") hydrogens attached to the element are also included. Polar surface area is usually defined as the area of nitrogens and oxygens and the hydrogen atoms attached to them. (i.e. @PAREA(N:,O:) )||Å2|
There are a number of atomic properties. The argument to these functions is the name of the atom.
|@MULLIKEN(i)||The Mulliken charge.|
|@NATURAL(i)||The Natural charge.|
|@ELECTROSTATIC(i)||The best fit electrostatic charge.|
|@ATOMNUM(i)||The atomic number.|
There are a number of development properties available that have proven useful. While these are not fully supported (meaning they may change in future release) they are still of interest and can be accessed with the '@PROP' function. The @PROP function has 4 formats, depending on whether the property is a single value, an array, a vector, or an atom based property. Single value properties take just 1 argument, the name of the property. For example '@PROP(SYM_STRING)' will display the symmetry of the molecule. An example of a vector is the 6 values of the charge quadrapole. The first (XX) component can be accessed via '@PROP(QM_QUADPOLE,1)'. For atom based property the @ATOM() should be used; for example '@PROP(ATOMIC_CPK_AREA,@ATOM(C1))'.
Below is a list of some of these properties. Not all properties are available from all computational methods, so care should be taken when using these keywords.
|Molecular @PROP keywords|
|CALC_START_TIMESTAMP||The time the calculation started.|
|CALC_START_TIMESTAMP2||Another spelling for the start time. This version sorts better.|
|CALCULATION_MACHINEHOSTNAMEP||The name of the machine the job was run on. Useful with the cluster package of Spartan.|
|EPN_O||The most negative "EPN value" of all Oxygen atoms in the molecule|
|EPN_N||The most negative "EPN value" of all Nitrogen atoms in the molecule|
|INITIAL_KEYWORDS||The keywords use. This can be used in lists with multiple job types. For example, 'Method=@PROP(INITIAL_KEYWORDS,2)' is the method used, i.e. HF, B3LYP etc.. 'Basis=@PROP(INITIAL_KEYWORDS,3)' is the basis used.|
|SYM_STRING||The symmetry of the molecule|
|QM_DIPOLE||The 3 components of the dipole moment, in Debye. i.e. 'Dy=@PROP(QM_DIPOLE,2)' is the y component.|
|QM_QUADPOLE||The 6 components of the traceless quadrapole moment in Debye-Ang. (XX,YY,ZZ,XY,XZ,YZ)|
|Atomic @PROP keywords|
|EPN_AU||The "Electrostatic Potential at the Nuclei". Often used as a predictor of Hydrogen Bonding strength. (Dimitrova et. al. SAR and QSAR in Environmental Research, Vol. 1594) Aug 2004.)|
|MM_ATOM_TDESC||The MMFF94 atom type descriptor|
It is possible to display the results of atom-based equations on the screen. Equations can be entered via the "Model/Configure..." panel. An example is shown below. Note that instead of using the '@PROP' function the '@PR' is used to generate a vector.
For large molecules the display can become cluttered. A trick using the conditional and the format operator can be specified. For example, to print the atomic volume for only Oxygen atoms (atomic number 8) the following equation can be used:
It is possible to add 'summary' rows at the bottom of the spreadsheet. While any equation or value can be entered in these rows and/or cells one the following summary functions are most useful. Typically these take no argument and refer to the appropriate column.
|@SUM||The sum of the columns|
|@AVG||The average value of the column|
|@STDEV||The standard deviation of the column|
|@MIN||The smallest value in the column|
|@MAX||The largest value in the column|
|@ATOM(atom-name)||The integer id for an atom. Used in conjunction with the @PROP function|
|@FITVAL(fit-name)||column of fit values from a regression analysis.|
|@REF(i,x)||The value of 'x' (a column or an equation) from row 'i'.|
|@ROW(molecule_name)||The row number of a given molecule. A useful 1st argument to the @REF function.|
|@ROW||With no arguments @ROW will return the number of the current row. The first row is row # 1.|
|@F(equation)||"Format": Converts a number into a string.|
|@ACCU(column-name)||Like @SUM but only sums from the first row to the current row.|
|@DB("Label",Equation)||Evaluate Equation with data from the database. For example, @F("T1",@Energy()*@hart2kj) will return the T1 energy the given molecule, assuming that this has been stored in Spartan's database.|
|@KEYWORDS||The current keywords and options set in the "Setup->Calculations" panel.|
|@ISNULL(Equation)||Returns true if the "Equation" evaluates to the "empty cell".|
|@SYMBOL(Equation)||Treat the result of the Equation as a symbol. Useful in passing column headers into "symbol" requiring functions such as @ATOMPAIR() etc.|
|The "Boltzmann Distribution" function will calculate the equilibrium of entries in the spreadsheet at a given temperature. (The default temperature is 298.15 K.) If degeneracy data is available (i.e. from a systematic conformational MMFF94 run) that is used to weight the entries in the distribution correctly. Alternatively, a second argument can be given which can contain a spreadsheet column header giving other degeneracy values. If the second argument is "1" degeneracy is ignored.|
Equations can also return vectors of numbers. Vectors are used primarily in the plotting features of Spartan. Plotting the Gibb's free energy is a good example of how this can be used. The following recipe can be done on any completed molecule where the IR spectra has been calculated.
Enter the Plot Properties dialogue and select the "Free form" plot type. Make sure Formulas is checked, and hit the Edit button. Type "T=@for(0,900,10)" and hit the Enter key. This will give you a temperature range from zero to 900 K with 10 degree increments. Next enter the formula for Gibb's free energy by typing "G=@G0(T)" and hitting the Enter button and then the OK button. Now select the "T" for the X axis and "G" for the Y axis. A Plot of Gibbs free energy (G) versus Temperature (T) will be displayed.
|@ANGS2AU||Angstroms to bohrs (atomic units)|
|@AU2ANGS||Bohrs (atomic units) to Angstroms|
|@EV2HART||eV to hartrees (atomic units)|
|@EV2KCAL||eV to kcal/mol|
|@EV2KJ||eV to kJ/mol|
|@HART2EV||hartrees (atomic units) to eV|
|@HART2KCAL||hartrees (atomic units) to kcal/mol|
|@HART2KJ||hartrees (atomic units) to kJ/mol|
|@KJ2EV||kJ/mol to eV|
|@KJ2HART||kJ/mol to hartrees (atomic units)|
|@KJ2KCAL||kJ/mol to kcal/mol|