****************************************************************** DockingApp RF README file ****************************************************************** DESCRIPTION: DockingApp RF is a user-friendly graphical application for carrying out molecular docking and virtual screening tasks, meant to enable non-experienced users to easily perform such activities and browse the docking results via a three-dimensional visualization. ************************************************************************************************************************************************************ SYSTEM REQUIREMENTS: DockingApp RF has been developed in Java SE 7. The application is meant to run locally on any major operating system (Linux, Windows and Apple OS X systems) provided that they are equipped with a suitable 64-bit Java Virtual Machine (JVM) and with a 64-bit Java Runtime Environment (JRE) version 1.7 or higher and a Python distribution. Packages for Java and Python are available for download for the respective OS. Please note that DockingApp RF takes advantage of a multi-threading algorithm that may use a number of processor cores available on the system, by creating and running a suitable number of concurrent threads to carry out the docking/virtual screening tasks. It DOES NOT run on a 32-bit OS and/or JVM. Please make sure that you are running the program in a 64-bit environment. DockingApp RF requires a minimum of 1GB RAM. For virtual screening against a large number of compounds, at least 4GB RAM is recommended. ************************************************************************************************************************************************************ INSTALLATION AND EXECUTION: Windows 64-bit 1 - If you have not done so before, download and install a 64-bit Java Runtime Environment (JRE) version 7 or higher from www.java.com for your operating system. Please make sure that the environment variable JAVA_HOME is correctly set in your system. If everything is setup correctly, launching the following command: "java -version" from a terminal should display the Java version installed on your system. 2 - Download and unpack the corresponding file from http://www.computationalbiology.it/software/DockingApp_RF_Windows_x64.zip. 3 - Run mgltools_win32_1.5.6_Setup.exe to install MGLTools. 4 - If you have not done so before, install a Python distribution version 3.6 or higher; you can install the included distribution by running python-3.6.8-amd64.exe. IMPORTANT: REMEMBER TO TICK THE CHECKBOX: "Add Python 3.6 to PATH", OTHERWISE THE FOLLOWING STEPS WILL NOT WORK! 5 - Run OpenBabel-2.4.1.exe to install OpenBabel. 6 - Run setup.bat to install the required Python libraries. 7 - Run DockingApp.bat to launch the program. For its first execution, DockingApp RF will ask for the installation directory of MGLTools (default location: C:\Program Files (x86)\MGLTools-1.5.6), the installation directory of Python (default location: C:\Program Files\Python36) and the number of processor cores to be assigned to the program (default: half of the available virtual cores on the machine). Upon confirming them, use the "Run" menu to choose either Docking (1 vs 1), Virtual Screening (1 vs many) or Replicated Docking (1 vs many repetitions of the same ligand) in order to configure and launch the desired task. ------------------------------------------------------------------------------------------------------------------------------------------------------------ Linux 64-bit 1 - If you have not done so before, download and install a 64-bit Java Runtime Environment (JRE) version 7 or higher from www.java.com for your operating system. Please make sure that the environment variable JAVA_HOME is correctly set in your system. If you have trouble setting it up, please refer to the instructions listed on http://www.computationalbiology.it/software/java.html. If everything is setup correctly, launching the following command: "java -version" from a terminal should display the Java version installed on your system. 2 - Download and unpack the corresponding file from http://www.computationalbiology.it/software/DockingApp_RF_Linux_x64.tar.gz. 3 - Run setup.sh (from a terminal, navigate to DockingApp RF's directory and then input: ./setup.sh) to install MGLTools, the included Python 3.6.8 distribution and the required Python libraries. This process will install miniconda3 to ease the installation process. IMPORTANT: remember to say "Yes" when the miniconda3 installation asks you: "Do you wish the installer to initialize Anaconda3 by running conda init?", otherwise the following steps may not work. 4 - Run DockingApp.sh (from a terminal, navigate to DockingApp RF's directory and then input: ./DockingApp.sh) to launch the program. For its first execution, DockingApp RF will ask for the installation directory of MGLTools, the installation directory of Python and the number of processor cores to be assigned to the program (default: half of the available virtual cores on the machine). IMPORTANT: For the installation directory of Python, you must specify the path of the Python distribution that miniconda3 will have installed: if you have not changed the default installation directory of miniconda3, the Python path will be: "~/miniconda3/envs/DockingAppEnv/lib/python3.6". Upon confirming them, use the "Run" menu to choose either Docking (1 vs 1), Virtual Screening (1 vs many) or Replicated Docking (1 vs many repetitions of the same ligand) in order to configure and launch the desired task. ------------------------------------------------------------------------------------------------------------------------------------------------------------ Mac OSX 64-bit 1 - If you have not done so before, download and install a 64-bit Java Runtime Environment (JRE) version 7 or higher from www.java.com for your operating system. Please make sure that the environment variable JAVA_HOME is correctly set in your system. If everything is setup correctly, launching the following command: "java -version" from a terminal should display the Java version installed on your system. 2 - Download and unpack the corresponding file from http://www.computationalbiology.it/software/DockingApp_RF_Mac_x64.zip. 3 - Run the file python-3.6.8-macosx10.9.pkg to install the included Python 3.6.8 distribution. IMPORTANT: after the installation, navigate to the installation directory of the Python distribution (typically "Applications/Python 3.6") and double click on the "Install Certificates.command", in order to install the SSL certificates required for the subsequent steps. 4 - Run setup.sh (from a terminal, navigate to DockingApp RF's directory and then input: ./setup.sh) to install MGLTools and the required Python libraries. 5 - Run DockingApp.sh (from a terminal, navigate to DockingApp's directory and then input: ./DockingApp.sh) to launch the program. For its first execution, DockingApp RF will ask for the installation directory of MGLTools, the installation directory of Python and the number of processor cores to be assigned to the program (default: half of the available virtual cores on the machine). Upon confirming them, use the "Run" menu to choose either Docking (1 vs 1), Virtual Screening (1 vs many) or Replicated Docking (1 vs many repetitions of the same ligand) in order to configure and launch the desired task. ************************************************************************************************************************************************************ TROUBLESHOOTING If you encounter issues in displaying the results of Virtual Screening tasks against a large number of compounds, you may need to increase the memory allocated to the Java Virtual Machine for DockingApp. To do so, open DockingApp.bat (Windows) or DockingApp.sh (Linux and Mac OSX) with a text editor and append the following parameter: -XmxNg, where you should replace "N" with the number of gigabytes to allocate to the JVM. For example, to allocate 4GB to the JVM, your execution file should like the following: - Windows, DockingApp.bat start javaw -jar DockingApp.jar -Xmx4g - Linux/Mac OSX, DockingApp.sh java -jar DockingApp.jar -Xmx4g ************************************************************************************************************************************************************ ************************************************************************************************************************************************************ Please address comments and report bugs to: Fabio Polticelli fabio.polticelli@uniroma3.it Daniele Toti toti@dia.uniroma3.it