[[examplesOverview]]
= Examples overview

OptaPlanner has several examples.
In this manual we explain mainly using the _n_ queens example and cloud balancing example.
So it is advisable to read at least those sections.

Some of the examples solve problems that are presented in academic contests.
The `Contest` column in the following table lists the contests.
It also identifies an example as being either _realistic_ or _unrealistic_ for the purpose of a contest.
A _realistic contest_ is _an official, independent contest_:

* that clearly defines a real-world use case.
* with real-world constraints.
* with multiple, real-world datasets.
* that expects reproducible results within a specific time limit on specific hardware.
* that has had serious participation from the academic and/or enterprise Operations Research community.

Realistic contests provide an objective comparison of OptaPlanner with competitive software and academic research.

The source code of all these examples is available in the distribution zip under [path]_examples/sources_
and also in git under [path]_optaplanner/optaplanner-examples_.

.Examples overview
[cols="1,1a,1a,1a,1a",options="header"]
|===
|Example |Domain |Size |Contest |Special features used

|<<nQueens,N queens>>
|* 1 entity class
** 1 variable
|* Entity <= `256`
* Value <= `256`
* Search space <= `10^616`
|* Pointless (https://en.wikipedia.org/wiki/Eight_queens_puzzle#Explicit_solutions[cheatable])
|None

|<<cloudBalancing,Cloud balancing>>
|* 1 entity class
** 1 variable
|* Entity <= `2400`
* Value <= `800`
* Search space <= `10^6967`
|* No
* Defined by us
|* <<realTimePlanning,Real-time planning>>

|<<tsp,Traveling salesman>>
|* 1 entity class
** 1 chained variable
|* Entity <= `980`
* Value <= `980`
* Search space <= `10^2504`
|* Unrealistic
* http://www.math.uwaterloo.ca/tsp/[TSP web]
|* <<realTimePlanning,Real-time planning>>

|<<tennis,Tennis club scheduling>>
|* 1 entity class
** 1 variable
|* Entity <= `72`
* Value <= `7`
* Search space <= `10^60`
|* No
* Defined by us
|* <<fairnessScoreConstraints,Fairness score constraints>>
* <<pinnedPlanningEntities,Pinned entities>>

|<<meetingScheduling,Meeting scheduling>>
|* 1 entity class
** 2 variables
|* Entity <= `10`
* Value <= `320` and <= `5`
* Search space <= `10^320`
|* No
* Defined by us
|* <<timeGrainPattern,TimeGrain pattern>>

|<<curriculumCourse,Course timetabling>>
|* 1 entity class
** 2 variables
|* Entity <= `434`
* Value <= `25` and <= `20`
* Search space <= `10^1171`
|* Realistic
* http://www.cs.qub.ac.uk/itc2007/curriculmcourse/course_curriculm_index.htm[ITC 2007 track 3]
|* <<pinnedPlanningEntities,Pinned entities>>

|<<machineReassignment,Machine reassignment>>
|* 1 entity class
** 1 variable
|* Entity <= `50000`
* Value <= `5000`
* Search space <= `10^184948`
|* Nearly realistic
* http://challenge.roadef.org/2012/en/[ROADEF 2012]
|* <<realTimePlanning,Real-time planning>>

|<<vehicleRouting,Vehicle routing>>
|* 1 entity class
** 1 chained variable
* 1 shadow entity class
** 1 automatic shadow variable
|* Entity <= `2740`
* Value <= `2795`
* Search space <= `10^8380`
|* Unrealistic
* http://neo.lcc.uma.es/vrp/[VRP web]
|* <<shadowVariable,Shadow variable>>
* <<realTimePlanning,Real-time planning>>
* <<nearbySelection,Nearby selection>>
* Real road distances

|<<vehicleRouting,Vehicle routing>> with time windows
|* All of Vehicle routing
* 1 shadow variable
|* Entity <= `2740`
* Value <= `2795`
* Search space <= `10^8380`
|* Unrealistic
* http://neo.lcc.uma.es/vrp/[VRP web]
|* All of Vehicle routing
* Custom <<customVariableListener,VariableListener>>

|<<projectJobScheduling,Project job scheduling>>
|* 1 entity class
** 2 variables
** 1 shadow variable
|* Entity <= `640`
* Value <= `?` and <= `?`
* Search space <= `?`
|* Nearly realistic
* http://gent.cs.kuleuven.be/mista2013challenge/[MISTA 2013]
|* <<bendableScore,Bendable score>>
* Custom <<customVariableListener,VariableListener>>
* <<valueRangeFactory,ValueRangeFactory>>

|<<bedAllocation,Hospital bed planning>>
|* 1 entity class
** 1 nullable variable
|* Entity <= `2750`
* Value <= `471`
* Search space <= `10^6851`
|* Unrealistic
* https://people.cs.kuleuven.be/~wim.vancroonenburg/pas/[Kaho PAS]
|* <<overconstrainedPlanning,Overconstrained planning>>

|<<taskAssigning,Task assigning>>
|* 1 entity class
** 1 chained variable
** 1 shadow variable
* 1 shadow entity class
** 1 automatic shadow variable
|* Entity <= `500`
* Value <= `520`
* Search space <= `10^1168`
|* No
* Defined by us
|* <<bendableScore,Bendable score>>
* <<chainedThroughTimePattern,Chained through time pattern>>
* Custom <<customVariableListener,VariableListener>>
* <<continuousPlanning,Continuous planning>>
* <<realTimePlanning,Real-time planning>>

|<<examination,Exam timetabling>>
|* 2 entity classes (same hierarchy)
** 2 variables
|* Entity <= `1096`
* Value <= `80` and <= `49`
* Search space <= `10^3374`
|* Realistic
* http://www.cs.qub.ac.uk/itc2007/examtrack/exam_track_index.htm[ITC 2007 track 1]
|* Custom <<customVariableListener,VariableListener>>

|<<nurseRostering,Nurse rostering>>
|* 1 entity class
** 1 variable
|* Entity <= `752`
* Value <= `50`
* Search space <= `10^1277`
|* Realistic
* https://www.kuleuven-kulak.be/~u0041139/nrpcompetition/nrpcompetition_description.pdf[INRC 2010]
|* <<continuousPlanning,Continuous planning>>
* <<realTimePlanning,Real-time planning>>

|<<travelingTournament,Traveling tournament>>
|* 1 entity class
** 1 variable
|* Entity <= `1560`
* Value <= `78`
* Search space <= `10^2301`
|* Unrealistic
* http://mat.tepper.cmu.edu/TOURN/[TTP]
|* Custom <<moveListFactory,MoveListFactory>>

|<<cheapTimeScheduling,Cheap time scheduling>>
|* 1 entity class
** 2 variables
|* Entity <= `500`
* Value <= `100` and <= `288`
* Search space <= `10^20078`
|* Nearly realistic
* ICON challenge 2014
|* <<annotationAlternatives,Field annotations>>
* <<valueRangeFactory,ValueRangeFactory>>

|<<investment,Investment>>
|* 1 entity class
* 1 variable
|* Entity <= `11`
* Value = `1000`
* Search space <= `10^4`
|* No
* Defined by us
|* <<valueRangeFactory,ValueRangeFactory>>

|<<conferenceScheduling,Conference scheduling>>
|* 1 entity class
** 2 variables
|* Entity <= `216`
* Value <= `18` and <= `20`
* Search space <= `10^552`
|* No
* Defined by us
|

|<<rockTour,Rock tour>>
|* 1 entity class
** 1 chained variable
** 4 shadow variables
* 1 shadow entity class
** 1 automatic shadow variable
|* Entity <= `47`
* Value <= `48`
* Search space <= `10^59`
|* No
* Defined by us
|

|<<flightCrewScheduling,Flight crew scheduling>>
|* 1 entity class
** 1 variable
* 1 shadow entity class
** 1 automatic shadow variable
|* Entity <= `4375`
* Value <= `750`
* Search space <= `10^12578`
|* No
* Defined by us
|

|<<coachShuttleGathering,Coach shuttle gathering>>
|* 2 entity class (BusStop, Shuttle)
** 1 variable each (previousBusOrStop for BusStop, destination for Shuttle)
* 1 shadow entity class (Coach)
** 2 automatic shadow variable (next bus stop and
passenger quantity total) (also on Shuttle)
|* Entity <=  `6` shuttles and
              `12` bus stops
* Value <= `3` coaches, `6` shuttles and `12` bus stops
* Search space <= `10^23`
|* No
* Defined by us
|* Custom <<customVariableListener,VariableListener>>
* <<shadowVariable,Shadow variable>>
|

|===
