\documentclass[10pt]{article}
\usepackage{verbatim,amsthm,amssymb,amsmath,color}
\usepackage[colorlinks=true,urlcolor=blue]{hyperref}

\pdfpagewidth 8.5in
\pdfpageheight 11in

\topmargin 0in
\headheight 0in
\headsep 0in
\oddsidemargin 0in
\evensidemargin 0in
\textwidth 6.5in
\textheight 9in

\newcommand{\sym}{\sc Symbrane}

\newcommand{\link}[2]{%
	\href{#1}{\underline{#2}}%
}

\newenvironment{wordlist}
{
	\begin{list}{}{
		\setlength{\leftmargin}{3.0cm}
		\setlength{\labelwidth}{2.5cm}
		\setlength{\labelsep}{0.5cm}
		\renewcommand{\makelabel}[1]{
			\hfil{\bf ##1}
		}
	}
}
{
	\end{list}
}

\begin{document}

\author{Jeff Martin}
\title{JDSHOT Documentation}
\maketitle

\section{Introduction}

JDSHOT stands for Java $D_n$ Symmetric Homo Oligomer Toolkit. This project contains sources for several tools useful for structure determination of symmetric proteins. One of the tools is essentially an implementation of the {\sym} algorithm adapted to work on $D_n$ proteins. The sources here are specific to structure determination. Other more general code (i.e. reading/writing PDB files) is housed in a separate project called {\em share}.

This document describes the internal organization of code in the JDSHOT project and how to invoke its tools. Information regarding resource files and testing can be found in the documention for the {\em share} project where it is handled similarly.

\section{Tools}

Each tool is an executable command-line program housed in a JAR interface. These JARs reside in the {\em dist} directory of the project. To invoke a tool from the command-line, use a command of the following form:
\begin{flushleft}
{\tt
	java -jar path/to/jdshot-\$(TOOL).jar \$(ARGUMENTS)
}
\end{flushleft}
where {\tt \$(TOOL)} is the name of a tool in the toolkit (each explained below) and {\tt \$(ARGUMENTS)} are the input supplied to the tool. All the tools use a unified command-line parsing module which offers a few useful features. Each tool is self-documenting. Simply invoke the tool without any arguments and it will return a list of the required and optional arguments along with a short description of each. The {\tt --help} argument will also report the documentation. Additionally, these tools allow passing of arguments by a file instead of the command line. Use the {\tt --file \$PATH} argument to supply a file from which to read arguments. Argument files are the preferred way to invoke these tools simply because they are easy to edit and they can be saved in \link{http://subversion.tigris.org}{SVN}. An example argument file is provided for each tool.

It is also possible to invoke these tools during development from the {\em bin} folder. Simply set the classpath to the bin folder and invoke the appropriate tool by its class:
\begin{flushleft}
{\tt
	java -cp path/to/bin edu.duke.donaldLab.jdshot.\$(TOOL)Main \$(ARGUMENTS)
}
\end{flushleft}
All of the tools in the toolkit are described briefly below.
\begin{wordlist}
	\item[Search]
		{\sym} implementation. Multi-threaded.
	\item[Analyze]
		Calculates NOE satisfaction scores and other statistics for the set of grid cells output by an iteration of the search tool. Multi-threaded.
	\item[StericFilter]
		Filters a set of cells/points such that representative structures with significant backbone clashes are removed. The significance level is a configurable parameter. Multi-threaded.
	\item[Cluster]
		Performs clustering on a set of grid cells/points. Single-threaded.
	\item[Minimize]
		Invokes CNS to minimize representative structures for a set of grid cells/points. Single-threaded or MPI-cluster-runnable.
	\item[Test]
		Runs the suite of unit tests for the project.
	\item[Compute]
		This is sort of a catch-all tool to perform small tasks that don't need a separate tool. It accepts a few ``standard'' arguments such as paths to PDB files and NOEs, but it really doesn't have a stable interface. The behavior of this tool is configured primarily by a programmer at compile-time. It serves as a quick prototyping environment similar to scripting environments. The source for this tool is also very messy as it changes rapidly to perform different functions.
	\item[RigidBody]
		Leftover code from a class project in computational geometry. This isn't really part of the toolkit, but it is listed here for completeness. It's safe to ignore this code. It will be eventually removed.
\end{wordlist}


\section{Inputs}

While each tool has a slightly different set of input parameters, some inputs are common to many tools. These are listed below:

\begin{wordlist}
	\item[monomerPath]
		Path to a PDB file containing single subunit
	\item[oligomerPath]
		Path to a PDB file containing the full number of subunits arranged in their correct configuration
	\item[noesPath]
		Path to a MR file containing assigned NOEs. Comments are also allowed.
	\item[subunitOrder]
		This one is a little less straightfoward and will require some explanation. To make the implementation simpler, much of the code that deals with oligomer structures assumes that the subunits are provided in ring-order. Meaning, choose an arbitrary subunit to be subunit {\tt A}. Then the adjacent subunit clockwise to {\tt A} becomes {\tt B} and so on around the ring. This argument provides a mapping between the names used in the PDB file, and this ring-order that the tools expect.
\end{wordlist}


\section{Packages}

All packages are under the root package/namespace: edu.duke.donaldLab.jdshot

\begin{wordlist}
	\item[(root)]
		The root package houses the main functions for each of tools in the toolkit
	\item[analyze]
		code for the analysis tool
	\item[cluster]
		code for the cluster tool
	\item[compute]
		code for the compute tool
	\item[grid]
		Contains classes for representing and dealing with grid cells/points. Much of this code is specific to $D_n$ symmetry.
	\item[minimize]
		code for the minimize tool
	\item[rigidBody]
		code for the RigidBody tool
	\item[search]
		code for the search tool
	\item[stericFilter]
		code for the steric filter tool
	\item[test]
		unit tests code. These classes are automatically excluded from the distribution JARs.
\end{wordlist}

\section{Compiling}

Compiling the distribution files (the end-user JARs) is handled through \link{http://ant.apache.org}{Ant} build scripting. The {\em dist} task performs the full compilation and creation of the distribution files (JARs).

\end{document}
