ReadMe
From JQuantLib
Contents |
About JQuantLib
JQuantLib is a Quantitative Finance framework written in Java. It aims to provide enough tools for a broad range of financial instrument valuation using a number of algorithms, pricing engines, simulation methods, etc.
If you are impatient, jump to Building JQuantLib from command line
Audience
The main audience is composed by Java developers interested on matters related to Quantitative Finance and specially interested on financial instrument valuation. You also need to be comfortable to use Linux. In particular, there are some examples which are suitable to Debian and variants.
What this README is about?
This README file is about how JQuantLib can be obtained and built both using command line commands in a Linux box or using the excellent Eclipse IDE. You can jump directly to the section which best matches your needs.
Building JQuantLib from command line
If you prefer to build JQuantLib under Eclipse, please jump to Building JQuantLib under Eclipse.
Overview
You can build JQuantLib using both Ant or Maven. You dont need to install both build tools. We will also guide you on how to install Subversion.
Requirements
- SVN client command line version
- Java JDK6
- Maven 2.2.1
Install Subversion
Simply type the following command under Debian and variants:
apt-get install subversion
On other platforms, you can find instructions at http://subversion.tigris.org/getting.html. Note: please make sure you install the command line version.
You can verify your installation like this:
$ svn --version svn, version 1.6.4 (r38063) compiled Aug 18 2009, 20:47:17 Copyright (C) 2000-2009 CollabNet. Subversion is open source software, see http://subversion.tigris.org/ This product includes software developed by CollabNet (http://www.Collab.Net/).
Install Ant
This installation is optional as it's not required for building JQuantLib. Ant is a very useful tool and chances are a developer will need it at some point. So, we explain here how Ant can be easily installed.
Ant is available as a Debian package but we prefer to install it by hand from the official Apache download site because it's a better controlled method which does not imply on the installation of the entire Java environment chosen by Debian packages. Doing so, you control which Java environment you are using and in the future, you will be able to switch to Java7 in order to take advantage of some advanced compilation options it offers.
- Download Ant from http://ant.apache.org/bindownload.cgi;
- Uncompress Ant distribution archive in a place of your choice;
- Add Ant bin directory in your PATH variable.
For instance:
# download Ant mkdir -p ~/Downloads/Java/apache-ant/1.7.1 cd ~/Downloads/Java/apache-ant/1.7.1 wget http://apache.mirror.rbftpnetworks.com/ant/binaries/apache-ant-1.7.1-bin.tar.bz2 # Install Ant mkdir -p /opt/JavaIDE cd /opt/JavaIDE tar xvpjf ~/Downloads/Java/apache-ant/1.7.1/apache-ant-1.7.1-bin.tar.bz2 # add to your PATH export PATH=$PATH:/opt/JavaIDE/apache-ant-1.7.1/bin echo 'export PATH=$PATH:/opt/JavaIDE/apache-ant-1.7.1/bin' >> ~/.bashrc
Now verify if your environment is properly configured. If you type
ant -version
You will obtain something similar to this:
Apache Ant version 1.7.1 compiled on June 27 2008
Install Maven
JQuantLib depends on Maven2 for its complete build process which not only generates .jar files but also generates full documentation and a complete website as it can be seen here.
Maven is available as a Debian package but we prefer to install it by hand from the official Apache download site because it's a better controlled method which does not imply on the installation of the entire Java environment chosen by Debian packages. Doing so, you control which Java environment you are using and in the future, you will be able to switch to Java7 in order to take advantage of some advanced compilation options it offers.
- Download Maven2 from http://maven.apache.org/download.html;
- Uncompress Maven2 distribution archive in a place of your choice;
- Add Maven2 bin directory in your PATH variable.
For instance:
# download Maven2 mkdir -p ~/Downloads/Java/apache-maven/2.2.1 cd ~/Downloads/Java/apache-maven/2.2.1 wget http://www.mirrorservice.org/sites/ftp.apache.org/maven/binaries/apache-maven-2.2.1-bin.tar.bz2 # Install Maven2 mkdir -p /opt/JavaIDE cd /opt/JavaIDE tar xvpjf ~/Downloads/Java/apache-maven/2.2.1/apache-maven-2.2.1-bin.tar.bz2 # add to your PATH export PATH=$PATH:/opt/JavaIDE/apache-maven-2.2.1/bin echo 'export PATH=$PATH:/opt/JavaIDE/apache-maven-2.2.1/bin' >> ~/.bashrc
Now verify if your environment is properly configured. If you type
mvn -version
You will obtain something similar to this:
Apache Maven 2.2.1 (r801777; 2009-08-06 20:16:01+0100) Java version: 1.6.0_16 Java home: /mnt/nfs01/it/JavaIDE/jdk1.6.0_16-linux-x64/jre Default locale: en_GB, platform encoding: UTF-8 OS name: "linux" version: "2.6.26-2-amd64" arch: "amd64" Family: "unix"
Compiling JQuantLib
Now the magic begins!
With a couple of commands you can build everything, thanks to the standard build environments offered by Maven
mkdir -p ~/workspace cd ~/workspace # obtain the source code svn co http://jquant.svn.sourceforge.net/svnroot/jquant/trunk/jquantlib svn co http://jquant.svn.sourceforge.net/svnroot/jquant/trunk/jquantlib-all svn co http://jquant.svn.sourceforge.net/svnroot/jquant/trunk/jquantlib-helpers svn co http://jquant.svn.sourceforge.net/svnroot/jquant/trunk/jquantlib-samples
In order to build using Maven, simply type
cd jquantlib-all mvn clean install
The first time you execute the mvn command above, Maven2 will download all dependencies for you. This process will take time enough for a cup coffee. When you return, you will find some JARs under your target directory.
cd .. cd jquantlib-samples ls -al target
The biggest file is a single JAR file, a.k.a. ubber JAR, which contains everything needed to run. So... go for it!
java -jar target/jquantlib*ubber.jar
You will see a very simple demonstration of what JQuantLib is able to calculate. As JQuantLib evolves, more financial instruments, more pricing engines and algorithms will be shown.
Obtaining documentation
If you are in a hurry and you need javadocs fast!
cd ~/workspace/jquantlib mvn javadoc:javadoc firefox target/site/apidocs
JQuantLib provides fancy javadocs which contains UML diagrams and mathematical equations. See an example here. If you'd like to generate such quality of documentation, please follow these installation steps.
Once you installed all the required stuff, you can generate fancy javadocs by employing the with-javadoc profile, like this:
cd ~/workspace/jquantlib mvn clean site -P with-javadoc firefox target/site/index.html
Results of Cobertura test coverage can be added to the documentation, like this:
cd ~/workspace/jquantlib mvn clean site -P with-javadoc,with-cobertura firefox target/site/cobertura/index.html
Note: generation of Cobertura test coverage reports may take easily one hour or even 2 hours to execute!
Building JQuantLib under Eclipse
JQuantLib is developed in Java under Eclipse IDE and depends on Maven2 for its build process. We also present here all plug-ins we recommend to be installed in your Eclipse IDE.
Requirements
We strongly recommend Sun Java 1.6.0_16 or above.
- SVN client command line version. See also: http://subversion.tigris.org/getting.html
apt-get install subversion
- Install JavaSE version 1.6.0_16 or above in your environment.
http://java.sun.com/javase/downloads/index.jsp
- Install "Eclipse IDE v3.5 (Galileo) for Java developers".
http://www.eclipse.org/download
Install plugins
We assume you know how plug-ins can be installed in Eclipse via update sites.
We recommend you install plugins one by one, in exact the following order of installation.
Please install the following plug-ins:
m2eclipse
- M2Eclipse integrates dependency management
provided by Maven into your Eclipse IDE, among other features.
name: m2eclipse URL: http://m2eclipse.sonatype.org/update-dev/
Tips
- Select m2eclipse and ask Eclipse to "Select Required"
- Select Mylyn and Mylyn extras
- Unselect broken references to BuckMinster products, if any.
- "POM Editor" requires EMF and GEF to install. You can safely unselect "POM Editor" if your Eclipse installation does not provide EMF and GEF.
See also: The link below demonstrates how m2eclipse and subversive plugins can be installed in one go.
http://www.jquantlib.org/images/d/d3/Screenshot-Eclipse2.png
Subversive
- Subversive is a highly recommended plugin which integrates Eclipse and Subversion. We've chosen Subversive instead of Subclipse because Subversive looks more mature and makes us believe it will be the official SVN connector for Eclipse someday.
See also: The link below demonstrates how m2eclipse and subversive plugins can be installed in one go.
http://www.jquantlib.org/images/d/d3/Screenshot-Eclipse2.png
name: Subversive SVN Connectors URL: http://www.polarion.org/projects/subversive/download/eclipse/2.0/update-site/
name: Subversive URL: http://download.eclipse.org/technology/subversive/0.7/update-site/
name: Subversive Integrations URL: http://www.polarion.org/projects/subversive/download/integrations/update-site/
FindBugs
- FindBugs analyses your code and point out
places where you probably have a bug or a bad practice listed in FindBugs knowledge base.
name: FindBugs URL: http://findbugs.cs.umd.edu/eclipse/
PMD
- PMD helps to find bad constructions in the code, either those widely known or those we defined locally for JQuantLib.
name: PMD URL: http://pmd.sf.net/eclipse
EclEmma
- [ http://www.eclemma.org EclEmma] allows you to easily verify the code coverage
of your JUnit tests.
name: EclEmma URL: http://update.eclemma.org/
Optional plug-ins
Evaluate yourself if these plug-ins match your needs. In particular, compare against functionalities offered by reports generated by Maven.
- Metrics offers some features offered by FindBugs and is also able to analyse complexity of your code. Installing this plugin is more a matter of taste and organization of information than functionality.
name: Metrics URL: http://metrics.sourceforge.net/update
- JGit - Java Git is a Eclipse plugin for Git, which is a distributed SCM tool developed for Linux project. JGit plugin not required for developing JQuantLib at the moment but we are slowly evaluating this possibility. There are lots of projects migrating from centralised SCMs (like SVN) to distributed SCMs (like Git) due to a number of advantages.
name: JGit URL: http://www.jgit.org/update-site
Obtaining JQuantLib
Open SVN Repository Exploring perspective and select the following location:
http://jquant.svn.sourceforge.net/svnroot/jquant/trunk
Now check out the following projects:
jquantlib jquantlib-all jquantlib-helpers jquantlib-samples
If you find problems, please have a look at this guide.
Compiling JQuantLib
When you open Java perspective and open your jquantlib project, m2eclipse plugin will perform a magic for you:
- analyse your pom.xml file;
- download all dependent artifacts JQuantLib and Maven depend on;
- compile JQuantLib
The first time you open jquantlib project, it may take a relatively long time to compile due to the amount of dependencies involved when you first run Maven. You can take your time and have a coffee.
Running Unit tests
Now let's run JQuantLib unit tests and at the same time obtain a test coverage report.
- Right click on project jquantlib;
- Select Coverage As >
- Select JUnit Test
EclEmma plugin will execute all test cases. You can see the output in Console window and coverage results in Coverage window.
Troubleshooting Eclipse installation
eclipse.ini
You may find my eclipse.ini configuration useful:
-startup plugins/org.eclipse.equinox.launcher_1.0.200.v20090520.jar --launcher.library plugins/org.eclipse.equinox.launcher.gtk.linux.x86_64_1.0.200.v20090519 -product org.eclipse.epp.package.java.product -showsplash org.eclipse.platform --launcher.XXMaxPermSize 256m -vmargs -Dosgi.requiredJavaVersion=1.5 -XX:PermSize=128m -XX:MaxPermSize=256m -Xms80m -Xmx512m -server -XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:+ExplicitGCInvokesConcurrent -XX:+CMSClassUnloadingEnabled -XX:+CMSPermGenSweepingEnabled -XX:+AggressiveOpts -Dawt.useSystemAAFontSettings=lcd -ea
Installing JQuantLib
JQuantLib is a software library, intended to be included by developers in applications developed by them. Developers are responsible for chosing what they think is more adequate for a particular purpose.
Additional documentation
The main source of information is our wiki at http://wiki.jquantlib.org/
Install JSR-308 tools (EXPERIMENTAL)
YOU CAN SKIP THIS SECTION
In a nutshell, JSR-308 improves annotation processing, creating new possibilities for whomever interested on writing robust, meaningful and professional Java code. JSR-308 will be available in the upcoming JDK7 which is expected to be released late 2008. For more information why JSR-308 is important for JQuantLib, please see DesignTypeChecking.
We present here a shell script which is intended to easy the process of installation of JSR-308 tools in your Java environment.
Requirements
Notice that both JDK6 and JDK7 are required. JDK6 is required to compile the JSR-308 tools. JDK7 is required by JSR-308 tools to compile your program which will be taking advantage of annotations conformant with JSR-308 proposal.
Shell Script
#!/bin/bash -x
###
### You need to change these settings according to your environment
###
#
# JavaIDE represents the 'Home' of your Java tools.
# Ideally, you should have JDK6, JDK7, Ant etc installed on this folder
#
JavaIDE=/opt/JavaIDE
#
# Define where JDK6 and JDK7 are installed.
#
JDK6_HOME=${JavaIDE}/jdk1.6.0_03-amd64/
JDK7_HOME=${JavaIDE}/jdk1.7.0_ea-amd64/
#
# Define the place where JSR308_HOME will be installed
# You need to have write access to this location
#
JSR308_HOME=${JavaIDE}/JSR-308
# Download and expand packages
for archive in langtools checkers ; do
wget -N -c http://groups.csail.mit.edu/pag/jsr308/releases/jsr308-${archive}.zip
if [ $? -ne 0 ] ;then exit 1; fi
rm -rf ${archive}
unzip jsr308-${archive}.zip ; if [ $? -ne 0 ] ;then exit 1; fi
done
# Configure your environment
mkdir -p ~/.openjdk
cat << EOD > ~/.openjdk/build.properties
boot.java.home=${JDK6_HOME}
target.java.home=\${boot.java.home}
EOD
# Compile javac and javap
pushd langtools/make
ant clean
ant build-javac build-javap
if [ $? -ne 0 ] ;then exit 1; fi
popd
# Install javac and javap
mkdir ${JSR308_HOME}/langtools/dist/bin ${JSR308_HOME}/langtools/dist/lib
for tool in javac javap ;do
echo Installing ${tool}...
echo "cp -p langtools/dist/bin/${tool} ${JSR308_HOME}/langtools/dist/bin"
cp -p langtools/dist/bin/${tool} ${JSR308_HOME}/langtools/dist/bin
if [ $? -ne 0 ] ;then exit 1; fi
echo Installing ${tool}.jar...
echo "cp -p langtools/dist/lib/${tool}.jar ${JSR308_HOME}/langtools/dist/lib"
cp -p langtools/dist/lib/${tool}.jar ${JSR308_HOME}/langtools/dist/lib
if [ $? -ne 0 ] ;then exit 1; fi
done
# Compile checkers
pushd checkers
ant clean
ant
if [ $? -ne 0 ] ; then exit 1; fi
popd
# Install checkers
mkdir -p ${JSR308_HOME}/checkers
echo Installing checkers...
echo "cp -p checkers/checkers.jar ${JSR308_HOME}/checkers"
cp -p checkers/checkers.jar ${JSR308_HOME}/checkers
if [ $? -ne 0 ] ;then exit 1; fi
echo "#"
echo "# Put the following lines in your user profile"
echo "#"
echo "PATH=${JSR308}/langtools/dist/bin:\${PATH}"
echo "CLASSPATH=${JSR308}/checkers/checkers.jar:\${CLASSPATH}"
echo "export PATH CLASSPATH"
Richard Gomes 14:29, 24 September 2009 (UTC)
