Perform Basic Operations

Use the Builder tool to create or modify the chemical system that is the basis for a calculation.

See also... Builder Quick Reference - a one-page guide to the Builder interface

Select Items in the Work Area

To enter Select mode, click on the arrow button. In the work area, the mode label becomes "Select" and the cursor becomes the Select cursor (arrow). Other Builder tools that require atom selection (such as the measurement tools) also use the arrow cursor. The following are several ways to select atoms and bonds for operations in the Builder work area.

All these actions use the left mouse button.
How to... Instructions
Select an atom Click on the atom.
The selected atom is highlighted in fuschia.
Select all atoms in a rectangular area 1. Position the cursor at one corner of the area. Depress and drag in any direction.
A rectangle forms with a fixed corner where you began the drag and the opposite corner following the cursor.
2. Release the mouse button to complete the selection.
All atoms enclosed or touched by the rectangle are selected.
Select all atoms of a residue Double-click on any atom in the residue.
All atoms in the residue are selected.
Extend a previous selection Depress the Shift key and use any of the selection methods above on unhighlighted atoms.
The new selection is added to the previous selection.
Select all atoms within a specific radius from one or more selected atoms. 1. Select one or more atoms in the work area.
The selected atoms are highlighted.
2. From the Edit menu, choose Select within radius.
The Radius Selection dialog window displays.
3. Enter a radius (in Angstroms), and click the Select button.
All atoms within that distance of any currently selected atom are added to the selection.
To include any affected residues in the selection, even if some portions of the residues are outside the radius, first mark the Select complete residues option in the Radius Selection window.
Select all atoms in the work area From the Edit menu, choose Select All.
Reduce a previous selection Depress the Shift key and use almost any* of these selection methods on highlighted atoms.
The affected atoms are subtracted from the previous selection.
*Note: Shift-double-clicking a selected residue does not unselect the residue.
Unselect all atoms in the work area Click on any unoccupied space in the work area. Or if you are not in Select mode, open the Edit menu and choose Unselect All.
All highlighted items return to their normal colors.

Tip: The Geometry Table can be a handy way to select atoms while monitoring the details of the chemical system. By selecting rows (atoms or bonds) in the Geometry Table, you also select the corresponding atoms in the Builder work area.

Select Atoms and Residues by Radius

Use the Edit: Select Within Radius window to select all atoms or residues within a defined radius of currently selected atom(s).

Radius selection can be based on a single atom or a set (multiple atoms) of atoms. Any non-highlighted (unselected) atom that is within the specified radius of any of the highlighted atoms will be included in the radius selection results. The Select Within Radius option defines the distance, from any of the highlighted atoms, to use for the radius select search.

If Select Complete Residues is indicated, then all atoms of a residue will be included in the radius selection results if one or more of its atoms are within the specified radius.

Radius Selection window
  1. Select an atom or multiple atoms in the molecule.

  2. From the Builder's Edit menu or the Calculation Viewer's Edit menu, choose Select Within Radius.

    The resulting options window displays the current settings and controls.

  3. Enter a radius in angstroms.

  4. To select complete residues, click the Select complete residues checkbox.

  5. Click the Select button to select all the atoms within the specified distance of any currently selected atoms. If the "Select complete residues" toggle is set, then all atoms in any residue that was within the specified distance will also be selected. The centers of atoms must be within the radius to be selected.

  6. Selection Options
    Radius Select all atoms that are within the specified distance (radius) of any currently selected atom.
    Select complete residues Selects a volume encompassed by the radius you set, and will include the complete residue beyond the specified radius. All atoms in any residue that has at least one atom within the specified distance will be selected.
Note: You can also hide selected atoms or modify their depiction in the Builder's work area by using the Style (Selected) option on the Builder's Display menu.

Add Atoms in the Work Area

  1. Click on any of the element buttons in the Builder's element palette.

    This selects that element, highlights the button, and puts the Builder into "Atom" mode. A corresponding bond "geometry" button also appears depressed, indicating a default hybridization or coordination number for that atom.

  2. If you want to change bond geometry associated with the atom to be added, click on a different button in the bond geometry palette.

  3. If you want to change type of bond that will be added between atoms, click on a different button in the bond palette.

  4. In the Builder's work area, click on a free space where you want the new atom or on a bonding site (nub) of a previous atom.

    The new atom is added at the specified location. As long as the Builder remains in "Atom" mode, each click of the mouse will add a new atom in the work area.
    See also... Modify Atoms and Bonds
    Tip: If the atoms added to the work area appear too small, open the Options menu and mark Autonormalize Display. Each time you add an atom, the Builder will recenter and rescale the chemical system.

To add hydrogens at all unoccupied bonding sites (nubs):

To use elements and bond geometries that do not appear in the basic palette:

  1. Click on the button.

    This opens a full periodic table for selecting elements and additional bond geometries.
    Picture... More Elements and Bond Geometries

  2. In the expanded table, click to select any element or bond geometry button.

    A selected element will fill in one of the two blank element buttons in the Builder. Similarly, a selected bond geometry will fill in one of the two blank geometry buttons in the Builder. You can select two user-specified elements for the element palette and two user-specified hybridizations/coordination numbers for the geometry palette. In either case, selecting a third items will cause the first item to be removed.

  3. In the Builder, use the user-specified element and geometry buttons as you would use the other buttons of the basic palette.

Record/Playback Builder Commands

To automate Builder tasks by recording and replaying a sequence of Builder commands:

  1. From the File menu, choose Record/Playback.

    This opens a Command Recorder (prototype) for recording a sequence of Builder commands in an XML file.



  2. Type a path/filename into the File field.

    The pathname may be necessary because you may not have access to create files in the default location. You must have access to create a file in the specified path: otherwise the Command Recorder will not be able to record the command sequence, and the Record button will not work. Although the Command Recorder does not require it, it may be useful to specify an .xml filename extension.

  3. Click the Record button.

    The Stop button becomes enabled.

  4. When you are finished with a sequence of Builder commands that you want to capture, click the Stop button.

  5. To replay the recorded commands, clear the Builder work area, open the Command Recorder, type the path/filename of the command file (or use the Browse button to find and import the file), and click the Replay button in the Command Recorder.

    If you replay recorded commands with a chemical system already present in the Builder's work area, you may see unexpected results.

Undo the Last Operation

From the File menu, choose Undo [last operation]. The Builder keeps track of your last 10 operations, which you can undo, one by one.

Save the Chemical System

From the File menu, choose Save (or click on the star-shaped "Save Work" icon ). This saves the chemical system as part of the current calculation.

If you launched the Builder directly from the Gateway, the Save option will be disabled because there is no specified calculation to which the chemical system can be saved. In that case, you can either drag a molecule from the Builder onto the drop site in the Calculation Editor or use the File menu Save As option to save the chemical system in a new calculation.

See also... How to export a chemical system to a molecular modeling format (and save a chemical system when using the standalone Ecce Builder)
  How to add molecular structures to a Structure Library

Add Predefined Structures

  1. In the Builder window, click on the button.

    This opens the Structure Library window and puts the Builder into "Add Structure" mode. The Structure Library window contains a folder tree that shows the directory structure of the Ecce Web server. The shared "Structure Library" folder contains a collection of predefined structures within organizing subfolders. You may need to click on a folder icon to reveal subfolders of molecules contained within a folder.
    Picture... Structure Library Window
    More about... Structure Libraries

  2. Select one folder from the folder tree by clicking on its name.

    The molecules in the last-selected folder are pictured in a scrolling panel on the right side of the window.

  3. Select one molecule by clicking on its name (not its picture).

    The name of the selected molecule is highlighted.

  4. In the Builder's work area, click on an empty location.

    As long as the Builder remains in "Add Structure" mode, each click of the mouse will add the selected molecule at the specified location in the work area.
    Tip: If the Structure Library window appears disabled (grayed out), you have switched to a different mode. To enable the Structure Library and return to "Add Structure" mode, just click again on the Structure Library button in the Builder window.

Modify Atoms and Bonds

To replace one atom with another:

  1. In the Builder's element palette, click on the element button corresponding to the replacing element.

  2. In the work area, click on the atom to be replaced.

    The old atom will be replaced with the new only if the change does NOT require removing bonds from existing atoms.

To replace all hydrogens with empty nubs:

Manipulate Atoms in the Work Area

You can change the location of objects in the Builder's work area by two methods: move your viewpoint (change your camera angle) or move the objects (change their space coordinates). The difference may not be important unless you are trying to build a structure based on space coordinates.

To move your point of view:

  1. Click on the Manipulate button .
    The cursor switches to the Manipulate cursor (hand) in the work area.

  2. Depress the left mouse button and drag to rotate the chemical system in arbitrary directions around a center point.
    -OR-
    Depress the middle mouse button and drag to move (translate) the system in the (x,y) plane of the work area.
    The cursor switches to the Translate cursor (hand with object) in the work area.
    -OR-
    Depress the  left + middle mouse buttons together (or Ctrl + ) and drag to dolly/zoom in the work area.
    The cursor switches to the Dolly cursor (pointing hand) in the work area.

To move and rotate objects in space:

  1. Select the atom(s) to be moved or rotated.
  2. Click on the manipulator sphere button .

    When you activate this option, a single wireframe manipulator sphere will enclose atoms that are already selected. To get additional manipulators after this option is active, select single atoms (or several atoms together).
    Picture... Manipulator Sphere
  3. To move atoms in space Click on the gridded surface of the manipulator sphere. While the mouse button is depressed, a double-ended arrow will appear through the center of the sphere, indicating the directions in which you can now drag and move the enclosed atom(s). It may take a bit of practice to become accustomed to using these manipulators.
    To rotate atoms in space Click on one of the two green bands that around the manipulator sphere. While the mouse button is depressed, you can rotate the sphere and the enclosed atom(s) along the direction of the selected band.

To rotate atoms about a bond axis:

  1. Select two bonded atoms, one at a time.
  2. Click on the manipulator wheel button .

    When you activate this option, a wireframe manipulator wheel will appear at the center of the bond between two selected atoms. After this option is active, you can select any two atoms together to get an additional manipulator wheel. The first atom selected remains fixed. You can also select a bond instead of two atoms, but then the choice of the fixed atom is arbitrary.
    Picture... Manipulator Wheel
  3. Click and drag in the region near the manipulator wheel.

    While the mouse button is depressed, you can rotate the atom(s) on one side of the bond while the other side remains fixed. During rotation, a box will appear around the bond axis to make it easier to judge the magnitude of the rotation.

Clean (Improve) the Structure

To improve the structure of molecules that have been built by hand, click on the Clean (broom) icon. This applies a simple molecular mechanics force minimization based on the Universal Force Field (UFF) of Rappe and Goddard.

The results of this operation are affected by the initial shape of the structure. You can also set parameters for this operation. The speed of this operation depends on the number of atoms. If no atoms are selected when the clean button is activated, then all atoms are optimized. If a subset of atoms is selected, then only the coordinates of the selected atoms are updated, although the remaining atoms are included when evaluating the forces on the atoms. The clean function can be slow for large systems, even if only a few atoms are selected.

Tip: Be careful using "Clean" on a molecule that has empty bonding site nubs because the nubs may end up being obscured by other structures after the clean operation. You may want to use the Add H button to add hydrogens to empty nubs before using the Clean icon.

Import/Export a Chemical System

You can import molecular structures directly to the work area of the Builder or to a selected folder in the Structure Library. You can export structure files or graphic files from either the Builder or the Structure Library.

To import molecular structures:

  1. From the Builder's File menu (or the Structure Library's Structure menu) choose Import.

    This opens the Import dialog window.
    Picture... Import Dialog Window

  2. From the Format menu of supported file formats , choose the desired format and import file units (angstroms, Bohr, picometers, or nanometers).

  3. Optional: At the end of the Filter string, type a filter for limiting the files that will be displayed in the Files list. Then press Enter (or click on the Update button) to update the Files list.

  4. In the Directories list, click on the appropriate source directory.

  5. In the Files list, click on the file to import.

    The selected file is listed in the Selection box.

  6. Click on the Import button.

    The imported structure should appear in the Builder work area. If the file format is incorrect, you will see an error message instead.

To export molecular structures:

  1. From the Builder's File menu (or the Structure Library's Structure menu) choose Export.

    This opens the Export dialog window.
    Picture... Export Dialog Window

  2. From the Format menu, choose the desired format.

    Note that the export formats include graphical formats (POV-Ray, Postscript, RGB, GIF, TIFF, and JPEG) in addition to the molecular structure formats.

  3. Optional: At the end of the Filter string, type a filter for limiting the files that will be displayed in the Files list. Then press Enter (or click on the Update button) to update the Files list.

  4. In the Directories list, click on the appropriate target directory.

  5. In the Selection box, type (or edit) the name of the export file.

  6. Click on the Save button.

Create a Structure Library

Structure libraries are folders of the Ecce Web server, typically created to store only chemical systems without any related information. You can create new structure libraries that contain up to about 20 structures in each folder. You can delete only structure library folders that you have created.

Note: Standalone Molecule Builder--The Structure Library files are included with the standalone Builder installation under the data/client/StructureLibrary directory rather than located on the Ecce Web server.
  1. In the Builder window, click on the button.

    This opens the Structure Library window, which lists the folders of the Ecce Web server. The shared "Structure Library" folder is a public collection of pre-built structures.
    Picture... Structure Library Window
    More about... Structure Libraries

  2. Click on your "users" folder. From the File menu select New Library. A new folder labeled "Structure Library" will be created.

    You may add a new structure library folder anywhere you have permission to create new folders on the Ecce Web server, typically under your user account folder within the "users" folder in the folder tree.

  3. Double-click on the new folder and type a new folder name to characterize the molecules that you intend to include.

    The new structure library folder is now ready to accept structures from the Builder or from imported structure files.

To add molecular structures to the new structure library:

  1. Select the new structure library folder in the folder tree of the Structure Library window.

  2. Drag from the Builder - With a desired chemical system displayed in the Builder's work area, use the middle mouse button to drag (the currently displayed chemical system) from the Builder's drag site to the Structure Library's drop site.
    -OR-
    Import Structures - From the Structure menu in the Structure Library, choose Import. The resulting file dialog window includes options for selecting the file format and file that you want to import.
    -OR-
    Copy and Paste - From the Edit menu of the Structure Library, use the Copy and Paste options to transfer structures from other folder locations or structure libraries.

To delete a structure library:

  1. Select the structure library folder in the folder tree of the Structure Library window.

    You can delete only folders that you have created.

  2. From the Structure Library menu, choose the Delete option.

    A confirmation dialog will ask if you are sure that you want to delete the selected folder.

  3. Click Yes to confirm the deletion.

Customize Chemical System Display Details

Use the Details: ChemSys Display Options window to adjust the appearance of atoms and bonds. The visible effect of the window controls depends on the general display style already in effect (Ball & Stick, Stick, Ball & Wireframe, Stick, Wireframe, or CPK).

Picture... Chemical System Display Options Window
  1. From the Builder's Display menu or the Calculation Viewer's Chemical System menu, choose Render Quality and then Customize.

    The resulting options window displays the current settings and controls. All controls in the window are either exclusive options or range sliders. Most sliders are marked from 1 to 100% with corresponding dynamic readouts from .01 to 1.0 .

  2. To adjust a display attribute, mark the option box or drag the range slider using the left mouse button.

    Wire Options (chemical system appearance for Wireframe styles)
    Line Width Width of the lines used for wireframe from about 1 to 10 pixels (.01 to .10).
    Cylinder Options (bond appearance for Stick styles)
    Cap Style Appearance of the atom ends of the bonds (Caps appear only in Stick style.)
    Render Quality The stick quality modifies the stick cross section from nearly triangular (0.1) to circular (1.0).
    Radius Radius of sticks
    Sphere Options (atom appearance for Ball and CPK styles)
    Hemi Spheres or Full Spheres Full Spheres is the preferred option for most workstations. The Hemi Spheres option may increase display speed, but the display can be uneven.
    Render Quality The sphere quality modifies the rendering from an 8-faced cube (.01) to an n-faced polyhedron approximating a sphere (1.0) The default sphere quality is set at about 50% (0.5). Higher values will increase the graphic quality and rendering time for atom surfaces.
    Ball/Stick Scale Relative size of the spheres from near zero (.01) to normal (1.0)
Note: You can also hide selected atoms or modify their depiction in the Builder's work area by using the Style (Selected) option on the Builder's Display menu.

Print a Picture of the Work Area

From the File menu, choose Print. In the resulting window you can select from a scrolling list of available printers.


Ecce Online Help
Revised: April 29, 2004
Disclaimer