A sandbox for building and testing scalable implementations of various market micro-structures.
Agora is being developed using Java 8 and Scala 2.11 and built using the Scala Build Tool (SBT). If you want to build Agora from source you will also need to install Git.
To see what version (if any!) of Java you already have installed on your system, open a terminal (or command prompt on Windows) and run...
java -version
...if the result is something like...
java version "1.8.0_$BUILD_NUMBER
...then you are good to go and can proceed to installing Scala and SBT. Note that the $BUILD_NUMBER will depend on the exact build of Java 8 you have installed. If you are running older versions of the JDK (or a JDK is not installed on your machine), then you can down install the Java 8 JDK from either Oracle or the OpenJDK 8 project.
Pre-packaged installers for Oracle's JDK 8 are available for all major operating systems. If you are new to Java development (and/or are not using a Linux-based OS!) then I would suggest that you use one of Oracle's pre-packaged installers.
The OpenJDK 8 project is an open-source reference implementation of the Oracle Java SE 8 Platform Specification. Installing the OpenJDK on Linux systems is a piece of cake. For example, Debian or Ubuntu users just need to open a terminal and run...
sudo apt-get install openjdk-8-jdk
...installing OpenJDK on Mac OSX can be done but requires a bit more work. While I am sure it is possible to install the OpenJDK on Windows, I don't have any idea how to go about doing it!
To verify your Java install, open a terminal (or command prompt on Windows) and run...
java -version
...and the result should be something like...
java version "1.8.0_$BUILD_NUMBER
...where the $BUILD_NUMBER will depend on the exact build of Java 8 you have installed
Once Java 8 is installed, need to install Scala and SBT. Installers exist for all major operating systems for both Scala and SBT.
An alternative solution is to install Activator from LightBend which includes both Scala and SBT (as well as the Play Framework).
To verify your Scala install, open a terminal (or command prompt on Windows) and run...
scala -version
...and the result should be something like...
Scala code runner version 2.11.8 -- Copyright 2002-2016, LAMP/EPFL
To verify your SBT install, open a terminal (or command prompt on Windows) and run...
sbt sbtVersion
...and the result should be something like...
[info] Loading global plugins from C:\Users\pughdr\.sbt\0.13\plugins
[info] Loading project definition from C:\Users\pughdr\Research\scalabm\markets-sandbox\project
[info] Set current project to markets-sandbox (in build file:/C:/Users/pughdr/Research/scalabm/markets-sandbox/)
[info] 0.13.11
In order to install Agora source code, you will need to install Git.
To verify your Git install, open a terminal (or command prompt on Windows) and run...
git --version
...and the result should be something like...
git version 2.9.2
To install Agora source code you can either clone the repo or, assuming you already have a GitHub account, you can first fork the repo and then clone it.
To build Agora simply open a terminal (or command prompt on Windows), change into the agora directory and run...
sbt clean compile
...which should generate output similar to...
[info] Loading global plugins from C:\Users\pughdr\.sbt\0.13\plugins
[info] Loading project definition from C:\Users\pughdr\Research\scalabm\markets-sandbox\project
[info] Set current project to markets-sandbox (in build file:/C:/Users/pughdr/Research/scalabm/markets-sandbox/)
[success] Total time: 0 s, completed Aug 5, 2016 11:47:25 AM
[info] Updating {file:/C:/Users/pughdr/Research/scalabm/markets-sandbox/}markets-sandbox-core...
[info] Resolving org.scala-lang#scalap;2.11.8 ...
[info] Done updating.
[info] Compiling 24 Scala sources to C:\Users\pughdr\Research\scalabm\markets-sandbox\target\scala-2.11\classes...
[success] Total time: 12 s, completed Aug 5, 2016 11:47:37 AM
Agora has an extensive suite of unit tests. To run Agora unit test suite simply open a terminal (or command prompt on Windows), change into the agora directory and run...
sbt clean test
..to run unit tests and generate unit test coverage statistics run ...
sbt clean coverage test
...followed by...
sbt coverageReport
...to generate the report. The html and xml versions of the code coverage reports can be found in the agora/target/ directory. Code coverage reports for both the master and develop branches of Agora repo are automatically generated by Travis as part of our continuous integration (CI) process and are available online (master, develop).
In addition to unit tests, Agora has an extensive suite of performance tests that make use of the excellent ScalaMeter testing library. To run the entire suite of ScalABM markets-sandbox performance tests simply open a terminal (or command prompt on Windows), change into the agora directory and run...
sbt performance:test
...note that running the entire suite of performance tests can take several hours. If you are interested in the results of a particular performance test, the you can run...
sbt "performance:test-only $CLASSPATH"
...where the $CLASSPATH should be a path to the class containing the performance test that you would like to run. For example, to run the performance test for a thread-safe, parallel implementation of an order book, you would run...
sbt "performance:test-only markets.orderbooks.parallel.concurrent.OrderBookMicroBenchmark"
...don't forget to include the quotation marks! The html version of the performance testing reports can be found in the agora/target/ directory. Performance testing reports for the master branch of Agora repo are automatically generated by Travis as part of our continuous integration (CI) process and are available online.
In addition to unit and performance tests, Agora has an extensive suite of functional tests primarily designed to demonstrate basic usage of the library. To run the entire suite of functional tests simply open a terminal (or command prompt on Windows), change into the agora directory and run...
sbt functional:test
...note that running the entire suite of performance tests can take several hours. If you are interested in the results of a particular performance test, the you can run...
sbt "functional:test-only $CLASSPATH"
...where the $CLASSPATH should be a path to the class containing the performance test that you would like to run. For example, to run the performance test for the Continuous Double Auction matching engine, you would run...
sbt "functional:test-only markets.twosided.auctions.continuous.PostedPriceAuctionSpec"
...don't forget to include the quotation marks!