Configuration parameters and profiles
Introduction
Configuration parameters give you greater control over how Timefold Platform treats your datasets. 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, Timefold Platform supports configuration profiles, which allow you to predefine and manage different sets of configuration parameters. Using configuration profiles makes it easier to 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 create and use configuration profiles, and how they help with goal alignment and benchmarking.
Configuration profiles are per model.
To access configuration profiles, log into Timefold Platform, select the model, then click Configuration profiles.
Configuration profiles
Timefold Platform allows users to define up to 50 configuration profiles per model.
Every new tenant has a Standard profile which is used as the default configuration profile unless a different profile is configured as the default profile.
The Standard profile is read only.
Create a new profile
To create a new configuration profile, do either of the following from the configuration profiles screen:
-
Click Add profile.
-
Select an existing profile and click Duplicate profile.
Next, give the new profile a name and description, then click Add or Duplicate.
Enter the configuration parameters you want to use and click Save profile.
Change the default profile
To change the default configuration profile, select the profile you want to use as the default and click Set as Default and confirm your decision. The default profile can be identified by the default badge in the list of configuration profiles.
Specify which configuration profile to use
Unless otherwise specified, the default configuration profile will be used for all datasets.
You can specify which configuration profile to use with a dataset in 2 ways.
Query parameter
The configuration profile can be specified when you submit a new dataset by appending a query parameter with the configuration profile ID (or the profile name) to the POST URL.
For instance, if the configuration profile is called test, the query parameter would be: ?configurationId=test
Configuration options
Each configuration profile represents a unique combination of:
When you view the details of a single dataset in the Timefold Platform UI, you’ll see a list of the exact configuration
options used for that dataset. This list combines default values with user-specified settings. You can also access
this information programmatically via the /config API endpoint of a dataset.
Configuration values for a datasets are determined by (in order of importance):
-
The settings that are submitted as part of the planning problem.
-
Settings from the configuration profile.
-
Settings inherited from the parent dataset (if using the
{id}/from-patchor{id}/from-inputendpoints on the parent dataset). -
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.
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.
Model configuration
These settings control how the optimization model itself operates. Each model can define its own set of parameters, which influence how data is processed. For example, the Field Service Routing model includes a parameter that affects how travel times are computed.
Not all models include model configuration.
Dataset 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.
Termination settings
The following settings determine the duration of a solve operation:
-
Max solve duration: After this configured amount of time the solve operation will always stop. (If no full solution was found, the dataset will be in status "Solving Incomplete", otherwise it’ll be "Solving Complete". More details about statuses.)
-
Smart termination:
-
Default: Choosing this option will terminate the solving when no significant further improvements are expected. (Under the hood it uses the Diminished Returns termination of the Timefold Solver with default configuration values.)
-
Unimproved time limit: Choosing this option will terminate the solving when the score hasn’t improved for a given amount of time.
-
After initial solution: This option stops a run immediately after the construction heuristic produces the first solution. This option is useful when you want a quick look at the initial plan before further optimization.
-
Step Count Termination: Choosing this option will terminate the solving after the specified number of steps.
-
| Step Count Termination and After initial solution are useful for testing and benchmarking configurations and datasets, however, these options should not be used in production. |
Thread count
The default number of threads that is used for solving is 1. This can be changed up to a maximum that is determined by the model and by the tenant plan.
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 dataset 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.