Aten v1.6 (r1511)

Very few Linux distributions have guides in this section - if you wish to contribute details of your own experience for the benefit of others, get in touch.

bob@pc:~> sudo apt-get install subversion
bob@pc:~> svn co http://aten.googlecode.com/svn/trunk ./aten-latest
bob@pc:~> cd aten-latest
				

bob@pc:~> sudo apt-get install autotools-dev libtool autoconf automake g++ libreadline5-dev \
	libqt4-gui libqt4-opengl libqt4-core libqt4-dev

bob@pc:~> ./autogen.sh
bob@pc:~> ./configure
				

bob@pc:~> make
				

bob@pc~	> ./autogen.sh
				

bob@pc~> ./configure --with-qt=framework
				

bob@pc~> ./configure --with-qt=fink
				

bob@pc~> ./configure --with-qt=fink --with-qtdir=path
				

bob@pc~> cmake /path/to/source/for/aten
				

bob@pc:> mkdir aten-build
bob@pc:> cd aten-build
bob@pc:~/aten-build> cmake /home/bob/aten-0.99-713
				

As already mentioned, Aten comes with a selection of filters ready to import and export a fair number of file formats (you can write your own - see the chapter on Filters). These filters should be found automatically, but if they are not Aten can be given their location in one of two ways:

Any filters written or obtained by the used can be placed in their ~/.aten/filters directory. See the next section.

User filters and preferences files should be placed in a .aten directory in your home directory (it must be created by hand). Within this directory can exist the user preferences file prefs.dat exists, along with another directory named filters which is used to store custom filters, or those currently under development by the user.

Two important things. Firstly, short options (e.g. '-b', '-d', etc.) may not be concatenated into one long specification of a short option (i.e. '-bd') - they must be given separately as '-b -d' or they will not be recognised. Secondly, the order of the given switches is important! Commonly, the actions of command-line switches and arguments do not depend on order, however in Aten this is not the case. For example:

bob@pc:~> aten --nobond test1.xyz test2.xyz
		

will load the models 'test1.xyz' and 'test2.xyz', preventing recalculation of bonds between atoms in both. However:

bob@pc:~> aten test1.xyz --nobond test2.xyz
		

will only prevent recalculation of bonds for the second model. The reason for acting on switches and arguments in the order they are encountered on the command line is to allow for flexibility, especially when using Aten as a non-graphical processor (for examples of this type of usage, see the resources section of the website).

Note: The position of debug switches or those affecting the verbosity of the program has no bearing on the timeliness of their effect - they are dealt with first by Aten regardless of where they appear in the program's arguments.

A filter is a plain text file containing one or more C-style programs that permit the input or output of data in a specific format. For example, a purely model-oriented filter file may contain two filters, one to read in files of the specified format, and one to write the data out again. Each individual filter is given a short nickname, a shell-style glob, and possibly several other bits of data that allow files to be recognised (if the file extensions defined for it are not enough).

Different filters that recognise the same file type may be provided if necessary, each performing a slightly different set of import or export commands (if it is not convenient to do so within a single filter), and all will appear in the drop-down list of filters in file dialogs within the program. Note that in batch, command-line, or scripting mode, filters are either selected automatically based on the filename, extension, or contents, or picked by matching only the associated nickname. In the former case, the first filter that matches the extension is used.

A basic stock of filters is provided with Aten and installed with the program - several default locations are searched for these filters on startup. Alternatively, if Aten fails to find these filters, or you wish to point it to a suitable directory by hand, either the $ATENDATA environment variable may be set to the relevant path (on Windows, this variable is set by the installer) or the --atendata command-line option may be used to provide the path.

Additional filters may be placed in a user's '.aten' directory, e.g. ~bob/.aten/filters/.

Filters that possess the same ID or nickname as other filters of the same type may be loaded simultaneously, with the last to be loaded taking preference over the other. Thus, an importmodel filter nicknamed 'xyz' from Aten's installed filter stock will be overridden by one of the same nickname present in a user's '.aten/filters' directory. Similarly, both these filters will be overridden by one of the same nickname loaded by hand from the command line (with the --filter switch). Note that this only holds true for filters referenced by nickname or determined automatically by Aten when loading data - from the GUI all filters are available in the file dialogs.

Filter definitions are made in a filter file in a similar way to declaring a user subroutine or function. The 'filter' keyword marks the start of a filter definition, and contains a list of properties in parentheses that define the subsequent filter, its name, and how to recognise the files (from their filenames and/or contents) that it is designed for. The definition of the filter to import XYZ-style model data is as follows:

filter(type="importmodel", name="XMol XYZ Coordinates", nickname="xyz", extension="xyz", glob="*.xyz", id=3)
{
	commands
	...
}
		

The comma-separated list of properties defines the type of filter ('type="importmodel"') and how to recognise files of that type (e.g., 'extension="xyz"'), amongst other things. The full list of possible properties is as follows:

exact="coords"
			

exact="results,output"
			

extension="xyz"
			

extension="xyz,abc,foo"
			

glob="*.doc"
			

id

When separate import and export filters for a given file type have been provided it is prudent to associate the pair together so that Aten knows how to save the data that has just been loaded in. Each filter has a user-definable integer ID associated with it that can be used to link import and export filters together. For example, if a model import filter has an ID of 7, and a model export filter also has this ID, then it will be assumed that the two are linked, and that a model saved with export filter 7 can be subsequently loaded with import filter 7. If the ID for a filter is not set it defaults to -1, and it is assumed that no partner exists and the file cannot be directly saved back into this format.

For example:

id	=13
			

	See Also:
	Supported formats to find out the list of currently-assigned ids

name="SuperHartree Coordinates File"
			

nickname="shart"
			

nickname="zyx"
			

search="UberCode Version 20.0"
			

search="SIESTA"
			

search=""GAMESS VERSION = 11 APR 2008 (R1)"
			

type="importgrid"
			

type="exportmodel"
			

within=50
			

zmap

By default, it is assumed that the commands which create new atoms will be given a proper element symbol from which to determine the atomic number. Case is unimportant, so 'na', 'Na', and 'NA' will all be interpreted as atomic number 11 (sodium). Where element symbols are not used in the model file, there are several alternative options that tell these commands how to convert the element data they are passed into atomic numbers. For example, the 'ff' style is particularly useful when loading in coordinate files which contain forcefield atom type names that do not always correspond trivially to element information (e.g. DL_POLY configurations).

For example:

zmap="numeric"
			

indicates that atomic numbers are provided in place of element names and no conversion should be performed.

	See Also:
	ZMapping types for a list of the available zmapping methods

When writing data, in many cases all the information that the filter wants to write is contained within the current model, for example when outputting simple file formats such as xyz or Aten's own akf. In other cases ther may be additional data for which would be nice to have some control over, and which lays beyond atoms and bondes. The best example is probably the input formats for nearly all ab initio codes which contain (as well as the atomic coordinates) statements and additional data necessary to control the running of the code itself. It is not a problem to write out 'static' lines of control commands from the output filter, but it would of course also be nice to be able to tailor this output from within the GUI (or from the command-line). This can be achieved by assigning values to variables in the filter through the use of filter options.

Any number of options can be defined, and some relatively simple but useful control over the layout of the related GUI controls is possible.

vartype var = option(string name, string type, ...);
			

string runtype = option(""Run Type"", ""combo"", "check,run,restart,analyse", 2);
			

DL_POLY, being a molecular dynamics code, stores its configuration and trajectory data in separate files. Filters are supplied with Aten that read in DL_POLY trajectories, and so this example will revolve around those filters.

filter(type='importtrajectory', name="Example Filter Template")
{
	int readheader()
	{
		// Code to read header data goes here
	}
	
	int readframe()
	{
		// Code to read frame data goes here
	}
}
			

filter(type='importtrajectory', name="Example Filter Template")
{
	int readheader()
	{
		// No header, so just return
		return 1;
	}
	
	int readframe()
	{
		// Code to read frame data goes here
	}
}
			

Formatted output corresponds to output to either the screen or to files, and is used in the following commands:

Note that all are called the same as their ((Delimited Reading and Writing|delimited counterparts)), but with the addition of an 'f' at the end of the name.

printf("Hello");
			

printf("Hello");
printf("There.");
			

HelloThere.
			

printf("Hello\n");
printf("There.");
			

Hello
There.
			

printf("Hello\nThere\n.");
			

Hello
There
.
			

Being able to print simple text strings is good, but not nearly enough. The first argument to the 'printf' command must always be a character string, but any number of additional arguments may be provided. Now, these additional arguments may be number constants, other character strings, variables, etc., and may be output in the resulting string by referencing them with 'specifiers' placed within the first example. One example of a specifier is '%i' which is shorthand for saying 'an integer value' - if used within the character string provided to printf, the command will expect an integer constant or variable to be provided as an additional argument. For example:

printf("This number is %i.\n", 10);
		

will print

This number is 10.
		

Similarly,

int value = 1234;
printf("Constant is %i, variable is %i.\n", 10, value);
		

will print

Constant is 10, variable is 1234.
		

There are other specifiers suitable for different types of data. The way data is presented by the specifier in the final output can also be controlled (e.g. for numerical arguments the number of decimal places, presence of exponentiation, etc., can be defined).

Formatted input corresponds to input from either files or string variables, and is used in the following commands:

Note that the meaning of the formatting string changes slightly here - in essence, the type and formats of the specifiers are used to break up the supplied string into separate arguments, which are then placed in the provided corresponding variable arguments. When reading in string data, note that blank characters are significant and will be retained. To strip trailing blank characters (spaces and tabs) when reading a fixed-length string in a format, supply the length as a negative number.

The list of allowable variable specified corresponds more or less exactly to that found in C, with some small omissions and minor inclusions. For a full list see the reference page at cplusplus.com or cppreference.com. The list of printf features that are not (currently) supported in Aten are as follows:

As well as the mostly complete standard set of specifiers provided by C, Aten also includes some other useful specifiers that may be used in formatted input and output.

Formatting strings (or 'format specifiers') can be used to specify the layout of data items on a line when reading or writing data, but if the data are separated by whitespace characters such as spaces or tabs (or, alternatively, commas), such 'delimited' data can be read in more easily. In such cases, it is not necessary to know beforehand the number of characters taken up by each item on the line, since the delimiters separate adjacent data items. A simplified method for reading and writing can be employed in these cases.

Commands providing delimited reading and writing are:

Note that all are called the same as their formatted counterparts, but minus the 'f' at the end of the name.

Na      0.0     1.0     0.0
Cl      1.0     0.0     0.0
Na      0.0    -1.0     0.0
			

double x,y,z;
string el;
while (!eof()) { readline(el,x,y,z); newatom(el,x,y,z); }
			

for (atom i = aten.model.atoms; i; ++i) writeline(i.symbol,i,rx,i.ry,i.rz);
			

double x,y,z;
string el;
while (!eof())
{
	readnext(el);
	readnext(x);
	readnext(y);
	readnext(z);
	newatom(el,x,y,z);
}
			

TODO

Bonds between atoms can be calculated and removed en masse with the bonding toolbar, encompassing either the whole model or just the current atom selection. The bond tolerance used in the calculation of bonds can be set with the spin control. Automatic detection of multiple bonds can be performed with the augment tool.

Table 5.2. Bonding Toolbar Icons

	Recalculate bonding in the current model
	Clear bonding in the current model
	Recalculate bonding in the current model, restricted to the current atom selection
	Clear all bonds between atoms in the current selection
	Based on the current connectivity, determine multiple bonds
N/A	The spinbox controls the bonding tolerance to use when automatically determining which atoms are bound - if the distance between two is less than the sum of their defined radii multiplied by this factor, then a bond exists

The primary function of the build toolbar is to allow for drawing, deletion, and transmuting of individual atoms and bonds using the mouse. Setting the type of bond requires pairs of atoms to be clicked sequentially after the tool is activated. Similarly, transmuting atoms to the currently selected element and removing atoms simply involve clicking on atoms in the main view.

Table 5.3. Build Toolbar Icons

	Draw unbound atoms
	Draw chains of atoms by clicking and dragging the mouse
	Add pre-defined molecular fragments to the model
	Delete individual atoms, or hold Shift to delete all bonds attached to clicked atoms
	Transmute clicked atoms to the currently selected element, or hold Shift to transmute all atoms of the same element as the clicked atom
	Add hydrogens to clicked atoms
	Transmute all selected atoms to the currently selected element
	Satisfy the natural valencies of all C, N, and O atoms by adding hydrogen atoms
	Set the current element to hydrogen
	Set the current element to carbon
	Set the current element to nitrogen
	Select the current element from the periodic table
N/A	The current element set by the final button (which defaults to oxygen) is set from the last element chosen in the periodic table.
	Create (or change to) a single bond between two clicked atoms
	Create (or change to) a double bond between two clicked atoms
	Create (or change to) a triple bond between two clicked atoms

The general drawing style for all atoms in all models is determined by the selection made on the Style toolbar. This does not clear any specific styles set for individual atoms, it only overrides them. The final 'Individual' style draws atoms in their associated styles (which defaults to 'Stick').

Table 5.4. Draw Style Toolbar Icons

	Atoms are not explicitly drawn unless they possess no bonds, bonds are drawn using simple lines
	Atoms and bonds are drawn as tubes
	Atoms are drawn as uniformly-sized spheres, with bonds drawn as tubes
	Atoms are drawn as spheres whose size depends on their atomic radii, bonds are drawn as tubes
	Each atom is drawn according to its own assigned style

Standard Cut, Copy, Paste, and Delete functions that work on the atom selection of the current model. Only the last copied (or cut) selection of atoms is remembered. Pasted atoms are created with exactly the same coordinates as when they were copied - i.e. no translation of the pasted atoms is made to avoid other atoms in the target model. The newly pasted atoms become the current selection.

Table 5.5. Edit Toolbar Icons

	Copy the current atom selection to Aten's clipboard
	Copy the current atom selection to Aten's clipboard and then delete it
	Paste the contents of the clipboard to the current model at the original coordinates. The pasted atoms then become the current selection
	Delete the current atom selection

Quick tools to load, save, and close models.

Table 5.6. File Toolbar Icons

	Create a new, empty model
	Load an existing model into Aten
	Save the current model under its original filename
	Save the current model under a different filename
	Close the current model (prompting to save first if changes have been made)

The minimiser can be run quickly from here (using the current method and associated settings from the minimiser window) and the total energy and forces of the current model calculated. A list of all loaded forcefields reflects the current default forcefield and allows selection of a new one.

Table 5.7. Forcefield Toolbar Icons

	Minimise the energy of the current model
	Calculate the total energy of the current model
	Calculate the atomic forces in the current model
N/A	The combobox lists all currently loaded forcefields, and represents the default forcefield to use if no other has been assigned specifically to a model or pattern

Simple measurements of distances, angles, and torsions between picked atoms or the current selection of atoms is possible from the measure toolbar.

Table 5.8. Mouse Toolbar Icons

	Measure distances between clicked atoms
	Measure angles between clicked atoms
	Measure torsion andlges between clicked atoms
	Measure all bond distances between atoms in the current selection
	Measure all bond angles between atoms in the current selection
	Measure all torsion angles between atoms in the current selection

For multi-button mice each button can be assigned an invidual action (select, rotate model etc.). For those who use single-button rats, this toolbar changes the function of the first (or left) button between select / interact, rotate model, and translate model. Selecting these buttons overwrite the stored action for the left button in the Preferences.

Table 5.9. Mouse Toolbar Icons

	The left button selects and interacts with atoms
	The left button rotates the view or selection
	The left button translates the view or selection

The standard mode for whichever mouse button is the interactor (by default its the left button) is Box Select, where atoms or groups of atoms are selected by click-dragging a box on the main canvas. This and other selection types are available here.

Table 5.10. Select Toolbar Icons

	Atoms may be (de)selected by clicking on them individually, or selected en masse with a click-hold-drag
	Bound fragments are selected by clicking on a single atom within that fragment
	Clicking on a single atom selects all atoms of the same element
	The current selection is expanded by following bonds attached to any select atoms.
	Select all atoms in the current model
	Deselect all atoms in the current model
	Toggle the selection state of all atoms

Tool windows are shown and hidden through the buttons on the tool stack toolbar. See the Tool Windows section.

Table 5.11. Tool Window Toolbar Icons

	Show the atomlist window
	Show the Z-Matrix editor window
	Show the surface/grid management window
	Show the fragment library
	Show the glyph edit window
	Show the building tools window
	Show the atom transformation tools
	Show the atom positioning tools
	Show the atom geometry tools
	Show the atom selection window
	Show the cell definition window
	Show the cell transformation window
	Show the disordered builder window
	Show the energy minimiser window
	Show the forcefield management woindow
	Show the command window

If a trajectory is associated to the current model, the trajectory toolbar allows to skip through frames and playback the trajectory.

Table 5.12. Trajectory Toolbar Icons

	Toggle between view of trajectory frames and the parent model
	Return to the first frame in the trajectory
	Go to the previous frame in the trajectory
	Start / stop sequential frame playback of the trajectory
	Go to the next frame in the trajectory
	Skip to the last frame in the trajectory
N/A	The slider and spinbox represent the current frame position, and provide quick access to other frames

Atom List Window

Figure 5.1. Atom List Window

Build Window

Miscellaneous build tools and options are located on the Build window.

Figure 5.2. Build Window

Cell Define Window

Figure 5.3. Cell Definition Window

Allows the user to edit the unit cell specification of the current model, assign a crystallographic spacegroup, and perform spacegroup packing according to the spacegroup.

Whether or not the current model possesses a unit cell is determined wholly by the 'Has Cell' checkbox - if checked, the current model is periodic, if not, then it is an isolated atomic globule (or a 'molecule', if you prefer). If the model has a cell, its lengths (in Angstroms) and angles (in degrees) are displayed on the left-hand side, and may be freely edited (the volume of the current cell is displayed just below). Any changes made are immediately applied to the model. Any changes made here are immediately applied to the current model.

The spacegroup assigned to the current model can be changed and removed here. On its own, an assigned spacegroup is just a number - no modifications to the atoms are made by changing the assigned spacegroup. Packing of atoms, however, is a different matter. Once a spacegroup is assigned, symmetry-equivalent atoms may be generated by use of the 'Pack' button. This assumes that the current contents of the model represents the symmetry-unique set of atoms (i.e. the minimal generator set which, along with the spacegroup and unit cell, defines the entire crystal).

Cell Transform Window

Transformations of the unit cell and its contents can be made here, encompassing geometric scaling of the cell (and atoms contained within) and replication of the system in three dimensions.

Replicate

Figure 5.4. Cell Transform Window, Replicate Panel

The Replicate panel allows the current cell to be replicated along its three principal axes in both positive and negative directions. The six inputs represent negative and positive replication values for each direction -- most of the time its probably only useful to consider the positive (right-most) replication directions. Note that the numbers define the ''additional'' cells that will be created in addition to the original one. So, if all numbers are left at zero the original cell will remain untouched. Entering a value of 1 for each positive direction will give a 2x2x2 supercell of the original cell, and so on.

Atoms in the model are folded into the unit cell prior to replication, unless the Fold Atoms checkbox is unticked. Similarly, atoms that exist outside of the cell after replication are trimmed unless the Trim Atoms checkbox is unchecked.

Scale

Figure 5.5. Cell Transform Window, Scale Panel

The Scale panel allows the principal axes of the current unit cell to be arbitrarily scaled, along with the cell's contents. If a valid pattern description exists for the model, then the positions of individual molecules or bound fragments within the cell are scaled relative to their centres of geometry - all intramolecular distances within molecules remains the same as before the scaling. If this is undesirable (or unintended) then performing the scaling with no pattern definition will scale the position of each atom separately.

Command Window

The command window allows commands or sequences of commands to be run and stored for later use, allows management and execution of scripts, and provides access to searchable command help.

Prompt

Figure 5.6. Command Window, Prompt Panel

Any command or compound command can be entered in the bottom editbox and will be executed immediately. This command will then be added to the list above, and can be single-clicked to return it to the editbox for tweaking or re-editing, or double-clicked to execute it again. The list of stored commands is saved when Aten exits, and loaded back in when restarted.

Scripts

Figure 5.7. Command Window, Scripts Panel

Scripts can be loaded in from here and executed at will by double-clicking individual scripts in the list or selecting multiple scripts and clicking the 'Run Selected' button. Any script files loaded in this way are remembered when Aten exits and are loaded back in when restarted. All scripts can be reloaded from disk (if, for example, changes have been made to one or more files after they were loaded in) by clicking the 'Reload All' button.

Command Index

Figure 5.8. Command Window, Command Index Panel

All of Aten's commands can be searched from this panel, and the syntax and arguments displayed. Useful!

Disordered Builder Window

Figure 5.9. Disordered Builder Window

The Disordered builder page allows the creation of randomly-oriented collections of molecules in periodic cells (e.g. gases, liquids, mixtures etc.) from individual molecule components. The list at the top of the panel gives all the currently-loaded molecules that are suitable for use as components – the main criterion is that they do not themselves possess a unit cell. Next to the name of each model in the list is a number, which specifies the number of molecules that you want to be inserted into the target model, and two checkboxes that allow certain Monte Carlo move types to be prevented for individual molecules. The first checkbox, if unticked, prevents rotations (both on insertion and in standard Monte Carlo moves) of the model, while the second checkbox, if unticked, will prevent the standard Monte Carlo translation move from being used with this model. If the number is set to zero (the default for all components) then no insertions of that model will be attempted.

The disordered builder needs a model with a cell already defined to insert into, and should be selected as the current model in the main view. The Build button will only be available if the current model is periodic. Note that the current model does not have to be empty to begin with, but if it is not, a forcefield must be assigned (or must be available) that describes completely the existing contents.

By default, all components are randomly distributed over the entire space of the model cell, but can be restricted to specific regions of the cell if required. For the model currently selected in the list of components, the Region panel may be used to define an area of the unit cell in which to restrict insertions of the model. If regions are defined for one or more models, these will displayed in the current model's cell.

The number of cycles determined the number of times to perform a round of Monte Carlo moves (see XXX), while the VDW Scale sets a temporary scaling factor to use in the energy calculation.

Forcefield Window

Figure 5.10. Forcefield Window

Forcefield files are managed through the Forcefield window. A list of currently-loaded forcefields is shown at the top, the default forcefield (if any) is indicated with a tick, and is used whenever a forcefield is required by a process but none has been linked to the target model. The forcefield selected in the list is the current forcefield, and the one used by all other actions on the page. Forcefields are loaded, unloaded, and edited with the buttons immediately underneath the list.

Fragment Library Window

Figure 5.11. Fragment Library Window

When in fragment drawing mode, the Fragment Library window presents a list of all the available fragment models, and whichever is selected represents the current fragment to add in to the model. The current fragment is 'attached' to the mouse pointer when moving over the main canvas, and shows a preview of what will be the orientation and position of the fragment when a left-click is made.

Geometry Window

Figure 5.12. Geometry Window

The geometry window can be used to explicitly set the distance, angle, or torsion of a group of selected atoms. Exactly two, three, or four atoms must be selected for the individual panels to be available. The atoms need not be connected with bonds. The panels on this window are also used when setting geometry from the atom context menu.

Each page is essentially the same, displaying the atom IDs which make up the current target geometry. The new value of the geometry can be set explicitly, or increased/decreased by 'nudging' the current value by a specified amount.

Table 5.13. 

	Add a specified amount to the current value
	Subtract a specified amount from the current value

Glyphs Window

The glyphs window allows new glyphs to be created by hand, or existing glyphs in the model to be managed, edited, and deleted.

Figure 5.13. Glyphs Window

All glyphs in the current model are listed to the left. Selecting one will allow its properties to be edited on the right. The type of glyph can be changed also. Colours for individual glyph data (i.e. points) may be changed through the colour controls associated to each.

Grids Window

The Grids Tool Window provides management for grid data sets owned by the different models. All grid data sets held by the current model are displayed here, and. The appearance of individual grids may be changed, and axes / cutoffs changed. Grid data can also be cut, copied, and pasted to different models.

Data / Cutoff

Figure 5.14. Grids Window - Data / Cutoff Page

Various data on the current grid is displayed here, including the minimum and maximum values present in the data, the number of points, and the total (unnormalised) sum of data values encompassed by the current isosurface.

For grids in which the data is 'symmetric' about a cutoff of zero (as is the case for orbital data, for example) a secondary surface can be enabled with the 'Secondary' checkbox. This second isosurface is controlled by the second lower/upper cutoff values. Note that the secondary isosurface can be drawn for any data set - it can be used, for example, to draw a second surface at a different cutoff to the primary cutoff, for example.

Origin / Axes

Figure 5.15. Grids Window - Origin / Axes Page

The associated origin and axes to the currently selected grid can be modified here. In this way grid data may be arbitrarily flipped, stretched, and sheared, and its position in the local space of the model changed. All changes made are reflected immediately in the main view.

Style

Figure 5.16. Grids Window - Style Page

The general appearance of the selected grid can be modified in the Style page, with the main rendering style set with the combo box (see grid styles for a list of possible styles). Optionally, the bounding cuboid of the grid data may be highlighted ('Outline Volume' checkbox). The 'Periodic' checkbox influences the way 3D surfaces are drawn close to the boundaries of the grid. If unchecked, a 'gap' will appear near to the edges of the grid volume since there is inufficient data with which to generate gradient information. If checked, data points on the opposite site of the grid will be used in this region (useful, for instance, in the case of orbital information calculated from 3D periodic QM codes).

In the simplest case the points, triangles, or polygons that make up the rendered grid data are drawn in a single colour. This colour is determined by the upper of the two colour selections. If the data is symmetric (see above) and is composed of 'positive' and 'negative' parts, then the uppermost colour selection is applied to the positive part, and the lower colour selection is applied to the negative part. In addition, the transparency of the rendered data (if drawn in the Solid style) is determined by the Alpha value (0 being fully transparent, and 255 being fully opaque).

Should a more useful colouring scheme be desired than the grid may be rendered using a colour scale, in which case the isovalue (if volumetric) or height (if a 2D grid) determines the colour of the data point. To do so, enable the checkbox next to the CScale widget, and select the ID of the colour scale to use (from the ten definable in the program).

Shift

Figure 5.17. Grids Window - Shift Page

The Shift page can be used to 'translate' the grid data points along each axis of the data set allowing, for instance, isosurface features of interest in a periodic grid to be displayed in a more central position. Note that no modification of the actual grid data is performed - the effect is entirely visual. The 'Atom Shift' group allows translation of selected/all atoms in the parent model to be moved at the same time, so as to correlate them with the new positions of the grid data.

Orbitals

Figure 5.18. Grids Window - Orbitals Page

Not implemented yet.

Minimiser Window

Figure 5.19. Minimiser Window

The Minimiser Window allows models to be energy-minimised w.r.t. their atomic coordinates. Several methods are available, listed in the drop-down list at the top-left. Each may have its own set of options, which are displayed in the panel underneath the convergence criterion for the energy and RMS force.

Atom Position Window

Tools for the absolute positioning of atoms are available here. All work on the current selection of atoms in the current model.

Centre Atoms

Figure 5.20. Atom Position Window, Centre Panel

The Centre page allows the centre of geometry of the current selection to be positioned at absolute coordinates. The desired position is entered in the three input boxes, or can be defined from the geometric centre of a selection of atoms (prior to the positioning of a different set). Any (or all) of the Cartesian axes may be 'locked' preventing coordinate adjustment along parcitular directions.

Table 5.14. 

Define target coordinates from centre of geometry of current atom selection

Flip About Axis

Figure 5.21. Atom Position Window, Flip Panel

The Flip page mirrors the positions of atoms in the current selection through its centre of geometry in either the X, Y, or Z directions. Note that this tool currently works only along the Cartesian axes, and does not take into account the shape of any defined cell.

Table 5.15. 

	Flip coordinates in the X direction
	Flip coordinates in the Y direction
	Flip coordinates in the Z direction

Translate

Figure 5.22. Atom Position Window, Translate Panel

Translations of atoms within model (local), world (view) and cell frames of reference can be performed in the Translate page. The group of directional buttons move the selected atoms along the relevant axis within the selected frame of reference, and by the amount specified in the Shift control. For model and world reference frames the Shift control specified the number of Angstroms moved along the axis in each step. For the cell reference frame it defines the fractional cell distance moved in each direction.

Table 5.16. 

	Translate selection along the positive X axis of the current frame
	Translate selection along the negative X axis of the current frame
	Translate selection along the positive Y axis of the current frame
	Translate selection along the negative Y axis of the current frame
	Translate selection along the positive Z axis of the current frame
	Translate selection along the negative Z axis of the current frame

Shift (Along Axis)

Figure 5.23. Atom Position Window, Shift Panel

The axis along which to move the current selection is define in the left half of the Shift page. Furthermore, the axis may be defined by two clicked atoms in the main window. The supplied vector need not be normalised, as this is done automatically. This also means that un-normalised vectors are always displayed, so defining the axis from two clicked atoms will use the actual positional difference of the two atoms as the shift vector. Since the axis is normalised prior to the shift taking place, the shift distance 'delta' is the actual distance the atoms are moved by.

Table 5.17. 

	Define vector from two selected atoms
	Normalise the currently defined vector to 1.0
	Move selected atoms 'delta' Angstroms along the defined vector
	Move selected atoms 'delta' Angstroms backwards along the defined vector

Reposition

Figure 5.24. Atom Position Window, Reposition Panel

The reposition page allows the centre of geometry of a selection of atoms to be moved from a reference coordinate (defined by the 'Reference' box) to a destination coordinate (defined by the 'Target' box).

Table 5.18. 

Define source or target coordinates from centre of geometry of current atom selection

Select Window

The select window provides a means to quickly access the capabilities of the select and deselect commands from within the GUI. The total number of atoms selected along with their empirical formula is also displayed.

Figure 5.25. Select Window

Atom Transform Window

For a selection of atoms, rotational or matrix-based transformations can be applied through the Transform Window.

Rotation About Arbitrary Axis

Figure 5.26. Atom Transform Window, Rotate Panel

The Rotate panel allows an origin and a rotation axis about this origin to be defined about which to rotate atom selections. The origin and axis may be entered manually, can be determined from a current atom selection, or defined by the click-selection of two atoms. Defining the rotation axis from the current selection will set the axis to the vector between the currently-defined origin and the centre of geometry of the current atom selection. Rotations of atom selections about this axis/origin combination are then made by defining the angle of rotation (in degrees) and then applying the rotation either clockwise or anticlockwise.

Table 5.19. 

	(Left) Define rotation origin from current atom selection
	(Right) Define rotation axis as the vector between current origin and centre of current selection
	(Right) Define rotation axis from two picked atoms
	Rotate current atom selection clockwise around defined axis/origin
	Rotate current atom selection counter-clockwise around defined axis/origin

Matrix Transformation

Figure 5.27. Atom Transform Window, Matrix Transform Panel

From here a 3x3 transformation matrix can be applied to the current atom selection, and with a specific coordinate origin (not necessarily the centre of geometry of the selection).

Table 5.20. 

	Define the matrix rows from pairs of picked atoms
	Normalise the matrix row to be a unit vector
	Orthogonalise the matrix row with respect to the other rows
	Generate the matrix row from the cross product of the other two
	Define transformation origin from the centre of geometry of the current atom selection
	Define transformation origin to be the centre of the current unit cell

Matrix Conversion

Figure 5.28. Atom Transform Window, Matrix Convert Panel

It is possible to transform the orientation of a given set of atoms if a suitable pair of source and destination matrices are defined - this page attempts to do so! The 'Source' matrix defines what should be considered the current frame of reference for the current set of coordinates, while the 'Target' matrix defines what the 'Source' matrix should become after the operation.

Table 5.21. 

	Define the matrix rows from pairs of picked atoms
	Normalise the matrix row to be a unit vector
	Orthogonalise the matrix row with respect to the other rows
	Generate the matrix row from the cross product of the other two
	Define transformation origin from the centre of geometry of the current atom selection
	Define transformation origin to be the centre of the current unit cell

ZMatrix Window

The z-matrix window allows the z-matrix for the current model to be viewed and its variables edited. Any changes made are reflected immediately in the coordinates of the model.

Figure 5.29. ZMatrix Window

Keywords, variables, and function names are case sensitive, so 'for' is different from 'For' (all internal commands in Aten are in lowercase). Individual commands must be separated by a semicolon ';', and newlines are optional. For example:

int i; printf("Hello there.\n"); i = 5;
		

...and...

int i;
printf("Hello there.\n");
i = 5;
		

...are equivalent. Whitespace characters (spaces and tabs) are ignored and may be present in any amount in any position in the code.

Individual lines or parts of them may be commented out. The presence of either the hash symbol '#' or '//' in a line means 'ignore rest of line'. Note that the '/*...*/' commenting style is not supported.

There are several standard rules for variables within Aten:

Since variables are strongly-typed, trying to set an integer variable from a string will not work since these are incompatible types. However, standard C-style string conversion functions are available - see String Commands.

So, to initialise some variables, assign them values, and print them out, we would do the following:

int i;
double result;

i = 10;

result = i*5.0;

printf("i multiplied by 5.0 = %f\n", result);
		

In addition to the standard 'int' and 'double' types, a 'string' variable exists for the storage of arbitrary-length character strings, and do not need to have a length specified on their creation (they will adjust dynamically to suit the assigned contents). Literal character strings should be surrounded by double-quotes. A set of variable types exist that are able to contain references (not copies) of various objects within Aten, e.g. atoms, models, unit cells, etc. Variables of these types are declared in exactly the same way as normal variables (see Variable Types for a list of available types). A 'vector' type is provided for convenience and stores a triplet of real ('double') values. There is no boolean type - use an 'int' instead - but the built-in constants 'TRUE' and 'FALSE' may be used in assignment, etc., and correspond to the integer values '1' and '0' respectively.

All variables will default to sensible values (e.g. empty string, numbers equal to zero) on initialisation. To create a variable with a specific value simply do the following:

int i=1,j=2,k=1001;
double myvar=0.0, angle = 90.0;
		

Arrays of most variable types are allowed (some, for instance the aten type, don't really make sense as an array). Arrays are requested by providing a constant size (or an expression) in square brackets after the name:

int values[100], i = 4;
double q[i];
		

Here, two arrays are created - an array of 100 integer numbers called 'values', and an array of four floating point numbers called 'q'. Array indices always run from 1 to the size of the array, unlike C in which arrays run from 0 to N-1, and Fortran in which it is possible to specify custom lower and upper indices for an array.

Arrays can be initialised to a simple value on creation, setting all elements to the same value...

string s[4] = "Nothing";
		

...or each element to a different value using alist enclosed in curly brackets:

string s[4] = { "Nothing", "Nicht", "Nada", "Not a sausage" };
		

Also, all array elements can be set to the same value with a simple assignment:

int t[100];
t = 40;
		

	See Also:
	String Commands for commands to convert to/from string data Variable types for reference information on the non-standard types

Several predefined constants exist, and may not be overridden by variables of the same name. All predefined in constants are defined using uppercase letters, so the lower case equivalents of the names may be used as variables, functions etc.

In addition, all element symbols found in the input will be seen as their equivalent integer atomic number. So, instead of having to provide short strings containing the element name to, for example, the transmute command, simply the capitalised element name itself may be used. Thus...

transmute("Xe");
transmute(Xe);
transmute(54);
		

...are all entirely equivalent.

As with C, variable scope is employed in Aten meaning that a variable may be local to certain parts of the code / filter / script. In addition, two or more variables of the same name (but possibly different types) may peacefully co-exist in different scopes within the same code / filter / script. Consider this example:

int n = 4, i = 99;
printf("%i\n", i);
if (n == 4)
{
	int i = 0;
	printf("%i\n", i);
}
printf("%i\n", i);
		

...will generate the following output:

99
0
99
		

Why? Well, even though two variables called i have legitimately been declared, the second declaration is made within a different block, enclosed within a pair of curly braces. Each time a new block is opened it has access to all of the variables visible within the preceeding scope, but these existing variable names may be re-used within the new block in new declarations, and does *not* affect the original variable. Hence, in the example given above, after the termination of the block the final printf statement again sees the original variable i, complete with its initial value of '99' intact. Note that if a variable is re-declared within a scoping block, there is no way to access the original variable until the scoping block has been closed. Blocks can be nested to any depth.

For functions that take arguments, the argument list should be provided as a comma-separated list in parentheses after the function name. For instance:

newatom("C", 1.1, 0, 4.2);
		

Arguments may be constant values (as in this example), variables, arithmetic expressions, or any other function that returns the correct type. For functions that (optionally) do not take arguments, the empty parentheses may be omitted. A list of all functions, their arguments, and their return types is given in the command reference.

All functions return a value, even if it is 'no data' (the equivalent of 'void' in C/C++). For instance, in the example above the newatom command actually returns a reference to the atom it has just created, and this may be stored for later use:

atom a;
a = newatom("C", 1.0, 1.0, 1.0);
		

However, if the return value of any function is not required then it may simply be 'forgotten about', as in the example prior to the one above.

User-defined functions can be defined and used in Aten, taking a list of variable arguments with (optional) default values. The syntax for defining a function is as follows:

type name ( arguments ) { commands }
		

type is one of the standard variable types and indicates the expected return value type for the function. If no return value is required (i.e. it is a subroutine rather than a function) then type should be replaced by the keyword 'void':

void name ( arguments ) { commands }
		

Once defined, functions are called in the same way as are built-in functions. The name of the function obeys the same conventions that apply to variable names, e.g. must begin with a letter, cannot be the name of an existing keyword, function, or variable. The arguments are specified in a similar manner to variable declarations. A comma-separated list of types and names should be provided, e.g.:

void testroutine ( int i, int j, double factor ) { ... }
		

Our new subroutine 'testroutine' is defined to take three arguments; two integers, i and j, and a double factor. All three must be supplied when calling the function, e.g.

printf("Calling testroutine...\n");
int num = 2;
double d = 10.0;
testroutine(num, 4, d);
printf("Done.\n");
		

When defining the function/subroutine arguments, default values may be indicated, and permit the function to be called in the absence of one or more arguments. For instance, lets say that for our 'testroutine', the final argument factor is likely to be 10.0 on most occasions. We may then define a default value for this argument, such that if the function is called without it, this default value will be assumed:

void testroutine ( int i, int j, double factor = 10.0 ) { ... }

printf("Calling testroutine...\n");
int num = 2;
testroutine(num, 4);
testroutine(num, 4, 20.0);
printf("Done.\n");
		

Both methods of calling 'testroutine' in this example are valid.

For functions defined to return a specific type, at some point in the bpdy of the function a suitable value should be returned. This is achieved with the return keyword. Consider this simple example which checks the sign of a numeric argument, returning '1' for a positive number and '-1' for a negative number:

int checksign ( double num )
{
	if (num < 0) return -1;
	else return 1;
}
		

If an attempt is made to return a value whose type does not match the type of the function, an error will be raised. Note that, once a return statement is reached, the function is exited immediately. For functions that do not return values (i.e. those declared with 'void') then return simply exits from the function - no return value need be supplied.

Arithmetic operates in the same way as in C, and utilises the same operator precedence etc. Similarly, comparison operators (less than, equal to etc.) are the same as those found in C.

For variables in Aten that are of reference type (i.e. the non-standard types) various sub-variables and functions may be accessed in the same way class members are utilised in C++. Each non-standard variable type is listed here along with the types and descriptions of their available subvariables / members.

In the same way that class members are accessed in C/C++, subvariables of reference types are accessed by use of the full stops '.' between member names. For instance, the atom type allows all the information of a given atom to be accessed. The following example illustrates the process of retrieving the third atom in the current model, finding its coordinates, and subsequently adjusting them:

atom a = aten.model.atoms[3];
vector v = a.r;
printf("Old coordinates are: %f %f %f\n", v.x, v.y, v.z);
v.x += 4.0;
a.r = v;
printf("New coordinates are: %f %f %f\n", a.rx, a.ry, a.rz);
				

Lots of paths are used here. Firstly, the global aten variable is used to get access to the current model and grab a reference to its third atom (aten.model.atoms[3]). Then, the coordinates of this atom are placed in a vector v by requesting the r subvariable from the stored atom reference. We then adjust the vector and store the new coordinates in the atom.

All subvariables can be read, but not all can be written back to - these are read-only subvariables, and are indicated with 'ro' in the Access column in the following tables.

Function members act in the same as subvariable members except that they take one or more arguments enclosed in parentheses immediately following the member name, just as command functions do.

The 'master' class type, 'aten', is there to provide access to various other structures such as the list of loaded models, preferences, element data etc. It is available at all times from any command, script, or filter, and is always called 'aten'.