Configuration and optimization goals

Introduction

When solving planning problems with the Timefold Platform, various configuration parameters influence the behavior and outcome. Managing these parameters effectively is crucial for aligning optimization goals and ensuring 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.

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.

Understanding Optimization Trade-Offs

Optimization is not a zero-sum game, where improving one objective must always come at the expense of another. Instead, different objectives can be balanced through careful tuning of constraint weights. In employee shift scheduling, for example, increasing the weight of work-hour fairness might slightly reduce operational efficiency, but the right balance can yield a solution that improves employee satisfaction without significantly increasing costs.

By setting up different configuration profiles with varying constraint weights, you can:

  • Compare how different priorities impact the final solution.

  • Identify solutions that balance objectives effectively.

  • Adjust trade-offs dynamically based on evolving business needs.

We recommend creating multiple configuration profiles that prioritize different objectives or disable certain constraints entirely to explore their impact. Running the same dataset with different configuration profiles allows you to visualize the effect of constraint weight changes on key performance metrics.

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.