The Basic Annotations In OptaPlanner

In this blog post, we shall talk about some basic annotations in OptaPlanner including @PlanningVariable, @PlanningEntity, and @PlanningSolution.

@PlanningVariable :
A planning variable is a property of JavaBean.
This type of variable is annotated with @PlanningVariable annotation and it needs a non-empty valueRangeProviderRefs property.A planning variable needs to be a member of a class that is annotated by @PlanningEntity annotation.These variables are ignored if the parent or child class is not annotated by @PlanningEntity annotation.Simply we can say, a planning variable is a variable that we want to assign to any planning entity class.

Example :

@PlanningVariable(valueRangeProviderRefs = "teacherRange", nullable = true)
private OptaTeacher teacher;

@PlanningEntity :
A planning entity is a JavaBean in which changes occur during solving. We can identify a class as a planning entity class if it is annotated by @PlanningEntity annotation. A planning entity class has one or more genuine or shadows type planning variables. Simply we can say, a planning entity is an entity to which we want to assign one or more planning variables.

Example :

@PlanningEntity
public class OptaModule {
@PlanningVariable(valueRangeProviderRefs = "teacherRange", nullable = true)
private OptaTeacher teacher;
}

@PlanningSolution :
Any class which is annotated by @PlanningSolution annotation is referred to by the planning solution. These types of classes contain planning entities, problem facts, and a score variable.

Example :

@PlanningSolution
public class OptaSolution {

@PlanningEntityCollectionProperty
private List<Vehicle> vehicles;

@ProblemFactCollectionProperty
@ValueRangeProvider(id = "driver")
private List<Driver> drivers;

@PlanningScore
private HardMediumSoftLongScore score = null;
}

@PlanningScore :
Any field in the @PlanningSolution class that is annotated by the @PlanningScore annotation is referred to by the planning score. Before calculating the score, the score field is set to null. The score value depends on the planning solution result.

@PlanningPin :
Any boolean field in the @PlanningEntity class that is annotated by the @PlanningPin annotation is referred to by the planning pin. If the value of this variable is set to true then during planning the pinned planning entity is not changed. For example, if you want to assign a shift to any specific employee then you must set the PlanningPin field to true. So, during planning solver does not change the employee for this shift.

Chained Planning Variable :
These types of variables are used to implement the Chained by Time pattern. It allows the planning entities to form a chain by pointing to each other. By adopting the problem as a set of chains heavily reduced the search space.

This type of planning variable either:

- Directly points to a planning entity or a problem fact, known as an anchor.

- Targeting any other planning entity with the similar type of planning variable, which recursively points to an anchor.

Shadow variable :
These are also planning variables whose correct value can be decided from the state of the genuine planning variables. If a class contains any shadow variable then this class is known as a planning entity class even if it does not contain any genuine planning variable. For a genuine planning entity, class is mandatory to contain a minimum of one genuine planning variable. For a shadow planning entity class is not mandatory to contain any genuine planning variable but it's mandatory to contain a minimum of one shadow planning variable.

Build-In Shadow Variables
1). @InverseRelationShadowVariable: These types of variables are also known as Bi-directional variables. If two variables are targeted at each other then these variables are called Bi-directional variables.

Example :

@PlanningEntity
public class CloudComputer {

@InverseRelationShadowVariable(sourceVariableName = "computer")
public List<CloudProcess> getProcessList() {
return processList;
}
}

2). @AnchorShadowVariable : It is the anchor of a chained variable.

Example :

@PlanningEntity
public class Customer {

@AnchorShadowVariable(sourceVariableName = "previousStandstill")
public Vehicle getVehicle() {...}
public void setVehicle(Vehicle vehicle) {...}

}

We, at Oodles, provide 360-degree OptaPlanner development and implementation services to help enterprises efficiently plan and execute routine operational tasks. Contact us at [email protected] to learn more about our OptaPlanner development services.