
=====================================================================
   DISCO
=====================================================================

Source distribution

v1.0
2011-05-24

Jeffrey W. Martin and Bruce R. Donald
disco@cs.duke.edu

Copyright © 2011 Bruce Donald Lab, Duke University



=====================================================================
   LICENSE
=====================================================================

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
USA

Contact Info:
	Bruce Donald
	Duke University
	Department of Computer Science
	Levine Science Research Center (LSRC)
	Durham
	NC 27708-0129 
	USA
	brd@cs.duke.edu

<signature of Bruce Donald>, May 2011
Bruce Donald, Professor of Computer Science


=====================================================================
   CITING DISCO
=====================================================================

When publishing work that uses DISCO, please cite one of the following:

[1] Jeffrey W. Martin, Anthony K. Yan, Chris Bailey-Kellogg, Pei Zhou, and
Bruce R. Donald. A graphical method for analyzing distance restraints
using residual dipolar couplings for structure determination of symmetric
protein homo-oligomers. Protein Science, 20(6):970–985, 2011.

[2] Jeffrey W. Martin, Anthony K. Yan, Chris Bailey-Kellogg, Pei Zhou, and
Bruce R. Donald. A geometric arrangement algorithm for structure deter-
mination of symmetric protein homo-oligomers from NOEs and RDCs. In:
Proceedings of The Fifteenth Annual International Conference on Research in
Computational Molecular Biology (RECOMB), Vancouver, BC, 2011. Springer
Berlin, pages 222–237.


=====================================================================
   ORGANIZATION
=====================================================================

In general DISCO was designed around the following philosophy:

	Write as little code as possible.
	Use standard libraries when they save effort.
	Write as much of the code as possible in Java.
	Except main methods, instead script those with Python.
	
As a result, the vast majority of the DISCO code is in the form of Java
sources with two exceptions.

Since DISCO relies on the CGAL library to perform the exact geometric
calculations, and the CGAL library was written in C/C++, some of DISCO's
code is also in C++. This C++ code creates a "glue" layer so that CGAL's
functions can be called directly from Java.

The second exception is main methods. Instead of directly invoking Java code,
almost all of DISCO's code is executed through Python scripts using a
Java-Python bridge called JPype. DISCO's Java code is highly modular,
so the Python scripts provide an extremely flexible way to tie together the
necessary Java components into the final programs. This approach also allows
the end-user to customize the high-level operation of DISCO without needing
to recompile code. The customization can be accomplished by merely modifying
the Python scripts.

DISCO is composed of three separate eclipse projects, each of which is described below.

	jdshot - The Symmetric Homo-Oligomer Toolkit (the jd will eventually be dropped)
	
		This project houses all the code specific to DISCO (among other things) and
		is comprised of a mix of Java classes, Python modules, and a light Python
		scripting layer on top.
	
	share - a generic library for manipulating protein structures and NMR data
	
		This project is not specific to DISCO and could be adapted to use as a starting
		point for any protein modeling software project. It is a mix of Java classes and
		Python modules.
	
	shotCgal - A Java JNI wrapper for the CGAL C/C++ library
	
		This project is purely C++ code and provides Java bindings for a small subset
		of the CGAL library -- specifically, planar arrangements of circular curves.

Each of these projects was designed and built in the Eclipse IDE (http://www.eclipse.org/),
although the final distribution files (such as this distribution) are assembled using ant scripts.

For Windows users, a Visual Studio "solution" is available to compile the shotCgal project.


=====================================================================
   DEPENDENCIES
=====================================================================

To compile DISCO, the following libraries must be installed:

	Java v6+ JDK                        http://www.java.com/en/download/
	CGAL v3.6.1+ (with C/C++ headers)   http://www.cgal.org/
	Boost (with headers and libs)       http://www.boost.org/
	
To run DISCO, the following libraries must also be installed:

	Python v2.6 (not 2.7!)              http://www.python.org/
	JPype v0.5.4+ for Python 2.6        http://jpype.sourceforge.net/
	Xplor-NIH                           http://nmr.cit.nih.gov/xplor-nih/

Please make sure the "bitness" of Java, Python, and JPype match. For instance, if
you've installed the 64 bit Java, you must also use the 64 bit versions of Python
and JPype.

For Linux users, your distribution will most likely already have packages for
Java, Python, and JPype. Your distributon's package manager will offer the
simplest option for installation. Xplor-NIH, however, will require manual
installation. Additionally, linux users will need to install the CGAL package.
Alternatively, one could download it from the CGAL website and install it manually:

	CGAL v3.6.1+                       http://www.cgal.org/

For Windows users installing the 64 bit versions of Java and Python:

	Sadly, JPype is not available in 64 bits for windows, so I've taken
	the liberty of compiling a 64 bit version from the JPype sources. See the
	following folder in the distribution for instructions on how to install
	the 64 bit version of JPype:
	
		extra/jpype64

After installing Xplor-NIH, make sure the directory for the pyXplor executable file
has been added to the PATH environment variable. One could alternatively add a symlink
for pyXplor to ~/bin, /usr/local/bin, or /usr/bin.

If pyXplor is not available "on the PATH," DISCO's structure minimization routines
will fail and DISCO will not finish successfully on Linux.



=====================================================================
   COMPILING DISCO - jdshot and share projects
=====================================================================

These instructions assume the reader has a basic familiarity with
the Eclipse IDE and the Java development tools. If needed, the following
tutorial offers a brief introduction to Java development using Eclipse:

	http://www.vogella.de/articles/Eclipse/article.html


1. Import the jdshot and share projects into Eclipse.

2. Resolve any Java build path problems that may remain after the import.
   
   For instance, both projects should depend on your local JDK installation.
   The jdshot project must depend on the share project. The jdshot and share
   projects must have all the jar files in their libs directory available on
   the classpath.

3. Once the build path has been properly configured, Eclipse should be able to
   compile the Java sources without trouble using its own project-based internal
   build system.

All of the Python scripts and modules, of course, won't need explicit compilation.


=====================================================================
   COMPILING DISCO - shotCgal project - windows
=====================================================================

Since the shotCgal project is comprised of C++ code, its build process is
somewhat more complicated than the build process for jdshot and share. To
simplify the compilation process in Windows as much as possible, a Visual
Studio project has been created to build this project.

1. Open the solution file (shotCgal.sln) from the shotCgal folder in Visual Studio.

2. Make sure the CGAL and Boost C/C++ headers and libs are available to the Visual Studio compiler.
      
3. Build the solution.

The final DLL file should appear in the releaseBinaries folder.


=====================================================================
   COMPILING DISCO - shotCgal project - linux
=====================================================================

Compiling the shotCgal project under Eclipse requires the C/C++ Developer Tools (CDT) plugin:

	http://www.eclipse.org/cdt/

NOTE: Eclipse does generate makefiles to manage its internal C/C++ build process.
      If you're opposed to compiling C/C++ code in Eclipse (or are just looking for an
      easier way), there's a chance the makefiles will work on the terminal with make.

1. Import the shotCgal project into Eclipse.

2. build the default debug build configuration using Eclipse's internal build system.

3. If desired, one also use the cross-compiling release build configurations.
   
   The resulting .so files will be post-build-copied into the releaseBinaries folder.


=====================================================================
   RUNNING DISCO
=====================================================================

Once all sources have successfully compiled, DISCO can be run by executing the
Python scripts in the jdshot/scripts folder.

The Python interpreter must know where to find the Python modues in both the
jdshot and share projects. This can be accomplished by modifying the
PYTHONPATH environment variable:

	http://docs.python.org/using/cmdline.html#envvar-PYTHONPATH
	
or by using the PyDev plugin for Eclipse:

	http://pydev.org/

Additionally, the JPype JVM launcher must know where to find the compiled Java classes.
To use the classes from the Eclipse project's bin folder (instead of the packaged
release classes, useful for debugging), modify the jdshot/modules/disco.py Python
module (under the "# start the jvm" comment) to add the class and lib folder paths for
both projects:

	jvmInstance.addPath( "/path/to/jdshot/bin" )
	jvmInstance.addPath( "/path/to/share/bin" ) 
	jvmInstance.addLibsDir( "/path/to/jdshot/lib" )
	jvmInstance.addLibsDir( "/path/to/share/lib" )


=====================================================================
   BUILDING DISCO RELEASE PACKAGES
=====================================================================

1. Open the jdshot/buildDisco.xml file in the Ant view in Eclipse

2. Run the dist and distSource tasks.

   The release packages will be saved to the jdshot/dist folder.

Alternatively, Ant can be invoked from the command-line.


=====================================================================
   TROUBLESHOOTING
=====================================================================

If you have difficulties or questions, feel to contact us with
inquiries by email:

	disco@cs.duke.edu
