////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////

[[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

|xref:use-cases-and-examples/nqueens/nqueens.adoc#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

|xref:use-cases-and-examples/cloud-balancing/cloud-balancing.adoc#cloudBalancing[Cloud balancing]
|* 1 entity class
** 1 variable
|* Entity <= `2400`
* Value <= `800`
* Search space <= `10^6967`
|* No
* Defined by us
|* xref:repeated-planning/repeated-planning.adoc#realTimePlanning[Real-time planning]

|xref:use-cases-and-examples/travelling-salesman/travelling-salesman.adoc#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]
|* xref:repeated-planning/repeated-planning.adoc#realTimePlanning[Real-time planning]

|xref:use-cases-and-examples/tennis-scheduling/tennis-scheduling.adoc#tennis[Tennis club scheduling]
|* 1 entity class
** 1 variable
|* Entity <= `72`
* Value <= `7`
* Search space <= `10^60`
|* No
* Defined by us
|* xref:score-calculation/score-calculation.adoc#fairnessScoreConstraints[Fairness score constraints]
* xref:repeated-planning/repeated-planning.adoc#pinnedPlanningEntities[Pinned entities]

|xref:use-cases-and-examples/meeting-scheduling/meeting-scheduling.adoc#meetingScheduling[Meeting scheduling]
|* 1 entity class
** 2 variables
|* Entity <= `10`
* Value <= `320` and <= `5`
* Search space <= `10^320`
|* No
* Defined by us
|* xref:design-patterns/design-patterns.adoc#timeGrainPattern[TimeGrain pattern]

|xref:use-cases-and-examples/course-timetabling/course-timetabling.adoc#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]
|* xref:repeated-planning/repeated-planning.adoc#pinnedPlanningEntities[Pinned entities]

|xref:use-cases-and-examples/machine-reassignment/machine-reassignment.adoc#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]
|* xref:repeated-planning/repeated-planning.adoc#realTimePlanning[Real-time planning]

|xref:use-cases-and-examples/vehicle-routing/vehicle-routing.adoc#vehicleRouting[Vehicle routing]
|* 1 entity class
** 1 list variable
* 1 shadow entity class
** 3 automatic shadow variable
|* Entity <= `55`
* Value <= `2750`
* Search space <= `10^8380`
|* Unrealistic
* https://neo.lcc.uma.es/vrp/[VRP web]
|* xref:shadow-variable/shadow-variable.adoc#shadowVariable[Shadow variable]
* xref:repeated-planning/repeated-planning.adoc#realTimePlanning[Real-time planning]
* xref:move-and-neighborhood-selection/move-and-neighborhood-selection.adoc#nearbySelection[Nearby selection]
* Real road distances

|xref:use-cases-and-examples/vehicle-routing/vehicle-routing.adoc#vehicleRouting[Vehicle routing] with time windows
|* All of Vehicle routing
* 1 shadow variable
|* Entity <= `55`
* Value <= `2750`
* Search space <= `10^8380`
|* Unrealistic
* https://neo.lcc.uma.es/vrp/[VRP web]
|* All of Vehicle routing
* Custom xref:shadow-variable/shadow-variable.adoc#customVariableListener[VariableListener]

|xref:use-cases-and-examples/project-job-scheduling/project-job-scheduling.adoc#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]
|* xref:score-calculation/score-calculation.adoc#bendableScore[Bendable score]
* Custom xref:shadow-variable/shadow-variable.adoc#customVariableListener[VariableListener]
* xref:planner-configuration/planner-configuration.adoc#valueRangeFactory[ValueRangeFactory]

|xref:use-cases-and-examples/bed-allocation/bed-allocation.adoc#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]
|* xref:repeated-planning/repeated-planning.adoc#overconstrainedPlanning[Overconstrained planning]

|xref:use-cases-and-examples/task-assigning/task-assigning.adoc#taskAssigning[Task assigning]
|* 1 entity class
** 1 list variable
* 1 shadow entity class
** 1 automatic shadow variable
** 1 shadow variable
|* Entity <= `20`
* Value <= `500`
* Search space <= `10^1168`
|* No
* Defined by us
|* xref:score-calculation/score-calculation.adoc#bendableScore[Bendable score]
* xref:design-patterns/design-patterns.adoc#chainedThroughTimePattern[Chained through time pattern]
* Custom xref:shadow-variable/shadow-variable.adoc#customVariableListener[VariableListener]
* xref:repeated-planning/repeated-planning.adoc#continuousPlanning[Continuous planning]
* xref:repeated-planning/repeated-planning.adoc#realTimePlanning[Real-time planning]

|xref:use-cases-and-examples/exam-timetabling/exam-timetabling.adoc#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 xref:shadow-variable/shadow-variable.adoc#customVariableListener[VariableListener]

|xref:use-cases-and-examples/nurse-rostering/nurse-rostering.adoc#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]
|* xref:repeated-planning/repeated-planning.adoc#continuousPlanning[Continuous planning]
* xref:repeated-planning/repeated-planning.adoc#realTimePlanning[Real-time planning]

|xref:use-cases-and-examples/travelling-tournament/travelling-tournament.adoc#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 xref:move-and-neighborhood-selection/move-and-neighborhood-selection.adoc#moveListFactory[MoveListFactory]

|xref:use-cases-and-examples/conference-scheduling/conference-scheduling.adoc#conferenceScheduling[Conference scheduling]
|* 1 entity class
** 2 variables
|* Entity <= `216`
* Value <= `18` and <= `20`
* Search space <= `10^552`
|* No
* Defined by us
|

|xref:use-cases-and-examples/flight-crew-scheduling/flight-crew-scheduling.adoc#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
|

|===
