Overview - Builder

The Builder enables you to build, visualize, modify, and manipulate 3D images of chemical systems to be used in Ecce calculations. The Builder can handle large chemical systems of tens of thousands of atoms—up to the practical limits imposed by your machine memory and processor. (The Builder has been successfully tested rendering 1,000,000 wireframe atoms on a Linux workstation with an ATI Fire GL X1 graphics card. Results will vary, depending on your graphics hardware and display driver.)

In the Builder's work area, a molecule can be constructed by

• building up from nothing, atom-by-atom
• building symmetric molecular systems with the Symmetry Toolkit
• modifying prebuilt structures from an extensive molecular structure library
• modifying and building very large systems with the MD (Molecular Dynamics) Toolkit
• importing structures from an external file, including large Protein Data Bank residues.

Measurement-adjustment tools are available for fine-tuning the position and spacing of atoms in chemical systems. The atomic coordinates of created molecules are used by other Ecce tools in calculations and can be exported to external files in various molecular modeling formats.

Learning the Builder. Although the Builder can easily be used to perform simple tasks, its many functions make mastering this tool a more difficult assignment than most other Ecce tools. This overview describes the Builder's components and controls.

See also...		Examples: Building Chemical Systems
		Builder Quick Reference - a one-page guide and "icon demystefier" for the Builder interface

Key Concepts

• Constraints: Although the Builder has some defaults that are guided by chemistry conventions, you are free to override them. In general, the Builder lets you build the molecules you can imagine (from the conventional to the outrageous).
• Standalone Molecule Builder: The Builder can be downloaded and installed as a standalone molecule builder independent of the other Ecce software. This may be useful if you want to use the 3-D direct manipulation molecule building capability but are not interested in the rest of Ecce's graphical interfaces for setting up, running, and viewing the results of electronic structure calculations. All building features supported in the Ecce-integrated version of the Builder are also available in the standalone version. The File menu Import… and Export… options are used to open and save chemical systems. The few options that require the context of an Ecce calculation are absent from the standalone Builder.
• Calculations: If you are using the Builder with Ecce (rather than as a standalone molecule builder), then at some point the chemical system that you build must be saved as an input to a specific Ecce calculation. You can create the calculation first in the Calculation Manager and start the Builder in the context of that calculation, or you can build the chemical system first and then use the Builder's File/Save As option to create a new calculation for the Calculation Manager.
• Modes of Operation: Generally you will click on a button that selects a mode of operation for actions in the Builder work area. For example, clicking on an element button puts the Builder in "Atom" mode for adding atoms to the work area. Or clicking on the button puts the Builder in "Select" mode for selecting atoms and bonds for further operations.
  

  To help you keep track of the mode, the selected control button is highlighted with a green border, and the corresponding mode is labeled at the top of the work area.

• Selecting Atoms: The left mouse button is used in Select mode to select atoms for further operations. Selected atoms are highlighted in pink (well, fuschia really).

  Select a single atom. Shift + Select multiple atoms, one at a time.

  More about...

  Selecting Items in the Work Area

Starting the Builder

Ways to start the Builder:

• In the Ecce Gateway: Click on the Builder icon (above) to open the Builder. If the Builder is already running, clicking on the Builder icon will bring its window to the front. To start a separate instance of the Builder, shift-click on the icon.
  
• In the Calculation Manager: First select a calculation. Then choose Builder from the Tools menu.
• In the Calculation Editor: Click on the Chem Sys button located in the upper left portion of the window.
• As a standalone application: Enter the command ebuilder (all lowercase) at the UNIX or LINUX prompt. On the Builder's File menu, use the Import/Export options to open and save chemical system data.

Work Area

The image viewer on the right side of the Builder window contains the work area where chemical systems are constructed and modified.

- Name / Charge / Symmetry

Just above the work area are fields for assigning a chemical system name, assigning an overall charge, and displaying the associated symmetry group.

• Name (optional): The name is used for reports and screen displays that call for a chemical system name (such as the structure library).
• Charge (optional): To assign a charge, just type an integer value or select a common choice from the pull-down menu.
• Symmetry (display only): If a symmetry has been found or assigned in the Builder's Symmetry Toolkit, the symmetry is displayed in the Symmetry field. If no symmetry has been found or specifically assigned, the symmetry displayed is C1 (no symmetry).

- Work Area Tools

Along the left side of the work area are five tool buttons that have the following key functions in the Builder.

Button	Purpose
	Select - Switch to the Select mode cursor (arrow) for selecting atoms and groups of atoms in the work area. How to... Select Items in the Work Area Tip: Keyboard Shortcuts Esc key Toggle quickly between the Select and Manipulate modes. Alt key In Select mode, switch the cursor to the Manipulate cursor as long as the Alt key is depressed. Note: The mode label in the Builder's work area may not change when you use these keyboard shortcuts.
	Manipulate - Switch to the Manipulate mode cursor (hand) for rotating the chemical system in arbitrary directions around a center point ( left mouse button). Note: It's a fine point, but these hand-cursor operations (like the thumbwheels) really manipulate only your viewpoint, NOT the items in the work area. Their space coordinates remain constant. In contrast, see 3D Manipulators and Construction Tools. Tip:In Manipulate mode only--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. Tip: In Manipulate mode only--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.
	Clean (broom icon)- Apply a simple molecular mechanics force minimization to improve the structure of molecules that have been built by hand. The Clean operation is based on the Universal Force Field (UFF) of Rappe and Goddard. 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.
	Orthogonal Plane Views - Open a separate window for viewing the current chemical system in the x-, y- or z-plane. If you open two or three of these windows with different views, you can more easily judge the results of 3D space manipulations.
	Drag Site - This is not a command button but a starting site for dragging the contents of the work area from the Builder to other Ecce tools. For example, if you have a newly created calculation under way in the Calculation Editor, you can use the middle mouse button to drag (the current molecule) from this drag site onto the drop site of the Calculation Editor.

- View Controls

Along the right side of the work area and below it are controls for manipulating your view of items in the work area.

Button	Purpose
	Home - Reset the chemical system in the work area to a "Home" orientation. Tip: Keyboard Shortcut Home key Reset to "Home" orientation like the Home button.
	Set Home - Establish the current chemical system orientation as the "Home" setting.
	View All - Scale and center the chemical system to bring all components within the work area.
	Seek - Switch to the Seek cursor (cross hairs) for selecting an object as the view center point of the chemical system. After selection, the cursor returns to its previous mode.
	Perspective View - This button indicates that the work area is showing a perspective view: "closer" objects appear relatively larger. Clicking on this button toggles the work area (and the button's icon) to the ortho view.
	Ortho View - This button indicates that the work area is showing an orthogonal view: objects appear a constant size, regardless of their front-to-back positioning. Clicking on this button toggles the work area (and the button's icon) to the perspective view.

The following "thumbwheel" controls ( + drag) manipulate your view of items in the work area.
Control	Purpose
Dolly/Zoom	In perspective view, this thumbwheel is labeled "Dolly" and moves the point of view into (or out of) the depth of the work area. In ortho view, this thumbwheel is labeled "Zoom" and merely enlarges or shrinks the size of the work area image. T ip: In Manipulate mode only--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.
X	This thumbwheel rotates the chemical system around the horizontal (X) axis at the current center of rotation.
Y	This thumbwheel rotates the chemical system around the vertical (Y) axis at the current center of rotation.
Z	This thumbwheel rotates the chemical system around the orthogonal (Z) axis at the current center of rotation. T ip: To display X-Y-Z axes and make the thumbwheel rotations more clear, open the View menu and mark Axes.

Menu Bar

- File Menu

The File menu enables you to:
Save	Save the current chemical system to the current calculation. Tip: For a shortcut way to save the chemical system, click on the "Save Work" icon . The icon appears in the window footer whenever you add or modify items in the work area. 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 of a Calculation Editor window or use the Save As option to save the chemical system in a new calculation.
Save As...	Open a file dialog window for saving the current chemical system as part of a new calculation within an existing or new project folder.
Record/Playback...	Open a command recorder (prototype) for recording and saving a sequence of Builder commands to automate Builder tasks. You must specify a writeable location for an XML file that stores the commands.
Import...	Open a file dialog window for importing a chemical system from a file. You must specify the format of the file to be imported. Ecce currently supports several file import formats: Alchemy (TRIPOS), MVM, PDB (Protein Data Bank), XYZ, and others . The XYZ format consists of a line with the total number of atoms, followed by a comment line and lines with an atomic symbol (H, Li, etc.) and the (x,y,z) coordinates in angstroms. Tip: If you import a chemical system that does not have explicitly defined bonds, you can use the Builder's Generate Bonds option to create bonds based on the distances between atoms and a table of standard covalent radii.
Export...	Open a file dialog window for exporting a chemical system to a file in the four formats listed above. Additional formats are available for exporting the chemical system as a graphics file (Postscript, RGB, GIF, TIFF, JPEG, and PICT).
Print...	Open a window for printing the contents of the work area on a selected printer. You can select from a scrolling list of available printers.
Quit	Quit the Builder. If you have created a chemical system and have not saved your work, you will be prompted to do so. Tip: To end an Ecce session and close all tool windows at once, close the Gateway.

- Edit Menu

- Display Menu

The Display menu controls how the atoms and bonds of a chemical system are depicted in the work area.
Style (All) >	Choose from a submenu to select a general display style for depicting atoms and bonds in the work area. (See also Details on this Display menu.) Ball & Stick Ball & Wireframe Stick (bonds) Wireframe (bonds) CPK (space filling) Picture... Atom/Bond Styles
Style (Selected) >	Choose from a submenu to select a display style for depicting all selected atoms and bonds in the work area. Ball & Stick Ball & Wireframe Stick (bonds) Wireframe (bonds) CPK (space filling) Invisible
Render Quality >	Choose from a submenu to select a quality level for rendering the atoms and bonds in the work area.: (See also Details on this Display menu.) High  Medium As the rendering quality decreases, the rendering/display speed increases. Low Very Low Customize... Open a window of chemical system display attributes for modifying the appearance details of atoms and bonds. If the molecule is being rendered as a wireframe, you can control the line width. If you're using stick rendering, you can control the appearance of the stick endcaps, their quality, and their radius. Other options control the Ball & Stick quality. Picture... Customize Details: Chemical System Display Options
Render As >	Choose from a submenu to select how to render the surfaces of atoms in the work area: Normal solid surface Mesh polygon lattice Dots dot lattice
Move as >	Choose from an identical submenu to select which image rendering style (above) is used as you move and manipulate the chemical system. Note: This may be useful for speeding up the manipulation of a chemical system on slow hardware. Depending on your computing platform and details settings (below), the manipulation of the chemical system may be faster and smoother with Mesh or Dots.
Selected atoms	Display only items that are selected in the work area. Unselected items are invisible.
All atoms	Display all items in the work area, cancelling any display limited by selected atoms.
Stereo	Mark this option to see a stereo 3D image of the chemical system on workstations equipped with CrystalEyes® stereo viewing glasses. Note: The monitor must first be enabled for stereo viewing by using a hardware-specific display command .
Depth Cueing	Mark this option to simulate depth perspective: closer objects appear brighter than more distant objects. This is especially useful for viewing larger molecules.
Transparency	When this option is marked, objects in the work area become partially transparent so that you can see how objects overlap.

- View Menu

- Options Menu

The Options menu enables you to generate bonds for imported chemical systems, control details of the "clean" operation, set background and labels colors, and use the special display features of the work area.
Edit Background Color...	Open a color chooser window for modifying the background color of the viewer work area. Picture... Background Color Chooser Window
Edit Atom Label Color...	Open a similar color chooser window for modifying the color of the labels (atomic symbols, bond lengths, etc.) in the work area.
Generate Bonds	If you import a chemical system, it may not have any existing bonds defined, depending on the format of the file. This option attempts to create bonds based on the distances between atoms and a table of standard covalent radii. Tips: About generating bonds You can control the bond generation by adjusting the bond formation tolerance and covalent radius associated with each element by using the Builder's Periodic Table tool (which is opened by the more... button in the Builder). How to... Set radii preferences for generating bonds You can the edit the generated bond types with the bond types palette. If a multiple bond to hydrogen is encountered during bond generation, only the shortest bond is generated. This prevents spurious bonds from appearing in hydrogen-bonded structures (such as double-stranded DNA). If you are interested in structures such as boron hydride, you can still store them without losing bonding information by saving them in MVM format.
Generate Hydrogen Bonds	Determine where hydrogen bonds should exist and display a distance measure between the affected atoms and the corresponding hydrogen atoms.
Recenter Coordinates	Center the chemical system around its center of mass and scale the display to show all components within the work area.
Clean Parameters...	Open a window for setting parameters related to the "clean" operation. The clean operation automatically improves crude guesses to the molecular geometry when you click on the "Clean" button . The parameters include the maximum number of line searches (steps), the convergence on the gradient, and the cutoff distance for computing non-bonded interactions.
Auto Normalize Display	When this option is marked, the Builder recenters the chemical system as you work, continually orienting and scaling the chemical system to fit in the work area as you add or subtract structures.
Enable Spinning	When this option is marked, you can use the Manipulate mode cursor (hand) to impart a spin to a chemical system around its center of mass. To stop the spin, click anywhere in the work area. Unmark this option to prevent accidental spinning. This option is saved as a preference that remains in effect until you change it.
Torsion: Rotate Group	When this option is marked, any adjustment using the torsion tool will move all atoms connected to atom 3 (the third atom selected). When this option is NOT marked, any adjustment of torsion angle will move only atom 4 and all atoms connected to atom 4.

- Toolkits Menu

The Toolkits menu provides access to toolkits for building special kinds of chemical systems.
Symmetry Toolkit...	The Symmetry Toolkit in the Ecce Builder has extensive capabilities for constructing symmetric molecular systems: automatic symmetry group recognition reduction of a symmetric system into a unique set of atoms generation of a complete molecule from a unique set of atoms a "symmetry clean" function that takes an approximately symmetric configuration and applies a set of coordinates that are symmetric to numerical precision additional tools for aligning atoms to particular axes and planes pre-loaded sets of ghost atoms for each symmetry group (for constructing symmetric systems and for indicating the location of the principle symmetry axes and planes for each point group). Picture... Symmetry Toolkit Window Examples... Building chemical systems with the Symmetry Toolkit More About... Symmetry Toolkit - overview of window and controls
MD Toolkit...	The Molecular Dynamics Toolkit in the Ecce Builder enables you to construct very large molecules by means of a number of techniques and tools: import PDB files to create internal residues structure analysis and validation insert/edit/delete residue assign residue atoms write segment or fragment files add hydrogens to the cleaned-up molecule Picture... Molecular Dynamics Toolkit Window More About... MD Toolkit - overview of window and controls
Trajectory Toolkit...	The MD Trajectory Toolkit enables you to import a trajectory file and to view and save the animation. The Trajectory Toolkit supports the NWChem MD trajectory format, and the Ecce input 0.2 XYZ geometric format. For more information on animation, molecular dynamics and NWChem files, see the NWChem User Manual Chapters 22, 27, and 30.
Partial Charge Toolkit	The Partial Charge Toolkit enables you to set up partial charge calculations. The toolkit sets up the calculation to derive partial atomic charges that fit the quantum mechanical electrostatic potential on selected grid points.
DNA Builder Toolkit	The DNA Builder Toolkit enables you to easily create DNA molecules by selecting from a list of base pairs.

- Help Menu

Element/Geometry Palette

This button palette is used like a painter's palette to add atoms in the work area. It includes element buttons for choosing the type of atom and geometry buttons for choosing the bond hybridization/coordination number.

To add a new atom, you must first "load the cursor" with an element--something like a painter loads a paintbrush with paint. That is, click on an element button (or a geometry button, which is automatically associated with an element) and then click on the work area to add a new atom. Each element has a default hybridization or coordination number.

For example, if you click on the carbon button, the geometry button for tetrahedral (sp3) hybridization also appears depressed. The C button will have a highlighted border around it, and a label in the work area will indicate "Atom" mode. Each subsequent mouse click inside the work area will add a carbon atom at the clicked location. If you click on one of the bond nubs (bonding sites) of a previous atom, the new carbon will be bonded to the previous atom. After an element button is selected, you can switch to a different hybridization/coordination number by clicking on a different geometry button.

If you want to use an element or hybridization/coordination number that does not appear on the basic palette, you can bring up other options with the more... button. A new window will appear with the entire periodic table and 12 geometry schemes. When you click on an element in the periodic table, that element will fill in one of the two blank buttons in the element palette. Similarly, when you click one of the 12 geometry buttons, the corresponding icon for that hybridization or coordination number will fill in one of the two blank buttons in the geometry palette. The current version of Ecce allows only two user-specified elements on the element palette and two user-specified hybridizations/coordination numbers on the geometry palette. In each case, choosing a third item will cause the first item to be removed.

Add/Remove Hydrogens

	Add hydrogens at all empty nubs.
	Replace all hydrogens with empty nubs.

Bond Types

The bond palette enables you to specify a bond type for bonds formed between atoms in the work area. The bond types used will affect the "clean" operation, which adjusts the molecular geometry when you click on the "Clean" button . The bond type buttons are disabled until the first atom is added in the work area.

The currently supported bond types are 1) single bonds, 2) double bonds, 3) triple bonds, 4) aromatic bonds and 5) metal-pi bonds.

The conventional bonds (the first 4 types) all work the same way:

• After you click on one of the bond type buttons, that bond type will be used for new bonds in the work area. For example, if you want to build a molecule with doubly bonded carbons, you can click on the double bond button and then click on the C button.
• To add a new atom and bond simultaneously, click on a bonding site or "nub" of an atom in the work area.
• To create a bond between two atoms already in the work area, first click on the bond type button and then select two atoms (or vice versa). One bond nub is used from each atom.
• To change an existing bond to a conventional bond type, first click on the bond type button and then click on the existing bond (or vice versa).

The metal-pi bonds work differently in these ways:

• After you click on the metal-pi button, your only option is to add a metal-pi bond between two existing atoms.
• Metal-pi bonds ignore bond nubs.
• You cannot convert a conventional bond type to a metal-pi bond.

Bond types are depicted only in the wireframe style of rendering. With other styles you won't be able to see a difference between the different bonds.

Structure Library

As an aid in constructing larger molecules, the Ecce Builder has an extensive collection of molecules contained in a structure library. These molecules can be easily added to the work area. The Structure Library button (located below the element/geometry palette) opens the Structure Library window. The Builder then switches into "Add Structure" mode.

In the Structure Library window you can choose from a number of pictured molecules by clicking on the name of a molecule. Then as long as you are in "Add Structure" mode, each mouse click in the Builder work area will add the selected molecule at the clicked location. The Structure Library tool includes options for creating your own structure libraries and for importing and exporting chemical systems to a structure library.

Measurement-Adjustment Tools

The four measurement-adjustment tool buttons below the Structure Library button enable you to display and modify atomic distances and angles, including dihedral angles (torsion). Measurements remain displayed in the work area until canceled by the Cancel Measurements button.

Button	Measurements Display
	Distance- After clicking on this button, select two atoms or a bond. The distance (in angstroms) between atom centers is displayed along a dashed line between the atoms.
	Angle - After clicking on this button, use Shift +  to select three atoms (one at a time) to define an angle. The measurement is displayed along a dashed line between the bonds.
	Torsion - After clicking on this button, use Shift +  to select four atoms (one at a time) to define a dihedral angle. The first three atoms define one plane, while the second three atoms define another plane. The measurement is displayed along with the planes that define the angle.
	Cancel Measurements - Remove all displayed measurements from the work area. The current operating mode is unaffected.
Picture... Measurement Examples

To MODIFY the measured geometry: After displaying a measurement, click on the dashed line (for distances and angles) or dihedral plane (for torsion). A small dialog window then displays the current value of the corresponding measurement. If you enter a new value, the last atom selected will move to reflect the new geometry.

3D Manipulators and Construction Tools

The eight buttons located below the measurement-adjustment buttons enable you to move and rotate atoms in 3D space, create "ghost" atoms that make building certain types of molecules easier, and add dashed lines between atoms to highlight their relationship. These buttons occur in pairs. The upper button of each pair activates the option. The lower button (with a red X) erases the corresponding tool from the work area (but does not cancel the option). A highlighted border appears around any active tool button.

Buttons	Purpose
	Move & Rotate Atoms - When you activate this option, a single wireframe manipulator sphere will enclose atoms that are already selected. After this option is active, select single atoms (or several atoms together) to get additional manipulators. Picture... Manipulator Sphere 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 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.
	Rotate About a Bond - 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 To rotate atoms about a bond Click 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.
	Ghost Atoms - After clicking on this button, you can click in the work area to position a "ghost atom" (a small placeholder ) at any point in 3D space as an aid to building a molecule. For example, sometimes it is helpful to position a ghost atom as a reference point at the center of a group of atoms. When you are finished and no longer need the ghost atom, just click on the X-Ghost Atom button. Picture... Ghost Atom To position a ghost atom centered in a group First select a group of atoms (in Select mode). Then click on the Ghost Atom button. The ghost atom will appear at the center of the structure. Note that this method (as well as accidentally clicking on atoms in Ghost Atom mode) can create ghost atoms "inside" other atoms, where they may be hidden from view.
	Atom Lines - After clicking on this button, select two atoms to draw a dashed line between them. This can aid your perception of the 3D space. The lines could also be useful for complexes containing cations or anions: you could use a line to indicate an electrostatic interaction without actually specifying a formal bond. Picture... Atom Lines

Window Footer

At the bottom of the window is a footer that displays status information as well as a drop site for receiving calculation inputs that have been "dragged" from another tool:

• the project path and name of the current calculation
• a colored icon that indicates the current state of the calculation
• a message area for system prompts and messages
• "Save Work" Icon -
  If you see a star-shaped icon, this indicates that you have added or modified items in the work area but have not yet saved them. To save the current chemical system, just click on the star icon.
• Padlock Icon -
  If you see a padlock icon, this indicates that the current calculation is locked. You will not be able save changes to the chemical system.

• Drop Site - The "in-tray" square at the right side of the footer is a drop site destination for "drag & drop" operations. For example, you can use the middle mouse button to drag a calculation from the Calculation Manager and drop it on this site.