Aten v1.5 (r1197)

Occasionally (and annoyingly) files have no extension at all, instead having short, fixed names, which must be checked for literally when probing files. This command defines one or more exact filenames that identify files to be acted on by this filter section. Multiple names may be given, separated by commas or whitespace. Exact filename matching is case-insensitive.

For example:

exact="coords"
			

associates any file called 'coords' to this filter.

exact="results,output"
			

associates any files called 'results' or 'output' to this filter.

Sets the filename extension(s) that identify files to be read / written by this filter. When files are being probed for their type, in the first instance the filename is examined and the extension (everything after the last '.') is compared to those defined in filter sections by this command. Multiple file extensions may be given, separated by commas or whitespace. File extension matching is case-insensitive.

For example:

extension="xyz"
			

means that files with extension '.xyz' will be recognised by this filter.

extension="xyz,abc,foo"
			

means that files with extensions '.xyz', '.abc', and '.foo' will be recognised by this filter.

Sets the file dialog filter extension to use in the GUI, and should be provided as a shell-style glob.

For example:

glob="*.doc"
			

filters any file matching '*.doc' in the relevant GUI file selector dialogs.

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

Sets the long name of the filter, to be used as the filetype description of files identified by the filter. This name will appear in the file type lists of file dialogs in the GUI, and also in the program output when reading / writing files of the type.

For example:

name="SuperHartree Coordinates File"
			

Sets a nickname for the filter, which allows it to be identified easily in the command language and, importantly, from the command line. It should be a short name or mnemonic that easily identifies the filter. No checking is made to see if a filter using the supplied nickname already exists.

For example:

nickname="shart"
			

sets the nickname of the filter to 'shart'.

nickname="zyx"
			

sets the nickname of the filter to 'zyx'.

Occasionally, checking the contents of the file is the easiest way to determining its type, and is probably of most use for the output of codes where the choice of filename for the results is entirely user-defined. For example, most codes print out a whole load of blurb and references at the very beginning, and usually searching for the program name within this region is enough to identify it. For files that are only easily identifiable from their contents and not their filename, plain text searches within files can be made to attempt to identify them. Individual strings can be given to the 'search' keyword, and multiple 'search' keywords can be provided. The default is to search the first 10 lines of the file for one or more of the defined search strings, but this can be changed with the within property.

For example:

search="UberCode Version 20.0"
			

matches the filter to any file containing the string 'UberCode Version 20.0' within its first 10 lines (the default).

search="SIESTA"
			

searches the first 10 lines of the file for the string 'SIESTA'.

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

attempts to identify output from a specific version of GAMESS-US.

The 'type' keyword must be provided an all filter definitions - an error will be raised if it is not. It specifies which class of data the filter targets (e.g. models, grid data etc.) and whether it is an import or export filter. A given filter may only have one 'type'. The possible values for 'type' are:

For example:

type="importgrid"
			

type="exportmodel"
			

Defines the number of lines to search for any 'search' string definitions (default is 10).

For example:

within=50
			

specifies that the first 50 lines should be searched for identifying strings.

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

Thus far, it has been implicity stated that the 'master' configuration and the trajectory files come necessarily as a pair - the master configuration is read in, and then the trajectory associated to it. This implies that the trajectory file is somehow tied to the master configuration - perhaps the trajectory file does not contain information such as the number of atoms or element data, and so a 'reference' configuration is necessary? Of course, this may not always be the case, and it is possible that some trajectory formats will store all the necessary information needed in order to fully generate the trajectory configurations. DL_POLY trajectories do, in fact, contain all the necessary data, but even so the master configuration is still used as a template for the trajectory data, and is used to check that the correct number of atoms are present etc. It comes down to a matter of preference as to whether the master configuration should be demanded, or whether the trajectory can itself be associated to any (even an empty) model. Remember, 'importtrajectory' filters always attach the trajectory data to an existing model.

An 'importtrajectory' filter is written in a slightly different way to other filter types. Since trajectory files may contain header data which is written once at the beginning of the file, preceeding the frame data, there are potentially two separate sets of data to read from trajectory files - header data and (individual) frame data. So, rather than putting the code to read this data directly in the main body of the filter, two functions should be defined instead, one for reading the header, and one for reading an individual frame. Note that, if a given trajectory format does not contain a header, the corresponding function may be left 'empty' (but must still be defined). The functions must be called 'readheader' and 'readframe' respectively, take no arguments, and must return an integer. A template for an 'importtrajectory' filter is thus:

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

The functions must take responsibility for informing Aten when the desired data cannot be read. Both should return a value of '1' if the data was read successfully, and should return '0' if an error is encountered.

When opening a trajectory file with an 'importtrajectory' filter, the first thing Aten does is attempt to read any header information from the file by calling the 'readheader' function defined in the filter. Since a trajectory file may not contain a header, and consists simply of individual frames back to back, in these situations the readheader() function defined in the filter should not read any data. The filter definition then becomes simply:

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

Here, the readheader() function always succeeds, so Aten always thinks it has successfully read a header, even if there isn't one.

If readheader() is successful, Aten proceeds to read the first frame (by calling the readframe() function) in order to get an idea of the size of an individual frame, and hence the total number of frames in the trajectory. Of course, this assumes that all frames take up the same number of bytes in the file, and may not always be the case, especially for plain-text trajectory files. Thus, the frame estimate output by Aten should not necessarily be taken as gospel.

Unless an error is encountered when reading the test frame (i.e. readframe() returns '0') the trajectory file is then 'rewound' to the end of the header section (start of the frame data). One of two things then happens. Since trajectory files are typically enormous (hundreds or thousands of megabytes) then it is unwise to try and load the whole trajectory into memory at once. Aten knows this, and from the estimated frame size also knows roughly how big the whole trajectory is. If the total trajectory file size is greater than an internally-defined limit (the ''trajectory cache size'') then only a single frame is stored at any one point. If the total size is smaller then this limit, the whole trajectory is cached in memory. Both have their advantages and disadvantages, as listed in the following sections.

If the trajectory is too big to be stored in memory, Aten only holds a single frame in memory at any one time. This means that:

Aten tries to minimise the seek time between frames by storing file offsets of frames it has already read in. However, since trajectory frames can be different sizes Aten never tries to 'jump' ahead in the file based on the size of a single frame. Skipping immediately to the final frame in the trajectory will, thus, read all frames along the way and store file offsets for all frames. Then, seeking to any individual frame is a much quicker process.

Although style and editing changes are forgotten between frames, the overall camera view of the model is linked to that of the master configuration and so is retained between frames. If the trajectory cannot be cached and you require changes (edits or styles) to be made to each frame (e.g. for the purposes of making a movie of the trajectory) then a script is the way to go (load frame, apply edits, save image, etc.).

If the trajectory is small enough to be stored in memory, Aten reads in all frames at once. This means that:

The size of the cache can be adjusted either from the command line with the --cachelimit switch or by setting the 'cachelimit' member of the &prefs. No check is made of the new cache limit with respect to the memory available on the machine on which Aten is running, so use with care.

In the current versions of Aten, the total trajectory size is determined from the size of the frame on disk, whereas it would be more appropriate to use the size of the frame in memory. This will change in a future release.

Formatting a string for output, as mentioned elsewhere on numerous occasions, works the same as for C. The C 'printf' command (equivalent to the command of the same name in Aten) takes a character string as its first argument, and at its simplest, this is all that is required:

printf("Hello");
			

This prints 'Hello' to the screen (minus the quotes). Importantly, however, a newline character is not printed, meaning that the next thing you try and printf will appear on the same line. For instance:

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

would output:

HelloThere.
			

The end of a character constant in the printf command does not implicitly mean 'and this is the end of the line' - you must indicate the end of the line yourself by placing '\n' at the point where you wish the line to end. So:

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

would output:

Hello
There.
			

Newlines (\n) are an example of escaped characters - the backslash '\' indicates that the following character, in this case 'n', is not to be treated as a normal 'n', but instead will take on its alternative 'meaning', in this case a newline. There are one or two other escaped characters recognised - see Escaped Characters for a list. Note that the newline token can appear anywhere in the string, and any number of times. So:

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

would output:

Hello
There
.
			

Consider this example datafile:

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

Since the data items (element type and coordinates) are separated by whitespace, we need only provide the target variables to the relevant command - a formatting string, as is demanded by the printf command, is not required. Using the readline command, the following code will parse this data correctly:

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

The variables el, x, y, and z will, at any one time, contain the element type and coordinates from one line of the file. In an analogous manner, the data may be written out again with the corresponding writeline command:

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

Each line will have the individual data items separated by a single space.

The readnext command reads in a single delimited item from a source file, preserving the remainder of the input line for subsequent operations. If there is no data left on the current line, a new line is read and the first delimited item is returned. The example above might be written in a slightly clunkier form as:

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

For all delimited reading operations, items of data read from the line are converted automatically into the type of the destination variable. So, the atom coordinates read in above, which are put into 'double'-type variables, could equally well be put into string variables. Standard C routines are used to convert data items in this way, and only some conversions make sense. For instance, attempting to read an item which is a proper character string (such as element symbol/name data) into a double or integer variable does not make sense. No error message will be raised, and the variables will likely be set to a value of zero (or whatever passes for 'zero' in the context of the type).

For all delimited writing operations, a suitable standard format specifier is chosen with which to write out the data.

The atom list shows, unsurprisingly, a list of all atoms in the model, displaying elements, charges, and positions. If patterns have been defined for the model, the atoms in the list will be grouped according to their encompassing pattern, otherwise they are listed in one continuous run by ascending ID.

The selection of items in the atom list mirrors the selection in the current model - (de)selecting atoms in one will also (de)select them in the other. If patterns are defined, (de)selecting the pattern name in the list (de)selects all atoms making up the pattern.

The four buttons at the foot of the atom list allow the current selection of atoms to be moved up and down the list, useful for reordering atoms into a specific sequence. Selected atoms can be shifted up/down the list one place at a time, or all moved to the top or bottom of the list at once. In the latter case the order of the original selection is preserved.

Figure 5.2. Build Window, Add Atom Panel

The Add Atom page allows atoms to be created at specific positions in the model. Coordinates are entered and the atom created (with element defined by the current selected element in the Build toolbar) by pressing the Add button. If the 'Frac' checkbox is ticked the coordinates are assumed to be fractional and are converted to cell coordinates as the atom is added. For example, setting coordinates to {0.5,0.5,0.5} will create an atom in the centre of the current unit cell.

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.

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.

Figure 5.7. 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.

The Associate panel links the selected forcefield to one or more models and their patterns; the 'Model' button links the current forcefield to the current model, while the 'All' button links the current forcefield to all loaded model. The 'Pattern' button brings up a dialog listing the patterns of the current model, from which one is selected to link the forcefield to. A forcefield associated to an individual pattern will be used in preference to the forcefield associated with its parent model.

Automatic Typing takes the current model and either assigns or removes forcefield types from the model's (or pattern's) associated forcefield(s). Forcefield types for all atoms are determined unless they have been assigned a specific type manually.

Manual assignment of forcefield types can be performed in the Manual Typing panel. The list gives all atom types in the current forcefield that are relevant to the element entered just above the list. One can be selected from the list and be manually assigned (forced) onto the current atom selection with the Set button. Such assignments will not be overwritten by subsequent automatic typings. Manual typings can be removed with the Delete button, and the currently selected atomtype can be tested for suitability on the current selection of atoms with the Test button.

Fragment models are just normal models stored in specific places. The only real difference is that atoms with unknown element (integer '0', or string 'XX') are slightly more useful than usual. These can act as anchor points for the fragment that do not correspond to the position of any 'proper' atom to allow for more control over the placement of structures - for instance, such an atom may be placed at the centre of a ring. It is important to note that all atoms with unknown element type are removed when the fragment is added to the current model.

At any time, a single atom in the selected fragment represents the attachment point and appears directly under the mouse pointer. Any atom in the fragment can be selected as the current anchor point, and may be cycled through by pressing Alt. If the atom acting as the anchor point has at least one bond to another atom then a reference vector is constructed allowing the fragment to be oriented along vectors dependent on the current geometry of existing atoms, for example.

Single-clicking in free space (i.e. not over an existing atom) places a copy of the current fragment in the current orientation in the current model. Click-dragging allows the fragment to be freely rotated about the anchor point before the placement is final. On placement, the anchor atom is pasted too unless it is of unknown element (see above).

When moving over an existing atom with an anchor point that has at least one bond to another atom, the fragment is attached at a suitable geometry, provided the valency of the atom allows (if not, the atom will be surrounded by a crossed-out box and the fragment will temporarily disappear). A single-click will place the fragment in the shown position and orientation, while click-dragging rotates the fragment about the newly-formed bond to allow fine adjustment before the final placement. If the anchor point has no bonds to other atoms, the fragment is placed in no specific orientation, and click-dragging freely rotates the molecule about the anchor point. In both cases, the anchor atom is always removed when being added to the model since the existing atom which was clicked on will replace it in terms of position.

If the existing atom in the model has one or more hydrogens attached to it, holding Shift will orient the fragment along the existing X-H bond. In this case, both the anchor atom and the existing hydrogen atom are removed when the fragment is placed.

Each grid in the left-hand list has associated with it a checkbox that determines whether or not it is currently visible. Below the list the minimum and maximum data values contained within the grid, and the current cutoff (i.e. the value that the isosurface is drawn at) to use when rendering the data. The File and Edit menus allow to load new grids into the current model, and to cut, paste, and delete grids between models.

The associated origin and axes to the currently selected grid may be modified in the top-right panel. 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.

The style of the selected grid can be modified in the lower-right panel, with the general rendering style set with the combo box (see grid styles for a list of possible styles).

For grids in which the data is 'symmetric' about a cutoff of zero (as is the case for orbital data, for example) the 'Symm' checkbox should be ticked to inform Aten that both the normal surface (above the cutoff) and the negative surface (below the negative of the cutoff) should be drawn.

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.0 being fully transparent, and 1.0 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).

Figure 5.14. 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

Figure 5.15. 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

Figure 5.16. 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

Figure 5.17. 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

Figure 5.18. 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

Figure 5.19. 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

Figure 5.20. 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

Syntax:

Sets the individual drawing style for the current atom selection, used when the global drawing style is 'individual'.

For example:

atomstyle("tube")
		

sets the current atom selection to be drawn in the 'tube' style.

	See also:
	Drawing Styles for a list of available styles

Syntax:

Return a reference to the current atom. If a new atom/id is provided the current atom is set before being returned.

For example:

atom i = getatom(1);
		

makes the first atom in the current model the current atom, and returns a reference to it.

Syntax:

Fix the positions of the current atom selection (or individual atom specified) so that they remain in the same position following various methods (e.g. minimisations).

For example:

fix();
		

fixes the positions of all selected atoms.

for (int n=1; n<=10; ++n) fix(n);
		

fixes the positions of the first 10 atoms in the current model.

Syntax:

Free the positions of previously fixed atoms in the current selection (or the individual atom specified).

For example:

free(5);
		

allows the fifth atom in the current model to be moved again.

Syntax:

Return a reference to the atom specified.

For example:

atom i = getatom(3);
		

returns a reference to the third atom in the current model.

Syntax:

Hides the current selection of atoms (or the supplied atom) from view, meaning they cannot be selected by direct clicking/highlighting in the GUI. They are still subject to transformation if they are selected by other means.

Syntax:

Set the atomic charge of the current (or specified) atom.

Syntax:

Set the coordinates of the current (or specified) atom.

Syntax:

Set the element of the current (or specified) atom.

Syntax:

Set the forces of the current (or specified) atom.

Syntax:

Set the x force of the current (or specified) atom.

Syntax:

Set the y force of the current (or specified) atom.

Syntax:

Set the z force of the current (or specified) atom.

Syntax:

Set the temporary ID of the current (or specified) atom, useful for when parsing atoms from a file that are not in any useful order but have an id specified for the purposes of subsequent connectivity definitions, for example. Within filters, once loading is complete the finalisemodel command will reset all atom ids to internal numbering.

Syntax:

Set the x coordinate of the current (or specified) atom.

Syntax:

Set the y coordinate of the current (or specified) atom.

Syntax:

Set the z coordinate of the current (or specified) atom.

Syntax:

Set the velocity components of the current (or specified) atom.

Syntax:

Set the x velocity of the current (or specified) atom.

Syntax:

Set the y velocity of the current (or specified) atom.

Syntax:

Set the z velocity of the current (or specified) atom.