Overview - Learn to Use Ecce

Start here to learn key concepts, terms, conventions, and options for using Ecce.

See also... How to Acknowledge and Cite Ecce Go to Ecce's Citations page outside of Ecce Help

Key Concepts to Know About Ecce

An Ecce calculation refers to

To run Ecce calculations, you must have UNIX accounts set up for 1) at least one machine where you can run the Ecce software, and 2) at least one Ecce-registered machine where the calculations can be processed and the appropriate computational codes are available. These may be the same machine. If you have accounts on several Ecce-registered machines, then you have more options about where to run calculations.

After your account(s) are properly set up, you can prepare and launch a calculation from your desktop workstation. Launch means to submit a calculation for processing on an Ecce-registered machine. Your desktop machine either runs the Ecce software or is logged in to a machine that can. The machine that runs the Ecce software is the launch machine. The machine that runs the computational codes is the run machine, sometimes referred to as the remote machine (even if it isn't really remote).

The inputs and results of calculations are stored on an Ecce Web server. This "database" of calculations is organized as a hierarchy of projects and calculations, roughly comparable to the folders and files of a personal computer. A project is a container that may include calculations and other projects. In this context, each calculation is an object that includes code input files, machine configurations, output files, and Ecce run logs. The Ecce Calculation Manager visually represents the calculation database as a collection of project folders that contain calculations.

Most Ecce users store their calculations in the "users" folder of the Web server, although it is possible to store calculations (and other Ecce objects such as chemical system structures) in any folder where you have read/write access.

Pathname structures

/ users / username / project / calculation
/ users / username / project / subproject / calculation

Example pathnames /users/raypalmer/HardWater/IceNine

A calculation also produces temporary files on the run machine--the Ecce-registered machine that processes a calculation. These include output files in a calculation directory and working files in a scratch directory. After successful completion of a calculation, the output files are copied from the calculation directory on the run machine to the project folder on the Ecce Web server, where they are stored as part of the calculation object.

Note: These run machine files are NOT automatically deleted: they can be useful for diagnosing run problems and for backup in case of network failures. You can (and should) clean up these run directories periodically to conserve disk space. See the Calculation Manager's option for Run Mgmt: Cleanup Run Directory Files.

Calculation property data displays are dynamic. Most displays of Ecce data are updated to reflect the changing conditions (as a running calculation completes each processing step, for example).

Conventions for Using Ecce

It will be helpful to understand the following conventions as you interact with Ecce tools and processes.

- Tool Windows

You can start the major Ecce tools either from the Gateway or from the Tools menu of an Ecce tool window. Although many tools operate in the context of a single calculation, you can open multiple instances of a tool window to work on more than one calculation at a time by shift-clicking on a tool icon in the Gateway or on a menu item in a Tools menu..
How to... Manage Tools on the Desktop

Most major tool windows include a menu bar for choosing task options and a window footer.

Menu Bar
Each of the menus on the menu bar can be "torn off" as an independent window that remains visible while you work. To "tear-off" a menu, open the menu by clicking on the menu title and then choose the dashed line that separates the menu title from the menu options.
Tip: Open any menu from the keyboard by using the Alt+underlined letter combination (for example, Alt+h opens the Help menu). Then select a menu option by pressing the letter that corresponds to the option.
Window Footer
A footer area at the bottom of most tool windows displays status information. The footer usually includes a message area for system messages and instructions.
More about... Items in the Ecce Window Footer

- Labeling Conventions

The labels on buttons and in menus convey the following information by their appearance.

Label Examples Convention

Dark labels - indicate that the option is available.

Grayed-out labels - indicate the option is not available in the current context. The option will become available under other conditions.
Ellipsis marks (. . .) - indicate that the option will open a separate window or dialog for further interactions.

- Visual Indicators (What's Happening?)

The mouse cursor and various elements of Ecce tool windows provide visual feedback about current operations and conditions.
Mouse Cursors The mouse cursor will change color and shape to indicate the status of various operations. For example:
Yellow cursor - indicates Ecce is processing a request (such as opening a tool after you click on an icon in the Gateway).
Stopwatch cursor - indicates Ecce is processing a tool request (such as loading calculation properties into the Calculation Viewer after a drag-and-drop from the Calculation Manager).
Drag & Drop cursor - indicates that an information object is being dragged. The cursor turns green when it points to a drop site where the object can be dropped. The cursor turns red when it points to a drop site where the information is inappropriate and cannot be dropped. The actual appearance of the drag & drop cursor varies, depending on the graphic interface of your system.
Hand cursors - indicate various types of chemical system manipulation operations in the Builder tool.
Icons Special icons in the Gateway or in tool windows indicate the status of programs or data.
Ecce wave animation (System Busy icon in the Gateway) - indicates that an Ecce tool is opening.
Tip: If you click on the Ecce wave while it is moving, the animation will stop for that instance. You can permanently disable this system busy icon by changing Preferences.

Calculation state icons - indicate (by their shape and color) the preparation or processing state of Ecce calculations. For more details, see Legend of Calculation Run States in the Calculation Manager.
Save Work Icon "Save Work" star icon - indicates that your work in an Ecce tool has not been saved to a database. (Click on the star icon to save your work and remove the Save Work icon.)
Padlock Icon Padlock icon - indicates that you cannot change inputs in the current window at the current time, such as the inputs of a running calculation.

- Mouse Conventions

Left click - Most mouse interactions in Ecce use the left mouse button. When following online help instructions, use the left mouse button unless specified otherwise.
Shift + 
Ctrl + 
Shift-click and Ctrl-click - Combinations of the left mouse button with the Shift or the Ctrl key are used for various special purposes in data tables, in the Builder work area, and the Calculation Manager. These uses are specified in the online help pages for the corresponding tools.
Middle-click-and-hold - The middle mouse button is used generally for Ecce drag & drop operations (as well as special operations in the Builder).
Right-click - The right mouse button is most often used to open a pop-up menu of options that apply to the clicked area.
Point-and-Help - The Help key (typically the F1 key) is used with the mouse pointer (no button click!) to provide access to Quick Help - short descriptions of items within a tool window.

- Drag & Drop

Ecce's drag & drop operations enable you to use the mouse to move several kinds of information within and between Ecce tools. By use of the middle mouse button, certain information objects can be quickly dragged from one location and dropped at another. Examples:

Reorganize items within a tool
Change the position of a calculation property column in Calculation Manager (in the Edit / Preferences window).
Move or copy (Ctrl + ) your folders in the project tree of the Calculation Manager.
Change the position of a property in the summary list of the Calculation Viewer.
Move information between tools
Drag a calculation from the Calculation Manager
- to the Calculation Editor (for editing input parameters for that calculation)
- to the Basis Set Tool (for choosing basis sets for that calculation)
- to the Calculation Viewer (for visualizing the calculation's chemical system)
Drag a chemical system from the Builder to another tool such as the Calculation Editor.

The information actually transferred between tools depends on what information is usable in the destination tool. For example, a calculation object dragged from the Calculation Manager can load the Builder with the calculation's chemical system or load the Calculation Editor with the calculation's current input parameters.

How to... Drag & Drop with the Mouse
  Move a Project or Calculation in the Calculation Manager

Drop Sites. Information can be dragged only to a drop site - a destination for "drag & drop" operations.

Warning: Dropping on a drop site that is not ready (usually because it is still processing the last drop) may cause crashes. See how to Drag & Drop with the Mouse (above).
Drop Sites Description
drop site The square "in-tray" area in the lower right corner of many Ecce windows is the main type of drop site for receiving information from other tools.
In the Calculation Manager's project tree, you can move or copy (Ctrl + ) one of your project folders by dragging and dropping it onto another of your project folders.
Summary Caption In the Calculation Viewer, summary item captions can be rearranged by dragging and dropping them onto each other.

Exporting and Importing Ecce Data

Exportable Data Export Format(s) Tools and Options
Chemical system molecular structure and graphic formats Builder / File menu / Export
Structure Library / Structure menu / Export
graphic formats Calculation Viewer / Calculation menu / Export
Values for a calculated property (table) spreadsheet-readable formats Calculation Viewer / data panel / pop-up menu / Export
Basis sets selected for a chemical system ASCII file Basis Set Tool / Molecular Basis menu / Save to File

A general printing option in several tools enables printing either to a postscript file or to a postscript printer selected from a list of available printers.

Printable Data Tools and Options
Chemical system image Builder / File menu / Print
Calculation Viewer / Calculation menu / Print
Values for a calculated property (tables and graphs) Calculation Viewer / data panel / pop-up menu / Print

Importing options include molecular structures and completed calculations.

Importable Data Import Format(s) Tools and Options
Chemical system molecular structure formats Builder / File menu / Import
Structure Library / Structure menu / Import
Basis Set Tool / Browse Options menu / Import Fragment
Calculation (code outputs)

NWChem output file (ecce.out)
Gaussian94 output file (filename.out)
Gaussian98 output file

Calculation Manager / Calculation menu / Import

Customizing Ecce

Ecce includes several preferences that you can set to control the behavior and appearance of Ecce tools. Preferences include the date format, the colors associated with calculation run states, and some units (energy, distance, frequency).

Moving Between Ecce Versions

If you need to run both Ecce v2.1 and v3.0 or higher back to back, Ecce offers a simple mechanism to support switching preference files between versions. When you first start v3.0, Ecce recognizes the presence of any v2.1 preference files and converts them to v3.0 format. The v2.1 files are copied to files of the same names with extensions of .v2.1. By copying the .v2.1 files back over top of the v3.0 counterparts, the older version of Ecce can be run again and Ecce will re-convert the files to v3.0 format when that version is run. A new script named reformat_machines is automatically called by Ecce to do this conversion for you.

How to... Set Preferences

Ecce Online Help
Revised: April 29, 2004