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.

- Equations in the spreadsheet
- Standard operators
- Mathematical functions
- The Conditional "?:" Operator
- Molecular Properties
- Atomic Properties
- The "@PROP" Function
- Atomic Properties in the Atomic Labels
- Summary Functions
- Specialty Functions
- Using Vectors in Plots
- Conversion Factors and Constants
- Full List of Supported Functions

**Equations in the spreadsheet**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 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:**"E/area"=@ENERGY/@CPKAREA****"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.

^^Back to Top^^

**Standard operators**Arithmetic

OperationBoolean Operations

0.0 for 'false'

1.0 for 'true'+ addition > greater than - 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

^^Back to Top^^

**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

^^Back to Top^^

**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:

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

^^Back to Top^^

**Molecular properties**..

Syntax Description Units @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 @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) @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.

^^Back to Top^^

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

@ANGLE( **H2,O1,H1**)Syntax Description Units @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}

^^Back to Top^^

**Atomic properties**There are a number of atomic properties. The argument to these functions is the name of the atom.

Syntax Description @MULLIKEN(i) The Mulliken charge. @NATURAL(i) The Natural charge. @ELECTROSTATIC(i) The best fit electrostatic charge. @ATOMNUM(i) The atomic number.

^^Back to Top^^

**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 Syntax Description 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 Syntax Description ATOMIC_CPK_AREA ATOMIC_CPK_VOLUME 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

^^Back to Top^^

**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:

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

^^Back to Top^^

**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.

Syntax Description @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

^^Back to Top^^

**Specialty functions**Syntax Description @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". @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.

^^Back to Top^^

**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.

^^Back to Top^^

**Conversion Factors and Constants**Constant Description @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 @pi π (3.1415..)

^^Back to Top^^

**Full List of Supported Functions**A full list of supported functions can be found in the "Formula Editor" dialogue by clicking the in the lower right. (The easiest way to get to the Formulat editor is via the Display/Formulas menu.)

phil Last modified: Thu Mar 5 14:01:46 PST 2009