README for AIMAll (Version 14.11.23)

AIMAll is a software package for performing quantitative and visual QTAIM (Quantum Theory of Atoms in Molecules) analyses of molecular systems - starting from molecular wavefunction data.

Two of AIMAll's components (AIMExt and AIMInt) are very heavily modified and extended derivatives of two programs (Extreme and ProaimV) from the AIMPAC package that was developed and maintained by members of Richard F.W. Bader's research group.

TAK was fortunate enough to be one of those members from 1991-1993.

Continued interest in QTAIM and its practical implementation eventually led to the development of AIMAll, which has been a spare-time effort for several years.

The initial goal for AIMAll was to make a QTAIM package that was:

• Easy to use, essentially automatic
• Rigorous
• Accurate
• Reliable
• Robust
• Relatively fast and efficient
• Able to calculate a rich variety of properties of interest
• Able to produce a descriptive consolidation of all important results

Once this goal was reasonably close to being achieved, work on AIMAll accelerated, including extensive work on a visualization component (AIMStudio) and shared memory multi-processor support for AIMAll calculations.  Visualization and shared memory multi-processor support have been added to the AIMAll package.  These features require an AIMAll Professional license in order to be used with non-small wavefunctions.

AIMAll is actively developed to address any issues which may arise, to expand upon and improve existing features and methods and to implement new features and methods.

AIMAll is available for Windows, Mac OS X and Linux.

• Developer:  Todd A. Keith (TK Gristmill Software)
• Website:  http://aim.tkgristmill.com
• EMail:     aim@tkgristmill.com

1. "AIMAll (Version 14.11.23)" is provided by Todd A. Keith (Doing Business As "TK Gristmill Software") "AS-IS", without any expressed or implied warranties of any kind.
    
2. Todd A. Keith (TAK) disclaims all implied warranties including, but not limited to, implied warranties of merchantability and fitness for a particular purpose.
    
3. Neither "AIMAll (Version 14.11.23)" nor any of its components may be sold, redistributed, repackaged, bundled, copied, modified, disassembled or reverse engineered in any form, either in whole or in part, without the explicit, written consent of TAK.
    
4. While TAK believes "AIMAll (Version 14.11.23)" to be useful, TAK makes no guarantees of any kind about the fitness of "AIMAll (Version 14.11.23)" for any purpose, its compatibility with or effect on any computer hardware or software, or the reliability or accuracy of any results it produces.
    
5. In no event shall TAK be held liable for any damages of any kind arising directly or indirectly from the download, installation or use of "AIMAll (Version 14.11.23)".
    
6. "AIMAll (Version 14.11.23)" operates either in AIMAll Professional mode or AIMAll Standard mode depending upon the presence of a valid aimallpro.lic file in the main AIMAll directory.
    
7. The AIMAll Standard operating mode is the default mode.  It does not require an aimallpro.lic file and is free of charge, though registration is requested.   The AIMAll Standard operating mode imposes a limit on the size of the molecular wavefunction data that can be used for running multi-processor calculations, for generating visualization-related data files (*.*viz) by AIMQB, AIMExt, AIMInt and AIMSum, and displaying them with AIMStudio.  This limit is 12 or fewer atoms and 400 or fewer primitive basis functions.  AIMAll Standard also imposes a limit of 3 wavefunctions per batch job when using AIMQB in GUI mode.  Depending on the evolution of AIMAll, future versions of AIMAll may impose other limits on the AIMAll Standard operating mode.
    
8. The AIMAll Professional operating mode does not impose any multi-processor limits, visualization limits or other limits on the size of the molecular wavefunction data.  AIMAll Professional does not impose any limits on the number of wavefunctions per batch job when using AIMQB in GUI mode.  A valid aimallpro.lic file must be present in the main AIMAll directory in order for AIMAll to operate in AIMAll Professional mode.  An aimallpro.lic file is specific to a single computer.  An aimallpro.lic file must be purchased as part of an AIMAll Professional License Pack.  An aimallpro.lic file is permanently valid on the corresponding computer for any version of AIMAll released within at least one year from the time that the aimallpro.lic file is issued.
    

• LICENSE.txt
   
• README.txt
   
• test Folder - Contains a variety of wavefunction files
   
• Manual Folder
   
• Plugins Folder - Do not touch
   
• MSVC, Qt and Intel dll files and MSVC manifest file - Do not touch
   
• aimqb.exe (AIMQB) - This is the primary AIMAll program for setting up and running calculations.
  • Automatically runs, with various options, a full QTAIM analysis using the programs aimext.exe, aimint.exe and aimsum.exe.
  • Windows Usage:  Launch AIMQB (aimqb.exe) directly or from a shortcut or from AIMStudio or drag-and-drop a .wfn, .wfx or fchk file onto it.
  • Command-line Usage:  aimqb [options] [wfnfile | wfxfile | fchkfile]


• aimutil.exe - Do not use directly.
   
• aimext.exe (AIMExt) - Typically, this program is run by AIMQB and AIMStudio and need not be run directly by the user
  • When AIMExt is run directly by the user, it operates in a self-explanatory Interactive command-line mode.
  • AIMExt can find, characterize and connect critical points of the electron density, writing the results to a .extout, a .mgp file and possibly a .mgpviz file.
  • AIMExt can find and characterize critical points of other functions, such as the Laplacian of the electron density, kinetic energy densities, the virial field and the magnetically induced current density, writing the results to a .extout file.
  • AIMExt can evaluate a variety of functions and their derivatives at user-specified points.
  • When the function being analyzed is the electron density, AIMExt can create input files for the atomic integration program AIMInt.  This involves determining the connectivity of all critical points of the electron density.
  • AIMExt also allows the creation of 2D and 3D grid files (.g2dviz and .g3dviz files) to be loaded by AIMStudio in order to display contour maps, relief maps and isosurfaces.
  • When the function being analyzed is the electron density, AIMExt allows the creation of one or more atomic basin GradRho path files (.basviz).  A .basviz file corresponding to atom A can be loaded by AIMStudio in order to display atom A's atomic basin in terms of a set of GradRho paths which terminate at its NACP (nuclear attractor critical point).
  • Windows Usage:  Launch AIMExt (aimext.exe) directly or from a shortcut or from AIMStudio or drag-and-drop a .wfn file or a .wfx file onto it.
  • Command-line Usage:  aimext [-progress] [-wsp] [wfnfile | wfxfile] [-input ...]


• aimint.exe (AIMInt) - Typically, this program need not be run directly by the user.
  • Calculate atomic properties based on the specified atomic input file (.inp) and wavefunction file (.wfn or .wfx), writing the results to a .int file and possibly a .iasviz file to be loaded by AIMStudio in order to display interatomic surfaces and atomic integration ray data.
  • Windows Usage:  Launch AIMInt (aimint.exe) directly or from a shortcut or from AIMStudio.
  • Command-line Usage:  aimint [-nproc=...] [-wstat] [inpfile wfnfile | wfxfile]


• aimsum.exe (AIMSum) - Typically, this program need not be run directly by the user.
  • Generate a summary file (.sum) and possibly a corresponding visualization file (.sumviz) by processing information from the .mgp file, .mgpviz file and .int files corresponding to the specified .wfn file or .wfx file.
  • Windows Usage:  Launch AIMSum (aimsum.exe) directly or from AIMStudio or drag-and-drop a .wfn file or .wfx file file onto it.
  • Command-line Usage:  aimsum [-feynman=true/false] [wfnfile | wfxfile]


• aimstudio.exe (AIMStudio) - 3D (OpenGL) graphics program for visualizing AIMAll data.
  • Load visualization data files (.*viz) created by the other AIMAll programs in order to interactively display various QTAIM-related items such as electron density critical points, bond paths, ring paths, interatomic surfaces, contour maps, relief maps, isosurfaces, critical point properties and atomic properties.  Atomic properties and critical point properties can be displayed in interactive, customizable, sortable, printable tables that can interact with the 3D windows.  AIMStudio includes the ability to save high resolution image files.
  • Windows Usage:  Launch AIMStudio (aimstudio.exe) directly or from a shortcut or drag-and-drop a .*viz file onto it.
  • Command-line Usage:  aimstudio [options] [viz file]

The contents of the Mac OS X version of AIMAll is similar to Windows except that the application executables are wrapped in bundles (e.g., AIMQB.app) that are used to launch the applications via the Finder and the non-system shared libraries that the AIMAll executables depend on are contained in the Frameworks folder.  The executables in each bundle are located in the the Contents/MacOS subdirectory (e.g., AIMQB.app/Contents/MacOS/aimqb).  To run an AIMAll application from the command line, you can use the executable path.  When running AIMExt, AIMInt and AIMSum directly (instead of indirectly via AIMQB), it is recommended to launch them from AIMStudio or from the command line rather than from the Finder.  AIMStudio and AIMQB are typically launched from the Finder, though command-line usage of AIMQB is sometimes useful.

The contents of the Linux version of AIMAll is similar to Windows except that the application executables are contained in the "bin" subdirectory and the non-system shared libraries that the AIMAll executables depend on are contained in the "lib" subdirectory.  "Wrapper" scripts (e.g., aimqb.ish) for setting up the environment for and running the AIMAll executables are provided in the main AIMAll directory.  Icons for the AIMAll applications are provided in the "icons" subdirectory.  Using the provided wrapper scripts and the icons, users can easily take care of setting up the AIMAll applications for quick launching from most Linux desktops.

• Launch AIMQB and you will be presented with an AIMQB dialog which is used to select an AIM wavefunction file (.wfn or .wfx) or a g09 or g03 Formatted Checkpoint file (.fch or .fchk) and specify a variety of calculation options.
   
• If a .fchk or .fch file was selected with AIMQB, then a .wfn or .wfx file having the same base name will automatically be created from it.
   
• After you specify a .wfn, .wfx, .fchk or .fch file and the desired calculation options, AIMQB will automatically run AIMExt to find and characterize all of the critical points of the electron density in the molecule and generate a set of atomic input files (.inp) as well as a .extout file, a .mgp file and possibly a .mgpviz file (for visualization of the molecular graph and electron density critical point properties with AIMStudio).
   
• AIMQB will then automatically run the atomic integration program AIMInt for each .inp file to produce a corresponding set of atomic integration results (.int files).
   
• AIMQB will then automatically run AIMSum to generate a descriptive tabulation of all results (.sum file) and possibly a .sumviz file (for visualization of the molecular graph, electron density critical point properties and atomic properties with AIMStudio).
   
• The numerical results of interest to most users are in the .sum file, which is written to be self-explanatory.
   
• In the event that integration results for one or more atoms are not sufficiently accurate (or are unavailable), you can rerun AIMQB for just those atoms, using the "Atoms to Calculate" fields and different integration options (for example, using the "Promega (1st-Order)" basin integration method and / or higher outer angular integration quadrature).  When the rerun of AIMQB is finished, the .sum file and possibly .sumviz file will automatically be updated to include the results for the newly calculated atoms.
   
• More information about AIMQB can be found at:  http://aim.tkgristmill.com/manual/aimqb/aimqb.html
   
• Interactive 3D visualization of AIMAll results (and more) can be done with AIMStudio by opening the .*viz files produced by AIMQB, AIMExt, AIMInt and AIMSum.

1. Launch AIMQB (Windows: aimqb.exe; Mac OS X Finder: AIMQB.app; Linux terminal: aimqb.ish).
    
2. Click the "Browse" button and select the file C:\AIMAll\test\cyclopropanone\cyclopropanone.wfn
    
3. Click the "OK" button in the AIMQB dialog to start the calculation.
    
4. Wait for a minute or so, until the AIMQB log window says "Job Completed".
    
5. In AIMStudio, select the File menu item "Open in Text Viewer" to look at the file cyclopropanone.sum.
    
6. Note that the magnitude of each atom's L value is acceptably small (the L value is ideally zero) and that the difference between the sum of atomic properties and the corresponding molecular value is small.  For example, the atomic charges sum to 0.000005 compared to the molecular charge of zero, and the sum of scaled atomic kinetic energies is -190.77439 compared to the total molecular energy of -190.77440.
    
7. In AIMStudio, select the File menu item "Open in New Window" and select the cyclopropanone.sumviz file to display the molecular graph derived from cyclopropanone.wfn as well as other data such as electron density critical point properties and atomic properties.  Atomic properties such as the atomic charges can be viewed in the "Atoms Table" by selecting "Table" from the "Atoms" menu.  Atomic property values can also be displayed in the 3D window next to the nuclear spheres by selecting one of the "Atoms->Properties->..." menu items.

• wfnfile ; .wfn ; AIM Traditional Wavefunction file ; Input to aimqb.exe, aimext.exe, aimint.exe and aimsum.exe
   
• wfxfile ; .wfx ; AIM Extended Wavefunction file ; Input to aimqb.exe, aimext.exe, aimint.exe and aimsum.exe
   
• fchfile ; .fch or .fchk ; g09 or g03 formatted checkpoint file ; Input to aimqb.exe
   
• extoutfile ; .extout ; General result file from AIMExt analyses ; Output of aimext.exe
   
• mgpfile ; .mgp ; Summary result file from a full electron density critical point analysis ; Output of aimext.exe
   
• inpfile ; .inp ; Input file for calculating a set of atomic properties ; Input to aimint.exe
   
• intfile ; .int ; Result file from calculating a set of atomic properties ; Output of aimint.exe
   
• mogfile ; .mog ; Intermediate data file for calculating Vee(A,A) and Vee(A,B) ; Output of aimint.exe
   
• sumfile ; .sum ; Result file, combining and summarizing all available results ; Output of aimsum.exe
   
• mgpvizfile ; .mgpviz ; Same content as mgpfile but with bond paths and other special GradRho paths also included for visualization with AIMStudio ; Output of aimext.exe
   
• sumvizfile ; .sumviz ; Same content as sumfile but with bond paths and other special GradRho paths also included for visualization with AIMStudio ; Output of aimsum.exe
   
• iasvizfile ; .iasviz ; Atomic result file containing interatomic surface (IAS) path data and integration ray intersection data (with the IASs and possibly with IsoDensity Surfaces) that can be visualized with AIMStudio ; Output of aimint.exe ; .iasviz files are written to wfname_atomicfiles subdirectory
   
• g2dvizfile ; .g2dviz ; 2D grid of function values (such as the electron density or the Laplacian of the electron density) for generating contour maps and / relief maps with AIMStudio ; Output of aimext.exe
   
• g3dvizfile ; .g3dviz ; 3D grid of function values (such as the electron density or the Laplacian of the electron density) for generating isosurfaces with AIMStudio ; Output of aimext.exe
   
• basvizfile ; .basviz ; Atomic result file containing atomic basin GradRho path data for visualizing (with AIMStudio) atomic basins in terms of a set of GradRho paths that terminate at the nucleus ; Output of aimext.exe ; .basviz files are written to wfname_atomicfiles subdirectory
   
• agpvizfile ; .agpviz ; Atomic result file containing Laplacian of Rho critical point data that can be visualized with AIMStudio ; Output of aimint.exe ; .agpviz files are written to wfname_atomicfiles subdirectory

• Windows XP/Vista/Windows 7/Windows 8, Intel/AMD (x86) processor(s), 32-bit or 64-bit, OpenGL-supporting graphics.
   
• Mac OS X Tiger/Leopard/Snow Leopard/Lion/Mountain Lion/Mavericks, Intel/AMD (x86) processor(s), 32-bit or 64-bit, OpenGL-supporting graphics.
   
• Linux (GLIBC 2.4 or later), Intel/AMD (x86) processor(s), 32-bit or 64-bit, OpenGL-supporting graphics.

• Wavefunctions are limited to S, P, D, F, G and H Gaussian basis function types.
   
• Non-Nuclear Attractors (NNACPs) are not handled in a fully automatic manner.  Each NNACP needs to be manually added to the wfnfile or wfxfile as an atom whose name begins with NNA (e.g., NNA13) and with atomic number = 0, nuclear charge = 0.0, and coordinates equal to the NNACP coordinates.
   
• Wavefunctions derived from semi-empirical calculations are not supported.
   
• For other limitations and issues, please see:  http://aim.tkgristmill.com/knownissues.html

• Portions of "AIMAll (Version 14.11.23)", namely aimint.exe and aimext.exe, are heavily modified and extended versions of corresponding portions of the AIMPAC package ( http://www.chemistry.mcmaster.ca/aimpac ) as it existed in 1994. AIMPAC was developed by members of R.F.W. Bader's research group.
   
• Much of the Quantum Theory of Atoms in Molecules (QTAIM) is described in the book:  "Atoms in Molecules - A Quantum Theory", R.F.W. Bader, Oxford University Press, Oxford, 1990
   
• For additional references please see: http://aim.tkgristmill.com/references.html