Package ai.timefold.solver.core.preview.api.move.builtin

Class Moves

java.lang.Object
ai.timefold.solver.core.preview.api.move.builtin.Moves
@NullMarked public final class Moves extends Object
Factory class for creating built-in Move instances that mutate planning variables.

This class provides static methods to create the standard moves used in optimization:

This package and all of its contents are part of the Neighborhoods API, which is under development and is only offered as a preview feature. There are no guarantees for backward compatibility; any class, method, or field may change or be removed without prior notice, although we will strive to avoid this as much as possible.

We encourage you to try the API and give us feedback on your experience with it, before we finalize the API. Please direct your feedback to Timefold Solver GitHub or to Timefold Discord.

See Also:

  • Method Details

    • compose

      public static <Solution_> Move<Solution_> compose(List<Move<Solution_>> moves)
      Creates a composite move from a list of moves.

      When executed, the composite move executes all its child moves in order. If the list contains only one move, that move is returned directly without wrapping.

      Type Parameters:
      Solution_ - the solution type
      Parameters:
      moves - the list of moves to combine; must not be empty
      Returns:
      a single move that executes all the given moves, or the single move if the list contains only one
      Throws:
      UnsupportedOperationException - if the list is empty

    • compose

      @SafeVarargs public static <Solution_> Move<Solution_> compose(Move<Solution_>... moves)
      Creates a composite move from an array of moves.

      When executed, the composite move executes all its child moves in order. If the array contains only one move, that move is returned directly without wrapping.

      Type Parameters:
      Solution_ - the solution type
      Parameters:
      moves - the array of moves to combine; must not be empty
      Returns:
      a single move that executes all the given moves, or the single move if the array contains only one
      Throws:
      UnsupportedOperationException - if the array is empty

    • change

      public static <Solution_, Entity_, Value_> Move<Solution_> change(PlanningVariableMetaModel<Solution_,Entity_,Value_> variableMetaModel, Entity_ entity, @Nullable Value_ value)
      Creates a move that changes a basic planning variable's value on a given entity.

      This move is the fundamental building block for optimizing basic planning variables. It sets the variable on the entity to a new value.

      Type Parameters:
      Solution_ - the solution type
      Entity_ - the entity type
      Value_ - the variable value type
      Parameters:
      variableMetaModel - describes the planning variable to be changed
      entity - the entity whose variable value is to be changed
      value - the new value to assign; may be null if the variable supports unassigned values
      Returns:
      a move that, when executed, changes the entity's variable to the given value

    • swap

      public static <Solution_, Entity_, Value_> Move<Solution_> swap(PlanningVariableMetaModel<Solution_,Entity_,Value_> variableMetaModel, Entity_ leftEntity, Entity_ rightEntity)
      Creates a move that swaps the value of a single planning variable between two entities.

      Both entities must be different instances. After execution, the left entity will have the value that the right entity had, and vice versa.

      Only provide entities whose values can be swapped; for example, if one of the values is not in the value range of the other entity's variable, then swapping would lead to an invalid solution.

      Type Parameters:
      Solution_ - the solution type
      Entity_ - the entity type
      Value_ - the variable value type
      Parameters:
      variableMetaModel - describes the planning variable to swap
      leftEntity - the first entity participating in the swap
      rightEntity - the second entity participating in the swap
      Returns:
      a move that, when executed, swaps the variable values between the two entities
      Throws:
      IllegalArgumentException - if leftEntity == rightEntity

    • swap

      public static <Solution_, Entity_> Move<Solution_> swap(List<PlanningVariableMetaModel<Solution_,Entity_,Object>> variableMetaModelList, Entity_ leftEntity, Entity_ rightEntity)
      Creates a move that swaps the values of multiple planning variables between two entities.

      Both entities must be different instances. For each variable in the list, after execution, the left entity will have the value that the right entity had, and vice versa.

      Only provide entities whose values can be swapped; for example, if one of the values is not in the value range of the other entity's variable, then swapping would lead to an invalid solution.

      Type Parameters:
      Solution_ - the solution type
      Entity_ - the entity type
      Parameters:
      variableMetaModelList - the list of planning variables to swap; must not be empty
      leftEntity - the first entity participating in the swap
      rightEntity - the second entity participating in the swap
      Returns:
      a move that, when executed, swaps all variable values between the two entities
      Throws:
      IllegalArgumentException - if the list is empty or if leftEntity == rightEntity

    • assign

      public static <Solution_, Entity_, Value_> Move<Solution_> assign(PlanningListVariableMetaModel<Solution_,Entity_,Value_> variableMetaModel, Value_ value, PositionInList targetPosition)
      Creates a move that assigns a value to a list variable at a specified position.

      The value must not already be assigned to any list variable. This move inserts the value at the given position, shifting all existing values at or after that position to the right.

      Type Parameters:
      Solution_ - the solution type
      Entity_ - the entity type
      Value_ - the variable value type
      Parameters:
      variableMetaModel - describes the list variable to be changed
      value - the value to be assigned; must not already be assigned to a list variable
      targetPosition - specifies the entity and index where the value should be inserted
      Returns:
      a move that, when executed, assigns the value to the list variable at the specified position

    • assign

      public static <Solution_, Entity_, Value_> Move<Solution_> assign(PlanningListVariableMetaModel<Solution_,Entity_,Value_> variableMetaModel, Value_ value, Entity_ entity, int index)
      As defined by assign(PlanningListVariableMetaModel, Object, PositionInList), but with explicit entity and index parameters.

    • unassign

      public static <Solution_, Entity_, Value_> Move<Solution_> unassign(PlanningListVariableMetaModel<Solution_,Entity_,Value_> variableMetaModel, PositionInList targetPosition)
      Creates a move that unassigns a value from a list variable at a specified position.

      This move removes the value at the given position, shifting all subsequent values to the left. After execution, the removed value will be unassigned.

      Type Parameters:
      Solution_ - the solution type
      Entity_ - the entity type
      Value_ - the variable value type
      Parameters:
      variableMetaModel - describes the list variable to be changed
      targetPosition - specifies the entity and index from which the value should be removed
      Returns:
      a move that, when executed, removes the value from the list variable

    • unassign

      public static <Solution_, Entity_, Value_> Move<Solution_> unassign(PlanningListVariableMetaModel<Solution_,Entity_,Value_> variableMetaModel, Entity_ entity, int index)
      As defined by unassign(PlanningListVariableMetaModel, PositionInList), but with explicit entity and index parameters.

    • change

      public static <Solution_, Entity_, Value_> Move<Solution_> change(PlanningListVariableMetaModel<Solution_,Entity_,Value_> variableMetaModel, PositionInList source, PositionInList destination)
      Creates a move that moves an element from one position in a list variable to another position.

      The element at the source position is removed and inserted at the destination position. Both positions may be in the same entity or in different entities.

      If the source and destination are within the same entity, the element is first removed from the source position (shifting later elements left), then inserted at the destination position.

      Type Parameters:
      Solution_ - the solution type
      Entity_ - the entity type
      Value_ - the variable value type
      Parameters:
      variableMetaModel - describes the list variable to be changed
      source - the source position from which to move the element
      destination - the destination position to which to move the element
      Returns:
      a move that, when executed, relocates the element from the source position to the destination position

    • change

      public static <Solution_, Entity_, Value_> Move<Solution_> change(PlanningListVariableMetaModel<Solution_,Entity_,Value_> variableMetaModel, Entity_ sourceEntity, int sourceIndex, Entity_ destinationEntity, int destinationIndex)
      As defined by change(PlanningListVariableMetaModel, PositionInList, PositionInList), but with explicit entity and index parameters.

    • swap

      public static <Solution_, Entity_, Value_> Move<Solution_> swap(PlanningListVariableMetaModel<Solution_,Entity_,Value_> variableMetaModel, PositionInList left, PositionInList right)
      Creates a move that swaps two elements between positions in list variables.

      The element at the left position is swapped with the element at the right position. The left and right positions may be in the same or different entities.

      Type Parameters:
      Solution_ - the solution type
      Entity_ - the entity type
      Value_ - the variable value type
      Parameters:
      variableMetaModel - describes the list variable to be changed
      left - the first position for the swap
      right - the second position for the swap
      Returns:
      a move that, when executed, swaps the elements at the two positions

    • swap

      public static <Solution_, Entity_, Value_> Move<Solution_> swap(PlanningListVariableMetaModel<Solution_,Entity_,Value_> variableMetaModel, Entity_ leftEntity, int leftIndex, Entity_ rightEntity, int rightIndex)
      As defined by swap(PlanningListVariableMetaModel, PositionInList, PositionInList), but with explicit entity and index parameters.