What is the meaning of 'Pinned' when I use the PlanningListVariable?

[kentbill]

I know that in a pattern that does not use PlanningListVariable (using PlanningVariable), using a field with @PlanningPin annotation can pin the planning variables of a planning entity. However, after using the PlanningListVariable pattern(such as the food packing case in quickstarts), the genuine planning variable no longer exists in the planning entity. So what does the @PlanningPin annotation play? Which field does it pinned for a planning entity?

Many thanks

[triceo]

Planning list variables don't support pinning yet. The behavior is undefined.

[kentbill]

Got it, Thank you Lukáš
Does that say, in scenarios where PlanningListVariable is used, the planning variable can't be locked? Even if use the filtered selection？

[triceo]

At the moment, we don't even have a good definition of what it would mean to "lock" a planning list variable. Does it mean the entire list cannot be changed at all? Does it mean any particular sublist is locked? If we lock a particular entry in the list, does it mean everything before is locked? Or everything after?

These are tough questions which we haven't yet thought through, which is why pinning on planning list variable is not supported.

[greyhairredbear]

My 2 cents regarding our use case at Cargonexx:

We are solving a variant of the VRP with pickups, returns and time windows. In a previous version implemented with OR tools, we allowed users to "lock" tours, which means they shouldn't be modified by planning anymore.

We made the switch to Optaplanner in July and have opted for modelling the problem with PlanningListVariables. Now, we obviously face the challenge of to implementing this by hand. Four our use case, I think the desired behavior of pinning a @PlanningEntity which is contained in an @PlanningListVariable would be that only the single entry is locked, nothing before and nothing after. If required, we could still also lock preceeding/following items manually.

EDIT: Seems like I missed something - I suppose our use case would rather require locking a sublist of a PlanningListVariable, while still being able to change elements before and after that. Might be tricky, since the first and last elements would have to be treated differently w.r.t. PreviousElementShadowVariable and NextElementShadowVariable. Still happy to provide more details if you're interested.

Having support for pinning in Timefold would provide a great benefit (and incentive to switch to Timefold ;) ) for us, although I totally understand that it's hard to come up with a good general solution.

[kentbill]

Yes, this is a quite tricky problem. In my scenarios, the most common case is to lock the space and time of a job - Use the particular equipment and start a job at a particular time. This problem is difficult to solve perfectly even using the Chained through time pattern.
In my project, I achieve this "locking" through another method:

1. Preset the "locked" jobs, which means equipment and start time for these "locked" jobs are known.
2. A job is a planning entity, but the "locked" job does not participate in the planning, that is, these planning entities which need to be "locked" will not be added to the list fields annotated by @PlanningEntityCollection.
3. For some equipment (the anchor in the Chained Through Time pattern), the periods used by the "locked" jobs are defined as break time, they are outside the working calendar, which means the equipment do not work during these periods, so the planning entities what in the planning can't be scheduled in these periods - keep these periods empty.
4. In the planning result, assign the "locked" job's equipment and start time with presetting.

[triceo]

It's looking increasingly likely that pinning on list variables will be delivered in the near future.
The semantics we are going for is:

• If a planning list variable value is pinned, it means that it and every value before it in the same list variable cannot be removed from the list, and their position in the list can not change. Essentially it is a way of saying "these items have already happened, you can not change the past".
• To do that, the entity with the list will receive a new optional annotated field (working name: @PlanningPinIndex, likely to change) that will determine the first un-pinned value in the list. (Defaults to zero, nothing pinned.)
• Any requirement other than the above will have to be implemented through constraints. We specifically discussed the idea of "fixed appointments" (values with pre-defined place in time and space that must be guaranteed), and this is a typical example of something that is best handled with a constraint.

[greyhairredbear]

Out of curiosity: What would be the closest description for "in the near future"? Weeks, months, quarters, years? (I'd also understand if the answer is "can't say" ;) )

[triceo]

The PR is already available. ;-)
I'm hoping for 1.6.0 later this week, but 1.7.0 next month is still possible.

[greyhairredbear]

Nice, sounds great! 👏

[triceo]

Timefold Solver 1.6.0 was just released, incl. support for list variable pinning.
Thank you for your feedback, and keep it coming! ;-)

[kentbill]

Great! Thank you for your efforts! I will try to use it in my project.