CME Optimizer Software User Guide

The current version of Optimizer is version 19, which is available for testing November 15th, 2023. This page will focus on integration for Optimizer 19 and will be updated as and when new builds are made available.

System Requirements

The following system requirements are required to install and run CME Optimizer 19*:

• • Windows Server 2016, 2019 or 2022
  • Quad-core Processor
  • 16 GB of available memory (32 GB is recommended)
  • 15 GB of available storage (~5GB installation / ~10GB daily data files).
  • Microsoft .NET 6.0 Runtime x64 (6.0.6 or higher).
  • Microsoft Visual C++ 2015-2022 Redistributable (x64) (14.32.31326.0 or higher)

Expected Performance

Based on extensive Optimizer 19 testing:

Downloading Optimizer

CME Optimizer 19 is available to download from CME CORE. To download, perform the following steps:

1. Log into CME CORE: https://cmecore.cmegroup.com/

1. Launch CORE Margin Calculator from the menu
2. Click the Download Center tab, then click on the Software tab
3. Scroll down to the CME Optimizer section and click on the Optimizer 19 file link, this will start the download process.

If you do not have a CME Login ID, then click on the Register link on the login page. If you have any questions about creating a CME Login ID, please contact Enterprise Application & System Entitlements (EASE).

Installation and Running Sample Files

Installing Optimizer 19

To install CME Optimizer 19 perform the following steps:

1. Download Optimizer 19, refer to the Downloading CME Optimizer 19 section for more information

2. Log onto the system where Optimizer 19 is to be installed. You should log on as an administrative user.

3. Double-click on the Optimizer 19 installer (filename: Optimizer.19.0.61.0.msi), this will start the installation process.

4. Follow the on-screen instructions.

5. You must accept the End-User License Agreement (EULA) to install Optimizer 19.

6. Accept the default installation location or optionally change it:

7. Select Install (admin entitlements required) and wait while program installs.

9. Once installation has completed, it is best practice to reboot the PC on which the software is installed. You can choose to automatically run the Optimizer 19 Samples once the installation completes. 

Troubleshooting

If you run into issues during the installation, please refer to the guidance below. Alternatively, reach out to our posttradeservices@cmegroup.com for further assistance:

1. Verify that you have the correct privileges to install software on the target system and that security software/policies are not preventing software from being installed
2. Verify that you have the minimum system requirements for hardware and operating system
3. Verify that you have installed the software prerequisites and that a system reboot has been performed
4. If the installer starts, but fails to complete, try running the MSI with logging enable from the command-line e.g. PowerShell:
   
   .\Optimizer.19.0.61.0.msi /log installer.log
   
   
5. If the installer log does not point to a localized issue, then forward the log to posttradeservices@cmegroup.com for further investigation (see below).

Sending Diagnostics Information to CME for Troubleshooting

If you are requested to send diagnostics information to posttradeservices@cmegroup.com to help them provide troubleshooting assistance, then please provide the following information along with any requested files within a compressed archive i.e. Zip, 7-zip, Tar etc.

• Operating System + Version
• MSI version
• Firm ID
• Technical and business contact information (where applicable)
• Description of the issue e.g. Installation Error, Run-time Error
• Context e.g. installing, running program interactively, running program as an automated task/job
• Any input, output or configurations files (where applicable) e.g. positions data, market data or configuration files, command-line arguments
• Any error messages / codes

Opening the Optimizer 19 Program Folder

During the installation process a convenient desktop shortcut is provided to allow you to easily access the Optimizer 19 Program folder. Double-clicking the “CME Optimizer 19 Folder” shortcut icon will launch the Windows Explorer process and navigate into the Program folder path.

Running Optimizer 19 Sample Set

CME Optimizer 19 includes a sample data set for the new Optimizer 19 plugin. This can be launched via a desktop shortcut or via the command-line.

Running from Desktop Shortcut

During the installation process a convenient desktop shortcut is provided to allow you to easily launch the  Optimizer 19 plugins with the sample data set. Double-clicking the “Run CME Optimizer 19 Sample” shortcut icon will launch a command-prompt and start running the sample data set.

Running from Command-line

The sample data set can also be run via the command-line. Open a command-prompt using powershell.exe and type the following:

CD "C:\Program Files\CME Group\CME Optimizer 19\Program"
.\OptimizerHost.exe --Configuration "..\..\Samples\configuration.json"

Note your program installation path may differ.

When the sample optimization completes, the Outputs folder will contain several files, including:

• Log file
• Reports – total savings estimate, margin summary and funding impact
• Transfers in CSV/FIXML format

Running Optimizer via Plugin

Optimizer 19 has been built using a plugin architecture, which allows greater release flexibility and opens the possibility to introduce additional optimization services in the future.

Listing Available Plugins to Run

To list the available plugins, open a command-prompt using powershell.exe and type the following:

CD "C:\Program Files\CME Group\CME Optimizer 19\Program"
.\OptimizerHost.exe --list

Note your program installation path may differ. The initial release of CME Optimizer 19 provides the following plugins:

• Optimizer (aka Optimizer 19)

Futures releases of Optimizer will introduce new plugins that provide enhanced or new functionality. To run a specific plugin, refer to the Running a specific plugin section.

Running a Specific Plugin

By default, CME Optimizer 19 will run the Optimizer plugin (this is Optimizer 19). To run a specific plugin, open a command-prompt using powershell.exe and type the following:

CD "C:\Program Files\CME Group\CME Optimizer 19\Program"
.\OptimizerHost.exe --run "Optimizer"

Note your program installation path may differ. CME Optimizer 19 will automatically initialize and start the specified plugin. To determine what plugins are currently available, refer to the List available plugins section. If you enter a plugin name that is either incorrect or does not exist, then a run-time error will occur, and the program will exit.

Optimizer 19 Plugin Command-line Arguments

The Optimizer 19 plugin provides several command-line arguments, these are listed in the table below. Note that some command-line arguments support both short and long-hand argument names:

Running Optimizer as a Scheduled Task

Optimizer 19 can be to execute as a scheduled task. To create a new task using Windows Task Scheduler perform the following steps:

1. From the Start menu, launch Task Scheduler
2. On the actions pane, click “Create Task”
3. Set the following task properties
   (Note some properties will be specific to your environment/requirements)
   
   

Optimizer Configuration File

Optimizer 19 Plugin Configuration File

The Optimizer 19 plugin requires a mandatory configuration file. By default, this configuration file is called configuration.json. The Optimizer 19 plugin configuration is based upon the JSON (JavaScript Object Notion) format. Unlike prior versions of Optimizer, all configurable settings are located within a single file. A default configuration file can be found within the Optimizer 19 plugin folder:

C:\Program Files\CME Group\CME Optimizer 19\Plugins\Optimizer

Note your program installation path may differ. If you run Optimizer 19c plugin, it will (by default) attempt to locate the configuration.json in the plugin folder. If you want to change this, then refer to the Specifying a custom configuration.json file section. If the configuration file is not found a run-time error will occur, and the program will exit.

The following table details each configuration section:

FICC section new for the RBOE workflow, released with version 19. Please see RBOE user guide for more information: https://www.cmegroup.com/confluence/display/EPICSANDBOX/Treasury+Rules-based+Offset+Engine.

Note that the JSON specification has some basic structural rules, some key considerations are listed below, but you can read more information on the JSON specification at https://www.json.org/:

• For string values that represent file and/or directory paths, the backslash character “\” must be escaped using two backslash characters e.g. “\\”
• Boolean values must be in lower case i.e. true or false. Specifying any other type of casing cause a run-time error.
• Strings (text) must be enclosed in double-quotes

Exclusions

With Optimizer 19, users can utilize enhanced exclusion features. This section describes how to use and configure exclusions. Updated to reflect changes to default configurations with version 19. 

{
	/*
	Optimizer configuration sections omitted for brevity
	*/        
	"Exclusions": {
	"IncludeBaselineInOptimalState": false,
    "EarlyExercise": {
      "Enabled": true
    },
    "PBAccount": {
      "Enabled": false,
      "Exclusions": [
        {
          "Enabled": false,
          "Type": "OOF",
          "Accounts": []
        }
      ]
    },
    "FiccPbAccount": {
      "Enabled": false,
      "Exclusions": [
        {
          "Enabled": false,
          "Type": "FUT",
          "Accounts": []
        }
      ]
    },
    "Exchange": {
      "Enabled": false,
      "Exclusions": []
    },
    "Product": {
      "Enabled": false,
      "Exclusions": []
    },
    "TradeEvents": {
      "Enabled": true,
      "Events": [
        {
          "Enabled": true,
          "Name": "First Position Date - Treasury Roll",
          "BeginEventType": 17,
          "DaysBefore": 0,
          "EndEventType": 7,
          "DaysAfter": 0,
          "Type": "FUT",
          "Exchange": "CBT",
          "Codes": [ "17", "21", "25", "26", "TN", "UBE" ]
        },
        {
          "Enabled": true,
          "Name": "Last Trade Date - CME Option Expiration",
          "BeginEventType": 7,
          "DaysBefore": 1,
          "EndEventType": 999,
          "DaysAfter": 0,
          "Type": "OOF",
          "Exchange": "CME",
          "Codes": [ "SR3", "S0", "S2", "S3", "S4", "S5" ]
        },
		{
          "Enabled": true,
          "Name": "Last Trade Date - CBT Option Expiration",
          "BeginEventType": 7,
          "DaysBefore": 1,
          "EndEventType": 999,
          "DaysAfter": 0,
          "Type": "OOF",
          "Exchange": "CBT",
          "Codes": [ "17", "21", "25", "26", "TN", "UBE" ]
        }
      ]
    }
  }
}

Example configuration.json File

{
  "Defaults": {
    "TransfersByPbAccount": true,
    "BreakOnException": false,
    "MoveDecision": "LIFO",
    "NettingMoveDecision": "LIFO",
    "ExclusionMoveDecision": "LIFO",
    "Culture": "en-US",
    "TimeZone": "Central Standard Time",
    "FloorSpanForFinalMarginCheck": true
  },
  "Inputs": {
    "InputDirectory": "..\\..\\Inputs",
    "PositionsFilename": "Positions",
    "IrsPnlFilename": "IRSPNL_",
    "IrsDeltaLadderFilename": "IRSDL_",
    "SpanFileNameSuffix": "cust.spn",
    "MarketDataArchiveFilename": "cme_optimizer_marketdata_*.zip",
    "UseSpanFileInArchive": true
  },
  "Outputs": {
    "OutputDirectory": "..\\..\\Outputs",
    "CsvTransfersFilename": "csvTransfers.csv",
    "TotalSavingsFilename": "Total Savings Estimate.csv",
    "FundingImpactsFileName": "FundingImpact.csv",
    "MarginSummaryFileName": "MarginSummary.csv",
    "FixmlOutputFilename": "fixmlTransfers.txt"
  },
  "Fixml": {
    "FixmlMsgEvtSrc": "API",
    "FixmlClOrdIdStatic": "0",
    "FixmlClOrdIdStaticId": "PM001",
    "SingleSidedReport": true
  },
  "Ficc": {
    "Enabled": false,
    "ExecutionMode": "BeforeIrsOptimization",
    "OptimizeMoveDecision": "LIFO",
    "UseBackMonthContracts": true,
    "FiccPositionsFilename": "FICCPositions_",
    "FiccEquivalentPositionsFilename": "*XMFICCPOSN_*.csv"
  },
  "Exclusions": {
	"IncludeBaselineInOptimalState": false,
    "EarlyExercise": {
      "Enabled": true
    },
    "PBAccount": {
      "Enabled": false,
      "Exclusions": [
        {
          "Enabled": false,
          "Type": "OOF",
          "Accounts": []
        }
      ]
    },
    "FiccPbAccount": {
      "Enabled": false,
      "Exclusions": [
        {
          "Enabled": false,
          "Type": "FUT",
          "Accounts": []
        }
      ]
    },
    "Exchange": {
      "Enabled": false,
      "Exclusions": []
    },
    "Product": {
      "Enabled": false,
      "Exclusions": []
    },
    "TradeEvents": {
      "Enabled": true,
      "Events": [
        {
          "Enabled": true,
          "Name": "First Position Date - Treasury Roll",
          "BeginEventType": 17,
          "DaysBefore": 0,
          "EndEventType": 7,
          "DaysAfter": 0,
          "Type": "FUT",
          "Exchange": "CBT",
          "Codes": [ "17", "21", "25", "26", "TN", "UBE" ]
        },
        {
          "Enabled": true,
          "Name": "Last Trade Date - CME Option Expiration",
          "BeginEventType": 7,
          "DaysBefore": 1,
          "EndEventType": 999,
          "DaysAfter": 0,
          "Type": "OOF",
          "Exchange": "CME",
          "Codes": [ "SR3", "S0", "S2", "S3", "S4", "S5" ]
        },
		{
          "Enabled": true,
          "Name": "Last Trade Date - CBT Option Expiration",
          "BeginEventType": 7,
          "DaysBefore": 1,
          "EndEventType": 999,
          "DaysAfter": 0,
          "Type": "OOF",
          "Exchange": "CBT",
          "Codes": [ "17", "21", "25", "26", "TN", "UBE" ]
        }
      ]
    }
  }
}

Creating a Custom configuration.json File

It is recommended users create a specific configuration.json file. Most firms prefer this approach as it allows them to place the configuration file in a non-application specific directory e.g. D:\<firm>\apps\data\... To create a new configuration.json file, open a text editor (an editor that supports JSON syntax and validation is recommended). Copy the example configuration.json in this user guide or copy the contents of the configuration.json file in the Optimizer directory. Once you have the configuration outline in an appropriate editor, you can change any settings as required. Save the file as configuration.json to your desired location. Note that it is possible to change the configuration.json filename, refer to the Changing the configuration.json filename section.

Specifying a Custom Configuration File

The Optimizer plugin folder includes a default configuration.json which can be overridden. This is done by specifying the --configuration <filename> argument and providing a file path, for example: -

CD "C:\Program Files\CME Group\CME Optimizer 19\Program"
.\OptimizerHost.exe –Configuration "C:\Temp\AcmeClearing\Optimizer\configuration.json"

Note your program installation path may differ.

Changing the Default Configuration Filename

If you are creating a custom configuration.json file, you are not restricted to using the “configuration.json” filename. You can change the existing the filename to valid filename, but it is recommended that you maintain the .JSON file extension. If you change the configuration filename, then you must use the Optimizer 19 --configuration argument, for example: -

CD "C:\Program Files\CME Group\CME Optimizer 19\Program"
.\OptimizerHost.exe –Configuration "C:\Temp\AcmeClearing\Optimizer\acme-custom-config.json"

Optimizer Data Files 

Optimizer 19 Data Files

Optimizer 19 requires several data files to perform portfolio optimization. Note the Optimizer Market Data Archive file is a zipped file containing many other files. This file was created to limit the number of inputs required to run Optimizer. Optimizer unzips this file during initialization.

• Positions CSV file†
• FICCPositions CSV file†*
• Equivalent Position Report*
• Configuration file i.e. configuration.json
• IRS DL
• IRS PNL
• Span risk parameter file (i.e. cust.spn, note must be unzipped prior to run)
• Optimizer Market Data Archive (ZIP file)

† A positions file is generated by a firm

††† Files in the New Release test environment as published to the same location with a .nr file name extension.

The default configuration expects all data files to reside within an Inputs folder which is located within the installation directory. However, it is recommended that you create your own configuration and data folder outside of the installation directory, refer to the Creating Custom Input/Output Folders section below for more information.

*Optional unless using RBOE feature introduced with version 19. Please see RBOE user guide for more details: https://www.cmegroup.com/confluence/display/EPICSANDBOX/Treasury+Rules-based+Offset+Engine. 

Changing the Input/Output folder locations

By default, the configuration file will point to default input/output folder locations that typically reside within the installation folder. If you run the tree command within the program installation folder you can see these folders: -

CD "C:\Program Files\CME Group\CME Optimizer 19\Program"
tree

In addition to create a custom configuration, you can change the directory paths by opening the configuration file and updating the following configuration properties:

{
  // Note that configuration sections/properties have been omitted for brevity

  "Inputs": {
    "InputDirectory": "..\\..\\Inputs",
    // other properties omitted
    "SpanIniFilesFolder": "..\\..\\Inputs",
  },
  "Outputs": {
    "OutputDirectory": "..\\..\\Outputs",
    // other properties omitted
  }
}

Creating Custom Input/Output Folders

With CME Optimizer 19, you are not limited to a single input/output folder. You can create multiple folders for a variety of situations such as (but not limited to): per-firm folders, splitting daily runs into date-folders, running different positions file inputs, splitting-up large portfolios, analyzing configuration variations or troubleshooting.

 As a best practice, it recommended that you create a folder outside of the installation directory that will contain all data and configuration. There are a number of benefits to this approach, including (but not limited to): - separation of concerns (program installation folder vs. input/outputs data folder), security (security permissions can be easily applied to a non-installation directory) and maintainability (i.e. application upgrades) .

Example Scenario #1: Per-firm Folders

If you run optimization on-behalf of two or more firms, then you can create folders and configurations on a per-firm basis.  Depending on your available system resources, you can run more than a single instance of CME Optimizer 19, provided each instance is targeting a different configuration file and different input/output folders. For example, assuming we have a “ManagedFirm” folder, this folder can contain sub-folders for Firm A, Firm B and Firm C. Each folder has its own isolated data and configuration. The configuration file for Firm A is called firma-configuration.json and this configuration file specifically points to the Firm A folder path for inputs and outputs. Note that the input folder for Firm A contains all data (positions, IRS, span etc.) required to run Optimizer. When running Optimizer for Firm A, the following command would be used:

CD "C:\Program Files\CME Group\CME Optimizer 19\Program"
.\OptimizerHost.exe –Configuration "C:\ManagedFirm\FirmA\firma-configuration.json"

Example Configuration File for Firm A

{
  // firma-configuration.json
  // Note that configuration sections/properties have been omitted for brevity
  "Inputs": {
    "InputDirectory": "C:\\ManagedFirm\\FirmA",
    // other properties omitted
    "SpanIniFilesFolder": "C:\\ManagedFirm\\FirmA",
  },
  "Outputs": {
    "OutputDirectory": "C:\\ManagedFirm\\FirmA\\Outputs",
    // other properties omitted
  }
}

Example Configuration File for Firm B

{
  // firmb-configuration.json
  // Note that configuration sections/properties have been omitted for brevity
  "Inputs": {
    "InputDirectory": "C:\\ManagedFirm\\FirmB",
    // other properties omitted
    "SpanIniFilesFolder": "C:\\ManagedFirm\\FirmB",
  },
  "Outputs": {
    "OutputDirectory": "C:\\ManagedFirm\\FirmB\\Outputs",
    // other properties omitted
  }
}

Equivalent Command-line for Firm B:

CD "C:\Program Files\CME Group\CME Optimizer 19\Program"
.\OptimizerHost.exe –Configuration "C:\ManagedFirm\FirmB\firmb-configuration.json"

Example Configuration File for Firm C

{
  // firmc-configuration.json
  // Note that configuration sections/properties have been omitted for brevity
  "Inputs": {
    "InputDirectory": "C:\\ManagedFirm\\FirmC",
    // other properties omitted
    "SpanIniFilesFolder": "C:\\ManagedFirm\\FirmC",
  },
  "Outputs": {
    "OutputDirectory": "C:\\ManagedFirm\\FirmC\\Outputs",
    // other properties omitted
 }
}

Equivalent Command-line for Firm C:

CD "C:\Program Files\CME Group\CME Optimizer 19\Program"

.\OptimizerHost.exe –Configuration "C:\ManagedFirm\FirmC\firmc-configuration.json"

Common Optimizer Log Errors

This section describes many, but not all, Optimizer log errors. See Recommended Remediation below for additional guidance.

Legal

Click-through Agreement

Prior to downloading/installing the software, CME Optimizer users must review and agree to the the End User License Agreement (EULA). 

To obtain the software to review, please contact CME Group Post Trade Services.

Open Source Software

Please see deployable margin software Open Source Software here: Open Source Software.