.. _installation: ************** Installing RMG ************** .. index:: DASSL, DASPK, DAEPACK, requirements, license .. _licenserequirements: License Requirements ==================== RMG is intended to be an open source program, available to the general public free of charge. The primary RMG code is distributed under the terms of the `MIT/X11 License <http://www.opensource.org/licenses/mit-license.php>`_. Although many of RMG's dependencies are also available under compatible open source licenses, there remain a few dependencies with :ref:`more restrictive licences <license>`. **It is the user's responsibility to ensure these licenses have been obtained.** .. _installrequirements: Installation of Binary Package ============================== Multiple binary releases are available from `the RMG website <../download.html>`_\ , including Windows 32-bit and Linux x86. The binary packages provides all of the executables necessary for a functional RMG, although some advanced features require additional third-party applications. To install the binary packages, follow steps 1-3 in the source section for your operating system (:ref:`linuxinstallation` or :ref:`windowsinstallation`). A Windows installer is also provided. The user has the option of installing all or part of the binaries, source, documentation, and examples. The installer will automatically set the ``RMG`` system variable to the installation directory. Whether you install a binary or a source package, you will need: The Java SE Runtime Environment (JRE), version 6. This is available from http://java.sun.com/javase/downloads/index.jsp. To generate InChIs and to convert from InChIs/.mol files to adjacency lists you will need: The IUPAC International Chemical Identifier InChI version 1 (software version 1.01). This is available from http://www.iupac.org/inchi/download/index.html Additional information about the advanced RMG features and the third-party software required to install them can be found in the following section. .. _compiling_from_source: Compiling RMG from Source ========================= Compilation Prerequisites -------------------------- To build a functional version of RMG from source you will need the following: The Java SE Development Kit (JDK), version 6. This is available from http://java.sun.com/javase/downloads/index.jsp. The Differential Algebraic System Solver (DASSL). This is available in the public domain from http://www.cs.ucsb.edu/~cse/software.html. A Fortran 90 compiler. We recommend the free g95 compiler, available from http://www.g95.org/. A Fortran 77 compiler. The g95 compiler can successfully build the Fortran 77 source code as well. The Basic Linear Algebra Subprograms (BLAS). This is present in most Linux distributions, and is also available from http://www.netlib.org/blas/. Although only the BLAS source code is required, we recommend installing the full package if possible. The Linear Algebra PACKage (LAPACK). This is present in most Linux distributions, and is also available from http://www.netlib.org/lapack/. Although only the LAPACK source code is required, we recommend installing the full package if possible. Although not required, we also recommend that you obtain: GNU make. This controls the generation of Fortran executables, and is present in most Linux distributions. More information can be found at http://www.gnu.org/software/make/. Apache Ant. This controls the generation of Java executables. More information can be found at http://ant.apache.org/. .. To perform sensitivity analysis on the models generated, you will also need: .. * **The Large Scale Differential Algebraic Equation Solver with Sensitivity Analysis (DASPK), version 3.1.** DASPK 3.1 is *subject to copyright restrictions*, but available for research purposes from http://www.cs.ucsb.edu/~cse/software.html. .. * **The Differential Algebraic Equation PACKage (DAEPACK) library file.** This can be obtained with the JACOBIAN software, which can be obtained at no cost for registered acadamic users from http://www.numericatech.com/academia.htm. To generate InChIs and to convert from InChIs/.mol files to adjacency lists you will need: The IUPAC International Chemical Identifier InChI version 1 (software version 1.01). This is available from http://www.iupac.org/inchi/download/index.html .. _linuxinstallation: Linux Installation ------------------ To install RMG on a Linux computer: 1. Create the directory in which you want to install RMG. For the purposes of this document, we will set the directory to :file:`/usr/local/rmg`. Depending on where you choose to install RMG, you may need superuser privileges. :: $ mkdir /usr/local/rmg 2. Set the RMG environment variable as the directory created in the first step. In a bash shell you would type, for our example, :: $ export RMG=/usr/local/rmg In a C shell you would type, for our example, :: $ setenv RMG /usr/local/rmg To avoid typing this line each time, append it to your :file:`~/.bashrc` (bash shell) or :file:`~/.cshrc` (C shell) file. 3. Obtain the source code (See :ref:`download`). Download the file :file:`rmg-3.2-linux-i386.tar.gz` or :file:`rmg-3.2-source.tar.gz`, ungzip and untar it, and move its contents to the :file:`$RMG` directory. :: $ tar -xvzf rmg-3.2-source.tar.gz $ mv rmg3/* $RMG Step 4 is only required if you are working with the source package. Binary packages are available for several platforms and will already contain the compiled executables. 4. Compile the programs. If you are working with the source package, you will need to compile RMG and its supporting Fortran programs. To do this, change to the directory :file:`$RMG` and execute the makefile. The make script will compile four programs: fame, frankie, DASSL, and GATPFit. It will then call the ant build script to compile RMG itself. :: $ cd $RMG $ make If you only wish to compile the RMG Java code, you can do so by typing:: $ cd $RMG $ ant jar At this stage you will have a functional version of RMG. The remaining steps are only required to enable some advanced features. .. The next few steps are required only if you want RMG to be able to perform sensitivity analysis on the models generated. Currently RMG uses DASPK3.1 (see Section :ref:`installrequirements`) to perform sensitivity analysis. Analytical Jacobian and partial derivatives with respect to rates of reactions and Gibbs free energy of molecules are generated using the automated differentiator of DAEPACK. .. 6. Obtain the DAEPACK library file. Make a symbolic link of the library file in a directory in your library file search path, e.g. :file:`/usr/lib`. .. 7. Download daspk31.tgz and untar it using the command ``$ tar -zxvf daspk31.tgz``. Copy all the source files (:file:`*.f` files) from the untarred directories :file:`ad_solver`, .. :file:`preconds` and :file:`solver` into the directory :file:`$RMG/software/ODESolver/daspk`. Change to the directory :file:`$RMG/software/ODESolver`and execute the makefile with the ``daspk`` option. Copy the resulting executable, :file:`daspkAUTO.exe`, to :file:`$RMG/software/ODESolver/daspkAUTO.exe` if this is not already done. :: .. $ tar -xvzf daspk31.tgz .. $ mv ad_solver/*.f $RMG/software/ODESolver/daspk .. $ mv preconds/*.f $RMG/software/ODESolver/daspk .. $ mv solver/*.f $RMG/software/ODESolver/daspk .. $ cd $RMG/software/ODESolver .. $ make daspk .. $ cp daspkAUTO.exe $RMG/software/ODESolver/daspkAUTO.exe .. You are now ready to run RMG with sensitivity analysis support. The next few steps are required only if you want RMG to be able to generate InChIs for the species present in the reaction mechanism. 5. Download the InChI version 1 (software version 1.01) source code and Application Program Interface (API). 6. Change to the :file:`InChI-1-API/cInChI/gcc_makefile` directory and execute the makefile. Copy the resulting executable :file:`cInChI-1.exe` to the :file:`$RMG/bin` folder. :: $ cd InChI-1-API/cInChI/gcc_makefile $ make $ cp cInChI-1 $RMG/bin You are now ready to generate InChIs in RMG. .. _windowsinstallation: Windows Installation -------------------- To install RMG on a Windows computer: 1. Create the directory in which you want to install RMG. Depending on where you choose to install RMG, you may need administrator privileges. 2. Set the RMG environment variable as the directory created in the first step. * Go to ``Start --> Control Panel --> System`` (may need to switch to Classic Control Panel view). Click on the ``Advanced`` tab, then click on ``Environment Variables``. * In the lower half of the ``Environment Variables`` window (System variables), click ``New``. * In the ``New System Variable`` window, in the ``Variable`` name field, type ``RMG``. In the ``Variable`` value field, type the directory in which RMG was installed. * Click OK twice to confirm the change. 3. Obtain the source code (See :ref:`download`). Download the file :file:`rmg-3.2-win32-i386.zip` or :file:`rmg-3.2-source.tar.gz`, decompress it, and move its contents to the :file:`%RMG%` directory. Steps 4 and 5 are only required if you are working with the source package. Binary packages are available for several platforms and will already contain the compiled executables. 4. Obtain BLAS and LAPACK DLL files. You can create these yourself by downloading the BLAS and LAPACK sources, or you can download them from our `GitHub downloads <http://github.com/GreenGroup/RMG-Java/downloads>`_ page. 5. Compile the programs. If you are working with the source package, you will need to compile RMG and its supporting Fortran programs. The easiest way to do the latter is to execute the file :file:`make.bat` in the :file:`%rmg%` directory. The batch script does not compile the RMG source; for this you will need ant. The next few steps are required only if you want RMG to be able to generate InChIs for the species present in the reaction mechanism. 6. Download the InChI version 1 (software version 1.01) source code and Application Program Interface (API) from `IUPAC <http://www.iupac.org/inchi/download/index.html>`_ and unzip the file. Navigate to the :file:`InChI-1-API\\cInChI\\vc6_project\\Release` folder. Copy the executable file :file:`cInChI-1.exe` and paste it in the :file:`"%rmg%"\\bin` folder. You are now ready to generate InChIs in RMG. RMG Viewer/Editor (RMGVE) Installation ====================================== The RMGVE is an accompanying software which can be used for viewing the database of RMG and also the models generated by RMG. The RMGVE is present along with RMG in the :file:`$RMG/RMGVE` directory and need not be downloaded separately. To run the RMGVE just go to the :file:`$RMG/RMGVE` directory and execute ``RMGVE 20080101.bat`` on the command line. The RMGVE directly reads the RMG database :file:`$RMG/database/RMG_database` which includes the thermo data and the kinetics data. Please refer to :ref:`Using the RMGVE <modification>` to see how to modify the RMG database. Installation of Dependencies for 3D-geometry-based Thermodynamic Property Calculation ===================================================================================== Several dependencies are required to use 3D-geometry-based thermodynamic property calculation features of RMG. These include (recommended versions in parentheses): 1. Python (2.x, with x=5 or higher) http://www.python.org/ 2. cclib (see below) 3. RDKit (Q2 2009 or later) http://rdkit.org/ 4. OpenBabel (2.2.0 or later) http://openbabel.org 5. InChI (1.02beta or 1.03) http://www.iupac.org/inchi/download/index.html 6. SYMMETRY (v. 1.15 or later) http://www.cobalt.chem.ucalgary.ca/ps/symmetry/ (from Serguei Patchkovskii at the University of Calgary) 7. GAUSSIAN03 and/or MOPAC2009 http://www.gaussian.com/ and http://openmopac.net/downloads.html With the exception of GAUSSIAN03 and MOPAC2009, all of the above may be obtained freely and are open-source. In the case of MOPAC2009, the software may be obtained freely for academic, not-for-profit use. Below are some notes for each of these and instructions on getting them to work properly with RMG: Python You should add the Python installation directory to the PATH environment variable such that typing "python" at the command-line brings up the Python prompt. NOTE: This will probably need to be done manually. cclib Modified portions of the source code for cclib 1.0 (http://cclib.sourceforge.net/) are included in the /source/cclib/ directory (licensed under LGPL 2.1). No action should be required on the part of the user. RDKit The typical installation process for RDKit should set the RDBASE environment variable and no further action on the part of the user should be required. Note: If installing from the Windows binaries, you will also need to install numpy and set environment variables as described at http://code.google.com/p/rdkit/wiki/InstallingOnWindows . OpenBabel The OpenBabel installation directory (e.g. C:\Program Files\OpenBabel-2.2.0) should be added to the PATH environment variable such that typing "babel" at the command-line produces output (including version information) from OpenBabel. This should be done automatically by the OpenBabel installer, and no manual intervention should be required. InChI Installation of InChI is described above. The InChI executable should be placed in the /bin/ RMG directory. SYMMETRY For Windows, it is recommended that the compiled .exe file available from http://www.cobalt.chem.ucalgary.ca/ps/symmetry/ (via symmdos.zip) be used. This file should be copied into RMG's /bin/ directory. On other platforms, you must compile the SYMMETRY.EXE executable yourself and place the executable in RMG's /bin/ directory. MOPAC2009 The environment variable MOPAC_LICENSE should be set (e.g. c:\Users\User1\Documents\MOPAC\). This should be done automatically by the MOPAC installer, and no manual intervention should be required. GAUSSIAN03 Add the GAUSSIAN03 directory (e.g. "c:/G03W/") to the PATH environment variable. NOTE: This will typically need to be done manually.