Cactvs Editor Manual


by Wolf-D. Ihlenfeldt
wdi@eros.ccc.uni-erlangen.de

for Version 2.13


The Cactvs System Editor

The Cactvs molecule editor is a graphical mouse-oriented X11 Unix-based tool for the input of molecular structures. It can be used both in stand-alone mode, optionally with Drag&Drop to and from other stand-alone programs from the Cactvs tool series, or as a dependent remote program of a Cactvs computational workbench.

The editor has been influenced by and drawn many ideas from the magic structure editor (author Robert Höllering, written in Fortran for the GKS graphics standard) and the med editor (author Wolfgang Witzenbichler, written in C for SunView). This program is more or less a superset of the functionalities of these earlier programs and adds numerous advanced features not found in magic or med. However, the source code is completely independent.

The 2D display coordinate generation is based on the algorithms of Craig Shelley.

This manual describes version 2.13 (December 22th, 1995) of the editor script.

All programs, scripts and documentation by Wolf-D. Ihlenfeldt. All rights reserved.

Cactvs System Tool Usage Licence Terms

This program is provided as is without any express or implied warranties. While every effort has been taken to ensure proper operation of the program, the author assumes no responsibility for errors or malfunctions, or for damages resulting from the use of the program.

This program is usable free of charge by anybody for any purpose, but it is not completely in the public domain. You may adapt the functionality of the program to your local needs, but you are forbidden to redistribute copies of the files comprising the program which were altered in any respect. If you add a valuable feature, or hunt down a bug, you are welcome to contact the author by email and he will most certainly add it to the one and only official release. Dynamically loadable modules of any kind, like I/O format extensions, property computation modules, data analysis tools, or GUI scripts, written completely by yourself, for example for the standard visualization server programs of the Cactvs system, are exceptions to this policy. You are welcome to distribute these by any means, preferably Cactvs system network databases. Simply slightly edited GUI scripts from the base distribution remain subject to the distribution limitations.

If you use data generated or analyzed by Cactvs tools for publications, you should cite a Cactvs paper, for example:

1) Computation and Management of Chemical Properties in CACTVS: An Extensible Networked Approach toward Modularity and Compatibility

W. D. Ihlenfeldt, Y. Takahashi, H. Abe, S. Sasaki, J. Chem. Inf. Comp. Sci. 34 (1994), 109-116

The data model of the CACTVS program suite (Chemical Algorithms Construction, Threading and Verification System) is presented. CACTVS is an open environment which readily integrates new computational modules and data format descriptions in the domain of computational chemistry. These chemical information (property) computation modules are provided with requested input data, typically transparently computed by other modules. Computational results are managed appropriately with regard to file and data base I/O, transport to display servers, input for high-level routines and report generation. Definitions of property characteristics which include optionally precompiled objects and source plus additional documentation may be stored in networked data bases for global access. This facilitates module reusal and the exchange of modules between interested parties. The elementary data format handling routines and the property computation routines need not to be part of the core program. They are retrieved from and loaded dynamically at runtime from local files or data bases which can be reached on the network. This lookup process can be made completely transparent, resulting in a comparably small core program which grows only on demand to incorporate procedures for the evaluation of requested information. A model for asynchronous distributed client-server computations is supported as an alternative to dynamic linking for expensive calculations. CACTVS is intended to make algorithm development in chemistry more productive and to help in collecting the synergistic benefits from the concerted application of compatible algorithm sets which derive chemical information in all its variety

2) Dataflow Processing in a Global Networked Context: A Solution for the Computational Method Pool Management Problem

W. D. Ihlenfeldt, Y. Takahashi, H. Abe, Proc. 28th Ann. Hawaii. Int. Conf. System Sciences, L. Hunter, B. D. Shriver (Eds.), IEEE Computer Society Press, Los Alamitos, U.S.A., 1995 Vol. V 227-236

While the number of computational methods available to approach problems in computational chemistry is steadily increasing, synergetic effects from the combination of a multitude of complementary methods fail to materialize in the expected extent. We introduce a system which provides an extensible networked environment for the computation, analysis and visualization of chemical data of arbitrary definition. The core is a flexible data manager connected to a network of algorithmic module databases. Upon accepting a request for some piece of chemical information, the system looks up methods to derive this information and autonomously invokes the necessary procedures to obtain the requested property data. Other types of modules available in a similar fashion include data analysis procedures or tools and visualization components. Complex sequences of computations and data analysis are specified in a visual programming environment, using building blocks obtained from sites all over the world. An increase in new algorithm implementation efficiency and notable synergetic effects are expected.

Starting the Editor

In stand-alone mode, the program is started from the command line with

csed [-l library_file] [-h helpfile] [-?] [-p] [-r] [filename]

csed is an abbreviation for Cactvs System Editor. All major tools in the Cactvs environment which can operate in a stand-alone mode are started with commands begin with cs, followed by a mnemonic tool name abbreviation (br - browser, ir - IR spectra display, nmr - NMR spectra display, xy - 2D data plotter etc.). If a filename is specified, the contents of this file are read into the editor buffer. The file is read completely up to the end, so be careful not to call the editor with a 10.000 record file. The contents of the first input file record are displayed on the drawing area. If no file was given, the canvas is empty.

The other options are:
-l: Load a private library file. The file should have been created with the fragment library facility of the editor.
-h: Specify a custom help file.
-r: Start with open file selector box for reading.
-p: Start with open print panel.
-?: Get list of available command line options.

Of course it is possible (and potentially useful) to add I/O redirection and pipes to and from other programs on the command line.

Basic Operations

The next sections give a short overview about the basic operation principles of the editor. Not all features will be covered here, only the most important.

After start-up, the editor displays a single window, the main editor window, shown on the first picture on the next side. The most important user interface elements are tagged. On the drawing area the molecule(s) are displayed and assembled. It is possible to resize the main window by the standard window manager mechanisms, i.e. drag on the corners. Most other windows of this program are of fixed size.

The Mode Selector Switch

The mode selector switches between the eight major operating modes of this program. The active mode is highlighted in green1. Modes are changed by clicking on the symbol in the top panel. An informative message is printed on the status line at the bottom of the window. These messages are deleted after a few seconds. Informative messages are printed in black. Errors and warnings are painted bright red and the bell rings. So whenever the editor chimes at you, read the message in the status line for a terse explanation.

The eight major modes are from left to right:

Drawing Atoms and Bonds

The major editor mode must be set to pencil first in order to be able to add atoms or bonds. The type of atom to be added is selected on the element selector panel. The most often used elements are lined up on this panel and can be selected with a mouse click. The currently selected element type is highlighted in green.

Clicking with the left mouse button on some empty space on the canvas adds an atom immediately, even before the mouse button is released. At the same time, if the ring grid is not set to none, ortho or custom, a ring of twelve cross-shaped markers in the pattern of a clock face appears. They are set 30 degrees apart and are location proposals form atoms bonded to the atom just entered. If the mouse is dragged4, a rubber band line extends from the last atom. A second atom of the same type is added if the mouse button is released at some distance from the start atom. If the mouse is not moved noticeably before the button release, no second atom and no bond is created. If the release point is near one of the cross-shaped markers, the second atom snaps to the marker position. If the release point is near an already existing atom, no new atom is entered. Instead a single bond is formed between the start atom and the closest atom, provided the number of shell electrons on both atoms is sufficient. Closeness to an atom is about 50% stronger than closeness to a marker point. You are not required to link to a marker or an atom. If you keep sufficiently away from any atom or marker, a new atom is placed exactly on the requested location.

Drawing may continue immediately after adding a second atom. Press the left mouse button and again a pattern of marker points appears. If the start atom forms already bonds, the number of marker points is reduced. In addition not only cross-shaped, but also small circular markers may appear. This is described below in detail. If the current ring size is set to six (the default), the drawing of perfect six-membered rings is trivial. All you need is to follow the cross marks across the canvas in an intuitive procedure. After the initial twelve markers, only two are displayed in the following steps, 120 degrees to the left and 120 degrees to the right. If you keep stubbornly left or right, the ring closes perfectly.

If the fixed bond length switch is active, the rubber-band will always have the length of the currently selected bond type. The mouse cursor only controls the compass direction. The new bond will continue to snap to grid points (which always are at the correct distance) and close atoms, even if the distance is not correct. However, if a new atom is introduced, it will always be at the end of the rubber-band, at a fixed distance from the starting point.

Branched skeletons can be started at any atom which forms already two bonds and has shell electrons left. The mouse is clicked on such an atom and dragged to the position of the new atom. Again markers pilot the process, and the same considerations about close markers and atoms apply as in the first linear drawing steps. If the element type has changed in the meantime, the new atom will have the type of the active element. The start atom is not changed if the mouse is actually moved before the button is released.

The distance of the grid markers from a source atom can be adjusted with the bond length selector panel. The default bond length is medium and is reset to this value if the canvas is cleared.5

By default, the editor will try to keep a little more than one bondlength distance between the border or the canvas and the last atom. If a molecule plot proceeds toward the border, the canvas automatically scrolls to maintain that distance. This is a very powerful and convenient feature, but some users tend to find it irritating. It can be disabled in the Props menu.

While the molecule is edited, the formula and weight displays (see below) are continuously being updated. These are read-only fields.

Drawing Markers and the Ring Grid

Cross-shaped and round drawing markers have been briefly mentioned in the previous section. In this chapter, an attempt is made to briefly describe the algorithms which decide where these markers are placed. With these markers, it is possible to draw perfect rings - not just six-membered rings as in the previous example, but rings of size three to nine, separate from other rings or joined to each other. They are a very powerful tool and actually pretty easy to use, although the algorithms behind them are sophisticated. and you should have a basic understanding of the workings behind the scenes.

The current ring grid is selected in the ring grid selector. In contrast to other popular commercial molecule editors, this is not a tool to introduce complete rings onto the canvas. This editor provides other mechanisms for this operation. The ring grid selection is by default set to a six-membered ring, and is reset automatically when the editor canvas is cleared. The upper part of the panel shows from top to bottom: A whirlpool (i.e. no ring, mode none), three- to nine-membered rings, the ortho special setting and the custom grid.

First the normal settings (three-membered to nine-membered rings) are described. They all use the same algorithms, only adapted to their respective size. If a new atom is introduced and it has no bonded neighbors, twelve marks corresponding to the twelve clock hours are always displayed. After that, the number of already bonded neighbors and the selected ring size jointly determine the type and number of markers displayed.

In case of one neighbor, four markers are shown. The first two are crosses, their angle to the already existing bond, taken at the current atom, is , and the second set of round markers is . If the markers overlap as in the case of four- and six-membered rings, only the crosses are shown. The cross markers correspond to the inner angle of the rings of the respective size. For example, after selecting the five-membered ring, it is only necessary to follow the cross markers clockwise or counterclockwise in order to close a perfect five-membered ring.

In case of two neighbors, two cross marks are displayed at positions which are at half the angle between the two ligands. Four additional round markers are put at the positions which are the connecting points for perfect circles of the selected size, which use one of the two bonds of the current atom. Each bond gets two markers: One to close the ring going left, one to close the ring going right.

In case of three or more neighbors, only cross markers at positions which cuts a ligand angle into two equal parts are presented.

The interplay of these simple rules makes it possible not only to construct simple rings and nicely placed exocyclic ligands, but also fused ring systems.

A simple example will clarify how to proceed. In order to draw a ring system consisting of a six-membered ring fused to a five-membered ring, first make the larger ring. Then switch to ring size five. Start drawing on one of the ring joints as shown in the graphic on the next page. In order to end up with the standard ring system orientation and to draw in the familiar clockwise orientation, the 2 o`clock atom of the cyclohexane skeleton should be selected. Six markers will appear: two crosses, which dissect the ligand angle and are not useful here, and four rings. The ring slightly below the cross outside the six-membered ring is our attachment point. This point uses the vertical bond to the 4 o`clock ring atom as the first ring bond and continues outwards in clockwise direction. The other ring mark belonging to this bond is inside the ring, close to the 12 o`clock atom. If this mark is followed, the five-membered ring will be inscribed in the six-membered ring. The round mark slightly above the cross marker outside the six-membered ring belongs to the bond from the 12 o`clock atom to the 2 o`clock atom. If this marker is followed counterclockwise, the ring is fused diagonally on the upper right to this bond. Likewise, the last marker inside the six-membered ring near the four o`clock atom inscribes the smaller ring fused to the 12 o`clock - 2 o`clock bond if followed clockwise. After creating the first exocyclic bond, just follow the inner cross markers which appear when you continue drawing from the last atom and the ring closes perfectly at the 4 o`clock ring atom.

The graphic on the next page is probably easier to understand than the textual explanation. The ring drawing business becomes natural quickly once you have experimented a bit, but seems to be extremely difficult to convey to anybody just reading. We think it`s a really cool feature. Even though the ring grid mechanism is powerful: The simple example structure can be entered much more easily with only two keystrokes. This will be explained in the chapterFast Construction of Ring Systems and Carbon Chains.

Note that, depending on the angle of the two start bonds, the correct ring mark to follow can lie on the other side of the angle dissection cross. For example, if a seven-membered ring is to be joined to the same six-membered ring in the example above, the right mark is the one slightly above the cross outside the ring. Of course, the overall positions of the four ring marks is also different from those in the example case. The ring marks inside the ring move just a little bit outside the ring because the potential seven-membered ring drawn in this direction encloses the start ring and not vice versa like in the first example.

Three ring modes remain which have not yet been explained. The simplest one of these is the none setting. The symbol is the whirlpool at the top. This mode suppresses grid markers completely. New bonds still snap to close atoms, but you are not distracted by markers pulling your bond into an orientation you don`t want. The ortho mode with the symbol of the square sitting on its side (in contrast to the four-membered ring icon, which sits on an edge) always displays four cross marks. They are precisely above or below or straight to the left or right, completely ignoring the environment of the atom clicked at. This mode it primarily useful to draw substituents on rings in special projections, i.e. for sugar chemistry. The final ring mode is custom.

The symbol is the angle with the embedded question mark. In this mode, exactly eight markers are displayed under all circumstances, irrespective of the source atom environment. The four cross markers are placed at 0 degrees plus or minus the custom degree angle and at 180 degrees, again plus or minus the custom angle. The four ring markers are positioned in the same pattern at 90 and 270 degrees. By default, the custom grid angle is 30 degrees. In order to change the angle, the name entry must be set to Grid first by choosing from the menu of the button to the left of the entry. The current value is displayed in degrees in the entry field. In order to change it, any floating point expression, even including sin()/cos() formulas etc., can be written in the entry field. After pressing the Return button, the new grid value becomes valid and the ring mode is set automatically to custom. The custom grid value is part of the parameter set which is saved when a configuration file is written.

Keyboard shortcuts support quick switching of the size of the ring grid They are active anywhere on the canvas.
TABLE 1. Ring Grid Shortcuts
Shortcut

Grid Size

Shortcut

Grid Size

@

none

3

3

4

4

5

5

6

6

7

7

8

8

9

9

#

ortho

%

custom

Changing Element Types

If you click on an atom once without moving the mouse and the active element type is different from that of the selected atom, its type is changed, provided the number of shell electrons of the new element is sufficient to satisfy the bonding requirements. Attributes such as charge and stereochemistry are left unchanged.

The active element type is changed on the element selector panel. The most common elements are assigned to buttons. At start-up, or after the canvas has been cleared, the active element is reset to carbon. The Xe button is the default button for reconfiguration. Any element in the PSE which is not yet assigned to a button on the panel, can be put onto a button. Pressing the PSE button opens a PSE display and selects the Xe button.

The highlighted button on the element selector in the main window is reconfigured to a new element if an element button on the PSE panel is pressed. The window closes automatically after this. If for some reason you don`t want to reconfigure the default Xe button, you can select another element button on the main window while the PSE panel is open. This selected button will be the target for reconfiguration. After changing an element button the new element will become automatically active.

It is not strictly necessary to have a button for the active element. If the carbon button is redefined and the canvas cleared, carbon is the active element, but no button will be highlighted.

Experienced users will routinely use keyboard shortcuts to change the current element without moving the mouse out of the canvas. The shortcuts are listed in the table below. A mnemonic hint: elements with a two-character abbreviation have an uppercase letter as shortcut. Elements with single-letter names use a lower-case shortcut.
TABLE 2. Element Shortcuts
Shortcut

Element

Shortcut

Element

A

Aluminum (Al)

b

Boron (B)

B

Bromine (Br)

c

Carbon (C)

C

Chlorine (Cl)

f

Fluorine (F)

F

Iron (Fe)

h

Hydrogen (H)

i

Iodine (I)

k

Potassium (K)

L

Lithium (Li)

M

Magnesium (Mg)

n

Nitrogen (N)

N

Sodium (Na)

o

Oxygen (O)

p

Phosphorus (P)

s

Sulfur (S)

S

Silicon (Si)

T

Titanium (Ti)

X

Xenon (Xe)

?

Any Atom (Substructure Search)

If an element which was selected by a shortcut is not on the element selector panel, the Xe button is automatically reconfigured. The keyboard shortcut should be issued while the mouse is not over an atom or a bond. Atoms and bonds have a separate set of shortcuts for setting and adjusting attributes with overlapping keys.

Changing Bond Orders

Clicking with the left mouse button on a bond once changes its bond order. The bond cycles through all bond orders accessible by the open valencies of the bond atoms. The maximum bond order is three. If the bond is member of a ring with size smaller than eight, the maximum bond order is restricted to two.6 Changing the bond order destroys stereochemistry at that bond with the exception of those based upon label-based nomenclature. Note that a double-click on a bond opens a bond attribute window, so it should be avoided to click too fast.

Deleting Atom, Bonds, Molecules and Everything

Deletion is either performed with the middle mouse button or with the left mouse button in the eraser mode.

Clicking the mouse button on an atom or a bond deletes the atom or bond. As a convenience, unbonded hydrogen atoms which are the result of the deletion of another atom are also automatically cleared. If the button is not pressed directly on an atom or a bond, dragging creates a rubber-banded box. When the button is finally released, all atoms and bonds enclosed in the area are deleted.

There is also a way to delete everything except a rectangular area. Hold down the shift button while you drag the rubber-band box with the middle mouse button (or with the left button when you are in the eraser mode).

In order to remove a whole molecule, the mouse pointer must be in the molecule box, but not on an atom or a bond. The molecule box is the rectangular area which encloses a molecule. Actually, it is even a few pixels larger. If the mouse pointer is in more than one molecule box, the molecule whose center is closest to the pointer is selected. If the right mouse button is pressed in the molecule box, or more general, if an operation is performed on this box, it is highlighted with a green frame so you can verify you have selected the right molecule. The molecule operations menu pops up. The first menu entry is a command to delete the molecule in the box. The keyboard shortcut for molecule deletion is Ctrl-Z. Another alternative is to click the middle mouse button in the molecule box while the control key is held down.

The whole canvas is cleared with the Clear Canvas command in the Edit menu in the menu bar on top of the main window. If the editor buffer contains molecules, for example because the editor was invoked with a file which was not empty, they are not affected by this operation. The buffer plus the canvas, i.e. really everything, are cleared with the Clear Buffer and Canvas command in the same menu. The keyboard shortcut to clear the canvas is Ctrl-X. There is no shortcut to clear the whole buffer and the canvas.

Undoing Changes and Setting Checkpoints

The most recent change to the canvas drawing area can always be undone. The Edit menu contains an Undo entry. Keyboard shortcuts are either Ctrl-U pressed anywhere on the canvas or the key labelled Undo, which is found on the keyboards of Sun workstations.

It is possible to save the current canvas contents at any time and return to the remembered state later. In the Edit Menu, the Set Checkpoint entry memorizes the current data. It is restored with the Return to Checkpoint command right below in the menu. With this method, you can only have a single checkpoint. Advanced users can save structures by putting them into the buffer, the fragment catalog or dragging them to a parallel csbr application. These methods are explained in the part for the advanced user.

Fast Construction of Ring Systems and Carbon Chains

A number of shortcuts are available to construct ring systems and other skeletons very rapidly. The core skeleton of the steroid class can be entered with only four keystrokes. Due to these input features, the need for a fragment library is greatly reduced. The editor still contains such a library, but it is hardly used in common everyday input tasks, except for really complex heterocycles, cage compounds, and difficult stereochemistry. It is described in the expert section of the manual in the chapter The Fragment Library.

The canvas has a fragment menu which is popped up with the right mouse button. This works only if the button is pressed while not resting on an atom, a bond or within a molecule box. Refer to section Deleting Atom, Bonds, Molecules and Everything for a definition of the term molecule box. The menu offers carbon rings size three to nine, the phenyl ring and linear zigzag carbon chains of length two to nine. The corresponding keyboard shortcuts are Ctrl-3 to Ctrl-9 for the rings, Ctrl-p for the phenyl ring and Meta-2 to Meta-9 or, if you keyboard doesn`t have a Meta key, Alt-2 to Alt-9 for the chains. The fragments are put on the canvas centered around the point the mouse cursor occupied when the keyboard combination was input or the menu popped up. Carbon chains are laid out in x-y direction starting with a down-stroke at the first bond. Moving the mouse while selecting from the menu does not influence the placement. The Shift-Meta-3 to Shift-Meta-9 or Shift-Alt-3 to Shift-Alt-9 combinations differ from the simple unshifted Meta-commands in that the main chain is shortened by one atom and substituted in the 2` position, i.e. an iso chain is built. Ctrl-6 and Ctrl-P are probably the most commonly used shortcuts in the editor. Many molecules contain a six-membered ring or a benzene ring as part of the core. Changing an element in the ring later is typically simpler than building the ring step by step with the correct atoms.

The direct placement of simple rings is nice, but only useful as a starting point. The full power of the fragment construction system is unleashed only while appending to existent atoms and bonds. Pressing one of these shortcuts including Ctrl-p, on an atom which still has free electrons left adds the fragment connected with a single bond. The fragment is automatically aligned as to fill the largest free gap in the ligand sphere, but not more than 120 degrees rotated from one atom. Pressing Ctrl-Shift-3 to Ctrl-Shift-9 on an atom adds the ring as a spiro substituent, if the start atom as already two ligands, or tightly (without additional bond, the start atom becomes the first ring atom) joins the selected rings. On atoms, iso chains (i.e. the linkage point is in 2` position) are added instead of terminal chains if a Shift-Meta-3 to 9 or Shift-Alt-3 to 9 combination is pressed instead of the unshifted command. Finally, Ctrl-T adds a tert.-butyl substituent to an atom. These operations (ring addition, chain or iso-chain addition, spiro linking, tbutyl-substitution) are also accessible from the atom menu, which is brought up when the right mouse button is pressed while the cursor is on an atom symbol or in the invisible atom box, should the atom not be displayed as a symbol.

If a Ctrl keyboard shortcut is issued while the mouse cursor in on a bond, the ring is joined to the bond. Both atoms of the bond count toward the ring size, so pressing Ctrl-6 on a bond of cyclohexane yields decalin. The sequence for the steroid skeleton construction is therefore Ctrl-6 on the canvas (start ring), Ctrl-6 on rightmost vertical ring bond, Ctrl-6 on top right diagonal bond and Ctrl-5 on the rightmost vertical bond Only after that, additional attributes and substituents should be specified. The Meta linear and iso chain commands cannot be used on bonds.

Note that it is not possible to add a benzene/phenyl ring as spiro substituent. If a bond serving as an attachment point is multiple or has attributes, these are preserved. Consequently, this means that a double bond from a benzene fragment added is not maintained as such if it is the link position. For ring joins to bonds both bond atoms must possess at least one free valence electron. Currently, ring joins to bonds are only possible by the keyboard shortcuts because there is no bond menu. This may change in the future. The following table summarizes the keyboard shortcuts for skeleton construction:
TABLE 3. Skeleton Construction Shortcuts
Shortcut

Function

Ctrl-3 to 9 on empty canvas

Add carbocycle of size N

Ctrl-P on empty canvas

Add phenyl ring

Meta-2 to 9 on empty canvas (or Alt)

Add linear carbon chain of length N

Shift-Meta-3 to 9 on empty canvas

Add iso carbon chain of size N

Ctrl-3 to 9 on atom

Add carbocycle of size N, linked with single bond

Ctrl-P on atom

Add phenyl ring, linked with single bond

Meta-2 to 9 on atom (or Alt)

Add carbon chain of length N, linked with single bond

Shift-Meta-3 to 9 on atom (or Alt)

Add carbon iso-chain of length N, linked with single bond

Ctrl-T on atom

Add tButyl-group

Ctrl-3 to 9 on bond

Add carbocycle of size N, integrating bond

Ctrl-P on bond

Add phenyl ring, integrating bond

Shift-Ctrl-3 to 9 on atom

Add spiro ring of size N, integrating atom

Atomic Charges

Atomic localized charges can be specified in a special charge/attributes mode, by mouse- or keyboard shortcuts and by means of the atom menu. The most easily remembered method is to use the atom menu which pops up when the right mouse button is pressed on an atom. Charges ranging from -3 to +3 can be set this way. The editor does not allow you to set charges which result in negative shell electron counts. Charge is preserved if the element is exchanged subsequently, but element exchange is only possible if the charge can be born by the new element. In the dedicated charge/attributes mode, (the fat plus symbol in the mode selector) the atom menu can be opened also by the left mouse button to make single-button mouse operation feasible. The keyboard shortcuts for the most often needed charges +1, 0 and -1 are +, - and 0 (null), respectively, pressed while the mouse cursor is above an atom. Another possibility is to press the left (charge -1), middle (neutral) or right (charge +1) mouse button over an atom while the Shift key is held down.

Graphical Attributes of Atoms

Besides charges, which also leave a graphical mark (the charge is written on the upper right of the symbol or node) a number of additional attributes can be set for atoms and bonds. In the case of atoms, some popular attributes can be set directly from the atom menu via the Flags submenu. These attributes are starred (an asterisk is displayed next to the atom/symbol), boxed (the atom is plotted in a box) and Fischer (an <F> sign is added, meaning this atom should be interpreted according to the Fischer convention for the automatic extraction of stereochemical descriptors). The shortcuts are *, ] and ^, respectively. Additionally, all atom attributes can be reset from this submenu or the x keyboard shortcut. The majority of atom attributes is setable only from the atomic attribute panel. It is opened for the current atom by a double-click on the atom.

While this panel is open, the drawing area is blocked. The selected atom flashes. The panel closes when the set or cancel button are clicked. The set button checks the entries and transfers all changes to the atom. The cancel button aborts the operation and no changes on the panel take effect.

On the left side, a number of purely graphical attributes can be set or reset. The Boxed, Starred and Fischer attributes are those found also in the atom menu. The other flags can be manipulated, but they are not currently displayed graphically on the canvas. They are however correctly read from and written to files for formats which support this type of attributes.

The top line specifies the atom type. Three types are known to the editor: Classical atoms, placeholders for any element in substructure searches and inclusive or exclusive element lists which are also used in substructure searches. Inclusive atoms lists (on this position, only elements in the list may occur) are specified by entering atom symbols on the entry to the right of the List button. They should be separated by spaces. Case does not matter. For exclusive lists (on this position, only elements except those in the list may occur) add at least one exclamation mark to the list. It needs not to be separated by blanks from the symbols, but it does not do any harm either. By default a list is displayed with an L symbol. If the tag style is set to Extended Symbol in the Display menu above the canvas, lists are printed in expanded form. The HydrogenCount, Valency, Ligands, RingSearch and Care interface elements specify other attributes for substructure searching. The three counts can be either any, a single number or a range in the format low - high. Leading, trailing or interspersed blanks are optional. The Care item defines whether the specified stereochemistry or charge matters during the substructure matching process and whether the atom should be unsaturated. There is no simple way to say that an atom should not be unsaturated.

In the next box atomic stereochemistry is defined. Three independent sets of descriptors can be carried along. The P/M set is based on the atomic labelling. The atom with the lowest label or an electron pair is put to the rear and if the sequence from the atom with the highest label to the atom with the lowest label is clockwise, the descriptor is P, otherwise M. The D/L and R/S pairs should be known to every user of this program. The Reset and Invert buttons perform the obvious operations. Stereochemistry can also be set via the atom menu. The keyboard shortcut (space bar) resets atomic stereochemistry, and the keyboard shortcut pairs p and m, as well as s and r and d and l set the respective flags. Accordingly, if you want to change an atom to sulfur, the s key must be pressed outside the atom symbol area and afterwards, the atom is clicked at with the left mouse button. The Invert operation in the atom menu works a little different than that in the atom attributes panel. All changes on the panel are completely independent from each other and do not influence bond attributes, so the user can leisurely set up attributes and descriptors. The Invert option in the atom menu does not only invert the complete set of atomic stereodescriptors but also appropriately modifies an automatically selected wedge bond linked to this center via the wedge tip. This operation is intended for the rapid generation of the stereo isomer of a compound which has already been fully specified stereochemically and probably was also written to file.

In the isotope field, the nucleonic number or the D/T strings for hydrogen isotopes can be entered. If this field is clean, no isotopic labelling is assumed to be present. The nucleonic number is displayed on the element symbol in square brackets. An exception to this rule are the two hydrogen isotopes. They are shown with their familiar D and T symbols.

Colors of individual atoms can be set to any named color in the X11 color database or to an arbitrary shade with the standard X11 #rgb nomenclature. The color of the box to the right of the entry field is of the current atom color. Drag&Drop to this box from a color choser is not yet implemented.

Finally, an arbitrary text line plus formatting instructions can be attached to every atom. This is currently only of limited usefulness. In a future release, these will be texts for superatoms such as COOH, employed to produce high-quality graphical output for word processing applications. The editor currently does not display them, but they are stored in and retrieved from files of suitable formats.

Graphical Attributes of Bonds

Bonds don`t have a bond attribute menu. Instead, the right mouse button is used to cycle through a predefined set of attributes which is dependent of the current bond order. If the Shift key is held down, the cycle is executed in the reverse direction. Additionally, bonds also have a bond attribute panel which is activated by a double click with the left mouse button. Remember that a single click with the left mouse button changes the bond order, so you should not click too lazily.

In case of single bonds, the attribute cycle driven by the right mouse button is bold, wavy (meaning no stereochemistry"), solid wedge (tip at atom with higher label), solid wedge (tip at atom with lower label), dashed wedge (tip at atom with higher label) and dashed wedge (tip at atom with lower label), dashed and plain line again.

In case of double bonds, the attributes are left (second bond line of bond view from lower to higher label is on the left side), right (the opposite), bold and plain centered bond again. The left and right styles are useful for double bonds in rings. The visual impression is more pleasant if the bonds are drawn on the inside. The same is true for some kinds of cis double bonds. Bonds in rings can be automatically configured to be inside the ring. The Edit menu contains the Smart Bonds command. This procedure puts all double bonds in rings inside if they are not shared between several rings and centers all other double bonds.

Bonds with triple and higher bond order can only toggle between bold and plain styles.

If the bond order is changed, all attributes are reset to plain.

A double click with the left mouse button on a bond opens the bond attribute panel.

While this panel is open, the drawing area is locked and the selected bond blinks. The structure of the panel is similar to the atom attributes panel. The left side contains a selection of setable and resetable graphical attributes. Just as in the case of atoms, not all attributes can be currently displayed. Some attributes are plotted only for specific bond orders (for example, the left/right attributes only for double bonds), and others only under special circumstances (for example, the dashed/dotted attributes are used only for wedges, and they are treated as equivalent, they display form is exactly the same). However, in principal these attributes can all be manually specified and input from or output to suitable files.

The box in the upper right corner defines attributes for substructure searches. The Bond Order entry can contain any, a single bond order as number or an allowable range in the form low - high. Spaces are optional. The Ring Search tableau offers a number additional search conditions. Small and Large indicate membership in small (size <5) and large (size >7) rings.

The stereo panel below sets the stereochemistry of the bond. The P and M descriptors are label-based. If the respective atomic substituents on both sides of the bonds with the lower label (or free electron pair) are on the same side of the bond, the descriptor is P, otherwise M. The other descriptors should be familiar to the audience. The Reset button clears all stereochemistry for the bond. A number of keyboard shortcuts are also available for bond stereochemistry: the c and t pair sets cis/trans stereochemistry, p and m bond stereochemistry, and (the space bar) clears all stereo descriptors.

Pressing the Set button transfers the new set of attributes to the current bond. The Cancel button aborts the operation and all changes performed on the panel are ignored.

Moving Atoms, Bonds and Molecules

Atoms, bonds and molecules can be moved directly with the left button in the move mode or with the left mouse button while a Meta or Alt button is held down.

Atoms are move when the mouse cursor movement begins while it is over an atom or its invisible box if no symbol is displayed. Only a single atom is moved. All bonds leading to this atom become rubber-bands and are stretched or shrunk while the mouse is moved. If the mouse button is release while the moved atom is over another atom, they are merged. The immobile atom and its bonds remain unchanged. The moved atom is deleted, and its bonds are taken over by the immobile atom as long as the number of shell electrons is sufficient. Bonds of the moved atom which cannot be transferred to the immobile merge atom are deleted together with the moved atom.

Bonds are similarly shifted if the cursor movement begins on a bond. Both atoms of the bond become mobile, and all bonds of the bond atoms with the exception of the moved bond itself become rubber-bands. In order to avoid undue confusion, no atomic merging step takes place after bond movement has stopped.

In order to move a molecule, the cursor movement must begin within the molecule box, but not on an atom or a bond. The term molecule box is explained in the section Deleting Atom, Bonds, Molecules and Everything. The whole molecule can be dragged around and follows the mouse pointer. After releasing the mouse button, an atom merge step is performed with all atoms of the moved molecule. As in the case of atom movement, atoms of the moved molecule are deleted if they end on top of an immobile atom. The immobile atom is preserved and captures the bonds of the mobile atom as long as the number of shell electrons is sufficient. If all atoms of the moved molecule overlap atoms on the static remaining structures, the moved molecule is effectively destroyed without trace.

Rotating around Atoms, Bonds or Molecule Centers

Rotations are either invoked directly with the left mouse button if the rotate mode is active or by holding down the Control button while dragging with the left mouse button.

Once the rotation sequence is initiated, a pie-shaped track marker appears. It shows the current rotation angle and is continuously updated while the mouse is moved. The pie center is located on the rotation center, which is not necessarily the point where the mouse button was pressed first. Rotation around atoms is started as usual by starting movement on an atom, rotation around bond centers by commencing on a bond and around the 2D display coordinates center by starting in the molecule box (Deleting Atom, Bonds, Molecules and Everything), but not on an atom or a bond. Note that it is necessary to drag the mouse some pixels away from the rotation center in order to be able to indicate an angle relative to the center. The current rotation angle is also printed in the status line of the canvas window. If the ring mode is none or custom, any degree of rotation can be selected. In the more common case of an active fixed ring grid, the rotational angle is gridded and dependent on the ring grid size. It jumps to the next accessible value only if the selected degree is larger than halfway to the next grid angle. For ring sizes up to six, the grid angle is one half of the sector angle of the ring, for example 30 degrees for a ring grid of size six. For larger rings, accessible ranges are multiples of the sector angle. In the ortho mode, the grid angles are multiples of 90 degrees.

The alignment of the zero degree base line of the pie depends on the rotation type. It is true zero degrees, i.e. a horizontal line to the right, if rotation is around the molecule center. In case of rotation around the midpoint of a bond, the bottom line is from the bond midpoint to the atom with the higher label. When rotating around an atom, the base line extends to one of the ligands. This base line adjustment makes rotation angles more easily judged by the human eye if non-gridded rotation is involved.

Duplicating Molecules

Molecules are duplicated by clicking in the molecule box (Deleting Atom, Bonds, Molecules and Everything) and dragging the duplicate of the selected molecule to its new place. In the duplicate mode this is all its takes. In the standard drawing mode the same effect can be achieved if both the Control and Meta (or Alt) keys are pressed before the molecule is selected.

When the molecule has reached its destination, an atom merging step is performed in just the same way as with simply moved molecules (Moving Atoms, Bonds and Molecules). Merging is performed with all unmoved atoms. This includes the atoms of the original molecule which have been duplicated.

The following table lists the most important movement shortcuts:
TABLE 4. Movement and Duplication Shortcuts
Shortcut

Function

Meta-Drag on atom

Move atom

Meta-Drag on bond

Move bond

Meta-Drag in molecule box

Move molecule

Ctrl-Meta-Drag in molecule box

Duplicate molecule

Ctrl-Drag on atom

Rotate around atom

Ctrl-Drag on bond

Rotate around bond center

Ctrl-Drag in molecule box

Rotate around molecule center

Ctrl-Shift-Left on bond

Flip around bond (see Miscellaneous Editing Functions)
Ctrl-V in molecule box

Flip molecule vertically (see Miscellaneous Editing Functions)
Ctrl-F in molecule box

Flip molecule horizontally (see Miscellaneous Editing Functions)

Adding and Removing Hydrogen Atoms

Hydrogen atoms can be added manually or automatically. Flags in the Props menu control if hydrogens are added automatically to all atoms of common elements with clearly defined valency when they are written to file or exported via a drag&drop operation. The automatic hydrogen addition flag for file output can be toggled with the Escape-H shortcut.

Hydrogen atoms can be added manually via the Add Standard and Remove All commands in the Hydrogen cascade of the Edit menu. In addition, the menu offers commands for a more selective stripping of hydrogens. Either plain hydrogen atoms (i.e., those which would not be printed in typical structure plots) or hydrogen atoms which are not linked by wedge-type bonds can be deleted selectively.

The keyboard shortcut Ctrl-H introduces even more editing functionality. If pressed over an object which contains or is bonded to hydrogens, the hydrogen atoms are removed, otherwise added according to the standard procedure. The command can be invoked on an atom, in a molecule box or globally on the canvas and only the respective target objects are modified.

The coordinates of the new hydrogen atoms are generated automatically. They are placed into gaps in the ligand sphere in an attempt to generate a pleasant overall impression. The bond length is about 0.62 medium bond lengths and therefore notably shortened compared to normal bonds. This shortening greatly reduces the ugly overlap of hydrogen atoms and is sufficient to yield pretty results for substituents such as the t-butyl group.

Naming Molecules

The most straightforward method to attach a name to the structures on the canvas is to set the name button to the Name: mode and enter the desired text in the name entry field.

In the default configuration, it is necessary to press the Return key after finishing input. Certain users seem to be prone to neglect the last key. Therefore, it is possible to set the Immediate Naming flag in the Props menu.If this flag is set, the structure name is updated even if no Return was pressed if molecules are written or exported.

The default name is reset to an empty string if the canvas is cleared. For file formats with a mandatory record name the molecular formula is substituted if no name is specified. Note that, if the entry field is empty, you may still involuntarily specify an empty string as name is the Immediate Naming flag is set.

Some file formats support a second textual identifier. It can be set by the same methods if the button to the left of the entry field is set to Ident:. Switching the button when the Immediate Naming flag is on sets the standard name.

The ident field is not reset when the canvas is cleared. Therefore it is not necessary to set it again if a dataset with a constant ident string is constructed. If the structures have been read from file, their attached name and ident information is of course displayed in the entry field.

Saving to File

The ultimate purpose of a molecular editor is to write a structure file. While there are several other methods of data export in this editor (Drag&Drop, export to a Cactvs workbench, mailing structures for remote computation), most commonly an output file will be written.

The functions for file I/O are concentrated in the File menu. The Write... entry or its shortcut Ctrl-W pops up a file selector box.

It offers numerous methods for the selection of files.

A single click on a file in the listing selects it as output file. Alternatively, it may also be entered directly on the File: entry. The current selection in the box is adjustable with the cursor keys. The view can be set with the scrollbar or the PageUp/PageDown/Home/End keys. Typing the first few characters of a file name while the mouse cursor is over the box is yet another possibility to select an existing file. If you are very sure about the file to overwrite or append to, you can also select it from the listbox without further confirmation with the Write button or Return in the File: entry by issuing a double-click. Some filters with popular structure filename suffixes can be chosen from the menu button to restrict the number of files listed. The filter applies only to files. Directories are always shown. A double-click on a directory or typing Return when a directory is selected in the box makes the editor enter it. Directory names can also be input on the Directory: entry field. They are visited if the Return key is pressed in the entry. The Escape key backs up one directory hierarchy step in this field. The file selector box remembers all visited directories and adds them to the menu under the Directory: button. Choosing from this menu is a fast method to return to some previous location. The listbox contains a menu which is activated with the right mouse button. It offers commands to rescan the directory or to delete the file the menu was popped up over.7

The final choice before issuing the write confirmation is the selection of the output format from the menu under the Format: button. The available output formats vary. Besides providing a standard built-in set, the editor tries to load some more file formats dynamically when it is started. They are only listed if you have these modules locally available in your file extension search path.8 If you have local custom format modules, you need to add the load instructions to the editor script. This is for experts only.

If the file chosen for output exists already, the editor displays a confirmation popup. You can request appending to the file, overwrite it, or back out. The editor can be instructed to create a backup copy of files it is going to change. The Auto Backup flag in the Props menu should be set if you want file copies. A backup file has the same name as the original file plus an affixed % character. Existing backup files are overwritten if possible.

For file formats which offer a choice between spitting multiple molecules in an ensemble into separate sub-records and writing a merged ensemble record, the editor currently chooses always the latter style. It is possible to set a file attribute to control this behavior, but not from the GUI.

The program remembers the name of the output file, its format and its directory. When the file output panel if opened again, it starts in the last write directory. The current file name is displayed in the name entry field if the menu button to the left is set to File:. It is possible to set the file name directly form this line by editing and pressing Return if you think it is faster than the file selector box. Note that the last output format or the default format is reused if you set the filename by this method.

Once a file has been written to, a number of additional commands become available in the File menu. First, you can conveniently Append to the file without going over the file selector box again, and without confirming that you want appending, not overwriting. The keyboard shortcut for appending is Ctrl-A. Strictly speaking, you can append even without specifying a filename first. The editor then writes a file noname.ctx. The next three options in the menu absolutely require a previous file name specification, either by writing a record via the file selector panel or by setting a filename on the name input field. You can generate a Backup copy of the file in its current state, can Delete it completely, or perform an Unwrite/Truncation operation on it. The last operation means that the last record is removed from the file, typically in order to correct a premature Append to the file with an incorrect or incomplete structure. However, it is not necessary that you have just added the last record personally. You can just chop of tail records step by step from any structure file with recognized format if you enjoy it. If the last record is removed, the file is deleted.

The editor prevents you from writing empty records if the canvas is clear, even if the selected file format supports empty records in principle.

Expert Features

The editor supplies some functionality which is popular with expert users, but has not been included in the basic description because these features are not used routinely by novice users.

Reading from File

Until now only the production of new structures has been treated. However, the editor can also be used to edit files of already entered structures. Input from file is requested either by selecting the Read... entry from the File menu or by pressing Ctrl-R somewhere in the editor windows. A file selector box appears which looks very similar to the box used for specifying output files.

The functionality of the File: and Directory: entry fields, of the Filter: button and of the file list box are completely identical. The only new element is the Scope: button.

Some file formats such as Ctx and Cactvs/Ascii have two ways of saving molecular ensembles. Either they are written as a single record or they are split into separate molecules and a special separator keyword or other construct indicates where a record ends. The read scope decides how to read a split record. If the scope is set to Ens, the record is reconstituted and all molecules of a record appear side by side together. If the read scope is Mol, the split is maintained and the molecules are read separately. The Cactvs molecular structure file read command support additional read scopes such as Reaction or Dataset, but they are not accessible in this application. The default and the safest choice applicable to all file formats is Mol. When files are written, the editor never performs a molecule split. Again, this functionality is implemented in the underlying program, but currently not accessible via the GUI.

It is no omission that there is no file format specification button in the file input panel. The editor detects the format of a file automatically. Once it has been determined, it also becomes the default for the next output file. It is not necessary for a structure file to provide 2D coordinates. They will be generated if necessary, although within certain limits, and the results will be ugly for complicated cases. Neither is it strictly required to have connectivity information in the input file. An attempt will be made to create reasonable connectivity from 3D coordinates if only those are present. Be aware that those output formats which are either 2D or 3D but never both are always 2D when written by the editor. Existing 3D coordinates are lost when the structure is edited, but they may be preserved when the structures are written out immediately without intermediate structural editing. Some of the file formats listed in the write panel are exclusively 3D. In the public version of this editor, automatic creation of 3D coordinates is disabled. You have access to free high-quality 3D coordinates via the editor, as will be described later, but the direct writing of, for example, a file in Xyz format will fail if it is not a simple format conversion from another 3D format. If you want to be able to write 3D coordinate files directly without submission to remote batch computation, you can contact the distribution site and buy a 3D module licence.

An input file is always read completely. The first record is put onto the canvas and all records are stored in memory in the editor buffer. Due to this input behavior, it is probably a bad idea to read a 10.000 compound database into the editor if you have not plenty of swap space, but a few dozen, even hundred records are no problem on a typical workstation.

If the input file contains substructure search specifications, the automatic hydrogen addition for file output is disabled automatically. It can be reactivated manually in the Props menu, but typically you don`t want hydrogen addition on these files.

The numerical range of the 2D coordinates written to output files is variable. If a structure is constructed completely within the editor, the coordinates are pixel values. If a start set of coordinates has to be computed because it is not in the input record, or if a structure is beautified, a set of coordinates with a characteristic bond length of 1.0 is generated. If 2D coordinates are present in an input record, the characteristic bondlength is computed as the median of all 2D bond lengths excluding hydrogen (except where no such bonds exist). Atoms of a bond of medium length added in the editor will have coordinates reflecting this standard bond length. Output coordinates and canvas coordinates are independent. Output coordinates are trying to preserve prior coordinate conventions, but the length of a medium length canvas bond is constant (45 pixels). The routines for 2D plot coordinates I/O are assuming a left-to-right X axis and a bottom-to-top Y axis.

The following table lists the most important shortcuts loosely associated with I/O:
TABLE 5. I/O Shortcuts
Shortcut

Function

Ctrl-R

Read from file

Ctrl-W

Write to file

Ctrl-A

Append to current output file

Ctrl-X

Clear canvas

Meta-X (or Alt)

Clear buffer

Ctrl-Q

Quit editor

Ctrl-E

Export to Cactvs workbench (see special section)

Special I/O File Names

The editor, like all Cactvs tools, supports I/O to and from some special files.
TABLE 6. Special Files
Filename

Description

stdin

Read from standard input. Input only

stdout

Write to standard output. Output only.

stderr

Write to standard error. Output only.

stdprint

Write to printer. Output only. The name of the printer is site-dependent. Output is a file listing, not an image.

scratch

Write to uniquely named file in /tmp directory. Output only. File is deleted automatically when closed, so definitely unsuited for editor.

|xxx [|yyy]...

Read from or write to other programs xxx (and yyy etc.) via pipe.

They are especially useful if the tools are part of a pipe or similar assembly. These file names are reserved names and cannot be used for normal I/O to real files. Writing via a pipe to program xxx in your search path can be achieved either by using |xxx as output file name or by starting the editor as csed|xxx and writing to stdout. Cactvs tools flush the output buffer after each record, so programs can time out if no new records are received for a while without the danger of being stranded in the middle of a record.

All Cactvs tools can read directly, without prior decompression, from gziped or compressed files. Typical file name ending of these files are .gz and .Z. The editor does not look for the ending of the file name, but for magic bytes in the file header, so the actual name is irrelevant and the presence and type of compression are automatically detected. Compressed output is supported in the underlying file handling routines, but not yet accessible by means of the editor.

All Cactvs tools support input via index files which index secondary (typically large) files of any readable format. An index file is an Ascii file with one record number on each line. The first line contains the name of the indexed file after the record number, separated by white space. The record numbers need not to be sorted. The first record is numbered one.

Cactvs tools can read Wodca libraries. The name of such a library is as usual the base name, without the different last character of the name of the various files which comprise a Wodca library. Reading a library by specifying the generic name is more efficient than reading the main data file ending in D.

The Editor Buffer

All structures read from file are put into the editor buffer. Then a copy is made of the first buffer record and this duplicate is presented for editing on the editor canvas. The buffer contents do no change if the copy is edited. In order to manipulate the buffer, it is necessary to explicitly use the set of commands in the Buffer menu. The editor buffer maintains a buffer pointer. After loading a file, it points on the first record.

Only two buffer commands are active if the editor has not read a file or the buffer has been reset. The Position (Meta-P or Alt-P) command displays the current buffer pointer position and the number of records in the buffer on the bottom status line. The Append (Meta-A or Alt-A) command puts the current canvas contents into the buffer as a new record. Independent of the position of the buffer pointer, it is always appended.

Once the buffer contains one or more records, additional commands become available. A group of commands (First / Meta-f, Last / Meta-l, Next / Meta->, Previous / Meta-<, Current / Meta-=, Alt key equivalent to Meta) moves the buffer pointer around. The current canvas contents are overwritten by the indicated buffer record. This is an undo-able operation, so it is no catastrophe if unsaved edited structures are purged.

Another set of commands changes the buffer contents. The Replace (Meta-R or Alt-R) overwrites the buffer record indicted by the buffer pointer with the current contents of the canvas, provided the canvas contains some atoms. The Insert (Meta-I or Alt-I) command inserts the canvas contents before the buffer pointer. Finally, the Delete (Meta-D or Alt-D) command deletes the current buffer record. The next buffer record is automatically copied to the canvas.

Normally, with the exception of the Delete command, the canvas contents do not change if the buffer manipulation commands are employed. If the Auto Clear flag is set, the canvas is however cleared and the next buffer record is copied to the drawing area. This feature saves some work if you are systematically working through a set of buffer records, sometimes replacing items after some editing. After the replacement, the next record appears automagically.

Finally, the Clear Buffer command (Meta-X or Alt-X) clears the buffer. The drawing area is not affected. The buffer contents can be written out as a whole to the original file in the original format with the Rewrite (Meta-W or Alt-W) command or to a new file with the Write... menu entry. In the latter case a file selector box is popped up which has the same features are the standard write panel. Writing single records directly from the canvas to a file and outputting the buffer are independent operations and may be mixed freely.
TABLE 7. Editor Buffer Shortcuts
Shortcut

(Alt-Key is equivalent to Meta)

Function

Meta-a

Append to end of buffer, ignoring buffer pointer

Meta-d

Delete buffer record indexed by buffer pointer

Meta-f

Get first buffer record and position buffer pointer

Meta-i

Insert new record before buffer pointer

Meta-l

Get last buffer record and position buffer pointer

Meta-p

Print buffer size and buffer pointer position

Meta-r

Replace buffer record by canvas contents

Meta-w

Rewrite buffer to original file

Meta-x

Clear buffer

Meta->

Get next buffer record and advance buffer pointer

Meta-<

Get previous buffer record and adjust buffer pointer

Meta-=

Get current buffer record again, overwriting canvas changes

Buffer operations can become awkward for larger datasets where only a few fine touches are needed. In this case I recommend that a Cactvs 2D structure browser is used to display the data set and those structures which need editing should be shuttled back and forth between the editor and the browser by drag&drop operations.

Display Variations

The Display menu offers some functionality to set the display style of the structures on the canvas. Normally, since you probably want to be able to edit all atoms, all hydrogen atoms are displayed. Carbon atoms are plotted by default as nodes without a symbol, with the exception of certain well-established traditions (single atoms, aldehyde carbon, sp-hybridized carbon). Atom lists for substructure search are shown as an L symbol. The menu gives you the choice to set the display style for carbon and hydrogen atoms and what kind of symbols to use. Symbols can be either the standard atomic symbols, atom labels, or symbols plus extended lists. Extended atom lists are plotted with all allowed or prohibited atom types enclosed in curly brackets. The information content is higher, but wide lists can become a nuisance. After changing one of the display attributes, the canvas is withdrawn. The display style does not have any influence on output operations. Suppressed hydrogen atoms are still written as long as they are physically existing. The suppression feature is intended to be used if structure drawings are prepared, not for data set editing. If bond orders or bond attributes are changed, the display is not always completely correct with regard to the display traditions for carbon and hydrogen atoms. Making the display redraw from the Edit menu or by means of the Ctrl-L shortcut cures these minor flaws.

Renumbering Atoms

It has already been mentioned in the previous section that the labels of the atoms can be viewed by adjusting the atom tag style from the Display menu. Normally, atom labels are generated automatically. The first atom put onto an empty canvas is labelled 1. New labels are always the highest currently used value plus one. Holes generated by deleting atoms which do not include the top labels are not automatically filled. Structures read from file honor labels specified in the file, if present, otherwise they are automatically generated as a sequence starting with one.

Atoms can be renumbered if desired. The renumber mode can be entered by means of the mode panel or the Ctrl-N keyboard shortcut. Once this mode has been entered, the mouse cursor becomes a green target cross. Most commands, especially those which could disturb the label sequence, are now disabled. The mode is left with the middle mouse button, another Ctrl-N keyboard command, or automatically after all atoms have been renumbered. Clicking on an atom attaches label 1 and the label counter is incremented. The next atom becomes label 2, and so on. Clicking onto an atom which has been relabelled in this renumber sequence before is an error. The new label is printed in green to the upper left of the atom symbol. The old numbering can be viewed in parallel if the atom tag style is set to Label beforehand in the Display menu. If the renumber mode is left before all atoms have received new labels, the remaining labels are automatically generated in the order of atom creation. It is not possible to end up with duplicate labels, and the labels form again an uninterrupted sequence starting with one.

It is currently not possible to influence the atom index for files which distinguish between atom indices and atom labels.

The Alignment Mode

The alignment mode can be entered by means of the mode panel or the Ctrl-G keyboard shortcut Once this mode has been entered, the mouse cursor becomes a green target cross. The editor remains in this mode until the middle mouse button is clicked or the Ctrl-G keyboard shortcut is executed a second time. In this mode most editing functions (with the notable exceptions of Undo and movement or rotation by means of the Meta/Alt-Left and Ctrl-Left keyboard commands) are disabled.

Basically, in the alignment mode you select pairs of anchor points. A point is either an atom, the center of a bond, or the center of a molecule. When the first point is selected, a green square highlights it as current pivot. The alignment operation is executed when the second point is selected and the green marker disappears. If the alignment operation did not result in the desired changes, it can be undone without leaving the alignment mode. There are two distinguished cases when the second point is selected by clicking onto an atom, a bond or into a molecule box.

In the first case both points lie within the same molecule. The molecule is rotated around the first point (an atom, the middle of a bond, or the center of a molecule) the smallest possible angle so that both points are on a vertical (if the slope of a virtual line between the points was less than 45 degrees) or horizontal line (if it was steeper). Typically one first roughly rotates and moves the molecule into place with the rotation and movement commands (which can be executed by their keyboard commands without leaving the alignment mode) and then performs a final adjustment with an alignment operation.

In the second case, the molecule of which the second point is part of is moved either horizontally or vertically so that the points are again on a horizontal (if the vertical point distance was smaller than the horizontal distance) or vertical line. No rotation takes place, and the molecule is moved only in one axis direction.

Miscellaneous Editing Functions

Some less commonly editing functions are hiding in the Edit menu and the molecule box menu. First the remaining unexplained options from the Edit menu:

Redraw redraws the canvas contents and centers them in the editor window. The canvas scrolls in order to give a central view. Besides performing centering, the Redraw command also corrects some small display errors with respect to plotting or suppressing carbon and hydrogen atoms. Keeping the display perfectly correct at all times is currently regarded as too time-consuming, especially if changes in the second ligand sphere influence the traditional display characteristics. The keyboard shortcut is Ctrl-L.

The Beautify command recomputes the 2D display coordinates. Its keyboard shortcut is Ctrl-B. It works well for simple molecules of small or medium size9, but will fail miserably with crowded structures or those with complex ring systems. If the result is unpleasant, it can be undone. This operations resets the output 2D coordinates to a standard bond length of 1.0. The command does not set wedge-shaped bonds for atomic stereocenters automatically, but it will honor P and M label-based bond stereochemistry, producing the correct cisoid or transoid structure plot. Bonds to hydrogen atoms are shorter than the standard bond length by a factor of about 0.62.

The Smart Bonds command beautifies double bonds. They are realigned to occupy the inside of rings, and double bonds outside rings are recentered.

The Purge Stereo, Purge Atomflags and Purge Bondflags commands from the Purge cascade of the Edit menu remove all stereo information for atoms and bonds, graphical atom attributes and graphical bond attributes, respectively. All operations work simultaneously on all molecules on the canvas. Purge Atomboxes is similar to Purge Atomflags, but only deletes the boxed flag and leaves other attributes unchanged. The global reset of atom boxes is most often invoked in order to clear the boxes generated as a result of a valence or stereochemistry check. These checks are explained a few pages later in this manual. The Purge Bold Bonds erases only the bold attribute of bonds and leaves other attribute flags untouched. It is typically used after a stereochemistry set in order to reset marked bonds which did not pass the test. Purge Wedges removes all wedged and dashed line styles indicating stereochemistry, but not the stereochemical descriptors themselves.

The choice button to the left of the name entry field has a Smiles: setting. In this position, the entry field displays the Smiles representation of the canvas contents. The string is continuously updated during the editing process. True brave chemical hackers just love to clear the string (Escape key) and type in the Smiles string of a fragment they want to add. After pressing the Return key, the string is decoded and the structure with automatically generated plot coordinates pasted into the canvas to the right of the older structures. Just pressing Return when the current Smiles string is displayed, without entering anything, is a fast way to duplicate multiple molecules.

The molecule box menu pops up if the right mouse button is pressed within the coordinate rectangle of a molecule, but not directly on an atom or a bond. It contains, besides the Delete Mol entry, which has already been explained in Deleting Atom, Bonds, Molecules and Everything, three more entries for vertical and horizontal flips and for enantiomer generation. The flip shortcuts are Ctrl-V and Ctrl-F, respectively. The selected molecule is flipped around the horizontal or vertical axis. Additionally, mirroring the pseudo-3D style of this command, the character of wedge bonds is switched from solid to dashed and vice versa. Double bonds which are drawn with offset to the center, for example inside rings, are adjusted to appear unchanged. The Enantiomer command edits the structure to represent the enantiomer of the old plot. It has no effects on molecules without stereochemistry descriptors and/or wedge bonds.

Parts of a molecule can be rotated 180 degrees around any bond which is not member of a ring. You simply need to click on the bond with the left mouse button while both the Shift and the Ctrl key are pressed. Clicking on an atom or its atom box has no effect, but the position on the bond decides which part of the molecule will rotate. The moving part is always the part including the bond atom closer to the click position. Admittedly, finding the right position can be sometimes a challenge. The style of this rotation is again pseudo-3D. The character of wedges (dashed or dotted) in the moved part is toggled, and off-center double bonds are again automatically adjusted. The following graphic will hopefully help to clarify the effect.

If the bond is a double bond with stereo descriptors, they are inverted, for example going from cis to trans. The keyboard shortcut for this operation is !, the same as for inverting atom stereochemistry.

The Fragment Library

As you have seen, the editor provides powerful mechanisms for the constructions of complex structures. Nevertheless, often, especially when drawing large sets of structures with recurring complex partial structures, it is desirable to be able to use a library of starting blocks. Listening to these requests, the editor provides a fragment library as well. The library panel is opened with the Library... command in the Data menu or, on Sun keyboards, the Find key. In contrast to most panels encountered so far this panel does not block the drawing canvas.

The panel consists of a top line with some menus and a 4x4 structure display. The csed start script provides a standard library if you don`t specify a private library by adding -llibraryfile to the invocation command.

The fragments are sorted into sheets or categories. Only one category is displayed at any time. The current category can be changed from the Select menu, which always contains an up-to-date list of all loaded categories, or by typing the name into the Category: field and pressing Return. The name of the current category is displayed in the entry field or can be looked up from the marker position in the Select menu.

A structure fragment is transferred from the library panel to the drawing canvas by dragging the fragment to the desired canvas position. Dragging is initiated by pressing the left mouse button over a structure plot in the library panel. A small window appears which contains a copy of the fragment. It is pulled to the canvas by moving the mouse and keeping the button pressed. If the button is released over the canvas, the structure is inserted. It automatically expands to standard bond lengths. The center of the structure is the release point. Because of the non-transparent drag window, precision is necessarily not very high. Therefore, no atom merge step as in the canvas-only structure duplication or move commands is performed. If necessary, the dropped structure should be precisely adjusted on the canvas with a standard move operation described in the basic features section of this manual.

Drag&Drop is also possible within the fragment panel in order to rearrange the fragments or from the editor to the fragment panel in order to introduce new fragments. In contrast to drags onto the drawing area, which add the transported fragments, dropping a structure on the fragment panel is always a replace operation. Refer to the Drag&Drop section of this manual for instructions how to initiate a Drag&Drop sequence from the drawing canvas. If the right mouse key is pressed over a fragment panel item, a menu pops up. It contains only a single entry. Its function is to delete the underlying panel item. The equivalent keyboard shortcuts are Ctrl-X or Delete or BackSpace.

Some of the fragment catalog records have a name which is displayed on the bottom. This is the Name: attribute, setable for example in the name entry field above the drawing area in the editor main window. If a named structure is imported from file or dropped in, the name is automatically displayed if it is not ???, the name default value, or an empty string. The name is not passed in the reverse direction. Dropping a named fragment onto the canvas does not change the name there.

The Edit menu of the fragment panel contains a number of commands to modify the fragment library in memory. Create Category creates a new, initially empty category. The name is taken from the contents of the Category: field, so it must have been entered beforehand. It is not possible to recreate a category which already exists. The new category becomes automatically active and an empty library panel is displayed. Clear Category deletes all structures in a category, but keeps the category valid, while Destroy Category does not only delete the structures but also the category page. Finally, Destroy All completely resets the fragment catalog in memory.

The File menu provides commands to save and restore fragment libraries. The Read... command opens another file selector box which is functionally equivalent to the standard input box except that it contains no read scope selector. Library files should be of Cactvs/Binary or Cactvs/Ascii format in order to retain their proper ordering and category classification. Molecules without a category information are put into the synthetic ??? category. New categories are created automatically if necessary. Molecules without placement information in their category are stored in the next free box or ignored if all boxes are occupied. If placement information is present, the old entry is deleted if the box is already filled. It is possible to merge multiple fragment library files. The library content becomes the union of the file contents. The Save All... and Save Category... commands in the menu write the complete library or only the current category to a file. The file selector box has no format selector because the format is always Cactvs/Binary, the native editor format, which is most efficient to handle10. Of course a library file can be read into the editor buffer as a standard input file. The Quit button in the File menu closes the library window, but does not exit the editor or forget the library contents. Be aware that a changed library is not saved automatically if the editor is quitted.

The fragment library panel can also be conveniently edited with the Cut/Copy/Paste buttons. On machines which don`t supply them on their keyboard, the top function keys F1, F2 and F3 are equivalent. The transferred contents can originate from the library panel, the canvas, other programs of the Cactvs tool series or even (as a Smiles string) from the standard X11 selection. The most convenient way to move a library record from one category to another is to cut or copy it, switch the category and paste it into a free box. Please refer to the Cut&Paste section of this manual for more information.

Extended Data Attachment

It has already been explained how to set a name and ident string for a molecular ensemble from the name input field. Additional data can be attached by means of another input panel. The Set Ensemble Data... command in the Data menu or the shortcut Ctrl-D opens a more extensive data input panel.

While this panel is open, the canvas is blocked. The Name: and Ident: fields are the same as those accessible by the name entry field in the main window. Comment: is a free-form comment. The Header: and Footer: fields contain strings intended to be printed on top of and below a structure plot. The Author: and Time: fields have the obvious meaning. All fields are transferred as a single block when the Set button is pressed. All changes are discarded if the Cancel button is invoked. The Immediate Naming flag has no influence on name or ident strings specified on this panel.

Be aware that it is not guaranteed that all file formats can actually encode this extended information set.

Submission for Remote Computations

The main reason this editor has been released to the public has been the establishment of a free 3D coordinate computation service, and the editor is its most convenient access tool. The service can be used with standard electronic mail through the address
cactvs-services@eros.ccc.uni-erlangen.de
if you are willing to send structure files manually and are careful to prepare a correct subject header.

But you can create submissions for remote computation of properties by means of Cactvs servers more comfortably directly from the editor. The Data menu has a Submit... field. This command pops up a property computation request submission panel.

If you want 3D coordinates from our site, the only interesting buttons are Send: and File Format:. The first selects whether to submit just the current canvas contents or the complete editor buffer, and the latter selects the file format of the returned information. You will receive the results by electronic mail, typically in the early morning hours European time. You must correct the reply address if it has not been correctly guessed by the editor. Once you have written the reply from your mail reader into a file, you can either manually strip the mail header information in order to make the file readable for your modelling programs or read the message unedited, header and all, into the editor and save the whole buffer, possibly with another format conversion, but without any editing in order not to loose the coordinates.

At the moment, we only honor requests for the A_XYZ property. These are atomic 3D coordinates generated by the corina program. We may consider to add more interesting property computation services if this services becomes popular. Then you can edit the property field and specify a list of other properties you want to have computed.

Currently, the only email-based Cactvs remote computation site is
cactvs-services@eros.ccc.uni-erlangen.de
If more are set up, their address can be set in the Server: field. If you are interested in setting up a Cactvs site to provide your interesting computed molecular properties to the Internet community, send mail to wdi@eros.ccc.uni-erlangen.de.

In case you need lots of 3D coordinates, need them fast and without going through email, for molecules which are too secret or too instable to be mailed on the Internet, you can buy better service. This means either a corina license as stand-alone program, or as loadable editor module, for a fixed fee or access to a real-time client-server computing mechanism also usable from within the editor for a fee based on the count of computed structures. Contact Prof. Gasteiger via email
gasteiger@ccc.uni-erlangen.de
for details.

Drag&Drop and Cut&Paste

All tools of the Cactvs series share a common Drag&Drop model and can interchange data. Additionally, the standard X11 text selection can be used to transfer structural information as Smiles strings.

A Drag&Drop operation is initiated on the drawing area when one of the shift buttons is held down and the mouse is dragged with the left button pressed. When the operation is started in a molecule box, only this molecule is selected, otherwise everything on the canvas. A small square window appears, which contains a plot of the selected structures and moves with the mouse. The destination can be a box of the fragment library or another tool of the Cactvs environment, including a second editor, but not the window of origin. As a side effect, the X11 selection is claimed. The drag can be aborted by ending the movement still on the source canvas or by dropping on some window or background which does not support the Cactvs Drag&Drop model.

In the same manner, the editor accepts drops from other tools of the Cactvs environment. Drops on the canvas are cumulative, i.e. the old contents are preserved. The center of the dropped structure is the button release point. No atom merging step is performed for structures imported this way because dragging an opaque window is somewhat imprecise. Drops are also accepted by the fragment library panel. Here they replace a structure dropped on, and the plot is always centered in the window. The editor currently supports only drops of single molecular ensembles. If multi-ensemble drops, for example from the Cactvs 2D structure browser, are received, only the first ensemble is accepted.

The function of the Copy and Paste keys on Sun keyboards, or F2 and F3 on all machines including Suns is closely related to the Drag&Drop functionality, which also uses the X11 selection mechanism internally. If the Copy key is pressed inside a molecule box, the current molecule is selected, otherwise the complete canvas contents. The Paste key now can be used to paste the structures onto the canvas (which results in structure duplication), the library panel, or windows of other programs. On the canvas the center of the pasted structure is the mouse cursor position. The editor canvas ignores the Cut key, or F1 on non-Sun keyboards. It can however be used in the fragment library panel. Here it claims the selection for the fragment and than deletes the current fragment from the panel, but preserves the structure internally in order to answer paste requests. The editor does not forget the structures marked for Cut&Paste if the canvas is cleared. Pasting the old structures remains possible as long as no new structures are selected or the X11 selection is lost.

Internally, the program is prepared to answer selection transfer requests of various types, including STRING. If a selection transfer of type STRING is requested, for example with the Paste key in an Sun cmdtool, or the middle mouse button in an Sgi xwsh, a Smiles string is produced and printed. On the other hand, you can also just mark a piece of text in these shells or any text editor and paste it into an editor window. If the string is syntactically correct Smiles, the structure will be properly created, augmented with computed display coordinates and inserted into the window.

Smiles transfers to the editor do not include implicit hydrogen atoms.

Valence Check and Valence Levels

The editor can perform a sanity check on the input structures. The editor will always prevent you from drawing a structure which violates the shell electron limitations of the involved atoms. Nevertheless, it is quite possible to input structures which contain obvious errors. In the Edit menu, the Check Valence command is waiting to help you. Its shortcut is Ctrl-V, the same as for vertical molecule flips (Miscellaneous Editing Functions), so it must be pressed outside of molecule boxes (Deleting Atom, Bonds, Molecules and Everything). This command examines all atoms and flags those which are radicals, bear excessive charge or have dubious valency. Problematic atoms are highlighted with green boxes. These are not necessarily errors. You can simply proceed if the structure is correct. Especially while formulating substructures for database searches, a valence check will probably not be very helpful. On the other hand, a successful valence check does not guarantee structural correctness.

Superfluous marker boxes are most conveniently deleted by the Purge Atomboxes command in the Edit menu (Miscellaneous Editing Functions). Resetting them manually on single atoms via the atom attribute panel, the atom menu or the [ keyboard shortcut are other possibilities.

Both the check function and the purge command overwrite manually set atom box attributes. These have to be set after the valence check.

Valence check can be performed automatically before writing a structure to file. The Props menu an Auto Valence Check radiobutton. It can also be toggled by the Escape-V shortcut.

The Props menu contains a Valence Level pullright. Opposite to what most users expect, this flag does not yet exert any influence on the valence check process within the editor. The valence level in this pullright is an exclusive and somewhat arcane attribute of files written in Ctx format. It has no effects for any other file format. The valence level value selected here is output under a /VALENCE keyword. It controls the valence check routines of the programs of the Eros series. Refer to the Eros and Petra manuals or the Ctx format specification document for further information.

Printing

The editor can print the canvas drawing in PostScript format. FrameMaker Mif output will be implemented in the future but is currently unimplemented. The print panel is opened from the File menu with the Print... command.

Output is either to a file as encapsulated postscript or directly to a printer. The output format is slightly different: If output is written to a file, only the structure in the bounding box enclosing all molecules on the canvas is printed. If output is on paper, the graphic is centered on the page and framed with a thin black line. The background is always white, regardless of the canvas color. Monochrome, greyscale and color output is supported. The output will still be readable if color output is sent to a monochrome printer, but the dithering performed by the printer will result in a worse quality than with the color translations performed by the editor if a monochrome printer is correctly selected. The paper size setting is used only if sending directly to a printer.

Submitting Bug Reports

The About... command in the File menu displays an information box.

Its Send Bug/Comments button opens another panel with a text field. Please feel free to type some sentences describing bugs and problems, or mail comments and enhancement requests. The destination mail address is
wdi@eros.ccc.uni-erlangen.de
like in the About... popup. Please use this address if your bug is so severe that you cannot open the report panel anymore. The sent text is automatically augmented with information about the editor script version, tkserver version and operating system you are running. It is not necessary to supply this information.

Stereochemistry Revisited

The editor contains a number of advanced commands to deal with stereochemistry. It has already been explained how to set the various bond and atom attributes or descriptors indicating stereochemistry and how to get rid of them. This is only the basic functionality for fully manual input. Additionally, the editor provides a number of commands to specify stereochemistry and bond attributes semi-automatically. These commands are collected in the Stereo cascade of the Edit menu.

The Get All Descriptors, Get Atom Descriptors and Get Bond Descriptors commands analyze the structure plot and assign label-based atomic and/or bond stereodescriptors to atoms and bonds which principally can exhibit stereochemistry. For atomic stereodescriptors, wedge-shaped bonds and the Fischer center flags are the principal source of information. Bond stereochemistry relies on the 2D drawing coordinates. No descriptors are computed for centers which cannot possess stereochemistry, even if (superfluous) wedges are present, or for centers with irregular wedge patterns (for example, four wedges pointing upwards), or for bonds inside small rings. Note that hydrogen atoms must already be attached in order to make the procedure work on centers with hydrogen substituents. Currently, only tetrahedral centers (including those with a free electron pair) and simple double bonds (possibly with an electron pair as ligand) are implemented. All old descriptors of the recomputed set are purged before computation commences.

At the moment, the only generated stereo descriptors are of the label-based type. A tetrahedral center is assigned P (i.e. descriptor +1), if after putting the ligand with the highest label into the back the frontside labels of the remaining three substituents are in an ascending clockwise sequence. In the reverse case, the descriptor is M (or -1). Electron pairs have a label of minus infinity. In the case of stereogenic double bonds, the descriptor is P (+1) if the respective ligands with the highest label around the bond atoms (excluding the partner atom in the stereogenic bond) are on opposite sides. Otherwise, the descriptor is M (-1).

The Show Poss. Centers and Show Poss. Bonds commands mark potential stereocenters and stereogenic bonds. Atoms are boxed and prospective bonds are boldened.

The Check Stereo command checks whether atoms and bonds with stereo attributes can actually exhibit stereochemistry. It does not yet check for inconsistency between wedges and atom descriptors or between double bond ligand labels and bond descriptors. Erroneous atoms and bonds are again marked with boxes and bold lines.

The Get Wedges command computes a new set of wedges around stereocenters marked with P or M descriptors. The algorithm tries to be smart and heuristically selects a set of bonds for wedges which is likely to correspond to human choice11. All old wedge bond attributes are purged. Double bonds are not rotated to conform to an attached descriptor. This can be achieved only with the Beautify command describe in the expert section about miscellaneous editing commands. The sequence Get Atom Descriptors, Purge Wedges, Get Wedges does not necessarily result in the same structure plot, since the initial choice of wedge bonds is arbitrary, but a recomputation of the atomic stereo descriptors must result in the same descriptors, 12 and further cycles should not produce any changes at all.

Operations with R/S and E/Z nomenclature will be available in the next release.

Using wedges and/or label-based descriptors is sufficient for remote computation services such as the 3D coordinate generator. Actually, only those are understood, so sending centers exclusively marked R or S is currently fruitless.

The Editor as Slave of a Cactvs Workbench

The editor has not been developed as a stand-alone program, even though this is now the most widely used application style. The true power of this program is only unleashed if it acts as a slave of a Cactvs workbench.

The editor is represented as a yellow icon on the workbench (upper right corner of the picture, second icon in the top row). If started from a workbench, two additional commands become available. The Export command in the File menu (shortcut Ctrl-E) exports the current canvas contents to the workbench. There either a visible molecular structure object pops out from the icon and simply lies on the bench (as in the picture), or, if the editor icon is connected to a processing pipe or network, the imported structure is immediately sent down to the next processing station. The second new editor command is Owner in the Display menu. If executed, the workbench icon which corresponds to the editor program is highlighted and all other workbench icons are deselected.

The data exchange with the workbench is bidirectional. Structures which are dropped on the editor icon or arrive from other processing objects connected to the editor icon are sent to the editor and put into its buffer. They can be passed on, i.e. sent back to the bench, after editing and visual inspection. The editor icon also contains in its menu some standard remote operations such as Destroy, CheckOut, Clear, Undo, IconOpen, IconClose, Handle and Raise. These commands are transmitted to the editor and executed there. The editor object is even remote-programmable with the editor command of the workbench`s Tcl dialect. Editors on the workbench are assigned unique handles starting with editor0. Refer to the Cactvs Tcl language manual for more information.

It is possible to connect an already running editor to a Cactvs workbench, provided that the tkserver program which executes the editor GUI script has not been started with the -norpc option, which is normally set in the csed script. A Cactvs workbench first looks for RPC-capable unconnected editors on the local machine before it tries to start a new editor.

Transferring Structures from and to other Tk Applications

Every Tk-based application can send structure information to the editor by means of the send mechanism. The easiest way is to hook into the selection data exchange protocols. The following sequence is recommended if you want to export a molecule for editing:

Colors

The color impression of the program is dependent on the screen type and the number of colors still available. The program will also function on monochrome displays. It will substitute colors which are not available (because other programs did already exhaust the colormap) by the closest color already in use. The editor can be configured to use a private colormap, which enables it to use the exact colors on color monitors under all circumstances. This is described in Configuration Options.

Configuration Options

The most important configurable options can be written to file and are automatically reloaded when the editor is restarted. The current configuration is saved with the Save Configuration command in the Props menu. The information stored includes all option in the Props menu, all entries in the printer output panel, font information13, the output file format, input file read scope and the fragment library file name. The data is written to the file .csedrc in the user`s home directory.

The meanings of the options in the Props menu are summarized in the following table:
TABLE 8. Props Menu Flags
Menu

Function

Auto Hadd

Whether to add automatically hydrogens if the editor ensemble is written to file or exported to a Cactvs workbench. This menu item can be toggled by the Esc-H key sequence,

Drag&Drop Auto Hadd

Whether to add hydrogens to structures imported by drag&drop from other applications of the Cactvs system or, more important, from the fragment library.

Auto Valence Check

Whether to perform a valence check before writing to file or exporting to a Cactvs workbench. Note that no automatic valence check is ever initiated when you start a drag&drop sequence in the editor or request an editor export remotely from a Cactvs workbench. This flag can be toggled by the Esc-V shortcut.

Valence Level

This is a flag which is output only in Ctx format files. It is used to control the valence checking in programs of the Eros series. It has currently no effect on the valence check function of the editor.

Auto Scroll

Controls whether the canvas should scroll automatically if a structure is drawn near the border to make room for more atoms.

Auto Clear

Controls whether the canvas is automatically reset as soon as the current content is written to a file. If there are structures behind the current buffer pointer, the canvas is not emptied, instead the next buffer structure is presented on the canvas after the current structures have been cleared.

Immediate Naming

If set, the name or ident of the molecular ensemble specified on the name entry becomes valid immediately, without the need to press Return. It is always necessary to hit Return when adding fragments via Smiles strings, changing the output file name via this entry or when setting the custom ring grid angle.

Stereo Check

If set, the editor checks whether stereochemistry is actually possible on an atom or a bond if it is specified.

Auto Close/Export

If set, the editor iconifies automatically after sending the current structures to a Cactvs workbench.

Auto Close/Write

If set, the editor iconifies automatically after writing the current structures to file by a Write or Append command.

Auto Backup

If set, a backup file (suffix %) is automatically created if a file is overwritten or changed.

History Strip

If set, the record history is stripped from molecular ensembles read in from file. Otherwise it is retained and written out again. Only applicable to file formats which support history lists. The editor always appends a history line of its own when writing these file formats.

Private Colormap

Normally, the editor tries to obtain precisely the prescribed colors for GUI elements, atoms etc. from the X server. If the display runs out of colors, the unsatisfied colors are replaced by the closest color in use. No flashing occurs when the mouse is moved into the editor windows and out again. If this flag is set, the editor allocates its own colormap. It will always have correct colors (the theoretical maximum of colors used by this program is about 50), but flashing can occur when the mouse pointer is entering or leaving editor windows. Note that it is necessary to write a configuration file and to restart the editor in order to make an attribute change take effect.

List of Keyboard Shortcuts and Mouse Functions

The following tables list the various keyboard shortcuts which are available in the editor windows. In any case, the Alt and the Meta keys are exchangeable. This table does not list the standard widget bindings of Tk4.0 for GUI elements. They are a superset of the Motif bindings plus Emacs-inspired extensions.The standard X11 key symbols are used as key names in the table. Some non-instant operations, such as renumbering, override the standard bindings. These temporary changes are not listed here. Please refer to the respective manual sections. Furthermore, this table describes the default pencil mode. Other modes such as eraser or rotate remove the need to press the Control, Shift, Meta or Alt keys. Operation conclusion actions which are run when mouse buttons are released and which follow as a logical consequence of a prior button press are also omitted.
TABLE 9. Shortcut Summary
Shortcut

Where

Function

Left Mouse Button Down

Canvas, on atom

Start bond drawing

Left Mouse Button Down

Canvas, on bond

Change bond order

Left Mouse Button Down

Canvas

Add new atom and start bond drawing

Control Left Mouse Button Down

Canvas, on atom

Start rotation around atom

Control Left Mouse Button Down

Canvas, on bond

Start rotation around bond

Control Left Mouse Button Down

Canvas, in molecule box

Start rotation around molecule center

Meta Left Mouse Button Down

Canvas, on atom

Start move of atom

Meta Left Mouse Button Down

Canvas, on bond

Start move of bond

Meta Left Mouse Button Down

Canvas, in molecule box

Start move of molecule

Shift Left Mouse Button Down

Canvas, on atom

Set atomic charge to -1

Shift Left Mouse Button Down

Canvas, in molecule box

Grab selection for current molecule, start drag&drop sequence

Shift Left Mouse Button Down

Canvas

Grab selection for whole ensemble, start drag&drop sequence

Control Meta Left Mouse Button Down

Canvas, in molecule box

Start duplication of molecule

Control Shift Left Mouse Button

Canvas, on bond

Invert stereochemistry and rotate around bond atom nearer to the cursor

Left Mouse Button Double-Click

Canvas, on atom

Present atom attribute panel and lock canvas

Left Mouse Button Double-Click

Canvas, on bond

Present bond attribute panel and lock canvas

Middle Mouse Button Down

Canvas, on atom

Delete atom

Middle Mouse Button Down

Canvas, on bond

Delete bond

Middle Mouse Button Down

Canvas

Start drag box for area deletion

Control Middle Mouse Button Down

Canvas, in molecule box

Delete molecule

Shift Middle Mouse Button Down

Canvas, on atom

Neutralize charge

Shift Middle Mouse Button Down

Canvas

Start preservation of boxed area

Right Mouse Button Down

Canvas, on atom

Display atom menu

Right Mouse Button Down

Canvas, on bond

Cycle bond attributes

Right Mouse Button Down

Canvas, in molecule box

Display molecule operation menu

Right Mouse Button Down

Canvas

Display ring/chain fragment menu

Shift Right Mouse Button Down

Canvas, on atom

Set atomic charge to +1

Shift Right Mouse Button Down

Canvas, on bond

Cycle bond attributes in reverse direction

Space ( )

Canvas, on atom

Reset atom stereochemistry

Space ( )

Canvas, on bond

Reset bond stereochemistry

Minus (-)

Canvas, on atom

Set atomic charge to -1

Plus (+)

Canvas, on atom

Set atomic charge to +1

*

Canvas, on atom

Set starred atom attribute

%

Canvas

Set ring grid to custom

[

Canvas, on atom

Set boxed atom attribute

]

Canvas, on atom

Set boxed atom attribute

^

Canvas, on atom

Set Fischer atom attribute

~

Canvas, on bond

Set wavy bond attribute

.

Canvas. on bond

Set dotted bond attribute

=

Canvas. on bond

Set fat bond attribute

!

Canvas, on atom

Invert stereochemistry and stereobond

!

Canvas, on bond

Invert stereochemistry and flip bond at nearer atom

?

Canvas

Set current element to any atom"

@

Canvas

Set ring grid to none

#

Canvas

Set ring grid to ortho

0

Canvas, on atom

Neutralize charge

1

Canvas, on atom

Set atomic charge to +1

3 to 9

Canvas

Set ring grid to n

A

Canvas

Set current element to Alumina

b

Canvas

Set current element to Boron

B

Canvas

Set current element to Bromine

c

Canvas, on bond

Set bond stereodescriptor to cis

c

Canvas

Set current element to Carbon

C

Canvas

Set current element to Chlorine

d

Canvas, on atom

Set atomic stereodescriptor D

e

Canvas, on bond

Set bond stereodescriptor to e

f

Canvas

Set current element to Fluorine

F

Canvas

Set current element to Iron

h

Canvas

Set current element to Hydrogen

i

Canvas

Set current element to Iodine

k

Canvas

Set current element to Potassium

l

Canvas, on atom

Set atomic stereodescriptor L

L

Canvas

Set current element to Lithium

m

Canvas, on atom

Set atomic stereodescriptor M

m

Canvas, on bond

Set bond stereodescriptor to M

M

Canvas

Set current element to Magnesium

n

Canvas

Set current element to Nitrogen

o

Canvas

Set current element to Oxygen

p

Canvas, on atom

Set atomic stereodescriptor P

p

Canvas, on bond

Set bond stereodescriptor to P

p

Canvas

Set current element to Phosphorus

r

Canvas, on atom

Set atomic stereodescriptor R

s

Canvas, on atom

Set atomic stereodescriptor S

s

Canvas

Set current element to Sulphur

S

Canvas

Set current element to Silicon

t

Canvas, on bond

Set bond stereodescriptor to trans

T

Canvas

Set current element to Titanium

x

Canvas, on atom

Reset all attributes

x

Canvas, on bond

Reset all attributes

X

Canvas

Set current element to Xenon

z

Canvas, on bond

Set bond stereodescriptor to z

Control-3 to Control-9

Canvas, on atom

Add ring of size n and bond to atom

Control-3 to Control-9

Canvas. on bond

Add ring of size n and include bond

Control-3 to Control-9

Canvas

Add ring around cursor position

Meta-2 to Meta-9

Canvas, on atom

Add chain of length n and bond to atom

Meta-2 to Meta-9

Canvas

Add chain of length n at cursor position

Control-Shift-3 to Control-Shift-9

Canvas, on atom

Add spiro ring of size n to atom

Shift-Meta 3 to Shift-Meta-9

Canvas, on atom

Add iso-chain of size n and bond or atom

Shift-Meta-3 to Shift-Meta-9

Canvas

Add iso-chain of size n at cursor position

Control-a

Anywhere

Append canvas contents to current output file

Control-b

Canvas

Recalculate (beautify) coordinates

Control-d

Canvas

Open auxiliary data entry panel

Control-f

Canvas, in molecule box

Flip molecule horizontally

Control-g

Anywhere

Enter alignment mode

Control-h

Canvas, on atom

Add or remove hydrogens on atom

Control-h

Canvas, in molecule box

Add or remove hydrogens on molecule

Control-h

Canvas

Add or remove hydrogens on canvas structures

Control-l

Canvas

Center and replot canvas contents

Control-n

Canvas

Enter renumber mode

Control-p

Canvas, on atom

Add phenyl group bonded to atom

Control-p

Canvas, on bond

Add phenyl or cyclohexadiene group and include bond

Control-p

Canvas

Add phenyl ring around cursor position

Control-q

Anywhere

Quit editor

Control-r

Anywhere

Open file input panel and lock canvas

Control-t

Canvas, on atom

Add tert.-butyl group

Control-u

Canvas

Undo last operation

Control-v

Canvas, in molecule box

Flip molecule vertically

Control-v

Canvas

Perform valence check

Control-w

Anywhere

Open file output panel and lock canvas

Control-x

Canvas

Clear canvas

Control-x

Fragment panel

Clear panel item

Control-z

Canvas, in molecule box

Delete molecule

Meta-comma (,)

Anywhere

Get previous buffer record

Meta-equal (=)

Anywhere

Get current buffer record again

Meta-period (.)

Anywhere

Get next buffer record

Meta-Delete

Anywhere

Clear buffer

Meta-a

Anywhere

Append current structure to buffer

Meta-d

Anywhere

Delete current buffer record

Meta-f

Anywhere

Get first buffer record

Meta-l

Anywhere

Get last buffer record

Meta-p

Anywhere

Print buffer pointer and buffer size

Meta-r

Anywhere

Replace current buffer record with canvas content

Meta-w

Anywhere

Write buffer to file

Meta-x

Anywhere

Clear buffer

Escape

Entry fields

Clear entry

Esc-h

Main window

Toggle auto hydrogen addition flag

Esc-v

Main window

Toggle auto valence check flag

Delete

Canvas, on atom

Delete atom

Delete

Canvas, on bond

Delete bond

Control-Delete

Canvas

Clear canvas

BackSpace

Canvas, on atom

Delete atom

BackSpace

Canvas, on bond

Delete bond

Control-BackSpace

Canvas

Clear canvas

Undo

Canvas

Undo last operation

Help

Anywhere

Open hypertext help panel

Redo

Canvas, on atom

Change element

Left

Canvas

Scroll left

Right

Canvas

Scroll right

Up

Canvas

Scroll up

Down

Canvas

Scroll down

Top Function Key 1

Fragment panel

Grab selection for current library item and delete it

Top Function Key 2

Canvas, in molecule box

Grab selection for current molecule

Top Function Key 2

Canvas

Grab selection for whole ensemble

Top Function Key 2

Fragment panel

Grab selection for current library item

Top Function Key 3

Canvas

Paste selection into canvas

Top Function Key 3

Fragment panel

Paste selection into fragment library

Top Function Key 4

Canvas, on atom

Change element

Left Function Key 2 (Again)

Canvas, on atom

Change element

Left Function Key 4 (Undo)

Canvas

Undo last operation

Left Function Key 6 (Copy)

Canvas, in molecule box

Grab selection for current molecule

Left Function Key 6 (Copy)

Canvas

Grab selection for whole ensemble

Left Function Key 6 (Copy)

Fragment panel

Grab selection for current library item

Left Function Key 8 (Paste)

Canvas

Paste selection into canvas

Left Function Key 8 (Paste)

Fragment panel

Paste selection into fragment library

Left Function Key 9 (Find)

Anywhere

Open fragment library panel

Left Function Key 10 (Cut)

Fragment panel

Grab selection for current library item and delete it

Right Function Key 2 (PrintScreen)

Anywhere

Open print panel

Known Bugs and Lacking Features

System Requirements and Portability

The Cactvs molecule editor is a Tk GUI script which runs on the generic Cactvs display server tkserver. The basic server program, i.e. the most simple of the tkserver program series, (without extensions for 3D molecule graphics [tkglserver], database access [tkdbserver] etc.) is sufficient because no auxiliary 3D widgets or networked database access are needed. The script will of course run unchanged on these more advanced display servers.

The underlying tkserver program has been ported to IRIX5.3, SunOS4.1.3 and Solaris2.4 (SunOS5.4). The csed command is a small shell script which sets some environment variables and calls the tkserver program with the correct command line options and GUI script.



1 No, its not green. Its chartreuse. All colors in this tool have fancy names.

2 Unmodified: No Shift, Control, Alt or Meta key or any combination thereof is pressed at the same time.

3 Currently, the editor uses only up to two modifier buttons simultaneously. We still refrain from introducing mouse button chords or Shift-Control-Meta combinations. However, few modifier key/button combinations are left unassigned, and there is still so much unimplemented desirable functionality...

4 Dragging means moving the mouse without releasing the (typically left) mouse button.

5 The bond length of automatically added hydrogen atoms is about 0.62 times the length of a medium bond.

6 It is still possible to draw higher bond orders in rings. Just temporarily open the small ring by deleting a bond, adjust the bond order and close the ring again.

7 This is NOT necessarily the currently selected file.

8 Automatic loading from Cactvs databases on the Internet is disabled in the public version. So you have to have the module locally on your machine.

9 Up to 200 atoms, subject to change

10 It`s a binary format, but Xdr-encoded, so you can exchange them between computers of different architectures.

11 The heuristics were developed by comparing the editor`s choice with human (catalog compiler`s) choice in complex structures taken from the VCH trivial names compound database. The structure drawings of this catalog clearly follow some rules, but these rules were obviously not always strictly adhered to, so no perfect human style emulation algorithm was possible.

12 Mail me an example if not! Stereochemistry is a rather new feature of the editor.

13 Not setable via the GUI


Ihlenfeldt@CCC.Chemie.Uni-Erlangen.DE
Copyright © 1998, W.-D. Ihlenfeldt, Universität Erlangen. All rights reserved.