To run BROOD, you will need to obtain a license file from OpenEye Scientific Software (firstname.lastname@example.org). OpenEye will send a file called oe_license.txt.
Warning: Do not edit or modify this file.
BROOD will ask for the license file the first time the program is opened.
If you intend to run multi-processor BROOD via Open MPI, only the master machine needs access to the license file. The necessary MPI resources are included in the BROOD installation for most standard platforms.
On Windows, the environment variables can be set under the system control panel.
On all platforms, BROOD is installed through a download from http://www.eyesopen.com.downloads. You will need to provide account information (login) and your license key. (If you don’t have an account, register for one now. You will be prompted to upload your license key during the registration process.)
Because memory is limited for 32-bit applications, to avoid crashes due to running out of available memory, memory-intensive tasks are best performed using 64-bit applications.
The basic installation steps for all platforms are:
Linux distributions are provided as a gzipped tarball of the distribution tree described below. Installation is performed by simply untarring the file in the desired location. The top-level directory in the tarball is named openeye. Distributions for different Linux variants can be installed into the same location, allowing multiple Linux versions to be run from a single shared directory.
To ensure that the installed applications can be called from the command line, the full path of the openeye/bin subdirectory to the PATH environment variable must be added. For instance, if the distribution was installed into /usr/local/openeye, the PATH environment variable should contain /usr/local/openeye/bin.
Under the top-level openeye directory are the following subdirectories:
|arch:||This directory contains the collection of platform-specific subdirectories. Each subdirectory contains the actual installed executables and support libraries for the associated platform. Under each platform-specific subdirectory, there is a subdirectory for each application. Within that subdirectory is another subdirectory for each version of the application.|
|bin:||This directory contains a startup script for each application that has been installed. This script determines the current platform at run time and calls the appropriate executable in the arch directory. This script enables the easy coexistence of multiple platforms and versions of any OpenEye application in the same distribution tree.|
|data:||This directory contains all the associated data for the installed applications. Each application has its own subdirectory; within that subdirectory is another subdirectory for specific versions of that application.|
|docs:||This directory contains all of the documentation associated with the installed applications. Each application has its own subdirectory; within that subdirectory is another subdirectory for specific versions of that application.|
|examples:||This directory contains all of the examples associated with the installed applications. Each application has its own subdirectory; within that subdirectory is another subdirectory for specific versions of that application.|
The startup script described above has the same name as the installed executable with which it is associated. When the script is called, it will attempt to determine the current platform and run the appropriate executable. If an appropriate executable cannot be found, the script will report that information and produce a list of the currently installed platforms. This autodetection process can be overridden by setting one of two environment variables:
OE_ARCH can be used to specify a colon-separated list of compatible distributions for the current platform. For example:
Specification of this environment variable overrides the autodetection process. If none of the compatible distributions listed are found, the script will fall back to the autodetection process.
APPNAME_OE_ARCH can be used to specify a colon-separated list of compatible distributions for a specific application (as specified by changing the APPNAME text in the environment variable name).
Specification of this environment variable overrides the OE_ARCH environment variable as well as the auto-detection process. If none of the compatible distributions listed are found, the script will fall back to the OE_ARCH list first and then to the autodetection process. Specifying this variable provides a simple way to customize the behavior for individual applications on non-standard platforms.
The startup script also supports a few commandline-arguments, including:
Windows distributions are provided as a standard EXE installer. To install, double-click the executable and follow the installation instructions. By default,
OpenEye applications will install into the C:\Program Files (x86) directory for 32-bit applications or C:\Program Files for 64-bit applications.
When the application is installed, BROOD and vBROOD icons will be placed on the desktop and an OpenEye group with an application-specific subgroup will be added to the Start menu. On Windows 8.1, the OpenEye group can be found under the Apps by Name area accessed from the Start screen by clicking the arrow at the bottom of the screen. For earlier Windows versions, the OpenEye group is found under All Programs in the Start menu as a folder named OpenEye. On all versions, this subgroup contains a link to a Windows command shell with PATH settings already defined to allow users to simply type the executable name at the prompt without concern for where the executable is actually installed. The subgroup also contains a link to the directory Extras. This contains documentation, examples, and other application-specific material.
Mac OS X distributions are provided as a DMG disk image. For installation:
To view the BROOD directory hierarchy, navigate to the Applications folder and right click on the BROOD application. From the Contents menu, select Show Package Contents.
MacOS This directory contains the application executables.
docs This directory contains all documentation associated with the installed applications.
examples This directory contains all the examples associated with the installed applications.
For command-line-only tools, an application named Install Command Line Support can be run from the DMG file. This allows users to add the application’s location to their PATH environment variable. Command-line applications can also be run from the Applications folder, in which case they will open a terminal window with a properly configured environment.
This application uses the Open MPI implementation of MPI, found at http://www.open-mpi.org/. This version includes a full Open MPI install, so no additional software is needed.
There are two requirements to run under Open MPI.
- Every machine in the cluster must have the same version of the application installed.
- The path to the application’s bin directory must be in the PATH environment variable on all machines, and be positioned before any other locations that may contain MPI executables (orted, mpirun, etc).
To run under Open MPI on a single machine:
> [application executable] -mpi_np [number of processes] [other application options]
To run Open MPI on multiple machines, begin by generating a text file that will include the MPI hosts you plan to use and the number of processes on each (for this example, we’ll call this file hosts). The file should contain a line for each machine with the name of the machine, a space, then slots=N, where N is the number of processors for your run. For this example, the file looks like this:
c1 slots=4 c2 slots=4 c3 slots=4 c4 slots=4 c5 slots=4
The following command-line will then start a job with one master and 19 slaves.
> [application executable] -mpi_hostfile hosts [other application options]
The master will be on c1, where the job is being started. All the input/output for the run is controlled from the master machine, and all results and logging information are combined.
Most files in this release are marked with the copyrights of the organizations who have edited them. The copyrights below are in no particular order and generally reflect members of the Open MPI core team who have contributed code to this release. The copyrights for code used under license from other parties are included in the corresponding files. Copyright (c) 2004-2010 The Trustees of Indiana University and Indiana University Research and Technology Corporation. All rights reserved. Copyright (c) 2004-2010 The University of Tennessee and The University of Tennessee Research Foundation. All rights reserved. Copyright (c) 2004-2010 High Performance Computing Center Stuttgart, University of Stuttgart. All rights reserved. Copyright (c) 2004-2008 The Regents of the University of California. All rights reserved. Copyright (c) 2006-2010 Los Alamos National Security, LLC. All rights reserved. Copyright (c) 2006-2010 Cisco Systems, Inc. All rights reserved. Copyright (c) 2006-2010 Voltaire, Inc. All rights reserved. Copyright (c) 2006-2011 Sandia National Laboratories. All rights reserved. Copyright (c) 2006-2010 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Copyright (c) 2006-2010 The University of Houston. All rights reserved. Copyright (c) 2006-2009 Myricom, Inc. All rights reserved. Copyright (c) 2007-2008 UT-Battelle, LLC. All rights reserved. Copyright (c) 2007-2010 IBM Corporation. All rights reserved. Copyright (c) 1998-2005 Forschungszentrum Juelich, Juelich Supercomputing Centre, Federal Republic of Germany Copyright (c) 2005-2008 ZIH, TU Dresden, Federal Republic of Germany Copyright (c) 2007 Evergrid, Inc. All rights reserved. Copyright (c) 2008 Chelsio, Inc. All rights reserved. Copyright (c) 2008-2009 Institut National de Recherche en Informatique. All rights reserved. Copyright (c) 2007 Lawrence Livermore National Security, LLC. All rights reserved. Copyright (c) 2007-2009 Mellanox Technologies. All rights reserved. Copyright (c) 2006-2010 QLogic Corporation. All rights reserved. Copyright (c) 2008-2010 Oak Ridge National Labs. All rights reserved. Copyright (c) 2006-2010 Oracle and/or its affiliates. All rights reserved. Copyright (c) 2009 Bull SAS. All rights reserved. Copyright (c) 2010 ARM ltd. All rights reserved. Copyright (c) 2010-2011 Alex Brick . All rights reserved. Copyright (c) 2012 The University of Wisconsin-La Crosse. All rights reserved. Additional copyrights may follow Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer listed in this license in the documentation and/or other materials provided with the distribution. - Neither the name of the copyright holders nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. The copyright holders provide no reassurances that the source code provided does not infringe any patent, copyright, or any other intellectual property rights of third parties. The copyright holders disclaim any liability to any recipient for claims brought against recipient by any third party for infringement of that parties intellectual property rights. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Included in the BROOD product is a large database of fragments generated by fragmenting the ChEMBL molecular database [Bento-2014]. This database is available for download from http://www.eyesopen.com/db-downloads in a platform-independent format. For user convenience, the database is available in either ZIP or TAR.GZ format, though either file can be used on any platform.
The BROOD database is large (>5G) and will take 15-30 minutes to download with a good internet connection. When the download is complete, move the file to a convenient location and unpack (either unzip or untar/gzip) the database. The default BROOD database is a directory full of preorganized files that are optimized to make common BROOD searches execute quickly.
After unpacking the default database, set it as the default database:
The BROOD product contains four applications as well as a script that can be run in conjunction with OpenEye’s molecular visualiser, VIDA. Two of the programs (BROOD and vBROOD) and the VIDA script provide the ability to generate queries, search for similar fragments, and visualize and triage the resulting analogs. The additional pair of applications, CHOMP and BROODDBMERGE, are utilities that generate and merge BROOD fragment databases, respectively.
The first time you open vBROOD, the program will prompt for:
- Click Yes to edit preferences.
- In the vBROOD preferences box, click Browse to navigate to the location where VIDA is installed or type the path to its location.
- Click Yes to edit preferences.
- In the vBROOD preferences box, click Browse to navigate to the location where your BROOD database was saved, or type in the path to the database.
vBROOD is now ready to use. Chapter 4 explores BROOD through tutorials. For detailed instructions for using the BROOD graphical interface (vBROOD) and viewing results in VIDA, see Chapter 5 and Chapter 6, respectively.