Migration Guide

New in v3

This guide helps you migrate older strategy definitions to the current MesoSim v3 format. It covers what changed, how the portal auto‑migration works, and what you should review manually.

For field structure and parameters, see Strategy Definition Reference; for expression vocabulary, see Script Engine; for scheduling semantics, see Timing Module; and for valuation tools, see Options Valuation Module.

Pages marked with v3 badges were updated or introduced for v3.

Version history

v1 → v2: Migrates automatically upon job rerun in the portal. Backward compatible migration path.
v2 → v3: The MesoSim Portal auto‑migrates the strategy definition and surfaces notes in the Job Editor. Manual changes might be required due to behavioral changes.

How Auto‑Migration Works

When loading a v2 job in the Job Editor, the portal performs a v2→v3 migration and displays a “Conversion” panel. It categorizes outcomes:

[AUTO]: Items updated automatically.
[WARN]/[ERROR]: Items that likely require manual review or edits.
Other notes: Informational context.

Use the Job Editor’s Validate button to catch any remaining issues. You can toggle the conversion details panel to see exactly what was changed or flagged.

Backward‑Incompatible & Behavioral Changes

The following items may change outcomes or require code/JSON edits. Each includes a recommended action.

Summary

Change	Impact	Recommended Action
Backtest and Settings section	New sections to organize top‑level fields	Move fields as shown below
StrikeSelector set	v3: Bid/Ask/Mid/Delta/StrikePrice/Complex only	Replace `Statement` with `StrikePrice`; use Complex if necessary
Indicators Removed	Indicator calculation is replaced with External Data	Bring in your indicators using External Data
Timing variables are decimals	Exact equality checks may fail; MesoLive differs	Use `int(var)` or tolerant compares (`<=`, `>=`)
Weighted vega (wvega)	Slight numeric differences vs int‑based DTE	Accept decimal behavior; cast DTE if needed
Marker legs (qty=0) greeks	Leg greeks shown; excluded from pos_* sums	Include leg greeks explicitly if needed
Leg selection constraint	Default now `UniqueInPosition`	Set to `FullyUnique` if you need stricter uniqueness
underlying_iv and hv ranges	The two variables are changed	Divide by 100 to get the old value

Backtest and Settings sections

Backtest section added (see Strategy Definition Reference → Backtest). TemplateName becomes StrategyName.

v2 (before):

{
  "Name": "generate",
  "TemplateName": "MyStrategy",
  "Start": "2021-01-01T00:00:00",
  "End": "2021-12-31T00:00:00",
  "Cash": 10000,
  "Symbol": "SPX"
}

v3 (after):

{
  "StrategyName": "MyStrategy",
  "Backtest": {
    "Name": "generate",
    "Start": "2021-01-01T00:00:00",
    "End": "2021-12-31T00:00:00",
    "Cash": "10000"
  },
  "Symbol": "SPX"
}

Settings replaces SimSettings (see Strategy Definition Reference → Settings)

v2 (before):

{
  "SimSettings": {
    "FillModel": "AtMidPrice",
    "SlippageAmt": 0,
    "Commission": { "CommissionModel": "FixedFee", "OptionFee": 1.5 },
    "PositionMonitor": { "TraceCollectionInterval": "Hourly" },
    "Margin": { "Model": "RegT", "HouseMultiplier": null, "RegTMode": "CBOEPermissive" }
  }
}

v3 (after):

{
  "Settings": {
    "Sim": {
      "FillModel": "AtMidPrice",
      "SlippageAmt": 0,
      "Commission": { "CommissionModel": "FixedFee", "OptionFee": 1.5 },
      "PositionMonitor": { "TraceCollectionInterval": "Hourly" },
      "TearsheetGeneration": "On"
    },
    "Core": {
      "LegSelectionConstraint": "UniqueInPosition",
      "ExpirationSelectionConstraint": "AbortOnReuse",
      "Margin": {
        "Model": "RegT",
        "HouseMultiplier": null,
        "RegTMode": "CBOEPermissive"
      }
    }
  }
}

Indicators removed (see Strategy Definition Reference → Indicators)

v2 top‑level Indicators are not available in v3. Use External CSV Data to bring inputs as variables.

StrikeSelector Set

StrikeSelector updates (see Strategy Definition Reference → Structure)

v3 supports exactly one selector per leg from: BidPrice, AskPrice, MidPrice, Delta, StrikePrice, Complex.
v2’s plain Statement selector becomes StrikePrice in v3.
Min/Max continue to constrain the chosen selector’s metric (price or delta).
Complex keeps Statement (score), Target, and optional Constraints.

v3 requires exactly one selector from BidPrice, AskPrice, MidPrice, Delta, StrikePrice, Complex. Replace legacy Statement with StrikePrice:

"StrikeSelector": {
  "StrikePrice": "leg_short_put_strike - 25"
}

If you used non‑delta greek selection in v2, convert to Complex (compute a score in Statement, select closest to Target, optionally enforce Constraints).

Variable related changes

The timing variables (e.g., leg_*_dte, leg_*_dit, expiration_*_dte, expiration_*_dit, timing.days_in_trade) are now decimals. Use int(var) or tolerant comparisons (<=, >=) over exact equality.
All the acc_* variables are removed
minutes_after_open and minutes_after_close is now served from the Timing module.
Weighted vega (wvega) uses decimal DTE: sqrt(30 / dte).

Strategy Definition v2 to v3 change summary

From (v2)	To (v3)
`Name`	`Backtest.Name`
`Start`	`Backtest.Start`
`End`	`Backtest.End`
`Cash`	`Backtest.Cash` (expression)
`TemplateName`	`StrategyName`
`SimSettings.*`	`Settings.Sim.*`
`SimSettings.PositionMonitor.*`	`Settings.Sim.PositionMonitor.*`
`SimSettings.Margin.*`	`Settings.Core.Margin.*`
`StrikeSelector.Statement`	`StrikeSelector.StrikePrice`
`Indicators`	Remove; replace with `ExternalData` if needed

underlying_iv and underlying_hv range change

The underlying_iv and underlying_hv variables were to percentage representation. Their range changed from 0..1 to 0..100.

Timing variables are now decimals

Timing variables (e.g., leg_*_dte, days_in_trade, schedule calculations) are decimals in v3. Exact equality checks (such as timing.days_in_trade == 2) with decimals are discouraged (it's nearly impossible to execute at the exact 1 day mark). Casting to whole numbers using the int function solves this problem, or use tolerant comparisons (<=, >=) to allow for execution after the desired event.

v2: Exit.Conditions=["leg_long_put_dte == 1"]
v3 (cast): Exit.Conditions=["int(leg_long_put_dte) == 1"]
v3 (tolerant): Exit.Conditions=["leg_long_put_dte <= 1"]

Weighted vega (wvega)

Weighted vega uses sqrt(30 / dte). With decimal DTE, small numeric differences vs integer logic can appear. If you modeled DTE as ints previously, cast if you want to emulate legacy behavior:

sqrt(30 / max(1, int(leg_short_call_dte)))

The old behavior was stepping with whole numbers and clamping dte at 1. The new behavior scales dte smoothly down to 0 (at expiration). This is more realistic, especially for 0DTE runs.

Marker legs (qty=0) greeks

Leg‑level greeks for marker legs are exposed, but marker legs are excluded from position sums (pos_delta, pos_theta, etc.). This is useful in scenarios where legs are taking part in entry, adjustment or exit condition which are not part of the structure itself (e.g. Skew-based entries).

Leg selection constraint default

Default is now UniqueInPosition (legs unique within a position; sharing allowed across positions). If you need the original behavior, set Settings.Core.LegSelectionConstraint = "FullyUnique" (Strategy Definition Reference → Settings.Core.LegSelectionConstraint).

How Auto‑Migration Works​

Backward‑Incompatible & Behavioral Changes​

Summary​

Backtest and Settings sections​

StrikeSelector Set​

Strategy Definition v2 to v3 change summary​

underlying_iv and underlying_hv range change​

Timing variables are now decimals​

Weighted vega (wvega)​

Marker legs (qty=0) greeks​

Leg selection constraint default​