Insight II 

Modeling Environment
Viewer, Docking, Analysis,
Ampac/Mopac, Builder

Release 2000
June 2000

9685 Scranton Road

San Diego, CA 92121-3752
619/458-9990 Fax: 619/458-0136
Copyright*
This document is copyright © 2000, Molecular Simulations Inc., a subsidiary of Pharma-
copeia, Inc. All rights reserved. Except as permitted under the United States Copyright Act
of 1976, no part of this publication may be reproduced or distributed in any form or by any
means or stored in a database retrieval system without the prior written permission of Molec-
ular Simulations Inc.
The software described in this document is furnished under a license and may be used or
copied only in accordance with the terms of such license.
Restricted Rights Legend
Use, duplication, or disclosure by the Government is subject to restrictions as in subpara-
graph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFAR
252.227–7013 or subparagraphs (c)(1) and (2) of the Commercial Computer Software—
Restricted Rights clause at FAR 52.227-19, as applicable, and any successor rules and regula-
tions.
Trademark Acknowledgments
Catalyst, Cerius2, Discover, Insight II, and QUANTA are registered trademarks of Molecular
Simulations Inc. Biograf, Biosym, Cerius, CHARMm, Open Force Field, NMRgraf, Polygraf,
QMW, Quantum Mechanics Workbench, WebLab, and the Biosym, MSI, and Molecular Sim-
ulations marks are trademarks of Molecular Simulations Inc.
IRIS, IRIX, and Silicon Graphics are trademarks of Silicon Graphics, Inc. AIX, Risc System/
6000, and IBM are registered trademarks of International Business Machines, Inc. UNIX is a
registered trademark, licensed exclusively by X/Open Company, Ltd. PostScript is a trade-
mark of Adobe Systems, Inc. The X-Window system is a trademark of the Massachusetts
Institute of Technology. NSF is a trademark of Sun Microsystems, Inc. FLEXlm is a trademark
of Highland Software, Inc.

Permission to Reprint, Acknowledgments, and References

Molecular Simulations usually grants permission to republish or reprint material copy-
righted by Molecular Simulations, provided that requests are first received in writing and
that the required copyright credit line is used. For information published in documentation,
the format is “Reprinted with permission from Document-name, Month Year, Molecular Simu-
lations Inc., San Diego.” For example:
Reprinted with permission from Cerius2 User Guide, March 2000, Molecular
Simulations Inc., San Diego.
Requests should be submitted to MSI Scientific Support, either through electronic mail to
[email protected] or in writing to:
*U.S.
version of Copyright Page
 MSI Scientific Support and Customer Service
9685 Scranton Road
San Diego, CA 92121-3752
To print photographs or files of computational results (figures and/or data) obtained using
Molecular Simulations software, acknowledge the source in the format:
Computational results obtained using software programs from Molecular
Simulations Inc.—dynamics calculations were done with the Discover®
program, using the CFF91 forcefield, ab initio calculations were done with the
DMol program, and graphical displays were printed out from the Cerius2
molecular modeling system.
To reference a Molecular Simulations publication in another publication, no author should be
specified and Molecular Simulations Inc. should be considered the publisher. For example:
Cerius2 Modeling Environment, March 2000. San Diego: Molecular Simulations
Inc., 2000.
Contents

APPENDICES

Figures
Figure 1. Viewer Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
Figure 2. Mouse Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Figure 3. Dial Box Functions . . . . . . . . . . . . . . . . . . . . . . . . . . .16
Figure 4. Using the Mouse as a Dial Box Control. . . . . . . . . . . .17
Figure 5. Commands in the Molecule Pulldown . . . . . . . . . . . .23
Figure 6. Color Command in the Molecule Pulldown . . . . . . . .32
Figure 7. Element Command in the Modify Pulldown . . . . . . .35
Figure 8. Color Molecule Command Parameter Block. . . . . . . .37
Figure 9. Center Command in the Transform Pulldown . . . . . .44
Figure 10. Label Command in the Graph Pulldown . . . . . . . . .45
Figure 11. Sample Spectrum. . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Figure 12. Example of Insight II Help Viewer Window . . . . . . .68
Figure 13. The Pilot Button . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Figure 14. The Forward Button . . . . . . . . . . . . . . . . . . . . . . . . .74
Figure 15. Spreadsheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
Figure 16. Molecule Browser . . . . . . . . . . . . . . . . . . . . . . . . . .114
Figure 17. Dial Box for Torsion Navigation . . . . . . . . . . . . . . .124
Figure 18. Example of the Fuse_1 command . . . . . . . . . . . . . .158
Figure 19. Example of 2-pair Intermolecular Fusion . . . . . . . .159
Figure 20. Example of 3-pair Fusion . . . . . . . . . . . . . . . . . . . .160
Figure 21. Example of Close Atom Fusion . . . . . . . . . . . . . . . .162

Insight II/March 2000 v

 Figure 22. Inversion of a Chiral Center . . . . . . . . . . . . . . . . . . 167
Figure 23. Captopril . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Figure 24. Components of Captopril . . . . . . . . . . . . . . . . . . . . 179
Figure 25. 2D Sketch of Captopril . . . . . . . . . . . . . . . . . . . . . . 189
Figure 26. The ACE Pharmacophore Model . . . . . . . . . . . . . . 196
207
Figure 27. MOPAC-BIOSYM-Optimizer Cycle . . . . . . . . . . . . 209
225
Figure 28. Graph/Threshold Examples. . . . . . . . . . . . . . . . . . 277

Tables
Table 1. Function Key Descriptions . . . . . . . . . . . . . . . . . . . . . . 18
Table 2. Operator Classes and Syntax . . . . . . . . . . . . . . . . . . . 269
Table 3. Reserved Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Table 4. Operator Precedence . . . . . . . . . . . . . . . . . . . . . . . . . 330
Table 5. Intrinsic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Table 6. Insight II Commands that Return a Value . . . . . . . . . 334
Table 7. Insight II Parameter Names . . . . . . . . . . . . . . . . . . . . 335
Table 1. Out-of-Plane Assignment Rules . . . . . . . . . . . . . . . . 446
Table 2. Atom Record Definition . . . . . . . . . . . . . . . . . . . . . . . 456
Table 3. Torsion Record Definition . . . . . . . . . . . . . . . . . . . . . 459
Table 4. Pseudo Atom Definition. . . . . . . . . . . . . . . . . . . . . . . 461
Table 5. Pseudo Atom Set Definition. . . . . . . . . . . . . . . . . . . . 463

1. Introduction to Molecular Modeling 1

Molecular Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Building and Modifying Structures . . . . . . . . . . . . . . . . . . . 2
Molecular Mechanics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Molecular Dynamics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Quantum Mechanics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Finally. . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

vi Insight II/March 2000

2. Introduction to Insight II 9
What is Insight II? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Starting Insight II. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Using Insight II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Accessing Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
By Object Name . . . . . . . . . . . . . . . . . . . . . . . . . . .13
By Object Connection . . . . . . . . . . . . . . . . . . . . . . .13
By Atom Selection . . . . . . . . . . . . . . . . . . . . . . . . .13
Manipulating Objects . . . . . . . . . . . . . . . . . . . . . . . . . .14
Mouse Functions . . . . . . . . . . . . . . . . . . . . . . . . . .14
Dial Box Functions . . . . . . . . . . . . . . . . . . . . . . . . .15
Slab Thickness Dial. . . . . . . . . . . . . . . . . . . . . . . . .16
On-Screen Dial Box Icon. . . . . . . . . . . . . . . . . . . . .17
Function Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
Atom Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Box and Lasso. . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Bond Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Toggling Selection . . . . . . . . . . . . . . . . . . . . . . . . .19
Picking vs. Selecting . . . . . . . . . . . . . . . . . . . . . . . .20
Deselecting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Selection Levels . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Logging and Playback . . . . . . . . . . . . . . . . . . . . . .21
Using ATOM_SELECTION . . . . . . . . . . . . . . . . . .21
Moving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Deleting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Command Hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Pulldowns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
Pre-Defined Icons (Icon Palette) . . . . . . . . . . . . . . . . . .24
Menu Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Atom Selection Icons . . . . . . . . . . . . . . . . . . . . . . .25
Subwindow Icons . . . . . . . . . . . . . . . . . . . . . . . . . .25
Parameter Block Icons . . . . . . . . . . . . . . . . . . . . . .25
User Definable Icons. . . . . . . . . . . . . . . . . . . . . . . .26
Help Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Customizing Your Environment . . . . . . . . . . . . . . . . . . . . .27
Icon Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
Nongraphics Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Backup, Recover, and Autosave Operations . . . . . . . . . . . .29
Command Logging and Restarting . . . . . . . . . . . . . . . . . . .29
Parameters, Parameter Blocks, and Value-Aids . . . . . . . . .31
Parameter Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Value-Aids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Insight II/March 2000 vii

 Focus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Inactive Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Parameter Defaults and Suggested Values . . . . . . . . . . . . . 39
Command Dispatching: Cancel, Execute, and the Trigger
Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Repeat and Activate Modes. . . . . . . . . . . . . . . . . . 40
Typed Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Concurrent Commands . . . . . . . . . . . . . . . . . . . . . . . . 43
On/Off Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Enumerated Parameters. . . . . . . . . . . . . . . . . . . . . . . . 46
List Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
All Other Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 47
History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Default Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Molecular Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
User Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Contour Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Assembly Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Graph Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Spectrum Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Object Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Object Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Monomer/residue Specification . . . . . . . . . . . . . . . . . 55
Atom Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Pseudoatoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Periodic Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Using Parentheses . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Predefined Properties. . . . . . . . . . . . . . . . . . . . . . . . . . 61
Property name (type). . . . . . . . . . . . . . . . . . . . . . . 61
Use of Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
RGB vs. Color Table Mode. . . . . . . . . . . . . . . . . . . 65
Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Insight II Help Viewer . . . . . . . . . . . . . . . . . . . . . . . . . 66
Using the Insgiht II Help Viewer . . . . . . . . . . . . . . 66
Top Menu Bar: Options and Help Menus . . . . 66
Navigational Buttons . . . . . . . . . . . . . . . . . . . 67
Help Text Viewing Area . . . . . . . . . . . . . . . . . 67
Pilot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
How Errors are Handled . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Errors in typed commands. . . . . . . . . . . . . . . . . . . . . . 69
Errors in menu -selected commands . . . . . . . . . . . . . . 70

viii Insight II/March 2000

3. Basic Applications 73
Pilot online tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Choosing a tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75

4. Viewer Module 77
Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
Window Layouts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
Spreadsheet Introduction . . . . . . . . . . . . . . . . . . . . . . .80
Creating a Spreadsheet. . . . . . . . . . . . . . . . . . . . . .82
Modifying the Spreadsheet Layout . . . . . . . . . . . .83
Manipulating Spreadsheet Data . . . . . . . . . . . . . . .83
Displaying Spreadsheet Data . . . . . . . . . . . . . . . . .83
Using the Spreadsheet . . . . . . . . . . . . . . . . . . . . . .84
Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Data Value Editing . . . . . . . . . . . . . . . . . . . . . .84
Cell References. . . . . . . . . . . . . . . . . . . . . . . . .86
Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Module Pulldown (MSI logo icon) . . . . . . . . . . . . . . . .87
Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Biopolymer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
DelPhi. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Solvation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Discover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Discover_3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Docking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
MCSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Ludi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Search_Compare. . . . . . . . . . . . . . . . . . . . . . . . . . .89
CHARMm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
MBOND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Homology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
NMR_Refine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Xsight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Binding Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Ampac/Mopac . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
DMol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Turbomole . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Zindo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
QuanteMM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
DeCipher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Session Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
Light_Source. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
Cmd_Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96

Insight II/March 2000 ix

 Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Autosave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Recover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Alias. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Stereo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Env_var . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Change_directory . . . . . . . . . . . . . . . . . . . . . . . . 100
Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
MSI_OnLine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
File Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Save_Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Restore_Folder. . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Remove_Folder . . . . . . . . . . . . . . . . . . . . . . . . . . 101
List_Folder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Export_Plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Export_Image . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Source_File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Export_Molscript . . . . . . . . . . . . . . . . . . . . . . . . . 104
Object Pulldown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Copy Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Paste Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Delete Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Rename Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Blank Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Axes_Display Object . . . . . . . . . . . . . . . . . . . . . . 106
Blink Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
DepthCue Object . . . . . . . . . . . . . . . . . . . . . . . . . 106
LineWidth Object. . . . . . . . . . . . . . . . . . . . . . . . . 106
List Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Molecule Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Get Molecule . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
AMPAC and MOPAC files . . . . . . . . . . . . . . 108
MSI car, arc, and cor files. . . . . . . . . . . . . . . . 108
Sybyl Mol2 files and MDL molfiles and SDfiles .
109
CSD Fdat . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Free Format Files. . . . . . . . . . . . . . . . . . . . . . 109
Brookhaven files . . . . . . . . . . . . . . . . . . . . . . 109
Put Molecule . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Set_Defaults. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Color Molecule . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Transparency Molecule . . . . . . . . . . . . . . . . . . . . 111

x Insight II/March 2000

 Display Molecule . . . . . . . . . . . . . . . . . . . . . . . . .111
Label Molecule . . . . . . . . . . . . . . . . . . . . . . . . . . .111
Bond_Order Molecule . . . . . . . . . . . . . . . . . . . . .112
Surface Molecule . . . . . . . . . . . . . . . . . . . . . . . . .112
Render Molecule . . . . . . . . . . . . . . . . . . . . . . . . .112
Ribbon Molecule. . . . . . . . . . . . . . . . . . . . . . . . . .112
Color_Ribbon Molecule . . . . . . . . . . . . . . . . . . . .113
SecondaryRender Molecule . . . . . . . . . . . . . . . . .113
List Molecule . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
Tabulate Molecule . . . . . . . . . . . . . . . . . . . . . . . .113
Browse Molecule . . . . . . . . . . . . . . . . . . . . . . . . .114
Measure Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . .115
Distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
Angle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Dihedral . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Monitor_Style . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
XYZ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Bump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Neighbor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
HBond . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
Energy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
Transform Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . .119
Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Position. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Move. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Rotate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Apply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Clip. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Rock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Torsion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Overlay. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
Superimpose. . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Subset Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Get Subset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Put Subset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
Define Subset . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
Zone Subset . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
Interface Subset . . . . . . . . . . . . . . . . . . . . . . . . . .126
Template Subset . . . . . . . . . . . . . . . . . . . . . . . . . .126
Combine Subset . . . . . . . . . . . . . . . . . . . . . . . . . .127
Copy Subset . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
Delete Subset . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
Rename Subset . . . . . . . . . . . . . . . . . . . . . . . . . . .127
List Subset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
Assembly Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . .128

Insight II/March 2000 xi

 Associate Assembly . . . . . . . . . . . . . . . . . . . . . . . 128
Add Assembly . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Remove Assembly . . . . . . . . . . . . . . . . . . . . . . . . 128
Cell Assembly . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Cell_display Assembly . . . . . . . . . . . . . . . . . . . . 129
Symmetry Assembly . . . . . . . . . . . . . . . . . . . . . . 129
Soak Assembly . . . . . . . . . . . . . . . . . . . . . . . . . . 130
List Assembly . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
User Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Get User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Color User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Transparency User . . . . . . . . . . . . . . . . . . . . . . . . 131
Annotate User . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Label User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Charsize User. . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
List User. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Spectrum Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Get Spectrum . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Put Spectrum . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Edit Spectrum . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
List Spectrum. . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Custom Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Add_To_Pulldown . . . . . . . . . . . . . . . . . . . . . . . 134
Catalogue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Macro_Delete. . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
List_Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Window Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Raise Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Lower Window . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Close Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Layout_Template Window . . . . . . . . . . . . . . . . . 137
Layout Window . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Raise_Layout Window. . . . . . . . . . . . . . . . . . . . . 137
Lower_Layout Window. . . . . . . . . . . . . . . . . . . . 138
Close_Layout Window . . . . . . . . . . . . . . . . . . . . 138
Help Pulldown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Insight_Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Traversing Help. . . . . . . . . . . . . . . . . . . . . . . 139
Print Window . . . . . . . . . . . . . . . . . . . . . . . . 139
Pilot_Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Contour Pulldown (accessed from the Contour icon) 140
Get Contour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Create_Single Contour. . . . . . . . . . . . . . . . . . . . . 141
Create_Range Contour . . . . . . . . . . . . . . . . . . . . 141
Clip_Display Contour . . . . . . . . . . . . . . . . . . . . . 142
Color Contour . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Transparency Contour . . . . . . . . . . . . . . . . . . . . . 142
Recalculate Contour . . . . . . . . . . . . . . . . . . . . . . 142

xii Insight II/March 2000

 Label Contour. . . . . . . . . . . . . . . . . . . . . . . . . . . .142
Charsize Contour . . . . . . . . . . . . . . . . . . . . . . . . .143
List Contour . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
Spreadsheet Pulldown . . . . . . . . . . . . . . . . . . . . . . . .143
New Command . . . . . . . . . . . . . . . . . . . . . . . . . .143
New_Molecule Command . . . . . . . . . . . . . . . . . .143
Open Command . . . . . . . . . . . . . . . . . . . . . . . . . .143
Put Command . . . . . . . . . . . . . . . . . . . . . . . . . . .144
Spreadsheet Command Summary . . . . . . . . . . . .144
New File. . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
Open File . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
Save File . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
Save_As File. . . . . . . . . . . . . . . . . . . . . . . . . .144
Duplicate File . . . . . . . . . . . . . . . . . . . . . . . . .144
Transpose File . . . . . . . . . . . . . . . . . . . . . . . .145
Print File . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Cut Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Copy Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Paste Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Clear Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Find Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Select Edit . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Insert Edit . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Delete Edit . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Fill Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Formula Data . . . . . . . . . . . . . . . . . . . . . . . . .146
Search Data . . . . . . . . . . . . . . . . . . . . . . . . . .146
Sort Data . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Summary Data . . . . . . . . . . . . . . . . . . . . . . . .146
Highlight Data . . . . . . . . . . . . . . . . . . . . . . . .147
Recompute Data. . . . . . . . . . . . . . . . . . . . . . .147
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
Color Format . . . . . . . . . . . . . . . . . . . . . . . . .147
Cell_Border Format . . . . . . . . . . . . . . . . . . . .147
Display Format . . . . . . . . . . . . . . . . . . . . . . .147
Style Format. . . . . . . . . . . . . . . . . . . . . . . . . .147
Column_Width Format . . . . . . . . . . . . . . . . .147
Row_Height Format . . . . . . . . . . . . . . . . . . .147
Protection Format . . . . . . . . . . . . . . . . . . . . .148
Preference Format . . . . . . . . . . . . . . . . . . . . .148
Graph Plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Bar Graph. . . . . . . . . . . . . . . . . . . . . . . . . . . .148
XYZ_Graph Plot. . . . . . . . . . . . . . . . . . . . . . .148
Histogram Plot. . . . . . . . . . . . . . . . . . . . . . . .148
Viewer Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148

Insight II/March 2000 xiii

 5. Builder Module 151
Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Atom Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Charge Atom . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Hybridization Atom . . . . . . . . . . . . . . . . . . . . . . 152
Planar Atom. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Potential Atom. . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Delete Atom. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Replace Atom . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Rename Atom . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
List Atom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Fragment Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Get Fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Put Fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Remove Fragment . . . . . . . . . . . . . . . . . . . . . . . . 155
Define Fragment . . . . . . . . . . . . . . . . . . . . . . . . . 155
Repeat Fragment . . . . . . . . . . . . . . . . . . . . . . . . . 155
Delete Fragment . . . . . . . . . . . . . . . . . . . . . . . . . 156
List Fragment. . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Modify Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Bond . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Fuse_1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Fuse_2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Fuse_3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Fuse_Close. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Hydrogens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Merge163
Unmerge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Ring_Conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Invert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Reflect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Atom_Position . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Forcefield Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Potentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Assign_CFF Forcefield. . . . . . . . . . . . . . . . . . . . . 170
Tabulate Forcefield. . . . . . . . . . . . . . . . . . . . . . . . 170
Forcefield Support . . . . . . . . . . . . . . . . . . . . . . . . 170
Pseudo_Atom Pulldown . . . . . . . . . . . . . . . . . . . . . . 171
Define . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Delete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Optimize Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Optimize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Builder Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

xiv Insight II/March 2000

6. Sketcher 175
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Application 2: Molecule Building . . . . . . . . . . . . . . . . . . .175
Building and Manipulating the ACE Inhibitor Captopril.
175
Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Building Captopril in 3D . . . . . . . . . . . . . . . . . . .178
Building Captopril in 2D . . . . . . . . . . . . . . . . . . .190
The Bioactive Conformation of Captopril . . . . . .197
The Inactive Stereoisomer . . . . . . . . . . . . . . . . . .202
Discussion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204
Files Created . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205

7. Ampac/Mopac Module 207

Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207
Summary of Ampac/Mopac Capabilities . . . . . . . . . .207
Geometry Optimization—The OPTIMIZE Suite of
Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210
Theory and Implementation . . . . . . . . . . . . . . . . . . . .214
The EF Algorithm and Mode Following . . . . . . .214
Constrained Optimization . . . . . . . . . . . . . . . . . .216
GDIIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .218
Command and Keyword Correspondance . . . . . . . . . . . .220
Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227
AM_Setup Pulldown . . . . . . . . . . . . . . . . . . . . . . . . .228
System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228
Electronic_State . . . . . . . . . . . . . . . . . . . . . . . . . .228
Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228
List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
Optimize Pulldown. . . . . . . . . . . . . . . . . . . . . . . . . . .229
Opt_Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .229
Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
AM_Parameters Pulldown . . . . . . . . . . . . . . . . . . . . .229
SCF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
Optimize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
Saddle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231
Background_Job Pulldown . . . . . . . . . . . . . . . . . . . . .231
AM_Run Pulldown. . . . . . . . . . . . . . . . . . . . . . . . . . .231

Insight II/March 2000 xv

 Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
AM_Analyze Pulldown . . . . . . . . . . . . . . . . . . . . . . . 231
Electron_Density . . . . . . . . . . . . . . . . . . . . . . . . . 232
Molecular_Orbital . . . . . . . . . . . . . . . . . . . . . . . . 232
Grid Pulldown (accessed from Grid icon) . . . . . . . . . 232
Get Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Put Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Display Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Color Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Histogram Grid . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Contour Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Slice Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Label Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
CharSize Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Difference Grid . . . . . . . . . . . . . . . . . . . . . . . . . . 235
List Grid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Ampac/Mopac Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . 235

8. Docking Module 237

Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Nonbond Potential in CVFF. . . . . . . . . . . . . . . . . . . . 238
Nonbond Potential in CFF9X . . . . . . . . . . . . . . . . . . . 239
Nonbond Potential in AMBER . . . . . . . . . . . . . . . . . . 241
Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Grid Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Evaluate Pulldown. . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Intermolecular . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Docking_Grid Pulldown . . . . . . . . . . . . . . . . . . . . . . 243
Create Docking_Grid . . . . . . . . . . . . . . . . . . . . . . 243
Compute Docking_Grid . . . . . . . . . . . . . . . . . . . 243
Display Docking_Grid. . . . . . . . . . . . . . . . . . . . . 244
Docking Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

9. Analysis Module 245

Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Average Plane Evaluation . . . . . . . . . . . . . . . . . . . . . 247
Frequency Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Additional Reading on Frequency Filtering . . . . 255
Clustering of Conformations into Families . . . . . . . . 255
Mean Square Displacement Precision . . . . . . . . . . . . 256
Radial Distribution Functions . . . . . . . . . . . . . . . . . . 257
Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Graph Pulldown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Trajectory Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Get Trajectory . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

xvi Insight II/March 2000

 Put Trajectory . . . . . . . . . . . . . . . . . . . . . . . . . . . .259
Filter Trajectory . . . . . . . . . . . . . . . . . . . . . . . . . .259
Animate Trajectory . . . . . . . . . . . . . . . . . . . . . . . .259
Unanimate Trajectory . . . . . . . . . . . . . . . . . . . . . .260
Conformation Trajectory . . . . . . . . . . . . . . . . . . .260
Family Trajectory . . . . . . . . . . . . . . . . . . . . . . . . .260
Repartition_Cluster Trajectory . . . . . . . . . . . . . . .260
Construct_Graph Trajectory . . . . . . . . . . . . . . . . .260
Axis_Function Trajectory . . . . . . . . . . . . . . . . . . .261
Cluster Trajectory . . . . . . . . . . . . . . . . . . . . . . . . .261
Distance_Def Trajectory . . . . . . . . . . . . . . . . . . . .261
COM_Distance_Def Trajectory . . . . . . . . . . . . . . .261
Angle_Def Trajectory . . . . . . . . . . . . . . . . . . . . . .261
Dihedral_Def Trajectory . . . . . . . . . . . . . . . . . . . .262
PP_Ang_3_Def Trajectory. . . . . . . . . . . . . . . . . . .262
PP_Ang_n_Def Trajectory . . . . . . . . . . . . . . . . . .262
pP_Dist_3_Def Trajectory . . . . . . . . . . . . . . . . . . .262
pP_Dist_n_Def Trajectory. . . . . . . . . . . . . . . . . . .262
COM_P_Dist_n_Def Trajectory . . . . . . . . . . . . . .263
Energy_Def Trajectory . . . . . . . . . . . . . . . . . . . . .263
Tabulate Trajectory . . . . . . . . . . . . . . . . . . . . . . . .263
Pseudo_Atom Pulldown. . . . . . . . . . . . . . . . . . . . . . .263
Background_Job Pulldown . . . . . . . . . . . . . . . . . . . . .264
Methodology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264
Memory Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . .266
Analysis Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .266

10. Graph Pulldown 269

Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269
Equation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .270
Correlate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .272
Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
Graph Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
Put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
Boolean. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274
Correlate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274
Equation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274
Contour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274
Line_Fit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .275
Interpolation. . . . . . . . . . . . . . . . . . . . . . . . . . . . .275
Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .275
Differentiation . . . . . . . . . . . . . . . . . . . . . . . . . . .275
FFT_Real. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .275
Smoothing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .276
CharSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .276
Color. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .276

Insight II/March 2000 xvii

 Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Move_Axis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Modify_Display. . . . . . . . . . . . . . . . . . . . . . . . . . 277
Scale_Axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Threshold. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Tick_Mark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

11. Background_Job Pulldown 281

Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Network Queuing System and Background Jobs. . . . 282
Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Background_Job Pulldown . . . . . . . . . . . . . . . . . . . . 283
Setup_Bkgd_Job. . . . . . . . . . . . . . . . . . . . . . . . . . 283
Control_Bkgd_Job . . . . . . . . . . . . . . . . . . . . . . . . 283
Completion_Status . . . . . . . . . . . . . . . . . . . . . . . 284
Kill_Bkgd_Job . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Methodology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Setting Up a Background Job . . . . . . . . . . . . . . . . . . . 285
Examining Completion Status . . . . . . . . . . . . . . . . . . 286
Killing a Background Job . . . . . . . . . . . . . . . . . . . . . . 287
Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

12. Biosym Command Language 289

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Creating Commands . . . . . . . . . . . . . . . . . . . . . . . . . 289
Creating Pulldown Menus and Modules . . . . . . . . . . 289
BCL vs. Open Interface . . . . . . . . . . . . . . . . . . . . . . . 290
How to Use this Guide. . . . . . . . . . . . . . . . . . . . . . . . 290
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Font Conventions of this Guide . . . . . . . . . . . . . . . . . 290
BCL Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Tutorial 1: hello.bcl . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Tutorial 2: myget.bcl. . . . . . . . . . . . . . . . . . . . . . . . . . 295
Tutorial 3: Working Example . . . . . . . . . . . . . . . . . . . 298
BCL Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
BCL Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

xviii Insight II/March 2000

 Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .305
Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .305
Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . .305
Accessing Parameters and Variables. . . . . . . . . . . . . .306
Coords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .306
Arrays and Pointers . . . . . . . . . . . . . . . . . . . . . . .306
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .306
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .307
Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .307
In Assignment Statements . . . . . . . . . . . . . . . . . .307
In Command Statements . . . . . . . . . . . . . . . . . . .307
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .308
Defining Functions . . . . . . . . . . . . . . . . . . . . . . . .308
Accessing Functions . . . . . . . . . . . . . . . . . . . . . . .308
Forward Referencing . . . . . . . . . . . . . . . . . . . . . .308
Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . .309
Conditionals . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309
If. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309
Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309
Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310
While . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310
ForEach . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310
File I/O and Operating System Access. . . . . . . . . . . .312
Reading from a File . . . . . . . . . . . . . . . . . . . . . . .312
By Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
By Token . . . . . . . . . . . . . . . . . . . . . . . . . . . .313
Writing To a File . . . . . . . . . . . . . . . . . . . . . . . . . .313
Parameter Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . .314
Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314
Setting Defaults . . . . . . . . . . . . . . . . . . . . . . .314
Calculating Defaults . . . . . . . . . . . . . . . . . . .315
Data Validation. . . . . . . . . . . . . . . . . . . . . . . . . . .316
Picking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316
Appearance . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317
Value-Aids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .318
Conditional Parameters . . . . . . . . . . . . . . . . . . . . . . .320
Accessing Insight II Data . . . . . . . . . . . . . . . . . . . . . . .321
Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .322
System Properties . . . . . . . . . . . . . . . . . . . . .322
User-Defined Attribute Properties . . . . . . . . .324
User-Defined Function Properties . . . . . . . . .326
Property Arrays . . . . . . . . . . . . . . . . . . . . . . .327
Spreadsheet Cells . . . . . . . . . . . . . . . . . . . . . . . . .327
Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .328
BCL Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .329
Reserved Symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . .329
Operator Precedence. . . . . . . . . . . . . . . . . . . . . . . . . .331
Intrinsic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . .333
Insight II Commands that Return a Value . . . . . . . . .335

Insight II/March 2000 xix

 Insight II Parameter Names . . . . . . . . . . . . . . . . . . . . 336
BCL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Assy_Fetch_Molecule . . . . . . . . . . . . . . . . . . . . . 338
BCL_UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Break . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Cell_Get_Real, Cell_Get_Int, Cell_Get_String . . . 338
Cleanup_Command. . . . . . . . . . . . . . . . . . . . . . . 339
Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Condition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Constant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Continue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Define_Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Define_Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Define_Module . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Def_Enum, Def_Enum_Sorted, Def_Enum_Unique .
341
Def_List, Def_List_Sorted, Def_List_Unique . . . . 341
End_Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Fgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
ForEach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
FullScreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Get_Boolean, Get_Integer, Get_Coord, Get_Real, Get_
Sstring, Get_Lstring, Get_Vlstring, Get_Ident,
Get_Enum . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Goto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
If. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Make_File_List. . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Message_Print_Error . . . . . . . . . . . . . . . . . . . . . . 345
Param_Add_File_List . . . . . . . . . . . . . . . . . . . . . 346
Param_Comment. . . . . . . . . . . . . . . . . . . . . . . . . 346
Param_New_Column . . . . . . . . . . . . . . . . . . . . . 346
Param_Pack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Param_Set_Style . . . . . . . . . . . . . . . . . . . . . . . . . 347
Place_Valuator . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Preview_Command . . . . . . . . . . . . . . . . . . . . . . . 347
Preview_Function . . . . . . . . . . . . . . . . . . . . . . . . 347
Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Printf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Prop_Exists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Prop_Get_Arr_Bool, Prop_Get_Arr_Int, Prop_Get_
Arr_Float, Prop_Get_Arr_Str . . . . . . . . . . . . 349
Prop_Get_Bool, Prop_Get_Int, Prop_Get_Float, Prop_
Get_Str . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Prop_Register . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Prop_Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Prop_Set_Bool, Prop_Set_Int, Prop_Set_Float, Prop_
Set_Str . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Read. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Input Formats . . . . . . . . . . . . . . . . . . . . . . . . 352

xx Insight II/March 2000

 Remove_Enum . . . . . . . . . . . . . . . . . . . . . . . . . . .353
Return. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .353
Run_Bkgd_Job . . . . . . . . . . . . . . . . . . . . . . . . . . .353
Screen_Update . . . . . . . . . . . . . . . . . . . . . . . . . . .354
Setv_Boolean, Setv_Integer, Setv_Coord, .Setv_Real,
Setv_Sstring, Setv_Lstring, Setv_Vlstring, Setv_
Ident, Setv_Enum. . . . . . . . . . . . . . . . . . . . . .354
Setv_Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .354
Setv_Precision . . . . . . . . . . . . . . . . . . . . . . . . . . .355
Setv_Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . .355
Set_Boolean, Set_Integer, Set_Coord, Set_Real, Set_
Sstring, Set_Lstring, Set_Vlstring, Set_ident, Set_
Enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .355
Set_Param_Pick . . . . . . . . . . . . . . . . . . . . . . . . . .356
Picking Templates . . . . . . . . . . . . . . . . . . . . .356
Picking Object . . . . . . . . . . . . . . . . . . . . . . . .357
Set_Rand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .357
Set_Random . . . . . . . . . . . . . . . . . . . . . . . . . . . . .357
Set_SideBlock . . . . . . . . . . . . . . . . . . . . . . . . . . . .357
Set_Slider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .358
Size_List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .358
Switch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .358
System_Fetch_Assy . . . . . . . . . . . . . . . . . . . . . . .359
System_Fetch_Atom. . . . . . . . . . . . . . . . . . . . . . .359
System_Fetch_Mol . . . . . . . . . . . . . . . . . . . . . . . .359
System_Fetch_Mono . . . . . . . . . . . . . . . . . . . . . .359
System_Fetch_Object . . . . . . . . . . . . . . . . . . . . . .359
System_Fetch_Sketch . . . . . . . . . . . . . . . . . . . . . .360
Test_Boolean. . . . . . . . . . . . . . . . . . . . . . . . . . . . .360
Test_Enum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .360
Textport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .361
Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .361
While . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .361
Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .361
Output Format . . . . . . . . . . . . . . . . . . . . . . . .362
Index of BCL Statements . . . . . . . . . . . . . . . . . . . . . . . . . .363

13. Utilities 367

Contour. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .368
Inplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .380

Insight II/March 2000 xxi

 A. References 389

B. File Formats 393

C. Setting Up the Brookhaven PDB 395

PDB Organization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Getting Brookhaven PDB database . . . . . . . . . . . . . . 395
Coping with more than 8000 PDB files . . . . . . . . . . . 395
The Standard Brookhaven Directory Structure . . . . . 395
Using a Representative Selection of PDB Files . . . . . . 396
Installing the PDB for use with Insight II Software . . . . . 396
Installing PDB Files . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Example of PDB setup for use with Biosym/MSI’s
software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Keep the INSIGHT_PDB Directory Clean . . . . . . . . . 399
IBM Workstations Warning: Do Not Use Soft Links to distr
Subdirectories . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Reading a PDB File into Insight II . . . . . . . . . . . . . . . . . . . 400
Using the Molecule/Get Command. . . . . . . . . . . . . . 400
Using the File/Import Command . . . . . . . . . . . . . . . 400
Creating New Index Files for the File/Import Command
401
Protein Loop Search (Biopolymer and Homology Modules) .
402
Setting Up and Using the Protein Loop Search
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Sequence Database Searching (Homology Module) . . . . . 404
Seq_extract and the Sequence Database File pdb.seq. 404
3D Profiles Database (Profiles-3D Module) . . . . . . . . . . . 405
Create_Profiles and the Database of 3D Profiles . . . . 405
The Shell Script Utility: link_pdb . . . . . . . . . . . . . . . . . . . 406

D. Fragment Definitions 409

E. Hydrogen Bonds 417

F. Space Group Names 419

G. Potential Template Rules 425

Potential Type Template . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Atom Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Element Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

xxii Insight II/March 2000

 Hybridization Test . . . . . . . . . . . . . . . . . . . . . . . . . . .428
Aromaticity Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . .428
Ring Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .429
Precedence Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .429
Examples of Potential Assignment for a Small Set of
Potential Types . . . . . . . . . . . . . . . . . . . . . . . . . . .430
Examples of Potential Assignments Using These
Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .433
Adding A New Parameter Type . . . . . . . . . . . . . .434
cvff_templates.dat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .435
Out-of-Plane Assignment Rules . . . . . . . . . . . . . . . . . . . .448

H. Amino Template File 451

File Format Description. . . . . . . . . . . . . . . . . . . . . . . . . . .452
Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .454

I. Classic File Formats 455

Cartesian Coordinate File (.car, .cor) . . . . . . . . . . . . . . . . .455
Molecular Data File (.mdf) . . . . . . . . . . . . . . . . . . . . . . . .457
Header Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .457
Comment Record . . . . . . . . . . . . . . . . . . . . . . . . .458
Atom Record . . . . . . . . . . . . . . . . . . . . . . . . . . . .458
End Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .461
Torsion Record . . . . . . . . . . . . . . . . . . . . . . . . . . .461
Pseudo Atom Record . . . . . . . . . . . . . . . . . . . . . .463
Pseudo Atom Set Record . . . . . . . . . . . . . . . . . . .465
Cartesian Coordinate Archive File (.arc) . . . . . . . . . . . . . .466

9. Using Compressed Files 469

Recognized Compression Formats . . . . . . . . . . . . . . . . . .469
Compressed Files Now Appear In Value-aids. . . . . . . . . .469
A Decompression Program Must Be On Your System. . . .470
Decompression Creates a Temporary File . . . . . . . . . . . . .470
Fail-Safe Decompression Strategy . . . . . . . . . . . . . . . . . . .471
Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .472
Using Soft Links to Compressed Files. . . . . . . . . . . . .472
VMS .Z Files Cannot Be Read . . . . . . . . . . . . . . . . . . .472
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INDEX-473

Insight II/March 2000 xxiii

xxiv Insight II/March 2000
Figure 1. Viewer Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
Figure 2. Mouse Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Figure 3. Dial Box Functions . . . . . . . . . . . . . . . . . . . . . . . . . . .16
Figure 4. Using the Mouse as a Dial Box Control. . . . . . . . . . . .17
Figure 5. Commands in the Molecule Pulldown . . . . . . . . . . . .23
Figure 6. Color Command in the Molecule Pulldown . . . . . . . .32
Figure 7. Element Command in the Modify Pulldown . . . . . . .35
Figure 8. Color Molecule Command Parameter Block. . . . . . . .37
Figure 9. Center Command in the Transform Pulldown . . . . . .44
Figure 10. Label Command in the Graph Pulldown . . . . . . . . .45
Figure 11. Sample Spectrum. . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Figure 12. Example of Insight II Help Viewer Window . . . . . . .68
Figure 13. The Pilot Button . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Figure 14. The Forward Button . . . . . . . . . . . . . . . . . . . . . . . . .74
Figure 15. Spreadsheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
Figure 16. Molecule Browser . . . . . . . . . . . . . . . . . . . . . . . . . .114
Figure 17. Dial Box for Torsion Navigation . . . . . . . . . . . . . . .124
Figure 18. Example of the Fuse_1 command . . . . . . . . . . . . . .158
Figure 19. Example of 2-pair Intermolecular Fusion . . . . . . . .159
Figure 20. Example of 3-pair Fusion . . . . . . . . . . . . . . . . . . . .160
Figure 21. Example of Close Atom Fusion . . . . . . . . . . . . . . . .162
Figure 22. Inversion of a Chiral Center . . . . . . . . . . . . . . . . . .167
Figure 23. Captopril . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Figure 24. Components of Captopril . . . . . . . . . . . . . . . . . . . .179
Figure 25. 2D Sketch of Captopril . . . . . . . . . . . . . . . . . . . . . .190
Figure 26. The ACE Pharmacophore Model . . . . . . . . . . . . . .197
209
Figure 27. MOPAC-BIOSYM-Optimizer Cycle . . . . . . . . . . . .211
227
Figure 28. Graph/Threshold Examples . . . . . . . . . . . . . . . . . .279

Insight II/March 2000 xxv

xxvi Insight II/March 2000
Table 1. Function Key Descriptions . . . . . . . . . . . . . . . . . . . . . .18
Table 2. Operator Classes and Syntax . . . . . . . . . . . . . . . . . . .271
Table 3. Reserved Symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . .329
Table 4. Operator Precedence. . . . . . . . . . . . . . . . . . . . . . . . . .332
Table 5. Intrinsic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . .334
Table 6. Insight II Commands that Return a Value . . . . . . . . .336
Table 7. Insight II Parameter Names . . . . . . . . . . . . . . . . . . . .337
Table 1. Out-of-Plane Assignment Rules. . . . . . . . . . . . . . . . .448
Table 2. Atom Record Definition . . . . . . . . . . . . . . . . . . . . . . .458
Table 3. Torsion Record Definition . . . . . . . . . . . . . . . . . . . . . .461
Table 4. Pseudo Atom Definition . . . . . . . . . . . . . . . . . . . . . . .463
Table 5. Pseudo Atom Set Definition . . . . . . . . . . . . . . . . . . . .465

Insight II/March 2000 xxvii

xxviii Insight II/March 2000
1 Introduction to Molecular
Modeling

Molecular modeling is a general term which covers a wide range

of molecular graphics and computational chemistry techniques
used to build, display, manipulate, simulate, and analyze molecu-
lar structures, and to calculate properties of these structures.
Molecular modeling is used in a number of different research
areas, and therefore the term does not have a rigid definition. To a
chemical physicist, molecular modeling might imply performing a
high quality quantum mechanical calculation using a supercom-
puter on a structure with 4 or 5 atoms; to an organic chemist,
molecular modeling might mean displaying and modifying a can-
didate drug molecule on a desktop computer. The criterion for a
successful modeling experiment should not be how accurately the
calculations are performed, but whether they are useful in ratio-
nalizing the behavior of the molecule, or in enhancing the creativ-
ity of the chemist in the design of novel compounds.
This section gives a brief introduction to techniques that can be
used to model molecules of interest to the bio-pharmaceutical
industry. The references included in appendix A contain more in-
depth information. Chapter 3, Basic Applications, lists a series of
tutorials which are provided, designed to help you get started
with molecular modeling with Insight II.

Molecular Graphics
A somewhat arbitrary, but frequently used, distinction is to divide
molecular modeling techniques into molecular graphics, and com-
putational chemistry. Molecular graphics is the core of a modeling
system, providing for the visualization of molecular structures
and their properties. Molecular graphics provides the ability to

Insight II/March 2000 1

1. Introduction to Molecular Modeling

display structures in a variety of styles (from simple line displays

to solid renderings known as CPKs) and color schemes, with
visual aids such as depth-cueing, and the ability to move the struc-
tures interactively in three dimensions. Simple tools for manipu-
lating structures, such as modifying torsion angles and calculating
geometry, are frequently included under the molecular graphics
banner.
The visualization of molecular properties is an extremely impor-
tant aspect of molecular modeling. The properties might be calcu-
lated using a computational chemistry program and visualized as
three-dimensional contours, along with the associated structures.
While manipulation of structures is usually interactive, the calcu-
lation of properties may require significant computer time. Calcu-
lations are usually run in the background rather than interactively,
leaving the modeling system free for interactive work. The graph-
ics part of the modeling system also provides the interface to the
computational chemistry tools, allowing calculations to be defined
and run, and then analyzed when complete. In Insight II the
Viewer module provides the tools for displaying and manipulat-
ing structures and representations of their properties.

Building and Modifying Structures

There are a number of sources of experimentally derived molecu-
lar structural data. These include the Brookhaven Protein Data
Bank which maintains a library of protein and nucleic acid struc-
tures, and the Cambridge Structural Database with a database of
small molecule structures. (Basics Application 6 shows how to use
structural data from these sources.) In the course of a modeling
experiment it is frequently necessary to modify these structures,
and of course to build completely new structures. A number of
techniques exist for building and modifying structures.
Small molecule structures can be built in three dimensions by join-
ing together basic building blocks from a fragment library, and
then modifying atom and bond types (this functionality is pro-
vided by the Builder module; see Basics Applications 1 and 2).
Macromolecule structures such as proteins and nucleic acids, con-
sisting of large numbers of specific units, can be built by specifying
the sequence of the units and the conformation in which the units

2 Insight II/March 2000

 Molecular Mechanics

should be joined. When necessary, individual units (amino acids

or nucleotides) may be modified or replaced in the same manner
that small molecule structures are modified (see the Biopolymer
module documentation).
An alternative to building in three dimensions (3D) is to sketch a
structure freehand in two dimensions, and then convert the sketch
into three dimensions. This approach has the advantage of speed
and the ease with which complex structures can be built; only ele-
ment types, connectivity, and (where necessary) stereochemistry
need to be defined. This capability is provided by the MolBuilder
toolbox of the Builder module, which uses distance geometry
techniques to convert a two-dimensional sketch to 3D. From the
connectivity of the sketch, distance geometry derives a series of
distance bounds for all atoms pairs, and a 3D structure is gener-
ated in which the interatomic distances satisfy these bounds. The
strength of the 3D conversion algorithm is that it is virtually insen-
sitive to the quality of the original 2D sketch. (See Basics Applica-
tions 1 and 2 for examples of sketching.)

Molecular Mechanics
When a structure is built it usually needs to be refined to bring it
to a stable, sterically acceptable, conformation. This is especially
true after building certain structures in three dimensions, when
the process of adding fragments can generate serious atom
clashes. The refinement process is known as minimization (or opti-
mization), and is an iterative procedure in which the coordinates
of the atoms are adjusted so that the energy of the structure is
brought to a minimum. The structure with the lowest energy is
considered to have the most stable arrangement, and by definition
the optimum geometry. Minimization generally results in a mod-
eled structure with a close resemblance to a real physical structure.
The ability to compute the energy of a structure is a necessary part
of the minimization process, and is an extremely important aspect
of a modeling system.
Molecular mechanics techniques take a classical approach to cal-
culating the energy of a structure. The molecule is treated essen-
tially as a set of charged point masses (the atoms) which are
coupled together with springs. The total energy of a structure is

Insight II/March 2000 3

1. Introduction to Molecular Modeling

calculated using an analytical function which sums a number of

individual energy terms. At its simplest level the function includes
bond stretching, valence angle bending, torsion, and nonbond
interaction terms, which associate an energetic penalty to the
structure based upon deviations from an idealized equilibrium
geometry. For instance, the bond term is a summation over all
bonds in the structure, in which the energy of each bond is evalu-
ated based on how far it is deformed from its equilibrium value.
The amount by which the energy increases for a given deviation
from the ideal value is determined by a parameter called a force
constant.
The nonbond interaction energy actually includes three terms:
1. van der Waals attraction
2. van der Waals repulsion, and
3. electrostatic
These three terms are summed for all atom pairs in the structure
that are 1-4 nonbonded and above. Any atom pairs in which one
atom is bonded to, or involved in an angle interaction with, the
other member of the pair is excluded from the nonbond energy
calculation. The electrostatic term requires that each atom be
assigned a partial charge, which for any atom can be either attrac-
tive or repulsive depending on the sign of the charges involved.
The number of nonbonded atom pairs rises with the square of the
number of atoms, and therefore the nonbond interaction term
dominates the computer time required for energy evaluation in
calculations on larger structures. For this reason, it is normal to
limit the nonbond energy evaluation to atom pairs within a certain
cutoff distance, based upon the assumption that atom pairs sepa-
rated by a larger distance make a negligible contribution to the
total energy.
The idealized equilibrium values of bond lengths and angles, plus
the force constants, and the van der Waals radii and associated
constants required to calculate the nonbond interactions, are
stored in a file which is referred to when the energy calculation is
run. The combination of these parameters with the functional
forms of the individual energy terms is known as a forcefield. It is
important to appreciate that the ideal values of bonds and angles
cannot be based upon element type alone. For example, a carbon-
carbon single bond is longer than a carbon-carbon double bond.

4 Insight II/March 2000

 Molecular Dynamics

For this reason, each atom in a structure must have a potential type
assigned before the energy calculation is run. The potential type
assigned depends on the hybridization state and environment of
each atom. The forcefield parameters themselves are stored in the
parameter file according to potential type.
Molecular mechanics enables the energy of a structure to be eval-
uated quickly, and may be applied to structures of a size up to and
including large proteins. Energy calculations have a range of
applications in molecular modeling. They can be used in confor-
mational analysis to evaluate the relative stability of different con-
formers (see below), and to predict the equilibrium geometry of a
structure. They can also be used to evaluate the energy of two or
more interacting molecules, as when docking a substrate into an
enzyme active site (Basics Application 3 illustrates docking in the
formic acid dimer using the Docking module.)
As described above, molecular mechanics energy calculations are
an integral part of energy minimizations. From the energy func-
tions it is possible to evaluate the forces acting on the atoms. Min-
imization actually uses information on the atomic forces to adjust
atomic coordinates in an iterative manner to bring the structure to
a minimum energy conformation. (Basics Application 1 and 2
illustrate use of the Optimize command in the Builder module.)
There are several different minimization algorithms which can be
used, depending on the nature of the problem (see Basics Applica-
tions 8 and 10).

Molecular Dynamics
A great deal of useful information can be gained from the study of
minimum energy structures. However, these structures are static
models, whereas in reality, molecules are flexible structures subject
to thermal motion. The technique of molecular dynamics can be
used to simulate the thermal motion of a structure as a function of
time, using the forces acting on the atoms to drive the motion.
Starting with the molecular mechanics energy description of the
structure as described above, the forces acting on the atoms can be
evaluated. As the masses of the atoms are known, Newton’s sec-
ond law of motion (force = mass * acceleration) may be used to

Insight II/March 2000 5

1. Introduction to Molecular Modeling

compute the accelerations, and thus the velocities, of the atoms.

The accelerations and velocities may then be used to calculate new
positions for the atoms over a short time step (around 1 femtosec-
ond, where a femtosecond is equal to 10-15 seconds), thus moving
each atom to a new position in space. This process iterates many
thousands of times, generating a series of conformations of the
structure known as a trajectory. A simulation is frequently run for
many tens of picoseconds (1 picosecond is equal to
10-12 seconds).
The velocities of the atoms are related directly to the temperature
at which the simulation is run. A simulation run at 300K provides
information on structural fluctuations that occur around the start-
ing conformation, perhaps to illustrate which parts of a molecule
are most flexible, and also can provide information on the path-
ways of conformational transitions. If the temperature of the sim-
ulation is increased, more energy is available to climb and cross
energetic barriers. Thus high-temperature (e.g., 1000K) simula-
tions are often used to search conformational space. (Basics Appli-
cations 10, 11, 12, and 13 illustrate some applications of molecular
dynamics.)
Molecular modeling techniques can become very powerful when
combined with experimental information. For instance, NMR
experiments may indicate that specific atoms are separated by a
certain distance. This information can be added to a simulation in
the form of restraints. During a simulation a force can be applied to
an atom pair to restrain it to the specified separation. Restraints are
important because they provide a certain amount of control over a
simulation. (Basics Applications 10and 11illustrate the use of
restraints in a dynamics simulation.)
Minimizations and molecular dynamics simulations may be per-
formed in Insight II using the Discover module. (For more infor-
mation, refer to the Theory and Methodology sections of the
Discover manual.)
Using molecular dynamics simulations it is easy to generate a vast
amount of data. The problem is in analyzing the data. The simula-
tion is usually analyzed first in a qualitative way by replaying the
simulation as a movie, a process known as animation. A simula-
tion can be analyzed quantitatively by defining properties of inter-
est, and then graphing those properties against each other. For
example, graphs that illustrate how the geometry or energy of the

6 Insight II/March 2000

 Quantum Mechanics

structure varies during the simulation can be created and com-

pared. The Analysis or, alternatively, the Decipher module pro-
vides a number of tools for analyzing a dynamics simulation.
(Refer to Basic Applications 9, 10, and 11.)

Quantum Mechanics
The electronic structure of a molecule is of prime importance in
determining its properties. When a drug molecule and receptor
interact, each “sees” the other as a blob of electron density which
is held together by the positive charges of the atomic nuclei.
Although molecular mechanics calculations are extremely useful
they consider essentially only the position of the nuclei and there-
fore cannot fully represent chemical reality. Molecular mechanics
provides no information on electronic structure, and furthermore
cannot be used when the molecule is not in its ground state, or
when covalent bonds are being broken or formed. There are a
number of properties that can be derived only using quantum
mechanics calculations.
Starting with a specified nuclear geometry, quantum mechanics
calculations solve the Schrodinger equation for this arrangement
of electrons and nuclei. This yields both the energy of the mole-
cule, and the associated wave function from which electronic
properties, such as electron density, can be calculated.
The energy of a structure calculated quantum mechanically can be
used in conformational searches, in the same way that the molec-
ular mechanics energy is used. Quantum mechanics calculations
can also be used for energy minimization. However, quantum
mechanics calculations typically consume a far greater amount of
computer resource than molecular mechanics calculations, and are
also generally limited to small molecules, whereas molecular
mechanics can be applied to structures up to the size of large pro-
teins. Molecular mechanics and quantum mechanics should thus
be viewed as complementary techniques. For instance, conforma-
tional energy calculations for a peptide are best carried out using
molecular mechanics. However, molecular mechanics is generally
ineffective for handling conjugated systems, while quantum
mechanics, in calculating electronic structure, takes account of
conjugation automatically and is therefore recommended for opti-

Insight II/March 2000 7

1. Introduction to Molecular Modeling

mizing the structure of a small molecule containing conjugated

systems.
The wave function can be used to calculate a range of chemical
properties, which can be used in structure activity studies. These
include electrostatic potential and electron density, dipole
moment, and the energies and positions of frontier orbitals. As
with the analysis of a molecular dynamics calculation, molecular
graphics is essential for visualizing these properties. Quantum
mechanics calculations are also used frequently to derive atom-
centered partial charges (although note that the term charge itself
does not have a strict quantum mechanical definition). Charges
have a wide range of applications in modeling, and are used in the
calculation of electrostatic energies in molecular mechanics calcu-
lations and in computing electrostatic potentials.
The most widely used quantum mechanics packages are the pub-
lic domain programs AMPAC and MOPAC, to which an interface
is provided in the Ampac/Mopac module. These programs utilize
the molecular orbital formalism in solving the Schrodinger equa-
tion, and are therefore known as molecular orbital programs. (The
application of molecular orbital calculations to computing partial
charges and then electrostatic potentials, and to calculating fron-
tier orbitals, is illustrated in Basics Application 5.)

Finally. . .
Once a modeling experiment is complete it is essential to be able
to convey the results. Hardcopy plots of molecular structures with
suitable annotations convey a large amount of information, and
the ability to incorporate structural displays into reports produced
using word processing packages is extremely useful. (Basics
Application 7 illustrates annotation and the production of hard-
copy.)

8 Insight II/March 2000

2 Introduction to Insight II

What is Insight II?

Insight II is a comprehensive graphic molecular modeling pro-
gram. In conjunction with the molecular mechanics/dynamics
program such as Discover, or CHARMm you can use the Insight II
program to build and manipulate virtually any class of molecule
or molecular system. In conjunction with other MSI products, you
can study molecular properties.

Starting Insight II
From the UNIX shell prompt type:

> insightII

Note that this command is case-sensitive. If you encounter prob-

lems, check with your system manager to be sure that the program
has been fully installed and that your UNIX environment vari-
ables are properly defined.
Note: For detailed hardware requirements and installation
instructions, refer to the Insight II Products System Guide.

Using Insight II
Building, displaying, and studying molecules is done by issuing
commands to the Insight II program. Most commands create and
affect objects. Further details on the object types in Insight II can be
found at the end of this chapter.

Insight II/March 2000 9

2. Introduction to Insight II

Commands
Commands can be issued in three ways: from the keyboard, by
selecting commands from pulldowns (menus), or by picking icons.
Picking an icon is equivalent to selecting a pulldown or a com-
mand from a pulldown. Each command has an equivalent typed
and menu form.
Typed commands are entered at the Command: prompt located in
the bottom of the Insight II program interface window. The box
around the command prompt is referred to as the command area
(see Command Area and Command Prompt in Figure 1). Typed
commands may also be placed in a file which can be executed
using the Source_File command.
If a command is presented in pulldown form, it appears along the
left of the interface window or along the top of the window (if the
number of parameters associated with the command is particu-
larly large).
Certain key pulldowns and commands can be accessed by clicking
on icons. When the Insight II program is started, a palette of icons
is provided (see Icon Palette in Figure 1). You may define the last
five icon positions to execute different commands.
Although some basic commands are self-contained, most com-
mands require you to input more information than just the com-
mand name. These additional pieces of information are referred to
as parameters for a command. In the menu version of a command,
the parameters are presented as boxes to be filled in. In the typed
form of the command, the parameters are listed after the com-
mand name and are separated by spaces.
When filling in parameter boxes in a menu, first select the param-
eter using the mouse. You may type in the parameter from the key-
board, and in some instances a value or object for the parameter
can be specified using the mouse. For example, if you need to spec-
ify the name of one of several molecules that are currently being
displayed, you could type in the name, use the mouse to pick the
molecule, or choose the molecule name from a list. All picking and
choosing is done by placing the cursor at the desired area of the
screen, and pressing the left mouse button. Other ways of using
the mouse are described later in this chapter.

10 Insight II/March 2000

 Using Insight II

Many commands output information of interest. This information

is presented in one or more of three general areas: the information
area, the textport, and the display window. Commands that gener-
ate answers that are in the form of a few numbers, or characters,
print the information in the bottom of the screen in the information
area (see Information Area in Figure 1). Note that this information
area can be scrolled.
Commands that generate large amounts of data print the informa-
tion in the textport (window) that was used to start Insight II. This
textport is made visible automatically, and may be put away with
the <Textport on/off> key at the bottom of the window. This key
can be activated by pressing the function key <F9> on your key-
board, or by toggling the box on the screen with the mouse.
Some commands produce information that changes depending on
subsequent operations. This data is presented at the top of the
Insight II window. The display of this information is controlled

Insight II/March 2000 11

2. Introduction to Insight II

directly through specific commands, and you cannot alter this dis-
play.
Figure 1. Viewer Module

Current Module Name

Pulldowns

Module Icon

Icon Palette

Command Area

Command Prompt

Information Area

Textport on/off Key

12 Insight II/March 2000

 Using Insight II

Objects
You can access and control objects in Insight II such as molecules,
graphs, and grids in commands by their unique name. You can
also manipulate objects, such as translating and rotating using the
mouse, function keys, physical dial box and the screen dial box.
These manipulations act on the connected object. You can also
select atoms that are affected by Insight II commands.

Accessing Objects

By Object Name
Each object in Insight II has a unique name. Insight II provides
defaults, which you can change with the Object/Rename com-
mand. For details about object names, see the Object Names section
later in this chapter.

By Object Connection
Either one object or all objects on the screen are “connected” at all
times. The connected object is specified immediately after the Conn
Obj line at the lower left corner of the Insight II window, by the
object’s name, or else the word World. The connected object is
affected by the mouse, function keys, and dials.
You can change which object is the connected object using any of
the following methods:
♦ the Transform/Connect command
♦ function keys 10 and 11
♦ holding the <control> key while picking the object with the
middle or right mouse button
Details about how to manipulate connected objects are covered on
the following pages.

By Atom Selection
Atoms can be selected with the left mouse button. Selected atoms
are shown with a white highlight in line mode or with stripes in

Insight II/March 2000 13

2. Introduction to Insight II

stick, ball-and-stick, and CPK modes. Selected atoms can be

affected by Insight II commands by referring to the ATOM_
SELECTION subset (e.g., Color ATOM_SELECTION Blue). Some
commands (particularly in the Sketcher product accessible from
the Builder module) use selected atoms directly.
Details about atom selection follow.

Manipulating Objects
You can manipulate objects with the mouse, dials, on-screen dials,
or function keys.
Note: In the following descriptions of functionality, the x axis is the
axis which lies horizontally in the plane of the screen. The y axis is
the axis which lies vertically in the plane of the screen. The z axis
is perpendicular to the x and y axes.

Mouse Functions
There are two basic actions you perform with the mouse: moving
the mouse to move the cursor on the screen, and pressing mouse
buttons. These two actions are combined to carry out a variety of
functions, such as accessing a pulldown, choosing commands or
parameters, picking a molecule or parts of a molecule on the
screen, and rotating, translating, or changing the viewing size of a
molecule. These functions are described in Figure 2.

14 Insight II/March 2000

 Using Insight II

Figure 2. Mouse Functions

Insight II Shortcuts

e
om
s

s
at
om

om
o

te
sl
at

s
ss

ta
om

an
om
At

At
le
a

Ro
es

Tr
om

/L

tip
At

At
le

ed
om
du

or ox
tip

nd

nd
ul
At

nd
An

ll

ed e
At
si

le e B

tM

tA

le lat
ul

ta

ta

Bo
n

Re

ct
M
tA

Se ans
ec
l

ec

ec
ec
Se g

le
ct

ct
ct
ct

ct

nn
c

nn
l
se

se
se
To

Tr
le

le
le

le

Co

Co
De

De
Se

Se
De
Se

Se

Double Hold Mouse

Click 2 Seconds.
Control Shift Shift Control Control
appears.

s
es

n
ld

io
kn
s

s
s

or

rs
s

ic
ct

ct
ct

ct

n
To
W

Th
je

je
je

io

io
je

Ob

Ob
Ob

rs

rs
le

n/
Ob

e
tiv
To

To
ec te

tio
ca

ec e
d

d
d

d
nn sla

nn t a t

nn v e

Ac
te
te
te

si
te

e
/S
nn e

Co Mo

at

rs
ec

Po
Co o
Co t a t
Co ran

ec

te
om

tiv

ve
Ro

ta
ab
Z

Z
T

Ac

Re
Ro
Zo

Sl

180.0

Copyright © 1995 Biosym/ Molecular Simulations

Dial Box Functions

Functions such as rotating, scaling, and translating can also be
manipulated using a Silicon Graphics dial box. The dial box func-
tions are described in Figure 3. Rotation speed can be scaled by
defining the environment variable DIAL_SPEED as a number
from 1 to 100, where the higher the number, the faster the rotation.
Note that some dials (dials 5 through 8) are dynamically allocated
to specific functions, based on the module you are working in or
the current function.

Insight II/March 2000 15

2. Introduction to Insight II

Figure 3. Dial Box Functions

Rotate in x
(dial 1)

Translate in x
Rotate in y (dial 5)
(dial 2)
Translate in y
(dial 6)
Rotate in z
(dial 3)
Translate in z
(dial 7)
Scale
(dial 4) Slab thickness
(dial 8)
Silicon Graphics
Dial Box

Slab Thickness Dial

The slab thickness dial (dial 8) adjusts the position and thickness
of the z clipping planes. Among other things, the thickness of the
slab controls depth cueing. When an object spans the entire z
depth, it exhibits maximum depth cueing. When an object spans
only a small portion of the z depth it exhibits little depth cueing.
This dial can be toggled to change the center of the z clipping
planes by depressing the function key labeled Slab Pos/Thick
(<F12>). Changing the position of the z clipping planes determines
what portions of the object are clipped in z space.
Clipping refers to the undisplaying of a region of an object or those
portions of the object that are external beyond the limits of the cur-
rently defined viewing window. The current thickness and posi-
tion settings of the z clipping plane are displayed at the lower
corner of the menu.

16 Insight II/March 2000

 Using Insight II

On-Screen Dial Box Icon

The dial box icon is the set of eight small boxes that appears near
the lower left corner of the window. The primary purpose of this
icon is to show what function is currently assigned to each of the
dials. Each box can be used with the mouse as a slider, controlling
the function of the corresponding dial.
To activate a dial box slider, move the cursor into the desired box—
for example, x rotation—and depress and hold the left mouse but-
ton. The object(s) currently connected to the dials should begin to
spin around the x axis. Releasing the mouse button stops the rota-
tion. Note that dial box sliders do not switch function when you
move the mouse outside of the box that the button was pressed in.
The slider stays active for the original function.
The direction and magnitude of the movement depends on where
in the box the cursor is relative to the box’s center. To the right of
center is positive (clockwise turning of the dial) and to the left is
negative.
Figure 4. Using the Mouse as a Dial Box Control
fastest no fastest
negative movement positive
(counterclockwise) (clockwise)
movement movement

X Rotate Y TranNSL

Insight II/March 2000 17

2. Introduction to Insight II

Function Keys
Across the bottom of the Insight II program’s interface screen are
a row of boxes with words and numbers. These are function keys.
Each function key performs a command. You can use a function
key in two ways: you can select it on the screen with the mouse, or
you can depress it on the keyboard. For example, function key 6
(on the screen) or <F6> (on the keyboard) causes all windows asso-
ciated with the current Insight II session to pop to the front of the
screen. A brief description of each function key follows:
Table 1. Function Key Descriptions
<F1> Full Screen. Toggle the Insight II program’s window so
that the black region of the window fills the entire
screen.
<F2> Stereo Sep. Toggles the function of the eighth dial so
that it can be used to control the stereo separation for
split pair stereo
<F3>, <F4>, <F5>
X, Y, Z Rotate. Rotates the connected object 90
degrees.
<F6> Windows Pop. Raise the Insight II windows so that the
main window is above all other applications on the
desktop and the subwindows are above the main win-
dow.
<F7> Next Torsion. Toggles the function of the right-hand
side of the dial box when there is one active torsion so
you can navigate through the defined torsions to acti-
vate the desired one.
<F8> Anim Frame/Speed. Toggles an animation from being
automatically updated to manually updated, or vice
versa. This function key also toggles the function of the
eighth dial from controlling the speed of the animation
to which frame is displayed, or vice versa. This key is
only enabled when an animation is present.
<F9> Textport on/off. Toggles the display of the textport
window from which Insight II was started. The textport
displays information that is too lengthy to be displayed
in the information area.

18 Insight II/March 2000

 Using Insight II

<F10> Connect Object. The dials are connected to the object

that is picked immediately after this key is selected. If
you need to end the Connect Object command without
picking an object, press the function key again.
<F11> Connect World. Automatically connects the dials to
world. When the dials are connected to world, all 3D
molecular objects on the screen move together.
<F12> Slab Pos/Thick. Toggles the function of the eighth dial
from controlling slab thickness to position, or vice
versa.

Atom Selection
Atom selection is an interactive, user-defined subset of atoms. This
subset is known to the system as ATOM_SELECTION. Refer to the
Mouse Graphics figure on page 2-5. The following tools and con-
ventions are used to define this subset.

Box and Lasso

In addition to using the cursor to pick individual atoms, an atom
selection can be defined by a box, or by a lasso. A box is defined by
clicking and dragging the cursor from one corner of an area to the
opposite corner. This method selects all of the atoms, monomers,
or molecules within the box. By holding down the <control> key
while dragging, a lasso can be used to draw a line around the
desired atoms. The Selection_Style icon can be used to toggle
whether box or lasso is the default. See Pre-defined Icons on the
following pages.

Bond Selection
Clicking on a bond selects both of the atoms connected by the
bond.

Toggling Selection
Hold down the <shift> key while selecting to add atoms to, or
remove atoms from what you have already selected.

Insight II/March 2000 19

2. Introduction to Insight II

Picking vs. Selecting

Atoms can be selected when no other picking operation is taking
place. Other picking operations take precedence when a parame-
ter has focus which has picking associated with it, such as a coor-
dinate parameter. Inking, transforming, and connecting also take
precedence over selection. The cursor shape indicates what opera-
tion the mouse controls.
Selecting:

Picking:

Inking:

Transforming:

Connecting:
NOTE: to make a selection while a picking parameter has focus,
hold down the ALT key.

Deselecting
To deselect all atoms, click over empty space.

Selection Levels
Atoms can be selected at three levels, atom, monomer/residue,
and molecule. A single click on an atom selects the atom. Double
click on an atom to select all the atoms in the residue containing
that atom. Triple click to select all the atoms in the molecule.
A default selection level can be set with the Selection_Level icon,
discussed on the following pages.

20 Insight II/March 2000

 Command Hierarchy

Logging and Playback

Selections are logged so that you can replay logfiles and have the
same selections occur. The selection is recorded as a list of values
to conserve space in the logfile.
BCL macros can use the ATOM_SELECTION subset, but should
not attempt to set selection with the selection playback command.

Using ATOM_SELECTION
The Builder module uses selected atoms directly. Select the atoms
to be affected and activate the command.
Use the string ATOM_SELECTION in specification parameters
such as Molecule Spec to affect selected atoms from commands.
ATOM_SELECTION is the subset which holds the selected atoms.

Moving
Selected atoms can be moved with the mouse. Position the selec-
tion cursor over a selected atom. Next, press and hold the left
mouse button until the cursor changes to:

.
Now you can drag the atoms to their new location. Monitors can
be added to help you position the atoms. Note that the movement
is in the plane of the screen.

Deleting
Selected atoms can be deleted by pressing the <Delete> key on the
keyboard.

Command Hierarchy
The Insight II program’s commands are organized in a hierarchy.
At the top of the organization are the modules. Next are the pull-
downs, and at the bottom of the hierarchy are the commands.

Insight II/March 2000 21

2. Introduction to Insight II

Modules
The base modules are: Viewer, Biopolymer, Builder, Docking,
Ampac/Mopac, Analysis, and DeCipher. There are also other
modules which may be available depending on your scientific area
of interest. Each module is a family of related commands. For
example, the Viewer module allows you to view molecules, con-
tours, and other graphical objects in different ways. You can tell
what module of commands is active by looking at the window
title. Following the Insight II program name and version number
is the name of the module (see Current Module Name in Figure 1).

Pulldowns
Below modules in the command hierarchy are pulldowns. These
are sets of related commands. You can tell which pulldowns exist
in the module you are currently in by looking at the top bars of the
Insight II program’s window. The names of the pulldowns are
listed horizontally along these bars (see Pulldowns in Figure 1).
There are more than two dozen pulldowns. Only some of these are
present in any one module. For example, only the Analysis mod-
ule contains the Trajectory pulldown. To execute a command, you
must be in a module that includes the pulldown that has that com-
mand. For example, if you want to load in atomic trajectory data
and animate molecules with it, you must go to the Analysis mod-
ule. This is required whether you are using menu or typed com-
mands.
The pulldowns listed along the top-most bar are present in every
module, and are collectively named the Viewer module. Those
along the second menu bar are available in whatever is the current
module, but not necessarily in any other module. Some pulldowns
are available in more than one module. These appear in the second
menu bar whenever you are in those modules.
Several of the most commonly used pulldowns can be accessed
either through the menu bar or by picking the appropriate icon
from the icon palette. Note that the icon functions do not vary from
module to module. The pulldowns (or commands) associated with
icons are consistent through all modules.

22 Insight II/March 2000

 Command Hierarchy

Figure 5. Commands in the Molecule Pulldown

Get
Put

Set_Defaults

Color
Transparency
Display Commands
Label

Bond_Order

Surface
Render
Ribbon
Color_Ribbon
SecondaryRender

List
Tabulate
Browse

Commands
Below pulldowns in the command hierarchy are the commands
themselves. For example, the Molecule pulldown contains the
commands: Get, Put, Set_Defaults, Color, Transparency, Display,
Label, Bond_Order, Surface, Render, Ribbon, Color_Ribbon,
SecondaryRender, List, Tabulate, and Browse (see Commands in
Figure 5). Some commands are unique to only one pulldown,
while others may appear in several pulldowns. For example,
Transform is the only pulldown containing the Center command
(i.e., there is only one Center command in all of the pulldowns).
Therefore, when you type in a command that appears in only one
pulldown you can always uniquely identify it by just the com-
mand name (e.g., Center). A command that appears in more than
one pulldown is not guaranteed to be unique. For example, there
is a Get command in each of the Molecule, User, and Contour
pulldowns (among others). If you want to get a molecule, you use
the Get command from the Molecule pulldown, while the Get
command from the User pulldown must be specified to get user
objects.

Insight II/March 2000 23

2. Introduction to Insight II

Note that the Insight II program provides a default object for each
module, and a default object for all modules. The default objects
are Molecule and Object. When typing in commands that require
an object to uniquely identify the command, the object specifica-
tion may be omitted if the default object is desired. For example,
Get Molecule may be entered as Get. Otherwise, use the com-
mand and pulldown name together as in: Get Subset.

Pre-Defined Icons (Icon Palette)

When the Insight II program starts, several icons are defined in the
icon palette (see Figure 1). These icons are one of these different
types.

Menu Icons
The top six icons (including the MSI logo) access pulldown menus.
Clicking one of these icons pops up the specified pulldown. Note
the small arrowhead in the lower right corner of most of these
icons, to indicate that it accesses a pulldown menu.

accesses the Module menu.

accesses the Spreadsheet menu.

accesses the Graph menu.

accesses the Grid menu.

accesses the Contour menu.

FF
accesses the Forcefield menu.

accesses the Selection_Render menu.

24 Insight II/March 2000

 Command Hierarchy

or accesses the Selection_Style menu.

or or accesses the Selection_Level menu.

Atom Selection Icons

The next group of icons act on the current atom selection.

depending on the current selection, measures and reports

the position (single atom selected), distance (two atoms), angle
(three atoms), or dihedral (four atoms), or suppresses an existing
monitor (Measure commands). If a monitor already exists, it is
removed.

defines the current selection (two atoms or four atoms) as an

active torsion, or deletes the torsion if it already exists. (Torsion).

Subwindow Icons
These icons bring up additional windows.

displays the Text_Browser.

displays the Sideview Window.

Parameter Block Icons

These icons bring up parameter blocks. They are redundant, in
that all of these can be brought up from the menu.
Note that on some smaller screens, these icons may not appear, to
prevent the iconbar from taking up two columns.

A bring up the text annotation parameter block (Annotate).

bring up the molecule color parameter block (Color Mole-

cule).

Insight II/March 2000 25

2. Introduction to Insight II

ON
OFF bring up the molecule display parameter block (Display
Molecule).

bring up the plot parameter block (Export Plot).

User Definable Icons

1 numbered buttons are user-definable. See the following sec-

tion on Customizing Your Environment for more information.

Help Icons

accesses the Pilot online tutorial and training tool (Pilot_

Tutorials).

? accesses the context-sensitive Insight II Help Viewer

(Insight_Help).

26 Insight II/March 2000

 Customizing Your Environment

Customizing Your Environment

Extensive options are available for modifying your session to best
meet your needs. Using commands in the core Viewer module,
some of the things you may choose to modify include:
♦ How each command’s parameters are displayed, using the
Cmd_Display command in the Session pulldown.
♦ Where additional windows (e.g., Spreadsheets, or the Molecule
Browser) created during the session appear, and how they are
scaled and moved, using the commands in the Window pull-
down.
♦ The light source color and direction using the Light_Source
command in the Session pulldown.
♦ Whether or not the automatic-save feature of the Insight pro-
gram is enabled. This is controlled by the Autosave command
in the Session pulldown (see additional information following).
♦ What commands are executed when one of the user-defined
icon buttons is clicked with the mouse. This is controlled by the
Button command in the Session pulldown. Hardware buttons
can also be set up using this command. The following section
details how to customize your icon buttons.

Icon Palette
The Insight II program provides an icon palette which includes
buttons for quick access to frequently used commands. The pre-
defined icons that automatically appear in Insight II are described
in the preceding section. It is easy to substitute your own choices
of frequently used commands for the default ones by following
these steps:
1. Use the Session/Button command to override one of the
default buttons with your own command. The buttons are
numbered from the top, starting with 1. If you would like the
icon button press to pop up a parameter block, in the same
manner as the default icons, just end the command string with
a ^ symbol.

Insight II/March 2000 27

2. Introduction to Insight II

2. When you override a default button, a new icon appears on that

button. Initially, this displays a numeral which corresponds to
the button number. If you would like to replace the numeral
with an icon of your own, use the following procedure:
a. Create your own insight_data directory. You may already
have this. If not, this is accomplished by creating a private
directory, then defining INSIGHT_DATA to point to it.
For example:
> mkdir $HOME/insight_data
> setenv INSIGHT_DATA $HOME/insight_data
The Insight program normally finds some data files,
including files which define the button icons, in the
INSIGHT_DATA directory. If you put your own versions
of any of these files in your private INSIGHT_DATA
directory, the private versions override the global ones.
b. Create icons (SGI only). The imged tool is a handy way to create
an icon. For example, use the following command:
> imged button1.rgb 32 32 -rgb
You can also use other image editing tools such as
imgworks to design your icon.
c. Convert the format. To convert from rgb to ximage format (the
format which the Insight program reads), use the make_ximage
tool. For example:
> make_ximage button1.rgb button1.ximage
This takes button1.rgb as input (the file created with
imged) and produces button1.ximage. To replace the
numeral icon for a button with your own, put a file called
buttonN.ximage, where N is the button number, into your
private INSIGHT_DATA directory. For example:
> cp button1.ximage $HOME/insight_data
The next time you start up the Insight program and replace button
1 (you can put the Session/Button command in your startup file)
your new icon appears.

28 Insight II/March 2000

 Nongraphics Mode

Nongraphics Mode
The Insight II program can be run without generating any graph-
ics. At the operating system prompt, the command to run the pro-
gram unattached is:

> insightII -at

Backup, Recover, and Autosave Operations

The Session pulldown includes commands that allow you to back
up the current objects in the session to a folder in the startup direc-
tory. This back up can be performed on demand, or automatically
at specified intervals using Autosave. Similarly, a Recover com-
mand is provided for bringing back all previously saved objects
(after deleting all existing objects).

Command Logging and Restarting

During each session using the Insight program, a record is kept of
the commands you execute. This log is written into a file named
WBLOGFILE in your present working directory. When you quit
from the program, the WBLOGFILE is renamed to insight.log. If
you terminate a session by any means other than using the quit
command, the WBLOGFILE is not renamed to insight.log. When
you start the Insight program, if the program finds that a WBLOG-
FILE already exists in your present working directory, it is
renamed to WBLOGFILE.save and a new WBLOGFILE is created.
The WBLOGFILE, WBLOGFILE.save, and insight.log files are nor-
mal text files that you can look at with any editor or with such
UNIX commands as more or cat. The log files contain a history of
the commands that were executed in a given session. All com-
mands appear in their typed form, even if they were originally
executed from a menu. However, menu commands are denoted by
several special characters at the start of the command line in the
log file. Once you have started the Insight program, a log file can

Insight II/March 2000 29

2. Introduction to Insight II

be replayed by using the Source_File command. By default, this

command uses the most recent insight.log file, although you can
explicitly specify any other filename (such as WBLOGFILE or
WBLOGFILE.save).
It may be convenient to have a variety of commands executed by
the Insight program each and every time you enter the program.
For example, you may wish to define aliases, or set the default
z-plane clipping automatically.
Each time you enter the Insight program, it checks to see if you
have a UNIX environment variable called INSIGHT_INIT_GLO-
BAL defined. (The program checks for a variety of variables. Refer
to the Installation instructions in the System Guide for complete
information.) If this variable exists, it should be defined as the
name of a file (including the path) that contains any commands to
be executed when starting the program. If INSIGHT_INIT_GLO-
BAL is defined, and corresponds to a file that exists, then those
commands are executed. If the file to which it refers does not exist,
an error is reported. If INSIGHT_INIT_GLOBAL is not defined, no
action is taken.
After checking INSIGHT_INIT_GLOBAL, the variable INSIGHT_
INIT_LOCAL is checked. If defined, and if the file to which it
refers is present, that file is taken as a source of commands which
are then executed.
Each of these variables may be used to refer to more than one file
of commands. In this case, each file is executed in order. To define
a variable which refers to more than one file, list the files in the def-
inition separated by spaces. For example, the following command
defines INSIGHT_INIT_LOCAL for two command files:
> setenv INSIGHT_INIT_LOCAL “my_startup_file /usr/dept/
insight_commands”

When starting the Insight program with this definition of

INSIGHT_INIT_LOCAL, the commands in my_startup_file are
executed, followed by the commands in /usr/dept/insight_com-
mands.
The paths used in your variable definitions may contain environ-
ment variables themselves. For example:
> setenv INSIGHT_DEPT “/usr/dept”

30 Insight II/March 2000

 Parameters, Parameter Blocks, and Value-Aids

> setenv INSIGHT_INIT_GLOBAL “$INSIGHT_DEPT/insight_commands”

In this example, the command insightII executes the commands in

/usr/dept/insight_commands when starting up.
A convenient way to use these startup variables is to define
INSIGHT_INIT_GLOBAL for an entire organization or depart-
ment and
INSIGHT_INIT_LOCAL for personal startup files.
One of the easiest ways to create a file containing your personal
startup commands is to copy and edit the insight.log file. Get into
the Insight program and interactively run all of the commands that
you want performed automatically at startup, then exit. The
insight.log file now contains those commands. Rename that file to
something like <yourname>.wbrc and edit the file to remove any
commands you do not want done automatically. Finally, edit your
.login to define INSIGHT_INIT_LOCAL to your personal startup
file.

Parameters, Parameter Blocks, and Value-Aids

As mentioned before, some basic commands are self-contained.
However, most commands require you to input more information
than just the command name. These additional pieces of informa-
tion are referred to as parameters for a command. In the pulldown
version of a command, the parameters appear in blocks along the
left- or right-side of the Insight II program’s window (see Parame-
ters in Figure 6). Very large parameter blocks may be placed along
the top of the window.

Insight II/March 2000 31

2. Introduction to Insight II

Figure 6. Color Command in the Molecule Pulldown

Command Name

Value-Aid

Enumerated Choice

Focus

Trigger Parameter

Typable Parameter

Non-typable Parameter

Parameter Blocks
A parameter block is labeled on top with the name of the com-
mand (see Command Name in Figure 6). Within each parameter

32 Insight II/March 2000

 Parameters, Parameter Blocks, and Value-Aids

block are the various parameter boxes. Each parameter box is

labeled with the name of that parameter.
There are different kinds of parameters. The most basic parameter
consists of a box that can be filled with a string of characters (see
Typable Parameters in Figure 6). The characters may be typed
from the keyboard. Some such parameters can also be filled by
simply selecting an appropriate object. The parameters Object
Name, Molecule Name, Molecule Spec, Subset, Monomer, Resi-
due, and Atom are among the parameters that may be filled by
typing or selecting.
Some parameters are filled only by selecting (see Non-Typable
Parameters in Figure 6). These parameters appear as a series of
choices listed vertically with a box next to each choice (see Enu-
merated Choice Parameter in Figure 6). To specify a choice for
such a parameter, position the cursor over the text or over the little
box next to the text and press the left-most mouse button. When
you have made such a choice, the little box is blackened. Using the
mouse in this way is referred to as selecting or choosing.
In addition to enumerated choice parameters, there are lists (see
List Parameter in Figure 7). A list parameter appears as a box
within which choices are listed vertically. For long lists, only a por-
tion of the choices are shown within the parameter box. You can
view different parts of the list by moving the little scroller box on
the right side of the parameter box. The scroller box is controlled
by placing the cursor over it and pressing down on the left-most
mouse button. To make a selection from a list parameter, place the
cursor over the item and press the left-most mouse button.
The final kind of non-typable parameter is one whose value is
either on or off. Such a parameter appears in a box containing that
parameter name next to the word on or off (see on/off Parameter
in Figure 7). To change the value between on and off, place the cur-
sor anywhere in the parameter box and press the picking mouse
button. This is sometimes referred to as toggling or toggling a
parameter on or off.
As mentioned above, a menu command’s parameter block starts
with the name of the command (in a box) and is followed by each
of that command’s possible parameters in separate boxes. Below
the parameter boxes are two boxes labeled <Cancel> and <Exe-
cute>.

Insight II/March 2000 33

2. Introduction to Insight II

Cancel is used to put a command’s parameter block away without

performing the command, even if some or all of the command’s
parameters are filled in. A command may be canceled in any of
several ways. The most obvious way of canceling a command is to
select the <Cancel> box with the mouse. A command is also can-
celed when a new command is selected from the menu bar (the
current command’s parameter block is replaced with the new
command’s parameter block). Commands are also canceled by
picking the information area below the command line.
Selecting <Execute> causes a command to execute with whatever
parameter values are currently set. If not all required parameters
are filled in, the <Execute> box cannot be selected and picking this
box causes the program to beep. It becomes accessible when you
have given sufficient information to execute the command.

34 Insight II/March 2000

 Parameters, Parameter Blocks, and Value-Aids

Figure 7. Element Command in the Modify Pulldown

List Parameter

On/Off Parameter

For many commands, the command name, the parameters, and

the <Cancel> and <Execute> boxes are all that exist in the param-
eter block. Other commands have extra boxes for what are known
as value-aids, because they help you to set values in parameters.

Value-Aids
Value-aids are found in the value-aid block near the command’s
parameter block. If there is room, they are placed below the <Can-

Insight II/March 2000 35

2. Introduction to Insight II

cel> and <Execute> boxes. If there is not enough room there, the
value-aid block is placed to the side of the parameter block.
Each value-aid is directly linked to a particular parameter in the
parameter block for a command. This linkage is apparent when
you look at a value-aid block because it is labeled with the name of
the parameter to which it is linked. Below the name of the param-
eter to which it is linked are one or more boxes which are labeled
in the same fashion as parameter boxes.
The most common value-aid is a list of suggested values. For
example, when filling in the value for the Molecule Spec parame-
ter, a value-aid pops up displaying a list of all the molecules that
exist in the current session. You can select an entry from this value-
aid list, and your choice is automatically placed into the parameter
that is linked to the value-aid.
Another common value-aid controls the picking level. Some
parameters can be filled in by picking objects from the screen. For
example, when coloring atoms in a molecule, you must fill in the
Molecule Spec parameter. Although you can type in a value, it
may be easier to pick a value by pointing to it with the mouse.
Note, however, that whenever you pick an object, you need to
specify whether you want the pick resolved to the molecule, a sub-
set of the molecule, the monomer or residue, or the specific atom
level. This is an important specification. If you specify the mole-
cule name, then all of the atoms in the molecule are affected. Sim-
ilarly, if you specify a monomer or residue, then only the atoms in
that subunit are affected, and if you pick an atom, then only that
atom is affected. So whenever you must fill in a value for the Mol-
ecule Spec parameter, a value-aid appears. It offers you a set of
choices to determine the picking level: Molecule, Subset, Mono-
mer, Residue, or Atom. Note that Monomer and Residue are
equivalent when setting the picking level. (See Value-Aid in
Figure 6.)
Another common value-aid is the color palette (see Color Palette
in Figure 8). This value-aid appears whenever you are filling in a
parameter that specifies a color. Placing the cursor over any one of
the pre-assigned colors and pressing the picking mouse button
selects this color as the one to be used for the command. Similarly,
selecting the blended color in corner of the color palette selects that
color for the command. The blend can be customized to any mix-
ture of red, green, and blue by using the horizontal color bars. Use

36 Insight II/March 2000

 Focus

the mouse and move the sliders to increase or decrease the amount
of red, green, or blue in the current color (Figure 8.)
Figure 8. Color Molecule Command Parameter Block

Color Palette

Red-Green-Blue Mix

Current Color

Pre-set Colors

Focus
As you fill in parameter values in the menu version of a command,
each typable parameter in turn is colored white. The focus is
whichever parameter is currently outlined in yellow. The top-most
typable parameter is usually the focus first. The focus parameter is

Insight II/March 2000 37

2. Introduction to Insight II

the parameter that currently is affected by typing or picking. If you

fill in a value (by typing and hitting <Enter>, by picking an object
on the screen, or by using a value-aid), the next typable parameter
becomes the focus and now only that parameter can be affected by
typing or picking.
Non-typable parameters are never the focus because they cannot
be affected by typing or picking objects on the screen (and they
never have associated value-aids). You can change values in non-
typable parameters at any time without affecting which parameter
is the focus.
You can explicitly change the focus at any time by placing the cur-
sor over the desired typable parameter and pressing the picking
mouse button.
The black vertical bar (|) is a text cursor showing where text you
type is added. You can use the picking mouse button to reposition
the cursor. You can also select or edit the region by positioning the
mouse, pushing the picking button, and then dragging to the
desired location before releasing the mouse. The edit region is
highlighted in black.

Inactive Parameters
A parameter block includes all of the parameters that can be used
for a given command. Depending on the value of some of the
parameters, other parameters may not be necessary or appropri-
ate. These parameters are inactive. You can use the Session/Cmd_
Display command to control whether inactive parameters are dis-
played in a light gray color, or are not displayed at all.
For example, consider the Color command in the Molecule pull-
down (see Figure 6). It only makes sense to specify R or S chirality
when you have chosen Chiral or Pro_Chiral for the Atom_Set
enumerated choice parameter. Therefore, unless you first choose
Chiral or Pro_Chiral, the R and S boolean parameter boxes are not
displayed (by default), or if specified by Session/Cmd_Display,
are drawn in light gray to indicate that they are inactive.

38 Insight II/March 2000

 Parameter Defaults and Suggested Values

Parameter Defaults and Suggested Values

Most commands in the Insight II program have default values for
some of the parameters. For example, in the Color command in the
Molecule pulldown, the default value of the Attribute parameter
is Atoms (meaning that, by default, you are coloring atoms rather
than Surfaces).
Over the course of a session using the Insight II program, parame-
ters that originally had no defaults may be given default values.
For example, when you first start the program, the Molecule
Name parameter (common to many commands) does not have
any default. But after getting your first molecule (by using com-
mands such as Get in the Molecule pulldown, or by using the
commands in the Builder or Biopolymer modules) the Molecule
Name parameter is defaulted to the name of the molecule
obtained.
As you continue working with the program, the default values for
such parameters may change. This is particularly noticeable when
you have multiple molecules. The default becomes whatever mol-
ecule you used last. Since the same parameter may be used in more
than one command, the default propagates from command to
command.
At times a parameter may be assigned a default value if the Insight
II program can suggest a reasonable value. For example, suppose
you are getting the crambin molecule from the Brookhaven library
of proteins. In the Get command in the Molecule pulldown, you
set the value of the File Name parameter to pdb1crn.ent. When
you press <Execute>, the Molecule Name parameter automati-
cally is set to the default value of crn because this is the most com-
mon name used for crambin. Naturally, you can change the
molecule name to something other than crn if you wish. Such sug-
gested values are intended to make working with the program
easier; they are not “written in stone”.
The Insight II program makes suggestions at two different times.
When you first enter a command’s parameter block, your current
environment (i.e., what objects exist, etc.) is examined and a first
draft of suggestions for parameter values is made. These are the
values you find when the parameter block initially appears.

Insight II/March 2000 39

2. Introduction to Insight II

As you fill in parameters (that do not have any value or do not

have an acceptable suggested value), more values may be sug-
gested. This is the case in the example described above, where crn
was suggested as a value for the Molecule Name parameter in the
Get command in the Molecule pulldown. The value crn was
derived by your filling in the File Name parameter.
Suggested values are not made for parameters if you type in a
command (i.e., you do not use the pulldowns at all). However, if
you do not fully type in a command (thus making the Insight II
program prompt you for each unfilled parameter) suggested val-
ues are presented.

Command Dispatching: Cancel, Execute, and

the Trigger Parameter
You can cancel a menu command at any time. To execute a menu
command, select the <Execute> button after the parameters are set
as you wish.
Some commands automatically execute after you have filled in
values for all of the typable parameters. Such commands contain
one (and only one) parameter framed by a double-lined box rather
than the usual single-lined box. This is the trigger parameter (see
Molecule_Spec parameter in Figure 6).
If you have filled in all other typable parameters and you fill in the
trigger parameter, the command automatically executes. You do
not have to select the <Execute> box. Therefore, be aware that fill-
ing in a value for a trigger parameter may cause the command to
execute. Make sure that non-typable parameters are set to the
desired values before causing a trigger parameter to execute a
command. The command trigger can be turned off or refocused for
any menu command, using the Trigger command in the Custom
pulldown.

Repeat and Activate Modes

After executing certain commands, the menu may reappear. Such
a command has entered repeat mode. The Command prompt
changes to the word Repeat. You can re-execute the same command

40 Insight II/March 2000

 Typed Commands

(presumably with at least one new parameter value). Or, you can
cancel the command.
The execution of some commands (in their menu form) may auto-
matically bring up different but related command menus. Com-
mands which correspond to such secondary menus are referred to
as activated commands. While in this mode, the Command prompt
changes to the word Activate. Secondary menus are used to step
you through a series of commands in a logical fashion. This is
done, for example, when creating a graph from atomic trajectory
information (with the Construct_Graph command in the Trajec-
tory pulldown). Since creating such a graph involves using several
different commands to define axis function data, the logical
sequence of commands is activated automatically.

Typed Commands
As mentioned previously, all commands are accessible in a fully
typed form. Note that an appropriate module must always be
selected before any non-Viewer command can be executed. To
select a module by typing, type the name of the module and then
the <Enter> key.
There is a direct correspondence between the order of the param-
eters as they are presented in a parameter block, and the order in
which they must be entered when typing in the full command.
When a command is typed in there is no value-aid available to
pick choices from. However, the Insight II program prompts for
omitted parameters if these are needed, and when available shows
defaults. Default enumerated parameters are immediately fol-
lowed by the word default, in angle braces: <default>. All other
defaults are enclosed in brackets. Pressing <Enter> when defaults
are available executes that command using default values.
To execute a command that you have typed, press the <Enter> key.
If the parameters necessary to complete the command have been
given, the command is executed. If there are missing parameters,
the program prompts you for the parameters needed to complete
the command. To cancel a typed command before <Enter> has
been pressed, you can backspace over each character in the com-
mand line. Or, easier still, press the letter u while holding down

Insight II/March 2000 41

2. Introduction to Insight II

the <Ctrl> key, or press <Esc>. This clears the command line
instantly. You can also use the <Esc> key to cancel a command that
is prompting for more input. Commands can be edited in the same
way as typable parameters.
If it is not clear to you how to finish a command or how to answer
a prompt, you may type a ^ (shift 6) and then hit the enter key. The
Insight II program responds by activating a parameter block and
setting the values that you have specified up until that point in the
command. You may then finish entering the command parameters
and execute the command as you normally would for a menu
command. The command is logged as a menu command. Note
that the ^ must not appear within a quoted string. This procedure
does not work for concurrent commands (see next section).
Parameters that were described as “non-typable” in the parameter
block description need not be entered in a typed command if the
default is desired. However, such parameters must be typed in if a
choice other than the default is desired. The three types of param-
eters that may be omitted when typing in a command are the on/
off parameters, the enumerated choice parameters, and the list
parameters.
There are basic rules for specifying the different types of parame-
ters described in the parameter blocks.
Parameters must be separated by spaces when entered on a com-
mand line. Triplet parameters, which are used to specify three
related numbers, such as coordinates (see the Triplet Parameter in
Figure 9), must have a comma separating each of the three num-
bers when they are entered on a command line. There must be no
spaces between the numbers and the commas. In the case of a
parameter that is text, and where that text includes spaces, all of
the text must be enclosed in quotation marks.
For example, suppose you want to label a graph axis as my axis
label. The command that you use is Label in the Graph pulldown,
and the pertinent parameter is Label Text (see Figure 10). To type
in the identical command, you must enclose the label text in
quotes. For example:

> label graph graph1 axis x “my axis label”

where label is the command name, graph is the object, graph1 is

the name of the graph or file itself, axis is the value of the Graph

42 Insight II/March 2000

 Typed Commands

Label Level parameter, x is the value of the Graph Axis parameter,

and my axis label is the value of the Label Text parameter.
When a command cannot be understood by the Insight II program,
the command that was entered is redisplayed in the command
area. The program highlights in reverse video the place in the com-
mand that it could not match, at which point a new value can be
entered. The command itself can be entered at any time by press-
ing the <Enter> key. Note that it is not necessary to retype the
entire command, only the portion causing the error. If you are hav-
ing difficulty with a typed command, it may be easier to clear the
command with <Ctrl>-u, and issue it using the appropriate pull-
down.

Concurrent Commands
Concurrent commands allow you to type a command in the com-
mand area while a parameter block is active. Concurrent com-
mands are entered by first selecting the command area, then
typing the concurrent command. The command area is selected by
moving the mouse to the command area and depressing and
releasing the picking mouse button. The command area is colored
yellow to signal that a command may be typed in. After the com-
mand is entered the parameter block becomes active again, and
the menu command can then be executed. Any command in the
top menu bar, which does not create or delete an object on the
screen, can be entered as a concurrent command.

Insight II/March 2000 43

2. Introduction to Insight II

Figure 9. Center Command in the Transform Pulldown

Triplet Parameter

Connected Object

On/Off Parameters
When specifying an on/off parameter as on, it may be typed as on,
or as the name of the parameter itself. When specifying an on/off
parameter as off, it may be typed as off, or as the name of the
parameter preceded by a dash (-).
For example, the Distance command has the parameter Monitor.
When the parameter is on, the distances selected are by default

44 Insight II/March 2000

 Typed Commands

added to the list of atoms monitored as the positions of the atoms

change. When this parameter is off, the distance is calculated once,
using the current atomic positions, and the atoms specified are not
added to the list of monitored atoms.
Figure 10. Label Command in the Graph Pulldown

The typed forms of the command to enable monitoring of the dis-

tance are:

> distance on 0 10 green atom1 atom2

or:

> distance monitor 0 10 green atom1 atom2

Insight II/March 2000 45

2. Introduction to Insight II

The 0 and 10 are the values for the parameter’s minimum distance
and maximum distance. The typed forms of the command to per-
form the distance calculation only once are:

> distance off atom1 atom2

or:

> distance -monitor atom1 atom2

Atom1 and atom2 must be entered in the proper syntax for atom
specification:
molecule:monomer/residue:atom

Enumerated Parameters
Enumerated parameters are entered by typing the text of the enu-
merated choice. In the above Distance command example, the
Monitor parameter actually controls whether or not an additional
enumerated parameter can be specified. The full syntax for the
Distance command allows for the addition of atoms to the list of
atoms having their distances monitored (using the Add option).
The command also allows for the deletion of atoms from the list of
atoms having their distances monitored (using the Remove
option). Finally, the list of atoms may be cleared entirely (using the
Clear option). Depending on the enumerated choice selected,
additional parameters may be necessary to completely specify the
command. In the case of Add, the parameters for the minimum
and maximum distances must also be specified.
Following are examples of the Distance command:

> distance monitor 0 10 green atom1 atom2

> distance monitor add 0 10 green atom1 atom2

These two commands add the specified atoms (atom1 and atom2)
to the list of atoms having their distances monitored. Note that
Add does not have to be entered since it is the default when Mon-
itor is specified. Also note that the 0 and 10 specify the minimum
and maximum distance to be used when monitoring the pair of

46 Insight II/March 2000

 Typed Commands

atoms. These specifications are required only when adding to the

list.

> distance monitor clear

This command clears the list of atoms having their distances mon-
itored. Note that the specification of atoms is not necessary in this
form of the command.

List Parameters
List parameters are entered by typing the text of the desired choice
from the list. For example:

> potential atom Ct atom1

All Other Parameters

All other parameters are entered by typing their desired values.

History
In addition to its log file, the Insight II program maintains a history
of the most recent commands executed. Both typed and
menu-entered commands are stored in the history buffer. Com-
mands can be accessed by typing a built-in history command to
the command prompt in the command line. Built-in history com-
mands have the following form:
!! Execute the last command again.
!-n Execute the nth command counting back from the last
(last=0).
!string Execute the most recent command starting with string.
&& Bring the last command into the command line for edit-
ing.
&-n Bring the nth command counting back from the last
into the command line.

Insight II/March 2000 47

2. Introduction to Insight II

&string Bring the most recent command starting with string

into the command line.
The & form of these commands allows you to see the command
and possibly edit it before it is executed. The command is executed
when you hit <return>. You may use <Esc> or <Ctrl>-u to clear the
command if you decide not to execute it.
The <up arrow> and <down arrow> keys allow you to move
through the history buffer, bringing each command into the com-
mand line for edit exactly as if you had typed &-n. If you are at the
most recent command and press <down arrow>, it clears the com-
mand line.

Default Objects
Commands can always be uniquely identified by both the com-
mand name and the object (pulldown).
For example, Get Molecule, Get Contour, and Get User uniquely
identify the proper command, while simply typing Get is too
ambiguous for the Insight II program. If Get is entered alone, you
are prompted with appropriate choices.
For typed commands, the program is set up to assume a default
object if one is not provided. For example, unless you reconfigure
the Insight II program, the Molecule object is set up as the default.
You can type get pdb pdb1crn.ent crn to get the crambin protein
from the Brookhaven library of proteins. You do not have to type
get molecule pdb pdb1crn.ent crn, because the default object is set
up as Molecule.
Even with a default object, you still might find it cumbersome to
have to type in the object for commands that are not included in
the default object. For example, if the default object is Molecule,
and you want to delete some Object (call it crn), you could type
delete object crn. This specifies which Delete command to use,
since Delete exists in both the Object and other pulldowns (and is
therefore not uniquely named). Because this is cumbersome, two
default objects are defined. One default is for all of the modules,
while the other is defined on a per-module basis.

48 Insight II/March 2000

 Object Types

Unless you change the defaults, the Insight II program is set up

with the Molecule object as the all-module default, while Object
is the per-module default object for each module. The result is that
you can give the commands get pdb pdb1crn.ent crn and delete
crn in all modules, and the program uses defaults to resolve the
ambiguities.
If you are interested in exploring the notion of default objects fur-
ther (and, perhaps, would like to set up your own choices for these
defaults), use the Default_Cmd_Object choice for the Command
Type parameter, in the Environment command in the Session
pulldown.

Object Types
Central to the understanding of the Insight II program is the con-
cept of objects. Objects are unique entities which may be addressed
by name within the program. There are several different types of
objects, each with its own unique characteristics and properties.
Throughout this section, reference is made to other sections of this
manual where you can find additional information on defining
and manipulating these object types.

Molecular Objects
The primary type of object is the molecule. Molecules can come
from a variety of sources, including:
♦ Molecular fragment files (see Get Fragment in the Fragment
pulldown)
♦ Brookhaven Protein Data Bank (see Get Molecule, PDB option)
♦ Cambridge Crystal Data Base (see Get Molecule, Cambridge
option)
♦ Energy minimization or dynamics simulations performed by
the Discover program (see Get Molecule, Archive option, and
Get Trajectory in the Trajectory pulldown in the Analysis
module)

Insight II/March 2000 49

2. Introduction to Insight II

♦ External modeling programs (see Get Molecule, Free_Format

option)
♦ Molecular sketch facility (see the Builder)
Regardless of their source, molecules all have several properties in
common. They are composed of monomers/residues, and atoms
within those monomers/residues. In the case of PDB input, the
monomers/residues are amino acids and, generally, there are
many monomers/residues per molecule. In the case of input from
the Cambridge database files, there is one monomer/residue per
molecule and all atoms are in that monomer/residue. Monomers/
residues usually have names that reflect their chemical composi-
tion (GLY, TRP), and numbers that denote their relative location
within the molecule.
The basic characteristics of atoms include atom names (which
reflect the atomic type of the atom, such as CG or ND1), and
atomic coordinates. Other information which may be known for
atoms of a molecule includes the atomic charge, the potential atom
parameter type, and the isotropic temperature factor. Molecules
can have van der Waals or solvent accessible surfaces, and in the
case of proteins, ribbon representations. Molecules can be
assigned crystal cell parameters, which may be used for crystal
packing and for generating the unit cell environment. Elemental
types are also assigned to each atom when molecules are read into
the system.

User Objects
The second type of object is the user object. User objects are com-
posed of dots, vectors, or text. Any given user object is composed
of one of these types. A user object has only a name. It does not
contain any divisible elements which can be referred to separately.
The entire user object color can be changed at one time, but indi-
vidual pieces cannot be changed. For the vector and text types,
there can be only one color for the entire object. For the dots type,
each dot has an individually specified color.
For further details on the format of the user object definition files,
see the online documentation for the Get User command, in the
Viewer module.

50 Insight II/March 2000

 Object Types

Contour Objects
The third type of object is the contour. Contours are used in the
solution of molecules via x-ray techniques and in the display of
output from ab initio programs such as Ampac, Mopac, and DMol.
Contouring may also be used for the display of energy levels (e.g.,
in the creation of phi/psi maps) and in displaying isopotential sur-
faces from DelPhi and DMol program output. Commands in the
Contour pulldown allow you to create contours from grid data.
The contour, like a user vector mode object, can have only a single
color. Unlike the user object, however, the contour can have
selected portions of the object displayed under user control. The
Clip Contour command description describes how to control the
display of contours.

Assembly Objects
The fourth type of object is the assembly. An assembly is composed
of a collection of one or more other objects (including other assem-
blies). Operations, such as rotations, applied to assemblies act on
each of the components of the assembly, treating the components
as if they were a single object. Thus, assembly rotations occur
about the assembly’s center of rotation just as if all of the objects of
which the assembly is composed are a single object.
Assemblies can be composed of a mixture of other object types. An
assembly could contain the combination of a molecule, an electron
density contour, and a user mode text object. These separate
objects could then be treated as a single object for the purpose of
rotation, translation, or scaling. Assemblies are created with the
Associate command, which is located in the Assembly pulldown.

Graph Objects
The fifth type of object is the graph. Graphs can be created from
within several different modules of the Insight II program. Graphs
are created by defining properties to plot on each of the axes.
A graph may be manipulated in much the same way as any other
type of object. Graphs may be scaled, moved, rotated, blanked, or

Insight II/March 2000 51

2. Introduction to Insight II

unblanked. Graphs may also have their axis titles colored or rela-
beled. Graphs may be coupled directly to an animated molecule or
molecular system, but need not be. Note that graph objects are not
automatically connected to other objects or world and therefore
must be explicitly connected using Connect Object in order to be
manipulated.

Spectrum Objects
The sixth type of object is the spectrum (see Figure 11). Spectrums
are created with the Create Spectrum command in the Viewer
module. Spectrums are used to map data values to colors in a vari-
ety of coloring and data analysis commands. They may specify
very complex mappings through the use of multiple subranges,
each being either a solid color or a color ramp. Commands in the
Spectrum pulldown are available to get, put, edit, manipulate, and
list spectrums. Spectrums may also be scaled, positioned, copied,
renamed, blanked, and listed using commands in the Transform
and Object pulldowns in the Viewer module.
Several spectrums are provided with the Insight II program. For
example, CHARGE_SPECTRUM is used to color atoms, surfaces,
and CPKs according to their partial charge values. Another,
TEMP_FACTOR_SPECTRUM, colors atoms, surfaces, and CPKs
according to their temperatures.

52 Insight II/March 2000

 Object Names

Figure 11. Sample Spectrum

under range color subrange 1 object label subrange 2 over range color

CHARGE_SPECTRUM

-1.00 -.80 -.60 -.40 -.20 0.0 .20 .40 .60 .80 1.0
DelPhi charge value

subrange boundary markers user label scale

Object Names
In addition to becoming familiar with the various object types, it is
important to understand the way the Insight II program uses
object names. Throughout the command descriptions in the fol-
lowing chapters it is assumed that you understand the format of
the object name and its various components. This section describes
each of the components of the overall object name, and looks at the
various ways these components can be specified and combined.
Every object must have a name. The name must be unique. Com-
mands should not be used as object names.
Molecule names are composed of up to three components:
1. Object name
2. Monomer/residue specification
3. Atom specification
Only molecules have these three components. All other objects
have only an object name.

Insight II/March 2000 53

2. Introduction to Insight II

Object Name
The object name is composed of characters taken from the set of
alphabetic characters (a-z), the numbers (0-9), and may also
include the dollar sign ($) and underscore (_) characters. An object
name can begin with any alphabetic character or the dollar sign.
The maximum length of an object name is 19 characters, but since
it may typed often, a short name is suggested. These are examples
of valid object names:
AMINO_ACID
LYS
BIND$PROTEIN
Note that although the dollar sign is allowed, it is not recom-
mended because in some instances the Insight II program uses the
object name to generate external filenames. Since the $ character
has special meaning in UNIX, its presence in a filename could
cause problems.
These are examples of invalid object names:
_LYS
(Invalid because of the leading underscore.)
23SKIDOO
(Invalid because it begins with a number rather than a letter.)
BIND@PROTEIN
(Invalid because it contains an illegal character, @.)
Object names can also be compound. When an object is part of an
assembly (see the Associate command), it can be referred to in the
context of the assembly by specifying first the assembly name,
then a dot to separate the names, then the name of the primitive
object. Thus, the name:
ASSEMBLY.PRIMITIVE
refers to the object named PRIMITIVE in the context of the object
named ASSEMBLY.
In the special case of a symmetry-replicated molecule (see the Cell
and Symmetry commands in the Assembly pulldown), there is a
special syntax for the molecule name which allows you to specify

54 Insight II/March 2000

 Object Names

a specific replicate of the molecule. The cell object name is fol-

lowed by the replicate number in parentheses. For example, to
refer to the third replicate of the cell object ABC_CELL, specify the
object name as:
ABC_CELL(3)
Only some commands can operate on replicates. See the command
descriptions for details.

Monomer/residue Specification
This portion of the overall name exists only for molecules. For
example, for a protein this subunit of the molecule can take several
forms:
1. It can be a specific residue type such as LYS or PHE (you can
also use the single letter abbreviations). In addition, the
charged species of residues may be referenced by using a P to
denote plus (+), or an M to denote minus (-). Examples:
ARGP references ARG+
ASPM references ASP-
Capping residues with neutral sidechains are also matched
with their normal names. Examples:
ARG matches ARG, ARGn, ARGN, and ARGC
GLY matches GLY, GLYn, GLYN, and GLYC
2. It can be a specific residue of a protein, such as A312 (residue
312 of the A-chain).
3. It can be a range of monomers/residues, specified by typing the
first and last monomers/residues (inclusive) separated by a
dash, such as A132-A150, or 3-12.
4. It can be a series of individual monomers/residues separated
by commas, such as A132,A140,A150, or 3-12,14,15.
5. It can be a combination of the above, such as A130-
A140,LYS,B12.
6. Two special names, BEG and END, can be used to refer to the
first and last residues or monomers, respectively, in the mole-
cule. Thus the range BEG-END refers to all residues or mono-
mers of the molecule.

Insight II/March 2000 55

2. Introduction to Insight II

An additional syntax is allowed in the specification of ranges. If

the monomer/residue range is followed by the at sign (@) and a
number (n), only every nth residue is used. Thus, A130-A140@2
specifies every second monomer/residue beginning with A130
and ending with A140.
The monomer/residue specification is separated from the object
by a colon. Thus, to specify all monomers/residues from A150 to
A160 of the object TEST, the proper specification is:
TEST:A150-A160
Note that all monomer/residue numbers must be unique within a
molecule.

Atom Specification
The next portion of the overall object name is the atom specifica-
tion. It takes very much the same format as the monomer/residue
specification. That is, you are allowed to specify single atoms sep-
arated by commas, atom ranges separated by dashes, and atom
ranges selecting every nth atom using the @. There are no specific
atom types or abbreviations for atoms. The atom specification fol-
lows the monomer/residue specification, separated by a colon. If
there is no actual atom specification, then the atoms are selected
from the molecule in the order of their occurrence in the molecule.
For example, consider a molecule that is comprised of the atoms
C1, O2, C3, C4, that has one monomer/residue, and is called TEST.
The specification:
TEST:1:
selects atom C1, O2, C3, and C4, or all the atoms of TEST. The spec-
ification:
TEST:1:c*
selects only the carbon atoms, or C1, C3, and C4 (that is, this spec-
ification identifies all C atoms). The specification:
TEST:1:C4,C3,C1
does the same thing, selecting atom C4, then C3, and finally C1.
For most commands the actual order in which the atoms are
selected is unimportant (for example, with the commands Color

56 Insight II/March 2000

 Object Names

and Display). However, in some commands matching or pairing

of one specification to another is implied. In these cases, the order
of atom specification is critical. An example of an order-dependent
command is Superimpose.

Pseudoatoms
Pseudoatoms are defined as the instantaneous average of the coor-
dinates of a set of real atoms. For example, the centroid of a phenyl
group could be displayed as a pseudo atom created from the six
carbon atoms in the ring. Pseudoatoms are referenced in the same
way as atoms; their names may be explicitly specified at the time
of their creation, or the names may be generated automatically.
Note that all atom names must be unique within a monomer/res-
idue. See the Builder command summary for additional informa-
tion about pseudoatoms.

Periodic Systems
Periodic atoms are used to model periodic systems. They are cre-
ated by performing symmetry operations or unit cell translations
on an asymmetric unit. Periodic atoms have many of a real atom’s
attributes and operations, such as coordinates, CPK, surface, color,
label, clipping, and bonds. They also contain information on the
real atom and the symmetry or offsetting operation which created
them. This information is reflected in a periodic atom’s pick string.
This string is obtained when a periodic atom is selected with the
mouse. The format of the pick string is as follows:
unit_cell.molecule:res:atom#operation%offset
where unit_cell is the name of the cell (a concise name for the peri-
odic system), molecule is the parent molecule contained in the cell,
res is the residue name, atom is the parent atom, operation is the
symmetry operation which the periodic atom was created via, and
offset is the x,y,z cell offset of the periodic atom. An example of a
periodic atom pick string is:
UNIT_CELL.PREN:1:C1#3%0.0.,0.0,0.0
Periodic atoms have the capability of being grouped into replicate
objects when needed by a command. This capability is reflected in

Insight II/March 2000 57

2. Introduction to Insight II

the molecule level pick string of a periodic atom. The pick string is
as follows:
unit_cell(replicate_number)
where unit_cell is the name of the cell object, and replicate_number
corresponds to the index of the replicate within the cell. An exam-
ple of a replicate level pick string is:
UNIT_CELL(4)
♦ The following Insight II program commands support periodic
atoms:
♦ CPK Molecule
♦ Get Molecule
♦ Put Molecule
♦ Distance Measure
♦ Angle Measure
♦ Dihedral Measure
♦ XYZ Measure
♦ Merge Modify (supported for periodic atoms grouped into
replicates)
♦ Save_Folder File
♦ Restore_Folder File

Using Parentheses
There is one additional syntax which is allowed in the specification
of the monomer/residue and atom portion of the object name.
This involves the use of parentheses to control the grouping of
atom references with monomers/residues. For example, suppose
that you want a command to refer to all of the alpha carbons of res-
idues in the range 1-40 and all of the beta carbons on ALA resi-
dues. If the object name is ABC then the specification:
ABC:(1-40:CA),ALA:CB
refers to these atoms in a single command. In general, you can use
parentheses to specify any valid monomer/residue and atom

58 Insight II/March 2000

 Object Names

combination which would ordinarily be allowed. Following the

parentheses you are allowed to put one final specification of
monomer/residue and atom. For the purposes of parsing the
name, the contents of the parentheses are treated as a monomer/
residue, and the comma which follows then separates it from the
following monomer/residue specification. After a comma, the
information in parentheses can be followed by another specifica-
tion enclosed in parentheses.

Wildcards
There are two types of wildcards which are valid in all portions of
the overall name. These are: the question mark (?), which matches
any single character; and the asterisk (*), which matches any num-
ber of characters. They may be combined to form several combina-
tions of matches. When a field is omitted, it is treated as if it
contained an *. Thus the name:
TEST::
is the same as:
TEST:*:*
Either expression specifies that all atoms of all monomers/resi-
dues of the object TEST are to be referenced.
Wildcards can be used in monomer/residue names and atom
names as well. For example, to refer to all monomers/residues in
the B chain of the object API, refer to:
API:B*
Experiment with the use of wildcards for the types of things you
like to do. It is the best way to get to know their power and limita-
tions.
Not all commands allow for wildcard specification. Which com-
mands allow wildcards, and in what context, is noted in each com-
mand’s online description. Generally, when you use a wildcard in
an invalid context, the program gives you an error message telling
you that the object name specified is invalid and why.

Insight II/March 2000 59

2. Introduction to Insight II

Properties
Visualization and analysis in molecular modeling is often a matter
of viewing or analyzing properties. Insight II provides a conve-
nient way to use these properties in a variety of ways, including
the ability to easily add your own properties using BCL or plug-
ins.
These properties are often properties of molecules, residues, or
atoms. For example, a property of a molecule is its mass. A prop-
erty of an amino acid residue is its hydrophobicity. A property of
an atom is its element type. Properties have a type and a class. The
type indicates the type of value for the property, which may be
float, integer, boolean, or string. For example, mass is a float, while
sequence number is an integer. The float and integer types are
referred to as scalar types since they are numerical and can be used
in arithmetic or used in conjunction with a spectrum object to indi-
cate a color. The display status of a molecule, which may either be
true or false, is an example of a boolean property, while the name
property of atoms is an example of a string property. The Custom/
List_properties command may be used to list the set of currently
defined properties.
Properties can be used in Insight II in a number of ways to help
you understand the system under study. For example:
♦ atoms, residues, or molecules may be labeled with property
values, thus attaching a small piece of text with the object.
♦ scalar properties may be used to color atoms or molecular sur-
faces according to a spectrum object
♦ atoms may be collected into subsets according to property val-
ues
♦ molecule spreadsheets can have property columns added to
them which display property values for each molecule in a list.
♦ property values may be queried in BCL scripts or spreadsheet
formulas
While MSI provides a pre-defined set of properties with Insight II,
it is easy to add your own properties using macros or “plug in”’s.

60 Insight II/March 2000

 Properties

See the BCL chapter for information on macro properties and the
Open Interface manual for information on plug ins.

Predefined Properties
The following table lists the predefined properties in Insight II
along with brief descriptions.

Property name (type)

Atom properties:
Partial_charge(float)
Formal_charge(string) The partial and formal charge on the
atom.
Chirality(string)
Chirality_R(string)
Chirality_S(string)
Prochirality(string)
Prochirality_R(string)
Prochirality_S(string) The various types of atom chirality.
Element(string) The name of the atom’s element.
Charge_group(string) The name of the charge group to which
the atom belongs.
Hetatm(boolean) True if the atom came from a PDB file
and was marked as a HETATM in that
file.
Hybrid(string) Hybridization.
Potential(string) Potential type.
Oop(string) Out-of-plane setting.
Switching(boolean) True if a switching atom for a charge
group.
Temp_factor(string) Temperature factor.
VDW_radius(float) Van der Waals radius, in angstroms.
Max_valence(float) The maximum valence for the atom.

Insight II/March 2000 61

2. Introduction to Insight II

Head_tail(string) If the atom is a head or tail atom for a

monomer (the attachment point for
chains of monomers) this string will con-
tain “head” or “tail”.
X_object(float)
Y_object(float)
Z_object(float) The x, y, and z coordinates of the atom in
the space of
its molecule.
X_world(float)
Y_world(float)
Z_world(float) The x, y, and z coordinates of the atom in
world space.
Name(string) The name of the atom.
Connection_count(integer) The number of bonds to the atom.
Mass(float) The mass of the atom.
Valence(float) The common valence for the atom.
Sequence_number(integer) The sequence number of the atom within
its molecule.
Sequence_in_monomer(integer)The sequence number of the atom within
its monomer.
Monomer properties:
Name(string) The name of the monomer. This is gener-
ally a number, although in multi-chain
proteins it often includes a chain letter.
Partial_charge(float) The sum of the partial charges of the
monomer’s atoms.
Type(string) The monomer type. For amino acids, this
is the name of the amino acid.
Type_1letter(string) For amino acids, the one letter abbrevia-
tion.
Atom_count(integer) The number of atoms in the monomer.
Mass(float) The sum of the masses of the atoms in the
monomer.

62 Insight II/March 2000

 Use of Color

Sequence_number(integer) The sequence number of the monomer

within the molecule.
Hydrophobicity(float) The hydrophobicity of the amino acid
monomer. This uses the Engleman-Steitz
scale.
Molecule properties:
Name(string) The name of the molecule.
Compound_name(string) If the molecule came from an MDL file
and a compound name was specified in
that file, this property will contain that
name.
Partial_charge(float) The sum of the partial charges on the
atoms of the molecule.
Mass(float) The molecular weight of the molecule.
Monomer_count(integer) The number of monomers in the mole-
cule.
Atom_count(integer) The number of atoms in the molecule.
Dials_connected(string) If the dials are connected to the object,
this will be “connected”; otherwise it will
be a blank string.
Displayed(string) If the object’s display status is on, this
will be “On”, otherwise it will be a blank
string.

Use of Color
The Insight II program allows you to set and change the colors for
atoms, entire objects, specific residues or monomers, surfaces, and
labels. In all of these cases you have three methods by which you
can specify the color:
1. By color name, using one of the six names which the program
recognizes.
2. By color number.

Insight II/March 2000 63

2. Introduction to Insight II

3. By RGB triplet.
Using methods 1 or 2, a color can be defined by a value from 0 to
360. The color names and their meanings are as follows:
Blue = 0 or 360
Magenta = 60
Red = 120
Yellow = 180
Green = 240
Cyan = 300
You are allowed, whenever a color is required, to specify one of the
names given above or a numerical value. The number must be an
integer in the range of 0 to 360, and where the number is not one
of the values listed above, corresponds to a blend of the colors
between which it lies.
In addition to the specification of color or hue, you are allowed to
specify, if you choose, a saturation value for the color. The hue is
the color quality of the picture. The saturation is the purity of the
color. A fully saturated color red is really red. A half-saturated red
is pink because the other half is white. All colors at zero saturation
are white. Use of both hue and saturation controls in the setting of
colors allows you to generate a virtually infinite variety of dis-
played colors on the screen.
Note that on an SGI, a total of 12 base colors can be simultaneously
displayed. These colors include the 7 pre-defined colors blue,
magenta, red, green, yellow, cyan, and white, and 5 user-defined
colors in color map mode. In RGB mode there are an unlimited
number of user colors, but if you switch back to color map mode
only 5 of those colors will remain.
To specify the saturation of a color, follow the color name or num-
ber with an open parenthesis, a value from 0.0 to 1.0, and a close
parenthesis. For example, to specify a pink color use:
red(0.5)
This syntax of color (saturation) is valid whenever a color is speci-
fied to the program. The default saturation, if none is given, is 1.0
which makes the color strong and pure.

64 Insight II/March 2000

 Use of Color

When specifying an RGB triplet, three color values representing

red, green, and blue must be specified and separated by commas.
Each of the color values may range from 0 to 255. For example:
255,0,0 represents red
0,255,0 represents green
0,0,255 represents blue
0,255,255 represents cyan
255,255,0 represents yellow
255,0,255 represents magenta
255,255,255 represents white
The RGB triplets are used when coloring with the color palette.

RGB vs. Color Table Mode

The Insight II program supports both RGB and color map modes.
The mode is selected using the RGB_Mode option in the Environ-
ment command under the Session pulldown in the Viewer mod-
ule. RGB mode is not available on 8-bit Personal Iris systems. In
RGB mode the red, green, and blue values are stored directly in the
frame buffer which drives the display. Some devices which do not
have a full 24 bits of color, such as the Indigo, do hardware level
“dithering”, where adjacent pixels are painted in slightly different
colors so that the result, when blended by the human eye, is
approximately the desired color. This can make the picture look
somewhat grainy, but otherwise works quite well. In color map
mode, the red, green, and blue values are stored in a color map and
an index into the color map is stored in the frame buffer.
The default mode for all 24-bit systems is RGB mode, and for all 8-
bit systems is color map. RGB mode provides a better lighting
model for solid surfaces, so CPK and solid contours look better in
RGB mode. However, anti-aliasing on Personal Iris systems
requires color map mode (i.e., RGB_Mode off).
Insight II on the Indigo also provides a Single_Buffer option in the
Environment command. This switches the hardware from 4-bit
double-buffered mode to 8-bit single-buffered mode. The picture
looks much better in the 8-bit mode, but flashes as it is moved. The
recommended use of this mode is to leave it off while positioning
the picture on the screen, and then turn Single_Buffer on to study
the picture more closely or take photographs.

Insight II/March 2000 65

2. Introduction to Insight II

Online Help

Insight II Help Viewer

The Insight II program provides a graphical online help facility,
the Insight II Help Viewer. This help viewer uses the X Window
system to display help for the Insight II program in a graphical,
easily accessed manner. Help for various topics can be displayed
by choosing items from pop-up menus. The Insight II Help Viewer
runs independently from the Insight II program, so you can con-
tinue to use the program while the help facility is executing.

Using the Insgiht II Help Viewer

The Insight II Help Viewer is accessed by picking the Help icon
from the icon palette (the icon with the question mark), by execut-
ing Session/Help or Help/Insight_Help, or by typing Help help
at the Insight II command prompt.
When the Insight II Help Viewer is invoked, a window appears
containing a menu bar, a set of navigational buttons, and the help
text viewing area.

Top Menu Bar: Options and Help Menus

Under the Options menu, five commands are available: Follow,
Go Forward, Go Backward, Print, and Quit Help. Note that key-
board accelerators to some of these commands are available.
Follow:
This command acts as a toggle to control whether the Insight II
Help Viewer follows the Insight II program. If on, help text is
displayed in the window whenever you choose a command
from within the Insight II program. For example, if you have
Follow turned on and you choose the Add command from the
Assembly pulldown (in the Insight II window), help text for
the Add command is automatically displayed in the Insight II
Help Viewer window.

66 Insight II/March 2000

 Online Help

Since the Insight II Help Viewer follows even while hidden,

you may want to toggle Follow off if you keep the help window
hidden for long periods so that no help processing occurs.
Go Forward, Go Backward:
These commands allow you to navigate through the history of
help text since the beginning of your Insight II session.
Print:
This command provides you access to a print dialog box. You
can choose a print command and set up print options, includ-
ing the amount of information to be printed.
Quit Help:
Activating this command causes the Insight II Help Viewer to
disappear. Picking the Help icon, executing the Session/Help
or Help/Insight_Help commands, or typing Help help at the
Insight II command prompt causes the window to reappear.

Navigational Buttons
These buttons are dynamically updated reflecting the hierar-
chical path to either the module, the menu, the command or the
parameter you are getting help for. Note that the right-most
button is a pulldown button. You can click on either of these
buttons to navigate through the entire hierarchy of Insight II
commands.

Help Text Viewing Area

The help text viewing area displays help for the selected topic.
If the amount of text exceeds the size of the widget, a scrollbar
is displayed at the right edge to permit you to scroll through the
text. Use the left mouse button for scrolling.

Insight II/March 2000 67

2. Introduction to Insight II

Figure 12. Example of Insight II Help Viewer Window

Pilot
Insight II Pilot is an electronic assistant which can provide interac-
tive training sessions and practical guidance for accomplishing a
variety of tasks. Using Pilot, the full functionality of the Insight II
modeling system can be navigated. Novice users can complete
practical modeling problems from the first time they use the pro-
gram. More experienced users will appreciate Pilot’s ability to
access the comprehensive capabilities of the fully integrated
Insight II software suite. Pick the large question mark at the bot-
tom of the Pilot window to access online help on Pilot itself,
including how to create or extend the exisitng tutorials.
Pilot provides a convenient means for organizing modeling infor-
mation and developing strategies. In-house modeling experts can
use Pilot as a convenient means of communicating modeling pro-
cedures or even demonstrating already-worked-out solutions for
internal customers.
An important part of MSI’s approach to online information is that
its interface should be intuitive, and self-documenting. Pilot is

68 Insight II/March 2000

 How Errors are Handled

consistent with this design goal. From the Insight II interface, click
the Pilot icon in the icon palette:

This opens the Pilot parameter block, where you can choose a
directory of Pilot log files. From the next window that opens,
choose any tutorial.
Pilot is designed to run in conjunction with Insight II. Starting
Insight II and then Pilot ensures that both programs work together.
It is possible to run Pilot separately, however. Enter pilot at a
UNIX prompt. This brings up the same Pilot windows as when
Pilot is started from within the Insight II interface.

How Errors are Handled

If you make an error, the Insight II program makes every effort to
detect the problem and handle it gracefully.

Errors in typed commands

Errors happen for a variety of reasons. The most common mistakes
are made while issuing a command. If you are typing in a com-
mand, you might spell the command name incorrectly. The offend-
ing name is enclosed in angle brackets, <>. At this point, you can
correct the mistake by retyping the name. Of course, it may be eas-
ier to start typing from scratch by first pressing the letter u while
holding down the <Ctrl> key.
Another common mistake is to give wrong parameters to a com-
mand. If you type the command, you might give too many param-
eters. This causes the extra parameters to be highlighted by
changing them to reverse video (white text against a black back-
ground). Again, you can retype to correct the mistake. If you give
too few parameter values in a typed command, you are prompted
for additional parameter values. If you misspell a parameter
value, the program may mistakenly assume you have entered too

Insight II/March 2000 69

2. Introduction to Insight II

few or too many parameters. In this case, you may receive a

prompt or part of the command may be colored red. The impor-
tant thing to remember is that if the command does not execute,
some kind of error was found and must be corrected.

Errors in menu -selected commands

By using the menu version of commands, you are less prone to
common errors. For example, you are not allowed to execute the
command if you have not filled in enough parameter values. And,
misspelling is less likely because you can use value-aids and can
pick objects from the screen or from a list to indicate your choices.
Better still, if you try to fill in a value that is inappropriate, the pro-
gram may be able to immediately draw your attention to the prob-
lem with a message.
Not all errors can be detected before a command is issued. For
example, you might give an integer parameter a negative number
where only a positive number is allowed. In this case, the Insight
II program might not recognize the problem in time to stop you
from executing the command. Note, however, that the program
keeps looking for illegal situations even after a command is issued.
In most cases, if it finds a problem while it is trying to complete a
command that has been issued, an error box containing red text
appears over the Insight II window. It contains a brief message
describing what has gone wrong. For all but the most severe
errors, you can select the <Explain> button within the error box.
This gives you a longer error message that describes the problem
in more detail. Note that errors are also echoed to the information
area of the window. You can get rid of the message windows by
clicking your mouse button anywhere, or by pressing any key.
In most cases, errors are not fatal and the Insight II program cleans
up sufficiently to allow you to continue your work. Often, this
means simply re-issuing the command with different (valid)
parameter values.
In some severe cases, the program does not allow you to continue
because internal data has been badly corrupted. In these situa-
tions, a diagnostic message is put out to the textport. Please make
a note of this message and contact MSI to report the problem. This
helps MSI to fix the problem for future releases.

70 Insight II/March 2000

 How Errors are Handled

There is one kind of severe error that can be triggered through no

fault of the software: running out of virtual memory. Like all soft-
ware packages, the Insight II program uses the computer’s virtual
memory. The amount of virtual computer memory varies depend-
ing on the size of the swap file at your site. If the program requires
more memory than is available, a severe error is produced. You
can recognize this kind of problem by a diagnostic message allud-
ing to memory_alloc, malloc, memory_free, free, or some other key-
word that corresponds to memory usage. If this type of error
occurs, kill the Insight II program session by killing the process or
quitting the graphics window by the usual operating system
methods. If you do not know how to do this, contact your system
manager or your MSI representative. Once you have completely
closed down the Insight II program, you may want to discuss the
problem with your system manager to see if more virtual memory
can be allocated on your computer.

Insight II/March 2000 71

2. Introduction to Insight II

72 Insight II/March 2000

3 Basic Applications

Insight II is accompanied by a set of tutorials demonstrating how

to use its basic features. The set of Insight II tutorials are organized
as applications, showing how to use Insight II to solve problems of
structure determination or ligand-receptor binding. Only the basic
tutorials for Insight II are included here. Tutorials for other prod-
ucts are described in the accompanying documentation for those
products.

Pilot online tutorials

Most tutorials for the Insight II program are available online for
use with the Pilot interface. To access the online tutorials, click the
mortarboard icon in the Insight interface.

Figure 13. The Pilot Button

There are various options for navigating through a Pilot tutorial

session, controlled by the icon buttons at the top of the Pilot win-
dow. The tutorials are set up like pages of a book. Each page con-
tains either text describing the processes involved in completing
the tutorial, or an Insight II command, or both. The filled forward
arrow can be used to step through the tutorial and, when there is
an Insight II command to be executed, automatically executes that
command. The next button to the right allows you to preview each

Insight II/March 2000 73

3. Basic Applications

command parameter block before it is executed The double filled

forward arrow executes all the commands for the entire lesson,
automatically paging through the tutorial as it does so. This could
be used as a quick and simple verification that a particular func-
tionality in Insight II has been installed correctly. The other two
buttons, outlined backward and forward buttons. allow you to
browse through the lesson without automatically executing and
Insight II commands. This is useful for new users in that it allows
them to navigate around the Insight II interface and learn where
all the pulldowns and commands are located, as well as for expe-
rienced users who just need to review some particular functional-
ity with Insight II. A brief description of the function of each
button pops up as a screen tip when the mouse cursor is placed
over the button (flyover help). The several icon buttons at the bot-
tom of the Pilot window provide additional functionality: opening
additional Pilot lessons, resetting the current session to the begin-
ning, deleting everything currently displayed in the Insight II win-
dow, toggling Insight II to full-screen mode, changing some of the
Pilot options, bringing up Pilot’s online help, printing the current
lesson, and quitting the Pilot window.

Example
Choose “Select this to see a list of the available online tutorials”
from the list that appears (it takes a few moments). Choose
“Insight II tutorials” from the next list which appears, then select
the desired tutorial. The Pilot window displays a narration for an
Insight II session and automatically executes Insight II commands
at each step of the narration. To proceed to the next step of the tuto-
rial, press the forward button.

Figure 14. The Forward Button

Pilot then displays the narration for the next step in the tutorial.
Note that with Pilot, the commands are executed for you automat-

74 Insight II/March 2000

 Choosing a tutorial

ically at each step. You can use Insight II while reviewing a Pilot
script, however. In this way you can experiment with the com-
mands that are being demonstrated.

Choosing a tutorial
From the Open Tutorial window, select Insight II tutorials (and, if
necessary, the module) and choose from the list of available les-
sons.
Application 1 Getting Started with Insight II
Application 2 Building Molecules (HARDCOPY ONLY; see Sketcher,
page 175)
Application 3 Docking 2 Molecules
Application 4 Superimposition
Application 5 Molecular Orbital Calculations
Application 6 Importing Structures
Application 7 Exporting & Printing Graphics from Insight II
Application 8 Conformational Search by Torsion Driving
Application 9 Conformational Search Using Molecular Mechanics
Application 10 Restrained Molecular Dynamics
Application 11 Cluster Analysis of a Dynamics Simulation
Application 12 Template Forcing

ALSO:
Viewer Module: Use of Insight II Viewer Commands
Ampac/Mopac Module: Use of AMPAC/MOPAC through Insight II
Docking Module: Simulation Trajectory Analysis Tutorials
Graph Pulldown: Use of General Graphing Tools within Insight II

You can access the Open Tutorial window at any time by clicking
the Open File button in the lower left corner of the Pilot window.
For a more complete description of Pilot and its use, click the
online help button in the Pilot interface or refer to Introduction to
Insight II.

Insight II/March 2000 75

3. Basic Applications

76 Insight II/March 2000

4 Viewer Module

The Insight II program’s most frequently used commands are in

every module, grouped into the pulldowns listed in the top menu
bar. These commands comprise the Insight II program core, and
are collectively referred to as the Viewer module.
The lower menu bar includes pulldowns with application-specific
commands restricted to certain modules. To access these pull-
downs and commands, pick the Modules icon (the MSI logo in the
top corner of the program window), then select a module of inter-
est.
Certain pulldowns and commands can be accessed by picking
icons from the icon palette. The icons can provide quick access to
pulldowns and commands from any module. By default, the icons
are set to access primarily Viewer-module functionality. However,
you can customize the icons to access any commands that you
choose. Refer to the Icon information in Chapter 1, Introduction.

Implementation

Window Layouts
During the course of a session using the Insight II program it is
common to create and interact with several application windows
simultaneously. The main window and Spreadsheet windows are
two examples. Since these windows are all independent windows
you can manage your workstation screen space by raising, lower-
ing, moving, resizing, and iconifying the windows with the win-
dow manager. However, it is often the case that several of the
windows are related, and it may be convenient to be able to per-
form these window manager type activities on all of the windows
at once.

Insight II/March 2000 77

4. Viewer Module

The Insight II program provides this capability through the use of

window layouts. A window layout is an abstraction which orga-
nizes a set of windows so that they can be raised, lowered, resized,
moved, and iconified as a single unit. The layout consists of two
parts: the layout template, and a list of windows to manage. Note
that the command summaries of the Layout_Template Window
and the Layout Window commands, later in this chapter, may also
be useful when working with layouts.
The layout template does not refer to specific windows, but rather
contains a set of entries each of which describes the position of a
window relative to the whole template. This position is described
as the position of the left, right, top, and bottom edges of the win-
dow as a percentage of the entire layout size. For example, a layout
template might specify a layout of three windows as shown below.
The left (l), right (r), top (t), and bottom (b) values of each of the
three entries are shown on the diagram.

entry 1 entry 2

t=0 t=0

l=0 r=50 l=50 r=100

b=67 b=67
t=67

l=0 r=100

b=100
entry 3

As mentioned above, a layout also contains a list of application

windows that are managed by the layout. As each application
window is added to the layout it is placed in the position specified
by the next available template entry. In the diagram above, the first

78 Insight II/March 2000

 Implementation

window added to the layout would occupy the upper left position,
the next window would be placed in the upper right, and the third
window would go below the other two.
Note that since the order in which the windows occur in the layout
determines which template entry is used, if a window is removed
from the layout, the other windows rearrange so that no template
entries are skipped. For example, if a layout contained three win-
dows (w1, w2, w3) and the layout template above, then initially
w1 would be in the location described by entry 1, w2 in entry 2,
and w3 in entry3. If w2 were then removed from the layout, w3
would now be the second window in the layout, so it would move
into the position specified by entry 2. Since the edges of each entry
are given as percentages, they do not directly specify the actual
size of the whole layout. To do so, one of the windows must be des-
ignated as the control window for the layout. The size and position
of the layout are then computed based on the size and position of
the control window. As this window is moved and resized, the rest
of the windows are automatically updated to satisfy the layout
template. By default, the first window in the layout is the control
window. However, any window can be designated as the control
window by using the Apply option of the Window/Layout com-
mand. By turning off the Use_Control_Window option in that
command, you may choose not to use a control window, in which
case the windows all move and resize independently. A special
string (“ - Controls layout NAME”) is appended on the window
name in the window title bar to identify the current control win-
dow.
To create a window layout you must first have some secondary
windows to be managed by the layout. Then go to the Window/
Layout command and select the Use_Template option. Enter a
unique name for the Layout_Name parameter, and then choose an
existing layout from the Layout_Templates value-aid to fill in the
Layout_Template_Nam parameter. This defines the layout tem-
plate to be used. Next select the Add_Window option, and choose
a window from the Window_List value-aid to fill in the Window_
Name parameter. Repeat this action once for each window to be
managed by the layout. When you add the first window, the only
change you should see is that the title bar of the window should
change to indicate that it is the control window. As each of the
other windows is added, the window size and location should
change to fit the layout template.

Insight II/March 2000 79

4. Viewer Module

To change the control window simply select the Apply option,

turn Use_Control_Window on and select a new window.
There are a couple of default layout templates which are read in on
system startup, but the most common way to use layouts is to cre-
ate them yourself using window arrangements that you prefer. To
define a new layout template, simply set up the windows in the
desired sizes and locations using the window manager. Then add
all of the windows to the layout as described above using a new
layout name. Note that in this case you do not have to have a lay-
out template defined for the layout. Then go to the Window/
Layout_Template command, and select the Create option. Make
sure that the Layout_Name is the name used when adding the
windows, and enter a new, unique name for Layout_Template_
Nam. This creates a new layout template with one entry for each
of the windows in the layout.
You can then write this layout template out to a file so that it may
be used again in the future. To do so, select the Put option, and
enter a filename (you do not need to add the default extension of
.ltpl). This, or any other layout template file may be read in with
the Get option of the Window/Layout_Template command. If you
want to use this layout template regularly, you may add it to the
system layout template file described in the File Formats section,
Appendix B.

Spreadsheet Introduction
The Insight II molecular modeling program includes an integrated
spreadsheet. This can be used to view various properties of struc-
tures in a tabular form.
The Insight II program’s spreadsheet is a fully functional spread-
sheet with the ability to view textual and numerical data. The
numerical data may be calculated and can be derived from formu-
las or from other data in the spreadsheet. The spreadsheet includes
features such as cut and paste, dynamic calculation of arithmetic
expressions and functions, references to cells, and data plotting. In
addition, spreadsheets are integrated into the Insight II program
environment in the following ways:
♦ Spreadsheets may be created which display tabular data for the
structure being modeled. The Molecule/Tabulate command

80 Insight II/March 2000

 Implementation

creates a spreadsheet which lists various properties of the

selected molecule. The Trajectory/Tabulate (in the Analysis
module) or the Configurations/Tabulate command may be
used to create a spreadsheet which lists properties of the frames
of the current trajectory.
♦ The Search command may be used to extract atoms of interest.
The results of the search may then be used as input to subse-
quent commands which act on atoms to only affect the atoms
which met the criteria of the search.
♦ A trajectory spreadsheet may be used to browse through sets of
conformations. By simply selecting a conformation with a
mouse click and pressing the conformation button, the display
of the molecule will adopt the geometry of the selected con-
former.
♦ Functions are provided which return values of chemical inter-
est, for example the distance between a pair of atoms.

Insight II/March 2000 81

4. Viewer Module

Figure 15. Spreadsheet

Creating a Spreadsheet
Spreadsheets may be created in one of three ways:
1. The New command under the Spreadsheet icon can be used to
create a blank spreadsheet, which may be edited to enter data.
The spreadsheet appears in a separate window from the main
window of the Insight II program, thus making it possible to
arrange it on the screen independently of the main window (see

82 Insight II/March 2000

 Implementation

the Window Layouts section for more information about man-

aging windows).
2. Use the Molecule/Tabulate or Trajectory/Tabulate command
to produce a spreadsheet which contains data regarding the
object under study. These commands offer various options
which make it possible to select which properties are listed in
the spreadsheet.
3. Use the Open command under the Spreadsheet icon to import
data from a text file. This makes it possible to bring data into a
spreadsheet which was created by another program. The text
option to this command specifies that columns within the text
file are delimited by tab characters. The graph option to this
command specifies that columns within the text file are delim-
ited by space characters (the convention used by the Put Graph
command).

Modifying the Spreadsheet Layout

Once a spreadsheet has been created, the appearance may be mod-
ified in a number of ways to tailor the appearance of the data
within it. Among the display characteristics which may be modi-
fied with the commands of the Format pulldown are the colors of
the cells, the numerical formatting and alignment of the data, and
the display of cell borders.

Manipulating Spreadsheet Data

The data within a spreadsheet may be treated as a small database
by the use of the Sort and Search commands. With the Sort com-
mand, you may order the rows of the spreadsheet based on the
numerical data in a specified column. With the Search command,
rows which meet certain criteria may be selected. In the case of a
spreadsheet which was created with the Tabulate Molecule com-
mand, the atoms of the selected rows may then be used as input to
subsequent commands which operate on atoms.

Displaying Spreadsheet Data

In addition to viewing the data within the spreadsheet in a tabular
form, you may plot the data as graphs using the commands of the

Insight II/March 2000 83

4. Viewer Module

Plot menu or the command buttons at the bottom of the spread-

sheet window.

Using the Spreadsheet

Spreadsheets have a number of associated commands which are
accessed via the pulldown menus at the top of the spreadsheet
window. In addition, there are a number of interactions which take
place directly with the spreadsheet, such as selection with the
mouse, data value editing, and command buttons. Summaries of
each available command are provided in the Command Summary
section later in this chapter.

Selection Many spreadsheet commands operate on a cell. To

specify a cell on which to operate, select the cell before issuing the
command. Selection of a single cell is accomplished by clicking the
mouse button on the cell. A bold outline around the cell is dis-
played to highlight the selected cell.
Most spreadsheet commands can operate on multiple cells. Selec-
tion of multiple cells can be performed in a number of ways. The
simplest is to click and drag over a rectangular area of the spread-
sheet: this selects the cells within the rectangle. These are dis-
played with a black background to indicate they are selected. A
selection may be extended to a larger rectangle by clicking the
mouse button while holding down the shift key. This extends the
current selection to the newly selected cell. A discontiguous selec-
tion may be created by clicking/dragging over a region while
holding down the control key. In this case the current selection
remains, and an additional selection region is created. Entire rows
or columns may be selected by clicking on the row or column
header.

Data Value Editing

Expressions
Data values may be entered into cells by creating a spreadsheet
with the Tabulate commands or by importing a text file, but it is
often useful to interactively edit the values by typing in strings,
numbers, arithmetic expressions, and formulas. These data values
may be literal, in which case the text which is typed in is displayed
in the cell, or they may be an expression which is calculated, in
which case the results of the calculation are displayed in the cell.

84 Insight II/March 2000

 Implementation

To enter a data value, select the cell to be edited as described

above, then type in the data value while the mouse is in the win-
dow of the spreadsheet to be edited. The text is displayed in the
text widget near the top of the window as you type it in.
To enter an expression, type in an equal sign (=) as the first charac-
ter. The expression may consist of numbers, cell references, or for-
mulas. These may be combined with the following arithmetic
operators: +(addition), -(subtraction), /(division), *(multiplica-
tion), %(modulus), and ^(power). Parentheses may be used to log-
ically group subexpressions.
Numbers may be entered literally, either as integers or floating-
point numbers. Cell references may be entered by typing in the
column letter followed by the row number, for example B6, or by
clicking on the cell to be referenced. Formulas may be used in
expressions to concisely use complex calculations within an
expression.
Formulas
Formulas are indicated by entering the name of the formula fol-
lowed by the input value(s), delimited by parentheses. Here is an
example of an expression which uses a number, a cell reference,
and a formula: = 2 + B6 + cos(45)
Formulas come in five categories: trigonometric, general math,
tables, molecule geometry, and user-defined.
The trigonometric formulas take a single input value and include
the following: cos, sin, tab, asin, acos, atan, sinh, cosh, tanh. The
units are degrees. The constants PI, DEGTORAD, and RADTO-
DEG are provided for use with these formulas.
The general math formulas include: log (natural log), log10 (log,
base 10), sqrt (square root), and abs (absolute value).
The table formulas include sum(a1..a3) to compute sums of cell
values, and avg(a1..a3) to compute average cell values. For exam-
ple, =avg(A1..A10) computes the average value of the column of
cells from A1 to A10.
The molecule geometry formulas include dist(atom1, atom2),
ang(atom1, atom2, atom3), and dihedral(atom1, atom2, atom3,
atom4) to compute intramolecular distance, angle, and dihedral,
respectively. The input to these formulas is atom specifications of

Insight II/March 2000 85

4. Viewer Module

the usual Insight II type. Surround each specification with double

quotes. For example: =dist(“CRN:1:CA”,”CRN:10:N”). Note that
the geometry values that are displayed in the spreadsheet by these
formulas are automatically updated as the geometry of the mole-
cule is modified by operations such as torsions and simulation ani-
mation.
User-defined formulas are formulas which you create to augment
those listed above. User-defined formulas are BCL macros (See the
BCL chapter to learn how to write BCL macros). You create them
like any other BCL macro and refer to them by name as if they
were any other formula. Currently, user-defined macros must
return a value of the type “float”.

Cell References Expressions may contain references to other

cells, in which case the reference is replaced by the value of the ref-
erenced cell at the time it is calculated. Cell references may be
entered by typing in the column letter followed by the row num-
ber, for example B6, or by clicking on the cell to be referenced. By
default, references are relative to the current cell. If rows or col-
umns are inserted, the reference is updated to reflect the addition
or deletion of rows or columns. If you wish a reference to be con-
stant, that is, have it remain unchanged when cells are moved, pre-
cede the row, column, or both, by a dollar sign ($). For example: =
2 * $B$6

Command Summary
The top menu bar consists of pulldowns which access the core
commands. The pulldowns are Module, Session, File, Object,
Molecule, Measure, Transform, Subset, Assembly, User, Spec-
trum, Custom, Window, and Help In addition, this section con-
tains summaries of the commands available when you pick the
Contour icon, and the Spreadsheet icon, including the commands
available only within the Spreadsheet window.

86 Insight II/March 2000

 Command Summary

Module Pulldown (MSI logo icon)

The Module pulldown contains commands that you use to switch
from one module to another. This pulldown is accessed by picking
the MSI logo in the top corner of the Insight II program’s window,
and contains the names of available modules. The contents of this
pulldown depend on the software configuration at your particular
site.
With the exception of Licenses, selecting any of the commands in
this pulldown causes additional pulldowns containing the com-
mands which are specific to that module to be added to the lower
of the two menu bars.

Builder
The Builder command activates the Builder module. This module
allows you to construct new molecules from molecular fragments
or individual atoms. It also allows you to modify such properties
as atom type, hybridization, potential function parameters, bond
order, and geometry of existing molecules. You can use the newly
created or modified molecules in all of the normal ways through-
out Insight II.

Biopolymer
The Biopolymer command activates the Biopolymer module. The
commands in this module facilitate the building and modification
of peptides, proteins, polynucleic acids, and carbohydrates. In par-
ticular the peptide commands can be used to: build up peptide
sequences while imposing secondary structure, delete or replace
residues in peptides and proteins, impose secondary structure on
existing peptides and proteins, and change N and C terminal cap-
ping groups. Other commands in this module allow you to search
a database for, and display regions of, proteins which meet a given
geometric criterion. The nucleic acid commands can be used to:
build single, double, or triple-stranded polynucleotides in A, B, or
Z form; delete or replace nucleotides in strands, measure angles
and distances between bases, and cap a prime or ligate strand. The
carbohydrate commands can be used to link monosaccharides in a
number of ways and to change the enantiomer or anomer of a
monosaccharide within a molecule. This module includes access

Insight II/March 2000 87

4. Viewer Module

to many of the commands from the Builder module, allowing you

to perform builder functionality while in the Biopolymer module.

DelPhi
The DelPhi module has commands to define DelPhi calculation
parameters (Setup), perform a DelPhi calculation (Run_DelPhi),
analyze the results (Potential), and create charge and radius tem-
plates (Templates). DelPhi itself is a software package which cal-
culates the electrostatic potential in and around macro-molecules,
using a finite difference solution to the Poisson-Boltzmann equa-
tion. The program allows specification of ionic strength as well as
dielectric constants of both the solvent and the molecule of inter-
est. In addition, periodic boundary conditions may be used for
molecules or systems with repetitive portions, such as nucleic
acids.

Solvation
The Solvation module has been implemented in order to simplify
and speed up calculating the solvation energy using DelPhi. It
involves one or two DelPhi runs (based on the parameter set—
CFF91, PARSE—used), a Discover run for calculating the intramo-
lecular energy, and a calculation of the total accessible solvent area.
In addition, this module provides several other simple solvation
models. Finally, a separate option to calculate the total solvent
accessible surface area, using current Insight II atomic radii, is also
provided.

Discover
The Discover module provides an interface to the Discover pro-
gram. The interface allows for the definition of minimization and
dynamics calculations. You can perform simulations using various
forms of constraints and restraints, including template forcing,
torsion forcing, tethering, and NOE. This module also enables you
to do free energy calculations, and provides options for querying
ongoing jobs.

Discover_3
The Discover_3 module provides an interface to the Discover 3.0
program by enabling you to specify molecular mechanics simula-

88 Insight II/March 2000

 Command Summary

tions using that program. It also provides basic options for query-
ing ongoing jobs. The interface allows for the definition of
minimization and dynamics calculations.

Docking
The Docking module provides facilities for calculating the non-
bond energy between two molecules using explicit van der Waals
energy, explicit electrostatic (Coulombic) energy, or the combina-
tion of van der Waals and electrostatic energies. The number of
atoms included in the calculation can be limited by specifying a
monomer- or residue-based cutoff. Alternatively, the computation
can be done approximately, using a precomputed energy grid.

MCSS
The MCSS command activates the Multiple Copy Simultaneous
Search (MCSS) module. The MCSS module predicts ligand bind-
ing affinities by flooding the active site of a target macromolecule
with thousands of non-interacting copies of the ligand. The copies
are minimized and sorted in the active site, leading to a reduced
number of highly optimized candidate ligands. The candidates
can then be analyzed and clustered using additional commands
available in the MCSS module.
The MCSS module provides functionality for defining and visual-
izing the active site, defining all MCSS simulation parameters, and
analyzing the results of an MCSS simulation.

Ludi
The Ludi module provides functionality to help you design candi-
date ligands.

Search_Compare
The Search_Compare module provides functionality for calculat-
ing molecular volumes, performing boolean volumetric opera-
tions, constructing vector maps, and for performing systematic
conformational searches.

Insight II/March 2000 89

4. Viewer Module

CHARMm
The CHARMm module provides an interface to the CHARMm
program, from which you specify molecular mechanics simula-
tions using that program. The interface allows for the definition of
minimization and dynamics calculations.

MBOND
The MBOND module provides an interface to the MBOND pro-
gram, allowing you to specify molecular mechanics simulations
using that program. The interface allows for the definition of min-
imization and dynamics calculations.

Homology
The Homology module contains commands to help build a model
of a protein given only its amino acid sequence and the three-
dimensional structure of at least one other protein. Facilities are
provided to find related proteins, to find regions of structural con-
servation among related proteins, to align amino acid sequences,
and to assign coordinates based on these alignments.

NMR_Refine
The NMR_Refine module is a structure determination module
that uses data from Nuclear Magnetic Resonance to determine the
structure of a molecule. The module includes IRMA (Iterative
Relaxation Matrix Approach) to refine restraints, DGII (Distance
Geometry), SA (Simulated Annealing in Discover) to help predict
structure, and tools to access the programs XPLOR and Felix.

Xsight
The Xsight module contains a comprehensive set of commands for
performing all aspects of macromolecular crystallography.

Binding Site
The Binding_Site module contains methods to characterize a pro-
tein binding site of active site.

90 Insight II/March 2000

 Command Summary

Ampac/Mopac
The Ampac/Mopac module provides an interface to the public
domain AMPAC and MOPAC programs, which provide a semi-
empirical solution to electron configuration problems. These pro-
grams can be used to predict such properties as electron distribu-
tion and partial charges. They can also be used to optimize small
molecule conformations, create contours showing electron config-
urations, and perform various other calculations. You can also run
AMPAC and MOPAC from the operating system level.

DMol
The DMol module provides an interface to DMol, a local density
functional quantum chemistry program. The module provides
options for choosing the type of calculation (e.g., energy, minimi-
zation, frequency), setting input parameters, and determining out-
put quantities from the DMol calculation. It also provides the
capability to restart energy and/or minimization calculations
from previous results, and to launch DMol jobs on remote hosts.
Molecular orbital, density, and other volumetric output from
DMol may be contoured and viewed from within this module.

Turbomole
The Turbomole module provides an interface to Turbomole, a pro-
gram for ab initio and Gaussian-based density function quantum
chemistry.

Zindo
Zindo is comprehensive semi-empirical SCF/CI program. It has
many options, offering RHF, UHF, UHFA, and ROHF SCF calcula-
tions; energy, geometry, and CI options; and EHT, CNDO, INDO,
NDDO, and PPP methods.

QuanteMM
The QuanteMM command activates the QuanteMM module.
This module combines functionalities of the quantum mechanical
programs MOPAC, Turbomole, and DMol with the capabilities of
the molecular mechanics program Discover to perform calcula-
tions where a molecule, described by a quantum mechanical

Insight II/March 2000 91

4. Viewer Module

method, is embedded into an environment described by a classical

mechanical method.

Analysis
The Analysis module is used to perform molecular conformation
analysis. This module provides functionality for analyzing the tra-
jectory data output by the molecular mechanics program Discover
(separately licensed from MSI). This functionality may also be
used to analyze conformational data produced by other molecular
mechanics programs, or by any other method, provided the data
is formatted in a file type recognizable by Insight II.
The analysis is performed by defining properties of interest, iden-
tifying the atoms that uniquely define the property, and then
graphing or tabulating those properties against each other. Four
types of properties are available for analysis: total energy, time,
distance (including point-plane), and periodic (angles, dihedral
angles, and plane-plane angles).

DeCipher
The DeCipher command activates the DeCipher module, which is
used to perform molecular conformation analysis. This module
provides functionality for analyzing the configuration data output
by the molecular mechanics program Discover, separately licensed
from MSI. This functionality may also be used to analyze confor-
mational data produced by other molecular mechanics programs,
or by any other method, provided the data is formatted in a file
type recognizable by Insight II.
The analysis is performed by defining properties of interest, iden-
tifying the atoms that uniquely define the property, and then
graphing or tabulating those properties against each other.

Licenses
The Licenses command lists all licenses that can be checked out or
checked in interactively during the Insight II session. There are
other licenses, such as License_Holder, that will be listed in your
license file but cannot be explicitly checked out/in. These do not
show up in this command.

92 Insight II/March 2000

 Command Summary

In general a checked box indicates that you have access, and an

unchecked box means that you do not. Any license you have
immediate access to is listed as a filled box. For some licenses, a
limited number of users are allowed. In these cases, a user may
want to uncheck a box in order to allow another user access to a
particular license.
Those licenses which are currently checked out are displayed as
ON; all others are displayed as OFF. Since an Insight II license is
required to run Insight II, and since other licenses are required to
run certain modules within Insight II, you may be unable to check
back in a license. If so, you are notified in the Information window.
Also note that licenses are checked out automatically as you access
parts of Insight II. You do not need to check in these licenses; they
are automatically checked in when you Quit Insight II. But, you
can check them in if you wish.
Bundles are special licenses which grant you access to the same
software as would a set of individual licenses. They are used to
simplify distribution of license files — by reducing the number of
lines in the average license file.
You can list the individual licenses (also called features) in a par-
ticular bundle by using the License Action parameter.
For any license, whether you have it checked out or not, you can
list the users of this license by using the List_Users option of the
License Action parameter. This listing is not generated if the fea-
ture selected allows an unlimited number of simultaneous users.

Session Pulldown
The Session pulldown contains commands to customize the cur-
rent Insight II session. Session commands also provide access to
Insight II’s comprehensive online help utility, allow you to exit
temporarily or permanently to the operating system, and replay
Insight II command scripts. Session commands, such as changing
the background color of the graphics window, do not impact the
contents of files created later using Save or Put.

Insight II/March 2000 93

4. Viewer Module

Environment
The Environment command allows you to customize the environ-
ment of your current Insight II session. The features that you can
control include the following:
Anti_alias in conjunction with the Antialiasing parameter
enables or disables anti-aliasing. When Antialiasing is On, lines
and curves appear smoother than when this feature is Off. How-
ever, when Antialiasing is On screen refreshes are somewhat
slower.
RGB_Mode in conjunction with the RGBmode parameter allows
you to change whether Insight II runs in colormap mode, or rgb
mode. Each mode has advantages and disadvantages depending
on which model of workstation you are using. Rgb mode generally
allows more colors and higher quality cpks to be displayed, but
may impact graphics performance. Colormap mode draws the
fastest anti-aliased lines on most platforms but limits the number
of simultaneously displayed colors. The default varies according
to the model of your workstation.
Single_buffer in conjunction with the Singlebuffering parameter
allows you to control whether Insight II runs in single or double
buffer mode. Double buffer mode is the default. When in rgb mode
on some eight-bit graphics board workstations such as the SGI
Indigo, turning on single buffering improves the sharpness and
detail of the image at the expense of the screen flashing during
redraws.
Render_in_Motion in conjunction with the Render_Quality
parameter allows control over how certain types of renderings
such as CPKs, solid ribbons, and solid contours are drawn when
they are being moved via the mouse or dials. When Render_Qual-
ity is set to Fast_Render various simplified representations are
used to give faster drawing performance while in motion.
Background in conjunction with the Background Color parame-
ter allows you to change the color of the graphics window. By
default, background color is BLACK.
Auto_World in conjunction with the Autoworlding parameter
enables or disables the automatic addition of newly created objects
to the WORLD assembly. The WORLD assembly is an internally-
maintained assembly object that normally is the assemblage of all

94 Insight II/March 2000

 Command Summary

objects. It is used with such commands as Connect to allow you to

rotate, translate, and scale all objects at once. If you do not want
newly created objects added to the WORLD assembly, then turn
this feature Off.
Default_CMD_Object in conjunction with the CMD Object
Scope and Command Object parameters allows you to specify a
default command object. Normally, when typing commands con-
tained in pulldowns you must specify both the name of the com-
mand and the name of the pulldown. For example:
Typed: Get Molecule PDB pdb1crn.ent crn
where the name of the command is Get and the name of the pull-
down is Molecule. However, you may specify a default pulldown.
If, for example, Molecule is specified as the default pulldown, you
could issue the command:
Typed: Get PDB pdb1crn.ent crn
and the word Molecule is implied by default. There are two kinds
of defaults which may be specified. One that you can specify is a
default pulldown on a per-module basis. For example, Molecule
could be the default pulldown for the Viewer module, while
Graph could be the default pulldown for the Analysis module.
The other default that you can specify is a default global pull-
down. A default global pulldown affects those modules that do
not have a per-module default assigned.
Energy_Timeout in conjunction with the Energy Timeout param-
eter allows you to specify how frequently van der Waals overlap
or non-bond energies are calculated in monitor mode. The default
is every 0.0 seconds. This value has the effect of performing the cal-
culation when the mouse button is released.
Random_Number_Seed in conjunction with the Seed Num
parameter initializes the random number generators with the
specified seed. This is particularly useful when log or restart files
are used to reproduce a particular set of results or simulation.

Light_Source
The Light_Source command is used to set the apparent direction
to the light source in an Insight II graphics window. The objects

Insight II/March 2000 95

4. Viewer Module

affected by lighting are mostly those drawn as filled polygons such

as CPKs, solid ribbons, and solid contours.
This command allows interactive adjustment of the light source
using the mouse. When the Light_Source command is active and
the Direction To Light parameter selected, the inking cursor (a
small pencil) replaces the normal pointer cursor indicating that
inking is active. Moving the cursor out into the graphics area of the
Insight II window and depressing the pick mouse button initiates
interactive light source positioning. While the mouse button is
held down a red circle is drawn indicating the extents of a virtual
sphere upon which the light source position is set. Moving the
mouse while holding the button down adjusts this position and
updates the Direction To Light parameter accordingly. Moving
outside the circle makes the K component of the Direction To
Light zero, effectively placing the light source in the plane of the
screen. The light cannot be positioned behind the object (K < 0.0)
using the interactive interface.

Cmd_Display
The Cmd_Display command gives you control over the display of
inactive parameters in the Insight II program’s command parame-
ter blocks. If you choose to show all parameters, then both active
and inactive parameters are displayed in parameter blocks. Inac-
tive parameters are displayed in gray and do not respond to user
input.
If you choose not to show all parameters, then only active param-
eters are displayed. The parameter block adjusts its size to accom-
modate all the active parameters at any given time.
Use the Single_Column_CMDs parameter to control the display
of parameters in commands with only one column of parameters.
Use the Multi_Column_CMDs parameter to control the display
of parameters in commands with more than one column of param-
eters.

Help
The Help command allows you to access the Insight II program’s
comprehensive on-line help facility. On-line help contains infor-
mation on every Insight II module, pulldown, command, and
parameter, as well as actual command examples. To access help,

96 Insight II/March 2000

 Command Summary

select the Help command in the Session pulldown, type the com-
mand help on the command line, or press the on-line help icon
(the question mark button in the icon palette).
Parameters are available to specify at which level you wish to
enter the help library.

Autosave
The Autosave command is used to control automatic saving of
objects in the current Insight II session. When Insight II first comes
up, automatic saving of objects is disabled. Autosave is used to
turn on or off the feature and specify the interval between saves.

Backup
The Backup command is used to save objects to the Insight II ses-
sion folder, .insight_session.psv, located in the directory where
Insight II was first started. A new file is created each time Backup
is executed or the operation is invoked via the autosave mecha-
nism.

Recover
The Recover command is used to restore objects from the folder
created with the Backup command or the periodic autosave oper-
ation controlled by the Autosave command. Delete * is executed
first.

History
The History command displays the commands in the current ses-
sion’s history buffer. By knowing the number of a command, you
may recall it by preceding the number with an exclamation point.
For example, !-7 recalls the seventh command counting from the
last command that was executed.

Buffer
The Buffer command controls the number of commands stored in
the current session’s history buffer.

Insight II/March 2000 97

4. Viewer Module

Alias
The Alias command in the Session pulldown allows you to create
and delete aliases. An alias is a custom notation for a command.
You can use an alias to give a command a more meaningful name,
or to shorten a frequently typed command string. This command
is used to create new aliases or to delete previously defined aliases.
Note that Alias remains active only at the token level. A valid alias
token must be surrounded by white space, and it cannot be part of
another token. For example:

> alias create list 1,3,5

> color ca:list green

In this case, the string "list" is not replaced with the alias value 1,3,5
because the string is part of another token.

> alias create list ca:1,3,5

> color list green

These commands color ca:1, ca:3, and ca:5 green because here "list"
is a single token surrounded by white space.
Note that aliases may be used anywhere in a command as long as
they are separated from the rest of the command with blanks.
Because alias token substitution applies to all command tokens, it
is necessary to place a backslash (\) in front of the existing token
in order to:

1. define an alias using an existing alias name.

2.use the alias name itself as a value, instead of the

value represented by the alias.
For example, to create an alias named Exit, which is equivalent to
the command Quit:

> Alias Create Exit Quit

To redefine the alias token Exit, when the alias Exit already exists:

> Alias Create \Exit Done

98 Insight II/March 2000

 Command Summary

This command redefines the alias token Exit to have the value
Done. If the backslash is not present, then the command:

> Alias Create Exit Done

first replaces Exit with Quit, and then defines an alias Quit to be
equivalent to Done.
A backslash is also required in order to use Exit as a value in a
command:

> Sample_command Sample_object \Exit

Here, the parameter value Exit is passed on to the command. If the

backslash (\) is omitted, then the command:

> Sample_command Sample_object Exit

results in the value Quit being passed in.

Button
The Button command is used to maintain the text associated with
the buttons on the optional button box peripheral. It provides the
ability to associate text with a button, clear the text associated with
a button, and list the text associated with buttons. The text can be
set to execute as a concurrent command. Once text is associated
with a button, that text is output, exactly as if it had been typed,
when the button is pressed. This makes buttons useful for holding
frequently used commands or parameters.

Stereo
The Stereo command provides a stereo view of the object or
objects in the graphics window. You are given the option of chang-
ing the stereo angle (the angle between the views) no matter what
type of stereo is being utilized. There are two types of stereo avail-
able: Hardware Stereo and Software Stereo.
The Software Stereo command creates split stereo pairs, and you
are required to cross your eyes slightly to see the stereo effect.
The Hardware Stereo command is intended for SGI systems
equipped with special stereo hardware. If you have StereoView
hardware, which utilizes an emitter and special glasses, then the

Insight II/March 2000 99

4. Viewer Module

environment variable STEREO_TRIGGER must be set. Users with

Stereographics or Tektronix stereo hardware, with an external
switch to change the monitor to stereo mode, should NOT define
the STEREO_TRIGGER environment variable. The STEREO_
TRIGGER variable is defined when the software is installed, but
can be changed at any time.

Env_var
The Env_var command allows you to access environment vari-
ables from within the Insight II program.

Unix
The Unix command allows you to issue commands to the operat-
ing system without leaving the Insight II program. You can enter
any valid UNIX command, including one that starts up a shell ses-
sion. To exit a shell session and return to Insight II, type exit or
press <control>-<D>. Changes to a subprocess, including to
default directories and environment variables, do not affect the
parent process.
Please note that although the Insight II program itself is not case-
sensitive, UNIX is. You must type all operating system level com-
mands that you invoke through the Insight II Unix command in
the proper case.

Change_directory
The Change_directory command is used to change the default
directory from which the Insight II program reads files, and to
which it writes files.

Sleep
The Sleep command allows you to suspend the running of this
program for a specified number of seconds. This is primarily use-
ful when replaying a log file for demonstration/training purposes,
allowing you to halt the display for a set length of time regardless
of the processing speed of the host computer.

100 Insight II/March 2000

 Command Summary

Quit
The Quit command ends the current Insight II session. This is the
normal way to exit the program. Upon normal completion, the
Insight II program names the logfile insight.log. Note that if the
program terminates abnormally, it names the logfile WBLOGFILE.

MSI_OnLine
This command launches a browser pointed to MSI’s online help.

File Pulldown
The File pulldown contains commands that allow you to perform
operations on the contents of a file or folder. Folders are special
files used by the Insight II program to store objects created during
a session. Folders can contain multiple objects created during dif-
ferent Insight II sessions.

Save_Folder
The Save_Folder command adds object(s) to a folder. You can cre-
ate a new folder, or insert an object(s) into an existing folder.
The comment parameter for the Save_Folder command allows
you to specify a comment string that can provide information on
an object stored in a folder. Both the List_Folder and Restore_
Folder commands cause the display of this comment string to the
textport. How the Insight II program handles duplicate object
names can be specified.

Restore_Folder
The Restore_Folder command displays object(s) previously
stored in a folder. Restore_Folder also displays the associated
comment to the textport for each object it restores, if a comment
exists. You can also use the Restore_Folder command to specify
how the Insight II program handles duplicate object names.

Remove_Folder
The Remove_Folder command deletes object(s) from a folder.

Insight II/March 2000 101

4. Viewer Module

List_Folder
The List_Folder command displays information on the contents of
a folder to the textport. This information includes each object’s
name, date of last modification, and associated comment text. The
List_Folder command is the only mechanism that queries the con-
tents of a folder. Folders cannot be printed or edited with standard
UNIX commands, such as more or vi.

Import
The Import command is used to read molecular data files into
Insight II for viewing or analysis. Import is similar in function to
Get, but adds features that permit searching for files utilizing an
index and preview operations that make it possible for you to view
the text or graphics contained in a file in a window separate from
the main Insight II graphics window. The Import command uti-
lizes different File_Filter strings for each file type that the com-
mand supports. File_Filter strings allow you to specify the file
extensions that are to be accepted when a file list is created. Insight
II provides reasonable defaults for these "filter_strings" to allow
easy access to files with non-standard file extensions. These
defaults can be changed during the Insight II session by using the
Set_File_Type toggle.

Export
Export is a companion command to the Import command. Molec-
ular data within Insight II can be written in one of the available
supported file formats.

Export_Plot
The Export_Plot command in the File pulldown allows you to
write the present display to various output file types, including an
intermediate plot file (.ipf), or directly to a specified hardcopy
device.
When the input is directly from the screen all current transforma-
tions such as clipping and coloring are taken into account. The
entire display is plotted except for hardware-created images such
as CPK spheres and the variable linewidth of bonds.

102 Insight II/March 2000

 Command Summary

To print hardware-created images such as solid contours, ribbons,

and CPK’d molecules, use the Snapshot and Tops utilities pro-
vided by SGI, or the xpr and xwd utilities provided by IBM. See
the Insight II Products System Guide for more information.

Export_Image
The Export_Image command allows you to capture a bitmap
image (also called a raster image) from the current display and
write it to a file, optionally sending it directly to a printer or pre-
viewer. To export images at 600 dots-per-inch (dpi) resolution you
should have at least 128 MB of RAM, and note that a PostScript file
saved at 600 dpi resolution may be as large as 200 MB. On an SGI
workstation, Insight II should be running in OpenGL mode in
order to export images at 300 or 600 dpi resolution. Otherwise text
in the exported image may be clipped. Additional notes on using
this command are provided online through the Insight II Help
Viewer.
The captured image can be the entire graphics window, or a por-
tion of it. The USER_DEFINED, NTSC, and PAL options for the
Image Size parameter allow interactive specification of the region
to capture.

Source_File
The Source_File command in the File pulldown executes a set of
Insight II program commands from a disk file. You may use up to
three nested levels of indirect files in any sequence of commands.
This is particularly useful for repeated operations.
To terminate a sourcing process, press <Esc> on the keyboard. To
temporarily halt the sourcing to review screen output, press
<Backspace> or <tab>. Then you can choose either <Esc> to exit
the command, or press any other key to continue. Note that while
the replay process is halted, you can use real or screen dials to
rotate, translate, or scale the screen image. However, commands
may not be executed.

Insight II/March 2000 103

4. Viewer Module

Export_Molscript
The Export_Molscript command creates a molscript input file for
each separate protein object (protein_id) in Insight II. The follow-
ing options are available:
♦ rendering and coloring atom subsets and secondary structure
elements.
♦ stereo diagram generation.
♦ CPK and Ball-and-Stick rendering.
Minimum input for this command requires setting:
♦ protein_id, the object to be rendered.
♦ Molscript_file, the name of the molscript input file to be gener-
ated.
For each Molscript_file generated, a matching Mol_<Molscript_
file>_<protein_id>.pdb file is generated. Both files must be present
in the same directory for molscript to work correctly. Postscript
File options also generate a <Molscript_File>.ps PostScript file.
Note that MSI does not distribute the molScript executable. It must
be properly installed and available in your PATH for the Post-
script File and Show Postscript options to work correctly.
Also, a properly installed PostScript viewer must be present for
the Show Postscript option to work. Export_Molscript requires
that the SGI_PS_VIEWER (on SGI) or IBM_PS_VIEWER (on IBM)
environment variable be set to point to the postscript viewer. SGI_
PS_VIEWER is set by default to xpsview and IBM_PS_VIEW does
not have a default value.

Object Pulldown
The Object pulldown contains commands for manipulating
objects.
For molecules, the object name is the first part of the molecule
specification, which does not include the monomer/residue or
atom specifications. As a result, the colon (:) character used in the
full molecule specification is not allowed in an object name.

104 Insight II/March 2000

 Command Summary

Also, most commands allow the use of wildcards in the object

name to specify a set of objects. The wildcard character (?) matches
any single character, and (*) matches any number of characters.

Copy Object
The Copy Object command creates a duplicate of the object you
specify. If the object is a molecule or a user object, it makes an
actual copy of all the vectors, atoms, and/or bonds. If the object is
an assembly, it creates an assembly with exactly the same contents
as the original assembly.
The newly created object may or may not be displaced from the
original object depending on the value of the Displace parameter.
Setting Displace to on helps you see the new object more clearly,
since it is not coincident with the original.

Paste Object
The Paste Object command pastes an object from the Motif clip-
board into Insight II. The clipboard may have been filled by an ear-
lier Copy Object command with To_Clipboard set to On, or by a
cut or copy operation using a compatible application running con-
currently under the Motif window manager. A warning message
is displayed if the Motif clipboard is empty or contains material
with an unrecognizable format.
Currently, Motif clipboard operations are limited to 2D and 3D
molecules and use the MDL “mol” format. Compatible applica-
tions must use the “MDL_MOL” format identifier. When using the
menus, Insight II fills in the New_Name parameter with the com-
pound name from the “mol” format, if that is set. Otherwise you
should fill in the New_Name parameter with a unique name for
the new object.

Delete Object
The Delete Object command deletes a specified object. Once
deleted, the object is removed from the screen, memory, and data
storage. No memory of the object is retained.

Insight II/March 2000 105

4. Viewer Module

Rename Object
The Rename Object command is used to give a new name to a
specified object.

Blank Object
The Blank Object command is used to blank the display of an
object. When an object is blanked, it does not appear on the display
screen. In the case of molecules, the Blank Object command
affects atoms, surfaces, CPKs, and ribbons.

Axes_Display Object
The Axes_Display Object command is used to control the display
of the local and alternate axes systems for objects of any class.

Blink Object
The Blink Object command is used to cause an object to blink or
flash on the screen. This facilitates seeing the minor differences
between two objects which are very similar and which have been
superimposed.

DepthCue Object
The DepthCue Object command activates or deactivates depth
cueing for the specified object. Depth cueing aids in the three-
dimensional perception of an object by drawing bonds and atoms
which are farther away from the view point in dimmer colors.

LineWidth Object
The LineWidth Object command is used to set the width of the
lines which are used to represent an object.

List Object
The List Object command lists general information about all types
of objects. This listing includes the object name, the object type,
and some specific information on the composition of the object.
Information can be requested for all objects (the default), or for any
single object. For more details on a particular object, you can use

106 Insight II/March 2000

 Command Summary

the List command which refers to the type of that object: List
Assembly, List Molecule, List Contour, List User, List Graph.

Molecule Pulldown
The Molecule pulldown contains commands to manipulate mole-
cules.

Get Molecule
The Get Molecule command brings a molecule into the working
session.
Using this command, you can retrieve a stored molecule, which
must be in one of these formats: Ampac, Mopac, Archive (MSI .arc,
.car, and .cor files are all read with the Archive option), Cambridge
(CSD_Fdat), free format, PDB (the Brookhaven Protein Databank
data set), CHARMm, Quanta_MSF, MDL, Sybyl_Mol2. The
default file type is Archive. If the file specified is a free format file,
an additional file for reading that format must also be specified.
The free format and MSI-provided template files are described in
Appendix B. HETATM cards may optionally be retrieved when
reading a PDB format file.
You can also retrieve an entire archive file, or a single frame or
range of frames from an archive file.
You may also specify a coordinate system for displaying the
retrieved molecule relative to an already existing molecule.
Molecules are displayed using default values for Color, Bond_
Order, DepthCueing, and Line_Width (see the Molecule/Set_
Default command for setting the default values of these parame-
ters).
When Insight II reads a file containing molecular data, it deter-
mines what element each atom is. This is crucial information for
any subsequent operation on a molecule. The determination of ele-
ment type is done by scanning the appropriate column in the input
file. If an atom cannot be matched with a known element, an error
is reported to the user. The elements known to Insight II are
defined in the file elements.dat, located in the $INSIGHT_DATA
directory. Insight II uses several different methods for establishing
topology when molecules are read:

Insight II/March 2000 107

4. Viewer Module

AMPAC and MOPAC files Connectivity is established by dis-

tances for AMPAC and MOPAC files, since they do not contain all
the bonding information that is needed to completely define the
connectivity of a molecule.

MSI car, arc, and cor files An accompanying mdf file is also
expected. The mdf file must have the same prefix as the car, arc, or
cor file (e.g., test.car or test.mdf). If the mdf file is present, and
refers to the same atoms as the car, arc, or cor file, the connectivity
found in the mdf file is used explicitly.
Note that Insight II writes an informational message when the mdf
file is being used. You should confirm the use of the mdf file by
looking in the information area when reading car, arc, or cor files.
If the mdf file does not match the car, arc, or cor file, or cannot be
found, then a two-pass algorithm is used to establish the connec-
tivity.
On the first pass the template file, amino_templates.dat, located in
the $INSIGHT_DATA directory is checked for matches. The tem-
plate file contains templates for amino acids including charged
and terminal amino acids, nucleic acids, and a few commonly
occurring residues and generic functional groups. A match occurs
when a monomer or residue matches the name found in the tem-
plate, has the same number of total atoms or heavy atoms only,
and has the same atom names. When a match is found the connec-
tivity for that residue is used from the template, with inter-residue
connectivity being determined by distances and atom types. Each
residue of a molecule is checked for a match, and those that have
templates are assigned their connectivity from the templates. Any
monomers or residues that do not match the templates have their
connectivity established by distances. In the second pass bonding
distances are read from the file elements.dat, also found in the
$INSIGHT_DATA directory.
Any two atoms that are within the bonding distance plus a small
margin of error are bonded together. If more than the appropriate
number of atoms lie within bonding distance they are all bonded
together. Insight II does not try to determine if any atoms close
enough to be bonded should not be bonded.
You should note that you can add your own entries to the template
file. For further information, refer to the appendices for Insight II.

108 Insight II/March 2000

 Command Summary

Sybyl Mol2 files and MDL molfiles and SDfiles The connectiv-
ity information that is contained in the file is used explicitly.

CSD Fdat The two-pass algorithm described above is used to

establish the connectivity in molecules read from the Cambridge
database.

Free Format Files Free format files may contain explicit connec-
tivity. In the cases that they do, it is used explicitly. Otherwise the
two-pass method described above is used.
In the Insight II program, atom names are constrained to a five-
character length.

Brookhaven files The PDB Directory item selects between

reading files from the Brookhaven database, as defined in
$INSIGHT_PDB, and the current working directory. For complete
information on reading in PDB files, refer to Appendix C.
The two-pass algorithm described above is used for establishing
the connectivity in molecules read from Brookhaven formatted
files. In addition the connectivity described by CONNECT records
is also used.

Put Molecule
The Put Molecule command writes molecules from the working
session into a disk file. The molecule may be stored in any of sev-
eral formats: Old_Biosym, WebLab_MSV, MDL, Sybyl_Mol2, free
format, Mopac (usable with Ampac or Mopac), PDB, or
CHARMm. Files can also be saved in a format of your own speci-
fication.
Optionally, the Put Molecule command can be used to store only
the atoms that are actually displayed, and store the molecule first
applying the current transformation matrix to the molecule’s coor-
dinates.

Insight II/March 2000 109

4. Viewer Module

Set_Defaults
The Set_Defaults command is used to view and set default
parameters for all molecules which are brought into the working
session by use of the Molecule/Get command. The parameters
which may have defaults set using this command are Color,
Bond_Order, DepthCueing, and Line_Width.
When the Insight II program is started, the default values of these
parameters are retrieved from a file named .in2rc. The .in2rc file
which is used is in one of three locations
1. The user’s local directory (the directory from which Insight II is
run)
2. The user’s home directory
3. The $INSIGHT_DATA directory (this file is on the Insight II
CD-ROM delivered by MSI and is not editable by the user).
The search order is as listed. If no such file is found in the local
directory, Insight II looks next in the home directory, and so on.
The $INSIGHT_DATA/.in2rc file is always present with the
default values set at MSI. The .in2rc file found at startup is the one
used throughout the session.
The .in2rc files in the local and home directories are editable and
can be updated by Insight II using the values selected in the Set_
Defaults parameter block. You may also list the current default
values at any time.
Parameter values are selected for each file type in the parameter
block. You can set values for all file types at once by selecting All
for the File Types parameter.
Choices for Coloring_Method are: By_Atom for coloring each
atom according to its element type; Specified for coloring all
atoms the selected color, for all subsequent molecules of that type;
or Color_By_Rotation for coloring all atoms of the next molecule
the selected color, and all atoms of subsequent molecules the next
color from Insight II’s color wheel.

Color Molecule
The Color Molecule command is used to render molecules and
molecular attributes in color.

110 Insight II/March 2000

 Command Summary

You can apply color assignments to single or sets of atoms in the

molecule, ribbons, specified threads of ribbons, surfaces, CPKs, or
any combination thereof. Molecule, monomer, residue, or atom
labels may also be colored separately. Colors can be specified by
name or number, or by mixing a new color from a color palette.
Colors can be assigned to individual atoms, by atom name, by
atom charge, by hydrophobicity, or any specified property. Insight
II can automatically select backbone, hydrogen, non-hydrogen,
side-chain, or trace atoms.

Transparency Molecule
The Transparency Molecule command is used to adjust the degree
of transparency effect used for the CPK, Ball_and_Stick, and
Stick solid renderings and surfaces of molecules. This is achieved
by adjusting the alpha component of all colors in the spheres and
cylinders used in the solid rendering of the specified molecule
without affecting the r,g,b values (see Use of Color for more infor-
mation). A Transparency Value of 0.0 means fully transparent and
a Transparency Value of 1.0 means fully opaque.

Display Molecule
The Display Molecule command is used to turn on the display
status of molecular attributes. This command is used to separately
display atoms, residues, monomers, subsets, or molecules, as well
as the axes, CPKs, ribbons, or surface attributes. Attributes can be
selectively added to the display, or only specified portions of an
attribute can be displayed. Backbone, hydrogens, heavy, side-
chain, and trace atoms can be automatically selected.

Label Molecule
The Label Molecule command is used to create or remove labels
for molecules, monomers, or atoms. A label is a short piece of text
attached to a molecule, monomer, or atom. The text may be a
property of the object it is attached to, such as its name or mass.
Labels may be displayed with a variety of display characteristics,
permitting display of the properties in a flexible manner.

Insight II/March 2000 111

4. Viewer Module

Bond_Order Molecule
The Bond_Order Molecule command controls the display of mul-
tiple-order bonds. By default all bonds are displayed as if they
were single bonds.

Surface Molecule
The Surface Molecule command is used to create and delete
atomic dot, line, or solid surfaces. Three surface types are avail-
able: van der Waals, solvent (solvent accessible using the Connolly
algorithm), and Quick, a pseudo-connolly surface that is not as
precise as the SOLVENT method, but the calculation is much
faster. The variables that can be controlled for the display are the
quality of the surface, and whether it is in the context of another
molecule.
In the case of solvent accessible surfaces, the probe radius can also
be varied.
The surface from a molecule can be written to a file using the Put
option. The file format used is identical to that of the dots.usr file,
so the surface can be retrieved later as either a user object or as a
surface on a molecule.

Render Molecule
The Render Molecule command allows you to control how the
atoms and bonds of a molecule are represented. Available render-
ing styles are CPK, Ball_and_Stick, and Stick.

Ribbon Molecule
The Ribbon Molecule command is used to create or delete a rib-
bon representation of protein or polynucleic acid secondary struc-
ture. This command allows you to specify the type of ribbon (flat,
solid, lines) and the number of strands to use in a line ribbon rep-
resentation, the offset distance to use in calculating ribbons around
helixes, and the width of the ribbon (in angstroms). You can also,
optionally, create decals to label the ribbons with residue property
values. You may also choose to vary the width of the ribbon based
on a per-monomer characteristic of the molecule.

112 Insight II/March 2000

 Command Summary

Color_Ribbon Molecule
The Color_Ribbon Molecule command allows you to color mole-
cule backbone ribbons. A ribbon consists of a number of threads,
and it spans one or more monomers. The smallest part of a ribbon
which can be individually colored is a single thread within a single
monomer.

SecondaryRender Molecule
The SecondaryRender Molecule command creates a Richardson
style rendering of the secondary structure of a protein. The dis-
play parameters (e.g., size, color) for the rendering can be set with
the Preferences parameter.
The secondary classification can come from the PDB file, a mono-
mer table, or from an ab initio Kabsch Sander calculation.
The SecondaryRender Molecule command works only on a
whole molecule. If you need to create a display for a partial mol-
ecule, you can accomplish this by using Merge and Unmerge com-
mands in the Modify pulldown in the Builder module.

List Molecule
The List Molecule command is used to display detailed informa-
tion about specific molecules. You can list the names, coordinate
information, charge group, potential type, atomic charge, frac-
tional coordinates, minimum and maximum Cartesian coordi-
nates, and link distances which match the molecular specification.
The total energy of a molecule can also be listed if it has been pre-
viously computed or read in. The listed information may be dis-
played to the textport or to a specified file.

Tabulate Molecule
The Tabulate Molecule command is used to create a table that dis-
plays the molecular properties selected for the specified atoms.
Each property is represented by a column of information, with the
name of the property above each.

Insight II/March 2000 113

4. Viewer Module

Browse Molecule
The Browse Molecule command creates a window which contains
a table of molecules. This table can be used to quickly and easily
browse through the molecules which are presently in the system.
This browser offers the ability to blank or show molecules, connect
molecules to dials, or select sets of molecules for use in subsequent
commands, all with the click of a mouse.

Figure 16. Molecule Browser

The browser is a table which lists the molecules and assemblies

which are currently being modeled with the Insight II program.
Each row contains four columns of information: the name of the
object, the display status (On indicates it is currently displayed),
and its dial connection status (Connected indicates that the object is
currently connected to the dials).
You may use the browser to quickly change the display and dial
connection status of objects. To change the display status, click on
the table cell next to the name of the molecule or assembly. The
dials may be connected to an object by clicking in the Dials column
next to the name of the object. You may connect the dials to world
by clicking on the Connect World button. When connected to the
world, this button changes to Reconnect to obj, and permits you to
connect back to the object which was connected before connecting
to world.
The browser may also be used to select molecules for use with sub-
sequent commands. Molecules are selected by clicking on their
name in the browser. Selected molecules are indicated by yellow

114 Insight II/March 2000

 Command Summary

highlighting. More than one molecule may be selected at a time. To

clear the selection so that no molecules are currently selected,
press the Clear Mol_Select button.
The selection may be used to easily operate on multiple molecules
with the single execution of a command. For example, select a set
of molecules which you would like to associate in an assembly.
Choose the Associate Assembly command, fill in a name for the
assembly, and press the Execute button. The selected molecules
are now associated as members of an assembly with the specified
name.
The browser also displays assemblies and shows the members of
the assemblies, indented below the row which contains the assem-
bly object. This may be used to quickly determine the contents of
an assembly.
Molecules are added to the table automatically as they are added
to the system, through commands such as Get Molecule and
Append Residue, and are removed from the table when they are
removed from the system using Delete Object.

Measure Pulldown
The Measure pulldown contains commands to measure the dis-
tance between two atoms, the angle defined by three atoms, and
the dihedral angle defined by four atoms. Several of the com-
mands also allow the setting of monitors. A monitor is a visual dis-
play of a quantity’s current value, which changes dynamically as
the objects involved move.
The Measure command also provides a mechanism for measuring
the internal energies of a molecule, including bond, angle, dihe-
dral, nonbond, and cross terms.

Distance
The Distance command measures the distance between two atoms
in the same or different molecules.
The output of the Distance command is determined by the Moni-
tor parameter, which indicates whether the command uses dis-
tance monitors. A distance monitor is a visual display of the
distance using a dashed line connecting the atoms, with the dis-

Insight II/March 2000 115

4. Viewer Module

tance value above the line. The monitor changes dynamically as

the atoms move. If Monitor is Off, the distance between the two
atoms is reported in the information message area and the text-
port. You can also add, remove, or clear distance monitors, as well
as display only distances between a specified minimum and max-
imum distance values.

Angle
The Angle command determines the current angle specified by
any three atoms. The atoms do not need to be in the same mole-
cule.
The output of the command depends on the value of the Monitor
parameter. If Monitor is On, a dotted line between the atoms
forming the angle and its measurement isdisplayed. If Monitor is
Off, the three atoms, minimum and maximum angle, angle, and
whether the condition criteria are currently satisfied are listed
either to a file or to the textport and information area.

Dihedral
The Dihedral command determines the current dihedral angle
between any four atoms. The atoms do not need to be in the same
molecule.
The output for the Dihedral command is determined by the Mon-
itor parameter. If this parameter is Off, the calculated angle, given
in degrees, is reported to the information message area, as well as
the textport. If the Monitor is set to On, a dihedral monitor is set
up. This displays the dihedral angle by connecting the four atoms
involved with dashed yellow lines, along with the current angle in
degrees. You can also add, remove, or clear dihedral monitors, and
specify values for the minimum and maximum dihedral angles to
be monitored.

Monitor_Style
The Monitor_Style Measure command allows you to set the color
of distance, angle, dihedral, bump, and hbond monitors created
via the Distance, Angle, Dihedral, Bump, and HBond commands
of the Monitor pulldown. For Distance, Angle, and Dihedral the
color may be set for all monitors of a given type, or for individual

116 Insight II/March 2000

 Command Summary

monitors. For Bump and HBond all monitors of the given type are
affected.

XYZ
This command determines the coordinates of an atom. The coordi-
nates are reported in the information message area and the text-
port.

Bump
The Bump command is used to check for van der Waals overlap
within a molecule or between two molecules. If overlap is
detected, red vectors are drawn between the offending atoms and
the distance between the atoms is listed.
Van der Waals overlap occurs when the distance between any two
atoms is less than the sum of the van der Waals radii of the atoms,
less the allowed overlap.
The default display for the Bump command is statically connected
to the first molecule specified. That is, it is not updated in response
to movement of the molecule(s) involved. The Bump command
can also set up a monitor that changes dynamically as the mole-
cule(s) are moved. The van der Waals radii used in calculating the
overlaps are determined from the elements.dat file in the
$INSIGHT_DATA directory and is read in when Insight II is
started. The percentage of overlap considered to be unacceptable
is a parameter of this command.

Neighbor
The Neighbor command displays the distance between one or
more source atoms and their neighbors. Two atoms are neighbors
if they are in the same molecule and are separated by three or more
bonds.
You can specify whether you want neighboring atoms to be con-
nected by a solid line with the distance displayed between them,
or with a dashed line. You can add, delete specific, or delete all of
the given type of neighbor displays.

Insight II/March 2000 117

4. Viewer Module

Other options allow you to limit the display of neighbors to only

those falling within a specified minimum and maximum distance,
or those having a certain element type.

HBond
The HBond command is used to add, and delete some or all of the
hydrogen bonds within or between molecules from the display.
A hydrogen bond is considered to be formed when the distance
between the proton on the donor atom and the heavy atom accep-
tor is less than a specified distance, and the angle between the pro-
ton acceptor, the proton, and the proton donor is greater than 120
degrees. If hydrogens are not included in the current display,
hydrogen bonds are displayed between the heavy atoms oxygen
and nitrogen. The distances and angle used for determining
whether an acceptor and donor are within hydrogen bonding dis-
tance are taken from the file, hbond_file.dat, which is located in the
$INSIGHT_DATA directory.
The display of the hydrogen bonds differs slightly between
intramolecular bonds (within a molecule), and intermolecular
bonds (between molecules). Intermolecular hydrogen bonds are
displayed with dashed green lines connecting the atoms, along
with the associated distances. This display looks and acts exactly
like a distance monitor. Intramolecular hydrogen bonds are lighter
in color and have no distance displayed. Note that although
hydrogen bonds are similar to distance monitors, they can only be
deleted with the HBond command.

Energy
The Energy command allows you to examine or to monitor the
total energy of a single molecule. You can specify which atomic
energies will be used to compute the total energy. You can choose
one of the sets of predefined groupings of energy terms, including
all atomic energies, only the diagonal terms excluding the hydro-
gen bonding and cross terms, and only the nonbond terms. You
can also specify any group of energies desired. You can also add,
remove and/or clear energy monitors.
The source of the parameters used for the energy calculation is the
currently assigned forcefield file.

118 Insight II/March 2000

 Command Summary

Transform Pulldown
The Transform pulldown contains commands that control the
three-dimensional spatial transformations of objects (i.e., rotations
and translations). Also included are commands that define certain
characteristics of the three-dimensional viewing window.
All objects that are defined in the system may be moved, rotated,
scaled, etc., in relation to the frame of reference of the viewing win-
dow (screen). Such three-dimensional transformations may be
performed in a continuous manner by using the mouse, or the dial
slider boxes in the lower left part of the screen. Some of the com-
mands in this group allow these same transformations to be per-
formed in discrete, user-defined steps. In the case of rotation and
translation, the transformations can be performed in an object
space axis system. Object space axes differ from the screen axes in
that they are unique to each object. Object space axes move and
rotate with an object when the object is transformed in screen
space. The default object space axes are defined by the principal
moments of inertia of the object. Alternative definitions can be set
up. The object to which the dials are connected is identified imme-
diately under the screen dial boxes.
Commands in this pulldown also allow you to select the object(s)
to which the transformations are applied, to set the scale of the
objects, and to set the window clipping parameters. Also included
are commands to define torsions about bonds, perform superim-
positions of molecules, rock any object about the y axis, and define
which object the mouse or dials are connected to.

Connect
The Connect command is used to connect the mouse and dials to
an object. The mouse and dials control the scale, translation, and
rotation of objects. These operations can be performed by using
the mouse, the dial slider boxes on the screen, or physical dials.
You can also specify that the given command be performed on
world, rather than an individual object or assembly.
By default, whenever more than one object exists, the dials are con-
nected to world, which is a pseudo-association to which all objects
in the system belong. Therefore, all objects initially move and scale

Insight II/March 2000 119

4. Viewer Module

as one. The Connect command allows you to connect to a particu-

lar object or assembly so that it may be moved or scaled indepen-
dently.
The dials remain connected to the specified object until another
Connect command is issued or until a command is given that con-
nects the dials to an object by default. The dials may be recon-
nected to world at any time by using the Connect command with
the World option and no object name.
In the case of rotation and translation, the transformation may be
performed in an object space axis system.

Position
The Position command in the Transform pulldown allows you to
list or delete alternate positions that have been previously stored
with objects.

Reset
The Reset command in the Transform pulldown allows you to
apply alternate positions that have been previously stored with
objects. These alternate positions are created with the Store com-
mand in the Transform pulldown. The positions LAST, CUR-
RENT, and ORIGINAL are automatically generated and are
updated whenever you use the commands Connect, Move,
Rotate, Scale, Center, Superimpose, and Overlay from the Trans-
form pulldown, or when you use the function keys (<F10> or
<F11>) to connect to objects.

Store
The Store command in the Transform pulldown allows you to
store alternate positions for objects. These alternate positions can
be applied later using the Reset command in the Transform pull-
down.
You may name a position with any alphanumeric string of charac-
ters and the dollar sign and underscore. However, the names
CURRENT and ORIGINAL are reserved and cannot be used.

120 Insight II/March 2000

 Command Summary

Axes
The Axes command is used to define the alternate space axes for
an object. The alternate space axes define the center of rotation for
the object and system in which the object is translated and rotated
when the dials are connected in the Alternate space of transform
mode. Alternate space axes are convenient for performing such
tasks as rotating about the axes running through a helix, or normal
to plane. They are also used for positioning and aligning the object
via the Move and Rotate commands and are used for positioning
sliceplanes when visualizing grids.
The alternate space axes can be defined by using the Moment_of_
Inertia of the object, specifying three Atoms or Coordinates, or
providing an alternate space transformation Matrix. The Recenter
boolean controls whether the alternate space axes are recentered
on a new point or whether only their direction is altered.

Center
The Center command in the Transform pulldown is used to define
the center of rotation of an object or assembly. The new center can
be defined in several ways. For example, you can define the center
of rotation as the center of mass of the object or set of objects
(default), as a single atom or the coordinates of an atom, as the
three-dimensional midpoint of three atoms, or as an arbitrary
point in the world system. You can also specify that the given com-
mand be performed on world, rather than an individual object or
assembly.
If one or more objects of an assembly are translated, the center of
rotation is not automatically updated. This update must be done
using the Center command.
The center of rotation of world may be redefined by using the
World parameter with no object name or mode option.
In the menu version of the Center command, the Position Center
parameter may be entered by picking an atom with the mouse. The
resulting values are the x, y, z world space coordinates of the atom.
Note that this is the same as using the Atom mode, and thus is not
the intended use of the position mode.

Insight II/March 2000 121

4. Viewer Module

Move
The Move command translates an object or assembly to a new
position on the screen. This can be in the world axis system or the
object axis system. The same effect can be obtained by using the
mouse, dial boxes on the menu, or physical dials for the transla-
tion. However, the Move command provides a means of moving
an object by a specific amount, or to a specific location.

Rotate
The Rotate command rotates an object or assembly by a specified
number of degrees about the world axis or object axis system.
You can specify the number of degrees in each direction (X, Y, Z),
that the object should be rotated. Values must be specified for each
direction, even if they are 0. The rotations are always done in the
order X, Y, Z.

Scale
The Scale command is used to set or change the scale of one or
more objects to a user-specified value. This is useful for resetting
objects that have been independently scaled, to a common scale, or
for changing the scale by a known amount. The scale of objects
specified with the Connect command can be changed in a contin-
uous manner through the use of the mouse or the dials.

Apply
The Apply command is used to apply the current rotation trans-
form to the coordinates of the molecule. This command functions
identically to the sequence of operations: Put Molecule Transform
ON, Delete Molecule, and Get Molecule with the transformed
coordinates.

Clip
The Clip command is used to manipulate the thickness (the dis-
tance between the front and back clipping planes) of the viewing
window, and the Z position (the midpoint of the window in the z
direction) of the viewing window. The viewing window is also
referred to as the slab. The position can be controlled using the

122 Insight II/March 2000

 Command Summary

onscreen dialbox labeled SlabPos. This dial may be toggled to con-

trol the thickness (SlabThick) by depressing the <F12> key.
The closer an object is to the front of the viewing window, the
brighter it appears. Conversely, the closer an object is to the rear of
the window, the dimmer it appears. The percentage of the viewing
window spanned by the object determines the range of the depth
cueing that is applied to an object. An object spanning the entire
window will range from no depth cueing (very bright) to all depth
cueing (black). Moving the Z position of the clipping plane is
equivalent to translating an object along the screen Z axis. The cur-
rent position of the center of the viewing window, and the width
of the viewing window are displayed in the lower left corner of the
screen.

Rock
The Rock command is used to initiate a rocking motion of one or
more objects on the screen about the Y axis. This rocking motion is
useful for giving a pseudo three-dimensional illusion to the struc-
tures. The rocking can be controlled in both speed and magnitude.
Each time the timer fires, the object(s) are rotated by a specified
number of degrees. Specifying a larger number of degrees causes
a faster rotation rate. By specifying a large value for the magnitude
of the rocking motion a rolling motion can be achieved.
Once the Rock command is activated, rocking continues even if
other commands are issued, until the Rock command is turned off.
When specifying the object or objects which are to be rocked, you
may use a wildcard, but may not specify an assembly object. If
rocking is already in progress, the specified objects are added to
the rocking motion.

Torsion
The Torsion command is used to define, tabulate, reverse, delete,
clear, and set the display style of dihedral angles for up to four
bonds in a molecule.
Once you have defined a torsion it becomes the active torsion; an
angle monitor as well as a cone indicating the directionality of the
torsion are displayed identifying the active torsion. There is only
one active torsion at any one time. To deactivate a torsion, click on

Insight II/March 2000 123

4. Viewer Module

empty space. To activate a torsion, click on the bond. To reverse the

directionality of the torsion, click on the cone; the vertex of the
cone is the anchor point of the molecule, while the large part of the
cone points toward the moving portion of the molecule.
You can navigate through the defined torsions using either the
<F7> key (Next Torsion) or the dial to activate the torsion of inter-
est.
You can also tabulate the defined torsions, and set the display style
to serial number or monitor angle values.
Note that you can define a torsion with two mouse clicks: one to
select the torsion bond, and one more click on the Torsion icon (in
the icon bar) to define/activate the torsion. If a torsion is active,
clicking the Torsion icon deletes that torsion.
Figure 17. Dial Box for Torsion Navigation

Dials

X Rotate Torsion1

Y Rotate

Z Rotate Next Torsion

World Scale Slab Pos

Conn Obj: DHFR

Slab: 50.00 @ 0.00

Forcefield: cvff

Overlay
The Overlay command allows you to overlay one object onto
another. The Insight II program knows where every molecule,
graph, user-object, contour, etc. is in space. That is, it knows how
each such entity has been moved (translated), rotated, and/or
scaled. When one graph is overlaid on another graph, the transla-
tion, rotation, and scaling of the two graphs is made the same so

124 Insight II/March 2000

 Command Summary

both graphs appear overlaid. In the case of molecules, the centers

of gravity of the two molecules defined are overlaid without rotat-
ing the molecules. Normally, this command is used to overlay enti-
ties of the same kind on one another: molecules on molecules,
graphs on graphs, user objects on user objects. However, you may
overlay a molecule onto a graph, or a user object onto a contour
and so forth. Note, however, that such heterogeneous object over-
lays may result in displays that are not easy to predict.

Superimpose
The Superimpose command is used to superimpose two mole-
cules on the screen. Sets of corresponding atoms from each mole-
cule are selected and used to perform a minimum RMS alignment
of the two molecules. The first (source) molecule is then moved to
visually display its superposition on the second (target) molecule.
A minimum of three atoms from each molecule are required for
superimposition.
Parameter options in the Superimpose command allow you to
select certain types of atoms, such as heavy atoms, backbone
atoms, and alpha carbon atoms, as the source spec and the target
spec.

Subset Pulldown
The Subset pulldown contains commands related to subsets. A
subset is a collection of atoms from one or more molecules. The
subset is defined using commands from the Subset pulldown and
can be used in commands anywhere a subportion of a molecule
can be used. Subsets can be created by explicitly defining mono-
mers, residues, or atoms, or automatically by having Insight II find
monomers and residues within a given proximity of selected
regions of a molecule. Subsets can also be used in molecular
mechanics simulations using Discover.

Get Subset
The Get Subset command is used to create a new subset by read-
ing a subset definition file (.sub) or a molecular data file (.mdf). If

Insight II/March 2000 125

4. Viewer Module

an mdf file is specified, the subset definition is read from the atom-
set section.

Put Subset
The Put Subset command is used to save a subset in an external
file. The subset members are written to a subset definition file (.sub
extension). The format of this file is consistent with the atomset
portion of the .mdf file. Refer to the file format documentation for
more information.

Define Subset
The Define Subset command is used to create and filter subsets
that describe static, or dynamic, sets of atoms on the basis of
atomic attributes. Multiple attributes can be used sequentially, to
define, for example, sets having two properties (attributes within
specified ranges) simultaneously.

Zone Subset
The Zone Subset command is used to create a subset that is spec-
ified in terms of a central set of atoms and a radius. All atoms that
belong to monomers or residues which fall within the spheres
described by the set of central atoms and the radius are made
members of the new subset.

Interface Subset
The Interface Subset command is used to create a subset that is
defined in terms of a central set of atoms, a radius, and an object
comparison list. All atoms which are contained in monomers or
residues that belong to objects in the comparison list and are
within the sphere described by the central atom and the radius are
made members of the new subset. This command is useful for
finding those residues in a protein around an inhibitor.

Template Subset
The Template Subset command is used to create a new subset
whose members are sets of atoms that make up specific patterns
within a molecule or assembly of molecules. A specific instance of

126 Insight II/March 2000

 Command Summary

a pattern is used as a template to locate all occurrences of that pat-

tern within a given search domain.
A template is defined by traversing bonds in a molecule along the
shortest path between two atoms. The template may be a branched
or linear pattern. If linear, only the atoms along the shortest path
between the two atoms are included in the template. If branched,
all branch structures encountered along the shortest path are
included in the template. Branches may be selectively excluded
from the template by specifying one or more blocking atoms.
In addition, a subpattern within the template may be specified. In
this case, the template matching still occurs, but only those atoms
within the subpattern become members of the subset.

Combine Subset
The Combine Subset command is used to perform logical set
operations on subsets. The logical operations include union, dif-
ference, and intersect.

Copy Subset
The Copy Subset command is used to create a duplicate of the
subset you specify. All members of the subset you specify will also
be members of the new subset.

Delete Subset
The Delete Subset command is used to delete a subset. Atoms that
comprise the subset are not deleted, only the subset abstraction of
them.

Rename Subset
The Rename Subset command is used to assign a new name to the
specified subset. The New Subset Name must be unique and fol-
low the same syntax restrictions as the Subset Name parameter.

List Subset
The List Subset command is used to display the monomers or res-
idues and atoms that comprise a subset.

Insight II/March 2000 127

4. Viewer Module

Assembly Pulldown
The Assembly pulldown contains commands that act on assem-
blies or groups of objects.
An assembly is a collection of objects that can be rotated, moved,
and scaled as a single unit. It is composed of one or more other
objects, which may themselves be assembly objects. This nesting
may take place to any depth, but name specification is limited to
five levels of nesting. The primary purpose of an assembly is to
allow you to move a cluster of objects about its common center of
mass.
For several of these commands, value-aids which specify assem-
blies already known to the system are presented alongside the rel-
evant parameter blocks.

Associate Assembly
The Associate Assembly command creates an assembly com-
prised of existing objects. An assembly is a logical grouping of
objects that can be manipulated as one unit when connected to the
mouse or dials. When an assembly is written out, all of its member
objects are written out.

Add Assembly
The Add Assembly command adds an object to an existing assem-
bly.

Remove Assembly
The Remove Assembly command removes an object from an
existing assembly.

Cell Assembly
The Cell Assembly command is used to specify the size, angles,
and table number of the asymmetric unit, which may then be used
in crystal and periodic boundary condition operations. This infor-
mation is also used by the Cell_display, Macro_Cell, Layered_
Cell, Symmetry and Soak Assembly commands. The asymmetric
unit is also used in solvent calculations and in solvent generations.

128 Insight II/March 2000

 Command Summary

The Center_in_Cell boolean specifies that the molecule or assem-

bly should be centered within the cell box.

Cell_display Assembly
The Cell_display command displays an object as it appears in a
periodic system defined by a given unit cell. Note that the asym-
metric unit needs to be defined prior to using Cell_display.
Display modification commands (e.g., Color, Display, CPK, Ball
and Stick) work on these periodic atoms (symmetry/lattice offset
generated replicates of the asymmetric unit). Ribboning, moving
individual replicates, and topological or chemical modification
(e.g., Element type, Charge, Potential Type, Bond order/type
changes) do not. This is because the periodic atoms mirror many
of their parent atoms' attributes, and cannot be changed. However,
the Merge command in the Modify pulldown can be used to con-
vert replicates into independent molecules by merging the repli-
cates into another molecule. Once merged, all modification
commands (e.g., Color, Move, Ribbon, etc.) are available for use.

Symmetry Assembly
The Symmetry Assembly command is used to create, delete, and
display symmetry-related replicates of a molecule. The position of
a replicate is calculated directly from the cell parameters (lengths,
angles, and space group operator) of a reference molecule.
Display modification commands (e.g., Color, Display, CPK, Ball
and Stick) work on these periodic atoms (symmetry/lattice offset
generated replicates of the asymmetric unit). Ribboning, moving
individual replicates, topological or chemical modification (e.g.,
Element type, Charge, Potential Type, Bond order/type changes)
do not. This is because the periodic atoms mirror many of their
parent atoms' attributes, and cannot be changed. However, the
Merge command in the Modify pulldown can be used to convert
replicates into independent molecules by merging the replicates
into another molecule. Once merged, all modification commands
(e.g., Color, Move, Ribbon, etc.) are available for use.
The Delete option in the Symmetry Assembly command allows
you to eliminate the entire periodic system, leaving only the asym-
metric unit.

Insight II/March 2000 129

4. Viewer Module

Soak Assembly
The Soak Assembly command can be used to solvate a molecule.
There are three Methods provided. The molecule can either be sur-
rounded by a Layer of solvent (where you specify the thickness),
placed in the center of a solvent Sphere (where you specify the
atom to place at the center of the sphere, and the radius of the sol-
vent sphere), or a Periodic Boundary Condition (PBC) box previ-
ously defined using the Assembly/Cell command can be filled
with solvent to generate a bulk model. Solvation is accomplished
by placing the molecule in an equilibrated 3D box of solvent and
removing those solvent molecules which overlap with atoms in
the molecule being solvated. Because any atom overlap causes the
whole solvent molecule to be removed the resulting model can be
at a lower than expected density. It is important to fully equilibrate
the model using molecular dynamics before carrying out any anal-
ysis.
The default is to soak with water using the waterbox.psv file pro-
vided in the $INSIGHT_DATA directory. $INSIGHT_DATA also
contains files for toluene (tolubox), THF (thfbox), paraxylene (pxy-
lenebox), and octanol (octobox). However, any solvent may be
used if the necessary solvent files are provided. Soak requires
either a .psv or .car and .mdf files for an equilibrated PBC box of
the solvent. These can be generated using Insight II (macros are
provided in the $BIOSYM_ROOT/$BIOSYM_CONTEXT/gifts/
insight directory to help with this task--contact the Customer Sup-
port hotline for further information), or using the Amorphous_
Cell module.

List Assembly
The List Assembly command lists information about assembly or
replicate objects. The details listed are the center of mass, scale,
current translation and rotation, transform and rotation matrices,
and the component objects for each specified assembly. This com-
mand can also be used to list the symmetry-related replicates for a
specified object, which list the cell space group information for
each replicate.

130 Insight II/March 2000

 Command Summary

User Pulldown
The User pulldown contains commands that manipulate the dis-
play of user objects and their labels. User objects are read from spe-
cially formatted .usr files that describe arbitrary data, such as
arrows, text, and dots. User objects frequently are used to annotate
models that are currently displayed.

Get User
The Get User command retrieves, displays, and names stored user
objects from special .usr format user files. By using the reference
option, you can control whether or not the Get command uses an
existing object as a reference coordinate system. The .usr files are
created by certain Insight II commands, or can be created by hand.

Color User
The Color User command modifies the color of the specified user
object, user object label, or user object user label. You may type the
color specification or select it from the color palette. Colors can be
specified using any of the normal methods.

Transparency User
The Transparency User command is used to adjust the degree of
transparency in the solid surfaces of a user object. This is achieved
by setting the alpha component of all colors in the surfaces with-
out affecting the r,g,b values (see Use of Color for more informa-
tion). A Transparency Value of 0.0 means fully transparent and a
Transparency Value of 1.0 means fully opaque.

Annotate User
The Annotate command is used to create annotations for molecu-
lar models. The annotation may consist of lines, arrows, text, cir-
cles, open boxes, and filled boxes. For example, you may use
annotations to add explanatory comments to a molecular model.
To create an annotation, select the object type (line, arrow, text,
etc.), specify an annotation name, select the characteristics you

Insight II/March 2000 131

4. Viewer Module

would like for the object (color, size, etc.), then click on the Coord1
parameter.
When the Coord1 parameter is active, you may click in the 3D
window to "draw" the object. For text, click the mouse button to
create the object, then, with the mouse button still down, drag the
mouse to place the text in the desired location. For the other object
types, click where you would like the object to begin and, while
holding the mouse button down, drag the mouse to the place
where the object is to end.
For example, to draw an arrow, click where you would like the
arrow to begin, then drag the mouse to the location where you
would like the arrow to end. The arrow is drawn as you drag the
mouse to illustrate the appearance the arrow will have when you
release the mouse button.
After creating the first object, you may continue to add objects to
the annotation. Subsequent objects continue to be added to the
annotation until a new annotation name is entered into the Anno-
tation name parameter. The annotation is an assembly which con-
tains the objects which have been added to it.
Note that the names for the annotation objects are automatically
generated.

Label User
The Label User command controls the creation and positioning of
labels for user objects. You can position the label above, below, or
to the left or right of the user object. You can also specify the x, y,
and z coordinates so that the command positions the correspond-
ing label to the screen position specified by these coordinates.
Options in the Label User command allow you to specify whether
the current Label User command operates on a user object label or
on a user object user label. A user object label is simply the name
of the user object, whereas a user object user label is any arbitrary
text.

Charsize User
The Charsize User command is used to modify the size of a spec-
ified user label.

132 Insight II/March 2000

 Command Summary

List User
The List User command displays information pertaining to the
structure and display of a user object. You can direct the informa-
tion to either the textport or a file.

Spectrum Pulldown
The Spectrum pulldown contains commands to get, put, create,
edit, and manipulate spectrums. Spectrums are used to map data
values to colors in a variety of coloring and data analysis com-
mands. They may specify very complex mappings through the use
of multiple subranges, each being either a solid color or a color
ramp. Spectrums can be translated and scaled, and their orienta-
tion and other display attributes adjusted to provide the optimal
relationship to the rest of the objects on the screen.

Get Spectrum
The Get Spectrum command is used to restore a spectrum from a
file. Spectrum save files have the extension .spect, and are created
with the Put Spectrum command.

Put Spectrum
The Put Spectrum command is used to save a spectrum to a file.
The resulting filename is the spectrum name with the extension
.spect.

Edit Spectrum
The Edit command of the Spectrum pulldown is used to invoke
the dialog boxes for spectrum creation and editing. Using these
dialog boxes you can create new spectrums with specified ranges
and colors and then edit these, or preexisting spectrums, in a
highly interactive fashion. To get help on specific Spectrum Edit
dialog boxes, press the Help button in the dialog box.

List Spectrum
The List Spectrum command displays information about the
value ranges and colors of spectrums. Wildcard specifiers are per-

Insight II/March 2000 133

4. Viewer Module

mitted in spectrum names for this command. The detail level may
be set to provide from single line output with names and overall
ranges to multiple line output with subrange values and colors.
You may redirect output from the screen to an output file if
desired.

Custom Pulldown
The Custom pulldown contains commands that assist you in exe-
cuting macro commands. A macro command is defined by you
using the Biosym Command Language (BCL). It is, in effect, a
command that combines basic commands of the Insight II pro-
gram.
In order for the Insight II program to know about a macro com-
mand, you need to define it. Typically this is done by putting the
macro command’s definition into the startup file corresponding to
the environment variable (refer to the separate Insight II Products
System Guide). Or, you may execute the Source_File command in
the Session pulldown (giving as input the name of a file that con-
tains the macro command’s definition). Then you may execute the
macro command by simply typing its name (and any parameters
that it requires). You may list the defined macro commands with
the Catalogue command in the Custom pulldown.
In addition, you may add the macro commands to any pulldown
(so that they may be executed using parameter blocks rather than
just typing the commands) with the Add_To_Pulldown command
in the Custom pulldown.

Add_To_Pulldown
The Add_To_Pulldown command allows you to add a new com-
mand to any pulldown in the currently active module. The new
command corresponds to a pre-defined macro command. These
new commands are colored red in the list of commands in the cho-
sen pulldown. In effect, the Add_To_Pulldown command gives
you a second means by which you can execute your macro com-
mands. Once a macro command is defined, it can be executed by
typing it in. By using the Add_To_Pulldown command, you auto-
matically build a parameter block for the given macro command.

134 Insight II/March 2000

 Command Summary

Thus, in addition to typing, you can use a menu to execute the

macro command.

Catalogue
The Catalogue command allows you to list out all defined macro
commands. The list appears in the textport window. It shows each
macro command (and its type) along with its parameters (and
their types). If there is no return for an item, it appeasrs in this list-
ing as "void".

Macro_Delete
This command allows you to remove a macro you previously
placed into a pulldown by sourcing a valid BCL file. You can
replace the macro by again sourcing that BCL file.

Default
The Default command allows you to specify default values for
parameters, commands, and pulldowns within each module.

Trigger
The Trigger command allows you to set which (if any) parameter
triggers the execution of a command, once that parameter is filled
in.

List_Properties
The List_Properties command allows you to list all of the system
and user defined properties currently available. The listing
includes the Prop_Name, its Origin (Sys/User), its Type (Func/
Attr), its Class (Mol/Monomer/Atom), its Return_type (Integer/
Float/Boolean/String), and if it is a Functional Type, possibly the
Macro Name. You can list all of the classes or, using the Property
Class parameter, only one. You can also print to the Textport or
output the information to a file.

Insight II/March 2000 135

4. Viewer Module

Window Pulldown
The Window pulldown contains commands that act on windows
created by the Insight II program. All of the windows created by
the program are normal top-level windows which can be manipu-
lated with the window manager. They can be raised, lowered,
closed, or iconified just like any other window. The commands in
this pulldown are intended to enhance, but not modify or replace
the existing window manager functionality. For example, it is pos-
sible to close (delete) any single window by selecting the close
option from the Window pulldown in the upper left corner of the
window’s title bar. While also providing this functionality, the
Close Window command provides the additional capability of
closing several windows simultaneously through the use of wild-
cards when specifying the window name.
Furthermore, the Window pulldown contains commands which
allow you to create and manipulate window layouts. A window
layout is used to organize a set of windows so that they may be
resized, moved, and iconified as a single unit.

Raise Window
The Raise Window command pops to the front all windows
whose names match the input string. The input string may contain
wildcard characters to allow raising more than a single window.

Lower Window
The Lower Window command pushes to the back all of the win-
dows whose names match the input string. This provides a quick
way of pushing a set of windows at one time.

Close Window
The Close Window command closes all windows whose names
match the input string. A wildcarded string may be used to close
more than a single window. Note that closing a window deletes
the window, as well as any objects which do not appear in any
other window. Since the main window of the Insight II program is
the primary focus of user interaction for the program, it may not
be closed with this command.

136 Insight II/March 2000

 Command Summary

Layout_Template Window
The Layout_Template Window command allows creation and
manipulation of layout templates. A layout template is a descrip-
tion of the relative positions and sizes of windows within a layout.
While the Insight II program provides a couple of simple default
templates, it is difficult to anticipate individual preferences for
window layouts. Therefore, this command provides the ability for
you to define new templates using the current positions of the
windows in the layout you have created. In addition, layout tem-
plates can be written to and read from files with this command, so
that you may reuse the layouts you create in future sessions.

Layout Window
The Layout Window command allows you to create and define
window layouts. A window layout organizes a set of windows so
that they can be moved, resized, and iconified as a single unit. The
layout consists of two components. The first is the layout template
which contains of a set of entries, where each entry specifies the
relative size and location of a window as a percentage of the total
size of the layout. The second component of the layout is the list of
windows which are managed by the layout. When the layout is
applied, each window is positioned and sized according to the
next unused template entry. That is, the first window in the list is
placed in the position described by the first template entry, the sec-
ond window with the second template entry, and so on until there
are either no more windows or no more template entries.
One window may be designated as a control window. This win-
dow’s position and size are used to determine the size and posi-
tion of all the other windows so that the layout template
specifications are satisfied. To move, resize, or iconify all of the
windows together, simply perform the operation on the control
window. Any window in the layout may be designated as the con-
trol window, or you can use no control window, in which case all
windows move and resize independently.

Raise_Layout Window
The Raise_Layout Window command pops to the front all win-
dows which are currently managed by the specified window lay-
out.

Insight II/March 2000 137

4. Viewer Module

Lower_Layout Window
The Lower_Layout Window command pushes to the back all of
the windows that are currently managed by the specified layout.

Close_Layout Window
The Close_Layout Window command closes a window layout.
Closing a window layout deletes the layout as well as all windows
which are managed by the layout.

Help Pulldown
There are two types of help for Insight II. Insight_Help invokes
the Help Viewer which enables browsing and printing of online
help. Pilot_Tutorials allow for interactive Insight II training ses-
sions using the Pilot program.

Insight_Help
The Help Viewer may be used to browse and to print online help.
The Help Viewer consists of a text viewing area, a row of buttons
and pulldown menus for traversing through online help, and the
Options and Help pulldown menus.
When the Help Viewer is started within Insight II, it is in follow
mode. In this mode, the Help Viewer dynamically changes to fol-
low the context of the Insight II commands being issued. This fea-
ture may be turned off by choosing the Follow toggle switch on the
Options pulldown menu.
The Go Forward and Go Backward menu items under the Options
pulldown allow you to revisit the last 10 help topics that you have
viewed. The Go Forward and Go Backward features may alterna-
tively be selected by the keyboard mnemonics Ctrl-f and Ctrl-b
respectively. This eliminates the need to open the Options menu
with the mouse.
The Print... menu item under the Options pulldown invokes a win-
dow with print options for the currently displayed help. This win-
dow is explained below.

138 Insight II/March 2000

 Command Summary

The Quit Help menu item under the Options pulldown removes
the current Help Viewer. This action has no effect on Insight II.
The keyboard mnemonic Ctrl-q may also be typed to quit from
help. This is the equivalent of opening the Options pulldown
menu and selecting the Quit Help menu item.
The Help pulldown menu contains a single menu item, Help On
Help, which displays this help text.

Traversing Help Online help may be traversed, whether or not

the Help Viewer is in "follow" mode, through the use of the but-
tons and pulldowns directly above the text area. The item farthest
to the right, excluding the "Examples" button, is a pulldown menu
containing all topics directly below the current topic in the Insight
II hierarchy. As you descend a level, the level pulldown for the
previous level is replaced with a button, and a pulldown for the
new level is displayed to its right. To return to a higher level,
choose the button of the level you wish to return to.

Print Window The print window provides various printing

options.
The Print Command is constructed from the highlighted entries
from the Printers list and the Print Commands list. If you do not
find the desired printer or command, you may edit the Print Com-
mand field by hand. The Printers and Print Commands lists are
read from the printer_info file created when Insight II is installed.
If you are missing printers or commands, talk to your system
administrator about adding them.
The Print Selection list allows you to choose at which level to
begin printing. The current level is always the bottom one, and is
the default selection.
If the Include Sub-Headings toggle button is set, all help below
the chosen selection is printed. If this toggle is off, only the
selected item is printed. The depth printing can get large very
quickly, so use it carefully.
The ASCII/PostScript toggle determines which type of output to
direct to the printer.

Insight II/March 2000 139

4. Viewer Module

Pilot_Tutorials
The Pilot tutorial sub-system displays its own help. To invoke Pilot
from within Insight II, select the Pilot_Tutorials command from
the Help pulldown menu. To view help for Pilot, select the "?" icon
from the bottom row of the main Pilot window.

Contour Pulldown (accessed from the Contour icon)

The Contour pulldown contains commands that allow you to cre-
ate and manipulate the display of contour objects and their labels.
Contour objects display values throughout a set of grid data, such
as are output by the DelPhi, DMol, or x-ray crystal refinement pro-
grams. Contours can be drawn as dots, lines, or solid surfaces, and
represent equivalent values of a given quality of a grid.
Contours created from .psv files using a revision of the Insight II
program earlier than 2.1.0 have no solid data and thus cannot be
displayed as solids. Similarly, contours created with the Get Con-
tour command have no solid data and cannot be displayed as sol-
ids.
Contours should be saved and restored using the commands in the
Session pulldown.

Get Contour
The Get Contour command retrieves contour maps from contour
files created prior to the 2.3.0 version of the Insight II program. By
using the Reference option, you can control whether or not the
Get Contour command uses an object as a reference coordinate
system when it retrieves the contours. The Get Command can
retrieve a specific contour value, or all contour values from the
contour file.
The Get Contour command defines contours as user objects,
rather than as contour objects, and thus they may not be manipu-
lated by the Contour commands. User objects created with the Get
Contour command have no solid data and can only be represented
as wireframe.

140 Insight II/March 2000

 Command Summary

Create_Single Contour
The Create_Single Contour command is used to create contours
from grid files or grid objects. The grid must be loaded before this
command can execute. When reading from a grid file, a grid object
is not created.
A contour object is created for the level selected using the slider
box connected to the Level Specification parameter. Contours are
given the name specified as the Contour Name parameter.
Contours can be created as Big_Dots, Dots, Lines, Solid contours,
or created but Undisplayed as dictated by the Display Style
parameter. In most cases the outside of a solid contour is the
lighted side, but if a solid contour appears as a dark shape, then
the normals should be inverted using the Recalculate Contour
command.
A contour created in the execution of the Create_Single Contour
command is initially given the color specified by the Color param-
eter. The color can be modified by the Color Contour command.

Create_Range Contour
The Create_Range Contour command is used to create contours
from grid files or grid objects. When reading from a grid file, a grid
object is not created.
The range of levels may be specified based on the value of the
Level Specification parameter. One contour object is created for
each level. The contours are given the name specified in the Con-
tour Name Root parameter, with a numeric suffix added to give a
unique name for each level.
Contours can be created as Big_Dots, Dots, Lines, Solid contours,
or created but Undisplayed as dictated by the Display Style
parameter. In most cases the outside of a solid contour is the
lighted side, but if a solid contour appears as a dark shape, then
the normals should be inverted using the Recalculate Contour
command.
Contours created by the Create_Range Contour command are
given one of six unique color specifications. These colors can be
modified by the Color Contour command.

Insight II/March 2000 141

4. Viewer Module

Clip_Display Contour
The Clip_Display Contour command controls the clipping and
display of contour objects. Various options of this command allow
you to clip contours using planes, boxes, or spheres in fractional
space and Cartesian space.

Color Contour
The Color Contour command modifies either the color of the spec-
ified contour, or the color of the specified contour’s label. You can
choose one of the predefined colors, such as blue, green, red, cyan,
yellow, magenta, or white. Or, you can specify a blend of these col-
ors or define a color hue.

Transparency Contour
The Transparency Contour command is used to adjust the degree
of transparency in the solid display of a contour. This is accom-
plished by setting the alpha component of all colors in the contour
without affecting the red, green, blue values. See the Use of Color
section in the Introduction to the Insight II User Guide for more
information on color specification, alpha values, and transparency.
A Transparency Value of 0.0 means fully transparent, and a Trans-
parency Value of 1.0 means fully opaque.

Recalculate Contour
The Recalculate Contour command is used to change the contour
level, the normals of solid contours, or the display style of a con-
tour. A new contour level can be selected using the slider box con-
nected to the Level Specification parameter. Solid contours have a
lit and a dark side which can be controlled by the Flip_Normals
parameter. The Display_Style of contours may be Big_Dots, Dots,
Lines, Solid surfaces, or Undisplayed.

Label Contour
The Label Contour command controls the creation and position-
ing of labels for contours. The object name of the contour becomes
the contents of the label. You can position the label above, below,
to the left of, or to right of the object. You can also specify the x, y,
and z coordinates for any Label Contour command, which then

142 Insight II/March 2000

 Command Summary

positions the corresponding label to the screen position specified

by these coordinates. This label is dynamic, and moves with the
contour itself.

Charsize Contour
The Charsize Contour command modifies the size of the specified
contour's label.

List Contour
The List Contour command displays information pertaining to the
structure and display of a contour. Information in the listing
includes the fractional space limits available for display, and the
fractional limits currently displayed. You can direct the informa-
tion to either the textport or a file.

Spreadsheet Pulldown
When you pick the Spreadsheet icon, a menu with fourcommands
appears. Picking the Spreadsheet icon is equivalent to picking the
Spreadsheet pulldown from the lower menu bar, in modules
where that option is available.

New Command
The New command creates a new empty spreadsheet.

New_Molecule Command
The New_Molecule creates a new spreadsheet for a selected mol-
ecule.

Open Command
The Open command gets information from disk in various file for-
mats to create a new spreadsheet. The file types include the MSI
ASCII format for graphs, and a neutral ASCII table format used by
other spreadsheets.

Insight II/March 2000 143

4. Viewer Module

Put Command
The Put command writes out the table data to an ASCII file that
can be printed, viewed, and/or edited. The data are written to a
file with the .tab format. Each table cell value is separated by tabs.

Spreadsheet Command Summary

The commands within a Spreadsheet are organized into pulldown
menus which are consistent with most other spreadsheet pro-
grams: File, Edit, Data, Format, and Plot. In addition, three icons
at the bottom of the spreadsheet window provide direct access to
the three spreadsheet Plot commands: Graph, XYZ_Graph, and
Histogram.

New File The New command creates a new empty spreadsheet

within a new window.

Open File The Open command gets information from disk in

various file types to fill the present spreadsheet. The file types
include: the two MSI ASCII formats .tbl and .tab, and the neutral
ASCII formats for Wingz and Excel (which should actually be the
same as .tab). The file type and the name of the file are stored for
use by any subsequent Save commands.

Save File The Save command writes the spreadsheet to a file

using the last values for file type and filename used by Open or
Save_As. Therefore, this command will not work unless preceded
by a Save_As or Open command. Various formats are supported
including: the two MSI text formats (.tab and .tbl), and a free for-
mat that simply outputs columns of information separated by a
user specified delimiter.

Save_As File The Save_As command writes the selected cells to

the specified file. Various formats are supported including the two
MSI text formats (.tab and .tbl).

Duplicate File The Duplicate command creates a new spread-

sheet that is identical to the present one. This is effectively a Copy
Object command.

144 Insight II/March 2000

 Command Summary

Transpose File The Transpose command changes the table dis-

play so that information that is displayed down a column is re-ori-
ented to be displayed across a row and vice-versa

Print File The Print command creates hardcopy output of the

selected cells by writing this information in ASCII format to disk.
No formatting information is used in preparing this output.

Edit
The Edit pulldown contains those commands used to modify the
spreadsheet, including changing the values of the stored data and
adding formula(e).

Cut Edit The Cut command removes the values of the selected
cells from the spreadsheet, placing them within the global clip-
board.

Copy Edit The Copy command duplicates the values of the

selected cell region and then places them in the global clipboard.

Paste Edit The Paste command uses values previously placed

within the clipboard to sequentially replace the values of those
cells selected. If there are more cells selected then there are values
within the clipboard, then the sequence is restarted at the begin-
ning of the clipboard selection.

Clear Edit The Clear command resets the Value, or Format, of

the selected cell region to empty. Using this command in conjunc-
tion with the Search command constitutes a filter operation.

Find Edit The Find command takes the selected cell region and
modifies the selection to represent only those cells whose value
falls within the specified constraints.

Select Edit The Select command allows the user to create a

selection that is used throughout the spreadsheet. This selection is
highlighted to indicate the members of the set. (NOTE: This com-
mand is redundant with the mouse driven selection using the
"ragged" selection methods, but is very useful for writing macros.

Insight II/March 2000 145

4. Viewer Module

This is also a fall back position if the mouse driven selection cannot
be completed.)

Insert Edit The Insert command allows the insertion of columns

or rows of cells at the position of the selected cells described. The
extents of the selected region will control the number of rows or
columns added.

Delete Edit The Delete command allows the deletion of the

selected cell region as described. Currently, this region encom-
passes one or more rows or columns.

Fill Edit The Fill command allows the user to supply a single
value to all cells, or a range of values in linear and non-linear pro-
gression. The row or column major application of the range to the
selected cells is controlled by the Preference Format command.

Data
The Data pulldown contains those commands to manipulate or
make inquiries about the data within the spreadsheet.

Formula Data The Formula command fills a row, column, or

single table_cell to represent the evaluation of the expression spec-
ified. This allows the user to apply the expression to multiple cells
at once instead of requiring multiple copy and paste operations
over a set of table_cells. This formula represents the mathematical
combination of existing information within the spreadsheet.

Search Data The Search command processes the selected cells

and modifies the selection to represent those rows or columns
which contain cells whose value falls within the specified range.

Sort Data The Sort command shuffles the selected rows/col-

umns into ascending or descending order depending on the key
row(s)/column(s) that are supplied.

Summary Data The Summary command displays simple statis-

tics about the specified rows/columns. These include the mini-
mum and maximum values, the average and standard deviation,
and the median value.

146 Insight II/March 2000

 Command Summary

Highlight Data For spreadsheets created with Decipher, the

Highlight command displays a link between graphs, tables, and
molecules using color, allowing you to visualize what information
was used to create the display.

Recompute Data The Recompute command recalculates the

active spreadsheet. This can be made to be automatic so that any
change in spreadsheet values can trigger the automatic reevalua-
tion of all formulas.

Format
The Format pulldown contains those commands to modify how
the spreadsheet is viewed. It also includes commands describing
how the spreadsheet is manipulated (such as row major versus
column major).

Color Format The Color command changes the color of the

selected cells. A single color value is specified.

Cell_Border Format The Cell_Border command changes the

border display of the selected cells. There are four borders for a cell
(top, bottom, right, and left) that can be displayed or undisplayed
independently.

Display Format The Display command allows the user to either

Hide cells, or Show previously hidden cells. The user must specify
whether either the rows or the columns are modified.

Style Format The Style command controls the Value_Type and

format of the display of the values in the selected cells. You can
control the justification (Left, or Right) of the value as well as the
Length and precision of the display. This does not have any effect
on the actual data stored within the spreadsheet.

Column_Width Format The Column_Width command changes

the width of the selected columns.

Row_Height Format The Row_Height command changes the

height of the selected rows.

Insight II/March 2000 147

4. Viewer Module

Protection Format The Protection command controls the pro-

tection of the Value or of the Value_Type of the selected cells. This
protection can be turned On or Off.

Preference Format The Preference command specifies

whether icon plotting and other operations are treated row or col-
umn major.

Graph Plot
The Graph command creates or adds to an existing graph a set of
plots using each column (or row if the preference is row major).
The set of plots created are oriented in 3D based on the plot num-
ber.

Bar Graph The BarGraph command creates, or adds to an exist-

ing graph, a set of plots using each selection column (or row, if
preference is row major). The set of plots created are oriented in 3D
based on the plot number and are represented as solid bars. With
a dynamic table (INTERACTIVE) bar graphs are dynamically
updated, as well.

XYZ_Graph Plot The XYZ_Graph command creates or adds to

an existing graph, a row/column vs. row/column graph on the X
and Y axes that can optionally contain a Z axis.

Histogram Plot The Histogram command creates, or adds to an

existing histogram, a description of the distribution of the selected
cells in a bar chart (histogram). You can specify the intended range
of the data and control the number of bars (or bins) over which the
data is distributed.

Viewer Tutorials
As of this release, most tutorials are now available online for use
with the Pilot interface. To access the online tutorials for the
Viewer module, click the mortarboard icon in the Insight II inter-
face.

148 Insight II/March 2000

 Viewer Tutorials

Then, from the Open Tutorial window, select Insight II tutorials,

then the Viewer module and choose from the list of available les-
sons:
Lesson 1 Basics
Lesson 2 Macros and Source Files
Lesson 3 Annotation
Lesson 4 Symmetry Operations
Lesson 5 Using Subsets
Lesson 6 Windows and Window Layouts
Lesson 7 Biosym's Spreadsheet
Lesson 8 Atom Selection Tutorial
Lesson 9 Use of Background Job Commands
You can access the Open Tutorial window at any time by clicking
the Open File button in the lower left corner of the Pilot window.
For a more complete description of Pilot and its use, click the on-
screen help button in the Pilot interface.

Insight II/March 2000 149

4. Viewer Module

150 Insight II/March 2000

5 Builder Module

The Builder command, typed at the command prompt or selected

from the Module pulldown, activates the Builder module. This
module allows you to construct new molecules from molecular
fragments or individual atoms. It also allows you to modify such
properties as atom type, hybridization, potential function param-
eters, bond order, and geometry of existing molecules. You can use
the newly created or modified molecules in all of the normal ways
throughout the Insight II program.

Command Summary
In addition to the core pulldowns in the top menu bar, the Builder
module adds pulldowns to the lower menu bar. The pulldowns
are Atom, Fragment, Modify, Forcefield, Pseudo_Atom, and
Optimize. (The Sketch pulldown and the Toolbox comprise the
Sketcher product, licensed separately and documented in the next
chapter.)

Atom Pulldown
The Atom pulldown is used to modify molecules at the atomic
level.

Charge Atom
The Charge Atom command is used to set or alter partial or formal
atomic charges. This command sets discrete user supplied charge
values for specified atoms. It does not perform any type of overall
charge assignment. The charges for an entire molecule can be com-
puted using the Potentials command, which is accessed from the
Forcefield icon.

Insight II/March 2000 151

5. Builder Module

Hybridization Atom
The Hybridization Atom command is used to change the hybrid-
ization of a molecule by adding or deleting hydrogen atoms as
needed, and modifying the molecular geometry accordingly. The
level for hybridization may be specified, or calculated automati-
cally by the Insight II program. The Hybridization Atom com-
mand can also be used to add hydrogens to fill unfilled values, as
determined by existing bonds and geometry. In this mode of oper-
ation, the desired hybridization is ascertained by looking at
explicit bond orders first, if the hybridization is still ambiguous
after looking at bond order the geometry of the atom and its sur-
rounding environment will be used. By default, the Insight II pro-
gram fills valences to a neutral state. Using this command, this
mode is equivalent to the Hydrogens command in the Modify
pulldown. The program never changes the actual bond orders of
any bonds. It is left to the user to make sure that the bond order
and geometry are consistent.
The naming scheme for hydrogens is as follows:

• If one hydrogen is bonded to X, it is HX; if two,

they are HX1 and HX2.

• If one hydrogen is bonded to XA, it is HA; if

two, they are HA1 and HA2.

• If one hydrogen is bonded to XD1, it is HD1; if

two, they are HD11 and HD12.
Any hydrogens bonded to X1 are named H1n, where n is the rela-
tive number of the hydrogen being bonded to the heavy atom. Any
hydrogens bonded to X11 are named H11n, where n is the relative
number of the hydrogen being added. Any hydrogens bonded to
X111 are named Hseq., where seq is the relative number of the
hydrogen in the residue containing the heavy atom.
The addition of any hydrogen to a residue causes a look-up to be
done in the currently defined residue library. The residue library
used for the look-up is the one pointed to by the environmental
variable RESIDUE_LIBRARY, in the directory pointed to by the
environmental variable BIOSYM_LIBRARY. A match occurs when
a residue has the same number of atoms as an entry in the library
with the identical atom names. The atoms do not have to be in the
same order; bond orders are not used when the look-up is done. If

152 Insight II/March 2000

 Command Summary

a match occurs, the residue inherits the residue type, partial

charges, and potential types of the template.
Optionally, lone pairs can be added along with the hydrogens.

Planar Atom
The Planar Atom command is used to set or unset the out-of-plane
flag for an atom. Out-of-plane atoms are used by the Discover pro-
gram to mark atoms that are to be constrained to lie in the plane of
the three atoms it is bonded to. You rarely need to use this com-
mand because the Insight II program automatically keeps track of
out-of-plane atoms.

Potential Atom
The Potential Atom command is used to set or change the poten-
tial function type for an atom, according to the assigned forcefield
library. This command is used to manually change the potential
function types of individual atoms. The Potentials command in
the Forcefield pulldown can be used to automatically set the
potential function atom types for an entire molecule. The available
potential function atom types in this command are taken from the
forcefield library, which is defined by the environment variable
FORCEFIELD and is in the directory defined by the environment
variable BIOSYM_LIBRARY.

Delete Atom
The Delete Atom command is used to delete an atom from a mol-
ecule. If a heavy atom is deleted, all bonded hydrogens are also
deleted. No attempt is made to fill valences left open by the dele-
tion. When the last atom of a molecule is deleted, the molecule
itself is deleted.

Replace Atom
The Replace Atom command is used to change the element type
of an atom. Connected hydrogens are removed appropriately. The
Insight II program allows the replacement of atoms that result in
valences being exceeded. For example, an sp3 carbon with three
ligands can be replaced by an oxygen. The deletion of the extra
bond is left for the user to do.

Insight II/March 2000 153

5. Builder Module

Rename Atom
The Rename Atom command is used to change the name of an
atom. Insight II requires that all atom names in a molecule be
unique. This command allows you to explicitly change the name
of individual atoms.

List Atom
The List Atom command lists information about a specified atom,
including the atom name, element type, coordinates, sequence
number, and connected atom sequence numbers. Additional infor-
mation can be displayed, including the group name, potential
function type, fractional space coordinates, charge, switch and
out-of-plane flag values. The information is listed tp the textport or
is output to a file.

Fragment Pulldown
The Fragment pulldown is used to maintain the fragment library,
create or modify a fragment, or repeat the fragment to create a
polypeptide or polymer.

Get Fragment
The Get Fragment command is used to create a molecule by copy-
ing a fragment from the fragment library. This command also dis-
plays the contents of the fragment library in a separate window.
You can configure which fragment libraries to display via the Frag-
ment Libraries... button. Once a molecule has been created with
this command, it can be modified and manipulated just as a mole-
cule from any other source. The available categories for storing
and retrieving a fragment are Aminos, Atoms, Groups, Hydrocar-
bons, Rings, Metal templates, Metal ligands, Cage Clusters, Metal
Complexes, and User.

Put Fragment
The Put Fragment command is used to add a newly-defined frag-
ment to the fragment library, or replace an existing fragment in the
fragment library. Once a fragment is added, it appears in the frag-

154 Insight II/March 2000

 Command Summary

ment display of the Builder module. New fragments are added at

the end of the list of the fragments of that type.
The available categories for storing and retrieving a fragment are
aminos, atoms, groups, hydrocarbons, rings, metals, ligands, and
user. Before storing a fragment, you might want to minimize its
geometry, or adjust its potentials and charges.
You may need your own copy of the fragment library to be able to
use the Remove Fragment command. Lesson 4, part 2, of the
Bioploymer tutorials includes information on setting up your own
fragment library.

Remove Fragment
The Remove Fragment command is used to remove a fragment
from the fragment library.
You may need your own copy of the fragment library to be able to
use the Remove Fragment command. Lesson 4, part 2, of the
Bioploymer tutorials includes information on setting up your own
fragment library.

Define Fragment
The Define Fragment command is used to make a molecule,
which may itself contain multiple fragments or monomer/resi-
dues, into a fragment suitable for
addition to the fragment library or for polymerization via the
Repeat command. During the process, the molecule is collapsed
into a single monomer/residue. If the fragment is to be repeated,
and head and tail atom must be identified.

Repeat Fragment
The Repeat Fragment command is used to create polypeptides or
polymers by repeating an amino acid, monomer, or existing
polypeptide or polymer that has forward and backward bonding
hydrogens defined. An optional dihedral angle for the bond cre-
ated may be given.

Insight II/March 2000 155

5. Builder Module

Delete Fragment
The Delete Fragment command is used to delete a single frag-
ment, residue, or monomer from a molecule. No change is made to
the geometry of the portion of the molecule which remains. In the
case that the molecule is a single monomer or residue as in the case
of a fragment or repeat unit, the whole molecule is deleted. An
energy minimization may be used to readjust the geometry of the
molecule in the cases where a nonphysical situation occurs.

List Fragment
The List Fragment command lists the coordinate and topology
details for a specific repeat unit, fragment, or residue. Using this
command, you can also list molecular mechanics information such
as partial charges and potentials.

Modify Pulldown
The Modify pulldown contains various commands for modifying
molecular structures.

Bond
The Bond command is used to create, delete, or modify intermo-
lecular and intramolecular bonds.
Intermolecular bonding requires choosing two atoms, usually
hydrogens, that are lost when the bond is created. When intermo-
lecular bonding is done, the smaller of the molecules is reposi-
tioned so as to make the length and geometry of the bond
reasonable. If a peptide bond is created via intermolecular bond-
ing, its bond order automatically is set to partial double. The bond
lengths used by the Insight II program are specified in the file ele-
ments.dat, which is located in the Insight II program’s help direc-
tory. This file is read each time the Insight II program is run, and
can be modified by the user.
For intramolecular bonding, the bond is created directly between
the specified atoms. When possible, the Insight II program deletes
hydrogens that would cause valences to be exceeded when the
bond is formed. The program allows heavy atom valences to be
exceeded temporarily while bonding. These inconsistencies must

156 Insight II/March 2000

 Command Summary

be corrected by the user before potential function atom types can

be assigned.
Bonds can be specified with atoms in fragments or repeat units. A
copy of the fragment is made automatically and the bond created
to it. The copied fragment is positioned as to the make the bond
length and geometry reasonable.
When the Bond command is used to break an existing bond
between two atoms, the program does not attempt to fill open
valences created when a bond is broken. Open valences can be
filled by adding alternative bonds or adding hydrogens.
The Bond command can also be used to modify the bond order of
a single bond or determine appropriate bond orders for an entire
molecule. The Insight II program uses a very simple scheme for
determining bond orders; it recognizes planar rings and carbonyl
groups. The program does not try to determine conjugation.
Hydrogens can be added or deleted to maintain the correct
valence for the bonded atoms.

Fuse_1
The Fuse_1 command is used to create fused ring systems by per-
forming intramolecular fusion of a pair of heavy atoms. The fusion
is performed by connecting all the bonds of the second heavy atom
to the first heavy atom, then deleting the second atom. After all the
bonds from the second atom have been added to the first atom,
hydrogens that violate the heavy atoms valence are deleted. The
Fuse_1 command is also useful for cleaning up any unfused pairs
remaining after a 2- or 3-pair fusion.

Insight II/March 2000 157

5. Builder Module

Before
1
2

After

Figure 18. Example of the Fuse_1 command

Heavy atoms labeled 1 and 2 are picked to create the struc-
ture shown at the bottom.

Fuse_2
The Fuse_2 command is used to create fused ring systems by fus-
ing component rings together intermolecularly. Two atoms (usu-
ally heavy), are used in each of the two molecules to identify the
atom used for superposition. A third atom in each molecule is
picked that defines a plane using the first two atoms picked. The
fusion is accomplished by superimposing the second molecule or
fragment on the first, such that the first two pairs of atoms picked
are coincident. The molecules or fragments are then merged. The
atoms that comprised the second molecule or fragment are then
rotated to bring the alignment atom into the same plane as the
alignment atom of the first molecule or fragment. The two pairs of
atoms used for superposition are fused, then, any atom pairs
brought within .5 Å of one another by the superposition are fused.

158 Insight II/March 2000

 Command Summary

Hydrogens that violate the valence of an atom are deleted from all
heavy atoms that were fused.

1 2 6
A
3 4

θ
B

Figure 19. Example of 2-pair Intermolecular Fusion

Figure 19 illustrates the creation of cap-decalin by fusing two

cyclohexanes. The resulting molecule is created by first picking
atoms 1, 2, 3, and 4 successively. This identifies the atoms used for
the superposition of the second molecule onto the first
(Figure 19a). Next, atoms 5 and 6 are picked which identify the
atoms which will be used for alignment rotation. The second mol-
ecule is then rotated through θ (Figure 19b is the angle between the
planes formed by atoms 5, 1, and 3, and 2, 4, and 6. Finally, coinci-
dent heavy atoms are fused (Figure 19c).

Insight II/March 2000 159

5. Builder Module

Fuse_3
The Fuse_3 command is used to create fused ring systems by fus-
ing component rings together intermolecularly. Three heavy
atoms in each molecule are usually used to identify three pairs of
atoms used for superposition. The fusion is accomplished by
superimposing the second molecule or fragment on the first such
that the pairs of fusion atoms are coincident. The molecules or
fragments are merged, then the specified pairs are fused. Any
other atom pairs brought within .5 Å of one another by the super-
imposition are also fused. Hydrogens that violate the valence of an
atom are deleted from all heavy atoms that were fused.

Before
pair 1

pair 2

pair 3

After

Figure 20. Example of 3-pair Fusion

Figure 20 illustrates the creation of a triphenyl unit using the

Fuse_3 command to fuse napthalene and benzene together. The
triphenylene was created by picking atom pairs 1, 2, and 3.

160 Insight II/March 2000

 Command Summary

Fuse_Close
The Fuse_Close command is used to fuse all the close atoms
(atoms within 0.5 Å of each other) either in one molecule, or
between two molecules. Close atom fusion between two mole-
cules results in the second being merged into the first, and then all
close atoms being fused. No superimposition is done. Hydrogens
that violate the valence of an atom are deleted from all heavy
atoms that were fused.

Before

molecule 1 molecule 2

After

Insight II/March 2000 161

5. Builder Module

Figure 21. Example of Close Atom Fusion

Figure 21 above illustrates the creation of a corenene molecule by

fusing two anthracene molecules. The corenene molecule is cre-
ated by first manually superimposing one of the anthrazenes. The
final molecule is then created using the Fuse_Close command.

Hydrogens
The Hydrogens command automatically adds hydrogens or lone
pairs to entire molecules. This command can also be used to add
hydrogens to fill unfilled valences, as determined by existing
bonds and geometry. In this mode of operation, the desired
hybridization is ascertained by looking at explicit bond orders
first. If the hybridization is still ambiguous after looking at bond
order the geometry of the atom and its surrounding environment
is used. By default, Insight II fills valences to a neutral state. Insight
II never changes the actual bond orders of any bonds. It is up to
you to make sure that the bond order and geometry are consistent.
This command also allows you to add hydrogens based on a target
pH for the solution. During pH based hydrogenation, the number
of hydrogens to be added for an atom is decided by doing a look-
up of the residue in the currently defined residue library. The res-
idue library used for the look-up is the one pointed to by the envi-
ronmental variable RESIDUE_LIBRARY, in the directory pointed
to by the environmental variable BIOSYM_LIBRARY. A match
occurs when either of following two conditions are met:
♦ pH of residue < abs( pKa of residue in library ) and pKa of res-
idue in library < 0 .
♦ pH of residue ≥ abs( pKa of residue in library ) and pKa of res-
idue in library > 0.
If a match occurs, the atom inherits the number of hydrogens of
the same atom in the template. Otherwise, valences are filled to a
neutral state.
The naming scheme for hydrogens is as follows:
♦ If one hydrogen is bonded to X, it is HX; if two, they are HX1
and HX2.

162 Insight II/March 2000

 Command Summary

♦ If one hydrogen is bonded to XA, it is HA; if two, they are HA1

and HA2.
♦ If one hydrogen in bonded to XD1, it is HD1; if two, they are
HD11 and HD12.
In addition, you can specify to rename the hydrogen atoms in
sidechains of amino acid residues to conform to IUPAC nomencla-
ture rules, by turning the Assign_IUPAC_Names parameter On.
To resolve any name conflicts, hydrogens are prefixed with the
bonded heavy element name, e.g., hydrogens bonded to C3´ and
O3´ are H3´ and HO3´.
Any hydrogens bonded to X1 are named H1n, where n is the rela-
tive number of the hydrogen being bonded to the heavy atom. Any
hydrogens bonded to X11 get named H11n, where n is the relative
number of the hydrogen being added. Any hydrogens bonded to
X111 get named Hseq, where seq is the relative number of the
hydrogen in the residue containing the heavy atom.
The addition of any hydrogen to a residue causes a look-up to be
done in the currently defined residue library (described above). A
match occurs when a residue has the same number of atoms as an
entry in the library with the identical atom names. The atoms do
not have to be in the same order; bond orders are not used when
the look-up is done. If a match occurs, the residue inherits the res-
idue type, partial charges, and potential types of the template.
For protein molecules, the Capping Mode parameter determines
whether the termini are capped by the Modify/Hydrogens com-
mand. In addition, the termini can be capped with charged or un-
charged capping groups.

Merge
The Merge command combines two molecules into a single mole-
cule. The separate atom and monomer/residue lists are merged
and henceforth treated as a single object. Note that Merge is differ-
ent from the Associate command, in which the two molecules are
maintained as two separate objects.
Replicates created by the Symmetry command can also be merged
into other molecules. Since replicates are dependent on the given
symmetry operation and state of the molecule that derived them

Insight II/March 2000 163

5. Builder Module

(i.e., the asymmetric unit), special steps are necessary to not break
the symmetry relationship of replicates with the asymmetric unit.
Replicates cannot be merged into the asymmetric unit because this
operation would break the symmetry relationship of the repli-
cates; however, the replicates can be merged into a copy of the
asymmetric unit. To merge replicates back into a molecule that cre-
ated the replicates, perform the following steps:
1. Make a copy of the asymmetric unit molecule by using the Copy
Object command.

2. Use the Merge command and reference the newly-created Copy

molecule for the Molecule Name parameter.

3. Use a given replicate for the Molecule_to_Merge parameter.

By using a copy of the asymmetric unit, the symmetry is preserved

as well as the integrity of the original asymmetric unit. Additional
symmetry operations can then be performed on the original asym-
metric unit without affecting the molecule copy containing
merged replicates.

Unmerge
The UnMerge command allows you to create a new molecule by
extracting a piece from an existing molecule. The piece to be
unmerged must not be bonded to any atoms of the part(s) that are
to remain in the original object. The UnMerge command can be
used to make a separate molecule out of one subunit of a protein
complex, for example.

Geometry
The Geometry command is used to modify distances, angles, and
dihedrals in and between molecules. Distances can be modified
between bonded or unbonded atoms not connected by rings.
Angles can be set between any three atoms not connected by rings.
Dihedrals can be set between four atoms not connected by rings;
however, they must all be in the same molecule.

164 Insight II/March 2000

 Command Summary

Ring_Conf
The Ring_Conf command is used to interactively modify the
geometry of rings in molecules without breaking a bond. A frag-
ment of a ring, which is specified by two anchor atoms, can be
moved up and down relative to the ring plane.
There are two types of operations you can perform. The first one is
called flipping. In this operation, the ring is flipped using the neg-
ative value of the current plane angle. A typical example is flip-
ping a cyclohexane ring from chair to boat conformation, or vice
versa.
The second operation is called flapping. In this operation, you spec-
ify the angle to apply either by typing in the value (in degrees) or
by using the valuator. In the latter case, the molecule’s structure is
changed interactively. Once you select Execute, the molecule
adopts the displayed conformation. If you select Cancel instead,
the original structure is restored.
You specify the moving fragment by selecting two anchor atoms.
These atoms must be in the same and in a unique ring, and there
must be at least one atom separating them. The side of the ring
containing fewer ring atoms is the moving fragment. If both sides
contain the same number of atoms, the fragment connecting to
fewer atoms is moved.
The plane angle is defined by two ring planes formed by the
anchor atoms and the two fragments. Each ring plane is defined by
three points:
1. The coordinate of anchor atom 1;
2. The coordinate of anchor atom 2;
3. Either:
a. If there is only one ring atom between atom 1
and atom 2, the coordinate of this atom.

b. If there is more than one atom separating the

two anchor atoms, the coordinate which is the
center of the two ring atoms connecting to
atom 1 and atom 2.

Insight II/March 2000 165

5. Builder Module

The moving fragment is flapped by rotating two bonds connecting

the anchor atoms on the fixed fragment.

Invert
The Invert command is used to invert the chiral sense of an atom
in an existing molecule or one that is being built. Inverting the
chirality about an atom is accomplished using a 180° rotation
around the axis defined as the mid-vector of the two bonds to be
inverted (see Figure 22). To invert chirality, choose the atom that is
the chiral center and two bonded atoms that specify the atoms to
be inverted. Chirality inversion can be done even if the two
bonded atoms are connected to each other in a ring, but cannot be
done if either is connected back to the chiral atom via another path.
Atoms in templates cannot be changed with the Invert command.
The chirality of the central atom is inverted by picking atoms 1, 2,
then 3, using the Invert command.

Before
1 3
180

switch switch
2
atom atom

chiral
atom

After

166 Insight II/March 2000

 Command Summary

Figure 22. Inversion of a Chiral Center

Reflect
The Reflect command generates the mirror image of a molecule.
This is done by changing the sign of either the x, y, or z coordinates
of all atoms of the molecule. The choice of which coordinate is
reflected is controlled by the Reflection Axis parameter. For exam-
ple, setting this parameter to X causes all the x coordinates in the
molecule to change sign, thereby effectively reflecting the mole-
cule along the x axis or, equivalently, in the yz plane.
In addition, the molecule’s transform is altered such that the mol-
ecule’s center of mass screen location is unchanged, and so that its
center of rotation undergoes the same reflection as the molecule
itself.

Element
The Element command is used to define elements and their
attributes. Explicit bond lengths between pairs of elements can be
defined. If the element specified is already defined, the defaults for
the parameters are the current values for that element.
The attributes of an element that can be modified include the van
der Waals radius, covalent radius, maximum valence, minimum
valence, and common valence. The common valence is defined as
the valence that results in a neutral state. The van der Waals radius
is used for van der Waals overlap checking, and surface and CPK
generation. The covalent radius is used for determining bond
lengths when explicit bond lengths are not known. The maximum
and minimum valences are used when adding and deleting hydro-
gens. The original definition of an element is made in the file ele-
ments.dat, which is located in the help directory ($INSIGHT_
HELP).

Atom_Position
The Atom_Position command allows you to move an atom to a
new coordinate position manually. You can move the atom to a
new position in either the world coordinate system or within the
coordinate space of the object to which the atom belongs. Move-

Insight II/March 2000 167

5. Builder Module

ment can be specified relative to the atom’s current location or rel-

ative to the absolute coordinates in the chosen space. Any bonds to
the atom are adjusted without affecting the accompanying atoms.

Forcefield Pulldown
The Forcefield icon is the “FF” icon. This pulldown contains com-
mands to fix, check, or accept the potential atom types and partial
charges of a molecule, to fix or accept formal charges of a molecule,
and to select a new forcefield type. It also contains the commands
to perform charge group validity checks and editing. These com-
mands are used to assign partial charges and potential function
atom types to molecules for energy calculations by either the
Insight II or the Discover program.

Select
The Select command allows you to determine the current force-
field type, select a new forcefield, or copy the forcefield file with-
out exiting your current session.
The Copy option of the Select command allows you to make a pri-
vate copy of the forcefield file and the associated rule file and res-
idue library so that you can modify it using the forcefield editor,
invoked by the Forcefield/Tabulate command.
The Select command automatically resets the FORCEFIELD,
RESIDUE_LIBRARY, and INSIGHT_POTENTIAL_TEMPLATES
environment variables each time you select a new forcefield. How-
ever, these variables revert to their original values defined prior to
the current Insight II session. Therefore, all changes to these vari-
ables apply to the current session only. The selected forcefield is
displayed in the lower left corner of the screen, beneath the dial
boxes.
Since the potential atom types and/or charges associated with the
previously built molecules may not be compatible with the force-
field, the Select command allows you to erase all of the previous
atom type and charge assignments.

168 Insight II/March 2000

 Command Summary

Potentials
The Potentials command is used to check, fix, or accept the poten-
tial function types of the atoms in a molecule.
This command is automatically activated when you leave the
model-building module (in which Forcefield appears) if there are
any molecules with inconsistent potential function atom types.
Most operations performed in a model-building module change
the model and necessitate reassignment of the potential function
atoms types. Potential function atom types must be assigned
before charges can be assigned. Potential function atom types
must be assigned prior to running a simulation with the Discover
program.
The Insight II program assigns potential types by looking at an
atom and its surrounding environment. The potential function
atom type assignment rules reside in an external file to facilitate
potential function atom type assignment to any forcefield. When
assigning potential function atom types, Insight II first looks for
matches in the currently assigned residue library. If a match is
found, the residue library entry is used to assign the potential
function atom types. If a match is not found, the program looks for
an entry in the potential template rule file. The potential template
rule file describes the chemical environment using a SMILES-like
language. You may add new potential function atom types by
making additions to the template rules file (refer to the Potential
Template Rules appendix for a complete description on how to
add rules to the template rules file). A rule file is provided for each
forcefield. As potential atom types are changed, this information is
reported to the information area and the textport. You should also
note atoms that could not be assigned a potential type, which are flagged
with a question mark (?). These atoms did not pass any potential template
tests, and are not usable in Discover program simulations. The appro-
priate forcefield file must also have been defined before running
any simulations.
The out-of-plane values are assigned for each atom based on the
rules in the Potential Template Rules appendix.

Groups
The Groups command is used to edit or perform validity checks
on charge groups. Potentials and charges for the atoms must be

Insight II/March 2000 169

5. Builder Module

fixed or accepted prior to Groups command execution. Also,

objects that are animated or contain active torsions cannot have
their charge groups edited.
The validity checks that are currently performed on the charge
groups are:
Charge Group Formal (int +- tolerance) Charge,
Single Switching Atom, and
Charge Group Sum (for Monomer and Molecules) Formal Charge,
The Edit enumerated choice of the Charge Group Action param-
eter enables you to assign atoms to charge groups as well as to
assign switching atoms.

Assign_CFF Forcefield
The Assign_CFF command is used to assign the CFF force field.
The corresponding atom types and partial charges are assigned if
“Fix” is set for Potential_Action and Partial_Chg_Action (this is
the default). Therefore, unlike “Select” command in the Forcefield
pulldown, after Assign_CFF, it is not necessary to use the “Poten-
tial” command to assign potential functions.

Tabulate Forcefield
The Tabulate Forcefield command creates the table of a Forcefield
previously loaded using the Select Forcefield command. It allows
browsing, editing, and analyzing of Forcefield parameters. In
addition to the Search, Sort, and Summary commands in the Data
pulldown of the spreadsheet, browsing of Forcefield parameters is
controlled by the View Data command (or the View button), and
updating by the Update Data command (or the Update button).
Editing is performed using spreadsheet operations. The modified
table can be saved as a new Forcefield file using Save_As File
command (or the Save button) in Forcefield table for use in Dis-
cover or CHARMm.

Forcefield Support
The Insight II program supports the CFF91 forcefield, the CVFF
forcefield, the AMBER forcefield, CHARMm, and the ESFF force-
field, specified through the Forcefield/Select command. Insight II

170 Insight II/March 2000

 Command Summary

also supports the CFF forcefield, which is licensed separately.

These environment variables are set:
BIOSYM_LIBRARY Points to the directory which contains the
rule files, residue libraries, and forcefield
files
RESIDUE_LIBRARY Points to the residue library currently be-
ing used for potential function atom type
assignments. The default is cvffa.rlb.
INSIGHT_POTENTIAL_TEMPLATES
Points to the potential template rule file
being used for potential function atom
type assignment when a match cannot be
found in the residue library. The default
is cvff_templates.dat. If this environment
variable is not defined, the Insight II pro-
gram uses the hard-coded rules consistent
with the CVFF forcefield.
FORCEFIELD Points to the forcefield file being used for
element type look-up and bond-incre-
ment look-up. This file must be consis-
tent with the currently assigned residue
library and template rule files.

Pseudo_Atom Pulldown
The Pseudo_Atom pulldown contains commands to create and
modify pseudoatoms. It contains the following commands:
Define, Rename, Delete, and List.
Pseudoatoms are defined as the instantaneous average of the coor-
dinates of a set of real atoms. For example, the centroid of a phenyl
group could be displayed as a pseudoatom created from the six
carbon atoms in the ring. Pseudoatoms are referenced in the same
way as atoms: their names can be explicitly specified at the time of
their creation or can be generated automatically.
In the DeCipher and Analysis modules, pseudoatoms can be
defined and used to study geometric properties. In the DeCipher
module, pseudoatoms can be used in conjunction with the com-
mands in the Functions and Geometrics pulldowns to plot and

Insight II/March 2000 171

5. Builder Module

visualize several user-definable properties. In the Discover mod-

ule, pseudoatoms can be defined and used to define NOE con-
straints.
Pseudoatoms can also be used in the Color, Display, Label, and
List commands in the Molecule pulldown; the Distance, Angle,
Dihedral, and XYZ commands in the Measure pulldown; the
Center, Move, Overlay, and Superimpose commands in the
Transform pulldown; and the commands in the Subset pulldown.

Define
The Define command is used to create new pseudoatoms. Five
computational criteria (charge, geometry or arithmetic mean, cen-
ter of mass, temperature factor, and van der Waals radius) are pro-
vided to define the pseudoatom relative to other atoms. The
Pseudo_Atom Name (maximum of four characters) can be user-
specified. The default value of Auto indicates the automatic gen-
eration of the names. The Definition_Mode allows you to add or
remove an atom set from the definition of a pseudoatom. The Mol-
ecule Spec can be applied to generate one specific pseudoatom.
The Per_Monomer and Per_Molecule parameters can be used to
apply the specification to each monomer or molecule. The ability
to use wildcards and multiple residue:atom combinations in the
Molecule Spec allows you to specify a virtually unlimited number
of atoms in defining the pseudoatom.

Rename
The Rename command is used to rename pseudoatoms created by
the Define command.

Delete
The Delete command is used to delete a pseudoatom or a group of
pseudoatoms.

List
The List command is used to list information about any specified
set of pseudoatoms. Coordinate information can be obtained by
choosing Extdetails as the List_Option. All output is listed to the
textport, or can be directed to a file.

172 Insight II/March 2000

 Builder Tutorials

Optimize Pulldown
The Optimize pulldown contains the Optimize command, which
provides convenient and rapid access to a minimization of a mol-
ecule or molecular system, using the Discover program.

Optimize
The Optimize command uses a Discover program minimization
strategy which automatically cycles through three different mini-
mization algorithms. Each minimizer may be accessed separately
in the Discover module, but Optimize provides a quick and con-
venient route to minimizing a molecule within the Builder mod-
ule without moving to the Discover module, and without defining
a new minimization when the previous minimization is complete.
A minimization defined with Optimize commences with steepest
descents, moves on to conjugate gradients, and finishes with the
BFGS algorithm. Maximum derivative criteria are used to select
the next algorithm in the cycle; conjugate gradients is selected
when the maximum derivative in the molecule is less than 10, and
BFGS is selected when the maximum derivative drops below 1.
The total number of iterations for the complete minimization cycle
and the final convergence criterion (i.e., the maximum derivative)
can be specified. Note that the optimization terminates if the total
number of iterations is exceeded, even if the convergence criterion
is not satisfied. It is also possible to specify whether or not to
include charges in the Discover energy calculation. The energy cal-
culation uses a harmonic term for bond stretching and does not
use cross terms.

Builder Tutorials
As of this release, most tutorials are now available online for use
with the Pilot interface. To access the online tutorials, click the
mortarboard icon in the Insight II interface.
Then, from the Open Tutorial window, select Insight II tutorials,
and choose from the list of available lessons. For molecule-build-

Insight II/March 2000 173

5. Builder Module

ing functionality in particular, refer to the following Sketcher

chapter.
Once you are running Pilot, you can access the Open Tutorial win-
dow at any time by clicking the Open File button in the lower left
corner of the Pilot window.
For a more complete description of Pilot and its use, click the on-
screen help button in the Pilot interface or refer to the Insight II
User Guide.

174 Insight II/March 2000

6 Sketcher

Introduction
The Sketcher is accessed from the Builder module of Insight II.
From the Sketch pulldown, choose the Toolbox command to bring
up the MolBuilder. The power of the Sketcher is its ease of use and
the speed with which complex structures can be built. You can
draw a molecule essentially freehand, much like drawing on a
piece of paper, and quickly convert the drawing into a reasonable
3D molecular structure. You can also use the Sketcher to build a
structure in 3D.

Tutorial
This tutorial takes you through the process of building a structure
in 2D, and in 3D. (It is numbered Application 2 because it is the
second of 12 basic applications that give a general survey of
Insight II functionality. To use the other applications start up Pilot
from Insight II, then choose Insight II Tutorials.)

Application 2: Molecule Building

Building and Manipulating the ACE Inhibitor Captopril

Background
In the majority of cases in drug design the structure of the target
enzyme or receptor is not known. The design of active compounds

Insight II/March 2000 175

6. Sketcher

then relies upon the identification of functional groups that are

critical for activity, and the definition of a 3D orientation of these
groups that can be adopted in all active molecules: the so-called
pharmacophoric pattern.
Angiotensin Converting Enzyme (ACE) is a zinc metallopeptidase
which catalyzes the conversion of angiotensin I to angiotensin II,
an octapeptide which is a potent vasoconstrictor. Compounds
which inhibit ACE have an antihypertensive effect. Captopril (1-
[(2S)-3-mercapto-2-methylpropionyl]-L-proline) (Figure 23) is a
potent and specific ACE inhibitor and an orally effective antihy-
pertensive agent (Hangauer 1989).
Extensive structure-activity studies have characterized the funda-
mental structural requirements for ACE inhibition as:
1. a terminal carboxyl group which interacts with a positively
charged residue in ACE;
2. a carbonyl group involved in hydrogen bonding to a group in
the active site;
3. an effective zinc ligand, which in captopril is provided by the
sulfhydryl group.
Using systematic conformational search techniques, a unique
pharmacophoric model has been defined that was accessible by a
series of 28 active and structurally diverse ACE inhibitors (Mayer
et al. 1987, Dammkoehler et al. 1989). This pharmacophore is
defined by a series of 5 interatomic distances between each of the
groups known to be important in binding (see Figure 26).

Introduction
This application illustrates how to build the captopril molecule
using the Sketcher. It goes on to demonstrate how to locate a con-
formation of captopril that is both low in energy (a conformation
that on the basis of molecular mechanics energy calculations is
energetically stable and attainable) and that also matches the phar-
macophoric pattern. This is the “bioactive” conformation of capto-
pril.
An important check of a pharmacophore model is that it should
distinguish active from inactive compounds. A stereoisomer of

176 Insight II/March 2000

 Application 2: Molecule Building

captopril that has markedly reduced activity will also be built.

This compound can only match the pharmacophore in a high
energy (unstable) conformation. The inactivity of this compound
may be explained by its inability to match the pharmacophore in a
stable conformation.

Figure 23. Captopril

HS

* N

Chirality at both O
centers * is S
O O

Application
This application is organized into the following sections.
♦ Building captopril in 3D
♦ Building captopril in 2D
♦ The “bioactive” conformation of captopril
♦ The inactive stereoisomer
The structures that are to be built in this application have already
been constructed should they be required:
Captopril_s.car initial 3D structure
Captopril_s.car2d 2D sketch
Captopril_active.car bioactive conformation
Captopril_r.car 3D structure of inactive isomer

Insight II/March 2000 177

6. Sketcher

Captopril_r.car2d 2D sketch of inactive isomer

If Insight II is running:
Enter delete * at the command prompt to remove any structures
displayed in Insight II.
If Insight II is not running:
Enter biosym_tutorial at the UNIX prompt, and follow the on-
screen
instructions.

Building Captopril in 3D
Using the Sketcher, 3D structures can be constructed by joining
together units stored in a fragment library, and by a form of 3D
sketching called Grow. The components of captopril are shown in
chapter Figure 24 . Components of Captopril. Proline is a conve-
nient fragment from which to start.

178 Insight II/March 2000

 Application 2: Molecule Building

Figure 24. Components of Captopril

H

C
H H H
H N
H H Methyl
H C C H
H H
H H
C
O H
O

Ethyl Aldehyde Proline

HS
D NB
C
A
Captopril
O

O O

1. Go to the Builder module

Select Builder from the Module pulldown, by clicking the

MSI logo. If the Molbuilder dialog box does not appear,
select Molbuilder from the Toolbox pulldown menu.

Insight II/March 2000 179

6. Sketcher

2. Access the necessary amino fragments

Open the Fragment Window by pressing the “3D Frag-

ments...” button on the Molbuilder dialog box. When the
window appears, and the fragments have been loaded,
select Amino Acids from the pulldown menu labeled Frag-
ment Libraries on the Fragment Window.

When accessing the fragment library for the first time in an Insight II
session, data from the library is read in from disk. This takes a few sec-
onds, after which the first amino acid fragments are displayed in the
Fragment Window. Note that you may have more than one Fragment
Library open at the same time.

Scroll through the fragments using the scrollbar at the bot-

tom of the Fragment Window until Proline is one of the
fragments displayed. Press the left mouse button down
over any atom in Proline. When the cursor changes shape to
a miniature drawing of the fragment, hold the left mouse
button down while dragging the mouse into the main
graphics window. This feature of the Fragment Window is
called Drag and Drop. Use Object/Rename to change the
name of the proline from PRO to captopril_s. Press Cancel.

The proline fragment is displayed in the graphics window, colored by

atom. Note that you do not necessarily have to hold the mouse button
over an atom to drag a fragment to the main graphics window. When-
ever the cursor changes shape to respresent the fragment, the Drag
and Drop feature is active.

CAPTOPRIL_S may be manipulated using the dials, or with

the mouse. Orient CAPTOPRIL_S so that the NH group
points to the left and the aldehyde group points down.

180 Insight II/March 2000

 Application 2: Molecule Building

The complete CAPTOPRIL_S molecule is built by modifying this

starting fragment.

3. Add additional fragments

CAPTOPRIL_S currently exists as an object containing one residue-

-to ensure that further fragments are included as part of this residue,
rather than as individual residues, turn on the Assimilate option.

Open the Defaults dialog box by selecting the “Defaults...”

menu command in the Toolbox pulldown. Toggle the
Assimilate Atoms default to On.

Note that, at this time, there are three open windows, the Molbuilder
Dialog box, the Fragment Window, and the Defaults dialog box. All
of these control windows can co-exist with the others, and any of the
available controls can be used at any time.
To construct the amide bond an Aldehyde group is appended to the
NH group. A fragment is added by selecting one hydrogen atom in the
fragment and one hydrogen atom from the molecule to which the frag-
ment is to be joined. Both hydrogen atoms are then deleted and a bond
is created between the two heavy atoms to which the hydrogen atoms
were bonded.

In the Fragment Window, press the “Fragment Libraries...”

button. The Fragment Libraries dialog box allows opening
and closing of multiple Fragment Libraries at a time. Turn
Off the Common Fragments, turn On the Functional
Groups libraries, and press OK. If the Aldehyde fragment
isn’t visible, scroll the window until it is. Pick either hydro-
gen atom in the Aldehyde fragment, then select the hydro-
gen bonded to the nitrogen in CAPTOPRIL_S and press the
Single Bond button in the Molbuilder Dialog box.

The Aldehyde fragment is appended to CAPTOPRIL_S. Note that

Insight II determined that the new bond is partially delocalized, and

Insight II/March 2000 181

6. Sketcher

created a partial double bond. The background behind the Aldehyde

fragment is now black, and a highlight should remain on the hydrogen
that was selected. This is called the Hot Fragment. As long as a frag-
ment is selected in this manner, you can bond the fragment to your
molecule by selecting one or many hydrogens, and pressing the appro-
priate bond button.
If the “Add Torsions to New Bonds” button is turned On in the
Defaults dialog box, a Torsion was also created on the new bond.
The value of the torsion is displayed at each bond. A cone on the Tor-
sion shows which end will rotate (the larger end is the moving one).
Clicking in empty space deactivates the Torsion (the cone disappears,
and the font used for the value changes). To re-activate the Torsion,
pick the bond again. To modify this torsion (only active Torsions may
be modified), hold the middle mouse button down and move the mouse
horizontally. To change the directionality of the Torsion (change the
end that rotates), click on the cone.
There is evidence from both constrained analogs and conformational
studies that the amide bond exists in the trans form in the bioactive
conformation.

Select Molecule/Label, and set Label Property to Name.

Pick CAPTOPRIL_S in the value aid. Press Cancel.

The geometry of the newly added aldehyde group is not

quite right, yet. If there is no Torsion on the new bond (rep-
resented by a numerical value label on the bond), create one
by picking on the center of the bond. Both atoms connected
by the bond should be selected. Press the Torsion button on
the main Icon Bar. Rotate the Torsion by moving the mouse
left or right while holding the middle mouse button down.
Change the geometry until the value becomes roughly 0.0,
or the bond to the aldehyde hydrogen is trans to the N-CA
bond. Click in empty space to de-activate the Torsion.

Drag and drop can also be used to create bonds to fragments.

182 Insight II/March 2000

 Application 2: Molecule Building

Open the Fragment Libraries dialog box again, and turn

Off Functional Groups, and turn On the Hydrocarbons
library. Press the OK button. Press and hold the left mouse
button over any hydrogen in the Ethyl fragment. Once
again, the cursor will become a small drawing of the frag-
ment. If the press was directly over a hydrogen atom, there
will be a small square highlight over that atom in the cursor.
With the mouse button held down, drag the cursor over the
hydrogen remaining on the Aldehyde group just added to
CAPTOPRIL_S, and release the mouse button.

Press the Done button in the Fragment Window and the

Defaults dialog box.

The Ethyl fragment is appended to the CAPTOPRIL_S.

Although the rest of the molecule could be built using fragments from
the Fragment Library, it is faster to use the Grow functionality. At
this time, only the Molbuilder dialog box should be open. The Grow
mode uses the same controls that 2D sketching does in the Molbuilder
dialog box, only they are used on 3D molecules.

Make sure no atoms are currently selected by clicking in

empty space. Press either the Single Bond button, or the
Draw button. Either of these controls activate the other, as
well as the Carbon button. The cursor changes shape when
moved over the graphics window to reflect the Element
Type and the Bond Type selected.

Try selecting different bond types and element types to see the effect
on the cursor shape. The cursor has these shapes only in the Draw

Insight II/March 2000 183

6. Sketcher

mode, it is the usual Arrow shape while in Select mode.

Click on one of the hydrogens alpha to the carbonyl group.

That hydrogen will become a methyl group, and if the Add
Torsions to New Bonds button in the Defaults dialog box
is turned On, a new Torsion is created as well.

In the Grow mode, Torsions are created dynamically. As you create

new bonds, you can manipulate the geometry of the new Torsion. If
you leave that Torsion active, the next Grow operation will replace it
with a Torsion at the new bond. If you wish to have the Torsion
remain, simply go to the Select mode and click in empty space to de-
activate the Torsion. It will not be replaced in the next Grow opera-
tion.
The chirality at the new methyl group will be checked and if necessary,
modified later. Atom types and bond orders are next modified to com-
plete the CAPTOPRIL_S molecule.

4. Add the sulfhydryl group

The sulfhydryl group can be added the same way.

Press the Sulfur button, leaving the Single Bond button

selected. The cursor will reflect that you have Sulfur
selected. Pick one of the terminal hydrogens on the ethyl
fragment you previously added.

This hydrogen is converted to sulfur and the sulfur-carbon bond

length is automatically adjusted.

5. Create the carboxylate group

The only remaining task is to make the carboxylate group on the pro-
line ring from the aldehyde. Although the hydrogen of the aldehyde
group could be changed to an oxygen using the same method as the
sulfur, we will use the Selection method to change both the element

184 Insight II/March 2000

 Application 2: Molecule Building

type and the two bond orders.

In Selection mode, the operating paradigm is “select, operate”. The
atoms that are to be operated on are selected, then the operation is
choosen.

Go into the Selection mode by pressing the Select button.

In this mode, atoms or bonds are selected, then the button
representing the desired change is pressed.

Select the aldehyde hydrogen, and press the Oxygen but-

ton.

This hydrogen is converted to oxygen and the oxygen-carbon bond

length is automatically adjusted.

6. Modify the bond orders

In Selection mode, any number of bonds or atoms can be operated on

at the same time.

Select the two bonds in the carboxylate group either by

clicking on the center of each bond, holding down the Shift
Key while clicking on the second, or Box/Lasso select the
three atoms. Then, press the Partial Double Bond button.

Both bond orders become partial double bonds. The model of

CAPTOPRIL_S has been completed. Note that the labels on the het-
eroatoms do not appear by default as in the Figure below. They have
been added to the graphic to clarify where those atoms are located. To
create a display like the Figure below, first remove the current labels
by choosing Label_action Off and selecting CAPTOPRIL_S as the
Molecule Spec, then select each heteroatom individually (using the
Shift key to add to the selection), go to the Label Molecule command
and choose ATOM_SELECTION as the Molecule Spec, and Element
as the Label Property.

Insight II/March 2000 185

6. Sketcher

The chirality at carbon atom D also needs to be checked. All chiral

atoms in CAPTOPRIL_S can be labeled by chirality.

7. Label all chiral atoms

Select Molecule/Label, and set Label Property to Chirality.

Pick CAPTOPRIL_S in the value aid.

Since the default Molecule Pick Level is Molecule, the atom selec-
tion defines the whole captopril molecule and all chiral centers are
labeled by chirality. In captopril, carbon D has chirality S.

If the chirality at carbon D is R, the chiral center must be inverted.

186 Insight II/March 2000

 Application 2: Molecule Building

8. Invert the chiral center, if necessary

Select “Stereochem...” from the Toolbox pulldown to bring

up the Stereochem dialog box. Box/lasso select the central
chiral atom, and the two atoms adjacent (one is a hydrogen,
and one is the methyl carbon). Press the Invert button on
the Stereochem dialog box. Press Done to put away the dia-
log box.

CAPTOPRIL_S now has the correct stereochemistry. Before any fur-

ther modeling it is important to refine the model in order to remove
any bad atom-atom contacts created during the building process.

To remove the labels, toggle Label Option to Off, and select

Execute. Press Cancel.

9. Refine the model

You can use Optimize to refine the structure. The optimization is an

iterative process which involves computing the energy of the structure

Insight II/March 2000 187

6. Sketcher

using a molecular mechanics force field, calculating the forces acting

on each atom and moving each atom to a new position in space in
order to lower the forces (and thus reduce the energy). In order to cal-
culate the energy, Insight II requires that the force field atom types
(the potential types), and point charges be defined; as the structure has
been built from various fragments the potential types and charges are
not yet defined correctly. The Forcefield/Potentials command may
be used to set potential types and charges, although in this instance
this command does not need to be used as potential types and charges
are set automatically when Optimize is invoked.

Press the Optimize button. The message “Now optimiz-

ing...” will appear in the Info Port, and the optimization
process will start.

The optimization process starts immediately if there is only one mole-

cule available in the graphics window. If there is more than one, you
must select at least one atom in the molecule you want to optimize.
There are several adjustable parameters to the optimizer in the Mol-
builder. Select the Optimize_setup... in the Toolbox pulldown. The
controls to select the Number of Iterations, the Derivative (Con-
vergence criterion), and whether to use Partial Charges are available
from this dialog box.
During the optimization, the energy, iteration number, and time used
are reported at the top of the display. As the optimization proceeds the
structure of CAPTOPRIL_S changes and the energy decreases. The
optimization procedure automatically cycles through a number of
optimization methods, commencing with a rapid method which is
good at removing initial bad contacts. The optimization terminates
with a very effective algorithm for refining small molecules that have
been brought close to a minimum with the previous procedures.

188 Insight II/March 2000

 Application 2: Molecule Building

10.Save the refined structure

Select Molecule/Put. Ensure that the Assembly/Molecule

parameter contains CAPTOPRIL_S, enter captopril_s for
File Name, and select Execute. Press Cancel.

Note that naming of files (in contrast with the naming of objects) is
case sensitive. CAPTOPRIL_S is now saved on disk in the Old_Bio-
sym format file captopril_s.car in the current directory. To retrieve
this file use the Molecule/Get command, with Get File Type set to
Archive.

Insight II/March 2000 189

6. Sketcher

Building Captopril in 2D
Sketching a molecule in two dimensions, followed by a conversion
to three dimensions, is a convenient alternative to building in 3D.
In many cases it is easier and quicker to build a molecule in this
way.
Sketch does not impose any restrictions on how molecules are to
be drawn; indeed they can be drawn with very poor geometry
(e.g., very long bonds). The geometry of the sketch does not affect
the quality of the three-dimensional structure, but it is recom-
mended that sketches are kept chemically sensible.

Figure 25. 2D Sketch of Captopril

O O

1. If the Builder module pulldowns are not displayed, first go to

Builder

Select Builder from the Module pulldown (i.e., the Biosym

logo).

190 Insight II/March 2000

 Application 2: Molecule Building

2. Before starting the sketch, remove the CAPTOPRIL_S

structure that was built with Builder

Type delete * on the command line, and press <Enter>.

3. Begin sketching

Open the Defaults dialog box by selecting “Defaults...” in

the Toolbox pulldown menu. In the “New Drawings are:”
grouping, turn On the 2D Sketches button. Press Done.

Press the 5-Membered Ring button in the Toolbox. As

before in 3D, the Carbon button and the Draw Mode button
will highlight. Double-click the left mouse button in the
graphics window, and a cyclopentane will appear. Rotate
the molecule so that one of the vertices points down.

You can also create a ring in the graphics window by clicking in one
place, and drawing a line to another place. That vector will become one
side of the ring.

The ring is displayed, and may be manipulated using the mouse.

However, as it is a two-dimensional object, rotations around the x and
y axes are not allowed. It is recommended that captopril is built in the
orientation shown in chapter Figure 25 . 2D Sketch of Captopril.

Insight II/March 2000 191

6. Sketcher

4. Sketch the side chain, initially as a four-carbon chain

Press the Single Bond button. As before, the Carbon and

the Draw buttons highlight. Pick the starting atom (the
atom on the left side of the ring--a beep indicates that an
atom has been picked), move the mouse a bond length hor-
izontally, and place the atom with a mouse click. Move the
mouse again (a zig-zag style is recommend for chains) and
place another atom. Repeat until the chain is 4 atoms long.
Terminate the chain by clicking a second time on the last
atom placed. A beep will also indicate that you have termi-
nated the chain. Note that the rubber-band is not displayed
when a chain is terminated.

5. Draw the methyl group

Pick the second atom in the side chain, move the mouse a
bond length vertically, place a new atom with a mouse click
and terminate the chain with a second click.

6. Add the carboxylate group

Pick the ring atom pointing down and move the mouse
down a bond length and place the carbon atom. Press the
Partial Double Bond button and the Oxygen button.
Return to the display area and place the partially double
bonded oxygen, and terminate the chain with a second
click. Pick the carboxyl carbon, and place and terminate
with another partially double bonded oxygen.

192 Insight II/March 2000

 Application 2: Molecule Building

7. Set the amide bond to partial double

Exit the Draw Mode by pressing the Select button. Pick the
first bond of the sidechain (pick at the center of the bond--
both atoms become highlighted). Then, press the Partial
Double Bond button.

This operation could also have been done while in Draw mode.

8. Draw the double bonded amide oxygen

Unselect the atoms by clicking in “empty space”. Press the

Double Bond button (this will, as before, automatically
enter the Draw Mode), and the Oxygen button. Pick the
first carbon in the side chain, move the mouse down a bond
length. When you click for the second atom, the rubberband
will terminate itself. This occurs when the valence of the
added atom (the carbonyl oxygen) is completely satisfied.

Insight II/March 2000 193

6. Sketcher

9. Create the correct element types

Change to the Select Mode, and select the ring atom con-
nected to the sidechain,, and press the Nitrogen button.
Lastly, select the atom at the end of the sidechain, and press
the Sulfur button.

10.Define stereochemistry

To complete the sketch, the stereochemistry needs to be defined. With

the sketch in the orientation shown in chapter Figure 25 . 2D Sketch
of Captopril, S chirality at both chiral centers is obtained using the
Wedge Up Bond.

Unselect any atoms you may have selected by clicking in

empty space. Press the Wedge_Up_Bond. Trace from the
sidechain carbon to the methyl carbon. In the same way
trace the bond from the ring to the carboxyl group as wedge
up (pick the ring carbon first).

The sketch is now complete. Note that hydrogens will be added auto-
matically in the 3D conversion process, so they are not necessary for
sketches, except to specify stereochemistry.

11. Save the sketch

Select Sketch/Put. Ensure that Sketch Name is set to

SKETCH_01 (i.e. the first and only sketch in this session),
and enter captopril_s as the File Name. Select Execute.
Press Cancel.

The file captopril_s.car2d has been saved on disk in the current direc-
tory. It may be retrieved using the Sketch/Get command.

194 Insight II/March 2000

 Application 2: Molecule Building

12.Create the three-dimensional structure of captopril

Open the Defaults dialog box, and ensure that the Keep
Sketch button in the Convert to 3D grouping is On. The
state of the Check Valences button is unimportant at this
time since the sketch we will convert has correct valences.
To convert the sketch to a 3D structure, simply press the 2D-
>3D button.

Press Done in the Defaults dialog box to put it away.

The 3D structure takes a few moments to generate. Although it is gen-

erated in a good conformation, it should be refined. Note that the
potential types and charges are automatically set when the 3D struc-
ture was generated.
The Sketcher conversion automatically assigns a simple molecule
name to the 3D molecule.

Use Object/Rename to change the name of the molecule

from MOL_01 to captopril_s. Press Cancel.

Insight II/March 2000 195

6. Sketcher

13.Refine the 3D structure

Select an atom in the 3D molecule, and press the Optimize

button.

Alternatively, you can select an atom of the 2D Sketch, and press the
Optimize button. Insight II will first convert the sketch to 3D, then
optimize the 3D molecule.
Watch the structure change and the energy decrease as the optimiza-
tion proceeds. Before moving onto the next section, the refined 3D
structure should be saved and the sketch deleted.

14.Save the structure and delete the sketch

Select Molecule/Put. Ensure Assembly/Mol Level is set to

Molecule level in the value aid, and the Assembly/Mole-
cule parameter is set to CAPTOPRIL_S, enter captopril_sk_
s for File Name, and select Execute. Press Cancel.

Select Object/Delete. Pick any atom in the 2D sketch and

select Execute. Press Cancel.

The sketch is removed from the display (but note that it is still stored
in the file created previously).

196 Insight II/March 2000

 Application 2: Molecule Building

The Bioactive Conformation of Captopril

Whether built in 2D or 3D, the CAPTOPRIL_S structure is now
displayed in the display area. This section illustrates the use of
Torsions, Distance Monitors and Measure/Energy commands to
locate the “bioactive” conformation of captopril.
The energy and specified interatomic distances are monitored
interactively (using the Measure commands) while bond rotations
are carried out using Torsions.
The ACE pharmacophore model is represented for captopril in
chapter Figure 26 . The ACE Pharmacophore Model as a set of five
interatomic distances between groups known to be important in
binding.

Figure 26. The ACE Pharmacophore Model

1 N
2 C B
D
E
4
3
5 4
O
S 2
F 3
1
O O

1sulfur - carboxylate oxygen:6.9 Å

2sulfur - carbonyl oxygen3.4 Å
3carbonyl oxygen - carboxylate oxygen3.8 Å
4sulfur - carbonyl carbon3.6 Å
5carbonyl carbon - carboxylate oxygen4.1 Å

1. Monitor the energy of a molecule

Insight II/March 2000 197

6. Sketcher

Using the Measure/Energy command the van der Waals and Cou-
lombic (electrostatic) energies of a molecule may be monitored inter-
actively while the conformation is modified. Note that the energy
reported will not be the same as that reported using Optimize, since
Insight II only calculates the nonbonded interactions. When rotating
around a bond the bond lengths and angles do not change, so their
contributions to the energy do not need to be included.

Select Measure/Energy, and set Coulomb to Off. Ensure

that Molecule Spec is set to CAPTOPRIL_S, and select Exe-
cute. Press Cancel.

The van der Waals, electrostatic (Coulombic), and total energy are
reported at the top right of the display area. Note the energy. The Cou-
lomb term is set off so the electrostatic energy is zero. ACE has a Zn2+
ion in the active site which would be expected to alter the charge dis-
tribution of any ligand, thus the charges that were automatically
assigned to captopril during the optimization process may not be rel-
evant.

2. Define distance monitors

The conformation of the carboxylate group can be defined indepen-

dently of the rest of captopril. The conformation of this group is deter-
mined by distances 3 and 5 which may be modified by rotating around
Torsion 4 only, as the amide bond is known to be trans. If the amide
bond is not currently trans, create a Torsion as before and rotate the
bond to have a trans configuration. The conformation of the carboxy-
late group is set before moving on to the rest of the structure.

Select the atom pair defining distance 3 (the carbonyl oxy-

gen to one carboxylate oxygen). Press the Measure button
on the Icon Bar. Then select the atom pair defining distance
5 (the carbonyl carbon (C) to the same carboxylate oxygen),
and press the Measure button again.

A distance monitor is displayed for each atom pair defined. The Mea-

198 Insight II/March 2000

 Application 2: Molecule Building

sure Icon will create either Distance, Angle, or Dihedral Monitors

depending on whether there are two, three, or four atoms selected.
Unlike the menu-based Measure commands, the Measure Icon
requires that for Angles and Dihedrals, the atoms are contiguous. The
is because atom selections are not ordered, and thus non-contiguous
ordering cannot be infered.

3. Define the bond around which to rotate (Torsion 4 in chapter

Figure 26 . The ACE Pharmacophore Model))

Select the two atoms that define torsion 4, (the ring carbon
and the carbon of the carboxylate group), or select the bond
between the two atoms. Press the Torsion button on the
Icon Bar.

Press and hold down the middle mouse button while mov-
ing the mouse horizontally. The carboxylate group rotates,
and the reported torsion angle changes.

Rotate the carboxylate group until the distance monitors

match the required distances, the carbonyl oxygen-carbox-
ylate oxygen distance is about 3.8, and the carbonyl carbon-
carboxylate oxygen distance is about 4.1 Angstrom.

The energy has increased, but only slightly. As the conformation of the
carboxylate group has now been defined, the distance monitors and
torsion definition may be cleared.

4. Clear monitors and de-activate the torsion

Click in ‘empty’ space to de-activate the Torsion. The cone

will disappear, and the value text change to a smaller font.

Insight II/March 2000 199

6. Sketcher

Both the Torsion and the Measure buttons are toggle buttons, and cre-
ate or remove Torsions or measurements. To completely remove a Tor-
sion, select the bond, or the two atoms, and press the Torsion button
on the Icon Bar.

Select the carbonyl oxygen, and the oxygen of the carboxy-

late that had previously been selected for the Distance
Monitor. Press the Measure button on the Icon Bar.
Select the other two atoms involved in the remaining Dis-
tance Monitor, and press the Measure button again.

The distance monitors are removed.

5. Modify the side chain conformation

In the same way the conformation of the side chain may be defined.
The remaining 3 distance monitors (1, 2 & 4) are set up first.

First define Distance 1 between the sulfur and the carboxy-

late oxygen used in the previous measurements. Distance 2
is between the sulfur and the carbonyl oxygen, while Dis-
tance 4 is between the sulfur and the carbonyl carbon. Cre-
ate each Distance Monitor by selecting each pair of atoms
in succession, and pressing the Measure button.

Now define the 3 torsion angles 1, 2, and 3 in chapter Figure 26 . The

ACE Pharmacophore Model.

Select the pair of atoms defining torsions 1 and press the

Torsion button on the Icon Bar. Repeat this process for tor-
sions 2 and 3.

Three torsions appear on the molecule. Note that at any one time, only
one Torsion is active. You can iteratively rotate each Torsion by click-

200 Insight II/March 2000

 Application 2: Molecule Building

ing on the bonds.

Iteratively manipulate torsions 1 and 2 to locate a low

energy conformation in which the distance monitors match
the pharmacophoric pattern.

Hint: In the “bioactive” conformation of captopril, torsion 1 has a

value of 150 degrees. Rotate torsion 1 until the value reported is 150.
Keeping torsion 1 at this value, rotate torsion 2 until the distances
match the pharmacophore (chapter Figure 26 . The ACE Pharmacoph-
ore Model).
Rotating torsion 3 does not effect the distances, but once the correct
conformation has been located rotating this torsion may lower the
energy.
In the “bioactive” conformation, torsion 2 has a value of 90 degrees.
Note that the energy has increased a little over the initial energy. This
is not unexpected as the act of binding can induce strain in a ligand.
With an energy increase of this size, this conformation of captopril
will be energetically accessible.

6. Clear the monitors and torsion definitions

In order to clear more than one Distance Monitor at a time,

select Measure/Distance. Set Monitor Mode to Clear, and
select Execute.

Select Measure/Energy. Assure that Monitor is on and then

set Monitor Mode to Clear. Select Execute.

The Energy Monitor text will no longer appear on the upper right of

Insight II/March 2000 201

6. Sketcher

the graphics window.

Select Transform/Torsion. Set Torsion Operation to Clear.

Select Execute.

7. Save the bioactive conformation of CAPTOPRIL_S

Select Molecule/Put. Ensure Assembly/Molecule is set to

CAPTOPRIL_S, enter captopril_active for File Name.
Select Execute. Press Cancel.

The file captopril_active.car is stored on disk in the current directory

in Old_Biosym format. It may be retrieved using Molecule/Get.

The Inactive Stereoisomer

If the pharmacophore model is correct, it should not be possible
for an inactive molecule to adopt the bioactive conformation with-
out a significant cost in energy. The stereoisomer of captopril (1-
[(2R)-3-mercapto-2-methylpropionyl]-L-proline) is markedly less
active as an ACE inhibitor. Using the same techniques used above
to locate the bioactive conformation of captopril, the ability of the
inactive stereoisomer to adopt the bioactive conformation can be
investigated.
The R stereoisomer can be built in one of two ways. If
CAPTOPRIL_S was built using Sketch, the saved sketch can be
read in using Sketch/Get, and modified by replacing the wedge
up bond at the methyl group with a wedge down bond, followed
by 3D conversion.
However, as the structure of CAPTOPRIL_S is present in the dis-
play area, it is simpler to invert the chirality at atom D (chapter
Figure 26 . The ACE Pharmacophore Model).

202 Insight II/March 2000

 Application 2: Molecule Building

1. Modify the chirality

Open the Stereochem dialog box by selecting Stereochem...

from the Toolbox pulldown menu. Select the methyl car-
bon, chiral atom D, and the bonded hydrogen, and press
Invert. Press Done to put away the dialog box.

Captopril now has chirality R at this center. The molecule should be

renamed:

Select Object/Rename. Pick any atom in CAPTOPRIL_S.

Enter captopril_r as the New Name. Select Execute. Press
Cancel.

This structure should be refined to remove the bad contacts generated

as a result of the chirality inversion.

2. Refine the structure

Select an atom in the molecule, and press the Optimize but-

ton.

The energy is initially high and drops rapidly as the optimization pro-
ceeds. (Check that the amide bond has not flipped into the cis confor-
mation during the optimization. If it has, define a Torsion and rotate
the bond to make it trans.)
With the procedures used in the previous section, attempt to locate a
low energy conformation of CAPTOPRIL_R which matches the phar-
macophore.

Insight II/March 2000 203

6. Sketcher

3. Locate a conformation that matches the pharmacophore

First set the conformation of the carboxylate group by defin-

ing a Torsion to the carboxylate and Distance Monitors as
before so that distances 3 and 5 match the pharmacophore.

Once the pharmacophoric conformation has been estab-

lished, de-activate the Torsion, clear the Distance Moni-
tors, and define the 3 side chain Torsions and 3 Distance
Monitors. Use Measure/Energy to monitor the energy of
the molecule. Set torsions 1 and 2 to those values of the bio-
active conformation of CAPTOPRIL_S (150 and 90 degrees
respectively).

In this conformation the distances match the pharmacophore quite

well, but the energy is very high. Modifying the torsions locates lower
energy conformations, but these do not match the pharmacophore. The
inactivity of CAPTOPRIL_R may be rationalized by its inability to
match the pharmacophore in a low energy conformation.

Discussion
This application has demonstrated how to use Insight II to build,
modify, and refine a small molecule structure, and has illustrated
the application of distance and energy monitors and bond rota-
tions to locating a conformation which matches a known pharma-
cophoric pattern.
The captopril molecule used is simple enough to make it feasible
to locate a conformation matching a known pharmacophore using
these techniques. In most instances the structures in question will
be more flexible and the pharmacophore will be undefined. In
these situations the Search_Compare module may be used to per-
form rapid systematic conformational searches to locate confor-
mations that match a set of distance constraints, and to generate

204 Insight II/March 2000

 Application 2: Molecule Building

and refine a pharmacophoric pattern for a series of active mole-

cules.

Files Created
In addition to those files written using Molecule/Put and Sketch/
Put, Insight II has automatically created a number of files, pro-
duced as a result of using Optimize. At this stage it is not impor-
tant to understand the purpose of all of these files, but it is
necessary to know the relevance of some of them.
The optimization of captopril_s produced files with the root name
captopril_s0. The 0 is a counter (starting at zero) indicating that
this was the first time Optimize was used in this session.
The initial coordinates of captopril_s (prior to optimization) are
stored in captopril_s0.car, and the final optimized coordinates are
stored in captopril_s0.cor. These files are both in the same format
and may be read into Insight II using Molecule/Get, with Get File
Type set to Archive. In addition to the coordinates these files con-
tain the partial charges, atom names, and element types.
The .car and .cor are the only files produced by Optimize that can
be read into Insight II. It is useful to have files that are created auto-
matically, in order to back-track if a mistake is made at a later stage
and the structure has not been saved using Molecule/Put.
The file captopril_s0.mdf is a definitions file, which along with
other information contains the connectivity of the structure (i.e.,
which atom is bonded to which), and the potential type of each
atom necessary for the molecular mechanics energy calculations.
The .inp file is the control file for the optimization, and the .out file
lists the results of the optimization process.
A set of files with the same extensions was produced for the opti-
mization of
captopril_r.

Insight II/March 2000 205

6. Sketcher

206 Insight II/March 2000

7 Ampac/Mopac Module

Implementation
The Ampac/Mopac module provides an interface to the public
domain AMPAC and MOPAC programs. AMPAC and MOPAC
are general purpose semiempirical molecular orbital packages for
the study of chemical structures and reactions. The semiempirical
Hamiltonians MNDO, MINDO/3, AM1, and PM3 are used in the
electronic part of the calculation to obtain molecular orbitals, the
heat of formation, and its derivatives with respect to molecular
geometry. Using these results, AMPAC and MOPAC calculate the
vibrational spectra, thermodynamics quantities, isotopic substitu-
tion effects, and force constants for molecules, radicals, ions, and
polymers. For studying chemical reactions, a transition state loca-
tion routine and two transition state optimizing routines are avail-
able.
While AMPAC and MOPAC call upon concepts in quantum the-
ory and thermodynamics, and use relatively advanced mathemat-
ics, you need not be familiar with these specialized topics. The
Ampac/Mopac module is designed with the non-theoretician in
mind. The Insight II program allows you to set up complex
AMPAC and MOPAC calculations with a minimal amount of
effort, so that you can concentrate on the chemistry involved
rather than the quantum and thermodynamic concepts.

Summary of Ampac/Mopac Capabilities

1. Makes use of MNDO, MINDO/3, AM1, and PM3 Hamilto-
nians (PM3 is not supported in AMPAC)
2. Can use Restricted Hartree-Fock (RHF) and Unrestricted Har-
tree-Fock (UHF) methods

Insight II/March 2000 207

7. Ampac/Mopac Module

3. Extensive Configuration Interaction (C.I.)

a. Up to 100 configurations
b. Singlets, Doublets, Triplets, Quartets, Quintets, and Sextets.
c. Excited states
d. Geometry optimization, etc., on specified states
5. Single Point Self-Consistent Field (SCF) calculation
6. Geometry optimization
7. Gradient minimization
8. Transition state location
9. Reaction path coordinate calculation
10.Force constant calculation
11. Normal coordinate analysis
12.Transition dipole calculation
13.Thermodynamic property calculation
14.Localized orbitals
15.Covalent bond orders
16.Bond analysis into sigma and pi contributions
17.One dimensional polymer calculation
18.Dynamic Reaction Coordinate calculation (DRC)
19.Intrinsic Reaction Coordinate calculation (IRC). IRC is not sup-
ported in AMPAC.
MOPAC 6.0, AMPAC 2.1, and Density 1.0 are distributed with
Insight II as executables. These programs can handle up to 83
heavy atoms and 83 light atoms. To obtain source code and further
documentation for these packages, please contact QCPE via e-
mail: [email protected]; or write to them at: QCPE, Creative
Arts Building 181, Indiana University, Bloomington, IN 47405,
USA.
In addition to HOMO (Highest Occupied Molecular Orbital) and
LUMO (Lowest Unoccupied Molecular Orbital), the Density pro-
gram has been modified to handle keywords such as HOMO:n

208 Insight II/March 2000

 Implementation

and LUMO:n (specifying HOMO - n and LUMO + n orbitals) and

to write the output in MSI’s standard formatted grid file format.
The simplest description of how Ampac/Mopac works in the
Insight II environment is that you select the various input options
describing the molecular system, the type of the calculation, and
the output desired, and then start the calculation. Insight II
extracts the desired output from the Ampac/Mopac output files
automatically and also generates the desired electron density
and/or molecular orbital (M.O.) contours. The contours are gener-
ated from the <name>.grd files produced by running the Density
program. The input file for the Density program, <name>.gpt, is
generated by an AMPAC or MOPAC run.
By default, the AMPAC or MOPAC calculation optimizes the mol-
ecules and computes the partial atomic charges. The input file for
the Density program, <name>.gpt, is also generated. If the appro-
priate options are selected, the Density program may be run once
or multiple times to generate the grid file(s). When the background
job completes, the output file containing the partial atomic charges
and updated coordinates is read in automatically and a new mol-
ecule is created in Insight II. Based on the options specified for the
calculation, electron density and/or M.O. contours are also gener-
ated automatically.
The following figure illustrates the data flow for the MOPAC pro-
gram.

.arc
Insight II .dat MOPAC .gpt Density .grd
.out .out
.gra

Insight II/March 2000 209

7. Ampac/Mopac Module

Geometry Optimization—The OPTIMIZE Suite of

Algorithms

Introduction
A powerful suite of algorithms for geometry optimization,
referred to collectively as OPTIMIZE, is now available for MOPAC
calculations. Within the Insight II environment, you can control
OPTIMIZE via parameters provided in the Optimize/Parameters
command; and specify its usage for a MOPAC calculation by
choosing BIOSYM as Optimizer_Type for the AM_Setup/Calcu-
lation command.
OPTIMIZE is a general geometry-optimization package for locat-
ing both minima and transition states on a potential energy sur-
face. It can optimize in Cartesian coordinates or in a non-
redundant set of internal coordinates which are generated auto-
matically from input Cartesian coordinates. It also handles fixed
constraints on distances, bond angles, and dihedral angles in Car-
tesian or (where appropriate) internal coordinates - this feature is
a key advantage of using OPTIMIZE in MOPAC calculations: it is
not available in generic MOPAC, unless you go through a rather
complicated process of editing the Z-matrix while maintaining its
validity.
The MOPAC-BIOSYM-Optimizer methodology is iterative:
repeated computation of energies and gradients (using MOPAC)
and calculations (only the starting one; using MOPAC) or estima-
tions (using OPTIMIZE) of hessians in every optimization cycle
are performed until convergence is achieved. The Use_MOPAC_
Hessian option, available through the AM_Setup/Calculation
command, controls calculation of the starting hessian.

210 Insight II/March 2000

 Geometry Optimization—The OPTIMIZE Suite of Algorithms

The following figure illustrates the MOPAC-BIOSYM-Optimizer

methodology, along with the data flow among various programs.
Figure 27. MOPAC-BIOSYM-Optimizer Cycle

.original
mopacEnergy a. OPTIMIZE b. hessian
.input
.car/.mdf .grad
.keywords .hessian .car/.mdf
(updated)
.chk
Insight II mopacOptimize .hessian
.car/.mdf .opt.log
.car/.mdf .opt.arc
.keywords c.
.input converged
NO

YES

.car/.mdf
.keywords

.out
Insight II mopacEnergy d. .log
.arc
.gpt

a. mopacEnergy performs a MOPAC single point energy (1SCF) calcula-

tion to compute energy, gradient, and hessian (the last two items: first and
second derivative of energy with respect to coordinate displacement
respectively) - only the starting hessian is calculated; appropriate MOPAC
keywords are retrieved from .keywords file. The .grad file contains energy
and gradient information; hessian data are stored in the .hessian file.

b. OPTIMIZE is comprised of a suite of algorithms, developed at MSI, to

perform geometry optimizations. The .input file contains keywords to
drive the geometry optimization. The .chk file checks information needed
in the next cycle: updated hessian, etc. The final updated hessian is stored
in the .hessian file; the user specified hessian file is renamed to .origi-
nal.hessian.

Insight II/March 2000 211

7. Ampac/Mopac Module

c. Convergence criterion: energy differences, gradients, and displace-

ments are less than tolerances specified in the .input file.

d. A single point energy (1SCF) calculation is performed on the opti-

mized structure after extracting appropriate keywords from the .key-
words file, to compute any user specified properties.
OPTIMIZE is designed to operate with minimal user input. All
you need to provide is the initial geometry in Cartesian coordi-
nates (obtained from the Insight or Discover programs or from an
appropriate database), the type of stationary point sought (mini-
mum or transition state), and details of any imposed constraints.
All decisions as to the optimization strategy—how to handle the
constraints, whether to use internal coordinates, which optimiza-
tion algorithm to use—are made by OPTIMIZE.
You may, of course, override the default choices and force a partic-
ular optimization strategy, but there is no need to provide OPTI-
MIZE with anything other than the minimal information outlined
above. In particular, you do not need to provide, for example, a
Z-matrix or other connectivity data in order to take advantage of
the potential efficiency gains associated with the use of internal
coordinates. An excellent set of natural internal coordinates (Fog-
arasi et al. 1992, Baker 1993) can be generated automatically from
the input Cartesians, and the optimization can be carried out using
these coordinates.
The heart of the program (for both minimization and transition-
state searches) is the EF (eigenvector-following) algorithm (Baker
1986). The Hessian mode-following option incorporated into this
algorithm is capable of locating transition states by walking uphill
from the associated minima. By following the lowest Hessian
mode, the EF algorithm can locate transition states starting from
any reasonable input geometry and Hessian.
An additional option available for minimization is GDIIS, which is
based on the well known DIIS technique for accelerating SCF con-
vergence (Pulay 1982).
The strategy adopted for constrained optimization depends on the
starting geometry and the nature of the constraints. Constraints
can be handled easily in internal coordinates, provided that (1) the

212 Insight II/March 2000

 Geometry Optimization—The OPTIMIZE Suite of Algorithms

constrained parameter (distance, angle, or dihedral) is a natural

part of the coordinate set and (2) the constraint is rigorously satis-
fied in the starting structure. If both (1) and (2) hold for all desired
constraints, then OPTIMIZE carries out the optimization in inter-
nal coordinates. Otherwise, the constrained optimization is per-
formed in Cartesian coordinates.
Traditional wisdom has it that optimization in Cartesian coordi-
nates is inefficient relative to internal coordinates; however, recent
work (Baker and Hehre 1991) has clearly demonstrated that if a
reasonable estimate of the Hessian matrix is available (e.g., from a
molecular mechanics forcefield) at the starting geometry, optimi-
zation in Cartesian coordinates is as efficient as an internal coordi-
nate optimization. In particular, constrained optimization can be
handled in Cartesian coordinates as efficiently as with a Z-matrix,
with the additional advantages that any distance, angle, or dihe-
dral constraint between any atoms in the molecule can be dealt
with (i.e., there is no formal connectivity requirement), and the
desired constraint does not have to be satisfied in the starting
structure.
OPTIMIZE incorporates a very accurate and efficient Lagrange
multiplier algorithm for handling constraints in Cartesian coordi-
nates, with a more robust (but less efficient) penalty function algo-
rithm as a backup. Both algorithms are suitably modified versions
of the basic EF algorithm (Baker 1992). The Lagrange multiplier
algorithm can locate constrained transition states, as well as min-
ima.
The original Lagrange multiplier algorithm has been significantly
enhanced to incorporate both fixed and dummy atoms (Baker and
Bergeron 1993). Standard distance and angle constraints can be
specified with respect to dummy atoms, greatly extending the
range of constraints that can be handled. Fixed atoms can be elim-
inated from the calculation (since there is no need to calculate their
gradients), resulting in potentially significant savings of CPU time
in ab initio computations.

Insight II/March 2000 213

7. Ampac/Mopac Module

Theory and Implementation

The EF Algorithm and Mode Following

Mode following is a powerful technique for geometry optimiza-
tion. It involves modifying the standard Newton–Raphson step:

 –1 
h = –H –1 g  ≡ ( ∇2F ( x ) ) • ∇F ( x )  Eq. 1

by introducing a shift parameter λ so that (Cerjan and Miller 1981):

h = – ( H – λ1 ) – 1 g Eq. 2

In terms of a diagonal Hessian representation, this can be written:

∑
–Fi ui
h = ------------- Eq. 3
bi – λ
i=1

where the ui and bi are the eigenvectors and eigenvalues of the

Hessian matrix H, and F i = uti g is the component of g along the
local eigenmode ui. Scaling the Newton–Raphson step in this way
has the effect of directing the step to lie primarily (but not exclu-
sively) along one of the local eigenmodes, depending on the value
chosen for λ.
Various recipes for choosing a suitable shift parameter exist: the EF
algorithm utilizes a rational function approximation to the energy,
yielding an eigenvalue equation of the form (Banerjee et al. 1985):

    
 H g   h  = λ h  Eq. 4
 t    
 g 0  1   1 

from which a suitable λ can be obtained. This RFO matrix equation

has the following important properties:
1. The (n + 1) eigenvalues of Eq. 4 {λi} bracket the n eigenvalues
{bi} of the Hessian matrix, λi ≤ bi ≤ λi+1.

214 Insight II/March 2000

 Geometry Optimization—The OPTIMIZE Suite of Algorithms

2. At convergence to a stationary point, one of the eigenvalues of

the RFO matrix is zero and the other n eigenvalues are those of
the Hessian at the stationary point.
3. For a saddlepoint of order m, the zero eigenvalue of the RFO
matrix separates the m negative and the (n - m) positive Hes-
sian eigenvalues.
Property 3—the separability of the positive and negative Hessian
eigenvalues—allows two shift parameters λp and λn to be used, one
for modes along which the energy is to be maximized and the
other for which the energy is minimized. Specifically, for a transi-
tion state (a saddlepoint of order 1) in terms of the Hessian eigen-
modes, we have the two matrix equations:

 
 b 1 F 1   h 1  = λ  h 1  Eq. 5
 
 F1 0   1   1 
p

  h 2   h 
 b2 0 F2    2 
  …    …
 … …   
 0 bn F n    = λn   Eq. 6
 hn   n 
h
    
 F2 … Fn 0  1   1 

where it is assumed that maximization is along the lowest Hessian

mode bi. Note that λp is the highest eigenvalue of Eq. 5—it is
always positive and approaches zero at convergence—while λn is
the lowest eigenvalue of Eq. 6—it is always negative and again
approaches zero at convergence.
Choosing these values of λ gives a step that attempts to maximize
along the lowest Hessian mode and minimize along all the others.
It always does this regardless of the eigenvalue signature (unlike
the standard Newton–Raphson step). The two shift parameters are
then used in Eq. 4 to give a final step:

Insight II/March 2000 215

7. Ampac/Mopac Module

∑
–F1 u1 Fi ui
h = ------------------------ – ----------------------- Eq. 7
( b1 – λp) ( bi – λn)
i=2

This step may be further scaled down if it is considered too long.

For minimization, only one shift parameter λn would be used and
this would act on all modes. It is often possible to locate different
transition states from the same starting structure by maximizing
along a mode other than the lowest (hence “mode following”).

Constrained Optimization
The essential problem in constrained optimization is to minimize
a function of, say, n variables F(x) subject to a series of m con-
straints of the form Ci(x) = 0, (i = 1 … m). This can be handled by
introducing the Lagrangian function (Fletcher 1981):

L ( x, λ ) = F ( x ) –
∑ λ C ( x)
i=1
i i Eq. 8

which replaces the function F(x) in the unconstrained case. Here,

the λi are the so-called Lagrange multipliers, one for each con-
straint Ci(x). Taking the derivative of Eq. 8 with respect to x and λ
gives:

m
∂L
∂ xj
=
∂
∂ xj
F ( x) –
∑ λ ∂∂x C ( x)
i=1
i
j
i Eq. 9

and:

∂L
= –Ci ( x) Eq. 10
∂ λi

At a stationary point of the Lagrangian function, we have ∇L = 0,

that is, all ∂L /∂xj = 0 and all ∂L / ∂λi = 0. This latter condition
means that all Ci(x) = 0, and so all constraints are satisfied. Hence,

216 Insight II/March 2000

 Geometry Optimization—The OPTIMIZE Suite of Algorithms

finding a set of values (x, λ) for which ∇L = 0 gives a possible solu-

tion to the constrained optimization problem in precisely the same
way as finding an x for which g = ∇F = 0 gives a solution to the
corresponding unconstrained problem.
We can implement mode following in constrained optimization by
simply adopting Eq. 4, but with H replaced by ∇2L and g replaced
by ∇L. However, it is important to realize that each constraint
introduces an additional mode to the Lagrangian Hessian (∇2L),
which has negative curvature (a negative Hessian eigenvalue).
Thus, when considering minimization with m constraints, you
should look for a stationary point of the Lagrangian function
whose Hessian has m negative eigenvalues, that is, for a saddle point
of order m.
Insofar as mode following is concerned, then, assuming a diagonal
Lagrangian Hessian representation, Eqs. 5 and 6 for an uncon-
strained system should be replaced by the following for a con-
strained system:

    
 b1 0 F1   h1   h1 
    
 … …  …   … 
 0   = λp   Eq. 11
 bm F m   hm   h 
    m 
 F1 … Fm 0    
 1   1 

   


 h


 bm + 1 0 Fm + 1   hm + 1
    m+1 
 … …  …   … 
  h  = λn   Eq. 12
 0 bm + n Fm + n  m+n   hm + n 
    
 Fm + 1 … Fm + n 0  1   1 
  

where now the bi are the eigenvalues of ∇2L with corresponding

eigenvectors ui and F i = uti ∇L. Constrained transition-state
searches can be carried out by selecting one extra mode to be max-
imized in addition to the m constraint modes, that is, by searching
for a saddlepoint of the Lagrangian function of order m + 1.

Insight II/March 2000 217

7. Ampac/Mopac Module

GDIIS
In the GDIIS method, geometries (xi) generated in previous opti-
mization steps are linearly combined to find the “best” geometry
on the current cycle (Császár and Pulay 1984):

xn =
∑C x
i=1
i i Eq. 13

The problem here, of course, is to find appropriate values for the

coefficients Ci.
If we express each geometry (coordinate vector) by its deviation
from the sought final converged geometry xf, that is, xi = xf + ei,
then it is obvious that if the conditions:

R =
∑C e i i = 0 Eq. 14

and:

∑C i = 1 Eq. 15

are satisfied, then the relation:

∑C x i i = xf Eq. 16

also holds.
The true error vectors ei are, of course, unknown. However, they
can be approximated by:

ei = –H –1 gi Eq. 17

where gi is the gradient vector corresponding to the geometry xi.

Minimization of the norm of the residuum vector (Eq. 14), together
with the constraint equation (Eq. 15), leads to a system of m + 1 lin-
ear equations:

218 Insight II/March 2000

 Geometry Optimization—The OPTIMIZE Suite of Algorithms

 B    0 
 11 B 12 … B 1m 1   C1   
 B    0 
 21 B 22 … B 2m 1   C2   
 …    =   Eq. 18
 … …  …   … 
 B   
B m2 … B mm 1   Cm   0 
 m1    
 1 1 … 1 0  –λ   1 

where Bij = 〈ei ej〉 is the scalar product of the error vectors ei and
ej, and λ is a Lagrange multiplier.
The coefficients Ci determined from Eq. 18 are used to calculate an
intermediate interpolated geometry:

x′m + 1 =
∑C x
i=1
i i Eq. 19

and its corresponding interpolated gradient:

g′m + 1 =
∑C g
i=1
i i Eq. 20

A new, independent geometry is generated by relaxing the inter-

polated geometry according to:

x m + 1 = x′m + 1 – H – 1 g′m + 1 Eq. 21

In the original GDIIS algorithm, the Hessian matrix is static, that

is, the original starting Hessian remains unchanged during the
entire optimization. However, updating the Hessian at each cycle
generally results in more rapid convergence, and this is therefore
the default in OPTIMIZE. Other modifications to the original
method include limiting the number of previous geometries used
in Eq. 13 by neglecting earlier geometries and eliminating any

Insight II/March 2000 219

7. Ampac/Mopac Module

geometries more than a certain distance (default = 0.3 au) from the
current geometry.

Command and Keyword Correspondance

The correspondence between various Insight II program parame-
ters (first column) and AMPAC and MOPAC keywords (second
column) is shown below. NOTE that this list and mapping contin-
ues to be revised. Please refer to the version of this chapter at MSI’s
website for the most current information.

[AM_Setup]/Calculation:
MNDO MNDO
MINDO/3 MINDO/3
AM1 AM1
PM3 PM3
Check_Input 0SCF
Energy 1SCF
Gradient NLLSQ
Minimize Optimize
Frequency FORCE
Saddle ________
Check_Frequency DUMP

[AM_Setup]/Electronic_State:
Lowest ________
Singlet SINGLET
Doublet DOUBLET
Triplet TRIPLET
Spin_Restricted RHF
Spin_Unrestricted UHF

220 Insight II/March 2000

 Command and Keyword Correspondance

Total_Charge CHARGE

[AM_Parameters]/SCF:
Energy_ConvergenceSCFCRT
SCF_Iterations ITRY
Pulay_Convergence PULAY
Peptide_Correction MMOK, NOMM
Geometry_Test GEO-OK
Shift_Energy_Level SHIFT

[AM_Parameters]/Optimize:
Gradient_Converge GNORM
NLLSQ NLLSQ
SIGMA SIGMA
BFGS BFGS
DFP DFP, POWELL
EF EF
Max_Step_Size DMAX
Transition_State TS
Line_Minimizer NOTHIEL

[AM_Parameters]/Saddle:

[AM_Parameters]/Properties:
Mulliken_Pop MULLIK
Overlap_Pop BONDS
ESR ESR
Spin_Density SPIN
Polarizabilities POLAR
Thermodynamic_PropTHERMO(nnn,lll,mmm)

Insight II/March 2000 221

7. Ampac/Mopac Module

Initial_Temp ________
Final_Temp ________
Temp_Step ________
Electrostatic_Pot ESP
Connolly ________
Williams WILLIAMS
Constrain_Dipole DIPOLE
Scale_Radii SCALE
Scale_Charges SLOPE
Number_Surfaces NSURF
Output_Surface POTWRT
Enforce_Sym SYMAVG
STO_3G STO3G
Surface_Distance SCINCR

[AM_Parameters]/Output:
Detail LARGE, PRINT
CI_Info MECI
Minimize_Info FLEPO
Energy_Info ENPART
Frequency_Info FMAT
Interatomic_Dist NOINTER
Summary NOLOG
Gradients GRADIENTS
Normal_Z_Matrix ________
Gaussian_Z_Matrix AIGOUT
Generate_Grid_ ________
Generate_Contour ________
Density_Contor_Level________

222 Insight II/March 2000

 Command and Keyword Correspondance

Density_Contor Color________
Genearte_Grid ________
Generate_MO_Contor________

[AM_Parameters]/Keywords:
Safety_Checking LET
Based on the parameters selected for performing the Ampac/
Mopac,
MOPAC-BIOSYM-Optimizer, and/or Density calculation in the
Insight II environment, the following files could be produced.

Mopac:
<name>.dat Input
<name>.out Results
<name>.res Restart
<name>.den Density matrix (in bi-
nary)
<name>.log Log messages
<name>.arc Archive or summary
<name>.gpt Data for program Den-
sity (in binary)
<name>.syb SYBYL data
<name>.pot Surface points and
electrostatic potential
file from ESP option
ESP.DUMP Dump file from ESP
option

Ampac:
<name>.dat Input
<name>.out Results
<name>.res Restart
<name>.den Density matrix (in bi-
nary)

Insight II/March 2000 223

7. Ampac/Mopac Module

<name>.log Log messages

<name>.arc Archive or summary
<name>.gpt Data for Density pro-
gram (in binary)

Density:
<name>_density.gra Input referring to elec-
tron density
<name>_homo.gra Input referring to
HOMO
<name>_lumo.gra Input referring to
LUMO
<name>_homo_<n>.gra Input referring to (HO-
MO - n) orbital
<name>_lumo_<n>.gra Input referring to (LU-
MO + n) orbital
<name>_density.out Output referring to
electron density
<name>_homo.out Output referring to
HOMO
<name>_lumo.out Output referring to
LUMO
<name>_homo_<n>.out Output referring to
(HOMO - n) orbital
<name>_lumo_<n>.out Output referring to
(LUMO + n) orbital
<name>_density.grd Grid produced by Den-
sity referring to elec-
tron density
<name>_homo.grd Grid produced by Den-
sity referring to
HOMO
<name>_lumo.grd Grid produced by Den-
sity referring to
LUMO

224 Insight II/March 2000

 Command and Keyword Correspondance

<name>_homo_<n>.grd Grid produced by Den-

sity referring to (HO-
MO - n) orbital
<name>_lumo_<n>.grd Grid produced by Den-
sity referring to (LU-
MO + n) orbital

MOPAC in conjunction with BIOSYM-Optimizer:

<name>.input Input for optimizer
<name>.keywords Keywords to control
MOPAC calculation
<name>.opt.arc BIOSYM archive file
<name>.opt.log Log messages
<name>.hessian Hessian file updated
by optimizer
<name>.original.hessian Original hessian file, if
any
<name>.grad Gradient file

Background_Job Control:
bkgd_job_am_<name>.csh
Shell script for Am-
pac/Mopac job
bkgd_job_am_<name>.csh_log
Output from the shell
script running the Am-
pac/Mopac job.
Two different contour objects are produced for each M.O. at plus
and minus contour level values and are colored with appropriate
colors. A grid object is also generated for each M.O. Based on the
parameters selected, the following different objects can be gener-
ated automatically in the Insight II program.

Electron Density:
<name>_DEN_GRD Grid object
<name>_DEN_CNT Contour object

Insight II/March 2000 225

7. Ampac/Mopac Module

HOMO:
<name>_HO_GRD Grid object for HOMO
<name>_HOP_CNT Contour object for
HOMO at plus contour
level
<name>_HOM_CNT Contour object for
HOMO at minus con-
tour level

(HOMO - n):
<name>_HO<n>_GRD Grid object for (HO-
MO - n) orbital
<name>_HO<n>P_CNT Contour object for
(HOMO - n) orbital at
plus contour level
<name>_HO<n>M_CNT Contour object for
(HOMO - n) orbital at
minus contour level

LUMO:
<name>_LU_GRD Grid object for LUMO
<name>_LUP_CNT Contour object for
LUMO at plus contour
level
<name>_LUM_CNT Contour object for
LUMO at minus con-
tour level

(LUMO + n):
<name>_LU<n>_GRD Grid object for (LU-
MO + n) orbital
<name>_LU<n>P_CNT Contour object for
(LUMO + n) orbital at
plus contour level
<name>_LU<n>M_CNT Contour object for
(LUMO + n) orbital at
minus contour level

226 Insight II/March 2000

 Command Summary

where n is an integer indicating the desired orbital lower than

HOMO or higher than LUMO.
The following diagram illustrates the relationship between the
molecule, grid objects, and contour objects.

<name>_DEN_GRD <name>_DEN_CNT

<name>_HOP_CNT
<name>_HO_GRD
<name>_HOM_CNT

<name>_HO<n>P_CNT
MOLECULE <name>_HO<n>_GRD
<name>_HO<n>M_CNT

<name>_LUP_CNT
<name>_LU_GRD
<name>_LUM_CNT

<name>_LU<n>P_CNT
<name>_LU<n>_GRD
<name>_LU<n>M_CNT

The grid and contour objects can be manipulated by using the

commands under the Grid and Contour pulldowns.

Command Summary
In addition to the core pulldowns in the top menu bar, the Ampac/
Mopac module adds pulldowns to the lower menu bar. These
pulldowns are AM_Setup, Optimize, AM_Parameters,
Background_Job, AM_Run, and AM_Analyze.

Insight II/March 2000 227

7. Ampac/Mopac Module

AM_Setup Pulldown
The AM_Setup pulldown contains commands to set up the type
of calculation to be performed on the system.

System
The System command is used to select the molecule to be studied.
You can specify the program, AMPAC or MOPAC, to do the calcu-
lations.
The following options provided in the interface for MOPAC are
not supported in AMPAC.
[Ampac/Mopac]AM_Setup/Calculation:
METHOD = PM3, CHECKPOINT, and CHECK_FREQUENCY
[Ampac/Mopac]AM_Parameters/SCF:
PEPTIDE_CORRECTION
[Ampac/Mopac]AM_Parameters/Properties:
ELECTROSTATIC_POT and all the parameters related to it
[Ampac/Mopac]AM_Parameters/Output:
DETAIL, SUMMARY, and ARCHIVE_FILE = GAUSSIAN_Z_
MATRIX
[Ampac/Mopac]Optimize:
Opt_Parameters and Constraints commands.

Electronic_State
The Electronic_State command is used to specify the electronic
state parameters of the system for Ampac/Mopac calculations.
You can select a desired electronic state (singlet, doublet, etc.),
choose a Hamiltonian (RHF, UHF), and specify the total charge on
the system.

Calculation
The Calculation command is used to set up the parameters for the
type of calculation to be performed in Ampac/Mopac. Four differ-

228 Insight II/March 2000

 Command Summary

ent kinds of semiempirical methods (MNDO, MINDO/3, AM1,

and PM3) are provided. Note that the PM3 method is not sup-
ported in AMPAC. You can specify an 0SCF or 1SCF calculation by
selecting Check_Input or Energy from the various Calculation_
Type options provided.

List
The List command is used to list the status of all the options avail-
able for all the commands in the AM_Setup pulldown.

Optimize Pulldown
The Optimize pulldown contains commands for setting up and
controlling a geometry optimization. These commands are only
available for a MOPAC calculation.

Opt_Parameters
The Opt_Parameters command is used to specify parameters con-
trolling the optimization calculation. Among other things, you can
specify: locate minima or a transition state; use Cartesian or inter-
nal coordinates.

Constraints
The Constraints command is used to set up geometric constraints
imposed during the optimization calculation. You can specify
fixed distance, angle, or dihedral constraints, or frozen atomic
coordinates.

AM_Parameters Pulldown
The AM_Parameters pulldown contains commands to set up the
parameters for the AMPAC or MOPAC calculation.

SCF
The SCF command is used to set up the parameters used in the
SCF calculation in Ampac/Mopac.

Insight II/March 2000 229

7. Ampac/Mopac Module

Optimize
The Optimize AM_Parameters command is used to specify the
parameters controlling the optimization of the system during the
Ampac/Mopac calculation.

Saddle
The Saddle command in the AM_Parameters pulldown calls the
Saddle AM_Parameters dialog box. This command allows you to
specify the parameters that control the Saddle calculation.

Properties
The Properties command is used to specify the various parame-
ters used in computing the desired properties of the system during
the Ampac/Mopac calculation.

Output
The Output command is used to control the various kinds of out-
put produced from the Ampac/Mopac calculations. The automatic
generation of contours for electron density and molecular orbitals
(M.O.s) can also be specified. The different M.O.s available for
generating contours are as follows:

• Highest Occupied Molecular Orbital (HOMO)

• Lowest Unoccupied Molecular Orbital

(LUMO)

• Any orbital lower than HOMO

• Any orbital higher than LUMO

Keywords
The Keywords command is used to specify additional keywords,
by typing them explicitly, to fine tune the Ampac/Mopac calcula-
tion. It is useful for specifying options that are not provided in the
interface.

230 Insight II/March 2000

 Command Summary

List
The List command is used to list the status of all the options avail-
able for all the commands in the Am_Parameters pulldown.

Background_Job Pulldown
The Background_Job pulldown allows you to set up background
jobs to run concurrently or interactively with the Insight II pro-
gram. You are given the choice of whether to send background
jobs to a local or remote host. This pulldown is generic and is
found in many modules that run background jobs. The
Background_Job pulldown contains the following commands:
Setup_Bkgd_Job, Control_Bkgd_Job, Completion_Status, and
Kill_Bkgd_Job. Refer to the Background_Job Pulldown chapter for
more information on background jobs and the commands in this
pulldown.

AM_Run Pulldown
The AM_Run pulldown contains the command, Run, to run an
AMPAC or MOPAC job.

Run
The Run command is used to run the Ampac/Mopac calculation.
Based on the parameters selected in other commands, Density is
also run (multiple times) automatically after the Ampac/Mopac
calculation is finished.

AM_Analyze Pulldown
The AM_Analyze pulldown contains commands to generate the
electron density and/or molecular orbital (M.O.) grid and contour
objects from the <name>.gpt file (produced by a previous Ampac/
Mopac run) by running the Density program without restarting
AMPAC or MOPAC.
The commands under the AM_Analyze pulldown are useful for
long Ampac/Mopac calculations. The Ampac/Mopac job can be

Insight II/March 2000 231

7. Ampac/Mopac Module

started without selecting the options for automatic generation of

the electron density and/or M.O. contours. After the job is fin-
ished, the desired electron density and/or M.O. contours can be
easily generated using Electron_Density and Molecular_Orbital
analysis commands from the file, <name>.gpt, produced by
Ampac/Mopac. The <name>.gpt file is always produced by
Ampac/Mopac running in the Insight II program environment.

Electron_Density
The Electron_Density is used to generate the electron density grid
and contour from the <name>.gpt file by running the Density pro-
gram without restarting Ampac/Mopac. The grid and contour
objects can be manipulated by using the commands under the
Grid and Contour pulldowns.

Molecular_Orbital
The Molecular_Orbital is used to generate the molecular orbital
(M.O.) grids and contours from <name>.gpt files, by running Den-
sity program successively without restarting AMPAC or MOPAC.
The grid and contour objects can be manipulated by using the
commands under the Grid and Contour pulldowns.

Grid Pulldown (accessed from Grid icon)

The Grid pulldown is used to create and manipulate an energy
grid for a given molecule. You may create and compute the energy
grid, display and undisplay this grid, and write this grid to an out-
put file (.grd) that is readable by commands in the Contour pull-
down.

Get Grid
The Get Grid command retrieves grids from grid files.
Get Grid also assigns grid objects a default name based on the grid
filename. If you specify an explicit grid name with the Grid Name
parameter, the Get Grid command names the grid object accord-
ing to the value you specified.

232 Insight II/March 2000

 Command Summary

Put Grid
The Put Grid command allows you to write the grid data to a disk
file. The output filename is specified in the File Name parameter.
If no file extension is explicitly given, a default extension of .grd is
tacked on.
The File Format option is used to specify the format of data writ-
ten out. Binary, Ascii, and Voxel_View are the available choices.

Display Grid
The Display Grid command is used to control the display of grid
objects. The Grid Attribute parameter controls which attribute of
the grid to operate upon. The Point Set parameter specifies which
points are set. The Alternate Space parameter specifies which axes
to use.

Color Grid
The Color Grid command is used to control the color of grid
objects. The Grid Attribute parameter controls which attribute of
the grid to operate upon. The Point Set parameter specifies which
points are set.

Histogram Grid
The Histogram Grid command plots a histogram of the scalar val-
ues of the grid points. The computation of histogram can be
restricted to points with values which fall within a specified range.
The coarseness of the histogram can be controlled by specifying
the number of bins. The histogram can be plotted with linear or
logarithmic scale heights.
The histogram is normally scaled so that the largest bin fills the full
width of the display. An exception to this rule occurs when the
number of grid data points is small. When the number of
datapoints in the largest bin is less than the maximum bar length,
the histogram is unscaled. In other words, the number of asterisks
("*") plotted is equal to the actual integer number of points in each
bin or (when the logarithm option is selected) the logarithm of the
integer values.

Insight II/March 2000 233

7. Ampac/Mopac Module

The number of points lying outside the lower and upper limits
(i.e., the “tails” of the distribution) are demarked by the symbols
[<<<] and [>>>], respectively.

Contour Grid
The Contour Grid command creates a set of contours from a spec-
ified Insight II grid. One contour is created for each of the contour
levels you specify. A contour level is a curved surface connecting
all of the points in the given grid which have the same value. These
contours may be automatically displayed or left undisplayed.
Note that the contours may be written to a file with the Save_
Folder command.
The Molecule Name parameter is the name of the molecule for
which the grid to be contoured is defined.
The Contour Name Root parameter specifies the prefix of the
names of the resulting contour objects. Each name consists of this
string with a digit appended on the end to make the name unique.
For example, if Contour Name Root is CNT and there are three
levels specified, the resulting contour names are CNT0, CNT1, and
CNT2. The next contour created using CNT is named CNT3.
You may create a Single or a Range of individual contour levels
with the Level Specification option, adding a range of levels with
the Interval_Size and Number_Of_Levels options.

Slice Grid
The Slice Grid command allows you to analyze grid data by posi-
tioning a two dimensional slicing plane inside the grid and visual-
ize the grid values interpolated to that plane either as a
continuously colored mapplane, or as a number of 2d isovalue
contours. The mapping from data value to color is controlled via a
spectrum.

Label Grid
The Label Grid command is used to create and position or to
remove labels for grid objects. The object name of the grid becomes
the contents of the label. The Label Coordinates parameter con-
trols the positioning of the label.

234 Insight II/March 2000

 Ampac/Mopac Tutorial

CharSize Grid
The CharSize Grid command modifies the size of the specified
grid object’s label.

Difference Grid
This command allows two grids to be summed or subtracted. The
two grids may be specified as files or as existing Insight II grid
objects. The resulting new grid is created as a grid object in
Insight II.

List Grid
The List Grid command displays information pertaining to the
structure and display of a grid object. The Detail Level parameter
controls the amount of information provided. Use the Output_File
parameter to direct the display of the command output to a file.

Ampac/Mopac Tutorial
As of this release, most tutorials are now available online for use
with the Pilot interface. To access the online tutorials for Ampac/
Mopac, click the mortarboard icon in the Insight II interface.
Then, from the Open Tutorial window, select Insight II tutorials,
then the Ampac/Mopac module and choose from the list of avail-
able lessons:
Lesson 1 Basic Functionality of MOPAC
Lesson 2 Use Post-Processing to Generate Contours
Lesson 3 Finding the Transition State of a Reaction
Lesson 4 Slicing Plane tutorial
Lesson 5 Characterization of the Potential Energy surface
of 1,3-butadiene
You can access the Open Tutorial window at any time by clicking
the Open File button in the lower left corner of the Pilot window.

Insight II/March 2000 235

7. Ampac/Mopac Module

For a more complete description of Pilot and its use, click the on-
screen help button in the Pilot interface or refer to the Insight II
User Guide.

236 Insight II/March 2000

8 Docking Module

Theory
In docking, the interaction energy is computed by summing the
energy contributions between all atoms of the two molecules. The
contribution between atoms interacting with other atoms in the
same molecule is ignored. Thus, for example, for CVFF:

∑ ∑  --------
A ij B ij qi qj 
E interaction = - – --------- + -----------  Eq. 22
12 6 ε r  ij
i r
j ij
r ij

The objective of a docking type calculation is to evaluate the inter-

action energies of many orientations of one molecule relative to
the other, while searching for the orientations that result in low
interaction energies.
Ideally, a user would like to graphically move the interacting mol-
ecules in real time on a workstation while computing the interac-
tion energy. While the energy expression is straightforward to
compute, the computation time increases as a square of the num-
ber of interacting atoms, making the process too slow for many
molecular systems on most workstations.
As proposed by Langridge (Pattabiraman et al. 1985) an energy
grid approximating the larger of the two molecules can be precom-
puted. Since the interaction energy can now be approximated by
calculating the energy between the atom of the moving molecule
and the appropriate grid points, the docking can be done in real
time.
The construction of energy grids depends on the forcefield in use.
This is explained in the following sections.

Insight II/March 2000 237

8. Docking Module

Nonbond Potential in CVFF

For CVFF the nonbonded interaction energy is:

A ij B ij
E ij = --------- – -------
12 6
Eq. 23
R ij R ij

where Aij and Bij are parameters with units of kcal mol-1
angstrom12 and kcal mol-1 angstrom6 respectively, and Rij is the
distance between atoms i and j in angstroms. A completely equiv-
alent representation is:

 *  12  *6
*  R ij   R ij 
E ij = ε ij  -------  – 2  -------  Eq. 24
 R ij   R ij 

where εij is the potential well depth in kcal mol-1 and Rij* is the
interatomic distance in angstroms at which the minimum occurs.
The conversion between the two representations is straightfor-
ward:

2
* B ij
* 12
ε ij = ---------- A ij = ε ij R ij
4A ij

1
---
* 2A ij 6 * 6
R ij = ---------- B ij = 2ε ij R ij
B ij
Eq. 25

Since CVFF uses the geometric combination rule:

* * * * * *
geometric: ε ij = ε ii ε jj R ij = R ii R jj
Eq. 26

Aij and Bij can be expressed as:

A ij = Ai Aj and B ij = Bi Bj
Eq. 27

The energy grid is constructed by first rewriting Eq. 22 as:

238 Insight II/March 2000

 Theory

Eq. 28

∑ q ∑ ---------- ∑ A ∑ --------
qi A i
E = + -
ε r
i
ij
j 12
j i r j i ij

∑ B ∑ --------
Bi
– j
-
6
j r i ij

Making the assumption that a grid point lies reasonably close to an

atom in the moving molecule, the quantity rij can be rewritten as
rig (rig being the distance between the grid point and the atom in
the non-moving molecule). Since rig is constant (the grid does not
move in relation to the non-moving molecule), the values of the
inner summations can be computed once and stored at each grid
point.
The interaction energy is now expressed as:

E interaction =
∑j
qj Ge ( P) + Ai G ( Pj) – Bj GB ( Pj)
A
Eq. 29

where Ge (Pj), GA (Pj ) and GB (Pj ) represent the value at the grid
points for the pre-computed electrostatic and van der Waals ener-
gies, Pj being the position of the atom in the moving molecule.
By using the position of the atom in the moving molecule to look
up the value at the appropriate grid point, the interaction energy
can be quickly computed.
It should be noted that as the grid spacing is decreased, the result
of Eq. 29 becomes closer to the result of Eq. 28 since the error
between the true atom position and the grid point decreases.

Nonbond Potential in CFF9X

The CFF (CFF91 and CFF) forcefields use the nonbonded interac-
tion potential

A ij B ij
E ij = ------- – -------
9 6
Eq. 30
R ij R ij

Insight II/March 2000 239

8. Docking Module

where Aij and Bij are parameters with units of kcal mol-1 angstrom9
and kcal mol-1 angstrom6 respectively and Rij is the distance
between atoms i and j in A. A completely equivalent representa-
tion is:

 *9  *6
*  R ij   R ij 
E ij = ε ij 2  -------  – 3  -------  Eq. 31
 R ij   R ij 

where εij* is the potential well depth in kcal mol-1 and Rij* is the
interatomic distance in angstroms at which the minimum occurs.
The conversion between the two representations is straightfor-
ward:

3
* 4B ij
* 9
ε ij = ------------- A ij = 2ε ij R ij
2
27A ij
Eq. 32
1
---
* 3A ij 3 * 6
R ij = ---------- B ij = 3ε ij R ij
2B ij

Since CFF 9X uses the sixth-power combination rule:

* *  *3 *3   6 61 ⁄ 6
* ε ii ε jj × 2  r ii r jj  6  R ii + R jj 
sixth-power: ε ij = ------------------------------------------------------------ R ij =  -------------------- 
 6 6
 2 
 r ii + r jj  Eq. 33

The repulsive term cannot be factorized:

9
A ij = 2ε ij • r ij
1
1 ---
3
 6 6 2
---
3  ri + rj 
2
= 2 ( ε i • r j ) • r i • r j • ----------------
 2 
Eq. 34

Thus, the following approximation is introduced:

240 Insight II/March 2000

 Implementation

1 9
--- ---
′ 2 2
A ij = 2 ( ε i • ε j ) • ( r i • r j )
1 1
--- ---
 9 2  9 2
=  2 • εi • ri  •  2 • εj • rj 
Eq. 35

This is actually the geometric combination rule used in CVFF and

AMBER, except that the 12th power is replaced by the 9th power.
Apparently, the approximation is exact for homogeneous atom
pairs and the error is largest when the radii r differ most for the
atom pair. Note that the dispersive term in the 9-6 potential can be
factorized the same way as that in the 12-6 potential for CVFF and
AMBER.
With the approximation of Eq. 35, the interaction energy can also
be evaluated by Eq. 29 for CVFF.

Nonbond Potential in AMBER

Since AMBER uses the 6-12 potential for vdw as CVFF, the vdw
energy grids for AMBER can be created the same way as for CVFF.
For electrostatics, however, AMBER uses distance-dependent
dielectric constant and therefore the ε in Eq. 28 needs to be set to
rij, instead of 1 for CVFF and CFF9X. It should be noted that the 10-
12 hydrogen bonding term in AMBER is neglected in constructing
the energy grids.

Implementation
The Docking module provides facilities for calculating the non-
bond energy between two molecules using the methods described
in the preceding theory section. Note that this calculation is per-
formed using the Discover program, and may only be used effec-
tively with the AMBER, CFF9X and CVFF forcefields.
Also note that the separate Affinity program may be useful to per-
form energy-based flexible docking. See the separate Affinity doc-
umentation for additional information.

Insight II/March 2000 241

8. Docking Module

The Evaluate pulldown provides facilities for calculating the inter-

action energy between two molecules using explicit van der Waals
energy (Eq. 30 or Eq. 28), explicit electrostatic (Coulombic) energy
(Eq. 34), or the combination of van der Waals and electrostatic
energies (Eq. 35). Alternatively, an energy grid can be used to cal-
culate the interaction energy between two molecules (Eq. 28).
The number of atoms included in the calculation can be limited by
specifying a monomer or residue based cutoff. Any monomer or
residue having one or more atoms within the specified cutoff dis-
tances of the atom currently being evaluated is included in the cal-
culation. A monomer or residue having no atoms within the
specified cutoff distance of the current atom being evaluated is not
included in the calculation.
The Grid pulldown provides facilities for defining and calculating
a potential energy grid which can be used for the evaluation of
intermolecular energies. The overall size of the grid as well as the
spacing between grid points can be specified.

Command Summary

Grid Pulldown
The Grid pulldown, which is accessed via the Grid icon, is used to
manipulate an energy grid for a given molecule. You may display
and undisplay this grid, and write this grid to an output file that is
readable by the commands in the Contour pulldown.
Refer to the Ampac/Mopac Module chapter for summaries of the
commands included in this pulldown.

Evaluate Pulldown
The Evaluate pulldown allows examination of intermolecular
energies. You may select which nonbond energy terms to use for
calculations, and can set up single-point or continuous evaluations
of these interactions.

242 Insight II/March 2000

 Command Summary

Intermolecular
The Intermolecular command allows you to examine the total
energy between two molecules. You can perform a single-point
calculation, or use a monitor to evaluate the energy continuously.
You can specify the cutoff value to be used when computing the
energy, and indicate whether or not you are using the electrostatic
or van der Waals energy parameters to compute the total energy.
The maximum derivatives with the total energy values can be dis-
played.
An energy grid can be used to approximate intermolecular energy
of very large systems. This grid can be on either molecule but must
be calculated before activating this command, using the Create
Docking_Grid and Compute Docking_Grid commands.

Docking_Grid Pulldown
The Docking_Grid pulldown is used to create and manipulate an
energy grid for a given molecule. This pulldown contains the com-
mands Create, Compute, and Display.

Create Docking_Grid
The Create Docking_Grid command allows you to define a 3D set
of points that represents the net contribution of all atoms of a spec-
ified molecule at discrete points. The size of the set of points
depends on the boundaries which are described as an enclosure
plus a defined border space. The position of the discrete points is
controlled with the Grid Step.

Compute Docking_Grid
The Compute Docking_Grid command allows you to calculate
the energy grid for the specified molecule. The grid must have
been previously defined using the Create Docking_Grid com-
mand. The Van_der_Waals and Coulomb parameters allow you to
modify which energies are calculated, while the Cut_off parame-
ter allows you to control the radius of interaction.

Insight II/March 2000 243

8. Docking Module

Display Docking_Grid
The Display Docking_Grid command allows you to display the
extents of the grid defined for the specified molecule. Grids are
displayed automatically when they are first created to make redef-
inition of the extents clearer.

Docking Tutorial
As of this release, most tutorials are now available online for use
with the Pilot interface. To access the online tutorials for Docking,
click the biplane or mortarboard icon in the Insight interface.
Then, from the Open Tutorial window, select Insight II tutorials,
then the Docking module and choose from the list of available les-
sons:
Lesson 1 Energy Calculations
Lesson 3 Energy Contours
You can access the Open Tutorial window at any time by clicking
the Open File button in the lower left corner of the Pilot window.
For a more complete description of Pilot and its use, click the on-
screen help button in the Pilot interface or refer to the Insight II
User Guide.

244 Insight II/March 2000

9 Analysis Module

Implementation
The Analysis module is used to display data, especially from
molecular conformation analyses, in graphs or molecular anima-
tion. Typically, the input data of molecular conformations comes
from the Discover program (separately licensed from MSI), but
this data can come from any source, provided it is formatted in a
way that is recognizable to the Insight II program.
Three types of graphs can be created with commands in the Anal-
ysis module. The first type of graph, usually referred to as a simple
trajectory graph, uses atomic trajectories as its most basic data
source. Properties of the trajectories, such as atomic distances or
angles, are displayed as curves. The second type of graph, called a
cluster graph, also uses atomic trajectories. Its purpose is to dis-
play the relationship between each conformer and every other
conformer. This relationship is expressed as an RMS value, and the
graph is a cluster of unconnected points that are color coded to the
RMS level, thereby indicating families of related conformations.
The third type of graph, sometimes called an inanimate graph,
does not use trajectory data. Instead, it uses data from simple
ASCII files that you may create on your own or by using the Put
Graph command. In any event, these ASCII files used to create
inanimate graphs contain columns of numbers which can be plot-
ted against one another to form curves similar to those displayed
in simple trajectory graphs.
Trajectory data from the Discover program’s history and archive
files (refer to the Discover documentation appendices for a com-
plete description of an archive file) can be analyzed quantitatively
by defining properties of interest, identifying the atoms that
uniquely define the property, and graphing those properties
against each other. The data can be qualitatively analyzed by sim-

Insight II/March 2000 245

9. Analysis Module

ply watching an animation of the molecule or molecular system as

it moves through its conformations in real time. When a molecule
is animated, each atom follows the path prescribed by the trajec-
tory data. For both qualitative and quantitative analyses, the tra-
jectory data can be filtered to remove unwanted vibrational
frequencies.
Simple trajectory graphs have a cursor that moves along the plot
in exact synchronization with the animation and dynamic data
labels that give the coordinates of the cursor. In this way, the cursor
highlights the data point on the curve that corresponds to the cur-
rent conformation being shown in the animation. Animations can
be temporarily frozen, and specific conformations corresponding
to specific plot points can be viewed. (Note that although inani-
mate graphs may have curves which look like those in simple tra-
jectory graphs, they are not necessarily derived from trajectories
and are, therefore, unchanged by animations.)
Archive files containing conformers derived from NMR or SCS
(Systematic Conformational Search) can also be used in the same
way that Discover program data is: to create graphs, etc.
Seven types of properties are available for analysis when creating
simple trajectory graphs: time, frame number, pressure, volume,
temperature, energy, and geometry (which includes distances,
angles, and dihedrals). Multiple properties may be plotted on the
same graph, as long as the properties have the same units of mea-
surement. Properties can be defined in any order. There is no soft-
ware limit on the number of properties that can be defined, or the
number of graphs that may be displayed. However, more than six
graphs or six plots on a single graph generally results in a cluttered
display.
If the trajectory data is read from a history file, the component
energies and the time step between frames are read from the his-
tory file; all other properties are calculated by the Insight II pro-
gram. If the data is read from an archive file, the total energy is
read from the file, and the time step is taken to be 1 fs (femtosec-
ond) per frame within the data file. All other properties are calcu-
lated by the Insight II program.
For those commands that use the loaded trajectory information
(such as Animate, and cluster and trajectory graph construction
commands), frame one (1) is the first frame loaded. This may not

246 Insight II/March 2000

 Implementation

be the first frame contained within the history or archive data file.
Additionally, the loaded trajectory data frame numbers run con-
secutively, starting from one (1) and ending with the maximum
frame number without skipping numbers. These frame numbers
may not exactly match the frames that were loaded from the data
file, but there is a one-to-one correspondence between them. For
example, the first frame loaded from the data file may be frame
five (5), but it is referred to as frame one (1) once it has been loaded.
The second frame loaded could be frame ten (10), but it is referred
to as frame two (2) after it is loaded.
The calculation of distances, angles, and dihedral angles is
straightforward, and is not presented here. However, the calcula-
tion of a plane that best fits more than three points is more complex
and is presented in the next section.
Cluster graphs have no cursors or dynamic data labels. Instead,
they have legends that describe the color coding used when dis-
playing clusters of points representing related families of conform-
ers.
Inanimate graphs (i.e., those created from simple columns of num-
bers) are not linked to any molecule and do not have cursors,
dynamic data labels, or legends. They do have axis labels to
describe what is being plotted, and axis min/max labels showing
the numeric bounds of the data being displayed.
When new trajectory data is loaded, either from a different trajec-
tory file or by using a combination of frames differing from the
presently loaded trajectory data, any non-animate graph is
deleted. In other words, any graph that is linked to the molecule(s)
associated with the present trajectory data disappears. This is
necessitated by the correspondence between the trajectory data
and each graph data point.
Once a graph is defined it can be manipulated in much the same
way as any other object within the Insight II program. Graphs may
be scaled, moved, rotated, blanked, or unblanked.

Average Plane Evaluation

A plane P is described in general with the following equation:

P(X) : ax + by + cz + d = 0 with x = (x, y, z) Eq. 36

Insight II/March 2000 247

9. Analysis Module

However, this description has an infinite set of a, b, c, and d, so that

when they are scaled, the same plane remains. For a unique repre-
sentation of this plane. From this equation, three unique equations
can be derived:

Qz : z = f(x, y) or z = 13x = m1y + n1 or Eq. 37

Qx : x = g(y, z) or x = 13y = m2z + n2 or Eq. 38

Qy : y = g(x, z) or x = 13x = m3z + n3 Eq. 39

Obviously, Eq. 37 is not appropriate to describe the plane x = 0. In

this case, Eq. 38 is the best representation.
To derive the average plane from a set of N points, it is important
to get the best plane by using a merit function which usually is:
minimize (a, b, c, d) by using:

∑ P (X )
2 2
χ = i : with P the plane equation and X i = ( x i, y i, z i )
i=1
2
χ : the chi square value

This is the familiar least square fitting function. This same function
is used in chi-square statistics, the so-called maximum likelihood
estimator (Pattabiraman et al. 1985).
Given a set of (a, b, c, d), certain questions arise, namely, “How
good is the fit? Is there a better fit?” When the average plane is
evaluated, the desired information includes:
1. The parameters (a, b, c, d).

2. An error estimation for these parameters.

3. A statistical measure of the fit.

The next lines describe how the most likely plane is obtained. To
derive the formula, take the plane equation:

Q z : f ( x, y ) or z = lx = my + n Eq. 40

248 Insight II/March 2000

 Implementation

The chi-square value estimates how well the model agrees with
the data (our points). The first derivative of this merit function for
the l, m, and n unknowns yields:

2
∂χ
--------- = 0 ⇒ 1S xx + mS xy + nS x = S xz
∂1

2
∂χ
--------- = 0 ⇒ 1S xy + mS yy + nS y = S yx
∂m

2
∂χ
--------- = 0 ⇒ 1S x + mS x + nS = S x
∂n
N N
with S = N points, Su = S u
and v equal to x, y, and z.
=
∑ ui and Suv = Su =
∑u v i i
with u
i=1 i=1

By solving this three-dimensional system you come up with:

d xz d yy + d xy d yz
l = ---------------------------------------
d

d xx d yz + d xy d xxz
m = ------------------------------------------
d

–Sx l –Sy m + Sz d
n = ----------------------------------------
Sd

with duv = S suv - Su Sv and d = dxx - dyy - dxy dxy and with S, Sx,
Sy, Sz defined as before.
From these l, m, and n values we obtain the a, b, c, d coefficient of
Eq. 36 (Press et al. 1986) with:

a = – l, b = – m, c = l, and d = – n

Insight II/March 2000 249

9. Analysis Module

Frequency Filtering
The Filter Trajectory command extracts motions that correspond
to interesting vibrational frequencies from a set of atomic trajecto-
ries.
The Discover program can be used to simulate a set of atomic tra-
jectories. The molecule(s) can then be displayed and animated
using the Insight II program so that it moves through the path of
the simulated trajectory.
Such simulations may cover a wide variety of molecular vibra-
tions. Amolecule can display the relatively quick movements of
bond stretches, scissors, wags, etc. It can also show the slower
movements such as linear chains rotating, bending, and twisting.
Viewing all of these movements at once may make it difficult to
focus on one or more particular kinds of vibrations.
A Fast Fourier Transform (FFT) can be used to convert the trajec-
tory data from the time domain to the frequency domain. Those
frequencies not corresponding to interesting vibrations can be fil-
tered out. This filtered frequency data can then be transformed
back into the time domain. When animated using this filtered tra-
jectory data, the molecule displays only those vibrations that are of
interest.
Prior to using the Filter Trajectory command, a trajectory data set
must be loaded (using the Get Trajectory command). After load-
ing this data, the Insight II program reports the overall number of
frames that exist. This number can be important when you decide
what values to give to the Filter Trajectory command, so it should
be noted.
The trajectory data set is modified by the Filter Trajectory com-
mand. To return to the original trajectory data, re-execute the Get
Trajectory command.
As described below, the Filter Trajectory command is limited to
modifying a number of frames that is an exact power of 2. For
example, 1024 or 2048 or 4096 frames can be modified, but some
arbitrary number, such as 1000 or 2000 frames, cannot. The num-
ber of frames that is modified is calculated by subtracting the start-
ing frame number (which is an input to the Filter Trajectory

250 Insight II/March 2000

 Implementation

command) from the total number of available frames. If this is an

even power of 2, then this is how many frames are modified. Oth-
erwise, the number of frames modified is less than this total num-
ber of frames available and is the nearest power of 2.
This means that the Filter Trajectory command might leave some
of the frames in the trajectory set untouched. You must be aware
of this and use that knowledge when you specify start/end/step
values for animation or when you create graphs.
The information about what frames have been touched by the Fil-
ter Trajectory command versus the frames that are left intact is
reported to the textport during the execution of the command.
These numbers should be noted for future reference.
Note that the limitation of modifying only a number of frames that
equals a power of 2 is not arbitrary. With very few exceptions, Fou-
rier transforms and their inverses can only be performed on com-
puters using some variation of recursion with a binary tree. In
other words, they work with arrays of data that have a number of
elements that equals a power of two. Arrays of arbitrary length can
be handled in one of two ways. The array can be clipped down to
a size that is a power of two. This is the technique that is used with
the Filter Trajectory command. Or, the array can be extended to a
size that is a power of two. When this is done, each newly added
element of the array must be given some value. There is no good
rule on how this padding should be done, although there are ref-
erences in various published articles that suggest that padding
with zeros or symmetric reflections of the original data have been
attempted. Without exception, such padding introduces fictitious
data that results in frequencies that are not truly present in the
original data. Bracewell (1990) stated, “When sampled input is not
naturally zero outside the sampled range, packing with zeros
introduces unwarranted discontinuities whose effects on the
transform, such as overshoot and negative-going oscillation, may
be undesirable. Packing with plausible but unobserved data can
eliminate the undesired artifacts and is probably practiced in more
cases than are admitted to. Investigators often mitigate the effects
of discontinuities in the data by multiplying by a tapering factor;
they should then explain that they value freedom from negatives
more than accuracy of amplitude values of spectral peaks or than
resolution of adjacent peaks.”

Insight II/March 2000 251

9. Analysis Module

One of the parameters in the Filter Trajectory command indicates

which frame to begin processing with. It specifies where, in the
total set of trajectory data, the FFT filtering is to begin. In most
cases, the starting frame number should be one (1), meaning that
the FFT filtering should begin with the first frame in the trajectory
set.
It is possible to use a value other than one in order to see the dif-
ference between the original molecule motions and those that have
been filtered. Also, you might want a to use a number greater than
one if you want to skip frames in the beginning of the trajectory set
that correspond to the molecule reaching temperature equilib-
rium.
There is another, more subtle, reason why you might want the
starting frame number to be a value other than one. As described
previously, the FFT algorithm can only process a number of frames
that is equal to an exact power of 2. Even if you request that the
processing begin with the first frame, the Filter Trajectory com-
mand may not process every frame. Processing would start with
the first frame, but may end before the end of the trajectory data
set if the total number of frames in the set is not an exact power of
2.
Consider the case where the trajectory data set has 1500 frames. If
the starting frame number is one, then the first 1024 frames are
processed and the remaining 476 frames are left untouched.
By setting the starting frame number to 476, the untouched portion
of the trajectory set is, in essence, moved from the end of the set to
the beginning of the set.
Trajectory data sets that are only partially filtered can lead to dis-
continuities when you cross the boundary between filtered and
unfiltered frames when using the Animate Trajectory or
Construct_Graph Trajectory commands. The discontinuities are
not wrong, but they may be startling because unfiltered and fil-
tered trajectories can have very different characteristics.
Another parameter in the Filter Trajectory command specifies the
time step between frames (in femtoseconds). This value can only
be determined if you know how the trajectory data was calculated.
By default, dynamics trajectories calculated using the Discover
program (through the Insight II program) have a time step of 10 fs.
This is because, while new conformers are, by default, calculated

252 Insight II/March 2000

 Implementation

every femtosecond, only every tenth conformer is put into the his-
tory file. Thus, the time step between frames is, by default, 10.
Both the time between conformers and the number of conformers
skipped between output to the history file can be adjusted before
the simulation is run.
The time between frames in a history file may be calculated by
multiplying the time step by the frequency of writing to the history
file. In terms of the input file (.inp) and output file (.out), these
parameters are controlled with the “steps” and “write history”
qualifiers to the initialize dynamics command.
A basic rule of the sampling theory that governs discrete Fourier
transforms states that the input data must be sampled at least
twice as fast as the fastest frequency in the system. Two times the
maximum frequency corresponds to what is called the Nyquist
sampling rate. Data collected with a sampling rate that is too slow
may introduce errors in the Fourier transform. It is often difficult
or impossible to predict exactly how severe these errors will be.
In terms of using the Filter Trajectory command, the Nyquist lim-
itation means that it is best to run simulations of hydrocarbons
such that the time between frames that are captured in the history
(or archive) file is not more than 5 fs. If the time between frames is
greater, you may see some erroneous movements in the molecule.
(However, practical experience has shown that these errors are
usually negligible as far as the display is concerned and the result-
ing animations look fine.)
The recommendation to capture frames every 5 fs is based on the
idea that the C–H bond stretch is one of the fastest (if not the fast-
est) vibration in a hydrocarbon simulation. Its period is about
11 fs. Half of this is about 5 fs.
Note, however, that the Filter Trajectory command allows any
positive value to be used when specifying the time between
frames. It is up to you to make sure that it is correct and that it is
not so large as to cause problems.
The final piece of information needed for the Filter Trajectory
command is the range of frequencies to retain after the filtering.
The unit of frequency used by the Insight II program is reciprocal
centimeters. In other words, frequencies are referred to by wave
numbers.

Insight II/March 2000 253

9. Analysis Module

The function of the Filter Trajectory command is to remove from

a set of trajectory data all but the interesting motions. Such
motions are identified by their vibrational frequency (range).
The zero frequency corresponds to the motionless molecule in its
average conformation. This is a simple positional average over a
set of positions. It is important to note that this kind of averaging
can result in atomic positions that do not fall on the trajectory path.
For example, atoms that sweep circles in space have an average
position that is in the center of the circle, not somewhere on the cir-
cle itself. For this reason, some atom groups might look distorted.
Methyl groups, for example, might show hydrogens that are col-
lapsed toward that central point (over the carbon). Nonetheless,
the overall topography of the molecule is generally maintained.
Frequencies of only a few hundred reciprocal centimeters gener-
ally correspond to global motions in the molecule, such as the rota-
tion or bending of linear chains. Higher frequencies generally
relate to bond stretches, or wags or scissor movements, and so on.
These are, of course, generalizations. There are many notable
exceptions. For example, the bond stretches of iodine correspond
to frequencies of only a couple hundred reciprocal centimeters.
The frequency range from zero to zero is always included and does
not need to be explicitly given.
Beyond exploring the more subtle aspects of using the Filter Tra-
jectory command, it is useful to provide some detail of the mathe-
matics that allow this filtering to take place. As mentioned above,
the filtering algorithm is straightforward:
1. The position of an atom in a simulated trajectory can be
regarded as a function of time (p = f(t)).
2. A discrete Fourier transform brings data from the time domain
to the frequency domain by

N–1

H ( ν ) = 1/N
∑ f ( t) e
t=0
– i2πνt/N

where H(v) is the frequency function corresponding to the posi-

tion function f(t), i is the imaginary unit, v is the frequency, t is
time, N is the number of discrete data points, and π is pi.

254 Insight II/March 2000

 Implementation

3. Unwanted frequencies are zeroed out in the resulting array of

calculated frequencies.
4. The filtered frequency array is brought back into the time
domain by

N–1

f ( t) =
∑ H ( ν) e
ν=0
i2πtν/N

where f(t) is the position function, H(v) is the frequency func-

tion corresponding to f(t), i is the imaginary unit, v is the fre-
quency, t is time, N is the number of discrete data points, and π
is pi.

Additional Reading on Frequency Filtering

It is beyond the scope of this document to provide a complete bib-
liography of books and periodicals that describe the theory and
application of Fourier transforms and filtering. For a general treat-
ment of numerical transforms with some discussion of caveats of
applications, see Bracewell (1990); for a cookbook approach to
model computational techniques for Fourier transforms, refer to
Press (1986); and for an application of Fourier transformations to
filter atomic trajectories, see Sessions (1989).

Clustering of Conformations into Families

The atomic trajectory data contained in a history or archive file cre-
ated by the Discover program can be thought of as a set of con-
formers for a molecule or system of molecules. It is often
important to examine whether families of conformers with closely
related topography exist. For example, each such family may cor-
respond to conformers surrounding a particular energy well in the
simulation.
The analysis of sets of conformers to reveal such families is per-
formed by creating a cluster graph. Such a graph looks like a box
filled with unconnected points. Each point represents how a par-
ticular conformer compares with another conformer. Each point is
color coded to indicate how well it compares. (The z axis of the
graph shows this comparison value numerically as well.)

Insight II/March 2000 255

9. Analysis Module

Cluster graphs are created by setting the Cluster_Graph parame-

ter on in the Construct_Graph Trajectory command. The exact
steps that you should follow to create a cluster graph are more
fully described later in this chapter. An example of a cluster graph
creation is included in the tutorial for this chapter.
The topographical comparison that is done between conformers to
classify families is based on determining a minimum RMS value
from superimposing selected atoms. Essentially, this procedure is
the same as the superimposition (with RMS calculation) done in
the Superimpose command in the Transform pulldown. Here,
too, the basic equation used to calculate the RMS is given as:

2 1⁄2
N
2 2
∑ ( xi – xi′ ) + ( yi – yi′ ) + ( zi – zi′ )
---------------------------------------------------------------------------------------------
N
i=1

where the superimposition is aimed at aligning N atoms in two

conformers of the same molecule and xi, yi, zi represent the spatial
coordinates of atom i in one conformer while xi′, yi′, zi′ represent
the spatial coordinates of the same atom in the other conformer.

Mean Square Displacement Precision

For n discrete frames in a trajectory, the MSD, <[ri(t) - ri(0)]2> of
frame τ from frame 0 is actually τ max calculated by:

τ = 1, 2, ..., n,
1
〈 [ r i ( τ ) – r i ( 0 ) ] 2〉 = -----------
τ max
j=0
∑
[ ri ( τ + j) – ri ( j) ] 2

Where τmax = (n - τ).

The short-time MSD, with a small τ, may be determined with
slightly greater statistical precision because the number of terms in
the average τmax may be greater.
This calculation is workable for both the minimum image and the
explicit image options for periodic boundary conditions in the Dis-
cover program. A correction is made for (translational) switching
between images, if the explicit image model in Discover is used in
the simulation.

256 Insight II/March 2000

 Implementation

Radial Distribution Functions

A radial (or pair) distribution function (RDF), g ab ( r ) , describes
the probability of finding an atom of type b at a distance between
r and r + dr from atoms of type a as a function of the a – b separa-
tion r. The radial distribution function calculations were initially
applied to investigate the modification of the solvent structure
induced by the presence of the solute. Recently, the RDF has been
used to study the dynamical structural modification of dense sys-
tems during a molecular dynamics simulation (Avbelj et al., to be
submitted). In addition, the RDF can serve broader purposes, with
weight factors for each atom at distance r. One such example is the
hydrophobicity contrast function which has been used to search
metal binding sites in proteins (Yamashita et al. 1990).
Furthermore, the ensemble average of any pair function, such as
the nonbonded energy and the pressure, can be related to g ( r )
(Allen and Tildesley 1989).

d 〈 N ab ( r ) 〉
g ab ( r ) = --------------------------- Eq. 41
ρ b dV ( r )

where d 〈 N ab ( r ) 〉 is the average number of type b atoms at the dis-

tance between r and r + dr from a type a atom, ρ b is the bulk den-
sity of type b atoms, and 〈 N ab ( r ) 〉 ⁄ dV ( r ) is the average local
density of type b atoms in the shell volume, dV ( r ) , between r and
r + dr from a type a atom.
Note that the type a atoms refer to the atoms specified by Molecule
Spec, and the type b atoms by Molecule 2 Spec in the Evaluate/
RadialDistFunc command.
The divisor, therefore, normalizes the distribution so that g ab = 1
when d 〈 N ab ( r ) 〉 ⁄ dV ( r ) is the same as the bulk density. Thus, the
RDF represents the factor of local density/bulk density for type b atoms
around type a atoms. Note that the bulk density can either be calcu-
Nb
lated as ρ b = ----------- for a system with a cell, (the Bulk_Density
V cell

Insight II/March 2000 257

9. Analysis Module

parameter is on) or as a unit for a molecular system with no cell

(the Bulk_Density parameter is off).
The coordination number, ab ( R ) , represents the number of type
b atoms around a type a atom at a distance R. The average coordi-
nation number is expressed as:

N ab ( R ) 〉 =
∫d 〈N
0
ab ( r ) 〉 dr . Eq. 42

In this calculation, the g ( r ) is also partitioned into intermolecular

and intramolecular contributions. To explore the structure of a sys-
tem during a dynamics simulation, options are provided for calcu-
lating either g ( r ) for an individual configuration, a set of
configurations (trajectory frames), or the average g ( r ) over a set
of frames. When calculated individually for each of the configura-
tions, they can be plotted as a 3D graph, ( r, g ( r ) , frame number ) .

Command Summary
In addition to the core pulldowns in the top menu bar, the Analy-
sis module adds five pulldowns, Graph, Trajectory, Pseudo_
Atom, Evaluate, and Background_Job to the lower menu bar.

Graph Pulldown
The Graph pulldown allows you to create and manipulate graphs.
These commands are described in the following chapter, Graph
Pulldown.

Trajectory Pulldown
The Trajectory pulldown contains commands for working with
trajectory data. These commands use information from previously
run molecular mechanics simulations.

258 Insight II/March 2000

 Command Summary

Some of the Trajectory pulldown commands are colored gray (e.g.,

the Cluster command, and the commands ending with _Def).
These are not selectable from the pulldown because they are acti-
vated automatically, in a specific sequence, by other non-grayed
commands in this pulldown. However, all the commands shown
in the pulldown are typable.

Get Trajectory
The Get Trajectory command is used to load into the Insight II
program atomic trajectory information contained in history or
archive files that have been generated in previous runs of the Dis-
cover program. The command sets up information needed by
other commands such as Construct_Graph or Animate.

Put Trajectory
The Put Trajectory pulldown allows you to create an archive file
from a loaded trajectory. It may contain all or just some of the
frames of trajectory data that have been loaded. These frames may
be reordered as they are written out.
The original trajectory data may come from a variety of sources: an
archive file, a history file, or a torsion file generated by Search_
Compare or Discover.

Filter Trajectory
The Filter Trajectory command allows you to filter trajectory sets
so that only motions with interesting vibration frequencies
remain. For details on the method used see the previous section on
Frequency Filtering.

Animate Trajectory
The Animate Trajectory command is used to make molecules
move through the conformations calculated during the simula-
tion, as read from the contents of a Discover history or archive file
(trajectory file).

Insight II/March 2000 259

9. Analysis Module

Unanimate Trajectory
The Unanimate Trajectory command is used to permanently stop
an existing animation. The display of the motion of the molecule
or molecular system stops and related printouts are cleared from
the screen. This is different from temporarily stopping an anima-
tion with function key <F8>.

Conformation Trajectory
The Conformation Trajectory command allows you to examine
conformations that come directly, or are derived from trajectory
sets previously computed by, the Discover program. The molecule
or assembly affected by this command is always whatever mole-
cule or assembly was specified when the Get command was last
executed.

Family Trajectory
The Family Trajectory command is used to create, or modify, a
family of conformers based on the values determined from a clus-
ter graph computation. Once a family has been defined it is iden-
tical to an assembly, where each member corresponds to some
frame within the trajectory data. All members of a given family
must be derived from cluster graphs that were defined using the
same set of atoms for comparison.

Repartition_Cluster Trajectory
The Repartition_Cluster Trajectory command allows you to
change the number of conformer families. You can repartition
cluster graph levels, or update the existing display of a cluster
graph, without having to recalculate the RMS values.

Construct_Graph Trajectory
The Construct_Graph Trajectory command is used to create
graphs that plot common properties, such as energy, time, dis-
tances, and periodic properties from previous simulations. You
can also add new plots to existing graphs. The relationship
between any two or three properties can be plotted in any order.

260 Insight II/March 2000

 Command Summary

Axis_Function Trajectory
The Axis_Function Trajectory command is used to associate func-
tions, such as time and energy, with a graph axis when plots are
created. This command is automatically invoked by the
Construct_Graph command and is not usually entered separately.

Cluster Trajectory
The Cluster Trajectory command allows you to create a cluster
graph that displays the results of a structural comparison through-
out the defined trajectory data. Every frame within the trajectory
specified by the Start, End, and Step parameters is compared to
every other frame and the RMS resulting from the superimposi-
tion of the frame pairs is displayed within the cluster graph. This
command is automatically invoked by the Construct_Graph com-
mand and is not usually entered separately.

Distance_Def Trajectory
The Distance_Def Trajectory command is used to assign a dis-
tance between two unique atoms to an axis on a graph. For exam-
ple, to see how a distance between two atoms varies over time, you
can assign a time function to the x axis using the Axis_Function
command and a distance value to the y axis with the Distance_
Def. This command is automatically invoked by the Axis_Func-
tion command and is not usually entered separately.

COM_Distance_Def Trajectory
The COM_Distance_Def Trajectory command allows you to
define a distance between two centers of mass. This command is
automatically invoked by the Axis_Function command and is not
usually entered separately.

Angle_Def Trajectory
The Angle_Def Trajectory command is used to assign an angle
between three unique atoms to an axis on a graph. For example, to
see how an angle between three atoms varies over time, you can
assign a time function to the x axis using the Axis_Function com-
mand and an angle function to the y axis with the Angle_Def com-

Insight II/March 2000 261

9. Analysis Module

mand. This command is automatically invoked by the Axis_

Function command and is not usually entered separately.

Dihedral_Def Trajectory
The Dihedral_Def Trajectory command is used to assign a dihe-
dral angle defined by four unique atoms to an axis on a graph. For
example, to see how a particular dihedral angle varies over time,
you can assign a time function to the x axis using the Axis_Func-
tion command, and dihedral to the y axis with the Dihedral_Def
command. This command is automatically invoked by the Axis_
Function command and is not usually entered separately.

PP_Ang_3_Def Trajectory
The PP_Ang_3_Def Trajectory command is used to assign an
angle between two planes to an axis on a graph, using only three
points to calculate the plane. For example, if you want to see how
a particular angle between two planes varies over time, you can
assign time to the x axis using the Axis_Function command, and
PP_Ang_3_Def to the y axis using the PP_Ang_3_Def command.
This command is automatically invoked by the Axis_Function
command and is not usually entered separately.

PP_Ang_n_Def Trajectory
The PP_Ang_n_Def Trajectory command is used to assign an
angle between two planes to an axis on a graph, using three or
more unique points to calculate the plane. This command is auto-
matically invoked by the Axis_Function command and is not usu-
ally entered separately.

pP_Dist_3_Def Trajectory
The pP_Dist_3_Def Trajectory command is used to assign a dis-
tance between a point and a plane, using only three points to cal-
culate the plane. This command is automatically invoked by the
Axis_Function command and is not usually entered separately.

pP_Dist_n_Def Trajectory
The pP_Dist_n_Def Trajectory command is used to assign a dis-
tance between a point and a plane to an axis on a graph, using

262 Insight II/March 2000

 Command Summary

three or more points to calculate the plane. This command is auto-

matically invoked by the Axis_Function command and is not usu-
ally entered separately.

COM_P_Dist_n_Def Trajectory
The COM_P_Dist_n_Def Trajectory command allows you to
define a distance between a center of mass and a plane. This com-
mand is automatically invoked by the Axis_Function command
and is not usually entered separately.

Energy_Def Trajectory
The Energy_Def Trajectory command allows you to use the
energy components found within a Discover program history file
to define an axis energy function. If the trajectory information is
from an archive file, then only the total energy may be defined.
This command is automatically invoked by the Axis_Function
command and is not usually entered separately.

Tabulate Trajectory
The Tabulate Trajectory command is used to create a table that
displays the selected trajectory properties. Each property is repre-
sented by a column of information, with the name of the property
heading the column. You can select which frames are output as
well as which atoms.

Pseudo_Atom Pulldown
The Pseudo_Atom pulldown contains commands to create and
modify pseudoatoms. The Define Pseudo_Atom command cre-
ates the pseudoatoms. The Rename Pseudo_Atom and Delete
Pseudo_Atom commands modify the already defined pseudoa-
toms. The List Pseudo_Atom command lists information about
the pseudoatoms. For more extensive descriptions of these com-
mands, refer to their descriptions in the Builder Module chapter
of this guide.

Insight II/March 2000 263

9. Analysis Module

Background_Job Pulldown
The Background_Job pulldown allows you to set up background
jobs to run concurrently or interactively with the Insight II pro-
gram. You are given the choice of whether to send background
jobs to a local or remote host. This pulldown is generic and is
found in many modules that run background jobs. The
Background_Job pulldown contains the following commands:
Setup_Bkgd_Job, Control_Bkgd_Job, Completion_Status, and
Kill_Bkgd_Job. Refer to the Background Job Pulldown chapter for
more information.

Methodology
Quantitative analysis of trajectory data usually results in the cre-
ation of a simple trajectory graph or a cluster graph. The steps usu-
ally followed to create a simple trajectory graph are:
1. The Get Trajectory command is used to read in trajectory data
(a .his file) and associate the data with the molecule or molecu-
lar system being studied (a .car or .arc file). The associated sys-
tem must already be loaded when you issue the Get Trajectory
command.
2. The Filter Trajectory may (optionally) be used to remove
unwanted vibrational frequencies from the trajectory data.
3. The Construct_Graph Trajectory command is used to begin the
sequence of steps followed to create a simple trajectory graph.
In this case, the Cluster_Graph parameter should be set to off.
If the New_Graph parameter is set off, you may use the
Graph_Name parameter to add plots to an existing graph.
When New_Graph is on, a new graph is created. If the Map
parameter is on, you can indicate which contour map to over-
lay in the graph through the Map_Name parameter.
4. When the Construct_Graph Trajectory command is executed
(from the menu), the Axis_Function Trajectory command is
automatically invoked. The type of property (time, energy, tem-
perature, or geometry) to be plotted on each axis is selected and
the command is executed.

264 Insight II/March 2000

 Methodology

5. For geometric or energy properties, when the Axis_Function

Trajectory command is executed another command (such as
Distance_Def, Angle_Def, Dihedral_Def, PP_Angle_3_Def,
PP_Angle_N_Def, pP_Dist_3_Def, pP_Dist_N_Def, Com_P_
Dist_N_Def, or Energy_Def from the Trajectory pulldown) is
automatically invoked. In these commands you give the appro-
priate details (such as atom selections or energy components)
to fully define the property you have already chosen.
6. Finally, you set the Function_Mode parameter in the Axis_
Function Trajectory command to End_Graph and execute the
command. This creates the graph curve.
The steps usually followed to create a cluster graph are:
1. The Get Trajectory command is used to read in trajectory data
and associate the data with the molecule or molecular system
being studied.
2. The Filter Trajectory command may (optionally) be used to
remove unwanted vibrational frequencies from the trajectory
data.
3. The Construct_Graph Trajectory command is used to begin the
sequence of steps followed to create a simple trajectory graph.
In this case, the Cluster_Graph parameter should be set to on.
4. When the Construct_Graph Trajectory command is executed
(from the menu), the Cluster command is automatically
invoked. Leaving the End_Definition parameter off, a list of
atoms to be used in the RMS comparisons is built by one or
more executions of the Cluster Trajectory command. Then the
End_Definition parameter is turned on, and the maximum
RMS cutoff value and the number of families to be grouped is
defined. When the Cluster Trajectory command is executed,
the cluster graph is built.
The Get Graph, Equation Graph, Correlate Graph, and Boolean
Graph commands can be used to create more simple trajectory
graphs as well as inanimate graphs. These commands are dis-
cussed in detail in Chapter 8 of this manual.
Qualitative analysis of trajectory data may be achieved with the
Animate Trajectory command to view molecular motions in real-
time.

Insight II/March 2000 265

9. Analysis Module

Memory Limitations
It is important to note that the Get Trajectory command causes
large amounts of memory to be used for the storage of the data. If
you are only interested in animating the molecule or molecular
system without creating any graphs, the Get Trajectory command
may be omitted. If the Get Trajectory command is not used to read
in the data, the file containing the data is specified as a parameter
to the Animate command. It should further be noted that the
amount of memory used in the Animate command is directly pro-
portional to the complexity of the display. If you are animating
large molecules, limit the number of atoms displayed and the
number of colors used in order to conserve memory. If you are
only interested in creating graphs, the molecule(s) or molecular
system should not be animated.

Analysis Tutorial
As of this release, most tutorials are now available online for use
with the Pilot interface. To access the online tutorials for Analysis,
click the mortarboard icon in the Insight II interface.
Then, from the Open Tutorial window, select Insight II tutorials,
then the Analysis module and choose from the list of available les-
sons:
Lesson 1 Using Trajectory Commands
Lesson 2 Using Pseudoatoms
Lesson 3 Getting the Data of a Box of Water
Lesson 4 Compute the Pair Distribution Function for a Box
of Water
Lesson 5 Compute the Mean Square Displacement for a
Box of Water

You can access the Open Tutorial window at any time by clicking
the Open File button in the lower left corner of the Pilot window.

266 Insight II/March 2000

 Analysis Tutorial

For a more complete description of Pilot and its use, click the on-
screen help button in the Pilot interface or refer to the Insight II
User Guide.

Insight II/March 2000 267

9. Analysis Module

268 Insight II/March 2000

10 Graph Pulldown

Implementation
The Graph pulldown contains commands that allow you to create
graphs, modify their appearance, and query their data. These com-
mands work on all types of graphs (e.g., those created from atomic
trajectory data, or any other source of data). A number of other
graph-related commands that work only with atomic trajectory
data can be found in the Trajectory pulldown. Note that through-
out this chapter, commands are listed in the format Pulldown/Com-
mand. This is a shorthand notation for the typed form of a
command. For example, Graph/Get specifies the Get command
from the Graph pulldown, and is exactly equivalent to the typed
form: Get Graph.
Graphs can be created from numbers in an ASCII file using the
Graph/Get command. They can also be created by copying exist-
ing plots (with automatic combination of thresholds) using the
Graph/Boolean command. The data from existing plots can be
correlated to form a new plot using the Graph/Correlate com-
mand. Or, new plots can be created with arbitrarily complex equa-
tions using the Graph/Equation command.
Contour maps can be added to graphs with the Graph/Contour
command. Display attributes such as colors used on the various
lines, curves, and points in graphs can be altered using the options
in the Graph/Color command. Text labels used to describe mini-
mum and maximum values and to describe axes can be modified
with the Graph/Label command. Tick marks (with or without
labels) can be created with the Graph/Tick_Mark command. The
scale of this text can be adjusted with the Graph/CharSize com-
mand. The axes can be moved from one side of the graph to the
other, or can be inverted, using the Graph/Move_Axis command.
Data points along the plot curves can be displayed or hidden using

Insight II/March 2000 269

10. Graph Pulldown

the Graph/Modify_Display command, which also controls the

display of the line segments that connect data points along a plot
curve. Bar graphs can also be constructed with the Graph/
Modify_Display command. You can zoom in or out on portions of
plot curves using the Graph/Threshold command. Similarly, the
box enclosing the plots can be scaled and reshaped with the
Graph/Scale_Axis command.
Graph/Integration, Graph/Differentiation, Graph/FFT_Real,
and Graph/Smoothing can be used to perform various numerical
operations on any curves in 2D or 3D graphs.
The actual data points on plot curves and the functions used to
derive those points can be queried with either the Graph/Put or
Graph/Info commands.

Equation
With the Graph/Equation command you can create plots of equa-
tions defined from data contained in other plots or from lists of
numbers in simple ASCII files. These equations consist of opera-
tors and operands. An operand may be a graph plot specification,
or a file and function specification, or a constant numeric value.
Any graph property that can be displayed by a plot can be an oper-
and, except cluster plots. An operator is a mathematical function,
such as addition or subtraction. The full list of operators is
described below.
There are five classes of operators (listed in Table 2) grouped
according to the operation each performs, and according to their
individual syntax requirements.
A number is any integer or decimal value. Negative number must
be enclosed within parentheses. An integer must be a positive,
nondecimal value.
An expression may be any grouping of the above syntax classes
enclosed within parentheses, or may be a single operand. There
are two groups of operands: number (a fixed numeric value,
allowing creation of baselines for graphs) and plot or file/function
specification.
A plot specification is:

270 Insight II/March 2000

 Implementation

Table 2. Operator Classes and Syntax

MATH: syntax: expression operator expression
operators: + add
- subtract
* multiply
/ divide
TRIG: syntax: operator (expression)
operators: sin sine
cos cosine
tan tangent
asin arc sine
acos arc cosine
atan arc tangent
UNIT: syntax: operator (expression)
operators: log logarithm, base 10
ln natural logarithm
abs absolute value
exp exponential
POWER: syntax: expression operator number
operators: ** power
^ power
(There is no difference between these.)
AVE: syntax: operator (expression)
average of all values of expression
operator (expression real-number real-number)
average of expression using only values
between the first and second numbers (the
real-numbers must have a decimal point)
operator (expression integer integer)
average of expression using only frames
between the first and second integers
operators: ave average
avg average
(There is no difference between these.)

graph<graph_number>:<plot_number>:<data_point>:axis

Insight II/March 2000 271

10. Graph Pulldown

where <graph_number> and <plot_number> are integers, <data_

point> is either an asterisk or empty, and axis may be x, y, or z. For
example:
graph<graph_number>:<plot_number>:*:axis
graph<graph_number>:<plot_number>::axis
A file/function specification is:
file(<file_name>,<column_number>)
or:
file(<file_name>,<function_name>)
where <file_name> refers to a file having the graph file format
(described in Appendix B), <column_number> is an integer which
refers to a specific column of numbers in the file, and <function_
name> is a string which also refers to a specific column of numbers
in the file. Either <column_number> or <function_name> should be
specified, but not both. The left-most column is considered num-
ber one. For examples of valid equations, refer to the on-line doc-
umentation for the Graph/Equation command.

Correlate
The Graph/Correlate command is used to perform auto- and
cross-correlations on graphs. The formula for standard correla-
tions is:

N–j
1
C ( j ) = -----------
N–j ∑ A ( i) × B ( i + j)
i=1

For a normalized correlation, the formula is:

N–j

N i=1
∑ A ( i) × B ( i + j)
C ( j ) = ----------- -------------------------------------------------
N
-
N–j

∑i=1
A ( i) B ( i)

272 Insight II/March 2000

 Command Summary

where C is the correlation, N is the number of frames, and A and B

are the functions being correlated. The variable j refers to the cur-
rent frame minus 1. The “current frame” starts as 1 and ends as N.
In the case of auto-correlations, A and B are equal.

Command Summary

Graph Pulldown
The Graph pulldown commands allow you to create and manipu-
late graphs.

Get
The Graph/Get command is used to create graphs that plot func-
tions whose domain and range are specified in files which have
been generated by the Put Graph command, by the various Poly-
mer application modules, or in files that have been created manu-
ally, following the file format described in Appendix B.

Put
The Graph/Put command is used to put the data used in a graph
into a file. If more than one graph is specified, only the unique data
from each graph is written to a file.
With the exception of cluster graphs, all plots written to a file using
the Put command (with the Header Style parameter set to the
Title option and the External_File parameter off) can be used to
create new plots with both the Graph/Get and Graph/Equation
commands.
You can also create files that can be used as input to the Insight II
program’s Contour utility. Extra information is put at the start of
the file so that the file can be used for this purpose. Please refer to
the Put Graph on-line command description.

Insight II/March 2000 273

10. Graph Pulldown

Boolean
The Graph/Boolean command allows you to create new plots by
cloning plots from existing graphs. The new plots all share the
same thresholds that are formed by unioning or intersecting exist-
ing threshold lists. When you union thresholds, you are able to see
at least as much of each plot as you could see before they were
cloned. This is because you are seeing thresholds that are merged
(unioned) together. When you intersect thresholds, you may see
less of each plot because you are looking at only those sections of
the plots where thresholds overlapped (intersected). You can also
use the Boolean command to clone plots that have no thresholds.
In this case, the command is merely a tool that simplifies the task
of copying plots.

Correlate
The Graph/Correlate command is used to either auto- or cross-
correlate plots on existing graphs. By default, the correlation result
is normalized.

Equation
The Graph/Equation command is used to create a graph that uses
mathematical expressions to describe each axis. Existing graph
functions or data from files produced by the Put command are
used as operands within the equation.

Contour
The Graph/Contour command creates a set of contours composed
of the specified contour levels from a specified Insight II program
graph plot, or from a Contour File. A contour level is a curve (or
surface) connecting all of the points in the given graph which have
the same value. This contour is automatically displayed in a
graph.
When creating contours from a graph plot, you may create a single
contour level or a range of contour levels, or you may delete a sin-
gle contour level from an existing contour.

274 Insight II/March 2000

 Command Summary

Line_Fit
The Graph/Line_Fit command allows the determination of the
equation of the line that best fits the data points contained in a
selected curve segment. The results can be displayed as a line on
the graph being examined. The equation of the line is reported as
well.

Interpolation
The Graph/Interpolation command allows you to interpolate an
existing graph with either the linear or cubic spline method. It also
allows you to modify the number of points in the graph.

Integration
The Graph/Integration command enables you to integrate a plot
using the trapezoidal rule. Since a plot is a set of discrete data, the
trapezoidal rule is sufficient. You can specify the plot by picking
from a graph, and specify the integration range by setting start and
end data-points. By default, the start and end data-points are set to
the first and last data points in the plot. The results are given in
two ways: a plot showing the running integration, and a numerical
value of the total integral. The former can be plotted in either a
new graph or in an existing graph; the latter is displayed in the
Information area.

Differentiation
The Graph/Differentiation command enables you to calculate
derivatives of a plot by using the Central Differences method. You
can specify the plot by picking from a graph. By default, the calcu-
lation is conducted over the entire range of the plot on the inde-
pendent axis. However, you can specify a smaller region to
integrate by setting the start and end points in the parameter
block. The results are given as a plot showing the running deriva-
tives in a new graph or in an existing graph.

FFT_Real
This command performs fast Fourier transform for an one-dimen-
sional, real function. The input-data must be even-spaced and the
number of points must be an integer power of 2. Failure of the first

Insight II/March 2000 275

10. Graph Pulldown

requirement leads to stop of calculation. If the second re

ment is failed, the data will be truncated, to the largest, av
integer power of 2. Only the real-part of the results (Pow
trum) are given, which are plotted in a new graph or an e
graph.

Smoothing
Two methods are provided in the Graph/Smoothing com
to enable you to smooth a plot. The Least_Squares met
reconstructs data by three-point fitting the input data to
order polynomial. This procedure can be repeatedly per
by specifying the parameter N_Iteration. The Fourier_T
form method transfers the input data into frequency spa
ters out high-frequency components according to the par
Window_Size, then restores the data by reverse transfor
N_Iteration and Window_Size affect the results obtaine
larger these values are, the smoother the results. The res
given as a plot in a new graph or an existing graph.

CharSize
The Graph/CharSize command allows you to change an
the size of text associated with graphs.

Color
The Graph/Color command is used to specify and alter
ors for portions of a graph such as axes, box segments, l
cursors, dynamic numbers, and plots (in their entirety o
segments). If an axis is recolored, the axis, the label, and t
imum and maximum values are all displayed in the new
You can color a graph using predefined colors, as well as
and hues of predefined colors.

Label
The Graph/Label command allows you to customize the
the labels on the x, y, or z axis of a graph, or the minimu
maximum labels on the x, y, or z axis of a graph. Each gra
also have an overall label that is placed just above the gra
maximum number of characters allowed in an axis labe
276 Insight II/March 2000 The maximum number for the overall label is 29. The ma
number of characters displayed for the minimum and ma
 Command Summary

Move_Axis
The Graph/Move_Axis command allows you to change the
position or orientation of an axis on a graph. By setting the
Shift_Axis parameter to on, the axis can be moved to a position
that is parallel to but opposite from the old position. This can be
used with the Color command (for coloring box segments) and
the Transform/Overlay command to create what looks like a sin-
gle graph with opposing axes.
By setting the Invert_Axis parameter to on, the axis can be
inverted. That is, its origin and termination are exchanged. The
origin of the graph can thereby be moved to a different corner of
the graph box.

Modify_Display
The Graph/Modify_Display command allows you to alter the
display characteristics of a graph plot. Some options are:
♦ display the plot as a single line
♦ display the plot as a set of bars
♦ display the plot as a disconnected set of points
In addition, you can control the scale of the points, and the width
and direction of the bars. Various combinations of the options
above are also possible.
The notion of displaying data points can be important when
using commands like Trajectory/Conformation, where you fre-
quently pick individual data points. The picking (and the differ-
entiating between points) is made much easier by temporarily
turning on display of the points.

Scale_Axis
The Graph/Scale_Axis command allows you to scale any of the
graph axes.

Threshold
The Graph/Threshold command allows you to zoom in on por-
tions of a plot, or to set an axis’ minimum or maximum limits.
Plot functions that are periodicInsight
(such as angle measurements)
II/March 2000 277
cannot be used in the Threshold command.
10. Graph Pulldown

Tick_Mark
With the Graph/Tick_Mark command you can add, modify, or
remove tick marks and their labels on any axis.

Info
With the Graph/Info command you can get information pertain-
ing to plots or map contours in graphs.
For plots, you are told which functions are set for the x, y, and z
axes. For functions that use atom selections (such as distance,
angle, etc.), you are told specifically which atoms were chosen.
However, graphs created with the Get command do not retain the
history of what atoms (if any) their data pertain to. Therefore, exe-
cuting Info for graphs created with the Get command do not list
any atoms. In some cases you may be able to find the atom refer-
ences in the top of the file used as input to the Get command.
For map contours, you are told the contour level (for example, the
energy level) and the x, y, and z values for the data point on the
contour. For example, if a map relates two dihedral angles to the
energy of a conformation, then Graph/Info might tell you that a
given point on a particular contour corresponds to energy level -
0.50, and that the two dihedral angles are 140.00˚ and -60.00˚,
respectively.
Among the parameters contained in the Info command are Graph
and Map. By setting these to On or Off, you specify whether you
are interested in plot or map information. You may set one or both
of them On.
Depending on the values of the Graph and Map parameters, you
may need to give a plot point (in the Graph Spec parameter) or a
map contour point (in the Map Spec parameter). You may type in
either of these parameter values or you may interactively pick
them off of a graph. If you pick a point at which a plot and a map
contour meet, both parameters are filled in simultaneously. If a
plot or map point is given, the coordinates of the point are also
given.
If Info does not give you enough information, try the Put com-
mand. Also note that when you pick a plot point when no param-
eter block is active, the x, y, and z values are given along with the
full plot point specification.

278 Insight II/March 2000

 Command Summary

Figure 28. Graph/Threshold Examples

A.No thresholds.
B.(Both plots) X axis thresholded from 10 to 15, but not zoomed in.
C.(Both plots) X axis thresholded from 10 to 15, and zoomed in.
D.(Top plot only) X axis thresholded from 10 to 15, but not zoomed in.
E. (Both plots) X axis thresholded from 4 to 6 and 8 to 10, and zoomed in.
F. (Top plot) X axis thresholded from 8 to 10.
G.(Both plots) X axis thresholded from 6 to 8, Y axis thresholded from 9 to 14, and
zoomed in.
H.(Both plots) Y axis thresholded from 0 to 20, and zoomed out.
I. (Top plot only) Y axis thresholded from 10.46 to 12.45.

Insight II/March 2000 279

10. Graph Pulldown

Tutorial
As of this release, most tutorials are now available online for use
with the Pilot interface. To access the online tutorials for Graph,
click the mortarboard icon in the Insight II interface.
Then, from the Open Tutorial window, select Insight II tutorials,
then the Graph Pulldown option and choose from the list of avail-
able lessons:
Lesson 1 Basics, Interpolation, and Numerical application
You can access the Open Tutorial window at any time by clicking
the Open File button in the lower left corner of the Pilot window.
For a more complete description of Pilot and its use, click the on-
screen help button in the Pilot interface or refer to the Insight II
User Guide.

280 Insight II/March 2000

11 Background_Job Pulldown

Theory
Much of the computational work within MSI products is per-
formed by background jobs that are run using the Insight II pro-
gram as the user interface. Background jobs run concurrently with
the interactive Insight II program; this is possible because, once
started, they do not require user interaction. If you have access to
more than one computer (mainframe or workstation), you may
wish to run some of the background jobs on a different computer
(hereafter called remote host) than the computer which is running
Insight II (hereafter called local host).
In order to run the background job on a remote host, there are sev-
eral general requirements:
♦ The actual background job program must exist as an executable
image for that host.
♦ Files transferred between local and remote hosts must be read-
able and writable on both hosts.
♦ You must have an account on the remote host—and sufficient
disk space to contain all of the input, temporary, and output
files produced by that background job.
The local host must be able to communicate statuses, submit jobs,
and copy files to the remote host.
Making an executable image compatible with a remote host
involves recompiling and relinking the program; this is done by
Biosym for host types which the company supports.

Insight II/March 2000 281

11. Background_Job Pulldown

Network Queuing System and Background Jobs

Background jobs are started up from Insight II in immediate sub-
mission mode: the job is run on the selected machine immediately
upon submission. In queued mode, background jobs are submitted
to a queue. The queueing mechanism pulls jobs from the queue
and starts them on one of the machines available for the queue.
Typically, each job is run to completion before the next job is pulled
off the queue. Support for a queuing software package, known as
the Network Queuing System (NQS), is now available to allow the
you to submit background jobs to a queue on a local or remote
machine.
Brent A. Kingsbury (Sterling Software) explains the origins of
NQS in a report entitled The Network Queueing System (see the NQS
documentation). “The invention of the NQS was driven by the
need for a good UNIX batch and device queueing facility capable
of supporting such requests in a networked environment of UNIX
machines. More specifically, NQS was developed as a part of an
effort aimed at tying together a diverse assortment of UNIX based
machines into a useful computational complex for the National
Aeronautics and Space Administration (NASA).”
It is up to you to acquire and install NQS products and deal with
its support issues. The Background_Job queueing mechanism
takes a properly configured NQS for granted.
NQS is available over the internet via anonymous ftp from archie
sites. It is also available with a GNU license.

Implementation
The Background_Job pulldown interface is the access point to a
system which allows submission of background jobs on both local
and remote hosts. This is a generic pulldown, which means that it
appears in more than one module of the Insight II program. The
commands found within this pulldown are used to set up, moni-
tor, and kill background job execution. Refer to the System Guide
for a detailed description of the mechanism used to invoke back-
ground jobs.

282 Insight II/March 2000

 Command Summary

The machinery for using NQS is available from within the

Background_Job/Setup_Background_Job command.
The Background_Job/Control_Bkgd_Job command allows inter-
active control of an already running background job. This com-
mand is currently available only for background jobs submitted by
the DGII/DGII_Run command. Attempting to use the Control_
Bkgd_Job command from any command other than DGII_Run
simply results in no execution of the command.

Command Summary

Background_Job Pulldown
The Background_Job pulldown allows you to set up background
jobs to run concurrently or interactively with the Insight II pro-
gram. You are given the choice of whether to send background
jobs to a local or remote host. This pulldown is generic and is
found in many Insight II modules that run background jobs. The
Background_Job pulldown contains the following commands:
Setup_Bkgd_Job, Completion_Status, Kill_Bkgd_Job, and
Control_Bkgd_Job.

Setup_Bkgd_Job
The Background_Job/Setup_Bkgd_Job command allows you to
set up the execution mode and select the host upon which to run a
job. In addition, this command can be used to control the notifica-
tion method for background job completion and cleanup options.

Control_Bkgd_Job
The Background_Job/Control_Bkgd_Job command allows you
to coordinate running background jobs by detaching or attaching
selected background jobs to the Insight II program. In addition,
this command allows you to specify the interval for invoking a
task specific to a particular background job for processing its out-
put.

Insight II/March 2000 283

11. Background_Job Pulldown

Completion_Status
The Background_Job/Completion_Status command allows you
to monitor and evaluate the completion status of one or all of the
background jobs. In addition, this command can be used to look
up the meaning of a given return status code.

Kill_Bkgd_Job
The Background_Job/Kill_Bkgd_Job command is used to termi-
nate execution of a background job that has been submitted during
the current session.

Methodology
Use of the Background_Job pulldown is optional. If not used, the
default is to run all jobs on the local host in Cont_Insight mode of
the Background_Job/Setup_Bkgd_Job command. When the
Background_Job/Setup_Bkgd_Job command is used, the back-
ground job list only shows those background jobs which are run
from the current module and which can be run on a remote host.
If the module contains only one job, the parameter is automatically
filled. The list of hosts only shows those hosts which are associated
with that background job in the background_job_hosts file at your
site. It is possible for you to specify a remote host that is unavail-
able (off line, for instance) or for which you have no login account.
Use the Background_Job/Control_Background_Job command to
coordinate running background jobs by detaching or attaching
selected background jobs to the Insight II program. In addition,
you can use this command to specify the interval for invoking a
task specific to a particular background job for processing its out-
put.
Every background job submitted via the generic background util-
ity is assigned a job number. This number is displayed in the infor-
mation area when the job is submitted (e.g., Starting RIS
background job on iris5 as job 1). You should note the
job number when the job is submitted since it can be used later to
check on the job’s completion status, control the job while it is still
running, or to kill the job.

284 Insight II/March 2000

 Methodology

Setting Up a Background Job

The Setup_Bkgd_Job command does not actually run the com-
mand; it simply records your host and Execution_Mode prefer-
ence. The default host is local. Your selected host and Execution_
Mode are used for any subsequent background job runs for the
duration of the session. When you start up a new session, all back-
ground job parameters are again set to their default values.
The Execution_Mode parameter allows you to choose to run a
given background job concurrently (Cont_Insight), run the job
interactively (Wait_For_Job), or simply create the necessary com-
mand files to submit the job, but not actually execute them (Cmd_
File_Only).
The Send_Mail parameter allows you to have the system send you
an electronic mail message upon completion of the background
job. This parameter is not active if Execution_Mode is set to Wait_
For_Job. You may find this option useful when running long jobs
where you exit the Insight II program before the job completes.
The Save_Cmd_Files parameter allows you to save the command
file used to submit the background job (bkgd_job_<run_
name><n>.csh). This file is otherwise deleted when the job com-
pletes. This parameter is not active when Execution_Mode is set
to Cmd_File_Only.
All background jobs return a completion status. The completion
status is an integer code that indicates success, failure, and/or rea-
son for failure of the job. The status code is always displayed when
you are notified that the job has completed.
If you consistently want to send background jobs to another host,
you can modify your personal Insight II program start-up file to
invoke Setup_Bkgd_Job for each module/background job(s) that
you want to automatically assign. Note that you must first change
to the module in which the background job’s interface is found
before using
Setup_Bkgd_Job to set a preference for that background job.
The Completion_Window parameter can be used to turn off the
notification window that appears when the background job com-
pletes. The default value is on.

Insight II/March 2000 285

11. Background_Job Pulldown

Support for the Network Queuing System (NQS) is now available

from within the Background_Job/Setup_Bkgd_Job command.
In order for the user interface to present parameter defaults and a
value-aid containing available queues, and to correctly formulate
an NQS command, it is necessary to provide the user’s NQS queue
environment information. The Background_Job_Hosts file con-
tains the NQS queue information, or you may enter the required
information directly using the Background_Job/Setup_Bkgd_
Job command.
Based on the parameter values provided in the Background_Job/
Setup_Bkgd_Job command for Queued_Submission_Mode, the
background job mechanism formulates a standard NQS command
and starts a process to execute it. It is assumed that the NQS com-
mand constructed by the Insight II program functions on your
NQS configuration.

Examining Completion Status

The Completion_Status command is used in one of three modes
of operation. The One_Job option displays a brief message indi-
cating if a specific job has completed or not. The message is dis-
played in the information area of the screen. Certain background
jobs generate a status file containing additional information while
they are running. If this additional status information is available,
it is displayed to the textport. See the Implementation section of the
module you are interested in for a detailed description of the infor-
mation provided in the background job status file. If All_Jobs is
chosen, the job number, job name, run name, status code, and job
status are displayed in the textport for every job submitted during
the current session. The Look_Up_
Status option is used to look up the meaning of a return status
code.
The Report_Mode enumerated parameter is used to indicate what
information you would like the command to return: status of one
job, status of all jobs, or look up the meaning of a return status code
from a particular background job.
The Job_Number parameter becomes active when One_Job is
selected. It is used to specify a unique background job that you
wish to monitor.

286 Insight II/March 2000

 Tutorial

The Background_Job and Status parameters become active when

Look_Up_Status is chosen. They are used to specify a status code
that you would like to look up.

Killing a Background Job

The Kill_Bkgd_Job command is used to stop execution of a back-
ground job by killing the process in which it is running and option-
ally deleting its output files.
The Job_Number parameter is used to specify which background
job to kill. A value-aid containing a list of all currently running
background jobs is provided.
If the Save_Output parameter is toggled on, then all output files
generated by the background job are saved when the job is killed.
The default value of this parameter is off, in which case all output
files are deleted.

Tutorial
As of this release, most tutorials are now available online for use
with the Pilot interface. To access the online tutorial for
Background_Job, click the mortarboard icon in the Insight II inter-
face.
Then, from the Open Tutorial window, select Insight II tutorials,
then the Viewer module and choose:
Lesson 9 Use of Background Job commands
You can access the Open Tutorial window at any time by clicking
the Open File button in the lower left corner of the Pilot window.
For a more complete description of Pilot and its use, click the on-
screen help button in the Pilot interface or refer to the Insight II
User Guide.

Insight II/March 2000 287

11. Background_Job Pulldown

288 Insight II/March 2000

 Introduction

12 Biosym Command Language

Introduction
The Biosym Command Language (BCL) is a full featured scripting
language that allows you to add your own commands, menus, and
modules to the Insight II program.
BCL macros range from simple collections of existing Insight II
commands to complex programs that perform file I/O, Insight II
data manipulation, and powerful arithmetic computations. For
example, you might want to create a new command that gets a
molecule from a file, colors it, and visualizes it in a ball-and-stick
representation all in one step. Or you may want to gather data
from a group of molecules and generate a table. New commands
created with BCL can then be added to existing menus, new
menus, or entirely new modules.

Creating Commands
To create a new command with a BCL macro, you create a text file,
or start with an existing log file, and describe the new command’s
name, parameters, parameter block appearance, processing, and
output. The BCL macro is then loaded using the File/Source_File
command and can be added to a menu with the Custom/Add_To_
Pulldown command. Your new command can now be used in the
same way as all other Insight II commands.

Creating Pulldown Menus and Modules

To create new menus and modules, simply add Define_Module
and Define_Menu statements to the source file. New menus can be
added to existing modules, or to new modules, allowing you to
create an entire user interface with BCL.

Insight II/March 2000 289

12. Biosym Command Language

BCL vs. Open Interface

Open Interface (OI) is a Biosym product providing C library func-
tions that let you do everything BCL can do and more. OI pro-
grams run faster than BCL macros but are typically larger and
more difficult to write and debug. BCL is often used to prototype
commands which are then recreated with OI. To learn more about
the Open Interface program, consult that program’s manual or
speak with your Biosym sales representative.

How to Use this Guide

This chapter is divided into three sections. The first section is a
series of tutorials to introduce BCL programming. The second sec-
tion is an overview of the language, broken down by topics, such
as File I/O, and Parameter Blocks. The third section is a reference.
We recommend that you start with the tutorials, then read the
overview, turning to the reference as needed to get complete
descriptions.

Examples
More than one hundred BCL macros can be found in the $BIO-
SYM/gifts directory.

Font Conventions of this Guide

♦ Code examples are shown in the Courier font.
♦ BCL keywords in definitions are shown in boldface type.
♦ [Optional] parameters are shown in square brackets.
♦ Words (tokens) in definitions that must be replaced are shown in
italics.

290 Insight II/March 2000

 BCL Tutorial

BCL Tutorial
The following tutorials walk you through the creation of BCL mac-
ros. The first tutorial, “hello.bcl” starts from scratch, giving step by
step instructions for creating, loading, running, and modifying a
simple macro. The second tutorial, “myget.bcl” starts with an
Insight II log file, then adds parameters. The third tutorial has you
enter and run a working example program that shows many of the
features of BCL.
Note: If you are unfamiliar with Insight II commands such as
Color Molecule, refer to the Viewer tutorials in chapter 2 first.

Tutorial 1: hello.bcl

Create and iteratively modify a simple BCL macro.

1. Create the text file

Start a text editor, such as vi or emacs. Enter the text below and save the
file as hello.bcl

Define_Macro hello
Print ”Hello BCL World!”
End_Macro

Insight II/March 2000 291

12. Biosym Command Language

2. Start the Insight II program

Note: we recommend invoking Insight from a separate window, so
that you can continue editing your macro and iteratively test it.

3. Load your macro

Select the File/Source_File command.

Type the name of your macro, hello.bcl, and select Execute.

4. Invoke your macro

Move your cursor to the command line and enter the name of the macro:
hello

The string “Hello BCL World” is printed to the info area and textport.
If any error messages appeared in the info area during steps 3 or 4, try
to fix them during step 5.

5. Fix/Enhance your macro

Edit the file so it appears as shown below, and save it under the same
name.

Define_Macro hello sstring Person

Print ”Hello to ” $Person ”from BCL!”
End_Macro

You have added a parameter, called Person of the type sstring. This
parameter type holds up to 19 characters. The print statement now
outputs whatever name you enter.

292 Insight II/March 2000

 BCL Tutorial

6. Reload your macro

Since you modified your macro, you need to reload it. Repeat step 3.

Since you will probably be repeating this step several times, you may
wish to use abbreviations (type source hello.bcl) and use history
(type !s). Also, you may find it more convenient to work in the text-
port.

7. Re-invoke your command

Enter hello. At the prompt for Person [no default], enter your name.

8. Add your command to the menu

Select the Custom/Add_To_Pulldown command. Enter hello at the

Macro Name prompt, accept the default Pulldown Name, and Execute.

For convenience, we recommend adding this command to the BCL

source file. For example, the last line of the hello.bcl file might be:
Add_To_Pulldown hello Custom
The macro is then automatically added to the menu whenever the
macro is loaded.

Insight II/March 2000 293

12. Biosym Command Language

9. Invoke your command from the menu

Select your new Custom/hello command, fill in the name, and Execute.

10. Iterate

Use a text editor to add additional parameters and print statements.

Reload and re-invoke your macro from the command line and menu.

294 Insight II/March 2000

 BCL Tutorial

Tutorial 2: myget.bcl
Use an Insight II log file to create a simple BCL macro.

1. Invoke Insight II

2. Get a molecule of your choice

3. Color the molecule

Enter the colat command or use the Molecule/Color command to color

the molecule.

4. Label the molecule

Use the Molecule/Label command to add labels to the molecule.

5. Quit Insight II

6. Copy the log file, naming the new file myget.bcl

At the shell prompt this can be done as:
cp insight.log myget.bcl

Insight II/March 2000 295

12. Biosym Command Language

7. Edit the new file

Note that the file contains the commands you invoked in Insight II, pre-
ceded by m:, as well as some comments, preceded by pound signs (#).
The m: MUST BE DELETED. The comments can be deleted or ignored.

8. Convert to BCL

At the top of the file, add the line Define_Macro myGet. At the bottom,
add the line End_Macro followed by the line Add_To_Pulldown myGet
Molecule.

9. Invoke Insight II again.

Note that you could have done this entire process without quitting
Insight II. This can be accomplished by copying WBLOGFILE, then
deleting previous commands from the top of the log file which you did
not want.

10. Load the macro

11. Invoke your new File/myGet

Since your new command has no parameters, the command is exe-
cuted immediately. If an error occurs, try to fix it in the next step.

12. Add parameters

Change the line “Define_Macro myGet” as shown below.

Define_Macro myGet \
Lstring Filename \
Ident Objname

Note that the backslash (\) is the line continuation character.

296 Insight II/March 2000

 BCL Tutorial

13. Implement parameters

In the Get Molecule command line, replace the actual filename with
$Filename and the actual object name with $objname. The line should
appear similar to what is shown below.

Get Molecule PDB System $Filename $Objname

14. Reload and re-invoke

You should now be able to enter a filename and an object name, and
have the molecule come up and be automatically colored and labeled.

15. Iterate
Add additional parameters for colors and labels as desired.

Insight II/March 2000 297

12. Biosym Command Language

Tutorial 3: Working Example

Enter the following program. Note the comment style, indention
style, use of spacing and blank lines, and the use of parentheses,
braces, and brackets. Iteratively run, debug, and enhance the
macro as you see fit.
This macro uses features that are discussed in the Overview sec-
tion and described in detailed in the Reference section. Note that
we have provided this macro as $BIOSYM/gifts/insight/BCL/
trace_torsions.bcl.
# Trace_Torsions
# Graph torsion angles along backbone by residue number

Define_Macro Trace_Torsions \
Ident Molecule_Name \
Int Starting_Residue \
Int Ending_Residue

# local variables
Float torsion_value # torsion angle value
Lstring fn # filename
Int presidue# previous residue index
Int cresidue# current residue index
Int nresidue# next residue index
Int nnresidue# next next residue index
Ident CA_presidue, CA_cresidue, \
CA_nresidue, CA_nnresidue # residue names

# initialization
presidue = $Starting_Residue - 1
cresidue = $Starting_Residue
nresidue = $Starting_Residue + 1
nnresidue = $Starting_Residue + 2
fn = trace_torsions.tbl

# add picking
Set_Param_Pick Molecule_Name MOLECULE_NAME

# check input parameters

If ( ($Starting_Residue <= 1) || ($Ending_Residue <= 1) )

Print “Residue number must be greater than 1”

Return
End

If ( ($Starting_Residue > $Ending_Residue) || \

( ($Ending_Residue - $Starting_Residue) < 3) )

Print “Ending_Residue number should be greater than”

Print “Starting_Residue number by at least three.”
Return
End

Continued...

298 Insight II/March 2000

 BCL Overview

# remove trace_torsions file, if present

Bcl_Unix (“/bin/rm -f “ // $fn)

# write table description information to file

Write $fn “INSIGHTII V9.5.0 “
Write $fn “DATE: Tue Jan 3 00:00:00 1995\n#\n”
Write $fn “TITLE: Residue Number\n”
Write $fn “MEASUREMENT TYPE: Dimensionless\n”
Write $fn “UNITS OF MEASUREMENT: <no units>\n”
Write $fn “FUNCTION: Residue Number\n#\n”
Write $fn “TITLE: Trace_torsions\n”
Write $fn “MEASUREMENT TYPE: Angle\n”
Write $fn “UNITS OF MEASUREMENT: degrees\n”
Write $fn “FUNCTION: Trace_torsions\n#\n#\n”

# main loop for measuring torsions in protein trace

While ($nresidue < ($Ending_Residue + 3))

CA_presidue = $Molecule_Name//”:”//$presidue//”:CA”
CA_cresidue = $Molecule_Name//”:”//$cresidue//”:CA”
CA_nresidue = $Molecule_Name//”:”//$nresidue//”:CA”
CA_nnresidue = $Molecule_Name//”:”//$nnresidue//
”:CA”

$torsion_value = \
{Dihedral -monitor $CA_nnresidue $CA_nresidue \
$CA_cresidue $CA_presidue}

Write $fn “%5d %11.6f\n” $cresidue $torsion_value

Dihedral Monitor Add -180.00 180.00 green \

$CA_nnresidue $CA_nresidue $CA_cresidue $CA_pres-
idue

presidue = $cresidue
cresidue = $nresidue
nresidue = $nnresidue
nnresidue = $nnresidue + 1

End # end of while loop

# close trace_torsions.tbl file

Close $fn

# load analysis module and draw graph from file

Analysis
Get Graph $fn New_Graph “Residue Number” Trace_torsions
None

End_Macro
Add_To_Pulldown Trace_Torsions User

BCL Overview
This section starts with general rules for the BCL language. Func-
tionality is then covered by topic. If you know what you want to

Insight II/March 2000 299

12. Biosym Command Language

do, but not which statements to use, start here. If you know the
statement but are not sure of the proper syntax, see the BCL Refer-
ence section.

BCL Rules
♦ BCL is case insensitive. A parameter name’s case is maintained
in prompts and parameter blocks.
♦ Multiple spaces and tabs may divide any tokens. A token is a
keyword, such as Define_Macro, a variable, a constant, or an
operator.
♦ Blank lines may appear anywhere in the macro.
♦ If more than one statement is on a line, each statement must be
separated with a semicolon (;).
♦ If a statement continues onto multiple lines, each line to be con-
tinued is ended with a backslash (\).
♦ Comments start with a pounds (#) and may begin anywhere on
a line. Comments normally run to the end of the line, unless
ended with another #.
♦ A complete statement, including continuations and comments,
must not exceed 1024 characters.
♦ Names used for macros, parameters and variables must start
with a letter and be made up of only A-Z, a-z, 0-9, _, and be fewer
than 20 characters. Names may contain spaces, but must always
be quoted as in “File Name”. (Underscores are recommended,
as in File_Name.) Reserved words should not be used as
names.
♦ Macro names must be unique command names within Insight
II.
♦ All macros must start with Define_Macro and end with End_
Macro.
♦ Multiple macros can appear in one file.
♦ Macros can call previously loaded macros.
♦ Any Insight II command may be used in a macro, but the module
containing the command must be open. Modules can be

300 Insight II/March 2000

 BCL Overview

opened within a macro just by adding the name of the module

on a line by itself.

Insight II/March 2000 301

12. Biosym Command Language

Parameters
Parameters are arguments to your macro. If your macro is invoked
from the command line, the user may type the values for the
parameter on the line. If you do not supply arguments, Insight II
automatically prompts you with the parameter name. If your
macro is invoked from a menu, the parameters appear as widgets
in a parameter block window, just like any other Insight II com-
mand, including Execute and Cancel buttons.
Parameters can have defaults, value-aids, and picking functions.
BCL statements are also available to format the parameter block
generated when the macro is invoked from the menu. These are
covered later in this section.
It is possible to share any Insight II command parameter with a
macro. Thus, Insight II parameter defaults can be inherited by the
macro command parameter. See Table 7. Insight II Parameter
Names on page 10-337 for a list of parameters which are already
used in Insight II.
Since parameters are shared with Insight II, you must be careful in
choosing parameter names so that they do not unintentionally
coincide with existing parameters.

Types
A parameter’s type determines what kind of data it can hold and
how large it can be. Data validation is built-in, so that if you or
another user of your macro enters letters in an Int parameter, the
bell rings, a warning message appears and the parameter is
cleared. Several additional (Short_) data types are available. These
are covered later in this section.
♦ Intinteger, 19 digits max, including sign
♦ Float real, 19 digits maximum, including sign
♦ Sstring short string, 19 chars max
♦ Lstring long string, 79 chars max
♦ Vlstring very long string, 511 chars max
♦ Logicalboolean ON / OFF

302 Insight II/March 2000

 BCL Overview

♦ Enumer read-only list of Sstrings, appears as radio box

♦ Llistread-write list of Lstrings, appears as scrolling list
♦ Identidentifier, 79 chars max
♦ Coordthree floats together

Insight II/March 2000 303

12. Biosym Command Language

Definition
All parameters must be defined in the Define_Macro statement.
Enumers and Llists are filled within the body of the macro with the
Def_Enum and Def_List statements. The example BCL code cre-
ates the parameter block shown.
Define_Macro All_Parameters \
Int Int_param \
Float Float_param \
Sstring Sstring_param \
Lstring Lstring_param \
Vlstring Vlstring_param \
Logical Logical_param \
Enumer Enumer_param \
Llist Llist_param \
Ident Ident_param \
Coord Coord_param

Def_Enum Enumer_param enum1

Def_Enum Enumer_param enum2
Def_Enum Enumer_param enum3

Def_List Llist_param list1

Def_List Llist_param list2
Def_List Llist_param list3
Def_List Llist_param list4
Size_list Llist_param 3

304 Insight II/March 2000

 BCL Overview

Variables
Variables temporarily hold data within a macro. Variables should
be defined before they are used, otherwise the variable implicitly
defined the first time it is used. We recommend defining all vari-
ables at the top of the macro, immediately following the Define_
Macro statement and its parameter definitions. Macro commands
do not share variables with other macros or commands.

Types
♦ Int integer, 19 digits max, including sign
♦ Float real, 19 digits maximum, including sign
♦ Sstring short string, 19 chars max
♦ Lstring long string, 79 chars max
♦ Vlstring very long string, 511 chars max
♦ Logical boolean ON / OFF
♦ Ident identifier, 79 chars max
♦ Coord three floats together

Definition
To define a variable, start a statement with a variable type, fol-
lowed by a comma-separated list of variable names. For example:
Int i, j
Lstring Filename

Arrays Arrays of variables may be defined as follows:

Sstring AtomList[50]

Pointers Pointers to variables may be defined. For example:

Sstring *AtomList

These are used with the fetch functions and accessed like arrays.

Insight II/March 2000 305

12. Biosym Command Language

Accessing Parameters and Variables

The contents of parameters and variables are accessed with a dol-
lar sign. For example the following statement prints out the con-
tents of the FileName parameter:
print $FileName

And the variable i could be printed as

print $i

Coords
You can access coords by x, y, and z values or as a unit.
Coord point

point = 3.0, 2.0, 5.0

Print $point # print x, y, and z
Print $point.x # print only x

Arrays and Pointers

Arrays and pointers are accessed by specifying an index into the
array. To print the contents of the first cell of the AtomList array:
print $AtomList[1]

Note that array indexing starts at 1.

Constants
Constants are numbers or strings to be used literally as values. The
number -12 is a constant, as is the string “Hello World”.
String constants should be enclosed in double quotes.
Constants may be used in expressions and statements as needed.
Constants may also be given symbolic names. See the Constant
command in the BCL Reference.

306 Insight II/March 2000

 BCL Overview

Operators
BCL has three types of operators: numerical, string, and logical.
See Table 4. Operator Precedence on page 10-332 for a complete list
and description of operators and their precedence. See Table 5.
Intrinsic Functions on page 10-334 for a complete list of built-in
functions, such as sin() and random().

Expressions
Expressions are collections of parameters, variables, constants,
functions, and operators. Expressions can be used in assignment
statements and within commands statements. Some examples of
expressions include:
$x + 7 (simple arithmetic expres-
sion)

$filename // “.pdb” (string concatenate expres-

sion)

cos ($x) <= cos ($y) (logical expression)

In Assignment Statements
An assignment statement begins with a variable name, followed
by the equal sign (=), then an expression. Some examples of
assignment statements include:
first_case = $MoleculeName // “:*”

i = $i + 1

Note that in BCL, variable names are preceded by a $ except on the

left hand side of an expression.

In Command Statements
Whenever an expression is embedded in a command, it must be
surrounded by parentheses. For example:
get mol pdb ($MoleculeName//”.brk”) $ObjName

Insight II/March 2000 307

12. Biosym Command Language

Functions
You can make your own BCL macros that act as functions, which
in turn can return values to other macros. The function macros can
appear in the same file or separate files, but the function macros
must be loaded before they are referenced.

Defining Functions
A function macro has an additional first argument in the Define_
Macro statement which specifies what type of value is returned.
Functions also have Return statements which actually return a
value. Otherwise functions look like any other macro. The exam-
ple shown below returns a coordinate when called.
Define_Macro Coord Cen_of_Mol Sstring Mol_name
Coord cur_com
...
Return $cur_com
End_Macro

Possible return types include Int, Float, Coord, Sstring, Lstring,

Vlstring, and Ident.

Accessing Functions
To access a function written in BCL, enclose the function name and
its arguments in curly braces. For example:
mol_cent = {Cen_of_Mol $MoleculeSpec}

Note: some Insight II commands return values and can be used in

the same manner.
dist_2 = {Distance abp:132:ca abp:132:c} * 2
angle_value = {Angle abp:132:ca abp:132:c abp:132:o}
center = {XYZ}

See Table 6. Insight II Commands that Return a Value on page 10-

336 for a complete list of Insight II commands that return values.

Forward Referencing
As mentioned above, functions need to be loaded before they are
referenced. One way to do this to put BCL functions in the file
above the macro which refers to them. Another solution is to use

308 Insight II/March 2000

 BCL Overview

the Command statement. The Command statement informs BCL

that the function is defined elsewhere. For example:
Define_Macro Anim Sstring MoleculeSpec

# forward reference
Command Coord Cen_of_Mol

Coord mol_cent
. . .
mol_cent = {Cen_of_Mol $MoleculeSpec}
. . .
End_Macro

Control Statements
A control statement is used to regulate the execution of statements
within a macro. The two primary types of control statements are
conditionals, such as If, and loops, such as While.

Conditionals
BCL provides two methods of conditional execution, the If state-
ment and the Switch statement.

If The BCL If statement is followed by a logical expression

enclosed in parentheses. If the expression is logically true, the
statements up to its associated End statement are executed.
Optionally, an If statement may have an Else statement which also
has an associated End. An abbreviated form, ElseIf is also pro-
vided. If statements may be nested.
Define_Macro Greeting Sstring str Int a Int b
If ($str = “Hello”)
Print “Hi there”
ElseIf ($str = “Bye”)
If ($a > 0 && $b > 0)
Print “Goodbye”
End
Else
Print “Not Goodbye”
End
End
End_Macro

Switch Another way to conditionally execute statements is the

Switch statement. A variable is compared with a number of cases

Insight II/March 2000 309

12. Biosym Command Language

and the code within the matching case is executed. If no case

matches and a Default case is provided, that block is executed.
Each Case must end with a Breaksw statement. The Switch has an
associated End.
Define_Macro Greeting Sstring str
Switch $str
Case “Hello”:
Print “Hi there”
Breaksw
Case “Bye”:
Print “Goodbye”
Breaksw
Default:
Print “You don’t say...”
Breaksw
End
End_Macro

Loops
The other type of control statement, the loop, causes the same
statements to be executed repeatedly, stopping when a logical test
fails. Loops can be created with the While, ForEach, and GoTo
statements. The Continue statement jumps control to the top of a
While or ForEach loop. The Break statement prematurely termi-
nates a While or ForEach loop. Loops may be nested.
Note: If you run your macro and it loops infinitely, it can be
stopped by pressing the <Esc> key.

While The While statement is a loop with a logical test in paren-

theses. The While statement has a matching End. The following
example also shows the use of the Break statement.
While ($n > 0)
n = $n -1;
If ($n = 7)
Break;
End
End

ForEach The ForEach loop has two forms: the first iterates
through the values of the array; the second increments a counter.
Both forms have a matching End statement. Examples of both
forms are shown below. The BCL fetch statements used in the
examples are discussed in System_Fetch_Assy on page 10-359.
Lstring mol_name, atom, *atom_list
Int count, index

310 Insight II/March 2000

 BCL Overview

atom_list = {system_fetch_atom $mol_name}

ForEach $atom In $atom_list
Print $atom
End
______________________________________________________

atom_list = {system_fetch_atom $mol_name}

count = sizeof ($atom_list)

Foreach $index From 1 To $count

Print $atom_list[$index]
End

Insight II/March 2000 311

12. Biosym Command Language

File I/O and Operating System Access

BCL provides statements to read from, and write to, text files. The
BCL_Unix statement can also be used to access the file system or
perform any operating system command.

Reading from a File

Two BCL statements are available for reading text files. The Fgets
statement reads one line at a time. The Read statement reads
space-separated tokens.

By Line Fgets reads a string of characters from a text file and

assigns the string to a variable. The maximum number of charac-
ters is specified as the second argument to Fgets. Fgets returns zero
on failure or end-of-file. Fgets attempts to open the file if it is not
already open. Here is a BCL example of the UNIX cat command.
Define_Macro Cat Lstring Catfile
Lstring buff
# open file and get first line
If({Fgets $Catfile 79 $buff})
Printf “%s” $buff
# get remaining lines
While ({Fgets $Catfile 79 $buff})
Printf “%s” $buff
End
Close $Catfile
End
Else
Print “Can’t open “ $Catfile
End
End_Macro

312 Insight II/March 2000

 BCL Overview

By Token The Read statement reads data from a text file and
assigns the data to BCL variables for further processing. Text can
be read as strings, integers, or floats. Read returns zero on failure
or end of file. The read statement attempts to open the file if it is
not already open. The Close statement should be used after all
reading is complete.
The following example uses the BCL_Unix command to print the
owner and modification time fields of the Insight log file.

Define_Macro Last_Run

Sstring access, owner, group, month

Int links, size, day, status

BCL_Unix “ls -l insight.log > /tmp/last_run”

status = {Read “/tmp/last_run” “%s %d %s %s %d %s
%d” \
$access $links $owner $group $size $month
$day }
Close /tmp/last_run
BCL_Unix “rm /tmp/last_run”

If ($status)
Print “Insight last run here on “ \
$month $day “ by “ $owner
End
Else
Print “Unable to determine when Insight last
run”
End
End_Macro

Writing To a File
The BCL Write statement outputs a formatted line of text. The syn-
tax of the Write statement is identical to the Read statement. Write
also returns zero on failure. The Close statement should be used
after all writing is complete.
The Trace_Torsions.bcl tutorial on page 10-298 shows how this
statement can be used to create a text file for use by an Insight com-
mand.
Conversion formats, such as %s, can be found in the BCL Refer-
ence section under the Read and Write statements.

Insight II/March 2000 313

12. Biosym Command Language

Parameter Blocks
Several BCL statements are available to enhance the use of your
new command. Some are for appearance only. Other statements
make it easier to fill in the parameter block by supplying defaults,
by providing value-aids, or by picking.

Defaults
Users of your macro appreciate smart default values in your
parameters. You can either set the value to some pre-determined
constant, or calculate the default with another BCL function.

Setting Defaults Each parameter type has an associated Set_

command to set the default value of a parameter of that type. See
the BCL Reference section for a complete list. The following exam-
ple sets default values for various data types.
Define_Macro Minimize_New \
Logical Restart_Minimize \
Int Cycles \
Float Gradient_Converge

# Set default values

Set_Boolean Restart_Minimize off
Set_Integer Cycles 20
Set_Real Gradient_Converge 0.001

This is the corresponding parameter block, as it initially appears:

314 Insight II/March 2000

 BCL Overview

Calculating Defaults A callback function can be created to cal-

culate default values for parameters. Two types of callbacks are
available: Preview_Command and Preview_Function. The first,
Preview_Command, is called before the parameter block appears
(it is not called for command line invocation). The second,
Preview_Function, is associated with a particular parameter and is
called whenever the value of that parameter changes, either by a
pick, focus change, or explicit <Enter>. Note that only the last call-
back registered is called.
Callbacks have no arguments and must be defined before they are
referenced. Callbacks can access the parameters of the calling
macro via the Setv_ and Get_ statements. Setv_ statements set the
current value of the parameter from a callback. Get_ statements
access the contents of a parameter from a callback, and return a
value indicating whether the contents is the current value or a
default value. Several other special statements are available for use
only in callbacks: Remove_Enum, Test_Boolean, Test_Enum, Setv_
Precision, Setv_Focus, and Setv_Trigger.
If a callback changes the state of the system (for example, it creates
a temporary file), and you cancel the command, that file is left
behind. For this reason, a third callback type called a Cleanup_
Command is available.
The following example uses a Preview_Function to calculate a
default.
### Preview function for Range macro
# sets High when Low entered

Define_Macro Update_Range
Int val, status

status = {Get_Integer Low val}

If ($status > 0) # Low not empty
Setv_Integer High ($val + 100)
End

End_Macro

### Range Command

Define_Macro Range Int Low Int High

Preview_function Low Update_Range

End_Macro
Add_To_Pulldown Range File

Insight II/March 2000 315

12. Biosym Command Language

Data Validation
Preview_Function callbacks may also be used to do data valida-
tion in parameter blocks. In this example, a callback validates that
a Float parameter is positive.
Define_Macro Validate_Size
Int status
Float f

status = {Get_Real Size f}

If ($status > 0 && $f < 0.0)

Print “Size must be positive”
Setv_Real Size 0.0
Setv_Focus Size 0
End

End_Macro

Define_Macro Set_Size Float Size Int Increment

Preview_Function Size Validate_Size
End_macro

Picking
Picking means placing the mouse cursor over a graphical object
and clicking the left mouse button. String and ident parameters
can be filled by picking. The statement Set_Param_Pick enables
picking, and adds a pre-defined value-aid for modifying the pick
level and selecting by name. Set_Param_Pick has arguments to
specify what level to pick to, such as atom, molecule, or assembly.
You may also specify a Screen_Only option to limit Object picks to
only Grids, Graphs, or other object types. Here are two examples
of the Set_Param_Pick statement, and the associated value-aid:
Define_Macro Check_Mol Ident Mol Sstring Obj
# Molecule picking
Set_Param_Pick Mol Molecule_Spec

316 Insight II/March 2000

 BCL Overview

# Graph picking
Set_Param_Pick Obj Object_Name Screen_Only Graph

Appearance
You can customize the appearance of a parameter block by using
Short_ parameters and by using several BCL statements to affect
layout.
Several of the parameter types have Short_ forms. These include:
Int, Float, and String. If the Short_ form of the data type is used, the
Label and Value widgets appear next to each other and are limited
to nine characters each. For example:
Define_Macro Morph \
Short_Int Steps \
Short_String From \
Short_String To

BCL also provides the following statements for enhancing the

appearance of a parameter block:
♦ Param_Comment Adds a line of text above a parameter.
♦ Param_New_Column Places a parameter at the top of a new
column of widgets.
♦ Param_PackAdds a double line below a parameter.
♦ Param_Set_StyleSets scrolling behavior and popup style enu-
merators.
♦ Size_List Sets the number of rows visible in a list
In the following example, the appearance of parameters has been
customized.

Insight II/March 2000 317

12. Biosym Command Language

Define_Macro Style_Demo Int NormalInt Short_Int ShortInt \

Enumer PopupEnum Vlstring HScrollVlstring

Param_Comment NormalInt “A Comment” Center

Param_New_Column PopupEnum
Param_Pack NormalInt
Param_Set_Style PopupEnum PARAM_POPUP
Param_Set_Style HScrollVlstring PARAM_HSCROLL
Def_Enum PopupEnum Value1

Value-Aids
Value-aids provide quick ways for the user to fill in a parameter.
The value-aid becomes visible when the parameter associated
with it gets keyboard focus. Value-aids include sliders for selecting
a float value in a range, palettes for selecting color, and lists for
selecting a value. The Place_Valuator, Set_Slider, and Param_
Add_File_List statements are used to add built-in value-aids. In
the following example, all three types of value-aids are used.
Define_Macro Value_Aids \
Sstring Shade \
Float Temperature \
Vlstring FileName

Place_Valuator Shade Palette Default

Set_Slider Ruler 0.0 500.0

Place_Valuator Temperature Ruler align

Param_Add_File_List FileName “bcl,log”

End_Macro

318 Insight II/March 2000

 BCL Overview

Palette Ruler

File List

Insight II/March 2000 319

12. Biosym Command Language

Conditional Parameters
You may wish to de-activate parameters based on the value of
other parameters. For example, if you turn off the Boolean param-
eter Set_Color, the New_Color parameter should be removed from
the parameter block. In this case the New_Color parameter is con-
ditional on the Set_Color parameter. Parameters can be condi-
tional on Boolean and Enumer parameters.
The Condition statement makes a parameter conditional on
another parameter, called the control parameter. The syntax allows
for multiple conditions logically ANDed and ORed together, as
well as NOT logic. The condition statement to have the New_
Color parameter active only when the boolean Set_Color parame-
ter is True is:
Condition New_Color Set_Color on off off

The condition statement has five arguments. The first is the condi-
tional parameter and the second is the control parameter. The third
argument is the value of the control parameter.
The fourth argument in the Condition statement is for use when
you have multiple condition statements for one parameter. In this
example on means logically and this condition with the previous
condition, whereas off means or. The condition statements to have
the Radians parameter active only when the boolean Adjust
parameter is True and the enumer Dimension parameter is Angu-
lar is:
Condition Radians Adjust on off off
Condition Radians Dimension Angular on off

The fifth argument to the Condition statement is the polarity. If it

is on, then the conditional parameter is active if the control param-
eter does NOT match the value. Therefore, if we also had a
Microns parameter, its Condition statements would be:
Condition Microns Adjust on off off
Condition Microns Dimension Angular on on

This means Microns is on when Adjust is True and Dimension is

NOT angular.

320 Insight II/March 2000

 BCL Overview

Accessing Insight II Data

Insight II molecular systems data can be accessed in BCL using
Fetch_, Props_, and Cell_ statements. Object identifiers are
obtained with Fetch statements. Properties of objects are accessed
with Prop_ statements. Spreadsheet cells are accessed with Cell_
statements.

Objects
Fetch functions return arrays of object identifiers that match the
specification argument. The returned object identifiers can then be
used to refer to an Insight II object in BCL statements. The func-
tions are: System_Fetch_Atom, _Mono, _Mol, _Object, _Sketch, _
Assy, and Assy_Fetch_Molecule. The functions return NULL if no
objects were found which match the specification argument.
The following example shows atom fetching.
Define_Macro List_Atoms
Ident *atom_list, atom
Int count

atom_list = { System_Fetch_Atom “CRN:29:*” }

count = sizeof($atom_list)
ForEach $atom In $atom_list
Print $atom
End
Print $count “atom(s) found”
End_Macro

The output of the previous example is shown below.

(Executing: List_Atoms User)
CRN:29:N
CRN:29:CA
CRN:29:C
CRN:29:O
CRN:29:CB
CRN:29:CG
CRN:29:CD1
CRN:29:CD2
CRN:29:CE1
CRN:29:CE2
CRN:29:CZ
CRN:29:OH
12 atom(s) found

Insight II/March 2000 321

12. Biosym Command Language

Properties
BCL macros can access properties from molecular system such as
element type, charge, or number of bonds. Properties come in two
forms, Function properties, and Attribute properties. Function
properties are calculated each time the property is requested.
Attribute properties are data stored with individual objects.
Each property is associated with a class of object, such as Atom or
Mol, and datatype, such as Int of Str. See the Custom/List_Proper-
ties command for a complete list of properties, their classes, and
their datatypes.
Once a property is defined, it can be used in Insight II commands
such as Molecule/Label and Subset/Define. Properties are also
accessible in Spreadsheet formulas.
This section describes properties in four parts: accessing the sys-
tem properties supplied with Insight II, user defined attribute
properties, user defined functional properties, and accessing
arrays of properties to increase performance.

System Properties The BCL function Prop_Get_ returns a prop-

erty value from an object. The syntax of the statement is:
val = Prop_Get_<datatype> <PropName> <Class> <Object spec>

where datatype is Int, Float, Str, or Bool, and class is Atom, Mono,
or Mol. If the property is not set, Prop_Get returns a null value of
the appropriate datatype.
The following example shows how to get several pre-defined
properties with different datatypes from different classes of
objects, and the output from the macro.
Define_Macro Print_Sys_Props
Int bonds, count
Lstring element
Ident atom

# get single properties

count = { Prop_Get_Int Monomer_Count Mol “CRN” }
Printf “Molecule CRN contains %d monomer(s)\n” $count

atom = “CRN:29:OH”
element = { Prop_Get_Str Element Atom $atom}
bonds = { Prop_Get_Int Connection_Count Atom $atom}
Printf “Atom CRN:29:OH is %s with %d bond(s)\n” \
$element $bonds
End_Macro

322 Insight II/March 2000

 BCL Overview

(Executing: Print_Sys_Props User)

Molecule CRN contains 46 monomer(s)
Atom CRN:29:OH is O with 1 bond(s)

Insight II/March 2000 323

12. Biosym Command Language

User-Defined Attribute Properties Attribute properties are val-

ues you can store to, and retrieve from, objects. These values are
saved with the object when you save your folder. Retrieving user-
defined attribute properties is identical to retrieving pre-defined
properties, using Prop_Get. Creating user-defined attribute prop-
erties is a two step process: first, the property must be registered;
second, the property must be set on the object.
Registering user-defined attribute properties is done with the
Prop_Register statement. Registration declares the name of the
property, the class it applies to, and the datatype it holds. This
operation only needs to be done once per session, and occurs auto-
matically when you restore a psv file which has an unregistered
property. The Prop_Register statement returns TRUE if either the
property was registered successfully, or if it already is registered in
the same way. It returns FALSE if the property is registered differ-
ently or if registration failed. The syntax to register a property is:
success = { Prop_Register Attr <PropName> <Class>
<DataType> }

Setting the user-defined attribute property on an object is done

with the Prop_Set statement. The syntax is identical to Prop_Get
except its value is passed in, instead of being returned. If the prop-
erty did not exist on the object, space is allocated the first time the
attribute property is set. If necessary, you can check whether a
property was set on a particular object with the Prop_Exists state-
ment. Properties can also be removed from the system with Prop_
Remove.
The following example registers, sets, and gets a user-defined
attribute property. The output is shown below.
Define_Macro Use_Attr_Prop Ident Atom
Lstring strvar
Set_Param_Pick Atom Atom_Spec

If(!{Prop_Register Attr My_String Atom Str})

Printf “Unable to register My_String Property\n”
End

Prop_Set_Str My_String Atom $Atom “Hello world”

If({Prop_Exists My_String Atom $Atom})

strvar = {Prop_Get_Str My_String Atom $Atom}
Printf “Property set to %s\n” $strvar
End

End_Macro

324 Insight II/March 2000

 BCL Overview

(Executing: Use_Attr_Prop CRN:29:OH)

Property set to Hello world

Insight II/March 2000 325

12. Biosym Command Language

User-Defined Function Properties Function properties are cal-

culated each time the property is requested. Like Attribute prop-
erties, function properties must be registered with the Prop_
Register statement. Unlike attribute properties, function proper-
ties have no set function or space allocation, and are not saved in
folders.
When you register a function property, you must specify the name
of a macro that will be called each time the property is requested
with Prop_Get. That macro is called with one parameter; the object
specified in the Prop_Get request. The macro must return a value
of the type specified when the property was registered.
The Prop_Register statement for function properties has a first
argument of Func instead of Attr and a new final argument: the
name of the function to call.
success = { Prop_Register Func <PropName> <Class> \
<DataType> <Macro_Func> }

The following example registers a new property macro (if it is not

already registered) and defines the macro that is called. The new
property, called Owner_Mon, returns a string containing the
monomer for an atom.
Prop_Register Func Owner_Mon Atom Str Owner_Mon_Prop

Define_Macro Lstring Owner_Mon_Prop Ident Atom

monlist = { System_Fetch_Mon $Atom }
return $monlist[1]
End_Macro

The following example uses the new Owner_Mon property

declared and defined above. Output is shown below.
Define_Macro Print_User_Prop Ident Atom
Ident mon
Set_Param_Pick Atom Atom_Spec

# call new property macro

mon = {Prop_Get_Str Owner_Mon Atom $Atom}
Printf “Monomer for atom %s is %s\n” $atom $mon

End_Macro

(Executing: Print_User_Prop CRN:29:OH)

Monomer for atom CRN:29:OH is CRN:29

326 Insight II/March 2000

 BCL Overview

Property Arrays To improve performance, you can get an array

of property values with one statement. The Prop_Get_Arr state-
ment returns an array of atom properties from all the atoms in a
molecule or monomer. The syntax is the same as Prop_Get, with
the addition of two new classes, Mol_Atom and Monomer_Atom.
The following example gets the pre-defined mass property of each
of the atoms in a molecule, and prints the sum. The output is
shown below.
Define_Macro Atom_Mass
Float m, sum, *mass
# get an array of properties
mass = { Prop_Get_Arr_Float Mass Mol_Atom “CRN” }
sum = 0.0
ForEach $m In $mass
sum = $sum + $m
End
Printf “Mass of atoms in CRN: %.2f\n” $sum
End_Macro

(Executing: Atom_Mass)
Mass of atoms in CRN: 4412.97

Spreadsheet Cells
Spreadsheet cells can be accessed with Cell_Get_String, _Int, or _
Float. The statement takes one argument of the form Table:row.col,
as shown in the example below.
Define_Macro Print_Cell \
Ident Table Int Row Int Col

Ident Cell
Lstring contents

Cell = $Table // “:” // $row // “.” // $col

contents = {Cell_Get_String $Cell}
Printf “\n\tTable %s Cell %d %d -- %s\n” \
$Table $row $col $contents
End_Macro

Insight II/March 2000 327

12. Biosym Command Language

Debugging
If errors occur when you load or run your macro, here are a few
debugging suggestions:
♦ The most common programming bugs are typos. Name mis-
matches or incorrect spelling of command names are also com-
mon.
♦ If you receive an error message that contains line numbers, look
at the line in your macro where the first error occurred. Subse-
quent errors frequently vanish when the first is fixed.
♦ If the error message says “Missing End_Macro” and your
macro does have an End_Macro statement, check for missing
End statements for If, Else, Switch, Foreach, and While state-
ments.
♦ If a loop is not executing the proper number of times, check
your initial values, termination values, and increment values.
♦ You may find it helpful to add temporary Print statements to
dump the values of parameters and variables or to see how far
execution proceeded before the error occurred.
♦ Another debugging technique is “Divide and Conquer”. Com-
ment out parts of the macro and see if the error still occurs.

328 Insight II/March 2000

 BCL Reference

BCL Reference

Reserved Symbols
The following words have special meaning in the BCL language
and should not be used as names:

Table 3. Reserved Symbols

After BCL_UNIX Before
Break BreakSw Case
Cleanup_Command Close Condition
Constant Continue Coord
Default Define_Macro Def_Enum
Def_Enum_Sorted Def_Enum_Unique Def_List
Def_List_Sorted Def_List_Unique Else
ElseIf End End_Macro
Enumer Fgets Float
ForEach From FullScreen
Get_Boolean Get_Coord Get_Enum
Get_Ident Get_Integer Get_List
Get_Lstring Get_Real Get_Sstring
Get_Vlstring GoTo Ident
If In Int
Logical Lstring Param_Add_File_List
Param_Comment Param_New_Column Param_Pack
Param_Set_Style Place_Valuator Preview_Command
Preview_Function Print Printf
Read Remove_Enum Return
Screen_Update Setv_Boolean Setv_Coord
Setv_Enum Setv_Focus Setv_Ident
Setv_Integer Setv_List Setv_Lstring
Setv_Precision Setv_Real Setv_Sstring
Setv_Trigger Setv_Vlstring Set_Boolean
Set_Coord Set_Enum Set_Ident
Set_Integer Set_List Set_Lstring
Set_Param_pick Set_Real Set_Sideblock

Insight II/March 2000 329

12. Biosym Command Language

Table 3. Reserved Symbols

Set_Slider Set_Sstring Set_Vlstring
Short_Ident Short_Integer Short_Real
Short_String Size_List Sstring
Step Switch Test_Boolean
Test_Enum TextPort To
Trigger Vlstring Void
While Write

330 Insight II/March 2000

 BCL Reference

Operator Precedence
In an expression, certain operations have precedence over others.
Operations of equal precedence are evaluated left to right. The
operations and their precedence are:

Insight II/March 2000 331

12. Biosym Command Language

Table 4. Operator Precedence

Operand
Order Symbol Value Type Comments
Type

1 % Integer Integer Modulo

1 -(unary) Integer or Integer or Negate

Float Float

2 // String or other String Concatenation,

one or both oper-
ands must be
string

3 *, / Integer or
Float
Integer or
Float
Multiply, Divide

4 +, - Integer or Integer or Addition, Subtrac-

Float Float tion

5 =, !=, .eq., Integer, Float, Logical Equal, Not equal

.ne. String, Coord

5 <, >, .lt., Integer, Float Logical Less than,

.gt. Greater than

5 <=, >=, Integer, Float Logical Less or equal,

.le., .ge. Greater or equal

6 ! (unary) Logical Logical Not

7 &&, Logical Logical And

.and.

8 ||, .or. Logical Logical Or

Precedence can be overridden with the use of parentheses. For

example:
3+7*4
evaluates to 31, but:
(3 + 7) * 4
yields 40.

332 Insight II/March 2000

 BCL Reference

Intrinsic Functions
Intrinsic functions are built-in functions provided by BCL. These
include common arithmetic and trigonometric functions. They can
be used as part of an expression in an assignment statement or as
a parameter value in a command statement.

Insight II/March 2000 333

12. Biosym Command Language

Table 5. Intrinsic Functions

Function Input Type Output Type Remark

acos(x)* Float Float

acosh(x)* Float Float

cos(x)* Float Float

cosh(x)* Float Float

asin(x)* Float Float

asinh(x)* Float Float

sin(x)* Float Float

sinh(x)* Float Float

atan(x)* Float Float

atanh(x)* Float Float

tan(x)* Float Float

tanh(x)* Float Float

exp(x) Float Float

log(x) Float Float Natural log, x > 0

log10(x) Float Float Log base 10, x >0

cbrt(x) Float/Integer Float

sqrt(x) Float/Integer Float x >= 0.0

float(x) Float/Integer Float

abs(x) Float/Integer Float/Integer

int(x) Float/Integer Integer

sizeof(x) Variable Name Integer

rand() Void Integer value: 0 ~ (2**15)-

1

random() Void Integer value: 0 ~ (2**31)-

1

* both the input value and the return value from this function are
in radians.

334 Insight II/March 2000

 BCL Reference

Insight II Commands that Return a Value

The following Insight II commands return a value which can be
used in a BCL expression. Refer to on-line help for further infor-
mation on command syntax.

Insight II/March 2000 335

12. Biosym Command Language
Table 6. Insight II Commands that Return a Value

Command Pulldown/Module Type Return Values

Distance Measure/Viewer Float Distance between two atoms

Angle Measure/Viewer Float Planar angle

Dihedral Measure/Viewer Float Dihedral angle

XYZ Measure/Viewer Coord Atom coordinate

Energy Measure/Viewer Float Energy of a single molecule

Soak Assembly/Viewer Int Number of molecules added

Superimpose Transform/Viewer Float rms float

Get Molecule/Viewer Int 1 if successful, 0 otherwise

Put Molecule/Viewer Int 1 if successful, 0 otherwise

Get Trajectory/Analysis Int Number of trajectory files

loaded

Animate Trajectory/Analysis Int Number of frames displayed

Construct_Graph Trajectory/Analysis Int Next graph index

Intermolecular Evaluate/Docking Float Energy between two molecules

Compute Docking_Grid/Docking Float Grid energy

3D_Convert Sketch/Builder Int 1 if successful, 0 otherwise

Insight II Parameter Names

336 Insight II/March 2000

 BCL Reference

Table 7. Insight II Parameter Names

Activation .............................................Enumer Min Value .................................................Float
Alternate_Space ................................... Logical Molecule Name ............................. Short_Ident
Assem/Mol Level .................................Enumer Molecule Pick Level............................. Enumer
Assembly Name ............................Short_Ident Molecule Spec..........................................Ident
Assembly/Mol Level.............................Enumer Monitor ................................................. Logical
Assembly/Mol Name......................Short_Ident Morse ................................................... Logical
Assembly/Molecule ................................. Ident Multiplier ...................................................Float
Atom ........................................................ Ident New Molecule Name ............................ Sstring
Atom 1 ..................................................... Ident New Name..................................... Short_Ident
Atom 2 ..................................................... Ident New_Graph .......................................... Logical
Atom 3 ..................................................... Ident Num of Levels ...................................... Integer
Atom 4 ..................................................... Ident Object ............................................ Short_Ident
Cell_Assemblies ........................................ Llist Object 2 ......................................... Short_Ident
Centroid Criterion ................................. Sstring Object Name ................................. Short_Ident
Charges ................................................ Logical Object_Spec.............................................Ident
Color ..................................................... Sstring Objects ...................................................... Llist
Color Spec............................................ Sstring Out_of_plane........................................ Logical
Comment ...............................................Lstring Output_File........................................... Logical
Constant .................................................. Float Output_Option ...................................... Logical
Contour Level .......................................... Float Phi Angle ..................................................Float
Contour Name ...............................Short_Ident Pick Level ............................................ Enumer
Contour Name Root.............................. Sstring Plot Spec ..................................................Ident
Coord.................................................... Integer Plus_and_Minus................................... Logical
Cross .................................................... Logical Point Pick Level................................... Enumer
Derivative................................................. Float Position Option .................................... Enumer
Descriptor List............................................ Llist Progression ......................................... Enumer
Detail Level..........................................Enumer Psi Angle ..................................................Float
Dihedral Angle ......................................... Float Repeat_Unit Name........................ Short_Ident
Display Style........................................Enumer Replace ................................................ Logical
Element Type ............................................ Llist Scroll ................................................... Enumer
End ....................................................Short_Int Set_Dihedral......................................... Logical
End Value ................................................ Float Spectrum Name ............................ Short_Ident
End_Definition ...................................... Logical Start................................................... Short_Int
File Name ..............................................Lstring Start Residue................................. Short_Ident
Files ........................................................... Llist Start Value................................................Float
Flip_Normals ........................................ Logical Step ................................................... Short_Int
Frame Spec ...........................................Lstring Stop Residue................................. Short_Ident
Frame_of_Reference...........................Enumer Subset List................................................. Llist
Function List .............................................. Llist Subset Name........................................ Sstring
Function Name ..............................Short_Ident Table Name................................... Short_Ident
Get Molecule .................................Short_Ident Tables........................................................ Llist
Graph Axis...........................................Enumer Tag ....................................................... Sstring
Graph Name ..................................Short_Ident Tail Atom ..................................................Ident
Graph Spec ............................................. Ident Temperature.............................................Float
Grid Name .....................................Short_Ident Termination ......................................... Enumer
Head Atom............................................... Ident Type Of Fragment .............................. Enumer
Interval Size............................................. Float Type Of Repeat_Unit........................... Enumer
Label........................................................ Float Units ..................................................... Integer
Label Coordinates ................................ Integer Use_Spectrum...................................... Logical
Label Operation ...................................Enumer User Name .................................... Short_Ident
Last .............................................. Short_string Window_List .............................................. Llist
List_File Name...................................... Sstring Window_Name .................................... Sstring
Lone_Pairs ........................................... Logical Write_TBL_File..................................... Logical
Map....................................................... Logical X_Function ............................................Lstring
Map Name .....................................Short_Ident Y_Function ............................................Lstring
Map Spec ................................................ Ident Z_Function ...........................................Lstring

Insight II/March 2000 337

12. Biosym Command Language

BCL Statements

Assy_Fetch_Molecule
Returns an array of molecules satisfying the assembly specifica-
tion argument. See System_Fetch_Assy.
Syntax: Assy_Fetch_Molecule object_spec
Input: object_spec (Ident): object specification for assemblies.
Returns: Array of molecules or NULL.

BCL_UNIX
Execute a UNIX shell command from within a macro.
Syntax: BCL_UNIX unix_command
Input: unix_command (Vlstring):UNIX command string
Example:BCL_UNIX “ls -l *.dat”

Break
Exit a loop. Control jumps to the statement following the end of
the loop. Typically placed within conditional code.
Syntax: Break

Cell_Get_Real, Cell_Get_Int, Cell_Get_String

Retrieve the contents of a spreadsheet table cell. Different state-
ments return different data types.
Syntax: Cell_Get_<datatype> table_cell_spec
Input: datatype (Enumer):Float, Int or String
table_cell_spec (Ident): specification of table cell of
the form Table:row.col
Returns: cell contents of specified type
Errors: mismatch type, table not found

338 Insight II/March 2000

 BCL Reference

Cleanup_Command
Associate a cleanup callback with a macro. The callback is exe-
cuted when the user cancels either explicitly with the Cancel but-
ton or implicitly by selecting another command.
Syntax: Cleanup_Command clean_macro
Input: clean_macro (Sstring): cleanup macro name
Error: macro not found

Close
Close an open file. After reading from or writing to a file, the file
should be closed with the Close statement. Failure to close files
may cause future read or write requests to fail.
Syntax: Close file_name
Input: file_name (Vlstring):data file opened for either read or write
Error: Specified data file not opened or not found.
Example:close /tmp/list.dat

Command
Declare a macro before it has been defined, to satisfy forward ref-
erences.
Syntax: Command declarator_type [*]macro_name[, macro_name]
Input: declarator_type(Sstring): parameter type returned
macro_name(Sstring): name of command

Condition
Makes a parameter conditional on the value of another parameter,
called the control parameter. The control parameter must be either
a boolean or an enumerated type.
Syntax: Condition cond_param control_param pvalue operation
polarity
Input: cond_param (Sstring): conditional parameter name
control_param (Sstring): control parameter name
pvalue (Sstring): control parameter value

Insight II/March 2000 339

12. Biosym Command Language

operation (Logical): off = OR, on = AND

polarity (Logical): off = normal, on = NOT
Error: Missing/Invalid conditional parameter, recursive conditions, re-
use of conditional parameter in macro without its control param-
eter.

Constant
Define a symbolic constant.
Syntax: Constant const_name value
Input: const_name (Sstring): new symbolic name
value: replacement value
Example:
Constant PI 3.14159
sum = $value * PI

Continue
Jump to the top of the loop. Typically placed with conditional
code.
Syntax: Continue
Example:
While ($n > 0)
n = $n - 1
# Skip this case, and start from the top
If ($n = 7)
Continue
End
Print $n
End

Define_Macro
Begin definition of a new macro.
Syntax: Define_Macro [return_type] name [param_type param][, ...]
Input: return_type (Sstring): for macro functions, data type re-
turned
name (Sstring): name of new command or function
param_type (Sstring): argument data type
param (Sstring): name of parameter

340 Insight II/March 2000

 BCL Reference

Define_Menu
Create a new pulldown menu.
Syntax: Define_Menu module_name menu_name
Input: module_name (Sstring): name of module to which new menu
will
be added
menu_name (Sstring): name of new menu

Define_Module
Create a new module. A name for the first menu in the module
must be specified. The module is placed in the first group of mod-
ules in the biochem discipline.
Syntax: Define_Module module_name menu_name
Input: module_name (Sstring): name of new module
menu_name (Sstring): name of first menu in new module

Def_Enum, Def_Enum_Sorted, Def_Enum_Unique

Add values to an Enumer.
Def_Enum: Value is added in the order specified.
Def_Enum_Sorted: Value is added alphabetically.
Def_Enum_Unique:Value is added alphabetically, not added if duplicate.
Syntax: Def_Enum param new_entry
Def_Enum_Sorted param new_entry
Def_Enum_Unique param new_entry
Input: param(Sstring): parameter name
new_entry (Sstring): addition to enum
Error: parameter not found, attempt to define value for system
parameter

Def_List, Def_List_Sorted, Def_List_Unique

Add values to a list. May be used in callbacks.
Def_List: Value is added in the order specified.
Def_List_Sorted: Value is added alphabetically.

Insight II/March 2000 341

12. Biosym Command Language

Def_List_Unique: Value is added alphabetically, not added if

duplicate.
Syntax: Def_List param new_entry
Def_List_Sorted param new_entry
Def_List_Unique param new_entry
Input: param (Sstring): parameter name
new_entry (Lstring): addition to list
Error: parameter not found, attempt to define value for system
parameter

End_Macro
Stop definition of a new macro.
Syntax: End_Macro

Fgets
Read a string of characters from a file. Reads up to end_of_file,
new_line, or specified limit. Attempts to open the file if not already
open. Use the Close command when finished reading.
Syntax: Fgets file_name char_count param
Input: file_name (Lstring): data file to read
char_count (Int): maximum number of characters to
read.
3up to 511 for Vlstring variable
param(Sstring): name of string variable to contain in-
put
data
Returns 1: successfully executed
0: execution failed, or beyond end of
file
Error: Invalid param_name, unable to open user file_name
Example:Fgets /tmp/list.data 40 $string

ForEach
Loop through an array or loop by an index.
Syntax: Form 1: Array

342 Insight II/March 2000

 BCL Reference

ForEach value In valuelist

statements
End
Valuelist is an array and value is of the same type as a member of the
array. With each iteration, value is set to the next member of
valuelist. The loop ends when valuelist is exhausted.
Form 2: Index
ForEach index From start To stop [Step steps]
statements
End
Where index is an integer parameter, start and stop are integer
expressions, step is integer constant with default value 1. The
conditional expression is evaluated by verifying index lies
between the range specified by start and stop.

FullScreen
Enables or disable FullScreen mode. In FullScreen mode, the
graphics window takes over the entire computer screen.
Syntax: FullScreen status
Input: status (Logical ON/OFF): new FullScreen mode

Get_Boolean, Get_Integer, Get_Coord, Get_Real, Get_Sstring,

Get_Lstring, Get_Vlstring, Get_Ident, Get_Enum
Used by callback functions to access the value of a parameter or its
default.
ONLY AVAILABLE IN CALLBACKS.
Syntax: Get_Boolean param var
Get_Integer param var
Get_Coord param var
Get_Real param var
Get_Sstring param var
Get_Lstring param var
Get_Vlstring param var
Get_Ident param var
Get_Enum param var
Input: param (Sstring): parameter to retrieve
var (Sstring): variable to store value for param

Insight II/March 2000 343

12. Biosym Command Language

(Note: var must be properly declared based on the

operation to be performed)
Returns: 3: command scope default
2: default
1: value
0: error
-1: empty
-2: emptied by user
Error: parameter is not accessible

Goto
Jump execution to a specified location. Every goto statement needs
a matching label followed by a (:), but not every label requires a
matching goto statement. Labels are not case sensitive and they
are a string of 19 or less characters. Any valid character can be part
of a label, e.g., 99999, exit, goodbye, done, begin_.
Syntax: goto label
Input: label (Sstring): name of label

If
Conditionally execute statements up to the associated End state-
ment based on a logical test. If statements may be nested.
Syntax: if (Logical_Test)
statements
End
The If statement can have an optional Else statement, which also
has an associated End. If the logical test fails, only statements after
the Else statement are executed.
Syntax: If (Logical_Test)
statements
End
Else
statements
End
The ElseIf statement provides an alternate form of the If..Else..
statement. This is useful when a series of tests need to be per-
formed. As soon as one of the tests succeeds, the statements below

344 Insight II/March 2000

 BCL Reference

the test, up to the next test (or end) are executed and control jumps
to the statement following the End.
Syntax: If (Logical_Test)
statement
ElseIf (Logical_Test)
statement
End

Make_File_List
Fill a file list value-aid that has already been attached to a param-
eter. More flexible than Param_Add_File_List. Typically used in
callback macros.
Syntax: Make_File_List File_List_Clear
value-aid path file_ext
Input: File_List_Clear (Logical): whether to clear value-aid parameter
value-aid (Sstring): value-aid name
path (Lstring): directory path where all files are lo-
cated
file_ext (Lstring): file extensions to search for,
comma separated
Returns: Number of file names added to the
value-aid.
Example: status = {Make_File_List File_List_
Clear Files . “bcl,log”}

Message_Print_Error
Display an error dialog with a message that you specify. The dia-
log has two buttons, “Done” and “Explain”. “Done” closes the
dialog. “Explain” closes the dialog and opens another dialog that
contains additional explanatory text.
Syntax: Message_Print_Error err_text explain_text
Input: err_text(Lstring): error message
explain_text(3Lstring): additional explanation

Insight II/March 2000 345

12. Biosym Command Language

Example: Message_Print_Error “Charge value out of range” \

“Formal charge must be between -6 and 6”

Param_Add_File_List
Attaches a value-aid to a parameter containing a list of files in the
current working directory with names ending in the specified suf-
fixes.
Syntax: Param_Add_File_List param suffixes
Input: param (Sstring): name of Lstring or Vlstring param
suffixes (Sstring): comma separated list of extensions
Example:Param_Add_File_List FileName “bcl,log”

Param_Comment
Add a line of text above a parameter in a parameter block.
Syntax: Param_Comment param comment justification
Input: param (Sstring): parameter name
comment (Sstring): text remark
justification (enumer): “Left”, “Center”, or “Right”

Param_New_Column
Start a new column in the parameter block. The specified parame-
ter is placed at the top of the next column. No check is made if too
many columns are created. We recommend that you use a maxi-
mum of four columns.
Syntax: Param_New_Column param
Input: param(Sstring): parameter name

Param_Pack
Add a double line beloe the specified parameter.
Syntax: Param_Pack param
Input: param(Sstring): parameter name

346 Insight II/March 2000

 BCL Reference

Param_Set_Style
Modify the appearance of a parameter in a parameter block. Lists
and Enumers may be displayed as popup option menus. Idents,
Lstrings and Vlstrings can be displayed as a single scrolling line.
Syntax: Param_Set_Style param style
Input: param(Sstring): parameter name
style(Sstring): PARAM_POPUP or
PARAM_HSCROLL
Errors: mismatched parameter type and style

Place_Valuator
Link a value-aid to a parameter. The Ruler and Palette are two pre-
built value-aids.
Syntax: Place_Valuator param value_aid location
Input: param (Sstring): target parameter name
value-aid (Sstring): value-aid name
location (enumer): location (side parameter block
only)
Default: normal placement
Top: top of the parameter block
Bottom: bottom of the parameter block

Preview_Command
Attach a callback to be run before the parameter block appears.
The callback is a macro with no parameters and no return value.
The callback accesses the command’s parameters with Get_ and
Setv_ statements. Note that only the last callback registered is
called.
Syntax: Preview_Command macro
Input: macro (Sstring): callback macro name
Error: command not found or it is not a BCL command

Preview_Function
Associates a callback with a parameter. The callback is called when
the parameter’s value is changed as a result of picking, focus

Insight II/March 2000 347

12. Biosym Command Language

change, explicit <enter> being pressed, or in response to a prompt

in the command line. The callback is a macro with no parameters
and no return value. The callback accesses the command’s param-
eters with Get_ and Setv_ statements. Note that only the last call-
back registered is called.
Syntax: Preview_Function param macro
Input: param (Sstring): parameter associated with callback
macro (Sstring): callback macro name
Error: command not found or it is not a BCL command

Print
The print statement prints an expression to the info area and text-
port. BCL will attempt to identify and print the expression in an
appropriate type.
Syntax: Print expression [expression]
Input: expression (Vlstring): variable, constant, expression
ExamplePrint “index = “ $index
Error: Invalid expression

Printf
Formatted print statement. See Write statement for Output For-
mats.
Syntax: Printf format_string expression [expression]
Input: format_string (Vlstring): user specified format string
expression (Vlstring): variable, constant, expression
Example:Printf “Index = \t%d\nlength = \t%d\n” $index $length
Error: Invalid format string, invalid expression

Prop_Exists
Determine if an Attr property is already assigned to an object.
Syntax: Prop_Exists property class object_spec
Input: property(Sstring): name of attr property
class (Enumer): Class of object that this property can

348 Insight II/March 2000

 BCL Reference

be
applied to: Atom, Monomer, or Mol
object_spec (Ident): Object to test
Returns: 1 if property set, otherwise 0
Example:If ({Prop_Exists MyMarker Mol CRN})

Prop_Get_Arr_Bool, Prop_Get_Arr_Int, Prop_Get_Arr_Float,

Prop_Get_Arr_Str
Retrieve an array of property values. Provides better performance
than Prop_Get when retrieving properties from all the atoms in a
monomer, using class Monomer_Atom, or all the atoms in a mol-
ecule, using class Mol_Atom. Property should be pre-defined or
registered with Prop_Register. Different statements return differ-
ent datatypes; you must use the appropriate datatype for the prop-
erty.
Syntax: Prop_Get_Arr_<datatype> property class object_spec
Input: <datatype>: type of value that will be returned
Bool int
Int int
Float float
Str lstring

property (Sstring):name of property to retrieve

class (Enumer): class of object to retrieve from, either
Mol_Atom or Monomer_Atom
object_spec (Ident):object to retrieve from
Returns: value of property or 0 (or ““) if uninitialized
Errors: mis-match datatype, mis-match assignment
Example:# get mass of all atoms in CRN
floatarr = { Prop_Get_Arr_Float Mass Mol_Atom CRN }

Prop_Get_Bool, Prop_Get_Int, Prop_Get_Float, Prop_Get_Str

Retrieve a property value. Property should be pre-defined or reg-
istered with Prop_Register. Use Prop_Exists to verify property is

Insight II/March 2000 349

12. Biosym Command Language

available for object. Different statements return different

datatypes; you must use the appropriate datatype for the property.
Syntax: Prop_Get_<datatype> property class object_spec
Input: <datatype>: type of value that will be returned
Bool int
Int int
Float float
Str lstring
property (Sstring):name of property to retrieve
class (Enumer): class of object to retrieve from: Atom,
Monomer, or Mol
object_spec (Ident):object to retrieve from
Returns: value of property or 0 (or ““) if uninitialized
Errors: property not defined, mis-match datatype, mis-match
assignment
Example:strvar = { Prop_Get_Str My_String Atom “CRN:29:OH”}

Prop_Register
Declare a new property. Two types of properties can be declared,
Attr and Func. An Attr property can be set and retrieved. A Func
property can only be retrieved. Func properties are registered with
an additional macro_name argument, which is executed each time
the property is requested with Prop_Get. Attr properties are main-
tained at the molecule level.
Syntax: Prop_Register type property class datatype [ macro_name]
Input: type (Enumer): Attr (r/w) or Func (ro)
property (Sstring): name of new property
class (Enumer): Class of object that this property can
be
applied to: Atom, Monomer, or Mol
datatype (Enumer): Bool, Int, Float or Str
macro_name (Sstring): name of macro that will be called
(if this is a Func property)
Returns: 1 if created successfully or if it is already registered the same
way
otherwise 0

350 Insight II/March 2000

 BCL Reference

Example:Prop_Register Func New_Prop Atom Str New_Prop_Macro

Prop_Register Attr MyMarker Mol Bool

Prop_Remove
Remove a user defined property from Insight II. Free all memory
used by an Attr property.
Syntax: Prop_Remove property class
Input: property (Sstring): name of new property
class (Enumer): Class of object that this property can
be
applied to: Atom, Monomer, or Mol
Returns: 1 on success, otherwise 0
Errors: system property, does not exist
Example:Prop_Remove Marker Base_Object

Prop_Set_Bool, Prop_Set_Int, Prop_Set_Float, Prop_Set_Str

Set an attribute property. Property should be registered with Prop_
Register. Different statements set properties with different
datatypes; you must use the appropriate datatype for the property.
Syntax: Prop_Set_<datatype> property class object_spec value
Input: <datatype>: type of value that will be returned
Bool int
Int int
Float float
Str lstring
property (Sstring): name of property to set
class (Enumer): class of object to set Atom,
Monomer, or Mol
object_spec (Ident): object to set
value: new value of proper data type
Returns: 1 on success, otherwise 0
Errors: property not registered, mis-match datatype, mis-match
assignment
Example:Prop_Set_Str My_String Atom “CRN:29:OH” “Old site”

Insight II/March 2000 351

12. Biosym Command Language

Read
Reads data from a specified file and assigns the data to variables.
Syntax: Read file_name format_string var [var]
Input: file_name (Vlstring): data file read
format_string (Vlstring): user specified format string
var (Sstring): variable to store value
Returns 1: successfully executed
0: execution failed, or beyond end of
file
Example:Read /usr/tmp/input.dat “%d %f” $index $length
Error: Invalid format_string, unable to open user file_name

Input Formats The format_string in the Read statement is a collection

of constants and specifications. Each specification starts with a
percent sign (%) followed by the letter s, f, or d. Each
specification must have a corresponding variable to store the
translated data.
s: string conversion. Any leading white space characters are
skipped. Characters are read until an end-of file is reached, or
until a white space character is seen. If end-of-file is reached be-
fore any non-white space character is seen, the operation is con-
sidered failed
f: signed decimal floating-point conversion. Any leading white
space characters are skipped. If no digits are read, the value is
zero. If the value is too large or too small to be represented as a
floating point number, the value is unpredictable. If the value
cannot be represented exactly as a floating-point number, the
value is truncated.
d: signed decimal conversion. Any leading white space characters
are skipped. Characters are read until end-of-file is reached, or
until a non-digit character is seen. The characters read are inter-
preted as a signed decimal number. If no digits are read, the val-
ue is zero. If the value expressed by the input is out of range
(2**32-1 ~ 2**32), then the value will have an unpredictable re-
sults.

352 Insight II/March 2000

 BCL Reference

Remove_Enum
Clears all entries from an Llist or Enumer parameter.
ONLY AVAILABLE IN CALLBACKS.
Syntax: Remove_Enum param
Input: param(Sstring): parameter name
Error: param is not an enumerated or list type

Return
Exit a macro before End_Macro. Required in function macros to
send a value back to calling macro; the argument must match the
return type declared in the Define_Macro statement.
Syntax: Return [expression]
Examples:Return # no return value
Return $center # return variable center
Return ($x+$y) # return an expression

Run_Bkgd_Job
Launch a background job.
Syntax: Run_Bkgd_Job job pathname file_of_files args
Input: job(Sstring): A unique name for the job that is
used in the commands in the Background_Job pulldown.
pathname (Lstring): The program to be run. If the direc-
tory where the program exists is in your PATH environment
variable, then you do not need to specify the directory path to the
program. Otherwise, this path specification is needed.
file_of_files (Lstring): The pathname of a file containing a
list of files needed by the background job. Each filename should
be listed on a separate line. Only needed if running on a remote
host, otherwise, specify “None”.
args (up to 30 Lstring’s): Background job command argument
list.
Returns: zero on error

Insight II/March 2000 353

12. Biosym Command Language

Screen_Update
Sets graphics refresh policy. By default, the graphics are only
updated when a macro completes. If Screen_Update is enabled,
refreshes take place during execution. Policy remains in effect
until reset with another Screen_Update.
Syntax: Screen_Update display_mode
Input: display_mode: (logical) ON/OFF
ON: refresh after each statement
OFF: refresh at end of macro (default)

Setv_Boolean, Setv_Integer, Setv_Coord, Setv_Real, Setv_

Sstring, Setv_Lstring, Setv_Vlstring, Setv_Ident, Setv_Enum
Set the current value of a parameter from a callback.
ONLY AVAILABLE IN CALLBACKS.
Syntax: Setv_Boolean param value
Setv_Integer param value
Setv_Coord param value
Setv_Real param value
Setv_Sstring param value
Setv_Lstring param value
Setv_Vlstring param value
Setv_Ident param value
Setv_Enum param value
Input: param (Sstring): parameter name
value: value of appropriate type for param

Setv_Focus
Shift keyboard input focus to a parameter from a callback.
ONLY AVAILABLE IN CALLBACKS.
Syntax: Setv_Focus paramindex
Input: param (Sstring): parameter name
index (int): Offset (1, 2, or 3) for coord parame-
ters
(0 for other types)

354 Insight II/March 2000

 BCL Reference

Setv_Precision
Set number of places shown after decimal in float parameter.
ONLY AVAILABLE IN CALLBACKS.
Syntax: Setv_Precision param places
Input: param (Sstring): parameter name
place (int): number of places after the decimal
point

Setv_Trigger
Make a parameter the trigger. When the trigger is filled by a pick,
value-aid or explicit “Enter”, the command executes. See the Trig-
ger statement.
ONLY AVAILABLE IN CALLBACKS.
Syntax: Setv_Trigger param
Input: param (Sstring): parameter name

Set_Boolean, Set_Integer, Set_Coord, Set_Real, Set_Sstring,

Set_Lstring, Set_Vlstring, Set_ident, Set_Enum
Set the default value for a parameter.
Syntax: Set_Boolean param value
Set_Integer param value
Set_Coord param value
Set_Real param value
Set_Sstring param value
Set_Lstring param value
Set_Ident param value
Set_Enum param value
Set_List param value
Input: param (Sstring): parameter name
value: value of appropriate type for param
Error: Parameter not found, invalid parameter value

Insight II/March 2000 355

12. Biosym Command Language

Set_Param_Pick
Add a picking function and related value-aid to parameters. The
picking functions enable the parameters to be filled in with the
specification of the object the user picks from the screen with the
mouse. The value-aids permit selecting from a list of objects.
Syntax: Set_Param_Pick Param Template [Screen_Only Object]
Input: Param (Sstring): parameter name of appropriate
type
Template (Sstring): see Picking Templates below
Object (Sstring): see Picking Object below

Picking Templates The picking function and value-aid provided are

determined by the type of the template.
MOLECULE_NAME is used when the parameter specifies the name of
a molecule. The attached pick function only picks molecules.
The attached value-aid list shows available molecules. The
associated parameter must be sstring, lstring, ident, or short_
ident type.
MOLECULE_SPEC is used when the parameter specifies the name of a
molecule, monomer, or atom. The attached pick function only
picks molecules, monomers, or atoms, depending on the value
of the associated pick-level value-aid. The attached value-aid
list shows available molecules. The associated parameter must
be ident or short_ident type.
MOLECULE_ASSEMBLIES is the same as MOLECULE_NAME,
except that assemblies may be picked and the attached list
includes assemblies. The associated parameter must be ident or
short_ident type.
OBJECT_NAME is used when the parameter specifies the name of an
object. The attached pick function only picks objects. The
attached value-aid list shows available objects. The associated
parameter must be sstring, lstring, ident, or short_ident type.
ATOM_SPEC is used when the parameter specifies the name of an atom.
The attached pick function only picks atoms. When an atom is
picked, the full molecule:residue:atom specification is filled
into the parameter. No value-aid is attached to the parameter.
The associated parameter must be ident, or short_ident type.

356 Insight II/March 2000

 BCL Reference

Picking Object If the Picking Template is OBJECT_NAME, a

SCREEN_ONLY object may be specified. This limits object
picking to only the type specified. Possible values for Object:
MOLECULE: Molecule type object
ASSEMBLY: Assembly type object
GRAPH: Graph type object
GRID: Grid type object
SPECTRUM: Spectrum type object
CONTOUR: Contour type object
USER_OBJECT: User_Object type object

Set_Rand
Seed the rand() Intrinsic Function random number generator. If
set_rand is not called before calling rand (), set_rand will be called
automatically with default value of 1 as the seed.
Syntax: Set_Rand starting_seed
Input: starting_seed (int): random generator seed
Error: Invalid starting_seed

Set_Random
Seed the random() Intrinsic Function random number generator. If
set_random is not called before calling random (), set_random will
be called automatically with default value of 1 as the seed.
Syntax: Set_Random starting_seed
Input: starting_seed (int): random generator seed
Error: Invalid starting_seed

Set_SideBlock
If set to off, display parameter block in multiple columns.
Syntax: Set_Sideblock state
Input: state (Logical):
ON: single column (default)
OFF: multi-column

Insight II/March 2000 357

12. Biosym Command Language

Set_Slider
Determine the range of a slider value-aid. The start and stop values
are floating point and may be positive or negative.
Syntax: Set_Slider valuator_name start stop
Input: valuator_name (Sstring): valuator name
start (float): valuator staring point
stop (float): valuator ending point
Example:Set_Slider Ruler -50.0 50.0

Size_List
Set the number of rows displayed in an Llist parameter. The
default is 7. The allowable range is from 3 to 50.
Syntax: Size_List param rows
Input: param(Sstring): Llist parameter name
rows(int): Number of visible entries
Example:Size_List list_param 4

Switch
Conditionally execute code by matching a variable with a case.
The switch statement has a matching End statement. Cases can be
numeric or alpha-numeric, but must match the type of the Switch
variable. Each Case statement has a matching Breaksw statement.
An optional Default case may be specified.
Syntax: Switch $variable
Case 1:
statements
Breaksw
Case 2:
statements
Breaksw
Default:
statements
Breaksw
End

358 Insight II/March 2000

 BCL Reference

System_Fetch_Assy
Returns an array of assemblies satisfying the specification argu-
ment.
Syntax: System_Fetch_Assy object_spec
Input: object_spec (Ident): object specification for assemblies.
Returns: Array of assemblies or NULL.

System_Fetch_Atom
Returns an array of atoms satisfying the specification argument.
Syntax: System_Fetch_Atom object_spec
Input: object_spec (Ident): object specification for the atoms.
Returns: Array of atoms or NULL

System_Fetch_Mol
Returns an array of molecules satisfying the specification argu-
ment.
Syntax: System_Fetch_Mol object_spec
Input: object_spec (Ident): object specification for molecules.
Returns: Array of molecules or NULL.

System_Fetch_Mono
Returns an array of monomers satisfying the specification argu-
ment.
Syntax: System_Fetch_Mono object_spec
Input: object_spec (Ident): object specification for monomers.
Returns: Array of monomers or NULL.

System_Fetch_Object
Returns an array of objects satisfying the specification argument
Syntax: System_Fetch_Object object_spec
Input: object_spec (Ident): object specification.

Insight II/March 2000 359

12. Biosym Command Language

Returns: Array of objects or NULL.

System_Fetch_Sketch
Returns an array of 2-D molecules satisfying the specification
argument.
Syntax: System_Fetch_Sketch object_spec
Input: object_spec (Ident): object specification for 2D mole-
cules.
Returns: Array of 2D molecules or NULL.

Test_Boolean
Convenience function for retrieving the state of a logical parame-
ter from a callback macro.
ONLY AVAILABLE IN CALLBACKS.
Syntax: Test_Boolean param
Input: param(Sstring): logical parameter name
Value: result (int): 1 if ON, else 0
Example:If ({Test_Boolean Set_Color})
Error: param is not a logical type

Test_Enum
Convenience function for comparing an Enumer parameter with a
value from a callback macro.
ONLY AVAILABLE IN CALLBACKS.
Syntax: Test_Enum param value
Input: param (Sstring): enumer parameter name
value (Sstring): parameter value
Value: result (int): 1 if equal, else 0
Example:If ({Test_Enum File_Type “PDB”})
Error: param is not an enumerated type
value does not occur in param

360 Insight II/March 2000

 BCL Reference

Textport
Raise the textport window in the window stack, making it visible.
Useful if you are printing multiple lines of output to the textport.
Syntax: Textport display_status
Input: display_status (boolean): ON / OFF
ON: pop the textport
OFF: push the textport (default)

Trigger
Make a parameter the trigger. When the trigger is filled by a pick,
value_aid or explicit “Enter”, the command executes. If no explicit
trigger is set for a macro, the last parameter is the trigger.
Syntax: Trigger param
Input: param (Sstring): parameter name
Example:Trigger index # set parameter <index> as the trigger
Trigger ”” # remove trigger parameter

While
Loop until a logical test fails. The While statement has a matching
End statement.
Syntax: While (Logical_Test)
statements
End

Write
Formatted write to a text file If the file is not open, Write attempts
to open the file. If the file exists, Write appends to the file. If the
file does not exist, it will be created.
Both the format string and expression may contain the following
escape characters:
\n newline
\t tab

Insight II/March 2000 361

12. Biosym Command Language

\\ literal backslash
\” literal quote

Syntax: Write file_name format_string expression [expression]

Input: file_name (Vlstring): data file for write
format_string (Vlstring): user specified format string
expression (Vlstring): variable, constant, expression
Value 1: if successfully executed
0: on failure
Error: Invalid format string
Unable to open user file_name
Invalid expression

Output Format The format_string used by the Printf and Write

statements contains constants and specifications to format
output. The specifications are percent signs (%) and one of the
following character combinations:
[n]s: string conversion. If precision specification n is not given, then
the converted value is the sequence of characters in the string up
to but not including the terminating null character. If a precision
specification n is given, then the converted value will only be the
first n characters of the string, or up to but not including the ter-
minating null character, whichever is shorter.
[n.p]f: signed decimal floating-point conversion. The converted value
consists of a sequence of decimal digits, possibly with an em-
bedded decimal point. Precision is specified by a number fol-
lowing the decimal point, which is the number of digits that will
appear after the decimal point in the output. If the floating-point
value cannot be represented exactly in the number of digits pro-
duced, the converted value will be the result of rounding the ex-
act floating-point value to the number of decimal places.
[p]d: signed decimal conversion. The converted value consists of a se-
quence of decimal digits that represent the absolute value of the
argument. The converted value will have leading zeros if neces-
sary to satisfy the precision specification.

362 Insight II/March 2000

 Index of BCL Statements

Index of BCL Statements

Assy_Fetch_Molecule 336
BCL_UNIX 336
Break 336
Cell_Get_Real, Cell_Get_Int, Cell_Get_String 336
Cleanup_Command 337
Close 337
Command 337
Condition 337
Constant 338
Continue 338
Define_Macro 338
Define_Menu 339
Define_Module 339
Def_Enum, Def_Enum_Sorted, Def_Enum_Unique
339
Def_List, Def_List_Sorted, Def_List_Unique 339
End_Macro 340
Fgets 340
ForEach 340
FullScreen 341
Get_Boolean, Get_Integer, Get_Coord, Get_Real,
Get_Sstring, Get_Lstring, Get_Vlstring, Get_Ident,
Get_Enum 341
Goto 342
If 342
Make_File_List 343
Message_Print_Error 343

Insight II/March 2000 363

12. Biosym Command Language

Param_Add_File_List 344
Param_Comment 344
Param_New_Column 344
Param_Pack 344
Param_Set_Style 345
Place_Valuator 345
Preview_Command 345
Preview_Function 345
Print 346
Printf 346
Prop_Exists 346
Prop_Get_Arr_Bool, Prop_Get_Arr_Int, Prop_Get_
Arr_Float, Prop_Get_Arr_Str 347
Prop_Get_Bool, Prop_Get_Int, Prop_Get_Float,
Prop_Get_Str 347
Prop_Register 348
Prop_Remove 349
Prop_Set_Bool, Prop_Set_Int, Prop_Set_Float, Prop_
Set_Str 349
Read 350
Remove_Enum 351
Return 351
Run_Bkgd_Job 351
Screen_Update 352
Setv_Boolean, Setv_Integer, Setv_Coord, Setv_Real,
Setv_Sstring, Setv_Lstring, Setv_Vlstring, Setv_Ident,
Setv_Enum 352
Setv_Focus 352
Setv_Precision 353
Setv_Trigger 353

364 Insight II/March 2000

 Index of BCL Statements

Set_Boolean, Set_Integer, Set_Coord, Set_Real, Set_

Sstring, Set_Lstring, Set_Vlstring, Set_ident, Set_
Enum 353
Set_Param_Pick 354
Set_Rand 355
Set_Random 355
Set_SideBlock 355
Set_Slider 356
Size_List 356
Switch 356
System_Fetch_Assy 357
System_Fetch_Atom 357
System_Fetch_Mol 357
System_Fetch_Mono 357
System_Fetch_Object 357
System_Fetch_Sketch 358
Test_Boolean 358
Test_Enum 358
Textport 359
Trigger 359
While 359
Write 359

Insight II/March 2000 365

12. Biosym Command Language

366 Insight II/March 2000

13 Utilities

These utilities are included with the Insight program:

• Contour
• Inplot
In the following descriptions, the Purpose section is a brief
description of the function and applications for each utility. The
Syntax section describes how to use the utility. Examples demon-
strate correct usage. Finally, background and incidental informa-
tion about each utility is included in a Notes section.
Note that these utilities do not appear on the menus within the
Insight II program. Utilities must be invoked at the UNIX operat-
ing system prompt.

Insight II/March 2000 367

13. Utilities

Contour

Purpose
The Contour utility allows you to contour two- or
three-dimensional grid data, such as electron density. It
requires an input file of data to be contoured and
produces an output file of contours, using linear
interpolation, that can be displayed by Insight II.
When the Contour utility is run, you specify the name
of the output file first, since information about the input
file is stored in a header record within the output file to
enforce consistent use of existing contour data. This
frees you from repeating setup information when
appending to an existing output file.

Syntax
contour [outputfilename [inputfilename]]
inputfilename Specifies a file containing
values at each of the points
in the grid. The values may
be entered with either x or
y as the fastest-varying co-
ordinate. It may also con-
tain other parameters
which are necessary to
align the contours with the
reference molecule. If the
necessary alignment pa-
rameters are not present in
the file, the Contour utility
attempts to compute them
if possible from the data
present within the file. If
this is not possible, you are
prompted for the neces-
sary parameters interac-
tively. The formats for the

368 Insight II/March 2000

 grid data are described be-
low.
outputfilename The output file contains
the actual coordinates (in
fractional space) used to
draw the contours. The
output file also contains
two header records. The
first describes how the in-
put data was used to create
the output. It contains the
input filename, the type of
input file (unformatted or
formatted), the version and
release of the present utili-
ty, which contour planes
were used, which columns
were used, and any align-
ment parameters that are
necessary to contour this
input. The second header
record contains the cell pa-
rameters, the fractional
space limits, the number of
x, y, and z values, and any
existing contour levels
which have been calculat-
ed during a previous run.
Filenames should be compatible with the operating
system being used. Any required files not specified on
the command line are prompted for by the Contour
utility.

INPUT FILES
There are essentially five types of input files, three
formatted and two unformatted (binary). Unformatted
files require less disk storage and can be read in

Insight II/March 2000 369

13. Utilities

quickly. Formatted files may require more disk

storage, but you can use the information in random
column order, especially those files created by the put
graph command within Insight II or the torsion files
created by Discover. Within each of these types there
is provision for integer or floating-point values. There
are parameters which are used to describe how the data
is represented in the input file and additional
parameters which are used to position the contour
relative to the reference molecule. The parameters vary
slightly in their meaning for each of the basic file types.

Formatted Files
The formatted files are either a standard grid file or a
torsion file. The first line in a formatted file is a title
or comment containing any combination of characters.
All lines in a .grd file must not exceed 132 characters.
1. Standard Formatted File
The standard grid file consists of five lines of pa-
rameters which precede the actual data. The first
line is the title as described above. The second line
is a format specifier (in FORTRAN style), en-
closed in parentheses. This line must begin in col-
umn 1, and specify the number of values on a line
in the file as well as the format of those values. An
implicit single field causes errors. A single field
must include the number 1. For example,
(1F10.6).
The third line specifies the unit cell parameters as-
sociated with the grid: the cell lengths a, b, and c
followed by the cell angles alpha, beta, and gam-
ma. These six values must be floating-point num-
bers, separated by spaces (no commas). If the grid
is not in the context of the molecule’s unit cell, a,
b, and c may be thought of as the distance the grid
spans in each direction, x, y, and z. For example,
if the grid spans the space from -20 to +10 in x,
then a is entered as 30.0. Alpha, beta, and gamma
are entered as 90.0 90.0 90.0.
The fourth line specifies the number of x, y, and z
intervals which are actually contained in the file.
Note that the width of an interval in x must be

370 Insight II/March 2000

 equal to the width of an interval in y, which must
also be equal to the width of an interval in z; the
grid is comprised of cubes. The fourth line also
contains an optional set of three integers that de-
scribe which directions to contour if two-dimen-
sional contouring is desired. By default, all direc-
tions are used. All numbers must be integers sepa-
rated by spaces (no commas). The contour direc-
tions should be either 0 or 1, with 0 meaning no
contour in this direction and non-zero (i.e., 1)
meaning contour in this direction. The directions
are x, then y, then z.
The final parameter line specifies which value, x
or y, varies fastest in the file, and the starting and
ending intervals in x, y, and z. The first number on
the line is entered as a 1 or 3. The digit 1 specifies
x is the fastest-varying coordinate. The digit 3
specifies y is the fastest varying coordinate. The
next six numbers are entered in the order: x start,
x end, y start, y end, z start, z end. The six numbers
must be integer numbers, separated by spaces (no
commas). Note that lines 3 through 5 are required
to uniquely locate the starting and ending coordi-
nates of the grid. The following expressions are
used to calculate the starting and ending coordi-
nates of the grid:
x start = (x cell length) (starting interval
in x)
(ending x interval - starting x in-
terval)
x end = (x cell length)(starting interval
in x + number x intervals)
(ending x interval - start-
ing x interval)
Similar computations are done for y and z.
An example of the standard formatted file is in-
cluded as Example 1, below.
2. Graph-Generated Contour File
A graph-generated contour file is created by In-
sight with the command put graph . . . contour.

Insight II/March 2000 371

13. Utilities

The format of this file is similar to that of the stan-

dard formatted files, except that the data for each
function on the original graph is written into a sep-
arate column. Thus there is only one contour value
on each line, which may be any of the entries on
the line.
3. Torsion File
Torsion files are the result of dihedral angle
searches by Discover, initiated with the Discover
rotors command. The torsion file consists of nine
header lines describing how the data was produced
by Discover, followed by columns of data. All
lines in a torsion file are only 80 characters long,
plus one space for the end-of-line character. Any
line longer than this is misinterpreted. The first
line is the title as described previously. The next
group of lines, seven in number, are individual
column headers for the data that follows. Lines
starting with the word unassigned, as well as blank
lines, are considered empty. The number of non-
empty lines, in this group of seven, corresponds to
the number of actual torsions defined and there-
fore corresponds to the number of columns of data
(plus one more column for the energy data). The
program also computes which is the first full row
of data, since it is possible to create a torsion file
where the first few rows of data are not complete.
After these column descriptors is a single line used
for the column headings. The first word within this
line is always ENERGY. This is expected. If it is
missing, the program is not able to recognize this
file as being a formatted torsion file. The names of
the dihedral angles being searched follow the EN-
ERGY keyword. Following the header line are
columns of data. The first entry in each column is
the energy for a given set of dihedral angles, and is
followed by the values for the dihedral angles.
Since there is no information about the grid itself,
the required parameters are calculated from the ac-
tual data. The first step in any column is used for

372 Insight II/March 2000

 this calculation, so you are limited to only one
stepping function per torsion data column being
produced. Also, you may not contour columns that
use angles containing common bonds that cause
both columns to step at the same time.
An example of a torsion input file is included as
Example 2, below.

Unformatted Files
Unformatted files are produced using the FORTRAN
write statement with only the logical unit specified.
1. Standard Unformatted
The standard unformatted file contains 2 lines of
parameters which precede the actual data. The first
line is a title or comment which may be up to 132
characters in length. The data may be 2- or 4-byte
integer, or 4-byte floating-point (single precision).
Each record in the file must contain all of the x val-
ues for a given y, or all of the y values for a given
x.
The second line contains the parameters necessary
for reading the file and for positioning the map rel-
ative to the molecule. The first three entries on this
line describe the contents of the file. The first entry
is a 4-byte integer. Set to 0, it specifies that x is the
fastest-varying coordinate, while set to 1 it speci-
fies that y is the fastest. The second entry is a 4-
byte integer giving the size of the data in bytes. Its
valid values are 2 or 4. The third entry is also an
integer. Set to 0 it specifies that the data is float-
ing-point, while set to 1 it specifies that the data is
integer.
The next twelve entries are 4-byte floating-point.
The first three are the cell lengths. If the cell
lengths do not correspond to the molecule’s unit
cell, then the cell lengths may be thought of as the
distance the grid spans in x, y, and z. Following the
three cell lengths are the three cell angles. The
next six entries are the fractional starting and end-
ing positions for x, y, and z. The fractional coordi-

Insight II/March 2000 373

13. Utilities

nates are calculated by dividing the starting or

ending coordinate by the cell length. For example,
if the cell length in the x direction is 5 angstroms
and the desired starting coordinate in the x direc-
tion is -5, then the first fractional entry is -1.0 = (-
5/5). The six fractional positions are ordered: x
start, x end, y start, y end, z start, z end. The final
three entries are 4-byte integers which represent
the number of x, y, and z intervals respectively.
The remainder of the file contains the actual data.
Each record contains all the x values for a given y,
or all the y values for a given x.
2. Non-standard Files
There is a provision for using non-standard unfor-
matted files. In this case, all the required parame-
ters must be supplied interactively. Once this is
done, subsequent entries into the output file do not
require user input since the information is stored
within the output header record.

INTERACTION WITH THE CONTOUR

UTILITY
This utility is invoked by entering:
> contour [outputfile inputfile]

1. The program is run by typing the contour com-

mand at the operating system prompt. You are
prompted interactively for any required informa-
tion.
2. Once a valid output file has been given, the pro-
gram determines first, whether the output file ex-
ists, and second, whether it contains a valid header
record. If there is a header record, you are not
prompted for anything except the contour level(s)
desired. (In the case of a torsion contour file as in-
put, you are also prompted for information on
which columns to contour.) If the specified output
file does not exist, you are prompted for some

374 Insight II/March 2000

 comment to be stored in the new output file. This
is displayed on subsequent entries into this file. If
the file exists and does not contain a header record
(indicating an output file created by previous ver-
sions of this program) or if this is a new file, you
are then prompted for the input file (if not given in
the original command). If the input file is a non-
standard unformatted file, you are prompted for
missing grid parameters. If the file is a multi-col-
umn formatted file (such as a torsion file), you are
prompted for which columns of data are to be used
and in what order. The default is to contour the
data in the first column with a, the fastest-varying
coordinate, and b, the second-fastest-varying co-
ordinate following respectively. For torsion files,
the default is to contour the data (which is always
in the first column and cannot be changed) with a
corresponding to the last column, and b and op-
tionally c preceding respectively. Normally these
are the fastest-varying columns in the torsion file,
assuming standard Discover output. Also, with
torsion files it is possible to have columns of data
that are not used directly, but that have an effect on
the grid location. In other words, these columns
need to have fixed angular values to uniquely align
the grid within the data file. You are prompted to
specify which angle should be fixed within each of
these non-data columns. In this case the default is
to fix the grid to the first angle in each non-data
column. Once the required information has been
input, you can specify which contour(s) you want
computed.
3. Contouring level specification allows for multiple
contour levels to be given by a series of individual
contour levels, by automatic stepping based on the
starting and stopping contour levels, or by a com-
bination of these two methods. You can step be-
tween these boundaries either by giving the num-
ber of intervals or by giving the size of each step.
In either case, the starting level is always comput-
ed and if the number of intervals is given, the stop-

Insight II/March 2000 375

13. Utilities

ping level is computed. When specifying the num-

ber of intervals, one contour level more than spec-
ified is produced. This means that the example in-
put below results in 11 contours, each 0.1 units
apart.
> auto 5.0 6.0 number 10

4. Contouring continues until you specify exit (or x),

or until 100 contour levels are present within the
output file. When using automatic contour level
specification, the entire command can be given at
one time, as done in the example above, or done in
pieces. In the latter case you are prompted for the
next piece of information. You are also prompted
if an incorrect value is given along the way, such
as a stopping contour level that is less than the
smallest level within the input file. All information
following the incorrect value is lost and must be
re-entered.

EXAMPLE SESSION
This example uses a Discover rotors file named
acetyl.tor. Prompts provided by the utility are in
regular type; required responses are in boldface type:
> contour

> Enter name of output file:

acetyl.cnt

> Comment for output file: tor.cnt

Energy (kcal/mol) vs Phi vs Psi for
N-acetylalanine-N’-methylamide

> Enter name of the input file:

acetyl.tor

> Use default column order (y/n or

exit): y

> Each record contains 1 floating

point numbers, each having a field
width of 9

376 Insight II/March 2000

> Created new contours

> Number of x values (per plane): 37

Number of y values (per plane): 37
Number of z values (planes): 1
Unit cell lengths 360.000000
360.0000001.000000
Unit cell angles 90.000000
90.00000090.000000
Fractional limits in x are
-0.500 to 0.500
Fractional limits in y are
-0.500 to 0.500
Fractional limits in z are
-0.500 to 0.500
Loading data for plane 1
The minimum contour value is:
-10.327
The maximum contour value is:
9.583

> Enter contour level(s) desired

(exit or auto): auto

> Enter starting and stopping con-

tour levels: -10.327
9.583

These responses determine which area of the map is

contoured.
> Enter stepping information (number
or size): number

> Enter number of intervals:

36

> Direction 0 contains # vectors

> Direction 1 contains # vectors

> Direction 2 contains # vectors

> Enter contour level(s) desired

(exit or auto): exit

Insight II/March 2000 377

13. Utilities

Example 1: Standard Formatted File

COMPLETE MINI MAP
(17I5)
20.00000 1.25 1.25 90.00000
90.00000 90.00000
16 1 1
1 -8 8 -1 0 0 1
-6 14 0 -24 -31 -45 -48 -16
39 102 102 18 -38 -39 -42 -43 -44
-31 -21 -56 -50 -30 17 103 106
107 2 -37 -32 -29 -29 -27 -32 -36
-54 -54 20 95 90 74 62 11
-25 -25 -39 -50 -32 -19 -44 -51 -55
-56 -2 81 110 54 -25 -47 -41
-28 -33 -24 -16 -51 -42 108 215 230

This example specifies that there are 16 intervals in the

x direction, 1 interval in the y direction, and 1 interval
in the z direction contained in the file. The 16 x
intervals span the coordinates -10.0 to 10.0, as
calculated from:
20.0 * (-8/(8 - -8))
and:
20.0 * ((-8 + 16)/(8 - -8))
The interval in the y direction spans the coordinates -
1.25 to 0.0, as calculated from:
1.25 * (-1/(0 - -1))
and:
1.25 * ((-1 + 1)/(0 - -1))
The interval in the z direction spans the coordinates 0.0
to 1.25, as calculated from:
1.25 * (0/(1 - 0))
and:
1.25 * ((0 + 1)/(1 - 0))
Note that the file contains 68 grid points, since there
are 2 z planes, each having 2 y values and 17 x values:
2 * 2 * 17 = 68

378 Insight II/March 2000

Example 2: Torsion Input File
COMPLETE MINI TORSION FILE
phi ACE 1:C ALA 1:N ALA
1:CA ALA 1:C
psi ALA 2:N ALA 2:CA ALA
2:C N-M 2:N
unassigned
unassigned
unassigned
unassigned
unassigned
ENERGY phi psi
15169.1017 0.00
15169.1017 0.00 0.00
60.2420 0.00 120.00
100.2786 0.00 -120.00
15169.1017 0.00 0.00
71.9180 120.00 0.00
62.4917 120.00 120.00
99.2156 120.00 -120.00
71.9180 120.00 0.00
28.7035 -120.00 0.00
15.9646 -120.00 120.00
59.3138 -120.00 -120.00
28.7035 -120.00 0.00
15169.1017 0.00 0.00
60.2420 0.00 120.00
100.2786 0.00 -120.00
15169.1017 0.00 0.00

Insight II/March 2000 379

13. Utilities

Inplot

Purpose
This procedure creates various device-specific
command files from the intermediate plot file (.ipf)
created by Insight II (using the Export_Plot
command, in the File pulldown). To use this utility,
call the Inplot utility from either outside Insight II or
by using the Unix command.

Syntax
inplot device filename [portrait/landscape]
[scale value]
[color/gray]
[pen pen# [pen#...]/only
pen#]
[linewidth value]
[output filename]
[banner]

device Specifies one of the fol-

lowing types of printers:
Device
Default File Extension
postscript
.ps
hpgl
.hp
eps (encapsulated Post-
Script).eps
qms
.qms
pict
.pict

380 Insight II/March 2000

filename Specifies an input file to
be plotted.
portrait, landscape Specifies the orientation
of the image on the page.
Landscape, the default,
puts the x axis of the image
along the longest edge of
the medium, while por-
trait places the y axis onto
the longest edge. These
options are mutually ex-
clusive; only one may be
specified in any one com-
mand.
scale value Increases the x and y val-
ues equally. By default,
this value is set to 1.0.
color Creates color (rgb) post-
script. This is the default.
gray Creates gray scale post-
script. If the gray option is
used, all rgb color values
are mapped to gray scale.
The gray and color op-
tions are mutually exclu-
sive; only one may be used
in a single command.
pen pen# Remaps the internal pen
values to match the plotter,
as desired. By default,
postscript color is treated
as one of these hpgl pens.
On hpgl, for example, pen

Insight II/March 2000 381

13. Utilities

4 is rgb color red

(1.0,0.0,0.0).
only pen# Causes all plotting to be
done in the single color
corresponding to the pen#
given. For example, only 0
causes all plotting to be
done in black.
output filename By default, the output file-
name is the same as the in-
put filename with a differ-
ent extension, and depends
on which device type is se-
lected. The output param-
eter can be used to over-
ride this default value and
is useful for trying various
combinations of parame-
ters to modify actual re-
sults.
banner Creates a single cover
page to be printed before
the actual image from the
input file.
When device is specified as either postscript (which
uses a gray scale to approximate coloring) or hpgl
(which attempts to duplicate the Insight II color
scheme), the pen and only options are valid; the color
option is only valid with postscript. Note that the color
and gray options are mutually exclusive; only one may
be used in a single command. Also note that the pen
and only options are mutually exclusive. Specifying
hpgl as the device assumes a six-pen plotting device,
but this can be overridden either by specifying each
pen with values between 0 and 8 (0 meaning pen 1,
black) or by specifying only 8. This latter command
creates the following default pen scheme for an eight-
pen plotter:

382 Insight II/March 2000

 Pen # Color
1black
2blue
3magenta
4red
5yellow
6green
7cyan
8black
For six-pen plotters, pen values of 7 or 8 are treated as
pen 6.
Postscript uses the Insight II color scheme so that
custom coloring is reproduced.

Examples
> inplot hpgl figure1 scale .75

> inplot postscript figure1 scale .75

only 8 linewidth 3

> inplot qms figure1 output figure1.plot

color

Notes

INTERMEDIATE PLOT FILE FORMAT

There are two parts to the intermediate file, the header
and the body. The header gives information about the
number of vectors present within the file, the
conversion factor that was used to integerize the
vectors, and the Insight II version and release number
that created this file. All these fields and their functions
are described in more detail later. The body contains
pairs of integers telling pen color and line width, and
giving the pen up/down commands with the
appropriate absolute positions. All this information is
stored in binary format to save disk space.
The header is a single record of format given below (C
language description):
struct head_t {
int number_of_records;
int conversion_factor;
int version_number;
int release_number;

Insight II/March 2000 383

13. Utilities

int filler[16]; /* for later possible information */

} head_type;
The number_of_records field tells how many vectors
have been put into the body of this file, making
termination of reading independent of end-of-file (eof)
markers. Since the vectors are normalized to a range of
0.0 to 1.0 before being written to the intermediate file,
integerization simply means multiplying this
normalized value by the conversion_factor (which is
one quarter the maximum value for a short integer,
16384). The version_number and the release_number
are stored so that these intermediate files may be used
by later versions of Insight II. The filler is reserved for
later use.
Within the body, information is stored compacted to a
single integer storage size containing an x,y pair. The
format is given below:
struct body_t {
short x;
short y;
} body_type;
The x and y values are the pen position in short integer
format. Pen up and down commands are encoded by
giving pen down pairs a negative y value, while pen up
does not. Since all vectors are positive this can be done
without ambiguity. The color and linewidth
information are given special negative x control
values, with the y value specifying the color and
linewidth values. This format allows the same record
type to be used for all commands within the body of the
file. The control values (negative x) are given below:
-1 end card
-2 pen value card
-3 linewidth card
-4RGB color card
-5string control card

384 Insight II/March 2000

RGB Color Card

x y
1 8 7 8 8
A B C D E

This diagram describes the use of the x and y pair

stored in the .ipf file. The numbers indicate the number
of bits used and the letters are the field descriptors.
This usage is mainly for the RGB control card,
although other control cards must conform within x. A,
B, and C make up the x storage value, and D and E
make up the y value. The following table describes the
usage of these fields.
Field#bitsUsage
A1If set, indicates this is control card.
B8Holds red color value of RGB system.
C7Positive value of control card.
D8Holds green color value of RGB system.
E8Holds blue color value of RGB system.
The individual RGB values range from 0 to 255, with
0 indicating no color and
255 indicating full saturation.

Examples Using RGB Card

x, y ValuesMeaning
(-32644, -1) RGB(0,255,255), indicates cyan color
(-4, -256) RGB(255,255,0), indicates yellow color
(-4, 255) RGB(255,0,255), indicates magenta color
There is no range of y values that is enforced upon the
control values, but the pen values have an effective
range of 0 to 8.

String Control Card

In order to allow fonted text from Insight II to be printed by
devices that can and those that cannot handle fonted text, the .ipf
file currently contains two representations of fonted character
strings. Fonted character strings are stored as ASCII characters
and as a series of move commands. The move commands repre-

Insight II/March 2000 385

13. Utilities

sent the strokes required to produce the characters in the standard

inplot font, and consist of records as described above.
This allows drivers for devices capable of plotting with fonts to use
the ASCII string and ignore the stroked character data. Likewise,
drivers for devices that do not handle fonted text can skip the
ASCII string and process the stroke commands.
The string control card contains two control values. The x value is
always -5, indicating a string control card. The y value can be -1, -
2, or -3, as shown in the table below.
xyUsage
-5-1Begin character data
-5-2End character data/begin stroked data.
-5-3End stroked data.

The first record after the begin character data control card contains
string length, font, and point size data encoded as follows:

x y
8 8 16
A B C

where field A is the number of characters, field B represents the

font, and field C is the point size. Each field is a positive number.
Field B contains a font code. The current Insight II fonts are Cou-
rier (B = 1), Helvetica (B = 2), and Times (B = 3).
The following records contain bytes of ASCII codes packed four to
a record, with the last record being padded with null characters if
necessary.
The -5, -2 string control card indicates the end of ASCII records
and the start of stroked data. The end of stroked data is indicated
by the -5, -3 control card.
For example, the string "Hello!" in Courier with a point size of 15
is represented by the following (x,y) pairs:
(-5,-1)(2049,15)(18533,27756)(28449,0)(-5,-2)...stroked data...(-5,-3)

386 Insight II/March 2000

 Intermediate Plot File Format Exam-
ples
> 1000,1000
Moves to position 1000,1000 with the pen down.
> 1000,-1000
Moves to position 1000,1000 with the pen up.
> -2, 4
Changes pen to number 4.
> -3, 2
Changes linewidth to 2.
> -1, --
Indicates end of file; y value does not matter. There
should only be one of these per file.

Insight II/March 2000 387

13. Utilities

388 Insight II/March 2000

A References

The following are explicitly referenced in the Insight II program’s

printed or online documentation.

Arnott, S. and Hukins, D. W. L. “Optimised Parameters for A-

DNA B-DNA” Biochem. Biophys. Res. Comm., 47, 1504–1509
(1972).
Arnott, S.; Hukins, D. W. L.; and Dover, S. D. “Optimised Parame-
ters for RNA Double Helices” Biochem. Biophys. Res. Comm., 48,
1392–1399 (1972).
Arnott, S. and Selsing, E.; “Structures for the Polynucleotide Com-
plexes
Poly(dA).Poly(dT) and Poly(dT).Poly(dA).Poly(dT)” J. Molec.
Biol., 88, 509–521 (1974).
Baker, J. “An algorithm for the location of transition states”, J.
Comp. Chem., 7, 385 (1986).
Baker, J. “Geometry optimization in Cartesian coordinates: Con-
strained optimization”, J. Comp. Chem., 13, 240 (1992).
Baker, J. “Techniques for geometry optimization: A comparison of
Cartesian and natural internal coordinates”, J. Comp. Chem.,
14, 1085 (1993).
Baker, J.; Bergeron, D. “Constrained optimization in Cartesian
coordinates”, J. Comp. Chem., 14, 1339 (1993).
Baker, J.; Hehre, W. J. “Geometry optimization in Cartesian coordi-
nates: The end of the Z-matrix?”, J. Comp. Chem., 12, 606 (1991).
Banerjee, A.; Adams, N.; Simons, J.; Shepard, R. “Search for sta-
tionary points on surfaces”, J. Phys. Chem., 89, 52 (1985).
Besler, B. H.; Merz, K. M.; and Kollman, P.A. “Atomic Charges
Derived Semiempirical Methods” J. Comp. Chem Vol. 11, No. 4,
431-439 (1990).

Insight II/March 2000 389

A. References

Bracewell, R. N. “Numerical Transforms”, Science, 248, 679 (1990).

Császár, P.; Pulay, P. “Geometry optimization by direct inversion
in the iterative subspace”, J. Mol. Struct., 114, 31–34 (1984).
Fletcher, R. Practical Methods of Optimization, Vol. 2, Constrained
Optimization, John Wiley & Sons: New York (1981).
Fogarasi, G.; Zhou, X.; Taylor, P. W.; Pulay, P. “The calculation of ab
initio molecular geometries: Efficient optimization by natural
internal coordinates”, J. Amer. Chem. Soc., 114, 8191 (1992).
Hagler, A. T.; Osguthorpe, D. J.; Dauber-Osguthorpe, P.; and
Hemple, J. C. “Dynamics and Conformational Energetics of a
Peptide Hormone: Vasopressin”, Science 227, 1309–1315
(1985).
Hagler, A. T. and Moult, J. “Computer Simulation of the Solvent
Structure Around Biological Macromolecules”, Nature 272,
222–226 (1978).
Hagler, A. T.; Lifson, S.; and Dauber, P. “Consistent Force Field
Studies of Intermolecular Forces in Hydrogen Bonded Crys-
tals. II. A Benchmark for the Objective Comparison of Alterna-
tive Force Fields”, J. Amer. Chem. Soc. 101, 5122–5130 (1979a).
Hagler, A. T.; Dauber, P.; and Lifson, S. “Consistent Force Field
Studies of Intermolecular Forces in Hydrogen Bonded Crys-
tals. III. The C=O…H-O Hydrogen Bond and the Analysis of
the Energetics and Packing of Carboxylic Acids”, J. Amer.
Chem. Soc. 101, 5131–5141 (1979b).
Hagler, A. T.; Stern, P. S.; Sharon, R.; Becker, J. M.; and Naider, F.
“Computer Simulation of the Conformational Properties of
Oligopeptides. Comparison of Theoretical Methods and Anal-
ysis of Experimental Results”, J. Amer. Chem. Soc. 101, 6842–
6852 (1979c).
Hoyland, J.R.; “MINDO/2 Calculations on the Reaction of Methyl
Radicals with Ethylene and Butadiene”, Theor. Chim. Acta 22,
229-233 (1971).
Pattabiraman, N.; Levitt, M.; Ferrin, T. E.; and Langridge, R. “Com-
puter Graphics in Real-time Docking with Energy Calculation
and Minimization”, J. Comp. Chem., 6, 432–436 (1985).

390 Insight II/March 2000

Press, W. H.; Flannery, B. P.; Teukolsky, S. A.; and Vetterling, W. T.
in Numerical Recipes, The Art of Scientific Computing; Cam-
bridge: Cambridge University Press, (1986).
Pulay, P., “Improved SCF convergence acceleration”, J. Comp.
Chem., 3, 556 (1982).
Saenger, W. in Principles of Nucleic Acid Structures; New York:
Springer-Verlag, (1984).
Sessions, R. B.; Dauber-Osguthorpe, P.; and Dauber-Osguthorpe,
D. J. “Filtering Molecular Dynamics Trajectories to Reveal
Low Frequency Collective Motions: Phospholipase A2", J.
Molec. Biol., 210, 617 (1989).
Watson, J. D. in Molecular Biology of the Gene; Menlo Park, CA: W.
A. Benjamin, Inc., (1976).

Insight II/March 2000 391

A. References

392 Insight II/March 2000

B File Formats

The format of files that are used by more than a single Insight II
product are documented separately in the Insight II Products Com-
mon File Formats documentation.

Insight II/March 2000 393

B. File Formats

394 Insight II/March 2000

C Setting Up the Brookhaven PDB

For Use with Insight II Software

PDB Organization

Getting Brookhaven PDB database

Refer to the Biosym Products System Guide, chapter 4 or 5
(depending on your installation media) for information on how to
access the Brookhaven databank.

Coping with more than 8000 PDB files

The growth in the size of the Brookhaven Protein Data Bank (PDB)
has accelerated enormously over the last year. As of mid-1998 the
PDB, if copied to a hard disk without compression, requires about
four gigabytes of disk space. As explained in Appendix 9, Using
Compressed Files, Biosym’s software can now read compressed
PDB files (and other types of compressed files such as archive, psv,
grid files, etc.). The files must be compressed either with the stan-
dard UNIX compress command, or with the gzip program distrib-
uted by the Free Software Foundation. We recommend that you
use gzip to compress your PDB files as the compression ratio is
higher.

The Standard Brookhaven Directory Structure

Each CD from Brookhaven organizes the PDB entry files under a
directory named distr (short for distribution). The distr directory
contains many subdirectories, each of which has a two-character

Insight II/March 2000 395

C. Setting Up the Brookhaven PDB

name. Each such subdirectory contains all PDB files having those
two characters as the middle two of their four-character PDB iden-
tifiers. For example, the PDB entry 1crn can be found in the file
distr/cr/pdb1crn.ent.

Using a Representative Selection of PDB Files

For users who do not need access to the full PDB, an alternative is
to use only a representative sample of the PDB. Note that this strat-
egy is not adequate for most users of the Homology product.
A good representative selection can be found in the list described
in:
Hobohm U, Sander C (1994) Enlarged representative set of pro-
tein structures. Protein Sci 3:522-524
The latest version of this list can be obtained via anonymous ftp
from:
ftp.embl-heidelberg.de (192.54.41.33)
directory: /pub/databases/protein_extras/pdb_select
Another is the sample of PDB files collected by the PDB Users'
Group under the direction of professor Jane Richardson. It is part
of the Protein Science CDROM, which is available from Cam-
bridge University Press, 40 West 20th St., New York NY 10011-4211
USA. Order forms appear in the journal Protein Science. This list
of selected filenames is also available directly from Brookhaven's
anonymous ftp server at ftp.pdb.bnl.gov (internet address
130.199.144.1) in the user_group directory.

Installing the PDB for use with Insight II Software

Installing PDB Files

Biosym/MSI’s software now supports the standard Brookhaven
directory structure described in the preceding section. Most users
should find this new method simpler and more convenient. To use
this new method of organizing your PDB files, you must set the

396 Insight II/March 2000

 Installing the PDB for use with Insight II Software

environment variable INSIGHT_PDB to point to a directory that

contains one or more subdirectory trees that conform to the stan-
dard Brookhaven directory structure. This can be done at installa-
tion time (refer to the separate Biosym Products System Guide) or
included in your local .cshrc file or even from within the Insight II
program through the Session/Env_var command where you can
set environment variables. The distr subdirectories can occur at
any depth below INSIGHT_PDB, and there is no limit (other than
available disk space) to the number of distr subdirectory trees you
can have.
The pre-release 95.0 method of organizing your PDB files that
required all PDB files to be in a single directory is still supported
by Biosym/MSI’s software (see The Shell Script Utility: link_pdb on
page C–406), but dealing with more than 8000 files in a single
directory can be overwhelming. Furthermore, copying or linking
the files from the CDs into a single directory can be complicated.
If you wish, you can even use both organizing schemes, with some
of your PDB files in the INSIGHT_PDB directory itself and others
in two-character subdirectories under distr subdirectories.

Example of PDB setup for use with Biosym/MSI’s software

The following example describes a typical procedure for installing
the PDB for use by Biosym’s software. It assumes that only one
CDROM drive is available, that it is mounted on /cdrom, and that
disk space is limited. To minimize the use of disk space, only two
of the three Brookhaven CDs are copied onto the hard disk, and
those files are compressed using the gzip program. The third
Brookhaven CD is left in the CDROM drive, and its distr subdirec-
tory tree will be made to appear under INSIGHT_PDB by means
of a soft link.
In this example, the directory /usr/local/pdb will be used as the
INSIGHT_PDB directory. Here is the procedure:
1. Create the directory to which your environment variable
INSIGHT_PDB will point:

> mkdir /usr/local/pdb

> setenv INSIGHT_PDB /usr/local/pdb

Insight II/March 2000 397

C. Setting Up the Brookhaven PDB

2. Create one subdirectory under $INSIGHT_PDB for each distr

tree to be created:.

> cd $INSIGHT_PDB

3. Put the first Brookhaven CD into the CDROM drive. Copy the
files under the distr subdirectory onto the hard disk:

> cp -r /cdrom/distr $INSIGHT_PDB/pdb1

4. Compress the files just copied:

> gzip -r $INSIGHT_PDB/pdb1

5. Repeat steps 3 and 4, for each Brookhaven CD.

Note: you may use compress instead, if gzip is not installed at
your site. The gzip software can be obtained from the Free Soft-
ware Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
USA, or downloaded via ftp from the directory /pub/gnu/ at
prep.ai.mit.edu.
6. Add this definition of INSIGHT_PDB to your .cshrc file:

> setenv INSIGHT_PDB /usr/local/pdb

Note that this can also be done from within Insight II as well
through the Session/Env_Var command.
The -r (recursive) option used with the cp and gzip commands in
this example causes those commands to operate recursively on the
specified directory and all files and subdirectories within them.
These commands may take minutes or tens of minutes, depending
on the speed of your hardware, when used on thousands of PDB
files.
The gzip program is recommended for compression of PDB files
because of its superior compression algorithm and because it can
recursively compress all files in a directory tree with a single com-
mand. It compresses PDB files by a factor of about 3.8 on average.
See Appendix 9, Using Compressed Files for instructions on how to
obtain gzip.
If you do not have the gzip program, you can compress your PDB
files with the standard UNIX compress command. Unfortunately

398 Insight II/March 2000

 Installing the PDB for use with Insight II Software

it cannot compress recursively, so you must combine it with the

UNIX find command to compress all files in a subdirectory tree:

> find $INSIGHT_PDB -name “*.ent” -print -exec \

compress ‘{}’ ‘;’

Keep the INSIGHT_PDB Directory Clean

The directory pointed to by the environment variable INSIGHT_
PDB should not contain files other than PDB files or subdirectories
other than those containing distr subdirectory trees. This is impor-
tant because Biosym’s software uses a UNIX find command to find
all of the distr subdirectories. If you have superfluous files and
subdirectories under INSIGHT_PDB, the find command wastes
time searching them for distr subdirectories. This results in an
unnecessary delay the first time you try to read in a PDB file.
The UNIX find command is not executed for each retrieval of a
PDB file, but only for the first retrieval during a given execution of
a program. The locations of the distr directories are then stored
internally for subsequent retrievals of PDB files. They are dis-
carded, and another find command is executed, only if the envi-
ronment variable INSIGHT_PDB is changed while the software is
running.

IBM Workstations Warning: Do Not Use Soft Links to distr

Subdirectories
The find command discussed in the preceding section does not
traverse soft links on an IBM workstation. This is not a problem if
you copy and compress your PDB files as in the instructions begin-
ning at step 3 of the installation instructions above.
You should not, however, create a link from a distr subdirectory of
INSIGHT_PDB to the CDROM drive. The recommended proce-
dure, if you have enough disk space, is simply to copy and com-
press all of your PDB files onto the hard disk. If you do not have
enough disk space for this and must use the CDROM drive for part
of your PDB database, then you should mount the CDROM drive
directly on a subdirectory of INSIGHT_PDB.

Insight II/March 2000 399

C. Setting Up the Brookhaven PDB

Reading a PDB File into Insight II

Using the Molecule/Get Command

The Molecule/Get command can be used to read in a PDB file,
specified by its file name, as in previous releases. As described
above, the PDB files need not all be in one directory, but can
instead be in subdirectory trees that conform to the standard
Brookhaven PDB directory structure. All of these subdirectory
trees must be under the directory pointed to by the environment
variable INSIGHT_PDB. If your PDB files are organized in this
way, their names do not appear in the File Name value-aid when
the PDB Directory parameter is set to System. The Molecule/Get
command can still find any PDB file, however, if you simply type
its name into the File Name parameter.
For example, to read in crambin, enter pdb1crn.ent for the File
Name parameter. You can also enter the four-character PDB iden-
tifier code. For example, to read in crambin you can enter 1CRN
for the File Name parameter.

Using the File/Import Command

The File/Import command allows you to access PDB files not only
by filename, but also by four indexed attributes such as resolution,
author, source, and compound. This command requires specially
processed index files, which are generated by separate utility pro-
grams. The index files supplied with Biosym’s 95.0 release (pdb_
author.index, pdb_source.index, pdb_resolu.index, and pdb_com-
pound.index, all in the $BIOSYM/data/insight directory) were
generated from the April 1995 release 71 of the PDB. These index
files can be used with later versions of the PDB, but they obviously
do not contain entries for files added since April 1995. You should
therefore regenerate new index files when you install a new
release of the PDB, as explained in Creating New Index Files for the
File/Import Command on page C–401.
To read a PDB file using File/Import, select the Import command
from the File pulldown and select PDB from the File Format list.

400 Insight II/March 2000

 Reading a PDB File into Insight II

When the boolean parameter Search is ON, the parameter Search_

Criteria is active and the names of various PDB index files appear
in the value-aid. For example, to search for a file submitted by W.
B. Church, select pdb_author.index from the Index Files value-aid,
then select CHURCH W.B. from the Pattern List value-aid. The
name of the file then appears in the Files value-aid. Select the file-
name and then Execute the command.
To read a PDB file when you know its filename, turn the Search
parameter OFF. A Files value-aid appears, listing the PDB files in
your current directory. You can select one of these, or, to specify a
PDB file that is in the system directories (under $INSIGHT_PDB),
just type its name into the File_Name parameter and Execute the
command. Like the Molecule/Get command, File/Import can also
find the file even if you type only its four-character PDB identifier.

Creating New Index Files for the File/Import Command

A UNIX C-shell script, pdb_index_gen, exists in $BIOSYM/gifts/
insight that allows you to regenerate the Biosym-format PDB
index files used for searching PDB files with the File/Import com-
mand. Four index files derived from the April ’97 release of PDB
are installed in the 98.0 distribution tree, in the $BIOSYM/data/
insight directory.
To run this script, type at the UNIX prompt:

> $BIOSYM/gifts/insight/pdb_index_gen /cdrom1

where /cdrom1 points to a directory that contains one or more sub-

directory trees that conform to the standard Brookhaven directory.
This command as typed generates four index files named:
pdb_resolu.index
pdb_author.index
pdb_compound.index
pdb_source.index
using respectively the following Brookhaven index files: res-
olu.idx, author.idx, compound.idx, and source.idx. These newly

Insight II/March 2000 401

C. Setting Up the Brookhaven PDB

created files are read in when you start up Insight II from this local
directory.
If you would like to update the 98.0 release tree with these new
files, you need to copy them to the release tree. To do this, type:

> cp pdb_resolu.index $BIOSYM/data/insight

and so forth for each file. Note that you need to have write permis-
sion in the $BIOSYM/data/insight directory. Check with your sys-
tem administrator if you do not.
Should you wish to regenerate only one specific file out of the four,
you can do so by giving the -f argument to the script, as in:

> $BIOSYM/gifts/insight/pdb_index_gen /cdrom1 -f

resolu

As typed, this command only regenerates the pdb_resolu.index

file. The specifier -f accepts the following options:
resolu for the resolution index file
author for the author index file
compound for the compound index file
source for the source index file.

Protein Loop Search (Biopolymer and Homology

Modules)

Setting Up and Using the Protein Loop Search Commands

You can search a subset of the PDB for protein loops that match
structural criteria using either the Protein/SearchLoop command
in the Biopolymer module or the Loops/Search command in the
Homology module. In both cases, the search is done using a pre-
computed database of alpha carbon distance matrices from a
selected list of PDB files. The file of distance matrices is a binary
data file named pdb_ca_distance.dat.

402 Insight II/March 2000

 Protein Loop Search (Biopolymer and Homology Modules)

We have generated this file for you and installed it in the $BIO-
SYM/data/biopolymer directory of the current release distribu-
tion tree. This file was calculated from a subset of files in the April
1998 release of the PDB. The list of files used is in the file $BIO-
SYM/data/biopolymer/pdb_entry.dat. This list of entries is a
subset of the representative selection of PDB files created by
Hobohm and Sander (see Using a Representative Selection of PDB
Files on page C–396). It comprises all files in the “25% list”, from
Hobohm and Sander’s June 1998 version of their representative
selection. To use the loop search commands with this database,
you need to make sure that all of the PDB files listed in $BIOSYM/
data/biopolymer/pdb_entry.dat are accessible within or beneath
the directory pointed to by the environment variable INSIGHT_
PDB, as explained in Installing the PDB for use with Insight II Soft-
ware on page C–396.
You can skip the remainder of this section if you do not wish to
replace the database of alpha carbon distance matrices that we
have supplied.
If you wish to regenerate pdb_ca_distance.dat using a different list
of PDB entries, here are the steps to follow:
1. Create a selected list of high-resolution PDB files.
Create a text file containing the list of entries that you wish to
use for protein loop searches. A sample file resides in $BIO-
SYM/data/biopolymer/pdb_entry.dat. It simply lists the
names of the PDB files, one filename per line. If you wish, you
can list only the four-character PDB identifiers instead of the
complete filenames.
2. Make sure your PDB files are accessible to pdb_find_distance.
The program pdb_find_distance creates the distance matrix
file, and it requires that all the PDB files to be used for loop
searching be accessible within or beneath the directory pointed
to by the environment variable INSIGHT_PDB, as explained in
Installing PDB Files on page C–396.
3. At the UNIX prompt, run the pdb_find_distance utility pro-
gram by typing:

> pdb_find_distance filename

Insight II/March 2000 403

C. Setting Up the Brookhaven PDB

where filename is the name of the file (created in step 1) contain-

ing your list of PDB filenames. The program prompts you for
the name of the file if you do not type it on the command line.
The program writes on the screen the name of each PDB file it
has processed. When finished reading the files, it creates the
binary file pdb_ca_distance.dat. This file occupies about 18.9
MB of disk space when generated using the entries in $BIO-
SYM/data/biopolymer/pdb_entry.dat.
4. Place pdb_ca_distance.dat into the proper directory.
To do this, execute this UNIX command:

> mv pdb_ca_distance.dat $BIOSYM/data/biopolymer

Be sure you have the necessary privileges to create files in this

directory. You may need to log in as root to do this. If you do not
have permission to create files in this directory, or if you just
want temporarily to use a local version of pdb_ca_distance.dat,
you can make your local version accessible to the Biopolymer
and Homology modules by setting the environment variable
$BIOPOLYMER_DATA to the directory that contains your local
version of pdb_ca_distance.dat.

Sequence Database Searching (Homology

Module)

Seq_extract and the Sequence Database File pdb.seq

The sequence database searching capability of the Homology prod-
uct uses the FASTA algorithm to search for homologous
sequences. One sequence database file, pdb.seq, is provided for
you in the Homology gifts directory ($BIOSYM/gifts/homology).
It contains the amino acid sequences of all proteins in the October
1998 release of the PDB. It is already installed for use by the com-
mands in the Databases pulldown of the Homology module.
If you want to create a new pdb.seq from a different release of the
PDB, follow the instructions for seq_extract in Appendix D of the
Homology or Profiles-3D manual.

404 Insight II/March 2000

 3D Profiles Database (Profiles-3D Module)

In addition to pdb.seq, a variety of other protein and nucleic acid

sequence database files can be installed for use by the database
searching commands in the Homology and Profiles-3D products.
You must obtain these sequence database files from the sources
listed in the Biosym Products System Guide, under the section in
Chapter 3 titled Database Resources. If you download compressed
sequence database files from the Internet, be careful to avoid files
compressed on VMS computer systems. Although these files end
in .Z extensions, they are not in the same format as the .Z files cre-
ated by the UNIX compress command and cannot be used with
Biosym’s software.
To install additional sequence database files, follow the proce-
dures explained in the Insight II Products System Guide, under the
section entitled Install Sequence Database Searching Software for
Homology and Profiles-3D.

3D Profiles Database (Profiles-3D Module)

Create_Profiles and the Database of 3D Profiles

Biosym includes a precalculated database of 3D profiles for use
with the Find Structures command of the Profiles-3D product.
These files are stored in the directory $BIOSYM/data/profiles_
3d/database. These were derived from the representative selec-
tion of PDB files created by Hobohm and Sander (June 1998, 25%
list). A complete set of profiles derived from the October 1998 PDB
release is in $BIOSYM/gifts/profiles_3d/. You can update the
database of 3D profiles using the Create_Profiles command of the
Profiles-3D product. If you want to use a database of profiles in a
location other than $BIOSYM/data/profiles_3d/database, you
must set the environment variable PROFILE_DATA to the path-
name of the directory that contains the profiles.

Insight II/March 2000 405

C. Setting Up the Brookhaven PDB

The Shell Script Utility: link_pdb

The purpose of the script link_pdb is to make PDB files on the
CDROM drive accessible to any software that requires that all the
PDB files be in one directory. Biosym’s software no longer requires
this, and we recommend that you use the standard Brookhaven
directory structure instead.
The UNIX C-shell script link_pdb creates links from your current
working directory to Brookhaven PDB data files on your CDROM
drive. It can also copy the files themselves from the many subdi-
rectories on the CD into a single directory on your hard disk.
A UNIX link can be used as if it were a real file. In fact, a link is a
pointer to a file in a different location. Link_pdb creates links in a
single directory (your current working directory) that point to
PDB files in many different subdirectories (such as the ones on the
Brookhaven CD). The advantage of doing this is that it saves con-
siderable space on your hard disk and eliminates the effort
involved in copying the files from the CDROM drive. The disad-
vantage is that reading the files is slower. As of April 1995, the
complete PDB fills three CDs. If you want to access all of these
through links, you will need three CDROM drives. Alternatively,
if you only have one CDROM drive, you can copy all the files from
two CDs, and then put the remaining CD into the CDROM drive
and create links for it. You can use link_pdb with its -copy option
to copy the files from the first two CDs.
To use link_pdb, you must first go to the directory in which you
want to create the links. Then just type link_pdb at the UNIX
prompt, followed by the name of the directory on which your
CDROM drive is mounted. For example, if your CDROM is
mounted on /cdrom, you would type:

> link_pdb /cdrom

The links remain on your hard disk even if you remove the CD
from the CDROM drive. If you try to read a PDB file when the CD
is not in the drive, Insight II gives you an error message indicating
that it cannot open the file. When you put the CD back in, the files
are again readable.

406 Insight II/March 2000

 The Shell Script Utility: link_pdb

If you have three CDROM drives mounted on /cdrom1, /cdrom2,

and /cdrom3, you can put the Brookhaven CDs into them and
make links for all of them at once:

> link_pdb /cdrom1 /cdrom2 /cdrom3

If you have enough disk space, you can also use this command to
copy the files themselves onto your hard disk, rather than making
links. This is useful if you want to copy the first two CDs and make
links to the third. To do this you must specify the option -copy on
the command line. The full procedure to copy two CDs and link
the third is:
1. cd to the directory that will contain your PDB files and links.
This is the directory that your environment variable INSIGHT_
PDB points to.
2. Put the first Brookhaven CD into the CDROM drive.
3. Type this command at the UNIX command prompt:

> link_pdb -copy /cdrom

4. Put the second Brookhaven CD into the CDROM drive.

5. Type this command at the UNIX command prompt:

> link_pdb -copy /cdrom

6. Put the third Brookhaven CD into the CDROM drive.

7. Type this command at the UNIX command prompt:

> link_pdb /cdrom

If you do not have enough space on your hard disk to copy the files
from the first two CDs, use the same procedure described above
but omit the -copy options from the first two link_pdb command
lines. You then have links for all the PDB files pointing to the
CDROM drive. Since only one CD can be in the CDROM drive at
any one time, those files on the other two CDs appear to be present
but are unreadable. If you try to access one of them via Molecule/
Get, Insight II gives you an error message indicating that the file
cannot be read. You must then change CDs and try to read the file
again. This approach may require frequent changing of the CDs,
and is therefore inconvenient, but it does give you access to all of

Insight II/March 2000 407

C. Setting Up the Brookhaven PDB

the latest PDB files. Note that if you set up your PDB directory in
this way, you cannot run the pdb_find_distance utility, unless all
of the files in pdb_entry.dat are first copied into your INSIGHT_
PDB directory (see Setting Up and Using the Protein Loop Search
Commands on page C–402).
Link_pdb can also be used to update your links or copies each time
you get a new release of the PDB. To do this, just run link_pdb in
the directory that contains your old links or copies. Link_pdb
always replaces old copies with new ones. It replaces an old link
with a new one only if the old link does not point to a valid loca-
tion in the new PDB release. If an old link points to a file that has
become obsolete (and therefore is not present in the latest PDB
release), link_pdb does not delete the old link. Obsolete files there-
fore appear to be present but are unreadable. To be sure to elimi-
nate these obsolete links, you must first delete all of your old links
before creating new ones for your new PDB release. The easiest
way to do this is to delete your PDB directory and its contents with
the recursive remove command:

> rm -r pdb_directory

You must then recreate your pdb directory, cd into it, and run link_
pdb to create the new links. Be sure the environment variable
INSIGHT_PDB points to the directory containing the links.

408 Insight II/March 2000

D Fragment Definitions

Following are the contents of the Insight II help file

named frags.def. Each entry in this file is comprised
of five columns of data.
1. An up-to-4-letter descriptor that is used as the
fragment’s lookup key.
2. A 1-letter descriptor of the fragment type:
blank = amino acid (fragment)
H = hydrocarbon (fragment)
G = functional group (fragment)
A = atom (fragment)
U = user library fragment (fragment)
R = ring library fragment, etc. (fragment)
V = vinyls (repeat unit)
O = olefins (repeat unit)
I = rings (repeat unit)
D = dienes (repeat unit)
E = heteroatom (repeat unit)
0 = RNA-DNA base fragment
1 = A RNA single strand fragment
2 = A RNA double strand fragment
4 = A DNA single strand fragment
5 = A DNA double strand fragment
6 = A DNA triple strand fragment
7 = B DNA single strand fragment
8 = B DNA double strand fragment
9 = Z DNA double strand fragment
b = A RNA-DNA hybrid fragment
t = RNA, DNA terminal group fragment
S = repeat_unit user fragment (and carbohy-
drates)

Note that when you add to this file, you may use
any of the defined
Insightdescriptors
II/Marchto2000
identify a new
409
fragment. Note also that the relative ordering of
the entries for each class of fragment determines
D. Fragment Definitions

3. A molecule descriptor (of up to 8 characters) that

appears under the object on the display.
4. A descriptor to designate the forward hydrogen in
the fragment to be used during chain-building op-
erations. This is necessary for fragments able to
form chains (using the Repeat command in the
Residue pulldown) but is optional if the fragment
will not be used in a chain (use an arbitrary hydro-
gen).
5. A descriptor to designate the backward hydrogen
in the fragment to be used during chain-building
operations. This is necessary for fragments able to
form chains (using the Repeat command) but is
optional if the fragment will not be used in a chain
(use an arbitrary hydrogen). Note that when mol-
ecules are built using the Repeat command, the
forward and backward hydrogens are used for
fragment alignment, and are then deleted.
Key Type Description For-
wardBackward
Hydro-
genHydrogen
ALA Alanine HN2HC
ARG Arginine HN2HC
ASP AspAcid HN2HC
ASN Aspagine HN2HC
CYS Cysteine HN2HC
GLU GlutAcid HN2HC
GLN Glutamin HN2HC
GLY Glycine HN1HC
HIS Histidin HN2HC
ILE Isoleuc HN1HC
LEU Leucine HN1HC
LYS Lysine HN2HC
MET Methion HN2HC
PHE Phenalan HN2HC
PRO Proline HNHC
SER Serine HN2HC
THR Threonin HN2HC
TRP Tryptphn HN2HC

410 Insight II/March 2000

TYR Tyrosine HN2HC
VAL Valine HN2HC
ASPM Aspartic- HN2HC
ARGP Arginine+ HN2HC
LYSP Lysine+ HN2HC
HISD HistidineD HN2HC
HISP Histidine+ HN2HC
GLUM Glutamic- HN2HC
DPRO Dproline HNHC
AIB AIB HN1HC
PGLU pyroglu HNHC
ACE acetyl HA1HC
NM nmethyl HN1HA1
Key Type Description For-
wardBackward
Hydro-
genHydrogen
OH Hyrdoxyl H1H2
NH2 NH2group HN1HN2
CH3 CH3group HC1HC2
CSP3 A C(SP3) HN1HC
CSP2 A C(SP2) HN1HC
CSP A C(SP) HN1HC
CAR A C(Arom) HN1HC
NSP3 A N(SP3) HN1HC
AMDE A N(Amide) HN1HC
NSP2 A N(SP2) HN1HC
NAR A N(Arom) HN1HC
NP3P A N+(SP3) HN1HC
NP2P A N+(SP2) HN1HC
NSPP A N+(SP) HN1HC
NARP A N+(Arom) HN1HC
OSP3 A O(SP3) H12H11
PSP3 A P(SP3) HN1HC
PSP2 A P(SP2) HN1HC
P5V A P(5BOND) HN1HC
SSP3 A S(SP3) HN1HC
SP3P A S+(SP3) HN1HC
ALHD G Aldehyde HN1HC
BCBN G B-Carbyl HN1HC
OHH G Hydroxy H12H11
AMIN G Amine HN1HC

Insight II/March 2000 411

D. Fragment Definitions

AMID G Amide HN1HC

AMN4 G QuatAmin HN1HC
AZO G Azo HN1HC
ACDN G AcAnhydr HN1HC
CBXA G CarboxAc HN1HC
CBXM G Crbxlate HN1HC
DAZP G Diazo+ HN1HC
GCRL G Glycerol HN1HC
GYCO G Glycol HN1HC
HDAZ G Hydrazon HN1HC
MTXY G Methoxy HN1HC
NTRL G Nitrile HN1HC
NTRO G Nitro HN1HC
NTSO G Nitroso HN1HC
OXIM G Oxime HN1HC
PROX G PerOxide HN1HC
PHOS G Phosph HN1HC
SLFA G SulfAcid HN1HC
SLMD G SulfAmid HN1HC
Key Type Description For-
wardBackward
Hydro-
genHydrogen
SFCL G SulfCl HN1HC
SLFS G SulfEstr HN1HC
ACCL G AcidCl HN1HC
METH H Methyl HN1HC
ETHL H Ethyl HN1HC
ETEN H Ethylene HN1HC
PROP H Propyl HN1HC
PRPN H Propylen HN1HC
BUTL H Butyl HN1HC
TBTL H T-Butyl HN1HC
C2BN H C2Butene HN1HC
T2BN H T2Butene HN1HC
IBTN H Isobuten HN1HC
BTDN H Butadie HN1HC
ALKN H Alkyne HN1HC
ALLN H Allene HN1HC
CYPD R Cyptdien HN1HC
PYRO R Pyrrole HN1HC
CYHX R Cyhexane HN1HC

412 Insight II/March 2000

BENZ R Benzene HN1HC
INDO R Indole HN1HC
NAPH R Naphlene HN1HC
ANTH R Anthcene HN1HC
PHAN R Phenanth HN1HC
PHDN R Phenanrd HN1HC
NPCN R Naphcene HN1HC
BZAN R Benzancn HN1HC
CRYN R Chrysene HN1HC
PYEN R Pyrene HN1HC
TRPH R Triphyln HN1HC
PORN R Porphin HN1HC
TOLN R Toluene HN1HC
NTMD R NictnAmd HN1HC
CYTO R Cytosine HN1HC
TYMN R Thymine HN1HC
VICL V VinylCl H12H21
DCLE V dClEth H12H2
VIF V VinylF H12H21
DFE V dFluoEth HC1H1
TFE V tFluoEth HCH1
VALC V VinylAlc H12H21
VAMD V VinylAm H4H1
VACE V VinylAce H5H7
VIET V VinEther H12H21
Key Type Description For-
wardBackward
Hydro-
genHydrogen
ACAC V AcrylAc HC3H12
MA V MethyAcr HC3H12
MMA V MMethac HC3H1
ACNI V AcrylNit HC2H11
STYR V Styrene H72H61
AMST V aMethSty H72H6
ETHE O Ethylene H12H22
PREN O Proplene H11H21
IBEN O Isobutl H13H2
BUTE O 1Butene H11H21
PHE1 I pPhenyl H6H3
PHE2 I mPhenyl H1H3
PHEO I pPhenOx H6HO

Insight II/March 2000 413

D. Fragment Definitions

XYLY I pXylylen H73H63

PYR I Pyrrole H3H1
PHDA I PhenDiam H4HN3
PHBN I pHydbenzo H9H2
BIMD I Benzimid H6H3
PBAM I pBenzAmid H12H1
ETTE I EtTerep H3H13
PHOX I Phenoxy H5H15
CARB I Carbonat H5H2
DI2 D TrButaDi H12H43
DI1 D CisButaD HC1H33
DI3 D 12ButaDi H33H21
DIC2 D TrNeopr H12H43
DIC1 D CisNeopr HC1H33
DIM2 D TrIsopr HC2H33
DIM1 D CisIsopr H33H43
DMBD D DMethBut H52H43
HDI1 D 14HexaDi HC1H11
OMET E OxyMeth H13HO
OET E OxyEth H13HO
OPRO E OxyProp H3HO5
DMS E DimethSi HSIH1
MPS E MePhensi HSIHO
UREA E Urea HN2H11
ETUR E EtUreth HN1H23
NYL6 E Nylon6 HC3H12
ADE 0 Adenine HN9HC
CYT 0 Cytosine HN1HC
GUA 0 Guanine HN9HC
THY 0 Thymine HN1HC
URA 0 Uracil HN1HC
Key Type Description For-
wardBackward
Hydro-
genHydrogen
ARA1 1 ARNA_A HO3’HP
ARC1 1 ARNA_C HO3’HP
ARG1 1 ARNA_G HO3’HP
ARU1 1 ARNA_U HO3’HP
ARAU 2 ARNA_AU HO3’HP
ARCG 2 ARNA_CG HO3’HP
ARGC 2 ARNA_GC HO3’HP

414 Insight II/March 2000

ARUA 2 ARNA_UA HO3’HP
ADA1 4 ADNA_A HO3’HP
ADC1 4 ADNA_C HO3’HP
ADG1 4 ADNA_G HO3’HP
ADT1 4 ADNA_T HO3’HP
ADAT 5 ADNA_AT HO3’HP
ADCG 5 ADNA_CG HO3’HP
ADGC 5 ADNA_GC HO3’HP
ADTA 5 ADNA_TA HO3’HP
D3AT 6 ADNA_ATT HO3’HP
BDA1 7 BDNA_A HO3HP
BDC1 7 BDNA_C HO3’HP
BDG1 7 BDNA_G HO3’HP
BDT1 7 BDNA_T HO3’HP
BDAT 8 BDNA_AT HO3’HP
BDCG 8 BDNA_CG HO3’HP
BDGC 8 BDNA_GC HO3’HP
BDTA 8 BDNA_TA HO3’HP
ZDCG 9 ZDCG_CG HO3’HP
ZDGC 9 ZDGC_GC HO3’HP
DRAU b ADRNA_AU HO3’HP
DRCG b ADRNA_CG HO3’HP
DRGC b ADRNA_GC HO3’HP
DRTA b ADRNA_TA HO3’HP
RDAT b ARDNA_AT HO3’HP
RDCG b ARDNA_CG HO3’HP
RDGC b ARDNA_GC HO3’HP
RDUA b ARDNA_UA HO3’HP
HBNA t H5_TERM HBHB
HENA t H3_TERM HEHE
POM t PO2_TERM HBHB

Insight II/March 2000 415

D. Fragment Definitions

416 Insight II/March 2000

E Hydrogen Bonds

Following are the contents of the Insight II template

file named hbond_file.dat. This file contains the atoms
considered in hydrogen bonding. The first line defines
the default minimum angle. For example:
Angle: 120.0.

The five columns are:

1. Name of the monomer/residue in which the fol-
lowing donor atom is found (an asterisk denotes
all monomers/residues).
2. Name of the donor atom (a letter followed by an
asterisk denotes any match on the letters following
the first).
3. Name of the monomer/residue in which the fol-
lowing acceptor atom is found.
4. Name of the acceptor atom.
5. Maximum distance the two atoms can be apart to
be considered hydrogen bonded (in angstroms).
Note that heavy atoms with no hydrogens which could
be involved in hydrogen bonding are included by
specifying the minimum distance for the two heavy
atoms.

Monomer/ Donor Monomer/

AcceptorHydrogen
Residue Name Residue
NameBonding
Name Name
Distance
* H* * N*
2.5

Insight II/March 2000 417

E. Hydrogen Bonds

* H* * O*
2.5
* H* * S*
2.5
* N* * O*
3.0
* N* * S*
3.7
* O* * O*
3.0

418 Insight II/March 2000

F Space Group Names

Note that these follow standard naming conventions, with the exceptions that:
21 becomes 21
and:
1 becomes 1b

1 (P 1) 2)
2 (P 1b) 24 (I 21
3 (P 2) 21 21)
4 (P 21) 25 (P m m
5 (C 2) 2)
6 (P m) 26 (P m c
7 (P c) 21)
8 (C m) 27 (P c c
9 (C c) 2)
10 (P 2/m) 28 (P m a
11 (P 21/ 2)
m) 29 (P c a
12 (C 2/m) 21)
13 (P 2/c) 30 (P n c
14 (P 21/ 2)
c) 31 (P m n
15 (C 2/c) 21)
16 (P 2 2 32 (P b a
2) 2)
17 (P 2 2 33 (P n a
21) 21)
18 (P 21 34 (P n n
21 2) 2)
19 (P 21 35 (C m m
21 21) 2)
20 (C 2 2 36 (C m c
21) 21)
21 (C 2 2 37 (C c c
2) Insight II/March 2000
2) 419
22 (F 2 2 38 (A m m
2) 2)
F. Space Group Names

2) n m a)
40 (A 63 (C m c
m a 2) 64 (C m c
41 (A 65 (C m m
b a 2) 66 (C c c
42 (F 67 (C m m
m m 2) 68 (C c c
43 (F 69 (F m m
d d 2) 70 (F d d
44 (I 71 (I m m
m m 2) 72 (I b a
45 (I 73 (I b c
b a 2) 74 (I m m
46 (I 75 (P 4)
m a 2) 76 (P 41)
47 (P 77 (P 42)
m m m) 78 (P 43)
48 (P 79 (I 4)
n n n) 80 (I 41)
49 (P 81 (P 4b)
c c m) 82 (I 4b)
50 (P 83 (P 4/m
b a n) 84 (P 42/
51 (P 85 (P 4/n
m m a) 86 (P 42/
52 (P 87 (I 4/m
n n a) 88 (I 41/
53 (P 89 (P 4 2
m n a) 90 (P 4 2
54 (P 91 (P 41
c c a) 92 (P 41
55 (P 93 (P 42
b a m) 94 (P 42
56 (P 95 (P 43
c c n) 96 (P 43
57 (P 97 (I 4 2
b c m) 98 (I 41
58 (P 99 (P 4 m
n n m) 100 (P 4 b
59 (P 101 (P 42
m m n) 102 (P 42
420 Insight II/March 2000 60 (P 103 (P 4 c
b c n) 104 (P 4 n
61 (P 105 (P 42
108 (I 4 c m) 156
109 (I 41 m d) (P 3 m
110 (I 41 c d) 1)
111 (P 4b 2 m) 157
112 (P 4b 2 c) (P 3 1
113 (P 4b 21 m) m)
114 (P 4b 21 c) 158
115 (P 4b m 2) (P 3 c
116 (P 4b c 2) 1)
117 (P 4b b 2) 159
118 (P 4b n 2) (P 3 1
119 (I 4b m 2) c)
120 (I 4b c 2) 160
121 (I 4b 2 m) (R 3
122 (I 4b 2 d) m)
123 (P 4/m m m) 161
124 (P 4/m c c) (R 3
125 (P 4/n b m) c)
126 (P 4/n n c) 162
127 (P 4/m b m) (P 3b
128 (P 4/m n c) 1 m)
129 (P 4/n m m) 163
130 (P 4/n c c) (P 3b
131 (P 42/m m c) 1 c)
132 (P 42/m c m) 164
133 (P 42/n b c) (P 3b
134 (P 42/n n m) m 1)
135 (P 42/m b c) 165
136 (P 42/m n m) (P 3b
137 (P 42/n m c) c 1)
138 (P 42/n c m) 166
139 (I 4/m m m) (R 3b
140 (I 4/m c m) m)
141 (I 41/a m d) 167
142 (I 41/a c d) (R 3b
143 (P 3) c)
144 (P 31) 168
145 (P 32) (P 6)
146 (R 3) 169
147 (P 3b) (P 61)
148 (R 3b) 170
149 (P 3 1 2) (P 65)
150 (P 3 2 1) 171
151 (P 31 1 2) Insight II/March 2000 (P
42162)
152 (P 31 2 1) 172
F. Space Group Names

174 (P 6b)
175 (P 6/m)
176 (P 63/m)
177 (P 6 2 2)
178 (P 61 2 2)
179 (P 65 2 2)
180 (P 62 2 2)
181 (P 64 2 2)
182 (P 63 2 2)
183 (P 6 m m)
184 (P 6 c c)
185 (P 63 c m)
186 (P 63 m c)
187 (P 6b m 2)
188 (P 6b c 2)
189 (P 6b 2 m)
190 (P 6b 2 c)
191 (P 6/m m m)
192 (P 6/m c c)
193 (P 63/m c m)
194 (P 63/m m c)
195 (P 2 3)
196 (F 2 3)
197 (I 2 3)
198 (P 21 3)
199 (I 21 3)
200 (P m 3b)
201 (P n 3b)
202 (F m 3b)
203 (F d 3b)
204 (I m 3b)
205 (P a 3b)
206 (I a 3b)
207 (P 4 3 2)
208 (P 42 3 2)
209 (F 4 3 2)
210 (F 41 3 2)
211 (I 4 3 2)
212 (P 43 3 2)
213 (P 41 3 2)
214 (I 41 3 2)
215 (P 4b 3 m)
216 (F 4b 3 m)

422 Insight II/March 2000

217 (I 4b 3 m)
218 (P 4b 3 n)
219 (F 4b 3 c)
220 (I 4b 3 d)
221 (P m 3b m)
222 (P n 3b n)
223 (P m 3b n)
224 (P n 3b m)
225 (F m 3b m)
226 (F m 3b c)
227 (F d 3b m)
228 (F d 3b c)
229 (I m 3b m)
230 (I a 3b d)

Insight II/March 2000 423

F. Space Group Names

424 Insight II/March 2000

G Potential Template Rules

The potential type template file is used for the

assignment of potential atom types to the atoms of a
molecule. It consists of one or more potential type
templates, followed by a precedence tree. The potential
type templates describe the connectivity and other
properties that an atom must have in order to be
assigned a particular potential type. The precedence
tree describes the relative priorities of the potential
types, and is used for deciding which type to assign in
the case of multiple template matches. Any line whose
first character is an exclamation point (!) is a comment.
Comments may appear anywhere in the file. The
environment variable INSIGHT_POTENTIAL_
TEMPLATES indicates which potential file in the
BIOSYM_LIBRARY directory is to be used. If
INSIGHT_POTENTIAL_TEMPLATES is undefined,
the old hard-coded assignment rules are used.
Note that in the definitions throughout this chapter,
parentheses are used to distinguish separate levels of
precedence. Each left parenthesis indicates the next
lower level of precedence. Each right parenthesis ends
the level begun by the preceding left parenthesis.

Potential Type Template

Each potential type template is of the following form:
type:ccc
template:(>....)
[optional atom tests]
end_type
where ccc is the 1-to-3 letter potential type name, the
template is the description of the surrounding chemical
environment of atoms receiving this potential type, and
the tests are a way to refine the description of this
environment.

Insight II/March 2000 425

G. Potential Template Rules

The template is a SMILES-like string describing the

bonded atoms and bond orders that must be
encountered in the search outward from the atom in
question. The first atom is always the one being
assigned a potential, and is preceded by the special
character >. All bonded substructures are enclosed in
parentheses or brackets, and begin with a bond order
character from the following set:
- = single bond
: = partial double bond
= = double bond
# = triple bond
~ = wildcard bond (matches any bond order)
Atoms are indicated by their chemical symbol, and the
special symbol * is used to indicate a match with any
element. Any substructure can in turn have nested
substructures. This can continue as deep as necessary
to uniquely identify the atom’s environment. Spaces
can be used in the template to increase readability.

Example:
The template (>C (=O) (-O(-H)) (-*)) describes the
carbon in the following group:
anything
/
O=C
\
O-H
The closing parenthesis for an atom does not indicate
that there may not be any more bonds out of the atom,
only that no further specific bonds are required for a
match. Thus the template (>N) matches any nitrogen,
no matter what its bonded neighbors are.
Brackets around an atom are used when you wish to
indicate that the connectivity must match the template
exactly. Thus the template [>Ca] can be used for ionic
calcium, and will not match a calcium with atoms
bonded to it. When an atom with substructures is
bracketed, it is only that atom, not all the substructures,
which is limited in its connectivity.

426 Insight II/March 2000

 Potential Type Template

Example:
The template (>C[:N(-*)]) matches a carbon in the
following groups:
H
C N
H

C H
C N
H
but not:
H
C N

H
Note that for the matching to work correctly the
subtrees at any level must be ordered from most
specific to most general. This prevents an atom that is
necessary for a specific subtree match from being
incorrectly paired with an earlier wildcard.

Example:
(-N(-H)(-C)) before (-N(-H)(-*)) before (-N) before (-
*)

Atom Tests
Atom tests are used to refine the matching criteria by
placing further restrictions on the atoms being
matched. Each test refers to an atom in the template,
using the order in which it appears in the template. The
atom tests are of the following form:
atom_test:x
.
.
tests
.
.
end_test

Insight II/March 2000 427

G. Potential Template Rules

where x is the atom number in the template, for

example 3 for the second oxygen in the template
(>C(=O)(-O(-H))). The atom_test section for a
particular atom can contain one or more tests from the
set described below. The only test type that is allowed
to occur multiple times is the ring test.

Element Test
The element test allows you to specify which elements
are permitted or not permitted at this location in the
template. Using element tests only makes sense for
template atoms of the wildcard (*) type. It has two
forms:
allowed_atoms: ..list..
and
disallowed_atoms: ..list..
In both cases, the list is a list of atomic symbols (i.e., C,
Si, Br, H) separated by commas indicating which
elements are allowed or disallowed.

Hybridization Test
The hybridization test allows you to specify what
hybridization state(s) an atom may have and still match
the atom in the template. The form is:
hybridization: ..list..
where the list is a comma-separated list of
hybridization types from among sp, sp2, sp3.

Aromaticity Test
This test allows specification of whether the atom is to
be aromatic or not. Its form is:
aromaticity: aromatic
or:
aromaticity: non_aromatic

428 Insight II/March 2000

 Precedence Tree

Ring Test
The ring test allows you specify ring size and ring
geometry requirements for the atom. Either the size or
geometry requirement can be wildcarded to indicate
that that property of the ring is not constrained. The
form of the ring test is:
ring: geometry(size)
where geometry is planar, non_planar, or *. The size is
an integer or the wildcard *.

Precedence Tree
The precedence tree is used to indicate which potential
types have priority over others in the case of multiple
template matches for a given atom. It is specified using
the same nested parenthetical style as the templates. To
properly resolve the precedence between a number of
matches there must be a path down from the root of the
tree (? in the example below) which contains all the
matches. The final potential type in this path will have
the highest precedence and be assigned. For example,
in the tree below there is a path that contains the
following set of matches: '', c', c=, and so an atom
matching these three types would be assigned c=.
However, if c1 were also matched for that atom, no
single path could contain the whole set of matches and
Insight II would report an error about being unable to
resolve the precedence. Notice that the path containing
the matches does not have to go all the way to the
lowest level of the tree, it must simply be a continuous
path starting at the root and containing all the matches.
The simple precedence tree (?(h?(hc))(c?(c1(c2))(c=)))
represents the following precedence relationships:

Insight II/March 2000 429

G. Potential Template Rules

?
/ \
h? c? Increasi
Priority
/ / \
hc c= c1
\ \
c2
Note that the ordering of the subtrees is unim
It is the order as you descend down a path in
that defines the precedence. Thus the simpl
(?(Br)(br)(Si)) and (?(Si)(br)(Br)) are equiv
and indicate the same precedence for Br, br
However, the tree (?(Br(br))(Si)) indicates th
potential takes precedence over Br if both a
matched.
The format of the precedence tree section is
precedence:
.
.
tree
.
.
end_precedence
The actual tree can be broken into multiple li
punctuated with spaces and comments for
readability.

Examples of Potential Assignment for a Small Set of

Potential Types
Suppose we have the following simple set o
eters to assign:
h generic hydrogen parame
hc hydrogen bonded to carbo
h* hydrogen in water
c sp3 carbon
c2 sp3 carbon with 2 hydrog
heavy atoms
c= non-aromatic double bond
430 Insight II/March 2000 carbon
o generic oxygen parameter
 Precedence Tree

The rules for these parameters would be as follows:

type: h
template: (>H)
! Matches any hydrogen
end_type

type: hc
template: (>H(-C))
! Matches a hydrogen single bonded to a car-
bon. No
! restriction on what may be bonded to the
carbon.
end_type

type: h*
template: (>H[-O(-H)])
! Matches a hydrogen single bonded to an ox-
ygen which
! in turn has a hydrogen bonded to it. The
brackets
! around the OH prevent matches in the un-
likely
! situation of a charged oxygen which hap-
pens to have
! two hydrogens. With the brackets present
the oxygen
! must have only the bonds specified.
end_type

type: c
template: (>C)
atom_test: 1
hybridization: sp3
end_test
! The template matches any carbon. The atom
test is
! applied to atom 1 (in this case the only atom)
of
! the template string and restricts the match to
only
! sp3 carbons.
end_type

type: c2
template: (>C(-H)(-H)(-*)(-*))

Insight II/March 2000 431

G. Potential Template Rules

! Matches a carbon with 4 single bonds, two

of which
! are to hydrogens. No hybridization test was
felt
! necessary since a carbon with 4 single bonds
is always
! sp3 to insightII. Note that the hydrogen sub-
structures
! appear before the wildcard substructures.
This
! prevents a hydrogen from being used for the
wildcard
! match and hence not being available for the
more specific
! substructure match.
end_type

type: c=
template: (>C(=*))
atom_test: 1
aromaticity: NON_AROMATIC
hybridization: sp2
end_test
! The template will match any carbon with a
double bond.
! To prevent matches to carbons in aromatic
rings there
! is an aromaticity test on the first atom of the
template (the
! carbon). The hybridization test somewhat
redundantly specifies
! that the carbon must be SP2.
end_type

type: o
template: (>O)
! Matches any oxygen
end_type

type: ?
template: (>*)
! Matches anything
end_type
The precedence tree for this small set of parameters
would be:

432 Insight II/March 2000

 Precedence Tree

precedence:
(? (h(hc)(h*)) (c(c2)) (c=) (o) )
end_precedence
Graphically this looks like:
____?____

/ / \ \

h c c= o

/ \ |

hc h* c2

Where the lower you go in the tree, the greater the

precedence. Thus if an atom matches the ?, h, and h*
types, then it is assigned the h* potential. In this
manner you can insure that the most appropriate
potential type out of all that were matched is assigned.

Examples of Potential Assignments Using These Types

H

C=O aldehyde

The hydrogens in this molecule match the ?, h, and hc

types. Since hc has the highest precedence of this set of
matches, it is assigned to the hydrogens. The carbon
matches only the c= and ? types; the hybridization test
prevents a match with the c template. Since c= has a
higher precedence than ?, the carbon is assigned c=.
Similarly, the oxygen matches o and ?, and is assigned
o.
Example of unmatched atom:
C---C

// \\

C C benzene

\ /

Insight II/March 2000 433

G. Potential Template Rules

C===C

The simple set of parameters described so far does not

do a good job on this aromatic ring. The c parameter is
not matched because the carbons are not SP3, the c=
rule fails because the carbons are aromatic, and we do
not even get a match with the template in the c2 rule.
The only match is ?, and this is what is assigned to the
carbons of the aromatic ring.

Adding A New Parameter Type

One way to handle the case above is to add a new
parameter for SP2 carbons. For example, call such a
rule cp. Once the new parameter is added to the
forcefield we want add to the potential assignment
rules so that the new parameter are assigned to the
appropriate atoms. The new rule will be:

type: cp
template: (>C)
atom_test: 1
hybridization: sp2
end_test
end_type

We also need to add this type into the precedence tree.

At first glance it might seem it should just go below ?:
precedence:
(? (h(hc)(h*)) (c(c2)) (c=) (cp) (o) )
end_precedence
The graphical representation of this is:
____?________

/ / \ \ \

h c c= o cp

/ \ |

hc h* c2

However if we go back and look at the aldehyde case

we see that this presents a problem. The carbon will
still match ? and c=, but now it will also match cp and
there is no single path in the precedence tree that
contains all three matches, and hence no way for

434 Insight II/March 2000

 cvff_templates.dat

Insight II to figure out which of the potentials has

highest precedence. The cp type will be matched any
time the c= type is matched because it is just a more
general (no aromaticity test) version of the c= rule.
This means that we can resolve the precedence conflict
by putting c= under cp:
precedence:
(? (h(hc)(h*)) (c(c2)) (cp(c=)) (o) )
end_precedence
The graphical representation of this is:
____?____

/ / \ \

h c cp o

/ \ | |

hc h* c2 c=

cvff_templates.dat
The following is a sample potential type template file
that does potential type assignment for the cvff.frc
library.

! cvff_templates.dat
! Template file of potential type assignment tem-
plates for the cvff
! forcefield
!
! Revision History:
! KWC 6/5/90 Initial version without ci and
ni types
! DWS 8/13/90 Fixes for beta bugs, addition
of ci,ni
! KWC 8/16/90 added o- templates for carbox-
ylate oxygens,
! changed precedence for Cl/cl
since brackets
! now work correctly for first
atom in template
! KWC 8/16/90 Fixed the error introduced into
the o-
! template covering O:*:O

Insight II/March 2000 435

G. Potential Template Rules

! DWS 11/17/90Removed SP3 test for o poten-

tial, changed
! precedence for some of the c'
and o' stuff
! JDC 4/8/92 Added alternative
bonding for nitro group
!
! SHS 1/9/92 Changed the atom type
for Calcium ion - Ca++
! from c+ to ca+
! JDC 9/10/92 Update template for
ca from cff91.
!
!

type: ?
! anything
template: (>*)
end_type

type:h
! hydrogen bonded to carbon
template: (>H (-*) )
atom_test:2
allowed_elements:C,Si,H
end_test
end_type

type:hn
! hydrogen bonded to nitrogen
template: (>H(-N))
end_type

type:ho
! hydrogen bonded to oxygen
template: (>H(-O))
end_type

type:hp
! hydrogen bonded to phosphorous
template: (>H(-P))
end_type

type:hs
! hydrogen bonded to sulfur
template: (>H(-S))
end_type

type:h*
! hydrogen in water

436 Insight II/March 2000

 cvff_templates.dat

template: (>H(-O(-H)))
end_type

type: lp
!lone pair
template: (>L (-*))
end_type

type:c
! generic SP3 carbon
template: (>C)
atom_test:1
hybridization:sp3
end_test
end_type

type: c=
! non aromatic double bonded carbon
template: (>C(=*))
atom_test:1
aromaticity:NON_AROMATIC
end_test
end_type

type:c'
! carbonyl (c=O) group
template (>C(=*))
atom_test: 2
allowed_elements: O,S
end_test
end_type

type:c'
! carbonyl (c:O) group
template (>C(:*)(~*)(~*))
atom_test: 2
allowed_elements: O,S
end_test
end_type

type:cp
! SP2 aromatic carbon
template:(>C)
atom_test:1
hybridization: SP2
aromaticity:AROMATIC
end_test
end_type

type:cp

Insight II/March 2000 437

G. Potential Template Rules

! This is used for aromatic carbons that fail the

aromaticity test because
! the current ring checker is to lame to figure on
a ring with more than
! seven or eight sides. The NON_AROMATIC test is to
eliminate the conflict
! with the above 'cp' definition. This can be removed
when the ring checker
! is made more robust.
template: [>C(-*)(:*)(:*)]
atom_test:1
hybridization: SP2
aromaticity:NON_AROMATIC
end_test
end_type

type: c5
! SP2 aromatic in 5 membered ring
template:(>C)
atom_test: 1
hybridization: SP2
aromaticity:AROMATIC
ring:PLANAR(5)
end_test
end_type

type: cs
! SP2 aromatic in 5 membered ring next to S
template:(>C(-S))
atom_test: 1
hybridization: SP2
aromaticity:AROMATIC
ring:PLANAR(5)
end_test
atom_test: 2
hybridization: SP2
aromaticity:AROMATIC
ring:PLANAR(5)
end_test
end_type

! The cn type is not assigned currently

!type: cn
! template (>C(-N)(-*)(-*)(-*))
!end_type

type: cr
! c in guanidinium group
template: (>C (=N(-*)) (-N(-H)(-H)) (-N(-H)(-H)) )

438 Insight II/March 2000

 cvff_templates.dat

end_type

type: c-
! c in charged carboxylate
template: (>C(:O)(:O))
end_type

type: c-
! c in charged carboxylate
! How do we indicate that the second O has nothing
bonded to it ?
! what makes it not match COOH ?
template: (>C(=O)[-O])
end_type

type: c1
! sp3 carbon with 1 h 3 heavies
template: (>C(-H)(-*)(-*)(-*))
atom_test:3
disallowed_elements:H
end_test
atom_test:4
disallowed_elements:H
end_test
atom_test:5
disallowed_elements:H
end_test
end_type

type: ca
! template: (>C(-H)(-C[~O])(-C)(-N(-H)))
template: (>C(-N(-*))(-C[~O])(~*)(~*))
end_type

type:c2
! sp3 carbon with 2 H's, 2 Heavy's
template:(>C(-H)(-H)(-*)(-*))
atom_test:4
disallowed_elements:H
end_test
atom_test:5
disallowed_elements:H
end_test
end_type

type: cg
template: (>C(-H)(-H)(-C[~O])(-N(-H)))
end_type

type: c3

Insight II/March 2000 439

G. Potential Template Rules

! sp3 carbon with 3 h's 1 heavy

template: (>C(-H)(-H)(-H)(-*))
atom_test:5
disallowed_elements:H
end_test
end_type

type: ct
! sp nitrogen involved in a triple bond
template: (>C(#*))
end_type

type: n
! Billed as sp2 with 1 H but seems to be used for
sp2 with no H's as
! well in proline
template: (>N(-*))
atom_test:1
aromaticity: non_aromatic
hybridization:SP2
end_test
end_type

type: n1
!sp2 nitrogen in charged arginine
template: (>N(-C)(=C)(-H))
atom_test:1
hybridization:SP2
end_test
end_type

type: n2
!sp2 nittrogen with two hydrogens
template: (>N(-H)(-H))
atom_test:1
aromaticity: non_aromatic
hybridization:SP2
end_test
end_type

type: np
!sp2 sp2 aromatic
template: (>N)
atom_test:1
aromaticity:aromatic
hybridization:SP2
end_test
end_type

type: np

440 Insight II/March 2000

 cvff_templates.dat

!sp2 sp2 aromatic

template: (>N(:*)(:*))
atom_test:1
aromaticity:non_aromatic
hybridization:SP2
end_test
end_type

type: np
!
template: (>N(=O)(-O))
atom_test:1
aromaticity:non_aromatic
hybridization:SP2
end_test
end_type

type: n3
! sp3 nitrogen with 3 substituants
template: (>N(-*)(-*)(-*))
atom_test:1
hybridization:SP3
end_test
end_type

type: n4
! sp3 nitrogen with 4 substituants
template: (>N(-*)(-*)(-*)(-*))
atom_test:1
hybridization:SP3
end_test
end_type

type:n=
! sp2 nitrogen involved ina double bond (non-aro-
matic)
template:(>N(=*))
atom_test:1
aromaticity:NON_AROMATIC
hybridization:SP2
end_test
end_type

type:nt
! sp nitrogen involved in a triple bond
template:(>N(#*))
end_type

type:nz
! sp nitrogen in N2

Insight II/March 2000 441

G. Potential Template Rules

template:[>N[#N]]
end_type

type: ni
! Nitrogen in charged imidazole ring
template:[>N(=C(-N(-C(=C))))(-H)(-C)]
atom_test:1
ring:PLANAR(5)
end_test
atom_test:2
ring:PLANAR(5)
end_test
atom_test:3
ring:PLANAR(5)
end_test
atom_test:4
ring:PLANAR(5)
end_test
atom_test:5
ring:PLANAR(5)
end_test
atom_test:7
ring:PLANAR(5)
end_test
end_type

type: ni
! Nitrogen in charged imidazole ring
template:(>N(-C(=C(-N(=C)(-H))))(-C)(-*))
atom_test:1
ring:PLANAR(5)
end_test
atom_test:2
ring:PLANAR(5)
end_test
atom_test:3
ring:PLANAR(5)
end_test
atom_test:4
ring:PLANAR(5)
end_test
atom_test:5
ring:PLANAR(5)
end_test
atom_test:7
ring:PLANAR(5)
end_test
end_type

type: ci

442 Insight II/March 2000

 cvff_templates.dat

! Carbon in charged imidazole ring

template:(>C(=N(-C(=C(-N)))(-H)))
atom_test:1
ring:PLANAR(5)
end_test
atom_test:2
ring:PLANAR(5)
end_test
atom_test:3
ring:PLANAR(5)
end_test
atom_test:4
ring:PLANAR(5)
end_test
atom_test:5
ring:PLANAR(5)
end_test
end_type

type: ci
! Carbon in charged imidazole ring
template:(>C(-N(-C(=N(-H)(-C)))))
atom_test:1
ring:PLANAR(5)
end_test
atom_test:2
ring:PLANAR(5)
end_test
atom_test:3
ring:PLANAR(5)
end_test
atom_test:4
ring:PLANAR(5)
end_test
atom_test:6
ring:PLANAR(5)
end_test
end_type

type: ci
! Carbon in charged imidazole ring
template:(>C(=C(-N(-C(=N(-C)(-H))))))
atom_test:1
ring:PLANAR(5)
end_test
atom_test:2
ring:PLANAR(5)
end_test
atom_test:3
ring:PLANAR(5)

Insight II/March 2000 443

G. Potential Template Rules

end_test
atom_test:4
ring:PLANAR(5)
end_test
atom_test:5
ring:PLANAR(5)
end_test
atom_test:6
ring:PLANAR(5)
end_test
end_type

type:o
! generic oxygen
template (>O)
! SP3 test removed by DWS 11/27/90
! atom_test:1
! hybridization:SP3
! end_test
end_type

type: o'
! oxygen in carbonyl group
template: (>O(=*))
atom_test:2
allowed_elements: N,C,S
end_test
end_type

type: o'
! oxygen in carbonyl group
template: [>O(:*(:*))]
atom_test:3
disallowed_elements: O
end_test
end_type

type: o-
! partial double oxygen bonded to something then
bonded to
! another partial double oxygen
template: [>O(:*[:O](-*))]
end_type

type: o-
! double bonded oxygen in charged carboxylate COO-
template: [>O(=C[-O](-*))]
end_type

type: o-

444 Insight II/March 2000

 cvff_templates.dat

! single bonded oxygen in charged carboxylate COO-

template: [>O[-C[=O](-*)]]
end_type

type: o-
! single bonded oxygen in incorrecly bond ordered
charged carboxylate COO-
! NOTE: the carbon will be flagged as having
unfilled valences
template: [>O[-C[-O](-*)]]
end_type

type: o-
! single bonded oxygen in incorrect nitro group
template: (>O(-N(=O)))
end_type

type: o-
! double bonded oxygen in incorrect nitro group
template: (>O(=N(-O)))
atom_test:1
hybridization:SP2
end_test
end_type

type oh
! oxygen bonded to hydrogen
template: (>O(-H)(-*))
end_type

type: op
! SP2 aromatic in 5 membered ring
template:(>O)
atom_test: 1
hybridization: SP2
aromaticity:AROMATIC
ring:PLANAR(5)
end_test
end_type

type: o*
!oxygen in water
template (>O(-H)(-H))
end_type

type: sh
template: (>S(-H)(-*))
atom_test:3
disallowed_elements:S
end_test

Insight II/March 2000 445

G. Potential Template Rules

end_type

type: s1
! disufide
template: (>S(-S))
end_type

type: s
! methionine sulfur
template: (>S)
end_type

type: sp
! SP2 aromatic in 5 membered ring
template:(>S)
atom_test: 1
hybridization: SP2
aromaticity:AROMATIC
ring:PLANAR(5)
end_test
end_type

type: s'
! S in thioketone group
template: (>S(=*))
atom_test:2
allowed_elements: C
end_test
end_type

type: p
! General phosphorous atom
template: (>P)
end_type

type: ca+
! calcium ion
template: [>Ca]
end_type

type: f
!fluorine bonded to carbon
template: (>F (-*))
atom_test: 2
allowed_elements: C,F
end_test
end_type

type: cl
!chlorine bonded to carbon

446 Insight II/March 2000

 cvff_templates.dat

template: (>Cl (-*))

atom_test: 2
allowed_elements: C,Cl
end_test
end_type

type: Cl
!chlorine ion
template: [>Cl]
end_type

type: Na
!sodium ion
template: [>Na]
end_type

type: br
!bromine bonded to carbon
template: (>Br (-*))
atom_test: 2
allowed_elements: C,Br
end_test
end_type

type: Br
!bromine ion
template: [>Br]
end_type

type: i
!iodine
template: (>I (-*))
atom_test: 2
allowed_elements: C,I
end_test
end_type

type: si
!silicon
template: (>Si)
end_type

type: ar
! Argon
template: (>Ar)
end_type

precedence:
(?
(ca+)

Insight II/March 2000 447

G. Potential Template Rules

(Cl) (cl)
(Br) (br)
(Na)
(p)
(si)
(f)
(i)
(h) (ho(h*)) (hn) (hp) (hs)
(lp)
(ct) (c=(ci)(c'(c-)) (cr)) (cp(c'(c-))) (c'(c-))
(cp(c5(ci)(c')(cs(c')))) (c(c1(ca)) (c2(ca(cg)))
(c3) (ca))
(o (o-) (oh(o*)) (op)) (o(o'(o-))) (o-)
(nt (nz))
(n(ni)(np(ni))(n2(n=))(n=(ni)(np(ni)(n1(ni)))))
(np(ni)) (n3(n4))
(s (sh) (s1) (sp) (s'))
(n(n=(n1(np(ni))(ni)))(n1(np(ni))(ni)))
(ar)
)
end_precedence

Out-of-Plane Assignment Rules

While assigning out-of-plane value to an atom, Insight
II first looks for matches in the currently assigned
residue library. If a match is found, the residue library
entry is used to assign the out-of-plane value to the
atom. If a match is not found, the following rules are
used to assign the out-of-plane value to the atom. Note,
however, that the rules are not designed to work for the
AMBER forcefield.
Table 1. Out-of-Plane Assignment Rules

ELEMENT ENVIRONMENT OOP FLAG

------- ----------- ----
----
N -NH3 0
=X-NH2 1
where X=SP2 and N=SP2
-NH2 0

448 Insight II/March 2000

 Out-of-Plane Assignment Rules

\
N-H 1
//
All other environments 0

------------------------------------
------------------
\
C C-- 1
//

\
C 1
/

\
C 1
/

where C=SP2
All other environments 0

------------------------------------
------------------
All other elements
All other environments 0

Insight II/March 2000 449

G. Potential Template Rules

450 Insight II/March 2000

H Amino Template File

The amino_template.dat file is used to determine the topology of

residues read in from file types that do not supply explicit connec-
tivity or bond order information. For the purposes of this discus-
sion, a residue is a set of atoms that may have their connectivity
explicitly determined without looking at their geometry. This may
be a peptide, protein, or nucleic acid residue, a complete small
molecule, or a monomeric repeat unit in a synthetic polymer. This
file also contains information as to what atoms belong to a given
charge group, which atom in a charge group is the switching atom,
and which atoms are out-of-plane atoms (atoms that are con-
strained to lie in the in the plane of their substituent atoms). This
file is used when reading Brookhaven database files, or Biosym
.car, .cor, and .arc files that do not have their normally molecular
data files.
Matches are made by first looking for exact name matches with the
residue type, and a template entry. If a match is found then the
next criterion is the correct number of atoms within the residue. If
this test passes, then a final test is made to make sure all of the
atom names in the residue and the template match. If all three tests
pass, then a match is assumed to have been found. Matches are
also made for residues with no hydrogens by subtracting off the
number of hydrogens within the template, and comparing the
heavy atoms between the residue in the molecule and the tem-
plate.
The template file is comprised of entries the first line of which is
the name of the residue and the number of atoms within it, fol-
lowed by a line for each atom in the residue which describes fully
the unknown information for each atom.
The template file is found in the $BIOSYM/data/insight directory
($INSIGHT_DATA).

Insight II/March 2000 451

H. Amino Template File

File Format Description

Line 1:
Columns 1-4, residue name
123456789_123456789_123456789_123456789_123456789_123456789_
123456789_123456789_

ALAnt 11

The first four columns make up the name of the residue, which
may be one to four characters in length.
Columns 6-7, number of atoms
123456789_123456789_123456789_123456789_123456789_123456789_
123456789_123456789_

ALAn 11

Columns 6-7 specify the number of atoms in the residue, including

hydrogens. Separate entries are specified for each of the terminal
types of amino acids, and the internal residue.

Line 2:
Columns 1-4, atom name
123456789_123456789_123456789_123456789_123456789_123456789_
123456789_123456789_

N pepN 3 1 0 1 1 4 5 1 1 1

The first four columns make up the name of each atom in the resi-
due, which may be one to four characters in length.
Columns 6-9, charge group
123456789_123456789_123456789_123456789_123456789_123456789_
123456789_123456789_

N pepN 3 1 0 1 1 4 5 1 1 1

Information in these columns specifies the name of the charge

group which contains this atom. This may be one to four charac-
ters in length. Each charge group must be contiguous and unique.
Column 11, number of bonded atoms

452 Insight II/March 2000

 File Format Description

123456789_123456789_123456789_123456789_123456789_123456789_
123456789_123456789_

N pepN 3 1 0 1 1 4 5 1 1 1

This specifies the number of atoms bonded to this atom.

Column 13, connectivity complete flag
123456789_123456789_123456789_123456789_123456789_123456789_
123456789_123456789_

N pepN 3 1 0 1 1 4 5 1 1 1

Set to 1, this specifies that the atom’s connectivity is specified fully

by other atoms within the residue. If it is set to 0, a search is also
performed for any atoms that are within range to form bonds. This
field is usually set to 1, except for internal amide nitrogens, inter-
nal carbonyl carbons, cysteine sulphurs, and nucleic acid linkage
points.
Column 15, out-of-plane switch
123456789_123456789_123456789_123456789_123456789_123456789_
123456789_123456789_

N pepN 3 1 0 1 1 4 5 1 1 1

Set to 1, this atom is constrained to lie in the plane of its substituent

atoms during molecular mechanics simulations. Set to 0, this atom
may be non-planar during molecular mechanics simulations.
Only atoms with exactly 3 bonds may have this field set to 1.
Column 17, group cutoff switching atom
123456789_123456789_123456789_123456789_123456789_123456789_
123456789_123456789_

N pepN 3 1 0 1 1 4 5 1 1 1

Set to 1, this atom is used by Discover to determine whether or not

the charge group is to be included in the energy calculation. Dis-
cover uses the distance between switching atoms to determine
which charge groups are used in energetic calculations. Only one
atom per charge group may have this field set to 1.
Columns 19-(19+number bonded atoms, from column 11), bonded
atoms
123456789_123456789_123456789_123456789_123456789_123456789_
123456789_123456789_

N pepN 3 1 0 1 1 4 5 1 1 1

Insight II/March 2000 453

H. Amino Template File

The atom number of each bonded atom is listed. Atom numbers

start at 0 and end at the number of atoms in the residue, less 1. For
example, the 1 in column 19 specifies that this atom is bonded to
atom number 1 in the residue, which is actually the second atom
found in the residue (N is the first, and is atom number 0). The 4
and 5 in columns 21 and 23 specify that this atom is also bonded to
the fifth and sixth atoms in the residue. Insight allows up to six
bonds per atom.
Columns beyond (19+number bonded atoms), bond order of bonded
atoms
123456789_123456789_123456789_123456789_123456789_123456789_
123456789_123456789_

N pepN 3 1 0 1 1 4 5 1 1 1

The bond order of each bonded atom is listed in the same order as
the bonded atoms. Bond orders are as follows: 0 or 1 is a single
bond, 2 is a partial double bond, 3 is a double bond, 4 is a partial
triple bond, and 5 is a triple bond.

Example
(extracted from amino_template.dat)

ALA 10
N pepN 2 0 1 1 1 4 1 1
CA pepN 4 1 0 0 2 5 6 0 1 1 1 1
C pepC 2 0 1 1 3 1 3 1
O pepC 1 1 0 0 2 3
HN pepN 1 1 0 0 0 1
HA pepN 1 1 0 0 1 1
CB meB 4 1 0 1 7 8 9 1 1 1 1 1
HB1 meB 1 1 0 0 6 1
HB2 meB 1 1 0 0 6 1
HB3 meB 1 1 0 0 6 1

454 Insight II/March 2000

 Cartesian Coordinate File (.car, .cor)

I Classic File Formats

The following describes fixed, non-changing formats for certain

key files which can be used. Refer to Appendix B and the separate
Common File Formats document for current formats of these files, as
these files are written and used by current software.

Cartesian Coordinate File (.car, .cor)

For each atom, this file contains an atom name, three Cartesian
coordinates, the residue name and number, and the absolute atom
number in the full atom sequence. The potential atom type fields
and partial atomic charge fields are no longer used, but are
reserved for compatibility with older version coordinate files. This
information is now specified in the molecular data file.
Starting with the 2.7.0 versions of Insight and Discover, the PBC
record is read in the Cartesian coordinate file instead of the molec-
ular data file. The format used for the Cartesian coordinate file
and the archive file is identical. Both files have 80 characters. The
new .car and .arc files start with a Biosym file header, followed by
a line indicating whether PBC information is available. The coor-
dinate section starts with the third line. The actual PBC informa-
tion is provided after the title and the date lines of the coordinate
section.
Note that this file consists of fixed-length (80-character) records.
Format of Cartesian coordinate file:
First line: !BIOSYM archive 3
Second line: PBC=ON or PBC=OFF
(The coordinate section begins with the third line.)
Third line:1-64 Title for the system.

Fourth line:!date ##/##/## time: ##:##:## (if any; oth-

erwise blank)

Insight II/March 2000 455

I. Classic File Formats

Fifth line:
PBC information IF present:
1-3 ‘PBC’
4-13 a in angstroms
14-23 b in angstroms
24-33 c in angstroms
34-43 alpha in degrees
44-53 beta in degrees
54-63 gamma in degrees
64-80 space group
The space group name adapted from
the Hermann-Manguin notation.
This notation is modified slightly to
accommodate a standard computer
character set by eliminating slashes,
subscripts, and bars over numbers.
A number with a bar over it is
denoted by the number with the
hyphen character (-) immediately
following. Subscripted numbers/let-
ters are represented by joining the
two characters together (non-sub-
scripted number/letters must have a
space between them). The entire
space group designation must be
enclosed within parentheses.
Sixth line - Nth line:
1-4 Atom name.
6-20 x Cartesian coordinate for the atom
(angstrom).
21-35 y Cartesian coordinate for the atom
(angstrom).
36-50 z Cartesian coordinate for the atom
(angstrom).
52-55 Name of residue containing atom.
56-60 Residue sequence number relative to
the
beginningof the current molecule.
62-65 Potential function atom type (left
justified)
(ignored; see Molecular Data File).
71-72 Element type.
74-79 Partial charge on the atom.
Final line for a given molecule:
1-3 The word end.
Final line for the entire molecular system input:
1-3 The word end.

456 Insight II/March 2000

 Molecular Data File (.mdf)

Molecular Data File (.mdf)

The molecular data file contains atom names, potential
energy function types, partial atomic charges, bonding
information, torsion definition, and pseudo atoms def-
inition. In fact, all of the information needed to define
a molecular system is specified in this file, except the
actual Cartesian coordinates and the periodic boundary
conditions parameters, which are specified in the Car-
tesian coordinate (.car) file. Thus, the .mdf and .car
files together completely define a system.
These files are prepared automatically by Insight. It is,
of course, possible to modify other model building pro-
grams to generate these files and thus interface with
Discover.
Format of the molecular data file:
There are seven record types in this specification of the
molecular data file:
1. Header Record
2. Comment Record
3. Atom Record
4. End Record
5. Torsion Record
6. Pseudo Atom Record
7. Pseudo Atom Set Record
All records begin with record identifiers (keywords). In
general, the data is free format. Because this is a free
format file, at least one blank between fields is required
and each field must have a non-blank entry.

Header Record
The first record of a molecular data file must be:
!BIOSYM molecular_data
Insight interprets this as being an ASCII file contain-
ing molecular data records as outlined above.

Insight II/March 2000 457

I. Classic File Formats

Comment Record
Comment lines begin with an ! and may occur any-
where after the first record. By convention Insight
inserts a system title and a date comment record after
the version record.
Example:
! I am a Sample Molecular Data File Com-
ment Record
! 3-FEB-1947

Atom Record
Atom records follow the version and any comment
records. Atom records form the core of the description
of the molecular systems. Atoms must be listed consec-
utively by molecule, residue, and charge group.

Table 2. Atom Record Definition

CONTENTS COMMENTS
ATOM Record Identifier
atom-name An atom name which
must be unique within
this residue. Any combi-
nation of up to 4 alpha-
numeric characters is
valid.
potential-atom-type The forcefield atom type
for this atom (maximum
3 characters). It should
correspond to a valid
type in some forcefield
file.
group-name A group name which is
unique within this resi-
due. Any combination of
up to 4 alphanumeric
characters is valid. All
atoms in the same group
must occur consecu-
tively in the file. Groups
should have a neutral net
charge and are used for
nonbond cutoffs.

458 Insight II/March 2000

 Molecular Data File (.mdf)

residue-name* A residue type name.

Any combination of up to
4 alphanumeric charac-
ters is valid.
residue-number(label)* A residue instance num-
ber. Any combination of
up to 4 alphanumeric
characters is valid. All
atoms in the same resi-
due must be consecutive
in the file.
partial-charge Partial atomic charge in
electrons.
switching-atom-flag 1 if this atom is the cen-
tral atom for switching of
nonbond potential cut-
offs, 0 otherwise. One
and only one atom in
each group has the
switching flag turned on.
oop-flag 1 if this is the central
atom in an out-of-plane
interaction, 0 otherwise.
free-energy-flag (for future use)
number-of-bonds Number of atoms
bonded to this atom.
bonded-atom/bond-order
If only the atom name is
given, then this bond is
an intra-residue bond. If
the bond is between
atoms in different resi-
dues, then the residue
name and number (sep-
arated by an underscore
(_), no spaces) must
accompany the atom
name. The residue
name and number is
separated from the atom
name by a colon (:)
(again, no spaces). For
example, CA in ALA 3
would be ALA_3:CA.**
The bond-order is a
number between 0 and 3
= 0 if bond order is not
used

Insight II/March 2000 459

I. Classic File Formats

= 1.0 if bond order is 1

(single)
= 1.5 if bond order is 1.5
(aromatic)
= 2.0 if bond order is 2.0
(double)
= 3.0 if bond order is 3.0
(triple)
This field is repeated for
each bond to this atom
(number-of-bonds
times).

460 Insight II/March 2000

 Molecular Data File (.mdf)

Example:
ATOM C c’ CO GLY 3 0.38 1 1
0 3 CA/1.0 O/2.0 GLY_4:N/1.0
* Note that the combination of residue-name and resi-
due-number must be unique within the molecule.
** It is necessary to remove all spaces in residue names
and numbers when specifying bonds so that the entire
atom specification can be read in as a unit during a free
format read.

End Record
Each molecule is separated from the previous molecule with an
end card. The end of all molecules in the atom based data is sig-
naled by an end system record.

Torsion Record
Names can be assigned to specific dihedral angles with the TOR-
SION record. It is possible to globally assign a name to all occur-
rences of a set of four atom names or to a specific set within one
residue.
Table 3. Torsion Record Definition
CONTENTS COMMENTS
TORSION Record identifier
residue-name The residue name of the
residue where the atoms
names are found (any
combination of up to 4
alphanumeric charac-
ters).
* means all residue
types.
residue-number(label) The residue number of
the residue where the
atoms names are found
(any combination of up to
4 alphanumeric charac-
ters).
* means all numbers.
angle-name The assigned name for
this dihedral which can
be any combination of up

Insight II/March 2000 461

I. Classic File Formats

to 4 alphanumeric char-
acters.
atom-name (x4) Four atom names.
Atoms must be con-
nected to each other in
the order given. The
dihedral named is that
angle formed by the
bonds connecting the
first with second and the
third with the fourth
atoms while looking
down the bond connect-
ing the second to the
third (the first atom being
closest to the viewer).
Atom names have one of
four possible forms:
1.molecule: residue_
number:atom
2.residue: atom
3.*:atom
4atom
where:
moleculeis an integer
molecule
number
residueis the residue
type name
_ must occur between
residue
and number
numberis the residue
instance
number
atomis the atom name
The first form specifies a
single particular atom in
the system. The second
form identifies an atom in
any instance of the spec-
ified residue. The third
form specifies an atom in
any residue. The final
form indicates an atom in
the same residue as the
torsion. Note that by

462 Insight II/March 2000

 Molecular Data File (.mdf)

convention the torsion is

assigned to the residue
in which the second
ERatom occurs.

Example:
TORSION * * phi *:C
N CA C
TORSION VAL * chi1 N
CA CB CG1

Pseudo Atom Record

A pseudo atom is defined as the weighted average position of a set
of atoms. The method for calculating this position can be arith-
metic averaging, center of mass.
One important use of pseudo atoms is when using distance infor-
mation derived from NOE intensities when assignments could not
be made.
Table 4. Pseudo Atom Definition
CONTENTS COMMENTS
PSEUDO identifier Must be after the ATOM
record and before the
END record. Must also
precede the correspond-
ing PSEUDOSET
record.
Number Indicates the count of
pseudo atoms.
name Indicates user specified
name of the pseudo
atom. Any combination
of up to 4 alphanumeric
characters is valid. If no
name has been given,
the internal name gener-
ation scheme is:
:residuename_#:Xn is
used where:
:residuenameis four
alphanumberic charac-
ters if all the members of
the pseudo atom belong
to the same residue.

Insight II/March 2000 463

I. Classic File Formats

Otherwise, the keyword

XRES is used. The key-
word XRES is also used
when the pseudo atom
set is empty.
_must occur between
:residuename and resi-
due#.
residue#is the residue
instance number of resi-
duename.
:XnX is mandatory and n
is a 3-digit integer repre-
senting the sequence
number of pseudo atoms
generated for that partic-
ular residue. If there is
only one pseudo atom
for that residue, X is
appended. Conse-
quently, the number of
internally named pseudo
atoms for one particular
residue is limited to 999.
The total number of inter-
residue pseudo atoms is
limited to 999.
Criterion_codeOne let-
ter code that represents
the method used for cal-
culating the pseudo atom
position.
A = arithmetic
C = center of Mass
F = fixed point in space
(the pseudo atom set is
then empty)
X,Y,Z coordinates
Specifies pseudo atom
coordinates. These are
optional since they are
calculated. However, in
the case of a fixed point
in space pseudo atom,
those values are used for
the empty pseudo atom
set. Real numbers.

464 Insight II/March 2000

 Molecular Data File (.mdf)

Example:
PSEUDO 23 CYS_26:X A
or:
PSEUDO 10 XRES:X A

Pseudo Atom Set Record

A pseudo atom set is a group of atoms used for defining a pseudo
atom. The pseudo atom set can be an empty set. The atom mem-
bers of one pseudo atom set can also be members of another
pseudo atom set. A pseudo atom can be composed of members
from different residues (inter-residue pseudo atom). However, all
the members of a pseudo atom set must belong to the same mole-
cule.
Table 5. Pseudo Atom Set Definition
CONTENTS COMMENTS
PSEUDOSET identifierMust precede the END record and follow
the corresponding
PSEUDO record. There
can be more than one
pseudoset record for a
given pseudo record.
residuename_residue#:atomname
residuenameis the resi-
due type name the atom
belongs to.
Any combination of up to
four alphanumeric
characters is valid.
residue#is the residue
instance number of resi-
duename. Any combina-
tion of up to four
alphanumeric characters
is valid.
atomname is the name
of the atom. It must be
unique within the speci-
fied residue and mole-
cule and must be an
atom name as labeled in
a previous atom record.
: and _ Delimiters are
colon (:) and underscore

Insight II/March 2000 465

I. Classic File Formats

(_).

Only three pseudo_set_

atom_name specifica-
tions can be made per
record. More than one
PSEUDOSET record per
corresponding PSEUDO
record is allowed.

Example:
PSEUDOSETALA_38:NALA_38:CA ALA_38:C
PSEUDOSETALA_38:0

Cartesian Coordinate Archive File (.arc)

This file is used internally by the program to archive and retrieve
sets of Cartesian coordinates during a run. The file is formatted
and can be examined by printing or editing it. The format for each
set of coordinates is essentially identical to the format of the Car-
tesian coordinate file (.car). Note that this file consists of fixed-
length (80-character) records.
First line: !BIOSYM archive 1
Second line: PBC=ON or PBC=OFF

(For the coordinate section, the lines below are

repeated for each archived file.)
Third line:
1–64 title for the system
65–80 energy obtained from the most
recent
minimization run (if any)
Fourth line:
!date ##/##/## time: ##:##:## (if any;
other-
wise blank)

Fifth line: PBC information IF present:

1–3 “PBC”

466 Insight II/March 2000

 Cartesian Coordinate Archive File (.arc)

4–13 a in angstroms
14–23 b in angstroms
24–33 c in angstroms
34–43 alpha in degrees
44–53 beta in degrees
54–63 gamma in degrees
64–80 space group
Sixth line–Nth line:
1–4 atom name
6–20 x Cartesian coordinate for the atom
(angstroms)
21–35 y Cartesian coordinate for the atom
(angstroms)
36–50 z Cartesian coordinate for the atom
(angstroms)
52–55 name of residue containing atom
56–60 residue sequence number relative to
the
begin-
ning of the current molecule
62–65 potential function atom type (left
justified)
(ignored; see Molecular Data File)
66–75 partial charge on the atom
(ignored; see Molecular Data File)
76–80 absolute atomic sequence number
relative to the
beginning of the entire molecular
system
Final line for a given molecule:
1–3 the word “end”
Final line for the entire molecular system input:
1–3 the word “end”

Insight II/March 2000 467

I. Classic File Formats

468 Insight II/March 2000

9 Using Compressed Files

Most of Biosym’s software, including Insight II, the various appli-

cation modules, and many related utility programs, can now read
compressed files. This feature affects only the reading of existing
files, not the creation or writing of files. Almost any kind of file can
be used directly in compressed form, including Brookhaven PDB
files, sequence database files, log files, and Biosym .arc files and
.psv folder files, to name a few.

Recognized Compression Formats

Files compressed in either of two formats can be read. These are
the formats of the two most commonly-used file compression
commands on UNIX systems:
1. the standard UNIX compress command, which marks com-
pressed files by appending a .Z extension onto their filenames;
2. the gzip command from the Free Software Foundation, which
marks compressed files by appending a .gz extension onto their
filenames.
Biosym’s software recognizes the compression format by the .Z
and .gz extensions, so you must not change the extension of a com-
pressed file. Also, you should not use .Z or .gz extensions for files
that are not compressed.

Compressed Files Now Appear In Value-aids

Any filename that would appear in a file list value-aid if it were
not compressed also appears if it has an extension that indicates
compression. For example, in the File/Restore_Folder command,

Insight II/March 2000 469

9. Using Compressed Files

the Files value-aid not only lists filenames ending in .psv, but also
those ending in .psv.Z and .psv.gz.

A Decompression Program Must Be On Your

System
Biosym’s software executes the uncompress program to decom-
press files ending in .Z, and the gzip -d (or gunzip) program to
decompress files ending in .gz. The decompression, and hence the
reading of the file, fails if the appropriate decompression program
is not installed on your system. The uncompress program is stan-
dard on all UNIX systems that Biosym supports. The gzip pro-
gram can be obtained from the Free Software Foundation, Inc., 675
Mass Ave, Cambridge, MA 02139, USA, or downloaded via ftp
from the directory /pub/gnu at prep.ai.mit.edu.

Decompression Creates a Temporary File

When Biosym’s software reads a compressed file, it decompresses
the file into a temporary file and reads that instead. If your com-
puter does not have enough free disk space to hold the decom-
pressed temporary file, the reading of the file fails. The temporary
file is always removed (strictly speaking, “unlinked”) immedi-
ately after it is opened for reading, so it disappears when the read-
ing is finished, or when the program terminates unexpectedly.
The name of the temporary file begins with the four letters temp
and ends with a string of alphanumeric characters generated by
the computer to make the file name unique. The temporary file is
automatically created either in your home directory or in the stan-
dard system directory for temporary files, depending on which of
the associated filesystems has more free disk space. The standard
system directory for temporary files is usually /tmp, /usr/tmp, or
/var/tmp on most UNIX systems. You can determine which of
these applies to your system by reading the definition of “P_tmp-
dir” in the file /usr/include/stdio.h.

470 Insight II/March 2000

 Fail-Safe Decompression Strategy

You can override the behavior just described, and force the soft-
ware to create the temporary file in a directory of your choice, by
setting the environment variable TMPDIR to the name of that
directory. For example, to force the creation of temporary files in
the directory /usr/local/tmp, you would type the command:

> setenv TMPDIR /usr/local/tmp

at the UNIX prompt, or add it to your .cshrc file.

Because the temporary file is automatically deleted, you normally
never see it. There is, however, one rare circumstance in which a
temporary file can persist: if the software is killed (for example, via
the kill command) during the brief period when the gunzip or
uncompress command is in the process of decompressing, then an
incomplete temporary file may be left on your disk. If this hap-
pens, you should manually delete the temporary file.

Fail-Safe Decompression Strategy

If the decompression fails for any reason, the software tries to find
and open an uncompressed version of the same file before it gives
up. It does this simply by removing the .Z or .gz extension from the
filename and then trying to open the corresponding file. Similarly,
if it fails to open or cannot find an uncompressed file, it tries to find
and open a compressed version of the same file before it gives up.
It does this first by looking for a version of the file ending in .gz,
then, if that fails, for one ending in .Z. If either a compressed or an
uncompressed version exists, the software reads it, whether or not
you specify the correct extension in the filename. The software
always tries first to open the file with the exact name and extension
that you specify.
This behavior frees you from the burden of trying to remember
whether or not you compressed a particular file that you want to
read. It also means that any log files or BCL macros that contain
explicit data file names continue to work even if you compress (or
decompress) those data files after the script is written.

Insight II/March 2000 471

9. Using Compressed Files

Caveats

Using Soft Links to Compressed Files

A compressed file can be accessed via a soft link, but only if the
name of the link has the same extension (.gz or .Z) as the file itself.
For example, if a soft link named my_file.gz points to the file
pdb1crn.ent.gz, then the Insight II command:
Get Molecule PDB User my_file.gz CRN -Heteroatom -
Reference_Object
works correctly. If, however, the soft link named my_file points to
pdb1crn.ent.gz, then the command:
Get Molecule PDB User my_file CRN -Heteroatom -Reference_
Object
fails with a “Bad file format” error message.

VMS .Z Files Cannot Be Read

Some files compressed on VMS computer systems have .Z exten-
sions but are not in the same format as UNIX .Z files. Unfortu-
nately these VMS .Z files cannot be read directly by Biosym’s
software. Instead they must first be decompressed on a VMS sys-
tem, transferred to a UNIX system, and then compressed. Some
protein sequence database files are distributed on the Internet in
this VMS .Z format, so be sure to download UNIX-compatible files
instead.

472 Insight II/March 2000

 Index

A methodology 265
Annotate command
ACE User pulldown 131
Inhibitor Captopril 175 Apply command
pharmacophore model 197 Transform pulldown 122
Adams, N. 389 aromaticity test 428
Add command assembly
Assembly pulldown 128 equivalent to family 260
Add_To_Pulldown command
Assembly pulldown 86
Custom pulldown 134
Aldehyde 181 commands in 128
Assimilate 181
fragment 181
Alias command Associate command
Session pulldown 98 Assembly pulldown 128
AM_Analyze pulldown Atom pulldown
commands in 231 commands in 151
AM_Parameters pulldown in Builder module 151
commands in 229 atom tests 427
AM_Run pulldown auto-correlations 272
commands in 231 average plane evaluation 247
AM_Setup pulldown Axes command
commands in 228 Transform pulldown 121
amide Axes_Display command
bond 181, 193, 198, 203 Object pulldown 106
Ampac/Mopac 8 Axis_Function command
Ampac/Mopac command Trajectory pulldown 261
Module pulldown 91 methodology 264
Ampac/Mopac module 22
tutorial 235
Analysis 7 B
Analysis command background color 94
Module pulldown 92 background job
Analysis module 22 completion status 285
tutorial 266 default mode 284
Angiotensin Converting Enzyme (ACE) 176 execution mode 285
Angle command host 285
Measure pulldown 116 requirements for running on a remote host
Angle_Def command 281
Trajectory pulldown 261 Background_Job
Animate command application 282
Trajectory pulldown 252, 259 command summary 283
memory limitations 266 commands in 231, 264, 283

Insight II/March 2000 473

C

methodology 284 C
Background_Job pulldown
commands in 231, 264 Calculation command
in Analysis module 258 AM_Setup pulldown 228
Background_Job tutorial Cambridge
using the Ampac/Mopac module 287 data files 2
Baker, J. 212, 213, 389 Cambridge Crystal database
Banerjee, A. 214, 389 molecule from 49
Captopril 176, 177, 178, 195
Bergeron, D. 213, 389
Using Sketch 190
Binding_Site command carboxyl
Module pulldown 90 group 176, 192, 194, 198, 199, 204
Biopolymer command oxygen 198
Module pulldown 87 case sensitivity 100
Biopolymer module 22 Catalogue command
Biosym Command Language Custom pulldown 135
see also BCL 289 Cell command
with Custom pulldown 134 Assembly pulldown 128
Blank command Cell_display command
Object pulldown 106 Assembly pulldown 129
Blink command Center command
Object pulldown 106 Transform pulldown 121
Bond_Order command Cerjan, C. J. 214
Molecule pulldown 112 Change_directory command
Boolean command Session pulldown 100
Graph pulldown 274 Charge command
Bracewell Atom pulldown 151
reference 251 CHARMm 9
Brookhaven CHARMm command
Protein Data Bank 2 Module pulldown 90
Brookhaven database CharSize command
molecule from 49 Graph pulldown 276
Browse command Grid pulldown 235
Molecule pulldown 114 Charsize command
Buffer command Contour pulldown 143
Session pulldown 97 User pulldown 132
Clip command
Builder 2, 5, 176, 179, 190, 197
Transform pulldown 122
Builder command Close command
Module pulldown 87 Window pulldown 136
Builder module 22 Close_Layout command
Builder module 175 Window pulldown 138
Builder tutorial 173 Cluster command
bulk density 257 Trajectory pulldown 261
Bump command methodology 265
Measure pulldown 117 color
Button command use of 63
Session pulldown 99 Color command

474 Insight II/March 2000

 D

Contour pulldown 142 search 7, 176, 204

Graph pulldown 276 Connect command
Grid pulldown 233 Transform pulldown 119
Molecule pulldown 110 Construct_Graph command
User pulldown 131 Trajectory pulldown 252, 256, 260
color palette 36 methodology 264
Color table mode 65 Contour command
COM_Distance_Def command Graph pulldown 274
Trajectory pulldown 261 Grid pulldown 234
COM_P_Dist_n_Def command Contour pulldown 86
Trajectory pulldown 263 commands in 140
command Contour utility
Fragment pulldown 156 description 368
command modes tutorial 374
activate mode 40 coordinates
repeat mode 40 Cartesian vs. internal 213
commands coordination number 258
Completion_Status 284 Copy command
concurrent 42, 43
Control_Bkgd_Job 283 Object pulldown 105
default objects 48 Subset pulldown 126
Define 172 core
Delete 172 Viewer module 77
escaping from typed to menu 42 Correlate command
Fuse_1 157 Graph pulldown 274
Fuse_3 160 create
Fuse_Close 161 graph 269
hierarchy 21 Create command
Invert 166 Grid pulldown 243
Kill_Bkgd_Job 284 cross-correlations 272
List 172 Császár, P. 218, 390
Merge 163 Custom pulldown 86
New 143 commands in 134
Open 143 customization 27
Put 144
Rename 172 cutoff
Setup_Bkgd_Job 283 in calculating interaction energy 242
typed 41 CVFF 238
Unmerge 164
Completion_Status command, Background_
Job pulldown 284
D
computational chemistry 1 DeCipher command
Compute command Module Pulldown 92
Grid pulldown 243 DeCipher module 22
Confirmation command default
Trajectory pulldown 277 changing object 49
Conformation command object 24, 48
Trajectory pulldown 260 setting 135
conformational 182 Define command

Insight II/March 2000 475

E

Fragment pulldown 155 DMol command

Subset pulldown 126, 127 Module pulldown 91
Define command, Pseudo_Atom pulldown Docking 5
172 Docking command
Delete command Module pulldown 89
Atom pulldown 153 Docking module 22
Fragment pulldown 156 tutorial 244
Object pulldown 105 dynamical structural modification 257
Subset pulldown 127 dynamics trajectories
Delete command, Pseudo_Atom pulldown default time step 253
172
DelPhi
grid output 140 E
DelPhi command
Edit command
Module pulldown 88
DelPhi program Spectrum pulldown 133
Electron_Density command
grid output 140
DepthCue command AM_Analyze pulldown 232
Electronic_State command
Object pulldown 106
dials 15 AM_Setup pulldown 228
electrostatic 4
Differentiation command
Element command
Graph pulldown 275
Dihedral command Modify pulldown 167
Measure pulldown 116 element test 428
Dihedral_Def command Energy command
Trajectory pulldown 262 Measure pulldown 118
Discover 6, 9 energy grid
Discover command calculating 237
Module pulldown 88 energy minimization 156
Discover program 250, 252, 255 Energy_Def command
and Forcefield pulldown commands 168 Trajectory pulldown 263
and out-of-plane atoms 153 ensemble average of any pair function 257
and potential function atom types 169 Env_var command
initialize dynamics command 253 Session pulldown 100
output for analysis 245 Environment command
Discover program Session pulldown 94
input to Contour utility 370 environment variable
rotors command 372 BIOSYM_LIBRARY 425
Discover_300 command INSIGHT_POTENTIAL_TEMPLATES 425
Module pulldown 88 environmental variable
Display command BIOSYM_LIBRARY 152, 153, 171
Contour pulldown 142 FORCEFIELD 153, 171
Grid pulldown 233, 244 INSIGHT_INIT_GLOBAL 30
Molecule pulldown 111 INSIGHT_INIT_LOCAL 30, 31
Distance command INSIGHT_POTENTIAL_TEMPLATES 171
Measure pulldown 115 RESIDUE_LIBRARY 152, 171
Distance_Def command eps 380
Trajectory pulldown 261 equation

476 Insight II/March 2000

 F

operators and operands 270 captopril_s.car 177, 189

Equation command captopril_s.car2d 177
Graph pulldown 270, 274 captopril_s0.mdf 205
errors 69 Cartesian coordinate file format 455
Evaluate pulldown cvff.frc 435
commands in 242 frags.def 409
for calculating interaction energy 242 hbond_file.dat 417
in Analysis module 258 history and archive from Discover 245
examples .hp 380
torsion input file 378, 379 Insight II startup 285
Export 102 intermediate plot file format 383
Export_Image command .ipf 380, 383, 385
molecular data file format 457
File pulldown 103
Export_Molscript 104 .ps 380
.qms 380
Export_Plot command standard formatted file 378
File pulldown 102 torsion input file 379
Export_Plot command Filter command
File pulldown 380 Trajectory pulldown 250, 259
methodology 264
F Fletcher, R. 216, 390
focus parameter 37
Family command Fogarasi, G. 212, 390
Trajectory pulldown 260 forcefield
Fast Fourier Transform (FFT) 250
AMBER 170, 448
additional reading 255 CFF 171
algorithm 252, 254 CFF89 170
limitations of 251 CHARMm 170
FFT_Real command CVFF 170
Graph pulldown 275 definition 169
File Formats 393, 455 ESFF 170
File pulldown 86 library 153
commands in 101 specification 118
files Forcefield pulldown
.arc 455, 466 commands in 168
.car 455 in Builder module 151
.cor 455 Forcefield/Potentials 188
.eps 380 forcefields 4
.grd 232 fragment library 154
.inp 253
.mdf 457 Fragment pulldown
.out 253 commands in 154
.pict 380 in Builder module 151
.tab 144 frequency filtering
background_job_hosts 284 explanation 250
captopril_ s0.car 205 function keys 18
captopril_active.car 177 F8 260
captopril_r.car 177 Fuse_1 command 157
captopril_r.car2d 178 Fuse_3 command 160

Insight II/March 2000 477

G

Fuse_Close command 161 input to Contour utility 370

Grid pulldown
command in 232, 243
G Groups command
generic pulldown Forcefield pulldown 169
Background_Job 282
geometric
properties 171 H
Geometry command 164 HBond command
geometry optimization Measure pulldown 118
algorithms 213 Hehre, W. J. 213, 389
constraints 212, 213
constraints, theory 216 help 66
dummy atoms 213 icon 97
eigenvector following mode, derivation XHelp 66
214 Help command
eigenvector-following algorithm 212 Session pulldown 96
fixed atoms 213 Help pulldown 86, 138
GDIIS 212 Help Viewer 66
GDIIS method, theory 218
Hessian mode-following option 212 Hermann-Manguin
starting geometry 213 notation 456
strategy 212 Hewlett-Packard
Get command output device 382
Contour pulldown 140 postscript 380
Fragment pulldown 154 Histogram command
Graph pulldown 273 Grid pulldown 233
Grid pulldown 232 history 47
Molecule pulldown 107 History command
Spectrum pulldown 133
Subset pulldown 125, 126, 127 Session pulldown 97
Trajectory pulldown 250, 259 Homology command
memory limitations 266 Module pulldown 90
methodology 264 host
User pulldown 131 local 281
graph preference 285
cluster 245 remote 281
inanimate 245, 247 Hybridization command
multiple properties on 246 Atom pulldown 152
trajectory 245 hybridization test 428
usual method of creation 264 hydrogens
Graph pulldown
forward and backward 410
commands in 258, 269, 273 naming scheme 152
in Analysis module 258
tutorial 280 Hydrogens command
graph-generated contour file Modify pulldown 162
input to Contour utility 371 equivalent to Hybridization Atom 152
grid file hydrophobicity contrast function 257

478 Insight II/March 2000

 I

I Layout command
Window pulldown 137
icon palette 27 Layout_Template command
icons Window pulldown 137
customizing 27 Licensescommand
pre-defined 24 Module pulldown 92
Import 102 Line_Fit command
Inactive Stereoisomer 202 Graph pulldown 275
Info command LineWidth command
Graph pulldown 278 Object pulldown 106
Inplot utility 380 link_pdb 406
Insight II startup file 285 List command
Insight_Help 138 AM_Setup pulldown 229
Integration command Assembly pulldown 130
Graph pulldown 275 Atom pulldown 154
interaction energy Contour pulldown 143
equation incorporating nonbond and elec Folder pulldown 102
239 Grid pulldown 235
Interface command Molecule pulldown 113
Subset pulldown 126 Object pulldown 106
intermediate plot file format 383 Spectrum pulldown 133
intermolecular bonds Subset pulldown 127
User pulldown 133
energies 242 List command, Pseudo_Atom pulldown 172
Intermolecular command
List_Properties command
Evaluate pulldown 243
Interpolation command Custom pulldown 135
log file
Graph pulldown 275
Invert command 166 WBLOGFILE 101
logfile
insight.log 29
J WBLOGFILE 29
WBLOGFILE.save 29
job number 284 Lower command
Window pulldown 136
Lower_Layout command
K Window pulldown 138
Kill_Bkgd_Job command, Background_Job Ludi command
pulldown 284 Module pulldown 89

L M
Label command Macro_Delete command
Contour pulldown 142 Custom pulldown 135
Graph pulldown 276 Macromolecule structures 2
Grid pulldown 234 macros
Molecule pulldown 111 with Custom pulldown 134
User pulldown 132 MBOND command
Langridge reference 237 Module pulldown 90

Insight II/March 2000 479

N

MCSS command fragments 409

Module pulldown 89 hydrogens 152
Measure pulldown 86 plots 270
commands in 115 space group 419
Measure/Distance 197, 198, 204 Neighbor command
Measure/Energy 197, 198, 201, 204 Measure pulldown 117
memory New command, Table pulldown 143
limitations 266 New_Molecule 143
Merge command 163 NMR
metal binding sites in proteins 257 experiments 6
methyl NMR_Refine command
group 192, 202 Module pulldown 90
Miller, W. H. 214 nonbond potential energy
Modify pulldown 6-12 equation 238
commands in 156 6-9 equation 239
in Builder module 151 nongraphics mode 29
Modify/Invert 202 non-standard
Modify_Display command input to Contour utility 374
Graph pulldown 277 Nyquist sampling rate 253
Module 179, 190
Module pulldown 86 O
commands in 87
MolBuilder 3 object names 53
molecular dynamics 5 atom level 56
simulation 257 monomer/residue level 55
Molecular Graphics 1 object level 54
molecular mechanics 3, 5, 7 parentheses in 58
output to analysis 258 wildcards in 59
Molecular modeling 1 Object pulldown 86
Molecular_Orbital command commands in 104
Object/Delete 196
AM_Analyze pulldown 232
Molecule pulldown 86 Object/Rename 203
commands in 107 objects 49
Molecule/Get 205 assemblies 51
Molecule/Put 189, 196, 202, 205 contours 51
graphs 51
Monitor_Style command molecules 49
Measure pulldown 116 spectrums 52
mouse functions 15 user objects 50
Move command Open command, Table pulldown 143
Transform pulldown 122 operands
Move_Axis command for equations 270
Graph pulldown 277 operators
for equations 270
N Optimize 5, 187, 196, 198, 203, 205
Optimize command
naming scheme AM_Parameters pulldown 230
file/function 272 Optimize pulldown 173

480 Insight II/March 2000

 P

Optimize pulldown cvff_templates.dat 435

commands in 173 Potentials command
in Builder module 151 Forcefield pulldown 153, 169
Overlay command PP_Ang_3_Def command
Transform pulldown 124 Trajectory pulldown 262
PP_Ang_n_Def command
P Trajectory pulldown 262
pP_Dist_3_Def command
parameter block Trajectory pulldown 262
building with Custom pulldown 134 pP_Dist_n_Def command
description 32
non-typable 33 Trajectory pulldown 262
parameters precedence tree 429
default values 39 pre-defined icons 24
enumerated choice 33, 46 Press et al. reference 249
focus 37 printers
inactive 38 postscript 380
list 33, 47 qms 380
on/off (Boolean) 33, 44 pseudo atoms
trigger 40
typable 33 defined 57
Pattabiraman et al. reference 237 Pseudo_Atom pulldown
Pattabiramin et al. reference 248 commands in 171, 263
pharmacophore 176, 204 in Analysis module 258
pattern 176, 205 Pulay, P. 212, 218, 390, 391
pict pulldowns
output device 380 Background_Job 283
Pilot 73 Put command
Pilot_Tutorials 140 Contour pulldown 141
Planar command Fragment pulldown 154
Atom pulldown 153 Graph pulldown 273, 274
plots Grid pulldown 233
naming scheme 270 Molecule pulldown 109
polymers 155 Spectrum pulldown 133
Position command Trajectory pulldown 259
Transform pulldown 120 Put command, Table pulldown 144
postscript
device 380
output device 382 Q
Potential command
Atom pulldown 153 qms
potential function atom type 153, 169 output device 380
potential template rule file 169 QuanteMM 91
Potential Template Rules quantum mechanics 7
appendix 169 calculations 7
potential template rules 425 Quit command
potential type template file Session pulldown 101

Insight II/March 2000 481

R

R S
R stereoisomer 202 Saddle command
radial distribution function 257 AM_Parameters pulldown 230
Raise command Save command
Window pulldown 136 Folder pulldown 101
Raise_Layout command Scale command
Window pulldown 137 Transform pulldown 122
RDF 257 Scale_Axis command
Remove command Graph pulldown 277
Assembly pulldown 128 SCF command
Folder pulldown 101 AM_Parameters pulldown 229, 230, 231
Fragment pulldown 155 Schrodinger equation 7, 8
Rename command Search_Compare 204
Atom pulldown 154 Search_Compare command
Object pulldown 106 Module pulldown 89
Rename command, Pseudo_Atom pulldown SecondaryRender command
172 Molecule pulldown 113
Select command
Render command
Forcefield pulldown 168
Molecule pulldown 112 Session pulldown 86
Repartition_Cluster command
commands in 93
Trajectory pulldown 260 Set_Defaults command
Repeat command Molecule pulldown 110
Fragment pulldown 155 Setup_Bkgd_Job command, Background_Job
Repeat command pulldown 283
Residue pulldown 410 Shepard, R. 389
Replace command side chain conformation 200
Atom pulldown 153 Simons, J. 389
Reset command Sketch 3, 151, 197
Transform pulldown 120 sketch facility 50
residue Sketch pulldown 175
library 152 Sketch/Edit 191
residue library 169
Sketch/Get 194, 202
Restore_Folder command Sketch/Put 194, 205
File pulldown 101 Sketcher 175
RGB mode 65
slab
Ribbon command also called viewing window 122
Molecule pulldown 112 position 16, 19, 122
RMS value thickness 16, 122
as basis for clustering 256 Sleep command
Rock command Session pulldown 100
Transform pulldown 123 Slice command
Rotate command Grid pulldown 234
Transform pulldown 122 Smoothing command
Run command Graph pulldown 276
AM_Run pulldown 231 Soak command

482 Insight II/March 2000

 T

Assembly pulldown 130 Transform pulldown 123

Solvation command torsion file
Module pulldown 88 input to Contour utility 372
Source_File command Trajectory pulldown 269
File pulldown 30, 103 commands in 258
Spectrum pulldown 86 in Analysis module 258
commands in 133 Transform pulldown 86
spectrums 52 commands in 119
standard unformatted Transform/Torsion 197, 199, 202
input to Contour utility 373 Transparency command
Stereo command Molecule pulldown 111
Session pulldown 99 User pulldown 131
stereochemistry 194 Trigger command
Store command Custom pulldown 135
Turbomole command
Transform pulldown 120
Subset pulldown 86 Module pulldown 91
tutorial
commands in 125
Superimpose command Ampac/Mopac 235
Analysis module 266
Transform pulldown 125, 256 Builder module 173
Surface Molecule 112 Docking module 244
Symmetry command Graph pulldown 280
Assembly pulldown 129 Viewer module 148
System command
AM_Setup pulldown 228
U
T Unanimate command
Trajectory pulldown 260
tables UNIX 178
atom record definition 458 commands 29
B-8, pseudo atom set definition 465 Unix command
F-1, out-of-plane assignment rules 448 Session Pulldown 380
pseudo atom definition 463 Session pulldown 100
torsion record definition 461 Unmerge command 164
Tabulate command User pulldown 86
Molecule pulldown 113 commands in 131
Trajectory pulldown 263
Taylor, P. W. 390
template V
out-of-plane assignment 448 value-aid 35
potential template rule file 169 color palette 36
potential type 425 description 35
textport 11 van der Waals
Threshold command attraction 4
Graph pulldown 277 electrostatic (Coulombic) 198
Tick_Mark command repulsion 4
Graph pulldown 278 Viewer 2
Torsion command Viewer module 22

Insight II/March 2000 483

W

pulldowns in 86
tutorial 148

W
weight factors for each atom 257
Window pulldown 86, 136

X
x-ray crystal refinement
grid output 140
XYZ command
Measure pulldown 117

Z
Zhou, X. 390
zinc metallopeptidase 176
Zindo command
Module pulldown 91
Z-matrix 212
Zone command
Subset pulldown 126

484 Insight II/March 2000