Getting Started

  1. First steps
  2. Risk analysis
  3. Using macros
  4. Using command line
  5. Flying solo

1. First steps

Follow these steps to install CCruncher and perform your first simulation.

  1. Download the binary package.
  2. Unpack it in a folder. To uninstall CCruncher simply delete the folder where it is located.
  3. Take a time to inspect the directory contents (bin, data, doc, samples).
  4. Execute CCruncher double-clicking bin/ccruncher-gui.
  5. Open file samples/test05.xml.
  6. Click on the 'Monte Carlo' button (lightning icon).
  7. Set data/ as output directory.
  8. Click the 'Run' button, or the 'Run' icon, to execute the Monte Carlo simulation.
  9. Read the execution trace.
  10. Open a file browser and review the content of the data/ directory. Observe the output files named portfolio.csv and sector-rating.csv. Open it and inspect its content. The values are the simulated portfolio losses. The output file format is described here.

2. Risk analysis

Output files contain the simulated portfolio and sub-portfolios losses. The technical document explains how to use these simulated values to compute the Expected Loss (EL), Value at Risk (VaR), Expected Shortfall(ES), and how to disaggregate by sub-portfolios these risk measures. We encourage using your preferred data analysis tool (Excel, R, SAS, SPSS, etc.) to compute these values using the simulated losses. The following lines explain how you can do the credit risk analysis using CCruncher:

  1. Open sector-rating.csv output data file. You can use the 'File > Open file' dialog, or click the output file link in the simulation trace, or click the 'Data analysis' icon.
  2. CCruncher displays the analysis tab. The top-right combobox indicates the analysis mode. There are two analysis modes: 'Segmentation' and 'Segments'.
  3. Set the 'Segmentation' mode. In this mode, CCruncher displays the risk disaggregation when there is more than a segment defined. The pie chart values indicate the percentage of risk attributable to the given sub-portfolio (right-click or ctrl-C to copy values to clipboard). The 'Results' section shows the whole portfolio risk measure.
  4. Set the 'Segments' mode. In this mode, CCruncher performs the risk analysis of the indicated segment. If you are analyzing a segment/sub-portfolio distinct than the whole portfolio, remain that risk measures distinct than EL aren't additives. The curve plot displays the risk measure evolution depending on the number of samples (right-click or ctrl-C to copy values to clipboard).

3. Using macros

The macros mechanism allows modifying the input file in an easy way. This is useful if you desire to evaluate the same input file modifying slightly a parameter each time.

  1. Open file samples/test05.xml in the xml editor tab.
  2. Create a new macro adding the following line into the <defines> tag:
    <define name="numsecs" value="20" />
  3. Go to the maxseconds parameter and replace its value by $numsecs.
    <parameter name="maxseconds" value="$numsecs"/>
  4. Save the changes made in input file.
  5. Click on the 'Monte Carlo' button.
  6. Set data/ as output directory.
  7. Now, click on the 'Set ...' macros button.
  8. Set numsims value to 0 (unbounded number of simulations).
  9. Close macros dialog pressing the 'Ok' button.
  10. Click the 'Run' button to execute the Monte Carlo simulation.
  11. Check that the simulation has elapsed ~20 seconds before to stop.

4. Using command line

The command line version of CCruncher is the proper way to perform multiple simulations or to integrate CCruncher in your risk management system. Below we show the available options: 

> bin/ccruncher-cmd -h

Usage: ccruncher-cmd [OPTION]... [FILE]

Simulate the loss distribution of the credit portfolio described in the XML
input FILE using the Monte Carlo method. FILE can be gziped. If no one is
given, then STDIN is considered. The input file format description and
details of the simulation procedure can be found at http://www.ccruncher.net.

Mandatory arguments to long options are mandatory for short options too.

  -D, --define=KEY=VAL    replace '$KEY' strings by 'VAL' in input file
  -a, --append            output data is appended to existing files
  -w, --overwrite         existing output files are overwritten
  -o, --output=DIRECTORY  place output files in DIRECTORY (default=current dir)
      --nice=NICEVAL      set process priority to NICEVAL (see nice command)
      --threads=NTHREADS  number of threads to use (default=number of cores)
      --hash=HASHNUM      print '.' for each HASHNUM simulations (default=1000)
      --info              show build parameters and exit
  -h, --help              show this message and exit
      --version           show version and exit

Exit status:
  0   finished without errors
  1   finished with errors

Examples:
  basic example      ccruncher-cmd -o data/ samples/test04.xml
  forcing overwrite  ccruncher-cmd -w -o data/ samples/test100.xml
  redefining values  ccruncher-cmd -w -o data/ -D ndf=8 samples/sample.xml

Report bugs to gtorrent@ccruncher.net. Please include the output of
'ccruncher-cmd --info' in the body of your report and attach the input
file if at all possible.

The following example simulates the input file samples/test05.xml redefining macros NU, W1, W2, R12, placing output files in data/ directory and overwriting output files if they exist. 

> bin/ccruncher-cmd -w -o data -DNU=12.54 -DW1=0.29 -DW2=0.48 -DR12=0.21 samples/test05.xml

Command line execution outputs a 80-column width trace containing valuable info. We recommend saving this trace because it contains the file name and its checksum, the macros values, the RNG seed, and a description of the problem that is simulated.

5. Flying solo

We have revised the main features. Some final words before you move by yourself: