Simulations

All simulation methods are available on client.simulation. What you can do depends on your tier.

Cached simulations

Free tier users can browse and download a fixed set of pre-run baseline simulations across a selection of HKEX and LSE symbols, calibration dates, and scenarios, with up to 10 Monte Carlo runs per group.

# List all available cached simulations
cached = client.simulation.list_cached()
print(f"Found {cached['total']} simulation groups")

for sim in cached["simulations"]:
    print(f"{sim['symbol']} {sim['date']} {sim['scenario']}: {sim['n_runs']} runs")
    print(f"  sim_id: {sim['example_sim_id']}")

# Filter by symbol
cached = client.simulation.list_cached(symbol="700.HK")

# Filter by scenario
cached = client.simulation.list_cached(scenario="flash_crash")

Download limits

Free-tier downloads are metered per simulation group — all the Monte Carlo runs of one symbol/date/scenario combination. You can add up to 3 new groups per rolling 24-hour window by default, counted the same way on every download path: single-file downloads (get_sim_data), bulk ZIPs (get_bulk_data), and the web explorer. Not per call, per run, or per file format.

Once you have downloaded a group it is yours permanently: re-fetching it later — more runs, a different file format, a different endpoint — never consumes quota again. Pro and demo tiers are unlimited.

Check your current allowance and the groups you own with client.profile.downloads(), which documents every field it returns. A request that would exceed the allowance returns HTTP 429 without charging anything, until the window rolls over. If you need more than the default, email support@simudyne.com — we can raise your daily limit without a Pro upgrade.

Submit a simulation

result = client.simulation.run(
    symbol="700.HK",
    cal_date="2025-09-02",
    provider="omd",
    exchange="hkex_securities",
    n_runs=5
)

job_id = result["job_id"]
sim_ids = result["sim_ids"]
print(f"Submitted job {job_id} with {len(sim_ids)} simulations")

result = client.simulation.run(
    symbol="700.HK",
    cal_date="2025-09-02",
    provider="omd",
    exchange="hkex_securities",
    n_runs=5,
    scenario="flash_crash",
    scenario_params={
        "start_time": "11:00:00",   # trigger mid-session
        "impact_multiplier": 20.0,  # severe liquidity drain
        "order_freq": "500ms",      # high-frequency cascade
    },
    exec_algos=[{
        "type": "twap",
        "order_size": 50,           # lots, not shares
        "horizon": 7200,            # two hours
        "start_time": "09:30:00",
        "frequency": 30,
    }],
)
job_id = result["job_id"]

Market scenarios

Inject market events into your simulation to stress-test strategies. Set the scenario parameter to one of:

scenario_params keys

impact_multiplier : float, optional

Total scenario volume as a multiple of average total resting liquidity, bid and ask combined. Must be greater than 0.

order_size_ratio : float, optional

Size of each child order as a fraction of average resting liquidity. Must be in (0, 1].

order_freq : str, optional

Spacing between child orders, as a number followed by a unit: ms, s, min (or m) or h. For example "500ms", "1s" or "1min".

start_time : str, optional

Wall-clock time to begin injection, "HH:MM" or "HH:MM:SS", e.g. "10:30:00".

There is no side: each scenario has its own direction — flash_crash, gradual_selloff and trending_down sell; buy_panic and trending_up buy. Pick the scenario for the direction.

Any other key is rejected with a 422 that names the allowed keys. These checks run whatever the scenario, including "normal".

Every key can be overridden for any non-normal scenario, and any you omit keep the defaults below. These mirror the engine's own scenario builders — get_scenario_defaults(scenario) reads them from the installed SDK, so prefer it over this table if the two ever disagree.

Execution algorithms

Test execution strategies by passing an exec_algos list to run(). Each config is a dict; type decides which of the remaining keys apply.

Algorithm config keys

type : {"twap", "vwap", "css"}

Algorithm to run. Required, and the only key common to all three.

order_size : int

Total size to execute, in lots — the unit the engine and the calibrated background agents both work in, not shares. Multiply by the instrument's lot_size from calibrated_data() to reason in shares: 50 lots of 700.HK (lot_size 100) is 5,000 shares. The sign sets direction unless side is given — positive is sell, negative is buy. Required for twap and vwap.

horizon : int

Execution window in seconds, e.g. 7200 for two hours. Required for twap and vwap.

orders : pandas.Series

Explicit schedule: sizes indexed by a full datetime index, date and time combined. Required for css, and unused by the other two. Orders falling outside HKEX continuous trading hours (09:30–12:00, 13:00–16:00) are silently dropped.

start_time : str, optional

When to begin, "HH:MM:SS". Defaults to market open.

frequency : int, default 1

Seconds between child orders.

side : {"buy", "sell"}, optional

Direction. Inferred when omitted — from the sign of order_size for twap/vwap, from the sign of the orders values for css.

random_offset : bool for twap/vwap, float (seconds) for css, optional

Jitter on order timing, and the one key whose type depends on type. For twap/vwap it is a flag that randomises each order within its frequency interval, default True. For css it is a window in seconds — each order is offset by a random amount up to that many seconds — default None, meaning disabled.

TWAP (Time-Weighted Average Price)

{"type": "twap", "order_size": …, "horizon": …} — a constant rate across the window. Every key it takes is in Algorithm config keys above, and run()'s second example shows one in place.

VWAP (Volume-Weighted Average Price)

{"type": "vwap", "order_size": …, "horizon": …} — identical configuration to TWAP, but the schedule follows the calibrated volume profile rather than the clock.

CSS (Custom Static Schedule)

{"type": "css", "orders": …} — you supply the schedule yourself as a pd.Series indexed by a full datetime, instead of a size and a horizon. The cookbook has a schedule builder and a recipe for comparing several schedules against one shared baseline.

Tracking a job

# setup: the most recent job of yours
job_id = client.simulation.get_jobs(limit=1)["jobs"][0]["job_id"]

status = client.simulation.get_job_status(job_id)

print(f"Total: {status['total_simulations']}")
print(f"Status: {status['status_summary']}")
print(f"Complete: {status['is_complete']}")

Total: 5
Status: {'complete': 3, 'running': 2, 'failed': 0}
Complete: False

from simudyne import PulseAPIError

# setup: the most recent job of yours
job_id = client.simulation.get_jobs(limit=1)["jobs"][0]["job_id"]

try:
    print(client.simulation.get_job_logs(job_id)[:2000])
except PulseAPIError as exc:
    print(f"no log for {job_id}: {exc}")

result = client.simulation.get_jobs()

print(f"You have {result['total']} jobs")

for job in result["jobs"]:
    print(f"Job {job['job_id']}")
    print(f"  Simulations: {len(job['sim_ids'])}")
    print(f"  Created: {job['created_at']}")

Retrieving results

# setup: any cached simulation
sim_id = client.simulation.list_cached()["simulations"][0]["example_sim_id"]

df = client.simulation.get_sim_data(sim_id)
print(df.shape)
print(df.head())

# setup: the most recent job of yours
job_id = client.simulation.get_jobs(limit=1)["jobs"][0]["job_id"]

results = client.simulation.get_job_results(job_id)

print(f"Completed: {results['completed']}/{results['total_simulations']}")

for sim in results["simulations"]:
    if sim["status"] in ("complete", "completed"):
        print(f"Sim {sim['sim_id']}")
        print(f"  Files: {sim['available_files']}")
        print(f"  Metrics: {sim['metrics']}")

Understanding simulation IDs

Each Monte Carlo run has a unique sim_id with the format:

{provider}:{exchange}:{symbol}:{cal_date}:{gen_method}:{cal_hash}:{time}:{sim_hash}:{scenario}_{hash}:{algo}:{run}

For example: omd:hkex_securities:9999.HK:2025-09-02:ABM_v1.37.0:d96cf520:0930-1600:c8961b94:flash_crash_6e6d5b3a:baseline:0000

The sim_id encodes all configuration parameters (including gen_method, the engine version that produced the run), making it deterministic and reproducible. The final :{run} field is the zero-padded Monte Carlo run index — take an example_sim_id and swap this last field to address each run (…:0000, …:0001, …). Don't hand-build sim_ids field-by-field; always start from an example_sim_idreturned by list_cached() or run().