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

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 powerful risk calculation library that firms can use to integrate directly into their own infrastructure.

Contents




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



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 new Java API
      • Production agreement license ready


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.
Technical Prerequisites:

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 SPAN 2 RPF (Risk Parameter File) is ~9.5G but will grow as more products and asset classes are add.


Linux:

  • Red Hat Enterprise Linux Server release 7.8 or later

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 VM


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, titled: F&O Java Deployable Margin SDK v1.1.42.

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.


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.


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.



Risk Parameter Files

  • 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. In builds prior to v1.46 (August 2021 release) users configured SPAN versus SPAN 2 mode, but this functionality is deprecated with the introduction of SPAN versus SPAN 2 risk parameter files.
  • SPAN Risk Parameter Files (RPFs) for the F&O Deployable Software are available through CME's SFTP site. Users will need SFTP access in order to download the deployable Risk Parameter Files (RPFs).
    • SFTP location: cme/ftp/FIRMID/PUB/SPAN2
    • File Names (Users will load the ".span" file for the legacy SPAN methodology and ".span2" file for the SPAN 2 methodology):
      • cme.span.yyyymmdd.[c/s].zip

      • cme.span2.yyyymmdd.[c/s].zip

      • c indicates the file is the 'complete' file with all contracts represented including those without open interest.
      • s indicates the file is the 'final settle' file which contains all active contracts (i.e. the active only file) but not inclusive of products without open interest.
    • Location: <install directory>\arcdl-sdk\arcDlApplication\rpfs
    • The latest version of Deployable is compatible SPAN 2 format RPFs from April 19 and June 21, 2021 (note these files remain in the JAVADLFNO directory) as well as daily files made available in September 2021. Historical dates, other than with legacy SPAN array files, will not be supported in this build.
  • Note: For testing purposes, if you need SFTP access to grab the market data files, please contact posttradeservice@cmegroup.com to request access.


  • 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 supply a compatible SPAN only RPF file (i.e. cme.span.yyyymmdd.[s/c].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.
    • Users should specify the -DspanFilesDirectoryOverride=[local directory location] configuration in the start_windows.bat or start_linux.sh file.

      • For example, the user creates/stores SPAN files in a new SPANFILES directory in the rpfs directory and includes -DspanFilesDirectoryOverride=./rpfs/SPANFILES configuration 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.


  • For loading an RPF to support Inter-exchange spreads, the RPF directory needs to be populated with the risk parameter file corresponding to the trade portfolio's date.
    • The RPF directory in deployable needs to have both the CME risk parameter file package from the SFTP site and the MGE file from the CME FTP site.
      • The latest version of Deployable when running in SPAN 2 mode, is compatible only with a Risk Parameter Files from April 19th, 2021 and June 21st, 2021 for margin analysis. The MGE files for the same dates need to also be placed alongside the sample SPAN 2 file in the config directory.
    • As a reminder, the MGE file needs to be unzipped.


  • Loading files to support OCC cross margining:
    • For the purposes of getting accurate cross margining results, the rpfs directory needs to have just the cross margining specific parameter file which can be located on the CME FTP site: ftp://ftp.cmegroup.com/span/data/xma.
      • Either the .spn file or the .pa2 file can be used but the file needs to be unzipped when put into the RPF folder.
    • For users who want the ability to run OCC cross margining without having to remove the CME SPAN file, we have introduced a new workflow with this latest release.
      • The first requirement is to add a new file directory in the SDK under the application where the start script is located. The name of this folder is up to the user. For the purposes of this example, the user-defined name is 'SPANfiles'.
      • The second requirement is to add a new tag in the "start_windows" bat file for Windows and "start_linux.sh" for Linux called -DspanFilesDirectoryOverride=./SPANfiles. For reference, the tag could be placed anywhere in the file in between -Dserver.port=8082 and

-Drpf.source.path parameter.

        • Note: If this tag is present, it will reference the new RPF location. To continue using the original RPF location, the tag needs to be removed.

      • This new directory will behave in the same way the old processing file did. Meaning, that the OCC file must be the only one in that location and that the OCC & SPAN files can't be in this same location to successfully run cross margining.
        • Each OCC file must be present in the sub-folder by itself for the margin requests to work.
    • This new directory also works with legacy SPAN files and MGE files.
      • The MGE and SPAN file must be located together for margin requests to work for inter-exchange processing.
      • This directory and start script must be in sync for use. In other words, you can't have the location in the start script but not have the directory setup and vice versa.


  • The compatible SPAN 2 Risk Parameter Files for the F&O Deployable Software are available through our SFTP site.
    • SFTP location: cme/ftp/FIRMID/PUB/JAVADLFNO
    • File Names: javadlfutopt_c_20210419_nr.zip; javadlfutopt_c_20210621_nr.zip
    • Location: <install directory>\arcdl-sdk\arcDlApplication\rpfs
    • The latest version of Deployable (SPAN/SPAN 2 model), is compatible only with the sample SPAN 2 risk parameter files from April 19th, 2021 and June 21st, 2021 trade dates.
      • If you are running with an older version of the deployable software, you will still need an older version of SPAN 2 RPF.
  • This version of Deployable is also compatible with the same points in time for an active only (.s) SPAN 2 risk parameter file. The active only files are smaller in size. (about 1gb – 2gb) and contains only active products. The fixed point in time for testing the active only file are also for April 19th, 2021 and June 21st 2021.
    • SFTP location: cme/ftp/FIRMID/PUB/JAVADLFNO
    • File Names: javadlfutopt_s_20210419_nr.zip; javadlfutopt_s_20210621_nr.zip
  • Location: <install directory>\arcdl-sdk\arcDlApplication\rpfsUsers can switch between multiple points in time when there are multiple dates of loaded risk parameter files. in the parameter controlling the loaded risk parameter file is in the start_windows bat/start_linux.sh.


o The parameter is -DfnoRpfDirectory=[sub-directory name i.e. YYYYMMDD_FNO_MARGIN_EOD].
Step 1.2: Redis RPF Load


  • SPAN 2 requires Redis cache for RPF load for production use.


  • Users will need to set jvm arguments (-DcacheMode=Redis) or property

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

  • Users can have distributed Redis cache or local Redis cache.

o Local Redis means that your application and Redis cache are running on the same server.

Local Redis Cache Load


  • Unzip the SPAN 2 RPF under (same as disk load) <install directory>\arcdlsdk\arcDlApplication\rpfs.


  • 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.

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.

o 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. If an option's values have multiple similarities (i.e. product code and period code), then 'underlying period code' is required. Otherwise this field is optional.
  • 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.
    o 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


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


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:
-Users
---someUser
-----rpfDirectory
-------20190527_FNO
-------20190528_FNO
-------20190529_FNO
---otherFolder
---someOtherFolder

//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:
RiskConfig = new Builder()

.rpfDirectory("/Users/someUser/rpfDirectory")


.build();
RiskAnalyticsService riskAnalyticsService =
RiskAnalyticsServiceFactory.createRiskAnalyticsService(riskConfig);

//If passing the rpfDirectory plus the fnoRpfDirectory it will select the specific folder inside the rpfDirectory. The folder 20190528_FNO will be selected.
Example:
RiskConfig riskConfig = new Builder()

.rpfDirectory("/Users/someUser/rpfDirectory")


.fnoRpfDirectory("20190528_FNO")
.build();
RiskAnalyticsService riskAnalyticsService =
RiskAnalyticsServiceFactory.createRiskAnalyticsService(riskConfig);

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

.rpfDirectory("/Users/someUser/rpfDirectory")


.validationDisabled(true)
.build();
RiskAnalyticsService riskAnalyticsService =
RiskAnalyticsServiceFactory.createRiskAnalyticsService(riskConfig);
//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:
RiskConfig riskConfig = new Builder()

.rpfDirectory("/Users/someUser/rpfDirectory")


.ignoreInvalidPositions(true)
.build();
RiskAnalyticsService riskAnalyticsService =
RiskAnalyticsServiceFactory.createRiskAnalyticsService(riskConfig);

//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:
RiskConfig riskConfig = new Builder()

.rpfDirectory("/Users/someUser/rpfDirectory")


.dontIgnoreSpanErrors(true)
.build();
RiskAnalyticsService riskAnalyticsService =
RiskAnalyticsServiceFactory.createRiskAnalyticsService(riskConfig);

//riskLibraryDump (default:false) à if true it will add extra logging from inside the native calculation
Example:
RiskConfig riskConfig = new Builder()

.rpfDirectory("/Users/someUser/rpfDirectory")



<span style="color: #a9b7c6">.riskLibraryDump(</span><span style="color: #cc7832">true</span><span style="color: #a9b7c6">)</span>
<span style="color: #a9b7c6">.build()</span><span style="color: #cc7832">;</span>
<span style="color: #a9b7c6">RiskAnalyticsService</span> <span style="color: #a9b7c6">riskAnalyticsService =</span>
<span style="color: #a9b7c6">RiskAnalyticsServiceFactory.createRiskAnalyticsService(riskConfig)</span><span style="color: #cc7832">;</span>
//spanFilesDirectoryOverride  will override the marketdata folder span files that are part of the standard SPAN/SPAN2 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:
<span style="color: #09c6c1"><strong>RiskConfig</strong></span> <span style="color: #a9b7c6">riskConfig</span> <span style="color: #d5e4f3">=</span> <span style="color: #cc7832">new</span> <span style="color: #1ac73f"><strong>Builder</strong></span><span style="color: #9876aa"><em>()</em></span>
<span style="color: #d5e4f3">.</span><span style="color: #1ac73f"><strong>rpfDirectory</strong></span><span style="color: #9876aa"><em>(</em></span><span style="color: #d5d823">"/Users/someUser/rpfDirectory"</span><span style="color: #9876aa"><em>)</em></span>
<span style="color: #d5e4f3">.</span><span style="color: #1ac73f"><strong>spanFilesDirectoryOverride</strong></span><span style="color: #9876aa"><em>(</em></span><span style="color: #d5d823">"/Some/override/directory"</span><span style="color: #9876aa"><em>)</em></span>
<span style="color: #d5e4f3">.</span><span style="color: #1ac73f"><strong>build</strong></span><span style="color: #9876aa"><em>()</em></span><span style="color: #cc7832">;</span>
<span style="color: #d5e4f3">RiskAnalyticsService</span> <span style="color: #d5e4f3">riskAnalyticsService =</span>
<span style="color: #d5e4f3">RiskAnalyticsServiceFactory.createRiskAnalyticsService(riskConfig);</span>


Using RiskFnoToRiskConverter

//with errors being returned as a list. It will still return a riskPortfolioRequestMessage.
Date pointInTime = new Date();
Optional<RiskFnoToRiskConverter> optional =
ConverterFactory.createConverter(RiskFnoToRiskConverter.class);
if (optional.isPresent()) {
RiskFnoToRiskConverter converter = optional.get();
List<Error> errors = new ArrayList<>();
RiskPortfolioRequestMessage riskPortfolioRequestMessage = converter.map("riskFnoStringCsv", pointInTime, errors);
}
//with exception being thrown when error is found. Exception of type RiskAnalyticException is thrown with information about the error. Flow is interrupted.
Date pointInTime = new Date();
Optional<RiskFnoToRiskConverter> optional =
ConverterFactory.createConverter(RiskFnoToRiskConverter.class);
if (optional.isPresent()) {
RiskFnoToRiskConverter converter = optional.get();
List<Error> errors = new ArrayList<>();
RiskPortfolioRequestMessage riskPortfolioRequestMessage = converter.map("riskFnoStringCsv", pointInTime);
}

Log File Parameter

There is an example log4j xml file supplied in the examples/arcdel-example directory under src/main/resources. This can be changed to use whatever logging level you require and packaged into your tech stack with deployable jar.
A second option is to supply a separate log xml file and then this can be loaded into deployable.

  1. 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).

  1. To supply the parameter at runtime.

Reducing the size of the Log File

In order to enable debug mode on the logging levels, you will need to download the follow 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

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 powerful risk calculation library that firms can use to integrate directly into their own infrastructure.

Contents

Revision 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

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

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 new Java API
      • Production agreement license ready


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.

Technical Prerequisites:

  • Azul Zulu Java 8 version 1.8.0_271 or later Java 8 installed, and the Java bin directory is on your path
  • Redis 5.0.5 or later (https://redis.io/download). Redis is not mandatory for dev testing but required for production
  • 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 SPAN 2 RPF (Risk Parameter File) is 8.8G but will grow as more products and asset classes are add.

Linux:

  • Red Hat Enterprise Linux Server release 7.8 or later

Windows:

* Windows Server 2012 R2

* Microsoft Foundation Classes MFC should be installed. We have 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 VM

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



2. The software can be found under the section labeled Java Deployable SDK, titled: F&O Java Deployable Margin SDK v1.1.34.

F&O Java Deployable Margin SDK, includes:

  • JAR file – arcdl-deployable.jar
  • Software Development Kit
    • 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

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

 

arcDlApplication directory which holds:

  • The already compiled Spring boot web example jar arcdl-web-example.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 single-threaded/multi-threaded manner
  • Standalone Java example classes that cover how to load a local/distributed Redis cache with data from RPF


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


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.



Readme.md

  • A README.md file provides information for developers on how to use the SDK. This file will be changed and updated as new software builds are released. Further technical integration requirements for both Windows and Linux can be found in the README section of the SDK.


arcDlApplication directory containing:

  • Start scripts for Linux and Windows for the Spring Boot example web application. For debugging interactions with the native risk library add the java system property to the start linux script – Drisk.library.dump=true. This will output xml files to the directory data/rl-dump.
  • The native C++ risk libraries in a native directory
  • Example JAR file arcdl-web-example.jar to start an example spring boot application to programmatically make an API call
  • Example start scripts for linux and windows docker container
  • Market Data Folder where users should place their Risk Data files. This directory has a README describing the directory structure depending on point in time and market data types

lib

  • Contains deployable jar called arcdl-deployable.jar. This is to be used for coding in your java application

examples

  • There are two projects under examples: arcdl-example and arcdl-web-example that contains the source code which can be compiled to recreate the executable jar, namely the arcdl-web-example.jar, in the arcDlApplication directory.

SampleData

  • Contains example collection that can be imported into Postman, which is a standard REST client interface. This is an example of how to make an API call
  • A cURL directory which contains examples on how to make an API call from Linux using cURL (csv and JSON input formats)

SampleJava

  • Directory holding an example Main class in Java, called ExampleMain, demonstrating how to use deployable interfaces and factories supplied in the deployable jar to determine margin.
  • This example main class shows how to programmatically create a F&O converter using a factory, use this converter to parse an F&O .csv format portfolio and then to margin the portfolio calling risk library.

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

Deployable Modes

  • The deployable software can run portfolio’s in two modes: SPAN only mode or SPAN 2 mode. (Note: When switching between modes, the Deployable application needs to be restarted)
    • SPAN mode will utilize the legacy SPAN model
    • SPAN 2 mode will utilize both the SPAN & SPAN 2 models
      • SPAN 2 model for in-scope Nymex energy products only
      • CME is not currently standing over the numbers in SPAN 2 mode. The purpose of running in SPAN 2 mode is for firms to start their technology project and understand the data points that are being returned in the margin response.
  • To change between SPAN & SPAN 2 mode, users can set the mode using a new tag called “-Dspan2”. This tag is included in the “start_windows” bat file for Windows and “start_linux.sh” for Linux.
    • For running deployable in SPAN only mode, set the tag as -Dspan2=false
    • For running deployable with a portfolio containing a combination of products supporting SPAN and SPAN 2 modes or SPAN 2 mode, set the tag as -Dspan2=true (Note: This is the default setting)

Risk Parameter Files

  • SPAN Risk Parameter Files (RPFs) for the F&O Deployable Software are available through CME’s SFTP site. Users will need SFTP access in order to download the deployable Risk Parameter Files (RPFs).
    • SFTP location: cme/ftp/FIRMID/PUB/JAVADLFNO
    • File Name: javadlfutopt_c_YYYYMMDD_nr.zip
    • Location: <install directory>\arcdl-sdk\arcDlApplication\rpfs
    • The latest version of Deployable in SPAN only mode, is compatible only with RPFs starting from May 24th, 2021 trade date and forward. Historical dates will not be supported in this build.
  • Note: For testing purposes, if you need SFTP access to grab the market data files, please contact PostTradeServices@cmegroup.com.


  • For loading an RPF to support Inter-exchange spread’s, the RPF directory needs to be populated with the risk parameter file corresponding to the trade portfolio’s date.
    • The RPF directory in deployable needs to have both the CME risk parameter file package from the SFTP site and the MGE file from the CME FTP site.
      • The latest version of Deployable when running in SPAN only mode, is compatible only with an RPF from May 24th, 2021 trade date and forward.
      • The latest version of Deployable when running in SPAN 2 mode, is compatible only with a Risk Parameter Files from January 19th, 2021.The MGE file for January 19th, 2021 needs to also be placed alongside the sample SPAN 2 file in the config directory.
    • As a reminder, the MGE file needs to be unzipped.


  • Loading files to support OCC cross margining:
    • For the purposes of getting accurate cross margining results, the rpfs directory needs to have just the cross margining specific parameter file which can be located on the CME FTP site: ftp://ftp.cmegroup.com/span/data/xma
      • Either the .spn file or the .pa2 file can be used but the file needs to be unzipped when put into the RPF folder.
    • For users who want the ability to run OCC cross margining without having to remove the CME SPAN file, we have introduced a new workflow with this latest release.
      • The first requirement is to add a new file directory in the SDK under the application where the start script is located. The name of this folder is up to the user. For the purposes of this example, the user-defined name is ‘SPANfiles’:
      • The second requirement is to add a new tag in the “start_windows” bat file for Windows and “start_linux.sh” for Linux called “-DspanFilesDirectoryOverride=./SPANfiles”. For reference, the tag could be placed anywhere in the file in between -Dserver.port=8082 and

-Drpf.source.path parameter.

  • Note: If this tag is present, it will reference the new RPF location. To continue using the original RPF location, the tag needs to be removed.


  • This new directory will behave in the same way the old processing file did. Meaning, that the OCC file must be the only one in that location and that the OCC & SPAN files can’t be in this same location to successfully run cross margining.
    • Each OCC file must be present in the sub-folder by itself for the margin requests to work.
  • This new directory also works with legacy SPAN files and MGE files.
    • The MGE and SPAN file must be located together for margin requests to work for inter-exchange processing.
    • This directory and start script must be in sync for use. In other words, you can’t have the location in the start script but not have the directory setup and vice versa.
  • The compatible SPAN 2 Risk Parameter Files for the F&O Deployable Software is available through our SFTP site.
    • SFTP location: cme/ftp/FIRMID/PUB/JAVADLFNO
    • File Name: javadlfutopt_c_20210119_nr.zip
    • Location: <install directory>\arcdl-sdk\arcDlApplication\rpfs
    • The latest version of Deployable in SPAN 2 mode (SPAN/SPAN 2 model), is compatible only with the sample risk parameter file from January 19th, 2021 trade dates.
      • If you are running with an older version of the deployable software, you will still need an older version of SPAN 2 RPF.


  • The SPAN 2 sample RPF for January 19th, 2021 can also be used for running the deployable software in SPAN only mode as well.
    • SPAN 2 risk parameter files will not be published daily until August of 2021.


  • This version of Deployable in SPAN 2 mode is also compatible with an active only file. The active only file is smaller in size (about 1gb – 2gb) and contains only active products. The fixed point in time for testing the active only file is also for January 19th, 2021.
    • SFTP location: cme/ftp/FIRMID/PUB/JAVADLFNO
    • File Name: zip
    • Location: <install directory>\arcdl-sdk\arcDlApplication\rpfs


  • Users now have the ability to switch between multiple points in time when there are multiple dates of loaded risk parameter files. To do this, there is a new parameter added in the start_windows bat/start_linux.sh.
    • The new parameter is -DfnoRpfDirectory=YYYYMMDD_FNO


Step 1.2: Redis RPF load

  • SPAN 2 requires Redis cache for RPF load for production use.
  • Users will need to set jvm arguments (-DcacheMode=Redis) or property (System.setProperty(“cacheMode”, “Redis”) before initializing the deployable service.
  • Users can have distributed Redis cache or local Redis cache.
    • Local Redis means that your application and Redis cache are running on the same server.

Local Redis cache load

  • Unzip the SPAN 2 RPF under (same as disk load) <install directory>\arcdl-sdk\arcDlApplication\rpfs
  • 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:

  • getRedisConfig() returns RedisConfig where you can override port.
  • Please refer to the ExampleMain class in the SDK.
  • Start deployable with property -DcacheMode=redis

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 CacheLoadService.clearCache
    • 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 is an example of a sprint 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:

  • This consists of a payload object called RiskPortfolioRequest. This contains the point in time details, which should match the market data date that is used to calculate the margin on the call, it's class snippet is:



  • The list of RiskPortfolio objects holds details of each portfolio being submitted for margin. A snippet of the RiskPortfolio class is 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.
  • First, we will describe what RiskPortfolioRequestMessage is and then the MarginDetailResponseMessage
  • The RiskPortfolioRequestMessage snippet is below.

  • This consists of a payload object called RiskPortfolioRequest. This contains the point in time details, which should match the market data 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 snipped 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.

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. If an option’s values have multiple similarities (i.e. product code and period code), then ‘underlying period code’ is required. Otherwise this field is optional.
  • 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 too
  • 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_MARKETDATA_SUPPLIED

ERR007

"Unable to create the Analytics Service Implementation. No market data provided or directory does not exist"

INVALID_MARKETDATA

ERR008

"Unable to properly initialize the risk analytics service. %s market data invalid: %s"

INVALID_POINT_IN_TIME

ERR009

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

NO_MARKETDATA_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 market data"

MARKET_DATA_INCORRECT_FORMAT

ERR011

"Unable to determine cycle dates from %s - market data missing or in the wrong format. Check the README in the market data 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_MARKET_DATE

ERR015

"Unable to find configuration for provided market data: %"

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"

INVALID OMNIBUS

ERR100

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

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: 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

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 that we have a file structure like the bellow:
-Users
---someUser
-----marketDataDirectory
-------20190527_FNO
-------20190528_FNO
-------20190529_FNO
---otherFolder
---someOtherFolder
 
 
//If passing just the marketDataDirectory, it will try to pick the latest market data available under that folder. In this case the market data under 20190529_FNO will be selected.
Example:
RiskConfig riskConfig = new Builder()
    .marketDataDirectory("/Users/someUser/marketDataDirectory")
    .build();
RiskAnalyticsService riskAnalyticsService = RiskAnalyticsServiceFactory.createRiskAnalyticsService(riskConfig);
 
 
//If passing the marketDataDirectory plus the fnoMarketDataDirectory it will select the specific folder inside the marketDataDirectory. The folder 20190528_FNO will be selected.
Example:
RiskConfig riskConfig = new Builder()
    .marketDataDirectory("/Users/someUser/marketDataDirectory")
    .fnoMarketDataDirectory("20190528_FNO")
    .build();
RiskAnalyticsService riskAnalyticsService = RiskAnalyticsServiceFactory.createRiskAnalyticsService(riskConfig);
 
 
//validationDisabled (default: false)  if true completely disables the semantic validation. This flag does not affect the converter syntax validation.
Example:
RiskConfig riskConfig = new Builder()
    .marketDataDirectory("/Users/someUser/marketDataDirectory")
    .validationDisabled(true)
    .build();
RiskAnalyticsService riskAnalyticsService = RiskAnalyticsServiceFactory.createRiskAnalyticsService(riskConfig);
 
//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:
RiskConfig riskConfig = new Builder()
    .marketDataDirectory("/Users/someUser/marketDataDirectory")
    .ignoreInvalidPositions(true)
    .build();
RiskAnalyticsService riskAnalyticsService = RiskAnalyticsServiceFactory.createRiskAnalyticsService(riskConfig);
 
 
//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:
RiskConfig riskConfig = new Builder()
    .marketDataDirectory("/Users/someUser/marketDataDirectory")
    .dontIgnoreSpanErrors(true)
    .build();
RiskAnalyticsService riskAnalyticsService = RiskAnalyticsServiceFactory.createRiskAnalyticsService(riskConfig);
 
 
//riskLibraryDump (default:false)  if true it will add extra logging from inside the native calculation
Example:
RiskConfig riskConfig = new Builder()
    .marketDataDirectory("/Users/someUser/marketDataDirectory")
    .riskLibraryDump(true)
    .build();
RiskAnalyticsService riskAnalyticsService = RiskAnalyticsServiceFactory.createRiskAnalyticsService(riskConfig);
 
Using RiskFnoToRiskConverter
//with errors being returned as a list. It will still return a riskPortfolioRequestMessage
Date pointInTime = new Date();
Optional<RiskFnoToRiskConverter> optional = ConverterFactory.createConverter(RiskFnoToRiskConverter.class);
if (optional.isPresent()) {
    RiskFnoToRiskConverter converter = optional.get();
    List<Error> errors = new ArrayList<>();
    RiskPortfolioRequestMessage riskPortfolioRequestMessage = converter.map("riskFnoStringCsv", pointInTime, errors);
}
 
//with exception being thrown when error is found. Exception of type RiskAnalyticException is thrown with information about the error. Flow is interrupted.
Date pointInTime = new Date();
Optional<RiskFnoToRiskConverter> optional = ConverterFactory.createConverter(RiskFnoToRiskConverter.class);
if (optional.isPresent()) {
    RiskFnoToRiskConverter converter = optional.get();
    List<Error> errors = new ArrayList<>();
    RiskPortfolioRequestMessage riskPortfolioRequestMessage = converter.map("riskFnoStringCsv", pointInTime);
}
 
Log File Parameter
There are two ways to use the log file parameter. In both cases the xml file will be the exact same, all that changes is with Option 2 there can be an xml included in the JAR but if you provide an external xml with the parameter it "overrides" the JAR xml.

  1. 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.)

2. To supply the parameter at runtime

-Dlog4j.configurationFile=DIR/log4jConfig.xml


Reducing the size of the Log File

In order to enable debug mode on the logging levels, you will need to download the follow 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  - 

-Dlog4j.configurationFile=log4j.xml


  • No labels