New Molecule

Create a new molecule, (currently a single carbon with 4
attached X (i.e. unidentified) atoms) and open the editing tools panel.

Save Image

Save the graphical image in the main window to file out.jpg in the
current working directory (the directory from which the GUI was started).

Open Calc

Opens a calculation window and restores the results of the chosen
calculation (.clc) file.

Quit

Exit the GUI.

Edit Menu

Edit Coords

Opens the molecular coordinates editor on the chosen molecule. The
coordinates editor is used for editing the atomic coordinates of the
molecule in either Z-matrix or Cartesian form. For more help on the
Coordinates Editor, click here.

Edit Grid

Dunno.

Connect

Determine the connectivity according to the parameters
specified in Edit -> Options -> Connectivity. You will need to
do this if you have loaded in a molecule in .pdb format.

Extend

Extend a periodic structure with more repeat units (periodic
structures can be read in from ChemShell unit cell format).

Delete

Delete the specified molecule.

Editing Tools

Opens a window with tools for molecular editing (point and
click) operations. More extensive help on the Editing Tools can be
displayed by pressing F1 when the Editing Tools window is
displayed or clicking here.

Select All

Selects all the atoms of the selected molecule.

Select by bonds

Select all the atoms that are part of this molecular fragment
(i.e. are part of the same bonded network).

Select (dist to sel)

Select all atoms within a specified distance of the currently
selected atom(s). On selecting this item, dialog box will appear that
you can use to specify the distance in Angstroms.

Select (dist to point)

Select all atoms within a specified distance of a particular
point. The origin of the grid used to specify the point is the centroid of all
currently selected atoms or the centre of the screen if no atoms are
selected. On selecting this item, dialog box will appear that you can
use to specify the coordinates of the point and the distance in
Angstroms.

Select (dist to point) + trim models

This functions exactly as Select (dist to point),
except that, following the selection, all unselected atoms will be
hidden ( to show the atoms again, use the Adjust
Molecule View tool ).

Delete Selected Atoms

Delete all the selected atoms.

Delete Unselected Atoms

Delete all atoms that are not currently selected.

Options

Opens the Options panel, allowing adjustment of defaults and
parameters relating to the behaviour of the GUI. More extensive help can be
displayed by pressing F1 with this window displayed or clicking here.

View Menu

Viewing Molecules

The CCP1GUI has extremely powerful and highly customisable
capabilities for viewing molecules and the data resulting from a
calculation. There are essentially three types of representation that
can be accessed from the view menu. These are listed below with a more
detailed description following on.

Molecule View - the representation
of the atoms and bonds within a molecule.

Scalar Data - the representation of
data that is defined by its magnitude at a point in space
(such as orbital vectors or electrostatic potential).

Vector Data - the representation
of data that has both a magnitude and direction at a point in space
(such as a charge density gradient).

Molecule View

Molecule views are grouped together under the View Menu according to the
molecule to which they belong. Selecting a particular molecule from
the View Menu opens a drop-down menu that lists the following options:

Show/Hide Molecule View

This is used to show or hide a particular view of a molecule.

Adjust Molecule View

This is where the properties of a particular view can be
changed. Selecting this option will cause a dialog box to appear with
the options listed below (this help may also
be displayed by pressing F1 when the window is displayed).

New Molecule View

This creates a new view object for the molecule. The view can then be
adjusted by selecting the view from the menu and selecting 'Adjust
Molecule View' as above.

Adjust Molecule View

The adjust molecule view tool changes the way that the molecular
structure is displayed on the screen. The tool is displayed below:

The available options are:

Wireframe - a simple representation of a molecule with the
bonds represented as coloured lines connecting the individual
atoms. From their midpoint to the end connected to an atom, the lines
are coloured with the colour associated with that atom type.

Show bonds - toggle the display of the wireframe
bonds.

Contacts - atoms that are not connected, but whose centres
are within a certain distance of each other can be considered to be
in contact. If two atoms are in contact, when the contacts
button is selected, the two atoms will be connected by a white
line. The contact distance can be specified in the Connectivity
tab of the Edit -> Options menu.

Spheres - the balls of the conventional ball and stick
representation of molecules. Spheres are drawn centred on the individual
atoms, sized and coloured according to the atom type
that they are associated with.

Show - toggle whether the spheres are shown or not.

Scale - change the relative sizes of the spheres.

Radii - toggle whether the reference radius for the
spheres is the Covalent or Van der Waals radius.

Sticks - the sticks of the conventional ball and stickrepresentation of molecules. Cylinders are drawn representing the
bonds connecting individual atoms.

Show - toggle whether the bonds are shown or not.

Radius - change the width of the bonds.

Colour - change the colour of the bonds (default is grey).

Labels - this displays labels identifying the individual
atoms. The labels show the type of the atom, as well as a unique
number identifying each atom.

Show - toggle whether the labels are shown or not.

Size - change the font size used for the labels.

Colour - change the colour of the labels.

Draw Selected Atoms Only - only display those atoms that
have been selected by clicking on them with the mouse.

Draw All Atoms - display all atoms regardless of whether
they have been selected or not.

Update - refresh the screen to show any changed options.

Show - display the structure.

Hide - hide the structure.

Destroy - destroy this representation of the structure.

Scalar data view

When a calculation is carried out on a molecule, the result is often
returned as the value of the property (such as the charge density) mapped
onto a 3-dimensional grid of points.

The GUI is equipped with a number of highly configurable visualisers for such scalar
data on a grids. The following menu items list the visualisers and
which of their properties can be adjusted. As the visualisers share many
of the same tools, there are also links to explanations of what the
individual property adjustment tools do

Density View

This defines a single isosurface for a specified positive value of the
grid. The contour height is adjustable, as is
the colour and opacity. The outline of
the grid is also configurable.

Density Volume Visualisation View

In this view, a whole volume of space is coloured according to
the value of the property within that volume. A transfer function can be selected and the outline of the grid is also configurable.

Orbital Volume Visualisation View

As for a density volume view, a whole volume of space is coloured according to
the value of the property within that volume. A transfer function can be selected and the outline of the grid is also configurable. The
difference between a density and orbital view is that, the density view
expects the values to be in a range from 0 to a positive number, whereas the orbital
view expects to colour the volume according to whether the values are
positive, negative or zero.

Orbital View

This is similar to density view, except that a pair of isosurfaces are
drawn, one for a specified positive value and another for the corresponding
negative value. The colours of both of the surfaces may be selected.

Coloured Surface

The coloured isosurface representation creates an isosurface at a
specified contour height. The colour, contour height, and opacity can all be configured. This surface can
also be colour mapped according to the value of
another property.

Grid View

This is the closest view to the 'raw' data and consists of a grid of
points with their associated values. The size of the points on the
screen can be altered as can their opacity
and the colour mapping.

Cut Slice View

The cut slice view creates a 2-dimensional 'canvas' that can
be moved through the molecule, with the values of the function at the
point the slice is taken displayed on the canvas as contours or a
colourmap. The size, orientation and position of the slice can be
specified by using the Tran, Rot and Scale tools, which
alter the position, orientation and size respectively, of the grid
components. The density of points, or mesh, that the colour map
or contours are mapped along any particular axis can be specified with the nx,
ny and nz tools.

The two tools at the top of the widget allow the opacity of the whole slice to be selected and
also the colour of the border to be determined

The options in the representations box determine which of
the properties area shown.

If contours is selected, contours are displayed. The
maximum and minimum contour values, as well as the total number of
contours displayed can be specified with the Min Contour
Height,Max Contour Height and Number of Contour
tools. The tools in the Contour Colour Mapping group allow a colour map may also be defined for the
contours.

If Colourmap is selected a colour
map will be applied to the whole canvas as specified in the
colourmap colour mapping group.

The border around the slice can be toggled on and off with the
border tool.

An optional 2D-representation of the canvas can also be created in
a separate window by selecting the 2D Representation. Selecting this
option opens up a separate window displaying a face-on of the
canvas, which can be saved to the current directory as the file
out2d.jpeg.

Vector data view

Vector data is data that has both a magnitude and a direction at a
point in space. The GUI's vector visualiser is described below.

Vector Visualisation

There are three ways that the GUI can visualise vectors:

Hedgehog Plot - this displays the vector as a line
oriented along the vector. The length of the line is proportional to
the magnitude of the vector. The lengths of the the hedgehog lines can
be scaled with the scale tool, and the display tool
toggles whether the hedgehog plot is displayed or not.

Oriented Glyph - this is similar to the hedgehog plot, but
instead of lines, cones are drawn, with the orientation of the cone
corresponding to the direction of the vector and the size of the cone
proportional to the magnitude of the vector.

Streamlines - Streamlines can be thought of as the paths of
particles that is travelling along the vector field. Starting at the point
on the grid defining the vector, the particle moves forward a distance
specified by the Integ Step Length and Step Length
tools. At that point, the magnitude and direction of the new vector field
is determined and the particle moves forward again in the new
direction.

The Propagation Time determines how long the
particle will travel for, and hence how long the streamlines will be.

The Display determines whether the streamlines will be
displayed as lines, tubes or surfaces.

The Integrate tool determines whether the particle will move
forwards in the direction the vector is pointing, backwards, or
whether the path will be traced in both directions.

Computer Health Warning!: computing streamlines
with Python code is extremely cpu and memory hungry and has been know
to bring even the hardiest of Linux boxes to its knees!

All of the different vector views can have their colour mapping changed according to
other properties with the Colour Map tool.

As displaying all of the points of the vector field is often not
particularly information, the Sampling Grid tool can be used to
select which points will be visualised. All of the points can be
selected, or a 2-dimensional plane can be selected, or the points may
be sampled according to another grid such as the grid defining the
HOMO.

An explanation of the individual view properties:

Edit Colours - for surfaces
that only have a single colour mapped to them, clicking on this option
brings up the below dialog box that can be used to select the
colour. The colour can be selected either by dragging the sliders to
mix in various Red Green and Blue components, or the hexadecimal value
of the colour can be entered in the selection box.

Colour Mapping - two or three elements of the colour map are
configurable depending on the tool that it is being used in:

Scheme - this determines how the colours change as
the value of the property that is being coloured changes from its
minimum to its maximum value.

Lo and Hi - this determines the maximum and minimum values
of the property that the colour spectrum will be mapped to

Colour By - for certain colour maps, this determines which property the colour
map is describing.

Opacity - this determines how see-through the coloured
surface will be.

Contour Height - this is the point value that the
surface or contour will be mapped to; this effectively creates an
isosurface mapped to the value specified in the contour height
box.

Outline - this is just a line
drawn around the outer edge of the 3-dimensional grid that the points
are mapped onto. It's display can be toggled on or off, and it's
colour specified when displayed.

Colour Field - this applies to the coloured isosurface
tool, and colours the isosurface according to the property specified
here. For example, an isosurface of the electron density can be
displayed and this can be then coloured according to the electrostatic
potential.

Transfer Function - A
transfer function is used to colour individual volumes of space according to the
value of a particular property within that volume. A transfer function
is defined by a number of steps; each step is defined by an upper and
lower value. If the value of the property within a volume of space falls
within one of the steps, that volume of space is coloured according to
the colour that has been ascribed to that step. The opacity of the
volume can also be specified, so that the whole volume can be viewed
at one time.

Vibrations

If the one of the Frequencies options (finite difference or
analytic) have been selected from the Properties Tab in the GAMESS-UK
widget, then the vibrational frequencies of the molecule will be
calculated, and the individual frequencies listed under the
Views menu. To view a vibration, select the vibration from the
views menu and a dialog box like the one below will be displayed:

The first few tools are the same as those for the Adjust
Molecule View Tool. The additional vibration-specific tools are
contained in the Animation box. These are:

Start - animate the selected vibration.

Stop - stop the animation.

Number of Frames - this is the number of still
images that will be concatenated to create the animation.

Amplitude - this determines the size of the
vibration: the distance from the equilibrium point of the vibration to
its apex.

Frame Delay - the time-step between each frame that is
concatenated to create the animation.

Animation...

The animation tool brings up a set of controls that can be
used to display a movie by cycling through the sequence of images that
have been loaded into the CCP1GUI. There are buttons to 'play' the
sequence in a loop, go to the first or last frame, or move forward or
backwards a frame at a time. The animation tools are displayed below:

The animation tool is particularly useful if you have carried out a
geometry optimisation under GAMESS-UK, as the geometry of the molecule
at each stage of the optimisation is saved to the punch file. Using
the animation tools, a movie showing the progression of the geometry
optimisation can be displayed.

Show/Hide All

Show All and Hide All affect the visibility of all graphical
representations.

Centre on Selected

Changes the origin for viewing and rotations of the centroid
of the selected atoms.

Info Menu

The info menu brings up a list of options to for displaying
select information about the molecule. The information will be
displayed in a pop-up window. Available options are:

Coordinate List - a list of all the coordinates of the
atoms within the selected molecule.

Bond Length and Angles - a list of all bond lengths and
angles for the selected molecule.

Contacts to Selected Atoms - a list of all the atoms that
are close enough to be considered in contact with the selected atoms.

Compute Menu

The compute menu is used to select a program with which to run a
calculation on the molecule. Currently, the GUI has control interfaces
for ChemShell, Dalton, GAMESS-UK, MNDO and Mopac. For help relating to the control
window for a particular program, press F1 when the window is
displayed.

Shell Menu

The Shell menu is used to open an IDLE (Integrated Development
Environment) Python shell - assuming you have IDLE installed. IDLE is
included with most Python distributions, but if for any reason you
don't have it, it is available from: http://www.python.org/idle

When opened from within the GUI, IDLE provides a powerful tool with
which to interact with the GUI. The GUI Python objects can be operated
on directly and information about them displayed.

It is also possible to write and run scripts to carry out complex
operations.

More help on this is to follow.

The Editing Tools Window

Changing the element type

When it is first displayed, the upper half of the panel displays a
selection of elements from the periodic table. To change the element
type of an atom in the main window, select the atom with the mouse (so
that a yellow square appears over it) and then click on the button
representing the element type you would like the atom to be changed
to.

If the element you are after isn't displayed in the selection, click
on the 'More...' button to display a full periodic table. To shrink
the window back down so that it only displays a small selection of
elements, click on the 'Short Table' button.

Editing

The tools in the Editing Group perform a number of simple editing
operations on a molecule, namely:

Del Atom - deletes the selected atom(s).

Del Bond - deletes a bond between two ( and only two ) selected atoms.

Add Bond - creates a bond between two selected atoms.

All X->H - when a new molecule is created ( using File
-> New Molecule ) or new atoms are added to the molecule, the
atoms at the end of the bonds are created as generic "X"
atoms. This button converts all the "X" to hydrogen
atoms.

Hybridisation

The tools in the hybridisation group change the hybridisation of
the selected atoms. If you click on an atom that is only connected to a
molecule with a single bond, changing the hybridisation scheme will
add however many generic atoms your hybridisation scheme permits. You
may then change their type individually or convert them all to
hydrogens as described above. Various hybridisation schemes are
available:

sp = sp

sp2 = sp2

sp3 = sp3

tpy = trigonal pyrimidal

sqpl = square planar

sqpy = square pyramidal

oct = octahedral

Add Fragment

To speed up the construction of large molecules, the GUI
supports the ability to add molecular fragments to a given atom. To add a molecular fragment, select the atom to
which you would like to add the fragment in the main window, select
the desired fragment from menu on the right hand side of the Add
Fragment frame in the Tools window and then click Add. Supported molecular
fragments are:

Me = methyl

Pr = propyl

t-Bu = tertiary butyl

CO = carbon monoxide

Bu = butyl

eta Bz = η (π-bound) benzyl

eta Cp = η (π-bound) cyclopentadienyl

i-Bu = iso butyl

eta Ethylene = η (π-bound) Ethylene

i-Pr = iso propyl

Et = ethyl

Py = phenyl

Measure

The tools in the Measure group provide a quick way to determine the
various properties for selected atoms. The value of the property for
the selected atoms ( which are identified by their number ) is
displayed in the space to the right of the buttons in the group.

Distance - the distance ( in Angstroms ) between two
selected atoms.

Angle - the angle ( in degrees ) between three selected atoms.

Torsion - the torsion ( or dihedral ) angle defined for 4 selected
atoms ( 1-2-3-4 ), is the angle between the planes defined by atoms 1-2-3 and
the plane defined by atoms 2-3-4.

Clean

The tools in the Clean group provide a quick way to run a geometry
optimisation to "clean up" a molecular structure. The
ability to use these tools depend on the relevant codes to perform the
optimisation being installed, as the CCP1GUI currently does not have
the ability to run an optimisation internally. The options for
cleaning are:

Clean - this runs the geometry optimisation and replaces
the structure in the window with the optimised structure.

The second menu option is used to select the code with which to
perform the geometry optimisation. Supported codes are:

Mopac - use the Mopac. Mopac is freely available from the WebMo website
or from the CCL
website.

MNDO - use the MNDO code.

UFF - use the UFF forcefield code.

GAMESS-UK - use GAMESS-UK.

Opts... - clicking on this button will bring up a menu for
configuring how the geometry optimisation will be performed with the
selected code.

Edit Options Menu

Files

Connectivity

Connection Parameters

The parameters here determine how the gui decides if two atoms are
bonded (assuming that the connectivity has not been specified in the
input file). The formula that is used to determine bonding is:

rij<scale *
(rcov(i) + rcov(j)) + tolerance

where rij is the distance between the two atomic
centres, rcov(n) the Van der Waals radius of the
atom, scale the radius scale factor and tolerance the
tolerance.

Radius scale - this determines the radius scale in the
above formula.

Tolerance - this determines the tolerance in the
above formula.

Non-bonded Connection Parameters

The parameters here determine how the gui decides if two
non-bonded, but adjacent atoms, are in contact with each other.
This determined using the same formula as for bonded
atoms and the same parameters are adjustable.

Visualisation

The visualisation options here permit the user to define exactly how
the GUI will represent the various objects that it draws.

Pick Tolerance - this allows you to change how close you have to
place the mouse pointer to an object in order to be able to select
that object.

Background Colour - clicking on the 'Choose' button will bring
up an colour editing widget to change the
background colour of the GUI.

Clipping Planes - this determines at what point VTK ( the
underlying graphics toolkit ) will stop trying to display objects
depending on how near or far away from the "camera" they are. This
should be left at Auto unless you know what you are doing or are
_really_ bored...

Near - distance to the front clipping plane

Far - distance to the back clipping plane.

Molecule Line Drawing Settings - settings here can be used
to change how the molecules appear when they are drawn as lines ( i.e.
when they are not being displayed as spheres ).

Line Width - the width of the line used to draw the molecules.

Point Size - the pint size of the line used to draw the molecules

Sphere Properties - the features here can be used to tweak
how the spheres appear on the screen.

Resolution -

Specular Power -

Diffuse -

Ambient -

Specular -

Cylinder Properties- the features here can be used to tweak
how the cylinders appear on the screen

Resolution -

Specular Power -

Diffuse -

Ambient -

Specular -

Data Line Settings -

Line Width -

Point Size -

Developmental

At present, there are no editable attributes available here.
The Editing Tool Panel is used to change various properties of the
molecule displayed in the main window.

The Edit Coordinates Window

This can be used to manually edit the coordinates of the atoms in a
molecule using either internal (displayed as a Z-matrix) or Cartesian
coordinates. It is also possible to mix and match the two.

The coordinates window at the top of the Edit Window is a table
displaying the coordinates. Each row corresponds to an individual
atom. The table below shows the meaning of each of the columns in this
panel for Z-matrix format and Cartesian coordinates.

Title

Cartesian

Zmatrix

i

A number serving as a unique identifier for the
atom

Same as for Cartesians.

Sym

The chemical Symbol for the atom - a number may be
appended to this to help identify the atom.

Same as for Cartesians.

i1

Unused

The first atom to which this atom is connected.

x/r

The x-coordinate of the atom in Angstroms

The distance of this atom from the atom specified in i1.

i2

Unused

The second atom to which this atom
is connected.

y/theta

The y-coordinate of the atom in Angstroms

The angle between this atom and the atoms identified
in columns i1 and i2.

i3

Unused

The third atom to which this atom is
connected.

z/phi

The z-coordinate of the atom in Angstroms.

The dihedral angle between this atom and those
identified in the fields 1i,i2 and i3.

connections

The other atoms to which this atom is connected.

Unused

Input Line

Values in the coordinates window cannot be edited by directly. However, by
clicking on the row corresponding to an atom in the coordinates window (or
clicking on the atom in the main window), the values for that atom
appear in the Input Line fields headed "Enter Coordinate values" that
sits below the table. By clicking in a field, the value can then be
edited.

Variables

The Variables field shows any values that are specified as variable
within the coordinates window.

Error Output

If there is a problem with any of the coordinates that have been
entered, an error message will be displayed here.

File Menu

Save Zmatrix

Save the coordinates to a simple text file with the extension
.zmt

Load Zmatrix

Load coordinates from a file.

Reload from Graphics Window

Update the coordinates window with the coordinates from the molecule
displayed in the main window.

Edit Menu

Select All Atoms

This selects and highlights all of the atoms specified in the
coordinates window - the corresponding atoms in the main window will
also be highlighted.

Insert Atoms

This opens up a blank Input Line so that the coordinates for a new
atom can be added.

Copy Atoms

The values for the specified atoms will be copied into a buffer ready
for pasting.

Cut Atoms

The atoms will be removed from the coordinates window, but the values
will be copied into a buffer ready to be pasted.

Paste Atoms

Paste the coordinates of any atoms that were saved into the buffer into
the table.

Delete Atoms

Delete the selected atoms, but don't save their values.

r,x -> var

Specify the value for x-coordinate or r as a variable (this value will then
be displayed in the 'Variables' window).

theta,y -> var

Specify the value for y-coordinate or theta as a variable (this value will then
be displayed in the 'Variables' window).

phi,z -> var

Specify the value for z-coordinate or phi as a variable (this value will then
be displayed in the 'Variables' window).

all -> var

Specify that all the selected values should be variables.

Select All Variables

This selects all of the variables displayed in the 'Variables' window.

Delete Variables

Remove a value from the variables window and specify it as a constant.

Convert Menu

Reorder Atoms

Not active at present

AutoZ

Not active at present.

Convert Selection to Z-Matrix

Convert a selection displayed as Cartesian to be displayed in Z-matrix
form.

Convert Selection to Cartesian

Convert a selection displayed as Z-matrix to be display in Cartesian
form.

Calculate Menu

Auto Recalc

This toggles whether the coordinates should be recalculated as each change
is made or whether the calculation should wait until 'Recompute Now'
is selected.