# Equations in Spartan

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

Ekcal="E (kJ/mol)"*@kj2kcal
will take the value in the "E (kJ/mol)" column (presumably an energy) and multiply by 4.184 (the conversion from kcal to kJ).

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:

"E/area"=@ENERGY/@CPKAREA
The quotes around the label are optional in most cases, but necessary if the name contains any spaces. Columns with no equation are often used for experimental data or comments. For example:
"Toxicity"

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.

• Standard operators
Arithmetic
Operation
Boolean Operations
0.0 for 'false'
1.0 for 'true'
-subtraction  >=greater than or equal to
*multiplication  <less than
/division  <=less than or equal to
^raise to a power      == equal to
!=not equal to
|or
&and

• Mathematical Functions

Mathematical Functions
@ABS(x)absolute value    @SQRT(x) square root
@SIN(x)sine @ASIN(x) arcsine
@COS(x)cosine @ACOS(x) arccosine
@TAN(x)tangent @ATAN(x) arctangent
@EXP(x)exponential @LN(x) natural logarithm
@LOG(x)base 10 logarithm

• The conditional "?:" operator

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. for example:

( @Energy > 500 )?'Too Big':@exp(-@Energy/12.5)/32.903
will return the string "Too Big"; if the energy is greater than 500, Otherwise it will return a Boltzmann-like value.

• Molecular properties

..

SyntaxDescriptionUnits
@CPKAREAArea of molecule using CPK radiiÅ3
@ELECTRONEGATIVITYEVQSAR descriptor, -(HOMO+LUMO)/2eV
@HARDNESSEVQSAR descriptor, -(HOMO-LUMO)/2eV
@POLARIZABILITYthe alpha polarizability parameter
@HYPERPOLARIZABILITYbeta hyperpolarizability parameter
@HOMOEV
@HOMOEV(-n)
Energy of the HOMO, or the n/th orbital below the HOMOeV
@HOMOBETAEV
@HOMOBETAEV(-n)
Energy of the HOMO, or the n/th orbital below the beta HOMO. Only available for open shell systems.eV
@LUMOEV
@LUMOEV(+n)
Energy of the LUMO, or the n/th orbital above the LUMOeV
@LUMOBETAEV
@LUMOBETAEV(+n)
Energy of the β LUMO, or the n/th orbital above the LUMOeV
@INERTIA(i)The principal moments of inertia from largest (i=1) to smallest (i=3)
@LOGPCLogP from the Ghose-Crippen model
@LOGPVLogP from the Villar model
@LABELThe name of the molecule given by the user.
@NAMEThe name of the molecule used in the SMD database
@STORThe internal label for the molecule
@SCOREThe 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.

• Geometric values

The arguments to the following functions are the names of specific atoms. For Example:

@ANGLE(H2,O1,H1)

SyntaxDescriptionUnits
@ANGLE(i,j,k)Angle involving atoms i,j,kdegrees
@DIHEDRAL(i,j,k,l)The torsion angle involving atoms i,j,k,ldegrees
@DISTANCE(i,j)Distance involving atoms i,jÅ
@LENGTH(bond_name)The distance of the bondÅ
@ISOTOPE(i)mass number of atom i
@OVALITYA 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

• Atomic properties

There are a number of atomic properties. The argument to these functions is the name of the atom.
SyntaxDescription
@MULLIKEN(i) The Mulliken charge.
@NATURAL(i) The Natural charge.
@ELECTROSTATIC(i) The best fit electrostatic charge.
@ATOMNUM(i)The atomic number.

• the "@PROP" function

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
SyntaxDescription
CALC_START_TIMESTAMPThe 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_OThe most negative "EPN value" of all Oxygen atoms in the molecule
EPN_NThe most negative "EPN value" of all Nitrogen atoms in the molecule
INITIAL_KEYWORDSThe 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_STRINGThe symmetry of the molecule
QM_DIPOLEThe 3 components of the dipole moment, in Debye. i.e. 'Dy=@PROP(QM_DIPOLE,2)' is the y component.
Atomic @PROP keywords
SyntaxDescription
ATOMIC_CPK_AREA
ATOMIC_CPK_VOLUME
EPN_AUThe "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

• Atomic properties in the atomic labels 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:

=(@ATOMNUM==8)?@F(@PR(atomic_cpk_volume)):' '
(The @F is necessary because both branches of the conditional must be the same type, in this case both are strings.)

• Summary functions

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.
SyntaxDescription
@SUMThe sum of the columns
@AVGThe average value of the column
@STDEVThe standard deviation of the column
@MINThe smallest value in the column
@MAXThe largest value in the column
These functions will also take the name of a column or an equation, if it is desired to use different values. It is also possible to use the functions (with an argument) in column headers and other cells, but this is generally discouraged as overuse of these functions can negatively impact the performance/speed of GUI response time.

• Specialty functions

SyntaxDescription
@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.
@ROWWith 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.
@BoltzDist(Temp)
@BoltzDist(Temp,Degen-Column)
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.

• Using vectors in plots

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.

• Conversion Factors and Constants
Constant
Description
@ANGS2AUAngstroms to bohrs (atomic units)
@AU2ANGSBohrs (atomic units) to Angstroms
@EV2HARTeV to hartrees (atomic units)
@EV2KCALeV to kcal/mol
@EV2KJeV to kJ/mol
@HART2EVhartrees (atomic units) to eV
@HART2KCAL    hartrees (atomic units) to kcal/mol
@HART2KJhartrees (atomic units) to kJ/mol
@KJ2EVkJ/mol to eV
@KJ2HARTkJ/mol to hartrees (atomic units)
@KJ2KCALkJ/mol to kcal/mol
@piπ   (3.1415..)