Global options

Global options set general Calendar Planning parameters that apply to all locations and all employees. Note that parameters for a specific location or specific employee usually have a higher priority.

When planning with Excel, global parameters are set on the options sheet. When planning via the API, global parameters are set in the options object.

Planning period

The planning period start date is specified in the date parameter in YYYY-MM-DD format. The planning period duration is specified in the planning_days parameter in days.

Relative time windows are calculated in the time zone that is set with the options.time_zone parameter. The time_zone field is mandatory.

When planning via the API, there are two ways to specify the time zone:

• As a number between -12 and 14 that determines the offset relative to UTC in hours. For example, 1 corresponds to GMT+1 (London).

• As a string. For example, Europe/London.

When planning with Excel, the time zone is set only as a number.

Use a list of time zones to specify the time zone.

Working and non-working days

The number of working days per week is specified in the working_days_in_week parameter (no more than 7). Working days always start on Monday and are distributed continuously throughout the week. The remaining days are considered non-working days.

By default, working_days_in_week = 5, which corresponds to a normal 5-day working week.

Other sample values:

• working_days_in_week = 7: All days are working days. Also set the parameter to 7 when Saturday is a non-working day and Sunday is a working day.
• working_days_in_week = 6: Corresponds to a 6-day working week, where Saturday is a working day.
• working_days_in_week = 2: Only Monday and Tuesday are working days.

Working and non-working days that are the same for all employees are specified in the working_days and non_working_days parameter. If the non_working_days parameter is specified, those days are subtracted from working days.

You can also set individual work schedules. For more information, see Employee's working and non-working days.

Employees who visit a location

By default, one location must be visited by the same employee. If this condition isn't important for planning, set allow_multiple_visitors to true to allow different employees to visit the same location on different days.

Addresses with multiple locations

Multiple locations can be at the same address (for example, there's a shopping center with multiple stores). To handle such locations within a single visit, you can set penalties on the options sheet in the Excel file:

• penalty.multiorders.per_extra_point: Penalty for each address employees visit more than once.
• penalty.multiorders.per_extra_employee: Penalty for each extra employee who visits an address with multiple locations (if visits are planned for multiple employees).
• penalty.multiorders.per_extra_visit: Penalty for each extra visit to an address with multiple locations.

Default penalty values are 0.

Locations are merged only if other restrictions aren't violated, for example, the locations' tag compatibility.

Moving between start and end route points on neighboring days

When planning, it may turn out that an employee handles locations that are far away from each other on different days. At the start of each day, an employee may need to travel hundreds of kilometers from their starting position on the previous day. To avoid such situations, you can take the distance or duration of transit between the starting route points on neighboring days and add it to the route cost.

The duration_between_days_starts_factor and distance_between_days_starts_factor parameters set the factors by which the cost of travels to the starting point of the day's route is multiplied. The default values are 0. If the values are 1, the travels are considered a part of the route (with the same cost per hour and km).

The duration_between_days_ends_factor and distance_between_days_ends_factor parameters impose similar restrictions for travels between end points of routes on neighboring days.

Visits on the earliest days

The late_days_cost_increment parameter allows planning visits to selected locations on earlier days. It can be used independently or together with location priorities.

When using late_days_cost_increment, the parameter value multiplied by the day number starting from 0 is added to each day's cost. Thus, nothing is added to the first day, late_days_cost_increment is added to the second day, 2 * late_days_cost_increment is added to the third day, and so forth. The impact of this parameter gradually decreases due to an internal factor that goes down from 1 to 0 during optimization. As a result, the solution's final cost doesn't change.

For an example of using this parameter, see Visits on the earliest days.

Post-optimization

With post_optimization set to true, the optimization runs 90% of the time, and the remaining 10% are taken up by re-running the algorithm where post-optimization is performed.

Post-optimization can improve the solution if the task uses the daily_proximity_factor or global_proximity_factor density parameters. In this case, the route is rebuilt and grouped around its last location prior to post-optimization.

Maximum time to solve the planning task

During planning, the algorithm seeks to distribute locations among employees in the best possible way and select optimal routes to visit them. Searching for the best routes may increase the time to solve the planning task. To limit this time, specify the solver_time_limit_s parameter, which sets the maximum time to solve a planning task. The algorithm generates the optimal routes that it managed to plan in the allotted time.

We recommend first running the task for a small planning period to make sure that the parameters set for locations and employees are correct and to find the optimal penalty values and other restrictions. Once you've selected the parameters, you can run the task for the entire required planning period.

Below are recommendations for limiting the maximum time to solve the planning task, where column Normal corresponds to the values of the solver_time_limit_s parameter for an appropriate quality solution and column High, for a high-quality solution.

Total number of visits	Total number of locations	Number of visits per location	Courier transportation method	Normal, sec	High, sec
501	496	1	driving	100	1000
860	308	2.8	driving	500	15,000
1100	900	1.2	driving	200	5000
2500	1600	1.56	walking	3600	15,000
2500	1600	1.56	driving	3600	15,000
2700	671	4	driving + walking	3600	15,000
11,000	2200	5	walking	5000	15,000

Contact support