diff --git a/docs/pom.xml b/docs/pom.xml index 627d128e4e9..55b6b4d2eae 100755 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -7,7 +7,7 @@ ai.timefold.solver timefold-solver-build-parent - 999-SNAPSHOT + 1.15.0 ../build/build-parent/pom.xml diff --git a/docs/src/modules/ROOT/nav.adoc b/docs/src/modules/ROOT/nav.adoc index f0fe53b6933..1820cf88b9f 100644 --- a/docs/src/modules/ROOT/nav.adoc +++ b/docs/src/modules/ROOT/nav.adoc @@ -1,10 +1,11 @@ -* xref:introduction/introduction.adoc[leveloffset=+1] -* Quickstart +* xref:introduction.adoc[leveloffset=+1] +* Getting Started ** xref:quickstart/overview.adoc[leveloffset=+1] ** xref:quickstart/hello-world/hello-world-quickstart.adoc[leveloffset=+1] ** xref:quickstart/quarkus/quarkus-quickstart.adoc[leveloffset=+1] ** xref:quickstart/spring-boot/spring-boot-quickstart.adoc[leveloffset=+1] ** xref:quickstart/quarkus-vehicle-routing/quarkus-vehicle-routing-quickstart.adoc[leveloffset=+1] +* xref:planning-ai-concepts.adoc[leveloffset=+1] * Using Timefold Solver ** xref:using-timefold-solver/overview.adoc[leveloffset=+1] ** xref:using-timefold-solver/configuration.adoc[leveloffset=+1] @@ -32,4 +33,5 @@ ** xref:upgrading-timefold-solver/overview.adoc[leveloffset=+1] ** xref:upgrading-timefold-solver/upgrade-to-latest-version.adoc[leveloffset=+1] ** xref:upgrading-timefold-solver/upgrade-from-optaplanner.adoc[leveloffset=+1] +** xref:upgrading-timefold-solver/backwards-compatibility.adoc[leveloffset=+1] * xref:enterprise-edition/enterprise-edition.adoc[leveloffset=+1] \ No newline at end of file diff --git a/docs/src/modules/ROOT/pages/.index.adoc b/docs/src/modules/ROOT/pages/.index.adoc index 6a070769288..db5da6299d5 100644 --- a/docs/src/modules/ROOT/pages/.index.adoc +++ b/docs/src/modules/ROOT/pages/.index.adoc @@ -18,13 +18,15 @@ ifndef::backend-pdf[] image::shared/timefold-logo.png[align="center"] endif::[] -include::introduction/introduction.adoc[leveloffset=+1] +include::introduction.adoc[leveloffset=+1] include::quickstart/.quickstart.adoc[leveloffset=+1] +include::planning-ai-concepts.adoc[leveloffset=+1] include::using-timefold-solver/.using-timefold-solver.adoc[leveloffset=+1] include::constraints-and-score/.constraints-and-score.adoc[leveloffset=+1] include::optimization-algorithms/.optimization-algorithms.adoc[leveloffset=+1] include::responding-to-change/responding-to-change.adoc[leveloffset=+1] include::integration/integration.adoc[leveloffset=+1] include::design-patterns/design-patterns.adoc[leveloffset=+1] +include::frequently-asked-questions.adoc[leveloffset=+1] include::upgrading-timefold-solver/.upgrading-timefold-solver.adoc[leveloffset=+1] include::enterprise-edition/enterprise-edition.adoc[leveloffset=+1] diff --git a/docs/src/modules/ROOT/pages/frequently-asked-questions.adoc b/docs/src/modules/ROOT/pages/frequently-asked-questions.adoc new file mode 100644 index 00000000000..1d3ebbab5b6 --- /dev/null +++ b/docs/src/modules/ROOT/pages/frequently-asked-questions.adoc @@ -0,0 +1,15 @@ += FAQ +:doctype: book +:icons: font + +== How is Timefold Solver Licensed? + +Timefold Solver Community Edition is _open source_ software, +released under http://www.apache.org/licenses/LICENSE-2.0.html[the Apache License 2.0]. +This license is very liberal and allows reuse for commercial purposes. +Read http://www.apache.org/foundation/licence-FAQ.html#WhatDoesItMEAN[the layman's explanation]. + +Timefold Solver Enterprise Edition is a commercial product +that offers xref:enterprise-edition/enterprise-edition.adoc#enterpriseEditionFeatures[additional features] +to scale out to very large datasets. +To find out more, see xref:enterprise-edition/enterprise-edition.adoc[Enterprise Edition section] of this documentation. \ No newline at end of file diff --git a/docs/src/modules/ROOT/pages/introduction.adoc b/docs/src/modules/ROOT/pages/introduction.adoc new file mode 100644 index 00000000000..09b5ad28097 --- /dev/null +++ b/docs/src/modules/ROOT/pages/introduction.adoc @@ -0,0 +1,30 @@ +[#introduction] +:page-aliases: ../index.adoc +:doctype: book +:sectnums: +:icons: font + +[#whatIsTimefold] += What is Timefold Solver? + +Every organization faces planning problems: providing products or services with a limited set of _constrained_ resources (employees, assets, time, and money). +Timefold Solver’s xref:planning-ai-concepts.adoc[PlanningAI] optimizes these problems to do more business with fewer resources using Constraint Satisfaction Programming. + +> Want to dive right into it? Follow our xref:quickstart/overview.adoc[Quickstart Example] to tackle your first planning problem in minutes. + +https://timefold.ai[Timefold Solver] is a lightweight, embeddable constraint satisfaction engine which optimizes planning problems. +Example usecases include: + +.Diagram showing a few use cases of Timefold Solver: vehicle routing, employee rostering, bin packing and equipment scheduling. +image::introduction/useCaseOverview.png[align="center"] + +Timefold Solver is 100% pure Java^TM^ and runs on Java {java-version} or higher. +It xref:integration/integration.adoc#integration[integrates very easily] with other Java^TM^, Python, and other technologies. +Timefold Solver works on any Java Virtual Machine and is compatible with the major JVM languages and all major platforms. +It also supports Kotlin and Python. + +:!sectnums: +== Next + +* Follow the xref:quickstart/overview.adoc[Quickstart Example] to tackle your first planning problem. +* Learn about some important concepts used in the realm of xref:planning-ai-concepts.adoc[PlanningAI]. diff --git a/docs/src/modules/ROOT/pages/introduction/introduction.adoc b/docs/src/modules/ROOT/pages/introduction/introduction.adoc deleted file mode 100644 index 6218b3efbb7..00000000000 --- a/docs/src/modules/ROOT/pages/introduction/introduction.adoc +++ /dev/null @@ -1,287 +0,0 @@ -[#introduction] -= Introduction -:page-aliases: ../index.adoc -:doctype: book -:sectnums: -:icons: font - -[#whatIsTimefold] -== What is Timefold Solver? - -Every organization faces planning problems: providing products or services with a limited set of _constrained_ resources (employees, assets, time and money). -Timefold Solver's <> optimizes these problems to do more business with less resources using _Constraint Satisfaction Programming_, which is part of the _<>_ discipline. - -https://timefold.ai[Timefold Solver] is a lightweight, embeddable constraint satisfaction engine which optimizes planning problems. -It solves use cases such as: - -* **Employee shift rostering**: timetabling nurses, repairmen, ... -* **Agenda scheduling**: scheduling meetings, appointments, maintenance jobs, advertisements, ... -* **Educational timetabling**: scheduling lessons, courses, exams, conference presentations, ... -* **Vehicle routing**: planning vehicle routes (trucks, trains, boats, airplanes, ...) for moving freight and/or passengers through multiple destinations using known mapping tools ... -* **Bin packing**: filling containers, trucks, ships, and storage warehouses with items, but also packing information across computer resources, as in cloud computing ... -* **Job shop scheduling**: planning car assembly lines, machine queue planning, workforce task planning, ... -* **Cutting stock**: minimizing waste while cutting paper, steel, carpet, ... -* **Sport scheduling**: planning games and training schedules for football leagues, baseball leagues, ... -* **Financial optimization**: investment portfolio optimization, risk spreading, ... - -image::introduction/useCaseOverview.png[align="center"] - -[#whatIsAPlanningProblem] -== Planning - -The need to create plans generally arises from a desire to achieve a *goal*: - -* Build a house. -* Correctly staff a hospital shift. -* Complete work at all customer locations. - -Achieving those goals involves organizing the available *resources*. -To correctly staff a hospital you need enough qualified personnel in a variety of fields and specializations to cover the opening hours of the hospital. - -Any plan to deploy resources, whether to staff a hospital shift or to assemble the building materials for a new house, is done under *constraints*. - -Constraints could be laws of the universe; people can't work two shifts in two separate locations at the same time, -and you can't mount a roof on a house that doesn't exist. -Constraints can also be relevant legislation; employees need a certain number of hours between shifts or are only allowed to work a maximum number of hours per week. -Employee preferences can also be considered constraints, such as, certain employees prefer to work specific shift patterns. - -[#feasiblePlans] -=== Feasible plans - -Any plan needs to consider all three elements, goals, resources, and constraints, in balance to be a feasible plan. -A plan that fails to account for all the elements of the problem is an infeasible plan. -For instance, if a hospital staff roster covers all shifts, but assigns employees back-to-back shifts with no breaks for sleep or life outside work, -it is not a valid plan. - -=== Planning problems are hard to solve - -Planning problems become harder to solve as the number of resources and constraints increase. -Creating an employee shift schedule for a small team of four employees is fairly straightforward. -However, if each employee performs a specific function within the business and those functions need to be performed in a specific order, -changes that affect one employee quickly cascade and affect everybody on the team. -If parts are delivered late and prevent one employee from completing their tasks, subsequent work will also be delayed. - -As more employees and different work specializations are added, things become much more complicated. - -For a trivial field service routing problem with 4 vehicles and 8 visits, the number of possibilities that a brute algorithm considers is 19,958,418. - -What would take a team of planners many hours to schedule can be automatically scheduled by Timefold Solver in a fraction of the time. - -[#operationsResearch] -==== Operations Research - -Operations Research (OR) is a field of research that is focused on finding optimal (or near optimal) solutions to problems with techniques that improve decision-making. - -Constraint satisfaction programming is part of Operations Research that aims to satisfy all the constraints of a problem. - -[#planningAI] -=== Planning AI - -Planning AI is a type of artificial intelligence designed specifically to handle complex planning and scheduling tasks, and to satisfy the constraints of planning problems. -Instead of just automating simple, repetitive tasks, it helps you make better decisions by sorting through countless possibilities to find the best solutions—saving you time, reducing costs, and improving efficiency. - -==== Why Planning AI is different -Traditional methods of planning often involve manually sifting through options or relying on basic tools that can’t keep up with the complexity of real-world problems. -Planning AI, on the other hand, uses advanced strategies to quickly focus on the most promising solutions, even when the situation is extremely complicated. -Planning AI also makes it possible to understand the final solution with a breakdown of which constraints have been violated and scores for individual constraints and an overall score. -This makes Planning AI incredibly valuable in industries where getting the right plan is crucial—whether that’s scheduling workers, routing deliveries, or managing resources in a factory. - -Planning AI is designed to be accessible, so you can start improving your planning process right away. - -[#aPlanningProblemHasConstraints] -=== Constraints - -Constraints can be considered hard, medium, or soft. - -Hard constraints represent rules and limitations of the real world that any planning solution has to respect. -For instance, there are only 24 hours in a day and people can only be in one place at a time. -Hard constraints also include rules that must be adhered to, for instance, employee contracts and the order in which dependent tasks are completed. - -Breaking hard constraints would result in infeasible plans. - -Medium constraints help manage plans when resources are limited, (for instance, when there aren't enough technicians to complete all the customer visits or there aren't enough employees to work all the available shifts). -Medium constraints incentivize Timefold Platform to assign as many entities (visits or shifts) as possible. - -Soft constraints help optimize plans based on the business goals, for instance, minimize travel time between customer visits or assign employees to their preferred shifts. - -To help determine the quality of the solution, plans are assigned a score with values for hard, medium, and soft constraints. - -`"0hard/-257medium/-6119520soft"` - -From this example score we can see zero hard constraints were broken, while both the medium and soft scores have negative values (the scores do not show how many constraints were broken, but values associated with those constraints). - -Because breaking hard constraints would result in an infeasible solution, -a solution that breaks zero hard constraints and has a soft constraint score of -1,000,000 is better -than a solution that breaks one hard constraint and has a soft constraint score of 0. - -The weight of constraints can be tweaked to adjust their impact on the solution. - -[#timefoldSolverStatus] -== Status of Timefold Solver - -Timefold Solver is 100% pure Java^TM^ and runs on Java {java-version} or higher. -It xref:integration/integration.adoc#integration[integrates very easily] with other Java^TM^, Python and other technologies. -Timefold Solver works on any Java Virtual Machine and is compatible with the major JVM languages and all major platforms. -It also supports Kotlin and Python. - -image::introduction/compatibility.png[align="center"] - -Timefold Solver is stable, reliable and scalable. -It has been heavily tested with unit, integration, and stress tests, and is used in production throughout the world. -One example handles over 50 000 variables with 5000 values each, multiple constraint types and billions of possible constraint matches. - -We offer two editions of Timefold Solver. - -[#communityEdition] -=== Timefold Solver Community Edition - -Timefold Solver Community Edition is _open source_ software, -released under http://www.apache.org/licenses/LICENSE-2.0.html[the Apache License 2.0]. -This license is very liberal and allows reuse for commercial purposes. -Read http://www.apache.org/foundation/licence-FAQ.html#WhatDoesItMEAN[the layman's explanation]. - -Timefold Solver Community Edition is available in <>. -It is and will always be free. -The overwhelming majority of solver features will always be available in the Community Edition. -Most users will be able to solve their planning problems with the Community Edition. - -[#enterpriseEdition] -=== Timefold Solver Enterprise Edition - -Timefold Solver Enterprise Edition is a commercial product -that offers xref:enterprise-edition/enterprise-edition.adoc#enterpriseEditionFeatures[additional features] -to scale out to very large datasets. -To find out more, see xref:enterprise-edition/enterprise-edition.adoc[Enterprise Edition section] of this documentation. - -[#backwardsCompatibility] -== Backwards compatibility - -Timefold Solver separates its API from its implementation: - -* **Public API**: All classes in the following package namespaces are 100% *backwards compatible* in future releases, -especially minor and hotfix releases: -** `ai.timefold.solver.core.api` -** `ai.timefold.solver.benchmark.api` -** `ai.timefold.solver.test.api` -** `ai.timefold.solver...api*` -* **Configuration**: The solver configuration is backwards compatible for all elements, -except for elements that require the use of non-public API classes. -The solver configuration is defined by the classes in the following package namespaces: -** `ai.timefold.solver.core.config` -** `ai.timefold.solver.benchmark.config` -* **Implementation classes**: All other classes are _not_ backwards compatible. -They will change in future major or minor releases, -but probably not in hotfix releases. - -Backwards incompatible changes will be clearly documented in xref:upgrading-timefold-solver/upgrade-to-latest-version.adoc#manualUpgrade[the upgrade recipe]. - - -[NOTE] -==== -This documentation covers some `impl` classes too. -Those documented `impl` classes are reliable and safe to use (unless explicitly marked as experimental in this documentation), -but we're just not entirely comfortable yet to write their signatures in stone. -==== - -[NOTE] -==== -The Python Solver is currently in beta and its API is subject to change. -==== - - -[#startUsingTimefoldSolver] -== Start using Timefold Solver - -[#useWithMavenGradleEtc] -=== Use Timefold Solver with Maven, Gradle or PyPI - -The Timefold Solver jars are available in https://central.sonatype.com/namespace/ai.timefold.solver[the central maven repository] and https://pypi.org/project/timefold[PyPI]. - -[tabs] -==== -Maven:: -+ --- -Add a dependency to `timefold-solver-core` in your `pom.xml`: - -[source,xml,options="nowrap"] ----- - - ai.timefold.solver - timefold-solver-core - ... - ----- - -Or better yet, import the `timefold-solver-bom` in `dependencyManagement` to avoid duplicating version numbers -when adding other timefold dependencies later on: - -[source,xml,options="nowrap"] ----- - - ... - - - - ai.timefold.solver - timefold-solver-bom - pom - ... - import - - - - - - ai.timefold.solver - timefold-solver-core - - - ai.timefold.solver - timefold-solver-jpa - - ... - - ----- --- - -Gradle:: -+ --- -Add a dependency to `timefold-solver-core` in your `build.gradle`: - -[source,groovy,options="nowrap"] ----- -dependencies { - implementation 'ai.timefold.solver:timefold-solver-core:...' -} ----- --- - -Pyproject.toml:: -+ --- -Add a dependency to `timefold` in your `pyproject.toml`: - -[source,toml,options="nowrap"] ----- -[project] -dependencies = [ - 'timefold == ...', - # ... -] ----- --- -==== - -See also how to xref:enterprise-edition/enterprise-edition.adoc#switchToEnterpriseEdition[switch To Enterprise Edition]. - -To find out how to get started with Timefold Solver, -see xref:quickstart/overview.adoc[Quickstarts]. - -[#useWithOtherBuildTools] - -=== Upgrade to the latest version - -See the dedicated section on xref:upgrading-timefold-solver/upgrade-to-latest-version.adoc[Upgrading Timefold Solver]. diff --git a/docs/src/modules/ROOT/pages/planning-ai-concepts.adoc b/docs/src/modules/ROOT/pages/planning-ai-concepts.adoc new file mode 100644 index 00000000000..dc8082fca45 --- /dev/null +++ b/docs/src/modules/ROOT/pages/planning-ai-concepts.adoc @@ -0,0 +1,93 @@ += PlanningAI Concepts +:doctype: book +:sectnums: +:icons: font + +== Planning + +The need to create plans generally arises from a desire to achieve a *goal*: + +* Build a house. +* Correctly staff a hospital shift. +* Complete work at all customer locations. + +Achieving those goals involves organizing the available *resources*. +To correctly staff a hospital you need enough qualified personnel in a variety of fields and specializations to cover the opening hours of the hospital. + +Any plan to deploy resources, whether to staff a hospital shift or to assemble the building materials for a new house, is done under *constraints*. + +Constraints could be laws of the universe; people can't work two shifts in two separate locations at the same time, +and you can't mount a roof on a house that doesn't exist. +Constraints can also be relevant legislation; employees need a certain number of hours between shifts or are only allowed to work a maximum number of hours per week. +Employee preferences can also be considered constraints, such as, certain employees prefer to work specific shift patterns. + +[#feasiblePlans] +=== Feasible plans + +Any plan needs to consider all three elements, goals, resources, and constraints, in balance to be a feasible plan. +A plan that fails to account for all the elements of the problem is an infeasible plan. +For instance, if a hospital staff roster covers all shifts, but assigns employees back-to-back shifts with no breaks for sleep or life outside work, +it is not a valid plan. + +== Planning problems are hard to solve + +Planning problems become harder to solve as the number of resources and constraints increase. +Creating an employee shift schedule for a small team of four employees is fairly straightforward. +However, if each employee performs a specific function within the business and those functions need to be performed in a specific order, +changes that affect one employee quickly cascade and affect everybody on the team. +If parts are delivered late and prevent one employee from completing their tasks, subsequent work will also be delayed. + +As more employees and different work specializations are added, things become much more complicated. + +For a trivial field service routing problem with 4 vehicles and 8 visits, the number of possibilities that a brute algorithm considers is 19,958,418. + +What would take a team of planners many hours to schedule can be automatically scheduled by Timefold Solver in a fraction of the time. + +[#operationsResearch] +== Operations Research + +Operations Research (OR) is a field of research that is focused on finding optimal (or near optimal) solutions to problems with techniques that improve decision-making. + +Constraint satisfaction programming is part of Operations Research that aims to satisfy all the constraints of a problem. + +[#planningAI] +== Planning AI + +Planning AI is a type of artificial intelligence designed specifically to handle complex planning and scheduling tasks, and to satisfy the constraints of planning problems. +Instead of just automating simple, repetitive tasks, it helps you make better decisions by sorting through countless possibilities to find the best solutions—saving you time, reducing costs, and improving efficiency. + +=== Why Planning AI is different +Traditional methods of planning often involve manually sifting through options or relying on basic tools that can’t keep up with the complexity of real-world problems. +Planning AI, on the other hand, uses advanced strategies to quickly focus on the most promising solutions, even when the situation is extremely complicated. +Planning AI also makes it possible to understand the final solution with a breakdown of which constraints have been violated and scores for individual constraints and an overall score. +This makes Planning AI incredibly valuable in industries where getting the right plan is crucial—whether that’s scheduling workers, routing deliveries, or managing resources in a factory. + +Planning AI is designed to be accessible, so you can start improving your planning process right away. + +[#aPlanningProblemHasConstraints] +== Constraints + +Constraints can be considered hard, medium, or soft. + +Hard constraints represent rules and limitations of the real world that any planning solution has to respect. +For instance, there are only 24 hours in a day and people can only be in one place at a time. +Hard constraints also include rules that must be adhered to, for instance, employee contracts and the order in which dependent tasks are completed. + +Breaking hard constraints would result in infeasible plans. + +Medium constraints help manage plans when resources are limited, (for instance, when there aren't enough technicians to complete all the customer visits or there aren't enough employees to work all the available shifts). +Medium constraints incentivize Timefold Platform to assign as many entities (visits or shifts) as possible. + +Soft constraints help optimize plans based on the business goals, for instance, minimize travel time between customer visits or assign employees to their preferred shifts. + +To help determine the quality of the solution, plans are assigned a score with values for hard, medium, and soft constraints. + +`"0hard/-257medium/-6119520soft"` + +From this example score we can see zero hard constraints were broken, while both the medium and soft scores have negative values (the scores do not show how many constraints were broken, but values associated with those constraints). + +Because breaking hard constraints would result in an infeasible solution, +a solution that breaks zero hard constraints and has a soft constraint score of -1,000,000 is better +than a solution that breaks one hard constraint and has a soft constraint score of 0. + +The weight of constraints can be tweaked to adjust their impact on the solution. diff --git a/docs/src/modules/ROOT/pages/upgrading-timefold-solver/.upgrading-timefold-solver.adoc b/docs/src/modules/ROOT/pages/upgrading-timefold-solver/.upgrading-timefold-solver.adoc index dad8b884110..4b43c75694b 100644 --- a/docs/src/modules/ROOT/pages/upgrading-timefold-solver/.upgrading-timefold-solver.adoc +++ b/docs/src/modules/ROOT/pages/upgrading-timefold-solver/.upgrading-timefold-solver.adoc @@ -6,4 +6,5 @@ include::overview.adoc[leveloffset=+1] include::upgrade-to-latest-version.adoc[leveloffset=+1] -include::upgrade-from-optaplanner.adoc[leveloffset=+1] \ No newline at end of file +include::upgrade-from-optaplanner.adoc[leveloffset=+1] +include::backwards-compatibility.adoc[leveloffset=+1] \ No newline at end of file diff --git a/docs/src/modules/ROOT/pages/upgrading-timefold-solver/backwards-compatibility.adoc b/docs/src/modules/ROOT/pages/upgrading-timefold-solver/backwards-compatibility.adoc new file mode 100644 index 00000000000..c1bd737a964 --- /dev/null +++ b/docs/src/modules/ROOT/pages/upgrading-timefold-solver/backwards-compatibility.adoc @@ -0,0 +1,36 @@ +[#backwardsCompatibility] += Backwards compatibility +:doctype: book +:icons: font + +Timefold Solver separates its API from its implementation: + +* **Public API**: All classes in the following package namespaces are 100% *backwards compatible* in future releases, +especially minor and hotfix releases: +** `ai.timefold.solver.core.api` +** `ai.timefold.solver.benchmark.api` +** `ai.timefold.solver.test.api` +** `ai.timefold.solver...api*` +* **Configuration**: The solver configuration is backwards compatible for all elements, +except for elements that require the use of non-public API classes. +The solver configuration is defined by the classes in the following package namespaces: +** `ai.timefold.solver.core.config` +** `ai.timefold.solver.benchmark.config` +* **Implementation classes**: All other classes are _not_ backwards compatible. +They will change in future major or minor releases, +but probably not in hotfix releases. + +Backwards incompatible changes will be clearly documented in xref:upgrading-timefold-solver/upgrade-to-latest-version.adoc#manualUpgrade[the upgrade recipe]. + + +[NOTE] +==== +This documentation covers some `impl` classes too. +Those documented `impl` classes are reliable and safe to use (unless explicitly marked as experimental in this documentation), +but we're just not entirely comfortable yet to write their signatures in stone. +==== + +[NOTE] +==== +The Python Solver is currently in beta and its API is subject to change. +==== \ No newline at end of file