The SPACE Module


Integrated Computational Chemistry Erin N. Thornton, Chance R. Younkin,
Environment Molecular Science Research Center John B.Nicholas, Donald R. Jones,
Pacific Northwest Laboratory {1}Anthony C. Hess
Richland, WA 

[ Pacific Northwest Laboratory is operated for the U.S. Department of
Energy by Battelle Memorial Institute under Contract DE-AC06-76RL0 1830.]


Table of Contents

Introduction
SPACE Data Input
Customizing SPACE
Appendix 1: Setting up new user of SPACE
Appendix 2: The SPACE directory structure
Appendix 3: The SPACE module environment

The SPACE Module User Guide

SPACE Module is an AVS graphics module designed for crystallographic and molecular research. The program models crystals, surfaces and molecules. Some editing capabilities are provided. For periodic systems (i.e. crystals and surfaces), SPACE Module accesses space group symmetry operations to identify symmetry-related atoms. For crystals, SPACE Module also implements the Buerger reduction algorithm, allowing users to find cells of highest symmetry. Miller planes may be displayed by which crystals may be cleaved and subsequently saved as surfaces. The user can display important precalculated volumetric data in SPACE Module, such as electron densities and electrostatic surfaces. Using a variety of methods, SPACE Module can compute the electrostatic potential of any chemical system based on input point charges. SPACE Module also implements an algorithm that approximates the Connelly dot surface algorithm. The AVS isosurface module is used to visualize this data. The "SPACE Module Tutorial" is the easiest way to become familiar with SPACE Module.

The purpose of this guide is to inform you about the Application Visualization System (AVS) software, SPACE. It includes information on installing SPACE, using AVS, using SPACE, importing data to Space, and customizing SPACE in AVS.

Before using SPACE Module you should become familiar with AVS. Section one of the "AVS User's Guide" provides an introduction to AVS. In addition, section two of the "AVS Tutorial Guide " is suggested reading since SPACE Module uses the AVS geometry viewer.

Return to the Table of Contents



SPACE Module Data Input

After becoming familiar with SPACE you may need to know how to input data. There are two data formats, MoViz Model (.mvm) and MoViz Volume (.mvv). The .mvm format describes molecules, surfaces, and crystals, while the .mvv format describes volumetric data.

The .mvm Format

The .mvm format is driven
by key words followed by user-specified data particular to that keyword. There are several example files in the directory "$SPACE/data/doc_models." There are a few rules that must be followed when creating the .mvm file:

  1. Each key word must be directly followed by a colon (:).
  2. The keywords can appear in any order.
    [Not always true. Exceptions: Num_atoms must be before Atom_list and Num_bonds must be before Bond_list.]
  3. Comments begin with a # character. Anything following '#' is ignored.
  4. The file is read until keyword "stop:" or until end-of-file is reached.
Here is a listing of the keywords recognized in the .mvm format.

title:Title of structure
-optional
type:Choose crystal, surface, molecule, or polymer
-optional
-default is molecule
sg_name:Space group name
-optional
-not needed for molecule
sg_number:Space group number
-required for crystals and surfaces
-not needed for a molecule
cell_units:Choose angstroms or Bohrs
-optional
-default is angstroms
cell_lengths:Lengths of the cell axes
-not needed for molecules
-A, B, and C required for crystals
-A and B required for surfaces
cell_angles:Angles of the cell
-not used for molecules
-alpha, beta, and gamma required for crystals
-gamma required for surfaces
num_atoms:Number of atoms in the atom list
-required
atom_info: Plus additional keywords indicating the order and type of data given in the atom_list
-required
NOTE: These keywords are all on one line with spaces separating them. Also, these keywords may appear in any order, so long as the atom_list follows that line.
  1. index Number of the atom
    -optional
  2. symbol Atomic symbol
    -required if at_number is not by a colon (:).
  3. at_number Atomic number
    -required if symbol is not listed
  4. frac Fractional coordinates
    -required if cart is not listed, for crystal, surface, or polymer
  5. cart Cartesian coordinates
    -required for molecule
    -required if frac is not listed, for crystal, surface, or polymer
  6. formal Formal charge
    -optional
  7. partial Partial charge
    -optional
  8. cov_rad Covalent radius
    -optional
  9. vdw_rad van der Waal's radius
    -optional
  10. sym_op Symmetry operation that created crystal
    -optional
atom_list: Listing of atom information in order specified by atom_info.
The number of atoms in atom_list must be less than or equal to num_atoms. One line of information per atom.
-required
num_bonds:Specifies the number of bonds
-optional
-required if bond_list is used
bond_list:List the bond using atom indices
-optional
-two indices per line indicate atoms to be bonded
stop:Indicates the end-of-file
-optional

Example mvm files:

This first example is for a crystal of corundum.

#This is an example of a crystal
title: corundum
type: crystal
sg_number: 167
num_atoms: 2
cell_lengths:
4.754 4.754 12.99
cell_angles: 90.0 90.0 120.000
atom_info: symbol
frac
atom_list:
Al 0.000 0.00000 0.35228
O 0.3064 0.0000
0.250000

The second example input file is for the SiH4 molecule.

# This is an example of a molecule
title: SiH4
type:
molecule
num_atoms: 5
atom_info: index at_number cart partial
atom_list:
1 1 0.00000 0.00000 0.00000 -.03146
2 14 1.48014 0.00000 0.00000 1.2577
3 1 1.97223 1.39575 0.00000 -0.3144
4 1 1.97128 -0.69597 1.21037 -0.3145
# The fifth atom used to be an oxygen, but it is deleted
6 1 1.97412 -0.69919 -1.20695 -0.3142
num_bonds: 4
bond_list:
2 1
2 3
2 4
2 6
stop:

The .mvv Format

The .mvv format is also driven by keywords followed by user-specified data particular to that keyword. There are a few rules that must be followed when creating the .mvv file.

  1. Each keyword must be followed by a colon (:).
  2. The keywords are not case sensitive.
  3. The keywords may appear in any order.
    [Not always true. Exception: Nbr_dims must be declared before Sizes, Order, Min_extent, and Max_extent]
  4. Comments begin with a # character. Anything following '#' is ignored.
Here is a listing of the keywords recognized in the .mvv format.

mvv_title:Title of the volume file
-optional
mvm_title:The associated model's title
-optional
nbr_dims:Number of dimensions of the grid volume (usually 3)
-required
nbr_points:Number of points in the volume
-required if sizes is not listed
-required if any grid points are missing (ie non-uniform grid)
sizes:List of the size of each dimension
-required if nbr_points is not listed
order:Indicates the order in which the grid data is specified.
For example, in a three dimensional grid (nbr_dims = 3) three numbers (0, 1, 2) must appear in any order after the order keyword. These numbers correspond to X, Y, and Z respectively and determine which order the grid should be read/generated. So, an order of order: 0 1 2 implies that X varies fastest, Y second fastest, and Z slowest. If order: 2 1 0 appears on the order line, then Z varies fastest, Y second fastest, and X slowest. If order is not supplied, then 0 1 2 is assumed.
storage_info:Contains a list of keywords indicating the type of data listed after data keyword (described below)
-required if data is used
-the following keywords can appear in storage info line in any order. The order they appear in indicates the order of the data in the data section:
  1. coordinates
    Specifies that coordinates are supplied in file
  2. data
    Specifies that data values are supplied in file
  3. usable_flags
    Not usually input by user. Used by SPACE to indicate which data values and points have been filtered
format:Indicates whether format of data section is mixed or concatenated,
-optional the default value is mixed
-mixed format indicates all data values for one grid point are on one line -concatenated format indicates that the first data set is listed in it's entirety, then the second, and so on. (Currently this is not implemented)
min_extent:A coordinate representing the minimum extent of the grid
-required if grid is to be calculated at read time or if storage_info is not used
max_extent:A coordinate representing the maximum extent of the grid
-required if grid is to be calculated at read time or if storage_info is not used
coord_labels: Set labels for the coordinates of the grid
-optional
data_labels: Set labels for the data sets (fields)
-optional
nbr_fields: The number of data sets (fields)
-required
coord_type: Indicates whether the grid should be considered as a Cartesian or fractional grid
-optionalthe default is cart
-frac corresponds to a fractional grid
-cart corresponds to a Cartesian grid
probe_radius:Value used as probe radius during Surface algorithm
-optional the default is 2.0
exclude_value:Value used for exclusion during Surface algorithm
-optional the default is 100.0
include_value:Value used for inclusion during Surface algorithm -optionalthe default is 0.0
data:Indicates that no more keywords appear and data begins on next line
-optional If only grid information is stored in a file, the grid can often be specified using above key words. In this case no data will be associated with the grid and the grid will be generated within SPACE.

Example mvv file:

This example file is for Hg(OSO3H)2.

#This is an example of a .mvv file with mixed format
mvv_title: Hg(OSO3H)2
nbr_dims: 3
sizes: 2 2 2
storage_info: usable_flags data # NOTE: This specifies the order of the data below!
format: mixed
nbr_fields: 2
data:
#the first number on a line is the usable_flags, which is followed by
#two data points for each grid point
1 1.0 8.0
0 2.0 7.0
0 3.0 6.0
1 4.0 5.0
0 5.0 4.0
0 6.0 3.0
0 7.0 2.0
1 8.0 1.0

Return to the Table of Contents


Customizing SPACE

Sample .avsrc File

For users there is a sample .avsrc file in $SPACE called AVSRC. This file, if copied as is to your home directory and called .avsrc, will set your AVS environment up to point to the SPACE networks, module library, and other SPACE data. See the AVS User Guide for details on the .avsrc file.

Customizing SPACE With the .elemrc File

The .elemrc file defines van der Waal's radius, default covalent radius, the number of oxidation states with charge-radius pairs, and the color of each element. If you do not wish to use the default file, you can make a copy of a .elemrc file. The file to copy is $SPACE/ELEMRC. SPACE first looks for a .elemrc file in the current directory, then the home directory, and finally the SPACE system directory.

The .elemrc file is arranged in columns: atomic number, atomic symbol, 'van der Waal's radius (vdw), default covalent radius (def_cov), weight, number of oxidation states with charge-radius pairs, and color (rgb). The color is defined by intensities of red, green, and blue. The range of intensity is from 0.0 to 1.0, where 0.0 means the color is off and 1.0 means it is at full intensity. The default color, specified by COLOR, is 0.0, 1.0, 1.0. Other default values are VDW which is 1.0, and UNK which is 0.999. If you have copied the system file into your own .elemrc file you can customize it for your needs.

NOTE: The C preprocessor (cpp) is used to read the .elemrc file. This allows you to use the '#define' mechanism as seen in the file $SPACE/ELEMRC. See the cpp man page for details on the C preprocessor.

Return to the Table of Contents


Appendix 1: Setting up a new user of SPACE

In the .cshrc file add:

First time only:

To let SPACE default to your local data directory: setenv MY_SPACE_DATA ~/mydata

To let SPACE default to your local space group tables directory: setenv MY_SPACE_TABLES ~/mytables

Return to the Table of Contents


Appendix 2: The SPACE directory structure

The following directory structure:

space
  • AVSRC ... sample .avsrc file for SPACE
  • CSHRC ... sample .cshrc file for SPACE setup
  • ELEMRC ... periodic elements file used by SPACE software
  • ENV ... environment setup file for SPACE
  • README ... bit of documentation
  • SPACE.applns ... AVS applications file
  • avs
    • demo ... directory of AVS demo scripts for SPACE
    • modlib ... directory containing AVS module library for SPACE
    • networks ... directory containing AVS networks for SPACE
  • bin ... useful but not needed programs
  • data
    • demo_models ... directory with demo SPACE model files (mvm format)
    • demo_volumes ... directory with demo SPACE volume files (mvv format)
    • doc_models ... directory with SPACE model files (mvm format)
    • doc_volumes ... directory with SPACE volume files (mvv format)
    • tables
      • plane ... directory of plane groups runtime files
      • sym ... directory of space groups runtime files
      • sym_op.bin ... binary space group file runtime file
  • doc ... directory containing documenation
  • scripts ... directory with installation scripts

Return to the Table of Contents


Appendix 3: The SPACE module environment

To complete installation, you need to set the SPACE environment variable to <space_install_path>/space and then source the $SPACE/ENV file (see the Environment Variables below). Following that you must then run the installspace script found in $SPACE/scripts. This will already be in your path if you have sourced the $SPACE/ENV file. Then, at the UNIX prompt type:

% installspace
and follow the prompts. It's quite simple.

Environment Variables

SPACE requires some environment variables to be set before it can run. Add the following lines to your .cshrc (or equivalent) file:

setenv SPACE <space_install_path>/space
source $SPACE/ENV


Search Path

Make sure that the search path variable includes the AVS
(usually /usr/avs/bin/avs) and cpp
(usually /usr/lib/cpp or /lib/cpp) executables.

Return to the Table of Contents