Skip to main content

Simulation templates

Simulation

represents a complete set of objects, configurations and processing pipelines for a route optimization session. It also stores the optimization results (assignments between vehicles and nodes).

The SWAT API supports templating simulation objects, which simplifies creating, maintaining, and updating configurations and predefined routes without having to build a simulation from scratch each time. The ability to save predefined routes and routing profiles enables support for situations where routes are preplanned (like milk runs or static routes). Templates repesent an instance of the simulation object that can be quickly copied over (cloned) into a another simulation, for example, for a new day of operations.

Each project can have multiple simulation templates, each with time-based rules that determine which simulation should be selected to copy over for a specific date and/or time. This is controlled by the recurrence field of the simulation object, which is used to choose a simulation template for the selected date. If multiple simulation templates are available for the same selected time, recurrence_priority is used to select one.

SWAT APIs also offer a streamlined process for uploading bookings with automatic creation of a simulation based on a template. The same rules apply to order upload.

A set of business rules is invoked to ensure that time windows for objects (for example, open times for nodes, vehicle operating hours, and processing pipeline time windows) are adjusted appropriately during this process.

To create a simulation from a template two options are available:

Creating simulation templates programmatically​

The main endpoint to create an instance of a template is /api/v2/microservices/simulation_template. However, by design, this endpoint executes idempotently—it will only return the first available template matching the request and prevents the creation of multiple templates sequentially.

To programmatically create multiple simulation templates (for instance, to seed an environment or automate template generation), you should bypass the microservice endpoint and issue a POST directly to the /api/v2/simulation/ endpoint.

When invoking POST /api/v2/simulation/, please note the following constraints:

  1. Required Configuration Fields: You must explicitly provide all configuration values usually defaulted by the backend to satisfy database NOT NULL constraints. This includes fields like conversion_rate, vehicle_capacity, and acceptable_waiting_time.
  2. Sequential Priority Control: When the system creates a simulation from templates, it uses the recurrence_priority field to decide which template to select when rule intervals overlap (choosing the one with the highest descending priority). If you create templates sequentially in bulk, you should dynamically assign a high priority (such as mapping recurrence_priority to the current Unix timestamp) so the newly created templates are correctly evaluated by the cloning logic.

Time window adjustment rules​

  1. Sets simulation.start_time to the desired value.
  2. Calculates simulation.end_time as the sum of start_time and the duration of the source simulation, unless end_time is explicitly specified.

Subsequently, the following fields are adjusted relative to the new simulation.start_time:

  • simulation.booking_start_time
  • simulation.booking_end_time
  • vehicle.start_time
  • vehicle.end_time
  • simulation_processor.start_time
  • simulation_processor.end_time
  • simulation_processor.vehicle_filter_expression (recursively adjusts common time fields like start_time, end_time)
  • simulation_processor.bookings_filter_expression (recursively adjusts fields like min_pickup_time, max_pickup_time, min_dropoff_time, max_dropoff_time)
  • simulation_processor.calculation_parameters_regenerator (recursively adjusts time fields)
Processor Settings Behavior

When cloning from a template, On-Demand Processor Settings (calculation_parameters_ondemand) are copied as-is and are NOT time-adjusted. This is because these settings typically contain boolean flags or static configuration rather than absolute timestamps. However, filter expressions and regenerator settings are recursively scanned and adjusted to match the new simulation's time window.

warning

There is always a chance that the timings of newly created objects may appear beyond the simulation timings due to incorrect or intentional setup of templates. For instance, time bounds are explicitly verified for vehicles, and their IDs are reported in the response. However, cloning a simulation with invalid vehicles is still permitted.