Skip to main content

Simulated Runs

A simulated run executes selection and volume optimization on a warehouse partition and calls no OEM OMS. A run on a past partition whose outcome is already known catches regressions from selection and volume-optimization changes. Daily simulated runs also estimate what the rest of a dealer's cluster would order, which ADR-012 uses to reduce order-sequencing bias.

Isolation​

Simulated runs execute SimulatedOrderingRunWorkflow on the ordering-simulated task queue. The worker registers no activity on that queue that can reach a private API. A run on that queue therefore cannot place an order, whatever its input. The queue selects the implementation, and no runtime flag can override it. Instead of submitting a selection, the workflow records it as a SIMULATED attempt.

A simulated run sends no Slack notification. SimulatedOrderingRunWorkflow calls no notification activity, and the worker registers none on the ordering-simulated queue.

Two further guards keep a simulated run from emailing a dealer:

  • run_summary.send_email: false in the run's config turns off the email step. The run still renders and archives the report PDF; it skips only the email.
  • resolve_recipients returns no dealer address for a run that placed no order. A dealer contact therefore receives no email even if the email step runs.

How the DAG starts a run​

TemporalWorkflowComponent (ai_dagster.components.TemporalWorkflowComponent) defines a partitioned job and a sensor. The sensor checks the last recent_partitions daily partitions (3 by default) and requests the latest one that every asset in monitored_assets has materialized, so a run never starts before its inputs are fresh. The partition key is the run key, so the sensor requests each partition once. A partition whose inputs are not all materialized before it leaves that window is never requested. On a branch deployment the sensor is stopped by default, because a branch deployment starts its workflows in the production Temporal namespace.

For that partition, the job's op takes the dealers from private_inventory_asset, the table of the OEM's private inventory source. In that table, each row's dealer_code is the code of the dealer whose inventory collection included the vehicle. The column that last_collected_column names contains the date of that collection. A partition of the table includes a dealer when the dealer's latest collection is within snapshot_lookback_days days before the partition date. The snapshot_lookback_days field of the table's raw component sets that number, 30 by default.

The op starts one SimulatedOrderingRunWorkflow for the partition. Its dealer_ids holds each dealer whose latest collection is at most max_collection_age_days days before the partition date. The op leaves the other dealers out of dealer_ids. It writes each of those dealers' latest collection date to its stale_dealers output metadata. The simulated run report lists those dealers as skipped.

When dealer_sample_size is set, dealer_ids holds only a random sample of that many of the dealers whose collection is recent enough. The op ranks each dealer by a hash of the partition key and the dealer code, and samples the lowest-ranked dealers. Running the same partition again therefore picks the same dealers. A dealer that enters or leaves the partition's dealers before a rerun changes the sample by at most that one dealer. The op records no metadata for the dealers it leaves out, and the simulated run report does not list them.

When a dealer's run starts, it reads that dealer's most recent collection session. A dealer's run whose session is older than the OEM's simulated_max_staleness ends SKIPPED with the exit reason SNAPSHOT_TOO_STALE.

The workflow id is {oem}-{market}-{name}-{partition}-{dagster_run}, where {dagster_run} is the id of the Dagster run. Each Dagster run of the job therefore starts its own workflow with every dealer it selects. Each workflow has its own run_id, so the ordering_runs sensor registers a partition of {oem}_{market}_ordering_runs for each. A workflow started with several dealers starts one child workflow per dealer, as A simulated run with several dealers describes.

An automatic run retry uses the id of the run it retries as {dagster_run}. Dagster's run retry daemon sets the tag dagster/auto_retry_run_id on the run it retries to the id of the retry, and the op follows that tag. No re-execution that a person starts is named there, so such a re-execution starts a new workflow, even when it copies the dagster/retry_number tag of a retry.

Temporal rejects a start whose workflow id it already holds, whether that workflow is running or closed. When the start fails, the op asks Temporal for the dealer_ids of the workflow with that id. Temporal holds that workflow when the retried run had already started it, or when the start failed after Temporal stored it. The op then records the dealers that the workflow was started with, starts no second workflow, and records each other selected dealer as not started. When Temporal holds no such workflow, the op records the start error for every dealer.

Each OEM configures the component in its own defs.yaml:

  • private_inventory_asset, last_collected_column, max_collection_age_days and dealer_sample_size, which choose the dealers;
  • monitored_assets;
  • the run's extras.

Each OEM's Simulated Ordering Run page describes its configuration. See the pages for Stellantis and Mercedes.

The as-of date​

The op passes the partition key as the run's as_of_date. The run reads its data as of that one date. The date sets:

  • the warehouse partition of every frame;
  • the reference time of the arrival simulation and the supply snapshot;
  • each target's production date;
  • the restriction month.

No step of the run reads the wall clock to choose data.

The warehouse probe can resolve an earlier date within partition_lookback_days when the requested date's data is not complete. Data flow describes the probe.

Running a past partition​

To run an earlier date, backfill that partition of the job from the Dagster UI or the dg CLI (see the dagster-cli skill). The op takes the dealers in that partition of private_inventory_asset, samples them when dealer_sample_size is set, and starts one run with every selected dealer. The run resolves its read date within the lookback window.

Rerunning a partition​

To run a partition's dealers again, launch the job's partition again from the Dagster UI in one of these ways:

  • re-execute an earlier run of the partition;
  • launch the partition from the Launchpad;
  • backfill the partition.

The new Dagster run starts a new workflow with every dealer it selects. The rerun does not delete the earlier workflows' ordering_runs documents. When a run of the job fails before it starts its workflow, launch the partition again the same way.

When the partition already has a simulated run report, launch the report job's partition again once the rerun's workflows have ended.