Getting started

[Anonymous]

At first, I would like to say thank you for the great work, which of course also goes out to the Quantlib team. I really appreciate it!
I have several years of professional experience in capital markets and risk management and in my opinion both tools can easily keep up with many commercial applications and pricing libraries I have encountered in banks so far.
However, after waiting excitedly for the new release, I am still struggling to get started with Open Source Risk Engine. Even with solid know-how about financial products and pricing/ risk models the sheer number of parameters and config files is overwhelming.
The provided examples are great to show the extensive power and the possibilities of the software in a complex pricing environment, but it is really challenging to identify the essential building blocks and parameters in the config files to run some simple test calculations.
The documentation is already pretty good for an open source project, but a small „getting started“ tutorial would be helpful. I have something like this in my mind:
– Single currency portfolio
– No multicurve framework
– No counterparty credit risk, no collateral etc.
– Only basic set of market parameters: flat vol surface, flat interest rate curves etc.
Maybe just pricing and sensitivity calculation of a plain vanilla equity option or a plain bond. I think it would be easier to start with a basic configuration and then add more features one after the other.
I started with the configuration in example 16 and by reducing the input files to a bare minimum I finally succeeded in pricing an plain vanilla option – but so far, I even failed in calculating the respective sensitivities…
My final goal is to run some market risk calculations like VaR of equity portfolios for training purposes, mainly by Monte Carlo Simulation.
I hope my feedback is helpful for you !

Cheers

FiveEights

[Anonymous]

Hi FiveEights,

Example 14 has a minimal market data setup for exactly this kind of simple test, I think it’s a 2 currency setup but a single one should work too, it’s easy to set it to single curve pricing (just change he specs in todaysmarket.txt)

I agree on your earlier points about the complexity of the configuration, allot of the time it’s necessary to step into the code to see what is going on.

Regards,
Niall.

[Anonymous]

Hi Niall

Thanks for the quick reply ! I checked out the setup in example 14 and this seems to be much more adequate for my test calculations.
I will now slim down my config files todaysmarket.xml etc. according to example 14 and I hope this will simplify my first steps with Open Source Risk Engine.

Cheers

FiveEights

[Anonymous]

Hi

In the meantime I succeeded in setting up a simple market environment and I am now able to price plain vanilla equity options and calculate their sensitivities.

Currently I am moving on to run some VaR calculations for single underlying portfolio.
From my first test runs I suppose that I always have to provide the covariance input file “covariance.csv”, even if I only have one single underlying – right ?

How exactly do I calculate the covariance parameter in this file ?
Since I am looking at a single underlying case, the correlation coefficient will be 1 but I don’t understand how I have to scale the respective value.

The userguide says “Also note that covariances are expected to include the desired holding period, i.e. no scaling with square root of time etc is performed in ORE”
Maybe I am missing something obvious but I simply can’t find the correct formula for covariance input. I guess Spot and Volatility also have to be included somehow ?

Could you please provide an example for calculating the correct covariance parameter ? Thanks for your help !

Cheers

Five Eights

[Peter Caspers]

Hi,

let’s look at Example_15, which provides a VaR calculation of a portfolio of trades. Furthermore let’s focus on EQ_CALL_SP5 which is an equity option corresponding to the case you are looking at. This trade has sensitivities to

– the USD discount curve
– the SP5 equity forecast curve
– the SP5 equity spot
– the SP5 equity volatility surface
– and finally the USDEUR FX Spot rate, since the reporting currency is EUR

To compute a parametric VaR you can provide a covariance matrix for all of these risk factors that influence the trade’s NPV. Notice that the covariance matrix contains the variances of the single risk factors on the diagonal, so even if we only consider one single risk factor it makes sense to provide a (1×1) covariance matrix, the only entry being the variance of this factor. You do not need to provide each cell of the covariance matrix, missing values are assumed to be zero. In case of zero variances (diagonal elements of the matrix) for a risk factor with a non-zero sensitivity, a warning is logged though indicating that the covariance matrix specification is incomplete.

As an example let’s take the equity spot sensitivity (from the output file sensitvitiy.csv)

EQ_CALL_SP5,EquitySpot/SP5/0/spot,21.475600,179736.37,7599.69,156.28

for which in covariance.csv we have the variance

EquitySpot/SP5/0/spot EquitySpot/SP5/0/spot 100

which has the following interpretation: Since we are computing equity spot sensitivities by applying a 1% relative shift, as can be seen in the input file sensitivity.xml

  <!-- Equity spot shifts -->
...
    <EquitySpot equity="SP5">
      <ShiftType>Relative</ShiftType>
      <ShiftSize>0.01</ShiftSize>
    </EquitySpot>

the variance is expected to be consistent with this shift type, i.e. the variance of relative movements of the equity spot expressed in percent. In other words you could estimate the variance on a historical time series by computing the sample variance of daily percentage relative changes 100.0 * (Spot(t+1) – Spot(t)) / Spot(t) of the equity spot. If you plug this value into covariance.csv the resulting value at risk will be a 1-day value at risk w.r.t. the given confidence level.

If you instead want to compute a say 10-day value at risk, you could for example

– estimate the variance of 10d changes 100.0 * (Spot(t+10)-Spot(t)) / Spot(t) directly on your time series, with an overlapping or non-overlapping 10 day window, or
– use your 1d estimate for the variance and scale (multiply) this by 10, following the square-root of time rule (notice we scale a variance here, not a standard deviation, so no square root shows up)

or use another method to arrive at an estimate for the 10 day variance. This is what is meant by “no scaling is applied” in the user guide. i.e. you directly provide the variance consistent with the horizon of the value at risk calculation. In the example covariance.csv we have

EquitySpot/SP5/0/spot EquitySpot/SP5/0/spot 100

which means that the variance of the equity spot risk factor key is 100, i.e. the standard deviation of relative equity spot moves is 10%. If we wanted to specify a correlation with another equity “Lufthansa” assume first we have a variance of the Lufthansa spot of 200, i.e.

EquitySpot/Lufthansa/0/spot EquitySpot/Lufthansa/0/spot 200

Then if the correlation between the two spots’ relative movements is 30% we would add a line

EquitySpot/SP5/0/spot EquitySpot/Lufthansa/0/spot 42.4264

because the covariance is the correlation times the standard deviation of SP5 and Lufthansa respectively, i.e. 0.3 * sqrt(100) * sqrt(200). Notice that in the covariance file of Example_15 no non-zero correlations are specified.

Does that make sense to you?

Best Regards
Peter

• This reply was modified 6 years, 10 months ago by Peter Caspers.
• This reply was modified 6 years, 10 months ago by Peter Caspers.
• This reply was modified 6 years, 10 months ago by Peter Caspers.
• This reply was modified 6 years, 10 months ago by Peter Caspers.
• This reply was modified 6 years, 10 months ago by Peter Caspers.
• This reply was modified 6 years, 10 months ago by Peter Caspers.
• This reply was modified 6 years, 10 months ago by Peter Caspers.

[Anonymous]

Hi Peter,

Thanks for the detailed and well-written explanation, appreciate it !!
I was finally able to work through everything carefully and now I get plausible VaR results.

The most important clue was that you pointed me to the specification of the sensitivities in sensitivity.xml.
Somehow I had changed the relative shift size for Delta from 1% to 0.1% and obviously this didn’t match my parameters in covariance.csv.

May I suggest that you include your answer in the official userguide ?
I am convinced that this explanation will be very helpful for other users as well to give more information about VaR calculation and covariance.csv.

By the way: I saw no product type for stocks in portfolio.xml, right ? At the moment, I use equity forwards as a workaround, but I am not sure if this is the best approach.

Kind regards

FiveEights

[Peter Caspers]

Hi FiveEights,

thank you. I agree we should add a section to the user guide explaining all this in more detail and with examples.

It is correct that we do not have stocks in ORE. For the purpose of valuation, sensitivity and VaR calculation it seems sensible though to use forwards (with maturity = reference date) instead.

Best Regards
Peter

[forde]

A question on building the userguide (I know there is one typeset in the root dir): Are you able to add the userguide.toc and userguide.aux files to the UserGuide directory?
I suspect that the errors when typesetting may be solved by these.

[forde]

For those on macOS, a few tips for installation in case they are of use. I use a bash script to install including the below. Let me know if you find a better way.

1. For problems finding boost:
`bash
export BOOST_LIB=$(brew –prefix boost)/lib
export BOOST_INC=$(brew –prefix boost)/include
`

2. For errors and warnings that stop the build…I find that
`bash
cmake -DBOOST_ROOT=$BOOST_INC -DBOOST_LIBRARYDIR=$BOOST_LIB -DCMAKE_CXX_FLAGS=”-Wno-error=unused-variable -Wno-error=unused-but-set-variable -Wno-unused-private-field -Wno-unused-but-set-variable” ..
`
..will not work, so I add the following to the CMakeLists.txt at ./, ./OREData, /Quantlib, ./QuantExt, ./OREAnalytics

`bash
add_compile_options(
“-Wno-error=unused-variable”
“-Wno-error=unused-but-set-variable”
“-Wno-unused-private-field”
“-Wno-unused-but-set-variable”
)
`
..before a target is set.

e.g.
`bash
# Define the directories
dirs=(“<path_to_ore>/” “<path_to_ore>/OREData” “<path_to_ore>/Quantlib” “<path_to_ore>/QuantExt” “<path_to_ore>/OREAnalytics”)

# Define the string to be inserted
insert_str=$’add_compile_options(\n “-Wno-error=unused-variable”\n “-Wno-error=unused-but-set-variable”\n “-Wno-unused-private-field”\n “-Wno-unused-but-set-variable”\n)\n’

# For each directory
for dir in “${dirs[@]}”; do
# Define the CMakeLists.txt file path
file=”${dir}/CMakeLists.txt”

# If the file exists
if [[ -f “$file” ]]; then
# Create a backup of the original file
cp “$file” “$file.bak”

# Create a temporary file
temp_file=$(mktemp)

# Read the file line by line
awk -v insert_str=”$insert_str” ‘NR==1{print; print insert_str; next} 1’ “$file” > “$temp_file” && mv “$temp_file” “$file”
else
echo “File $file does not exist”
fi
done
`

3. Amend the cmake commonSettings.cmake to allow for parallel unit test runner

`bash
# Define the path to the file
FILE=”<path_to_ore>/cmake/commonSettings.cmake”

# Use sed to find and replace the text
sed -i ” ‘s/option(ORE_ENABLE_PARALLEL_UNIT_TEST_RUNNER “Enable the parallel unit test runner” OFF)/option(ORE_ENABLE_PARALLEL_UNIT_TEST_RUNNER “Enable the parallel unit test runner” ON)/g’ $FILE
`

4. To remove errors each build (just an annoyance), update Doxygen files

`bash
# An array of directories containing Doxyfiles that need to be updated
directories=(
“<path_to_ore>/OREData/doc”
“<path_to_ore>/QuantExt/doc”
“<path_to_ore>/OREAnalytics/doc”
)

# Loop over the directories
for dir in “${directories[@]}”
do
# Navigate to the directory
cd “$dir”

# Update the Doxyfile
doxygen -u Doxyfile
done
`

5. Update .doxy file to fix DOT_GRAPH_MAX_NODES too low error:

`bash
# Specify files
FILES=(
“<path_to_ore>/OREAnalytics/doc/orea.doxy”
“<path_to_ore>/OREData/doc/ored.doxy”
“<path_to_ore>/QuantExt/doc/quantext.doxy”
“<path_to_ore>/QuantLib/Docs/quantlib.doxy”
)

# Loop over files and update each one
for file in ${FILES[@]}; do
if [ -f “$file” ]; then
# Backup original file
cp “$file” “$file.bak”

# Update DOT_GRAPH_MAX_NODES value
sed -i ” ‘s/DOT_GRAPH_MAX_NODES = [0-9]\+/DOT_GRAPH_MAX_NODES = 100/g’ “$file”
echo “Updated $file”
else
echo “File not found: $file”
fi
done
`

[Author]

Posts