Page tree
Skip to end of metadata
Go to start of metadata

Deployable Software User Guide - Futures and Options

This content describes the deployable margin software used to reconcile EOD margin requirements for futures and options products across CME Group's margin methodologies.



Document History

Date

Version

Description

12/01/2018

1.0

Initial Version

3/11/2019

1.1

Updated Technical Requirements
Release Timeline
Deployable Contents
Testing the F&O Deployable Software

4/30/2019

1.2

Updated Technical Requirements
Release Timeline
Testing the F&O Deployable Software
Appendix
Software Release Details

5/31/2019

1.3

Updated Release Timeline
Testing the F&O Deployable Software
Software Release Details
Appendix
Release Examples

6/28/2019

1.4

Updated Release Timeline
Testing the F&O Deployable Software
Release Details

9/11/2019

1.5

Updated September Release Timeline
Software Release Details
Updated Appendix to include list of error codes

10/1/2019

1.6

Updated October Release timeline
Software Release Details
Updated list of error codes

11/12/2019

1.7

Overview
Updated November Release Timeline
Loading the Risk Parameter Files
Accessing the API: Best Practices
Software Release Details: November

11/21/2019

1.8

Technical Integration Requirements
Updated November Release Timeline
Loading the Risk Parameter Files
Software Release Details: November

12/09/2019

1.9

Updated December Release Timeline
Downloading the Software
Testing the Deployable Software
Software Release Details: December

1/31/2019

2.0

Overview
Technical Integration Requirements
Updated Q1 2020 Release Timelines
Loading Risk Parameter Files

6/5/2020

2.1

Technical Integration Requirements: Redis Risk Parameter Files loading in Deployable

8/7/2020

2.2

Licensing
Technical Integration Requirements
Software Release Details: August 2020
Downloading the Software: Deployable version
Loading the Risk Parameter Files
Appendix: Inputs and Outputs

9/14/2020

2.3

Software Release Details: September 2020 Loading Risk Parameter Files

9/25/2020

2.4

Software Release Details: September 2020 Technical Integration Requirements

11/23/2020

2.5

Technical Integration Requirements
Testing the F&O Deployable Software
Deployable Modes
Risk Parameter Files

12/18/2020

2.6

Overview
Licensing
Technical Prerequisites
Downloading the Software
F&O Deployable SDK Contents
Local Redis cache load
Margin Request and Input Portfolio
Margin Call and Margin Request
Analyzing the Margin Response Message Appendix:
Inputs
Errors List
Errors Text
Log Parameter File
Reducing the Size of the Log file

3/8/2021

2.7

Technical Integration Requirements
Linux – remove gcc pre-requisite
Updated March Release Timeline
Risk Parameter Files Omnibus Combinations Appendix:
Inputs – Added location to find examples
Outputs – Added location to find examples

5/24/2021

2.8

F&O Deployable SDK Contents

  • Updated Market Data to RPFs

    Testing the F&O Deployable Software
  • Updated Market Data to RPFs

    Risk Parameter Files
    Redis RPF Load
    Local Redis Cache Load
    Clearing the Redis Cache Load Errors List
  • Updated Market Data to RPFs

    Release Examples
  • Updated Market Data to RPFs

6/28/2021

2.9

Updated loading risk parameter files with latest dates for full and active only fixed points in time

8/23/2021

3.0

Testing the F&O Deployable Software

  • Updated to remove references to deprecated SPAN vs. SPAN 2 mode features.
  • Added details regarding deployable software's use of SPAN and SPAN 2 risk parameter files to interpret margin framework.
  • Added details on loading historic risk array files to Risk Parameter Files Section.

    Appendix
  • Outputs - Added Lower-Level Warnings and INFO Messages section.
  • Release Examples - Added spanFilesDirectoryOverride

10/4/2021

3.1

Testing the F&O Deployable Software à Risk Parameter Files

  • Updated to reflect new risk parameter file (rpf) SFTP location and filenames.
  • Removes section describing static files for testing – daily files are now available for testing.
  • Added "Initializing RPF Data in Deployable Software" section.
  • Added "Limited Backwards Compatibility" section.

    Appendix - Inputs - Errors List
  • Added new backwards compatibility error.

    Appendix - Release Examples
  • Added list of start-up arguments.

11/22/2021

3.2

Updated Technical Integration Requirements
Updated Download and Install

  • Updated Downloading the Software

    Updated Testing the F&O Deployable Software
  • Updated Risk Parameter Files
  • Added Best Practices for Using CME Risk Parameter Files
  • Simplify the historical and cross-margining use cases by adding Using the SPAN Over-ride Feature and removing sections referring to OCC and MGE SPAN files

    Updated Appendix
  • Added detail around user of Underlying Period Code in Inputs
  • Added Performance Metrics

12/16/2021

3.3

Updated Technical Integration Requirements
Updated version number in Downloading the Software

1/24/2022

3.4

Download and Install

  • Downloading the Software: Removed reference to current software build number, please see release notes document.

5/9/2022

3.5

Local Redis Cache Load

  • Updated to include the withTimeout configuration for using a Redis cache.

    List of Startup Parameters
  • Added log4j startup parameter

    Release Examples
  • Added new Log Levels section
  • Enhanced Log File Parameter detail


Overview

The purpose of this document is to provide a comprehensive user guide for how to interact with
CME's F&O Deployable Software and how to calculate margin results on Futures and Options products using SPAN Methodology & CME's new F&O Margin Model, SPAN 2. For assistance with this document or for general inquiries about the enhancements to SPAN, please contact PostTradeServices@cmegroup.com.
What to expect from CME's F&O Deployable Margin Software
The F&O Deployable SDK is a risk calculation library that firms can use to integrate directly into their own infrastructure.

Licensing

CME Group provides Margin Tools to clearing firms and trading firms pursuant to standardized License Agreements:

  • Firms interested in discussing details of SPAN 2 model methodology must sign an NDA
  • Firms interested in testing the F&O deployable software must sign an evaluation agreement
  • Firms interested in using the SPAN trademark or SPAN 2 trademark must execute trademark license agreement
  • Licensing Options for system integration with CME Margin Models:
    • CME CORE API Agreement
      • Authorizes connectivity to CME's test and production environments
      • Service available today
    • Deployable Software Agreement
      • Authorizes use of the Deployable Software in production environment
      • Production agreement license available
  • CME CORE User Interface is a complimentary service onboarding is self-service


Key Licensing Concepts:

  • CME does not provide warranty or assume any liability for these services.
  • CME does not change or negotiate the terms of these Agreements.


Technical Integration Requirements

The F&O Deployable Software is compatible to run on Windows and Linux. Further technical integration requirements for both Windows and Linux can be found in the README section of the SDK. Please note CME's recommended technical requirements reflect our own technical recommendations and versions of software we are readily able to support. We recognize that there is often technical compatibility to use higher versions of Linux, Java and Redis and users have reported the deployable margin software is runnable on different infrastructure configurations relatively well; however, we provide no formalized support for technical setups outside of those listed in our user guide. We recommend users test their preferred setup in a lower environment.
Technical Prerequisites:

  • Azul Zulu Java 8 version 1.8.0_291 with Java 8 installed, and the Java bin directory is on your path.
  • Redis 5.0.5 https://redis.io/download. Redis may not be used for dev testing but is highly recommended for production for SPAN 2.
  • Maven 3 required if developing application to programmatically call API.
  • Valid RPF (Risk Parameter File) downloaded for specific points in time margin calls.
    • This can be retrieved from the CME SFTP site.
      • Access to CME's SFTP location to download risk parameter files (RPFs) required for the Deployable software.
  • SPAN 2 file size will be a minimum of 15gb – 20gb compressed.
    • The latest complete SPAN 2 RPF (Risk Parameter File) is ~9.5G but will grow as more products and asset classes are added.


Linux:

  • Red Hat Enterprise Linux Server release 7.9
  • Azul Zulu Java 8 version 1.7.9_271
  • Redis 5.0.5


Windows:

  • Windows Server 2012 R2
  • Microsoft Foundation Classes MFC should be installed. CME has tested with "Visual C++ MFC MBCS Library for Visual Studio 2013 12.0.21005.01"
  • The dlls that are required on Windows are:
  • MSVCP140.dll
  • VCRUNTIME140.dll
  • api-ms-win-crt-math-l1-1-0.dll
  • api-ms-win-crt-heap-l1-1-0.dll
  • api-ms-win-crt-string-l1-1-0.dll
  • api-ms-win-crt-locale-l1-1-0.dll
  • api-ms-win-crt-stdio-l1-1-0.dll
  • api-ms-win-crt-filesystem-l1-1-0.dll
  • api-ms-win-crt-convert-l1-1-0.dll
  • KERNEL32.dll
  • mfc140d.dll
  • KERNEL32.dll
  • USER32.dll
  • OLEAUT32.dll
  • MSVCP140D.dll
  • VCRUNTIME140D.dll
  • ucrtbased.dll
  • 2C1_seh_filter_dll


CME Hardware specifications for internal testing:

  • 8 cores
  • 64GB Ram
  • 32GB JVM


Download and Install

Logging in to CME CORE

The CME Margin Software Support Team PostTradeServices@cmegroup.com will permission you to download the software from CME CORE.
To access CME CORE, a CME Group login is required. If you do not have one, please follow these instructions:

  1. Go to the CME CORE login screen: {+}https://loginnr.cmegroup.com/sso/navmenu.action+
  2. Click on the "Register" link and provide the required information
  3. Receive your CME Group Login and activation email
  4. Please contact PostTradeServices@cmegroup.com with any questions about creating a CME Group Login.


Downloading the Software

Once you have successfully logged into CME CORE, the F&O Deployable Software can be found in the "Download Center".

  1. Navigate to Portfolio &Risk à CORE Margin Calculator-NR à Download Center à Software

  1. The software can be found under the section labeled Java Deployable SDK.

F&O Java Deployable Margin SDK, includes:

    • JAR file – arcdl-deployable.jar
    • POM file – pom.xml
    • Software Development Kit
  • Sample java examples on how to margin and how to load/clear a remote Redis cache
  • Sample web service example
  • Sample postman collection endpoints
    • rpfs (Risk Parameter File) folder
    • READ ME


F&O Deployable SDK Contents

The SDK (Software Development Kit) is for use by customers who want to either hit the API using a REST client or programmatically to request margins on a portfolio of trades. The SDK is bundled as a zip file which will need to be unzipped onto the target box.

The F&O Deployable Margin SDK includes:

Readme.md

  • A README.md file containing technical details and instructions for developers on how to use the SDK.
    • This file will be changed and updated as new software builds are released.

licence.txt

  • licence.txt file contains licenses for any third-party jars distributed with the SDK.


arcDlApplication directory which holds:

  • Please note the already compiled Spring boot web example has been removed from the jar arcdl-web-example.jar with the introduction of the skinny jar.
  • Start scripts for Linux and Windows for the Spring Boot example web app in order to start it and test margining portfolios.
  • rpfs folder where the RPF (Risk Parameter File) should be placed.
    • There is a README in this folder describing the directory structure and where the RPF is to be placed.
  • Native directory containing the risk native C++ libraries and span dlls (which are only required for Windows).


examples directory holds the source for:

  • The example Sprint boot application (arcdl-web-example).
  • Standalone Java example classes that cover how to programmatically margin in a singlethreaded/multi-threaded manner.
  • Standalone Java example classes that cover how to load a local/distributed Redis cache with data from RPF.
  • Note: These are technical documentation samples; not intended for production use.


lib

  • Directory containing the arcdl-deployable.jar which is the jar to be used for integrating into your java tech stack. Examples on how to do this are in the above examples folder.
  • Also contains a pom.xml file with instructions for your local maven to download and include all the necessary dependencies required to be able to compile, package and run an application using our provided jar.


SampleData directory containing:

  • Example requests for importing into Postman which is a standard REST client interface (https://www.postman.com/product/api-client/).
  • cURL directory consisting of example cURL files. These can be used to make calls to an exposed end point in example spring boot web app.
  • Note: the supplied portfolio samples files contain test sample data and products contained therein may have expired. Updated samples are available in the CORE margin Calculator test (NR) environment for users logging in at https://cmecorenr.cmegroup.com/ then navigating to Download Center - Software.


Testing the F&O Deployable Software

After the F&O Deployable Software has been downloaded, clients can start testing the workflow and generating margin responses.

Step 1: Loading the Risk Parameter Files

Step 1.1: Downloading Risk Parameter Files in Deployable.

  • The rpfs (Risk Parameter File) directory in deployable needs to be populated with the unzipped RPF corresponding to the trade portfolio.
    • Navigating to the RPF Directory from the SDK: arcdl-sdk - arcDlApplication – rpfs.

Please note the deployable margin software version number is tightly coupled to the version of market data file the user selects to load. This user guide indicates compatible market data packages for a given build and how to run with limited backwards/historical file compatibility for SPAN RPFs.

Risk Parameter Files

Downloading Risk Parameter Files from Secure FTP

  • The type of Risk Parameter Files loaded into the software will determine whether the software runs the legacy SPAN methodology or the SPAN 2 methodology.
  • SPAN Risk Parameter Files (RPFs) for the F&O Deployable Software are available through CME's SFTP site. Users will need SFTP access to a new location to download the deployable Risk Parameter Files (RPFs).
    • SFTP location: cme/ftp/FIRMID/pub/SPAN2/rpf
    • File Names (Users will load the "span" file for the legacy SPAN methodology and "span2" file for the SPAN 2 methodology):
      • SPAN filename: cme.span.yyyymmdd.[cycle].zip

      • SPAN 2 filename: cme.span2.yyyymmdd.[cycle].zip

      • In the above, the 'cycle' will refer to the clearing cycle code produced throughout the business day. This can change over time and some cycles examples are c (complete), s (settle), i (intraday)
      • For the November 2021 release, CME is producing SPAN and SPAN 2 c cycle files, but to assist with the large size of the c file, the published c file contains only contracts with open interest. In the future additional cycle files will be published including a c file with all contacts including those without open interest.
    • Deployable software default RPF location: <install directory>\arcdl-sdk\arcDlApplication\rpfs
      • The latest version of Deployable is compatible SPAN 2 format RPFs from November 22. 2021. Older SPAN 2 files will not be supported in this build. See also "Limited Backwards Compatibility" below for information on SPAN RPF backwards compatibility.
  • Note: Users requiring access to SFTP for the first time or users requiring entitlements to an existing SFTP username, should contact posttradeservice@cmegroup.com to request access. Please provide your existing SFTP username, if necessary.

Initializing RPF Data in Deployable Software

  • Users must unzip the SPAN and SPAN 2 RPFs prior to initializing the software. The unzipped files are folders with the following names:
    • SPAN 2: yyyymmdd_FNO_SPAN2_C
        • Future state filenames will update the _C suffix to describe new daily cycles (i.e. _S, _I).
    • SPAN: yyyymmdd_FNO_SPAN_C
        • Future state filenames will update the _C suffix to describe new daily cycles (i.e. _S, _I).
    • Files should be unzipped at the top level only, nothing within the unzipped files requires unzipping/editing; all data within is obfuscated except for the SPAN risk array file.
    • The software requires the 'yyyymmdd_FNO' prefix in this filename to run.
  • Location: <install directory>\arcdl-sdk\arcDlApplication\rpfs
  • The location of the SPAN file within the file structure is <install directory>\arcdl-sdk\arcDlApplication\rpfs
    [unzipped file]\marketdata

    • Users can add SPAN files here to compute inter-exchange spread credits, for instance between CME and MGE.
  • Users can switch between multiple points in time when there are multiple dates of loaded risk parameter files. The argument controlling the loaded risk parameter file is in the start_windows bat/start_linux.sh.
    • The argument is -DfnoRpfDirectory=[market data unzipped filename i.e. yyyymmdd_FNO_SPAN_C].

    • If multiple files are supplied with the same business date in the root directory and the above argument is not used, deployable will use the following logic to initialize with the "latest" rpf file: first attempt to initialize a file with the most recent date in the filename pattern (i.e. yyyymmdd_FNO . .); if not satisfied, then the dataset with the most recent local timestamp will be initialized.
    • It is recommended users utilize the -DfnoRpfDirectory argument described above to pass reference to the specific dataset to limit issues with multiple daily data sets.


Best Practices for Using CME Risk Parameter Files

  • Users are not expected to manually edit the contents of the CME risk parameter files other than adding additional SPAN files to the /marketdata directory when necessary (for instance to compute inter-exchange spreads with the MGE SPAN file).
  • Users are not expected to change the naming conventions of any of the contents of an RPF file.
  • The RPF file structure can change from time to time.
  • CME does not support non-CME SPAN files which do not meet the formatting requirements of the Deployable Software. These files may load incorrectly or not at all during initialization.

Limited Backwards Compatibility

  • The Deployable Software contains limited backwards compatibility for older versions of the SPAN risk parameter file This is intended for margining historic points in time.
  • When a user supplies a SPAN RPF that the deployable software determines may not be compatible (i.e. is from an older point in time), it will log out this error: WARNING: Current configuration in RPF not compatible with deployable version. Overriding for backward compatibility.
  • Program will continue to initialize data supplied but results should not be considered for number-matching against SPAN software.
  • It is not recommended to initialize the software with older versions of the SPAN 2 RPF. This will result in calculation failures.

Using the SPAN Over-ride Feature

  • Deployable Software can read from SPAN files outside of the standard RPF data structure via the SPAN Over-ride feature. This is intended for use while loading historic risk array files in SPAN format and computing cross-margin benefits between CME and OCC in the SPAN model.


  • Loading historic risk array files, including the legacy .pa2 and .xml files:
    • The deployable SDK allows users to specify a legacy SPAN file in an override directory during start-up.
    • Please note this workflow requires a user to supply a compatible SPAN only RPF file (i.e. cme.span.yyyymmdd.[cycle].zip) prior to starting the initialization process. More details regarding the SPAN RPF files can be found in 'Risk Parameter Files' above.

      • Supplying a SPAN 2 RPF will invoke the SPAN 2 methodology which is not expected for the historic margin workflow.
    • Users should create a new directory or directories for the desired SPAN pa2/xml files and download/zip/store file(s) to this location.
      • For example, the user could set up a new directory locally as "[internal path]\arcdl-sdk\arcDlApplication\SPANFILES"

    • Users should specify the -DspanFilesDirectoryOverride=[local directory location] configuration in the start_windows.bat or start_linux.sh file.

      • For example, the user stores SPAN files in a new SPANFILES directory and starts the software with -DspanFilesDirectoryOverride= [internal path]\arcdl-sdk\arcDlApplication\SPANFILES argument in the start file. Please note it is expected users download the standard CME historical SPAN file in .pa2 or .xml format. The 'c21' version of the .xml file is not expected.

    • See example in Initialization of RiskAnalyticsService later in this document.
  • Users can employ the same process as above for processing cross-margin SPAN files (OCC/CME). For this workflow, it is expected the user would only supply the cross-margin SPAN file from this FTP site: ftp://ftp.cmegroup.com/span/data/xma to the SPAN over-ride directory. This is imperative because CME/OCC SPAN files represent cross-margin only products, not to be confused with the normal CME products in a CME SPAN file.


Step 1.2: Redis RPF Load

  • It is highly recommended to use Redis cache for loading SPAN 2 risk parameter files during production use.
  • When using Redis, users will need to set jvm arguments (-DcacheMode=Redis) or property

(System.setProperty("cacheMode", "Redis") before initializing the deployable service.

  • Users can utilize distributed Redis cache or local Redis cache.
    • Local Redis means that your application and Redis cache are running on the same server.
  • Distributed Redis cache can be used to improve memory management depending on the expected usage load.


Local Redis Cache Load

  • Unzip the SPAN 2 RPF under (same as disk load) <install directory>\arcdlsdk\arcDlApplication\rpfs.
  • Below is an example of RedisConfig with basic configurations:

Needs to be updated with new screenshot

    • Users can configure a timeout using the withTimeout (number of milliseconds) property. The default for this property is 60 seconds (60000 ms). An example of the timeout configuration can be found in the examples "ExampleMainWithTimeout.java".
    • SPAN 2 RPF will be loaded to local Redis during deployable startup. Local Redis port is 6379 and if you want to change any default value you can while creating RiskAnalyticsService as below:

      • RiskConfig.getRedisConfig() returns RedisConfig where you can override port.
      • Please refer to the ExampleMain class in the SDK.
      • Start deployable with property -DcacheMode=redis.Local redis true versus false implications. Condition (true) – the cache clears every time


Distributed Redis Cache Load

  • Users can load SPAN 2 RPF into central cache and can be used 'n' number of deployable instances.
    • Unzip the SPAN 2 RPF under (same as disk load) <install directory>\arcdl-sdk\arcDlApplication\rpfs.
    • Load cache by providing the SPAN 2 RPF folder and redis details as below:

Please refer to the ExampleCacheLoad class located in the SDK.

    • Start deployable with property -DcacheMode=redis and with redis server details. Please refer to the ExampleMainDistributedCache located in the deployable SDK.


Clearing the Redis Cache Load

  • Users can manually clear the central cache if needed:
    • Use clearCache to completely clear the cache.
    • Data in the cache can be deleted by RPF loaded by using deleteFromCache.
    • When loading the cache the default is to clear it first. To override this behavior set the property clearRedisCacheOnLoad to false.
    • Refer to ExampleCacheLoad class in SDK.
    • Manual cache clear is only supported for distributed cache, if using the local Redis cache simply create a new RiskAnalyticsService instance instead.


Step 2: Margin Request and Input Portfolio

  • The source code under the examples/arcdl-example directory is an example of how to correctly call the API. The source under the examples/arcdl-web-example is an example of a spring boot application that allows the API to be called over REST.

  • In the class MarginController there are examples on how to use the risk engine interface RiskAnalyticsService taking either CSV or JSON format. Using this a developer can imbed the arcdl deployable jar and risk library within their own application.


  • Build an input portfolio using the Risk API schema found in the CME CORE software center or by using the examples as a guideline. (See appendix for Risk API input format examples in .JSON and CSV)
  • The RiskPortfolioRequestMessage structure will be organized by categories and further detailed through a subset of attributes within each category. Below is a class snippet below:


Step 3: Margin Call and Margin Request

  • The MarginController class is where to find the call to retrieve the margin calculations. This is shown below, and it takes a RiskPortfolioRequestMessage object.

  • The margin service takes a RiskPortfolioRequestMessage object and returns a MarginDetailResponseMessage object.
  • The snippets below describe the class structure of the object sent to the margin service, those where there are tags @XmlElement or @XmlAttribute are the way that the JSON message is mapped to object instances of these classes and vice versa. Note that not all values need to be returned unless they are marked as required.




  • The RiskPortfolioRequestMessage snippet is below.

  • This consists of a payload object called RiskPortfolioRequest. This contains the point in time details, which should match the RPF date that is used to calculate margin on the call.

  • The RiskPortfolio object holds details of each of the portfolio being submitted for margin. A user can submit multiple portfolios at once. A snippet of the RiskPortfolio class is below:




Step 4: Analyzing the Margin Response Message

  • The MarginDetailResponseMessage class snippet is below:

  • This consists of a payload object called MarginDetailResponse. This contains the point in time details, which will correspond to the date used in the request above.

  • The list of PortfolioMarginDetail objects holds details of margin for the portfolio of trades that were submitted. A snippet of the PortfolioMarginDetail class is below:


Accessing the API: Best Practices

  • Always use the converter factories provided to create a converter. This will mean that any internal change made within the converters will not cause any code changes for those developers that have already integrated with the application.
  • Always use interfaces rather than class implementations directly. As any future changes made to physical classes can be hidden behind interfaces causing no change for existing integrations to the application.


Appendix

Inputs

Inputs for an F&O portfolio will contain data definitions for the Risk Portfolio Message. The
Risk Portfolio Message structure will be organized by categories (Header, Point In Time, Portfolio, Entities, Positions, and Instruments) and further detailed through a subset of attributes within each category. For the full list of attributes, please refer to the SPAN 2 Risk Analysis Framework document available in CME CORE or https://www.cmegroup.com/confluence/display/EPICSANDBOX/SPAN+2+Risk+Analysis+Framework.

  • Deployable Margin Software accepts two input formats: .json format and .csv format.
    • Examples of .json & .csv formatting structure can be found in the CME CORE NR download center under the Java Deployable SDK section.
  • Attributes will not be present in the input message if an optional field is left blank. The attached .json sample includes optional attributes just for clarity.
  • If encoding JSON, data type "decimal" can be encoded as "string".
  • Users can define multiple 'entity' blocks.
  • 'Underlying Period Code' is a conditional attribute and applied to options only. If an option's values have multiple similarities (i.e. product code and period code), or if the user is using the deployable software to compute requirements for non-CME markets, then 'underlying period code' is required.
  • A unique portfolio identifier is based on the fields: firmId, accountId, and originType.


Outputs

The Margin Results Message will be organized at various levels (Portfolio, CCP, POD, Product Group) and each level will contain further details for margin requirements, valuations, and sensitivities further broken down by currency when applicable. This structure will support results
for Futures and Options products margined through SPAN and SPAN 2 risk models. For the full
list of attributes and the full margin results data model, please refer to the SPAN 2 Risk Analysis Framework documentation available in CME CORE or
{_}{+}https://www.cmegroup.com/confluence/display/EPICSANDBOX/SPAN+2+Risk+Analysis+Framework+_.

  • Deployable Margin Software returns a margin result in .json message format.
    • Examples of .json message output can be found in the CME CORE NR download center under the Java Deployable SDK section.


Omnibus combinations

OmnibusInd indicator defines the relationship between parent and child portfolios, here are possible combinations of account type, NetQty, NakedLong and NakedShort when Omnibus is equal to YES and NO.

AccountType

OmnibusInd

NetQty

NakedLong

NakedShort

SPECULATOR

YES

0/null

≥ 0/null

≥ 0/null

HEDGE

YES

0/null

≥ 0/null

≥ 0/null

SPECULATOR

NO

<>/null

0/null

0/null

HEDGE

NO

<>/null

0/null

0/null

MEMBER

NO

<>/null

0/null

0/null


If OmnibusInd is set to YES, then the final NetQty must either be 0 or null also the Naked Long must be null or non-negative and Naked Short must be null or non-negative. The account type must be either HEDGE or SPECULATOR.
If Omnibus is set to NO, then the final NetQty must not be null and Naked Short must be null or 0 and Naked long must be null or 0.
The following omnibus edge cases will return warning messages:

  • When a fully disclosed omnibus request (i.e. no positions) provides and ID but there are no children present. A warning message will occur, and the portfolio will not be returned in the margin response.
  • If a child account and parentPortfolioId do not match an Omnibus ID.
  • Different accounts with the same ID will return a warning for the account it is not aggregating to.
  • Multiple omnibus parent accounts with the same Id will return a warning message.

Errors List


Error Type

Error Code

Error Message

NO_PAYLOAD

ERR001

"Payload can't be null"

NO_TRADES_POSITIONS

ERR002

"No trades and/or positions provided"

INVALID_INPUTTYPE

ERR003

"Unsupported portfolio type supplied in inputType parameter: %s. Must be one of: %s"

INVALID_CSV_FORMAT

ERR004

"Issue whilst converting from csv format. See logs for more details"

MARGIN_CALCULATION_ERROR

ERR005

"Unable to process margin request, error during calculations: %s. Check logs for more information"

MARGIN_AGGREGATION_ERROR

ERR006

"%s"

NO_RPF_SUPPLIED

ERR007

"Unable to create the Analytics Service Implementation. No risk parameter file provided, or directory does not exist"

INVALID_RPF

ERR008

"Unable to properly initialize the risk analytics service. %s risk parameter file invalid: %s"

INVALID_POINT_IN_TIME

ERR009

"Point in time supplied is invalid: %s. Should be in YYYY-MM-DD format"

NO_RPF_FOR_POINT_IN_TIME

ERR010

"Portfolio %s of type %s cannot be margined because the supplied point in time %s does not match any loaded risk parameter file"

RPF_INCORRECT_FORMAT

ERR011

"Unable to determine cycle dates from %s – risk parameter file missing or in the wrong format. Check the
README in the rpfs folder in the sdk for information on the format for market data"

INVALID_PORTFOLIO

ERR012

"Invalid portfolio supplied"

INVALID_POSITION

ERR013

"Invalid position at line $d"

INVALID_SPAN_POSITION

ERR014

"Invalid position at line $d"

NO_MODULE_CONFIG_FOR_RPF

ERR015

"Unable to find configuration for provided risk parameter file: %"

CANNOT_BE_ENCODED

ERR016

"Unable to encode value"

INVALID_TRADE

ERR017

"Invalid trade at line $d"

NO_POINT_IN_TIME_SUPPLIED

ERR018

"No point in time supplied"

INVALID_TRANSACTION

ERR019

"Invalid transaction at line $d"

CANNOT_CONFIGURE_DIFFERENT_DATES

ERR020

"Issue when attempting to load different versions of risk library for different dates"

CANNOT_FIND_INSTRUMENT

ERR021

"Instrument does not exist"

UNABLE_TO_LOAD_CACHE

ERR022

"Unable to load cache %s"

FAILED_CREATE_RISK_DATA_READERS

ERR023

"Failed to create risk data readers for file in %s"

FAILED_TO_REFRESH_RPF

ERR024

"Failed to refresh/reload risk parameter file"

ERROR_IN_RL_MARGIN_CALCULATION

ERR025

"Error calculating margin for position/s, please contact CME"

INVALID_PORTFOLIO_CUSTOMER_ACCOUNT_TYPE

ERR026

"Invalid portfolio customer account type"

INVALID OMNIBUS

ERR100

"Invalid
netQty/nakedShortQty/nakedLongQty supplied for
parentPortfolio/omnibusIndicator combination

N/A

N/A

WARNING: Current configuration in RPF not compatible with deployable version. Overriding for backward compatibility.


Lower-Level Warnings and INFO Messages

Message Type

Message Code

Message Details

DUPLICATE_OMNIBUS_PARENT_ACCOUNT

WRN028

Duplicate omnibus parent account, aggregation may occur to this account

OMNIBUS_ACCOUNT_WITH_NO_POSITIONS_AND_NO_CHILDREN

WRN029

Omnibus account has no positions and no child accounts - margin response not returned

OMNIBUS_PARENT_ACCOUNT_NOT_FOUND_FOR_CHILD_ACCOUNT

INF030

No omnibus parent account found for child account

OMNIBUS_PARENT_ACCOUNT_HAS_NO_CHILDREN

INF031

No child accounts found for omnibus parent account

FAILED_TO_RETRIEVE_SPAN2_DATA_FROM_RPF

WRN032

Missing SPAN 2 product data in RPF. Check logs for more information


  • Anything with a '%' in front of it gets injected with the actual details depending on the error.
  • Error code "ERR013" is also used for any semantic F&O position errors.
  • Error codes are made up of a couple of different messages
    • One way is the number of the field in error + "_" + the line number in the csv in error. For example, error code. ERR116_2 indicates ERR116 which is an invalid origin type field and is in line 2 in the csv input file.
    • Another way is with a counter attached. For example, let's say you have a portfolio of 1000 positions and if there was a semantic validation error in each line then you could potentially have error codes from ERR017_1 to ERR017_1000.


Error codes coming out of the converter:

Error Type

Error Code

REQUEST_ID

ERR101

VERSION

ERR102

SENT_TIME

ERR103

BUSINESS_DATE

ERR104

CYCLE_CODE

ERR105

RUN_NUMBER

ERR106

PORTFOLIO_ID

ERR107

CURRENCY

ERR108

CUSTOMER_ACCOUNT_TYPE

ERR109

OMNIBUS_INDICATOR

ERR110

PARENT_PORTFOLIO_ID

ERR111

CLEARING_ORGANIZATION_ID

ERR112

FIRM_ID

ERR113

ACCOUNT_ID

ERR114

ACCOUNT_NAME

ERR115

ORIGIN_TYPE

ERR116

ACCOUNT_TYPE

ERR117

SEGREGATION_TYPE

ERR118

LEDGER_BALANCE

ERR119

OPEN_TRADE_EQUITY

ERR120

SECURITY_ON_DEPOSIT

ERR121

NET_QUANTITY

ERR122

NAKED_LONG_QUANTITY

ERR123

NAKED_SHORT_QUANTITY

ERR124

EXCHANGE_ID

ERR125

PRODUCT_CODE

ERR126

PRODUCT_TYPE

ERR127

PERIOD_CODE

ERR128

OPTION_TYPE

ERR129

STRIKE

ERR130

UNDERLYING_PERIOD_CODE

ERR131

MEMO

ERR132


Additional error message text which can be found after the ERROR_MESSAGE string:

  • Failed validation: No point in time supplied
  • Failed validation: Cycle code must be one of [ITD, EOD]

  • Failed validation: No valid currency supplied
  • Failed validation: No account id supplied
  • Failed validation: Origin type must be one of [CUST, CUSTOMER, HOUS, HOUSE]

  • Failed validation: No portfolio level customer account type supplied
  • Failed validation: No firm id supplied
  • Failed validation: Omnibus Account Type cannot be MEMBER
  • Failed validation: No valid product type supplied
  • Failed validation: No clearing organization id supplied
  • Failed validation: No period code supplied
  • Failed validation: No product code supplied
  • Failed validation: No valid exchange id supplied
  • Failed validation: No valid exchange id supplied: must be one of CBT,CME,CMX,COMEX,NYM,NYMEX
  • Failed validation: No strike supplied
  • Failed validation: Missing Series, could not populate underlying period code
  • Failed validation: No PUT or CALL option type supplied
  • Failed validation: Strike price should not be supplied for this instrument
  • Failed validation: Option type should not be supplied for this instrument
  • Failed validation: Underlying period code should not be supplied for this instrument
  • Failed validation: Naked short quantity is not allowed for non-omnibus accounts
  • Failed validation: Naked long quantity is not allowed for non-omnibus accounts
  • Failed validation: Final Net must be non-null
  • Failed validation: Final net quantity must not be 0 for non-omnibus accounts
  • Failed validation: Final Net quantity is not allowed for an omnibus account
  • Failed validation: Naked short quantity must be non-negative integer
  • Failed validation: Naked long quantity must be non-negative integer
  • Failed validation: Naked long and naked short must not both be 0


Release Examples

The below examples are intended to assist with new features and concepts introduced in Deployable Software, not to provide an exhaustive list of all features. For technical details, please review the "examples" provided in the software download package.

List of Start-up Arguments

Listed in alphabetical order.

Start-up Argument

Data Type

Required?

Description

Default

-DcacheMode

string

N

If "redis" informs deployable to run with redis data cache; else ignored.

N/A

-DdontIgnoreSpanErrors

boolean

N

true = does not ignore errors from the SPAN library, fails to margin when errors from SPAN library occur.
false = ignores invalid span errors and margins the rest of the portfolio.

falseLikely deprecated need to check.

-DfilterByOrigin

string

N

HOUS = margins only portfolios where OriginType = House
CUST = margins only portfolios where OriginType = Customer
See list of valid origin Types in errors above.

N/A

-DfnoRpfDirectory

string

N

User-supplied risk parameter file directory under suppled root directory (see -Drpf.source.path)

N/A

-DignoreInvalidPositions

boolean

N

true = ignores invalid positions in request and passed only valid positions to margin
false = passes all positions, regardless of validity, to margin. Can result in errors for portfolios with invalid positions.

true

-Dlog4j.configurationFile

string

N

User-supplied log4j configuration file, describing log level.

N/A

-DomnibusPortfolioValidationDisabled

boolean

N

true = omnibus warning messages are not exposed in the margin response.
false = omnibus warning messages are exposed in the margin response, see "Lower-Level Warnings and INFO Messages" above

false

-DriskLibraryDump

boolean

N

true = allows extra logging via arcDlApplication/data folder

false

-Drpf.source.path

string

Y

User-supplied risk parameter file root directory.

./rpfs

-Dserver.port

number

Y

User-supplied server port.

8082

-DspanFilesDirectoryOverride

string

N

User-supplied legacy SPAN file location (see Risk Parameter Files above).

N/A

Initialization of RiskAnalyticsService

RiskAnalyticsServiceFactory.createRiskAnalyticsService(…) takes an object of type RiskConfig.class. This class has a builder internal class.
For the purposes of the following examples let's assume a file structure like the bellow:

//If passing just the rpfDirectory, it will try to pick the latest RPF available under that folder. In this case the RPF under 20210119_FNO will be selected.
Example:

//If passing the rpfDirectory plus the fnoRpfDirectory it will select the specific folder inside the rpfDirectory. The folder 20190528_FNO will be selected.
Example:

//validationDisabled (default: false) à if true completely disables the semantic validation. This flag does not affect the converter syntax validation.
Example:

//ignoreInvalidPositions (default:false) à if true ignores invalid trades picked up by semantic validation and margins the good ones. This is the validation before the trades are sent to be margined. Syntactically invalid positions picked up by the converter are handled using the converter API described below in the section 'Using RiskFnoToRiskConverter'.
Example:

//dontIgnoreSpanErrors (default:false) à if true then it will throw exception when errors are returned from the margin calculation. When false the errors will simply be added to the response.
Example:
//riskLibraryDump (default:false) à if true it will add extra logging from inside the native calculation
Example:
//spanFilesDirectoryOverride - will override the marketdata folder span files that are part of the standard SPAN/SPAN 2 rpf file installation. When margining historical SPAN only files, the override folder must be used along with an existing/installed SPAN rpf ( cme.span.yyyymmdd.[s.c].zip ). This folder can also be used to add in cross-margin and/or inter-exchange span files (e.g. MGE, OCC).
Example:

Using RiskFnoToRiskConverter

//with errors being returned as a list. It will still return a riskPortfolioRequestMessage.
Example:

//with exception being thrown when error is found. Exception of type RiskAnalyticException is thrown with information about the error. Flow is interrupted.


Log File Parameter

Deployable uses SLF4j which allows users to plugin desired logging framework. To help users understand logging framework, there is an example log4j xml file supplied in the examples/arcdl-example directory under src/main/resources. This can be changed to use whatever logging level required and packaged into users' tech stack with deployable jar by changing the "Root Level=" field per the below list of log levels.
A second option is to supply a separate log xml file and then this can be loaded into deployable.

  • Include a log4j2.xml file configuration file within the packaged JAR. (note: The highlighted code is where the output file properties, such as file name and logging pattern, can be modified).

  • To supply the parameter at runtime.

Log Levels

Level

Description

Default?

Perf Test Log File Example*

DEBUG

Highest level logging, includes details on calculation engine order or operations.

N

14,700 KB

INFO

Standard logging, some calculation details and all errors

Y

8,400 KB

WARN

Errors only.

N

6,200 KB

ERROR

Very limited logging produced

N

1 KB

OFF

No logging is produced

N

N/A


*Perf test conditions:
Initialize SPAN-only risk parameter file (2/2/22 point in time) + MGE 2/2/22 EOD pa2 file
Load portfolioA – 13,500 positions with errors, no margin expected
Load portfolioB – 12,700 positions, multiple errors, margin expected

Reducing the size of the Log File

In order to enable debug mode on the logging levels, you will need to download the following log4j file:

In this file find <Root level="INFO">, you can change that to DEBUG (at the bottom of the file).

  • Then place this in the same location as the arcdl-web-example.jar.
  • Then in your start script before the jar name use this parameter:
    • Dlog4j.configurationFile=log4j.xml


Performance Metrics

Baseline Test Case Description:

  • 1.5m positions across 15k accounts, 100 positions average
  • Testing performed using CME-produced SPAN and SPAN 2 RPF files, not using legacy SPAN files via SPAN Over-ride feature.
  • Optimized Hardware:
    • 8 cores, 10 worker threads
    • 64gb RAM
    • Total Max memory usage: 31 GB
  • A Redis process is running locally on our test boxes that is used for caching; this could be run remotely on a separate box but will introduce some latency.
  • Different memory usage metrics:
    • JVM memory is the memory being used by the Java Virtual Machine when running the app
    • Redis memory is the memory being used by the Redis cache
    • Total memory is the entire amount of memory being used by the box. This includes the JVM memory, memory used by Redis cache as well as the OS.




  • Performance Test Case Results (v2.0):Need to add Redis perf tests and 2.2 perf tests from Pete
Request TypeTotal Time (mm:ss)Time per portfolioPortfolios per secondMax JVM memory usage (max vm mem)Redis memory usageMax total memory usage
SPAN5:2021.3ms46.812 GBn/a25 GB
SPAN 28:1933.3ms3012.7 GB10.8 GB32 GB
ThreadsSPAN (HH:MM:SS)SPAN 2 (hh:mm:ss)
100:42:0001:09:30
1000:05:2000:08:30
  • No labels