Tools to build molecules from scratch, or finalise unfinished models. When creating atoms using the commands listed below, if the coordinates of the new atom are not specified then it is placed at the current pen position. In addition, the reference frame of the pen position is represented as a set of three orthogonal vectors defining the pen's local coordinate system (set initially to the Cartesian axes) centred at an arbitrary origin (the pen position). Subsequent rotations operate on these coordinate axes. Think of it as a 3D version of the old-school turtle.


addHydrogen

Syntax:

void addHydrogen ( )

void addHydrogen ( Atom|int i )

Satisfy the valencies of all atoms in the current model by adding hydrogens to heavy atoms. If an integer id or atom reference is provided as the argument then the addition of hydrogen is restricted to the specified atom.

For example:

addHydrogen();

add hydrogens to all atoms in the current model.

addHydrogen(10);

add hydrogens to atom 10 only.


bohr

Syntax:

void bohr ( object x, ... )

Converts the specified object(s) data to Ǻ, assuming that it is currently specified in Bohr.

For example:

Atom i = aten.model.atoms[2];
bohr(i);

converts the coordinates of the supplied atom from Bohr to Ǻ.


chain

Syntax:

Atom chain ( int|string el )

Atom chain ( int|string el, int|string bondtype )

Atom chain ( int|string el, double x, double y, double z )

Atom chain ( int|string el, double x, double y, double z, int|string bondtype )

Create a new atom of element el at the current pen position (or the specified coordinates) bound to the last drawn atom with a single bond (or of type bondtype if it was specified). The element can be provided as a character string containing the element symbol or element name instead of the integer atomic number. A reference to the new atom is returned.

For example:

Atom i = chain("C");

places a carbon atom at the current pen coordinates, and creates a single bond with the last drawn atom.

Atom i = chain(8, "double");

places an oxygen atom at the current pen coordinates, and creates a double bond with the last drawn atom.

Atom i = chain("Cl", 4.0, 5.0, 6.0, "single");

creates a chlorine at coordinates { 4.0, 5.0, 6.0 }, joined by a single bond to the last drawn atom.


endChain

Syntax:

void endChain ( )

Ends the current chain (so that the next atom drawn with ‘chain’ will be unbound).

For example:

endChain();

growAtom

Syntax:

Atom growAtom ( Element el, Atom|int [var]*i[/var], string geometry = "tetrahedral", double distance = (auto), bool bond = true )

Grows a new atom of the specified element from the specified target atom i. The position of the new atom will conform to the required geometry, and will have the specified distance from the target atom.  If the supplied distance is negative, then the atomic radii of the target and new atoms are used to calculate the new bond length.  If the target atom already has enough (or too many) atoms to prevent a new position from being calculated, then no atom is added.  If a new atom is successfully added, it is returned. The default is to create a bond between the target and new atoms, but this can be restricted by passing false as the bond argument.

For example:

Atom i = newAtom(P);
for (int n=0; n<6; ++n) growAtom(F, i, "octahedral");

creates a PF6 (anion), with a perfect octahedral arrangement of F atoms, and calculating the bond distance from the atomic radii of P and F atoms.


locate

Syntax:

void locate ( double x, double y, double z )

Sets the pen position to the coordinates specified (in Ǻ).

For example:

locate(0.0, 0.0, 0.0);

moves the pen back to the coordinate origin.


move

Syntax:

void move ( double x, double y, double z )

Moves the pen position by the amounts specified (in Ǻ).

For example:

move(1.0, 1.0, 0.0);

moves the pen one Ǻ in both the positive x and y directions.


moveToEnd

Syntax:

void moveToEnd ( )

Move the current atom selection to the end of the list. The relative order of atoms in the selection is preserved.

For example:

select(H);
moveToEnd();

moves all hydrogen atoms to the end of the atom list.


moveToStart

Syntax:

void moveToStart ( )

Move the current atom selection to the start of the list. The relative order of the atoms in the selection is preserved.

For example:

selectType(O, "nbonds=2,-H(n=2)");
moveToStart();

moves all water molecules to the start of the atom list.


newAtom

Syntax:

void newAtom ( int|string el )

void newAtom ( int|string el, double x, double y, double z )

void newAtom ( int|string el, double x, double y, double z, double vx, double vy, double vz )

void newAtom ( int|string el, double x, double y, double z, double vx, double vy, double vz, double fx, double fy, double fz )

Create a new atom of element el at the current pen position or, if provided, the specified coordinates (and optional velocities or velocities and forces). Either the integer atomic number or the symbol/name of the element may be used to identify the desired element. A reference to the new atom is returned.

For example:

Atom i = newAtom("N");

places a nitrogen atom at the current pen coordinates.

Atom i = newAtom(18, 5.2, 0, 0);

places an argon atom at the coordinates { 5.2, 0.0, 0.0 }.


newAtomFrac

Syntax:

void newAtomFrac ( int|string el, double x, double y, double z )

void newAtomFrac ( int|string el, double x, double y, double z, double vx, double vy, double vz )

void newAtomFrac ( int|string el, double x, double y, double z, double vx, double vy, double vz, double fx, double fy, double fz )

Create a new atom of element el at the specified fractional coordinates (velocities and forces are optional). Either the integer atomic number or the symbol/name of the element may be used to identify the desired element. A reference to the new atom is returned.

For example:

Atom i = newAtomFrac("C", 0.5, 0.5, 0.5);

places a carbon atom at the centre of the model’s cell.


reorder

Syntax:

void reorder ( )

Adjust the ordering of atoms in the current selection such that atoms in bound fragments/molecules have successive IDs. Useful to recover 'molecularity' in order to apply a suitable pattern description to the system.

For example:

reorder();

rotX

Syntax:

void rotX ( double angle )

Rotates the reference coordinate system about the x axis by angle degrees.

For example:

rotX(90.0);

rotates around the x axis by 90 degrees.


rotY

Syntax:

void rotY ( double angle )

Rotates the reference coordinate system about the y axis by angle degrees.

For example:

rotY(45.0);

rotates around the y axis by 45 degrees.


rotZ

Syntax:

void rotZ ( double angle )

Rotates the reference coordinate system about the z axis by angle degrees.

For example:

rotZ(109.5);

rotates around the z axis by 109.5 degrees.


selectionAddHydrogen

Syntax:

void selectionAddHydrogen ( )

Adds hydrogen atoms to the current atom selection only.


selectionGrowAtom

Syntax:

void selectionGrowAtom ( Element el, string geometry = "tetrahedral", double distance = (auto), bool bond = true )

Grows a new atom on each of the currently selected atoms, conforming to the specified geometry and distance (if provided). See the growAtom command for more information.


shiftDown

Syntax:

void shiftDown ( )

void shiftDown ( int n )

Move the current atom selection one (or n) places down in the atom list (i.e. towards higher IDs).

For example:

shiftDown(4);

moves the current atom selection down four places.


shiftUp

Syntax:

void shiftUp ( )

void shiftUp ( int n )

Move the current atom selection one (or n) places up in the atom list (i.e. towards lower IDs).

For example:

shiftUp();

moves the current atom selection up one place.


transmute

Syntax:

void transmute ( int|string el )

Transmute the current atom selection to the specified element.

For example:

transmute("F");

changes all atoms in the current selection to fluorine.

transmute(Cl);

changes all atoms in the current selection to chlorine.

transmute(6);

changes all atoms in the current selection to carbon