Tutorial

This tutorial is written for Octarisk latest master release.

1. Installation prerequisites

a. Installation of Octave

If you already have Octave versions 8.4 up and running and the financial, io, struct and statistics packages installed, continue with section 2c. Compatibility tests have been done for Octave versions 8.4.0. For Octave 9.1, still the financial package has to be updated in the official sources.

Windows

Go to GNU Octave's website and download the latest stable version.

Linux

Depending on your distribution, install Octave directly from the repository or build it from sources.
For Debian / Ubuntu / Mint just open a terminal and type sudo apt-get install octave liboctave-dev.
For Fedora type yum install octave-forge into your terminal.
For CentOS you need to activate the EPEL repository sudo yum install epel-release first. The development resources are required for compiling oct files, in some cases you have to also install a Gnu++ and Fortran compilers

b. Installation of OpenBLAS / LAPACK

Since vectorized code relies heavily on matrix operations, it is absolutely essential to have a fast linear algebra package.

Windows

Here you don't have to do anything, a linear algebra package is already included in your installation file.

Linux

Depending on your distribution, install OpenBLAS / LaPACK directly from the repository or build it from sources.
For Debian / Ubuntu / Mint just open a terminal and type sudo apt-get install libopenblas-base liblapack-dev.
For Fedora type yum install openblas lapack-devel into your terminal.

Alternatively, you get your own version of ATLAS / Intel MKL libraries running.

c. Get familiar with Octave

If you are not already familiar with Octave I would recommend to start with some online tutorial. For running Octarisk and adjusting input parameters it is necessary to have a basic understanding of the Matlab progamming language.

2. Adjust paths and download files

a. Adjusting the working directory

Now you can start Octave. If the GUI is mandatory, so you should see something like a console, the editor and a history. In order to get Octave to know where all your scripts are, you have to add your working folder. This can be easily done by typing

Linux

addpath ("~/path/to/working/directory")

Windows

addpath ("C:/Documents/Path/to/Octave")

After adding the path to your working directory, type in savepath() to get Octave to remember the added paths.

b. Installation of Octave's additional packages

Offline installation

Go to Octave Sourceforge and download the Financial, io and Statistics Package and place it somewhere. After downloading, type into Octave console pkg install "path/to/download/folder/io-X.X.X.tar.gz". Adjust the path to your Linux or Windows environment and repeat this step for the other packages.

Automatic installation

There also exists the possibility to download and install the required packages directly from Octave's command line:

financial package

pkg install -forge financial

io package

pkg install -forge io

statistics package

pkg install -forge statistics

struct package

pkg install -forge struct

parallel package

pkg install -forge parallel

These packages are not automatically loaded at start up. If you want to do this, you have to add pkg load financial;pkg load statistics; to the last lines of the file "octaverc". You can find these file in

Linux

~/.octaverc

Windows

C:\Installdirectory\Octave-X.Y.Z\share\octave\X.Y.Z\m\startup\octaverc

Octarisk is automatically loading packages at runtime, so you don't have to take care about this step.

c. Download the latest version of Octarisk

Either you download the latest release with all Octarisk files and extract it into your working directory (which you alreadyhave added to your search path) or you clone the latest Octarisk repository from Github from the master branch.

d. Compile C++ binaries

Type on the Octave console compile_oct_files('/path/to/octarisk-latest') This takes a couple of minutes and compiles some binaries for even faster pricing (the most performance relevant algorithm have been highly optimized in C++, e.g. curve interpolation of callable bond pricing).

e. Run automized test suites

Run the following scripts for both unit tests (testing single scripts) and integration tests (testing interaction of several scripts at once):

Unittests:

unittests()

Integrationtests:

integrationtests ('/path/to/octarisk-latest/testing_folder')

All tests should be successful (PASS only, no FAILS). In case plotting tests fail, please ignoe since there is no issue (Generated plots are compared by their hashes. Even small (single pixel) deviations result in a different hash). Otherwise make sure all C++ binaries were compiled and financial, io and statistical packages were installed properly. The integrationtests valuate all possible instrument types and calculates portfolio value-at-risk and stress figures (a full end-to-end test including scenario generation, instrument valuation, portfolio aggregation and reporting is performed).

3. Run Octarisk

The latest release comes with a complete set of example data - it is ready for running the market risk calculation! By running octarisk('/path/to/octarisk-latest/test_folder'), a full valuation of a sample portfolio including various financial instruments (Fixed Rate Bonds, European and American options, swaptions, floating rate bonds, some ETFs and stocks etc.) is performed for parametric and historical stress scenarios and for 50000 Monte Carlo scenarios on a one year time horizon. Standardized reports and plots in various formats are being generated, which can then be used in e.g custom LaTeX reports. All generated reports and plots can be found under /reports subfolder.

5. Adjust specifications and input files

a. Specify parameters

You can make changes to the pre-specified settings in file parameter.csv:

Value-at-Risk

Specify the number of MC scenarios, the time horizon and confidence intervall and Harrell-Davis estimator

Aggregation

Specify aggregation keys and portfolio currencies

Scenario Generation

Specify random number generator and Sobol or MC seed, enable risk factor statistics and plotting features

b. Adjust input files

Once you got familiar with the design of the script and the input parameters, it is time to adjust the input files to your needs. Before doing so, it is recommended to read Octarisk's User and Developer manual.

Instruments

Append or modify financial instruments. Refer to the manual for specifications (input file working_folder/input/instruments.csv)

Market data

Append or modify financial market data objects like curves, indizes and exchange rates. Refer to the manual for specifications (input file working_folder/mktdata/mktdata.csv)

Positions

Adjust positions and unit sizes for all of your portfolios. Risk measures will be automatically aggregated of all positions within a portfolio and one report per portfolio will be distributed (input file working_folder/input/positions.csv)

Risk factors

Add new risk factors or adjust the stochastic parameters of existing ones - try what happens if you double the standard deviation or make a risk factor distribution more skewed (input file working_folder/input/riskfactors.csv)

Stresstests

Define your own new stress tests and calculate your portfolio's profit or loss - try out either new parametric or historic stress tests or generate your own scenario - the impact on your portfolio is just one step away (input file working_folder/input/stresstests.csv)

Correlation data

Change the correlations between risk factors - no fear of being not positive semi-definite anymore, an automatic adjustment to your correlation matrix will be performed to assure positive-semidefiniteness (input file working_folder/mktdata/corr.csv)

Volatility data

Change the volatility smile of e.g. your German equity risk factor by adjusting the time / term volatilty surface (input file working_folder/mktdata/vol_index_RF_VOLA_EQ_DE.dat)

For automatic batch runs you may write scripts to export all your instruments and positions from your database and to calculate statistic parameters from historic time series.

6. Gain experience, ask questions and contribute

If you want to see all the possibilities you have - read the User and Developer manual, look into the code and adjust it to your needs. For contribution you are kindly refered to the developer site.