Configuration parameters and profiles

Introduction

When solving planning problems with the Timefold Platform, various configuration parameters influence the behavior and outcome. Managing these parameters effectively is crucial for both correct and fast results, as well as aligning optimization goals to ensure high-quality solutions.

To streamline this process, the Timefold Platform supports configuration profiles, which allow you to predefine and manage different sets of configuration parameters. Configuration profiles help to easily experiment with different settings, optimize trade-offs between competing objectives, and benchmark performance across different configurations.

This document explains which configuration options are available, how to use configuration profiles, and how they help with goal alignment and benchmarking.

Run configuration options

Each planning run is influenced by several configuration parameters, which we categorize into three main types:

Run settings

These settings define which hardware is used to solve the planning problem and when the solving process terminates. For example, you can specify the number of threads used for computation.

Model configuration

These settings control how the optimization model itself operates. Each model defines its own set of parameters, which can influence how data is processed. For example, the Field Service Routing model includes a parameter that affects how travel times are computed.

Constraint weights

A model can expose constraint weights as optional parameters. Constraint weights determine the relative importance of the different constraints the model implements:

  • By default, constraint weights are set to 1, but they can be adjusted to any positive number.

  • Increasing a constraint weight prioritizes that constraint more in the optimization process.

  • Setting a constraint weight to zero effectively disables that constraint, meaning it won’t impact the solver’s decision-making.

Since constraint weights directly shape the optimization goal, configuring them strategically is key to achieving the best possible solutions.

The run configuration is shared across all models. Below is an example of a run configuration.

"config": {
  "run": {
    "name": "run name",
    "termination": {
      "spentLimit": "PT5M",
      "unimprovedSpentLimit": "PT10S"
    },
    "maxThreadCount": 1,
    "tags": []
  },
  "model": {
    "overrides": {
      <model-specific configurations>
    }
  }
}

A run configuration has two fields: the run and the model.

The run has four fields:

  • name - The run name (if empty, it will be generated).

  • termination - The termination properties containing:

    • spentLimit - The maximum duration to keep the solver running (ISO 8601 Duration). If omitted, no maximum duration will be set (platform limits will apply).

    • unimprovedSpentLimit - The maximum unimproved score duration, i.e. if the score has not improved during this period, the solver will terminate (ISO 8601 Duration). If omitted, the diminished returns termination will be used.

      The diminished returns termination is the recommended default setting. This termination is desirable since it terminates based on the relative rate of improvement, and behaves similarly on different hardware and different problem instances. unimprovedSpentLimit should be set only when necessary.

  • maxThreadCount - The maximum thread count, which indicates the maximum number of threads to be used for solving. If not provided, 1 will be used.

  • tags - The tags, which are a set of optional tags to be assigned to the job.

The model is a model-specific field, that contains additional global model configuration attributes.

Viewing configuration options

When you view the details of a single run in the Timefold Platform UI, you’ll see a list of the exact configuration options used for that run. This list combines default values with user-specified settings. You can also access this information programmatically via the /config API endpoint of a run.

Configuration values for a run are determined by (in order of importance):

  • The settings that are submitted as part of the planning problem.

  • Settings from the configuration profile (if a configuration profile is specified).

  • Default values specified by the model.

Additionally, maximum values may be enforced by the model or the tenant plan, such as limits on the number of threads or allocated memory.

Configuration profiles

The Timefold Platform allows users to define up to 50 configuration profiles per model. Each configuration profile represents a unique combination of:

  • Constraint weights.

  • Model configuration parameters.

  • Run settings.

Go to one of your installed models, click “Configuration profiles” in the sidebar, and then add a new one, or duplicate an existing one.

Once configuration profiles are created, they can be applied easily to a new run by selecting them in the Timefold Platform UI or passing the configurationId parameter in the API request.

Goal alignment with configuration profiles

One of the key benefits of configuration profiles is that they help users define and refine their optimization goals. Real-world planning problems involve multiple competing objectives—such as minimizing costs while ensuring fairness, or maximizing the number of optional visits/shifts while still honouring employee preferences. Configuration profiles allow you to explore these trade-offs systematically.

Read more on Balancing different optimization goals.

Benchmarking with configuration profiles

Configuration profiles also support benchmarking, enabling you to evaluate the performance impact of different run settings. For example: To measure the effect of multi-threaded solving, create one configuration profile with 1 thread and another with 2 threads, then compare the solving times and solution quality.

By systematically comparing different configurations, you can fine-tune settings for optimal performance.