\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{\link}[2]{%
	\href{#1}{\underline{#2}}%
}

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

\begin{document}

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

\section{Introduction}

The Share framework is intended to be a library of general APIs and codes to perform mundane tasks related to protein modeling. To the author's knowledge, no general freely-available APIs implemented in Java exist to perform these tasks. To be fair, the implementations provided in this project are in many clases simplistic (and in a few cases incomplete), but they perform sufficiently well to support the needs of the JDSHOT project when working with p53 - the only project currently built on top of Share. Also, the author does not suggest that the implementations of functions/classes here are necessarily the best way to do it and would be happy to hear suggestions for improvement.

It is the author's goal that this framework be (as the name might imply) shared with developers interested in protein modeling to provide a basis for starting new projects quickly.

\section{Packages}

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

\begin{wordlist}
	\item[(root)]
		The root package houses the main function for unit testing
	\item[atomType]
		Code for specifying types for atoms (e.g., C.1, C.ar, N.1, N.3) and van der Waal radii. This is configured using the {\tt .atomTypes} resource files.
	\item[bond]
		Code for specifying bonding structure for sets of atoms. Bonds are represented as edges in a graph and can be configured per amino acid and backbone state (i.e. normal vs terminus) using the {\tt .bonds} resource files. Performing BFS in this graph is also supported using iterators. This package is incomplete (not all amino acids are defined), but is sufficient for p53.
	\item[clustering]
		This code provides methods to cluster sets of points using an implicit Euclidean distance metric as well as using a distance matrix. The Euclidean method is rather sophisticated and fast (!), but the distance matrix method is currently very naive and extremely slow.
	\item[geom]
		These classes represent generic geometric objects such as boxes and spheres and can perform intersection tests between pairs of these objects. Also implemented is an algorithm that computes the min bounding sphere for a set of points.
	\item[io]
		The command-line argument processor is implemented here along with a few extra classes to operate on streams.
	\item[kinemage]
		This package provides a simplistic model of the \link{http://kinemage.biochem.duke.edu/software/king.php}{kinemage} format and provides an API for a subset of its features. Also included is code to render geometric objects (e.g., proteins, NOEs) into the kinemage format.
	\item[mapping]
		Classes here perform various mappings between various namespaces. For example, this code can map between a couple atom naming conventions found in PDB and MR files. It also maps atom addresses between text formats (e.g., {\tt resid 36 and name HE22 and segid A}) and a more efficient binary format. In particular, the atom naming convention mapping is incomplete (but sufficient for p53), but can be adjusted/improved by modifying the {\tt .map} resource files.
	\item[math]
		The math package contains vector libraries in 3 and higher dimensions, matrix operations in 3 and 4 dimensions, and higher-dimensional analogues to the objects in the geom package. Implementations for quaternions are also included along with a class that computes optimal rotations between two point sets under an RMSD objective function.
	\item[minimize]
		Wrapper classes for the CNS integration
	\item[mol2]
		For now, contains a single class that exports proteins in the MOL2 format.
	\item[nmr]
		Contains code for reading/writing NOEs from MR files, mapping these NOEs to a protein in memory, and a class that removes all atoms from a protein object except for those referenced by NOEs (useful as an optimization).
	\item[pdb]
		Contains code to read/write PDB files into/from protein memory objects. Also has a class to update PDB files written by CNS to the more modern format.
	\item[perf]
		This package contains timers and progress bars.
	\item[protein]
		This package contains all the classes needed to represent a protein in memory. Protein objects in memory are organized in a heirarchical structure as follows: A protein can contain many subunits. A subunit can contain many residues. A residue can contain many atoms. Finally, an atom can contain many models. Each model for an atom is essentially a 3D point specifying the atom's position. Also, two schemes exist for addressing atoms in a protein object. The readable format ({\tt ReadableAtomAddresser}) is human-readable but slow to process. There is also binary format ({\tt AtomAddresser}) that is not human readable, but is much faster.
	\item[pseudoatoms]
		Implementation of pseudoatoms for proteins. This package is configured using a resource file {\tt pseudo.atoms}.
	\item[steric]
		Performs steric checking for protein objects.
	\item[test]
		This package contains the unit tests
	\item[util]
		Miscellaneous code
\end{wordlist}

\section{Resources}

Resources are ``extra'' files included in the program distribution that are used during execution (e.g., configuration, settings, etc). These files get baked into the JARs under the package {\em resources} with the exception of the files under {\em resources.test}. Testing files are excluded from all distribution files. When writing code to read these files, one must use methods in the class loader to get an input stream for the resource. Simply opening a file at that path will only work in development. In the deployed setting (when the application is executed from JAR files), the paths will not be available. Example code to load a resource file is as follows:
\begin{flushleft}
{\tt
	InputStream in = getClass().getResourceAsStream( "/resources/myResource.file" );
}
\end{flushleft}
Note that {\tt getClass()} might not work in all settings. However, any reference to an object of type {\tt Class} is sufficient.

\section{Testing}

Wherever possible, code is written such that it allows unit testing to ensure component correctness. In a nutshell, unit testing is the practice of writing a little extra code (unit tests) to execute application code and verify that the result is correct. The unit tests for this project are implemented using the \link{http://www.junit.org}{JUnit} automated testing framework.

The code is also written using the built-in assert library for java. However, the asserts are not enabled at runtime by default. When running code for debugging purposes, it is useful to turn on the asserts to help trap errors. This can be done by using the java VM argument {\tt -ea}.

\end{document}
