AMPAC 8 with Graphical User Interface Release Notes - General ----------------------- Copyright (c) 1996-2005 Semichem, Inc. All Rights Reserved. This README file contains very general information about AMPAC and its Graphic User Interface (GUI). The AMPAC GUI is referred to here simply as the AGUI. Details that depend upon the operating system as well as troubleshooting instructions are located in a separate system specific README file. Important Features ------------------ AMPAC 8 utilizes dynamic memory allocation to allocate at run time only as much memory as is required by the individual job. This is a major change from previous versions where memory was statically allocated. Using dynamic memory allocation means that there is only one executable and no longer any need to select which executable is needed to handle a given molecule. There is no longer any fixed limit on the number of atoms or the size of the CI space. The primary limit on job size is the amount of memory (real plus virtual) that is available on the machine. For operating systems using 32-bit executables, the maximum job size is constrained by the limitation on addressable space. (Memory and disk space requirements are discussed in the Appendix below.) Another new feature of AMPAC 8 involves the management of environmental variables. (This only applies to Unix systems.) In previous versions, link library path variables were explicitly initialized into the user's environment before AMPAC could be used. These changes can interfere with or affect the run-time performance of other applications that rely on the same path variables to pick up their run-time libraries. Now, only simple AMPAC specific variables are initialized directly into the user's environment. The link library path variables are part of a separate script and are initialized only within the scripts that run AMPAC and so will not affect other processes run by the users. This should prevent AMPAC from interfering with other processes on the same machine. Documentation describing all of the latest features of AMPAC and the AGUI are included with AMPAC package. Both sets of documentation can be accessed directly from the AGUI from the Help menu. The AMPAC manual can also be opened directly in html using standard browsers. The main page of the AMPAC manual is located at $AMPAC_DIR/ampacmanual/index.html. Where $AMPAC_DIR is the base AMPAC installation directory. The main index of the manual for AGUI is likewise found at $AMPAC_DIR/agui/aguimanual/index.html. For windows systems, help documentation for AMPAC is also available in Microsoft HTML Help format, which can be found at $AMPAC_DIR/agui/aguimanual/ampac.chm. Getting Started --------------- After unpackaging and installing AMPAC, there are a few steps that need to be performed before AMPAC or AGUI can be used. These steps are outlined here but more detail can be found in the "Package Administration" section of the AMPAC manual. These steps need to only be performed once but may require administrator privileges. 1) A valid AMPAC license must be installed before AMPAC and AGUI can be used. This license must be obtained from Semichem's Customer Support. Once the license key file is obtained it must be copied to the base directory of the AMPAC installation and be given the name "ampac.key". The "ampac.key" file must have read permissions for anyone who will be using AMPAC or AGUI. 2) Set the proper file protections: cd {AMPAC installation directory} chmod u+x Set_File_Protection.csh ./Set_File_Protection.csh 3) Edit the AMPAC_DIR variable in the "init_ampac.[c]sh script". For users of csh or tcsh shells, the necessary script is "init_ampac.csh". For users of sh, ksh, or bash shells, the necessary script is "init_ampac.sh". Open the appropriate script and make sure that the variable AMPAC_DIR near the top of the file is set to be the AMPAC installation directory. If necessary, edit the file to set AMPAC_DIR points to the correct directory. 4) The initialization script must sourced before AMPAC, AGUI, or any of the AMPAC utilities may be used. Follow the set of instruction according to which type of shell you will be using. (If you are uncertain of which shell type you are currently using, type "echo $0".) For csh or tcsh shells, one must give the command "source init_ampac.csh" before AMPAC can be used in that shell. To have done automatically (rather than having to do it every time), add the following line to either one's ".cshrc" or ".login" shell. source {AMPAC installation directory}/init_ampac.csh For sh, ksh, or bash shells, one must give the command ". init_ampac.sh" before AMPAC can be used in that shell. To have this happen automatically, add the following line to one's ".profile" (or ".bash_profile"). . {AMPAC installation directory}/init_ampac.sh 5) It is recommended that users run the "check_env.csh" to verify that everything has been set up. Details on the use of this script and what tests it performs can be found in the "Diagnostic Tool (Unix Only)" section under Troubleshooting. 6) On unix platforms which provide the KDE or GNOME desktops, AMPAC can be integrated with those desktop environments. For more information, See the file README-Desktops.txt Semichem Customer Support ------------------------- If you are experiencing problems running AMPAC or AGUI, please read this file and the system specific README file (in the READMEs directory) before contacting Semichem Customer Support. If these fail to resolve your problem, contact Semichem Customer Support at (913) 268-3271 or send email to "support@semichem.com". =============== Troubleshooting =============== Diagnostic Tool (Unix Only) --------------------------- AMPAC now provides a new diagnostic tool to help identify and solve the most common problems that might prevent AMPAC from running. This tool should be the first step in identifying problems. Simply execute the script $AMPAC_DIR/bin/check_env.csh. The script makes the following checks: 1) Checks that $AMPAC_DIR and $AGUI_DIR have been set (i.e. that init_ampac.csh or init_ampac.sh have been sourced). 2) Verify that $AMPAC_DIR and $AMPAC_DIR has been set correctly. 3) Checks that key executables and scripts are present and in the correct directories. 4) Verify that file permissions have been set correctly for key executables and scripts. 5) Verify that file permissions have been set correctly for any libraries accompanying AMPAC and AGUI. 6) Check that ampac.key exists and is in the correct location. (If the key exists, it may still be corrupted and need cleaning. See "Corrupt or invalid license key file" below.) 7) Check the ld_env.csh script and run-time load library paths. 8) Use ldd (or its equivalent) to print the list of required libraries, their locations, and if a library is missing. 9) Report configuration details (if any). This is diagnostic information only. 10) Attempt to run AMPAC and verify that it works correctly. (Requires read and write permission into temporary directory /tmp.) If this script is unable to identify your problem, check the troubleshooting information in this file and your system specific README file. If these do not resolve the problem, contact Semichem Customer Support with a description of the problem and the output from "check_env.csh" script. Missing license key file ------------------------ Symptom: AGUI reports "Failed to locate ampac.key" or AMPAC output file reports "### ERROR OPENING AMPAC.KEY FILE" For either of these two errors, the program was not able to locate the necessary ampac.key file. If you do not have this file, you will need to contact Semichem's Customer Support to get one. If you already have a valid key, it must be located in the correct directory to allow AGUI and AMPAC to run properly. The ampac.key file must be located in the base directory of the AMPAC installation (i.e. $AMPAC_DIR). Corrupt or invalid license key file ----------------------------------- Symptom: AGUI reports "Error! Invalid KEY File" or AMPAC output file reports "### AMPAC.KEY FILE IS INVALID" In the process of emailing the ampac.key license file or in transferring it from one machine to another, the file may become corrupted. The program, keycleaner.exe, is a special utility that is designed to fix the most common cases of corrupted key files. For Windows systems, follow the instructions given in the README-WIN32.txt file instead. First, execute the "init_ampac.csh" (for csh or tcsh shells) or "init_ampac.sh" (for sh, ksh, or bash shells) scripts to set up the environmental variables if this has not already been done. Go to the main AMPAC directory (i.e. $AMPAC_DIR) and locate the ampac.key file. Issue the command: keycleaner -k ampac.key If the program completes without issuing an error, then it was successful and you should be able to use AMPAC and the AGUI. If AMPAC or AGUI continues to report the same error, then contact Semichem Customer Support for help. If keycleaner reports "Key is corrupted! Unable to clean" or other error messages then either it is a bad file or unfixable. In this case, contact Semichem Customer Support for a new key. Additional information on the keycleaner program can be found in the AMPAC documentation under "AMPAC Utilities." Missing Libraries ----------------- AMPAC relies on libraries that must be loaded at run time. In the event that AMPAC is unable to find all of its required libraries, then it will print out an error message and exit. The specific error message and required libraries varies between operating systems. Consult the operating system specific README file for specific details regarding your operating system and how to fix this problem. AGUI reports "Can't Open Display" (X11 Only) -------------------------------------------- Symptom: AGUI fails to launch. You must launch this application from an X-terminal, and the DISPLAY environment variable must point to the IP address of the terminal. In a remote location, you must issue a "setenv DISPLAY" command prior to launching the apps. See your printed documentation for more details. OpenGL is Required ------------------ The AGUI requires an OpenGL capable display and will not launch without one. For X11 based systems, there are two utilities that can be used to gain information about the system to determine if they are OpenGL capable and provide useful system configuration information and other properties. "xdpyinfo" is a utility program that comes with the operating system (except Windows) and displays information about the system's X server. It is called with the following command: xdpyinfo | more The "xglinfo.exe" program can be found in the "$AMPAC_DIR/agui/xglinfo" directory. (Some operating systems also have their own version of xglinfo.) "xglinfo.exe" prints information about the system's GL properties. It is called with the following command: xglinfo.exe | more If you believe your display should support OpenGL AND the printout from these utilities confirm support, send the output from the above commands to Customer Support, along with a description of the problem. Appendix -------- Memory Required: Memory allocation is now handled dynamically and is no longer fixed by the size of the executable. 128 MB should be considered the bare minimum for running both AMPAC and its GUI. It is recommend that you have at least 512 MB memory to run reasonably. It is best to have at least 1 GB or more of memory, especially if you anticipate handling large molecules (several hundred atoms) or doing large CI calculations. AMPAC places no fixed limits on the size of the system that can be handled and is only limited by the available memory and machine architecture. For 32-bit executables, there is an additional limitation on addressable space that can prevent very large jobs from running. The exact limitation depends on the specific job but some general guidelines can be given. For a simple optimization with no C.I., the 32-bit limitation is around 1,000 atoms. For small molecules, 32-bit addressing limits C.I. to around 5,000 microstates. Swap Space: In addition to physical memory, swap space is also important for efficiency in running AMPAC or CODESSA. As a general rule the system should always be configured with swap space at least as large as the actual physical memory. A larger amount of swap space is recommended if you expect to run AMPAC (or other programs) requiring large blocks of memory. Consult your system manager or documentation on setting up this part of your system's configuration. This is also explained to some extent in each of the version specific README files found in the top AMPAC or CODESSA directories. Disk Space: You need to set aside at least 100 MB of disk space for storage of the programs and support files.