improved documentation

README.md

@@ -11,6 +11,8 @@
 - [Applications](#3-applications)
   - [Two-Dimensional Bin Packing Problem](#31-two-dimensional-bin-packing-problem)
   - [Traveling Salesperson Problem (TSP)](#32-the-traveling-salesperson-problem-tsp)
+  - [Dynamic Controller Synthesis](#33-dynamic-controller-synthesis)
+  - [Traveling Tournament Problem (TTP)](#34-the-traveling-tournament-problem-tsp)
 - [Unit Tests and Static Analysis](#4-unit-tests-and-static-analysis)
 - [License](#5-license)
 - [Contact](#6-contact)
@@ -59,6 +61,8 @@ The additional dependencies for a [full `make` build](https://thomasweise.github
 ## 3. Applications
 
 Here we list the applications of [`moptipy`](https://thomasweise.github.io/moptipy).
+Step by step, we will add more and more interesting optimization problems.
+For each problem, we provide means to load the problem instances and a basic infrastructure to construct optimization algorithms for solving them.
 
 
 ### 3.1. Two-Dimensional Bin Packing Problem
@@ -117,6 +121,8 @@ We use the TSP instances from [TSPLib](http://comopt.ifi.uni-heidelberg.de/softw
 
 Important work on this code has been contributed by Mr. Tianyu LIANG (梁天宇), <[email protected]> a Master's student at the Institute of Applied Optimization (应用优化研究所, http://iao.hfuu.edu.cn) of the School of Artificial Intelligence and Big Data (人工智能与大数据学院) at Hefei  University (合肥学院) in Hefei, Anhui, China (中国安徽省合肥市) under the supervision of Prof. Dr. Thomas Weise (汤卫思教授).
 
+The Traveling Tournament Problem ([TTP](#34-the-traveling-tournament-problem-tsp)) is related to the TTP.
+
 
 ### 3.3. Dynamic Controller Synthesis
 
@@ -145,6 +151,24 @@ dy/dt = sigma * y + x + c
 What we try to find is the controller which can bring move object to the origin `(0, 0)` as quickly as possible while expending the least amount of force, i.e., having the smallest aggregated `c` values over time.
 
 
+### 3.4. The Traveling Tournament Problem (TSP)
+
+In the package [`moptipyapps.ttp`](https://thomasweise.github.io/moptipyapps/moptipyapps.ttp.html#module-moptipyapps.ttp), we provide a set of classes and tools to explore the *Traveling Tournament Problem (TTP)*.
+In a TTP, we have an even number of `n` teams.
+Each team plays a tournament against every other team.
+If the tournament is a single round-robin tournament, each team plays exactly once against every other team.
+In the more common double round-robin tournament, each team plays twice against every other team &mdash; once at home and once at the place of the other team.
+A tournament takes `(n - 1) * rounds` days in total, where `rounds = 2` for double round-robin.
+Now additionally to the basic constraints dictated by logic (if team `A` plays at home against team `B` on day `d`, then team `B` has an "away" game against team `A` on that day `d` and so on), there are also additional constraints.
+For instance, no team should play a continuous streak of home (or away) games longer than `m` days, where `m` usually is `m = 3`.
+Also, if teams `A` and `B` play against each other, then there must be at least `p` games in between before they play each other again, usually with `p = 1`.
+
+Now the first hurdle is to find a game plan that has `n / 2` games on each day (since there are `n` teams and each plays against one other team) that satisfies the above constraints.
+The second problem is that this is not all:
+For each TTP, a distance matrix is defined, very much like for the [TSP](#32-the-traveling-salesperson-problem-tsp).
+The goal is to find a feasible game schedule where the overall travel distances are minimal.
+
+
 ## 4. Unit Tests and Static Analysis
 
 When developing and applying randomized algorithms, proper testing and checking of the source code is of utmost importance.

moptipyapps/ttp/__init__.py

@@ -21,11 +21,22 @@
 1. David Van Bulck. Minimum Travel Objective Repository. *RobinX: An
    XML-driven Classification for Round-Robin Sports Timetabling.* Faculty of
    Economics and Business Administration at Ghent University, Belgium.
-   https://robinxval.ugent.be/
+   https://robinxval.ugent.be/. In this repository, you can also find the
+   original instance data, useful descriptions, and many links to related
+   works.
 2. Kelly Easton, George L. Nemhauser, and Michael K. Trick. The Traveling
    Tournament Problem Description and Benchmarks. In *Principles and Practice
    of Constraint Programming (CP'01),*  November 26 - December 1, 2001, Paphos,
    Cyprus, pages 580-584, Berlin/Heidelberg, Germany: Springer.
-   ISBN: 978-3-540-42863-3. https://doi.org/10.1007/3-540-45578-7_43
-   https://www.researchgate.net/publication/220270875
+   ISBN: 978-3-540-42863-3. https://doi.org/10.1007/3-540-45578-7_43.
+   https://www.researchgate.net/publication/220270875.
+3. Celso C. Ribeiro and Sebastián Urrutia. Heuristics for the Mirrored
+   Traveling Tournament Problem. *European Journal of Operational Research*
+   (EJOR) 179(3):775-787, June 16, 2007.
+   https://doi.org/10.1016/j.ejor.2005.03.061.
+   https://optimization-online.org/wp-content/uploads/2004/04/851.pdf.
+4. Sebastián Urrutia and Celso C. Ribeiro. Maximizing Breaks and Bounding
+   Solutions to the Mirrored Traveling Tournament Problem.
+   *Discrete Applied Mathematics* 154(13):1932-1938, August 15, 2006.
+   https://doi.org/10.1016/j.dam.2006.03.030.
 """

moptipyapps/ttp/errors.py

@@ -1,4 +1,12 @@
-"""An objective that counts constraint violations."""
+"""
+An objective that counts constraint violations.
+
+The idea is that we will probably not be able to always produce game plans
+that adhere to all the constraints imposed by a TTP
+:mod:`~moptipyapps.ttp.instance`, so we will instead generate game plans
+that may contain errors. Then we apply this objective function here to get rid
+of them.
+"""
 
 
 from typing import Final
@@ -73,11 +81,13 @@ def count_errors(y: np.ndarray, home_streak_min: int,
     9.  If team `A` plays team `B` at home `a` times, then team `B` must play
         team `A` at home at least `a-1` and at most `a+1` times.
         In total, we have `D*n` games. There cannot be more than `(D*n) - 1`
-        such errors.
+        such errors. Notice that this kind of error can never occur if we use
+        our :mod:`~moptipyapps.ttp.game_encoding` as representation.
     10. Each pairing of teams occurs as same as often, namely `rounds` times,
         with `rounds = 2` for double-round robin.
         In total, we have `D*n` games. There cannot be more than `D*n` such
-        errors.
+        errors. Notice that this kind of error can never occur if we use
+        our :mod:`~moptipyapps.ttp.game_encoding` as representation.
 
     The violations are counted on a per-day basis. For example, if
     `home_streak_max` is `3` and a team has a home streak of length `5`, then
@@ -271,7 +281,13 @@ def count_errors(y: np.ndarray, home_streak_min: int,
 
 
 class Errors(Objective):
-    """Compute the errors in a game plan."""
+    """
+    Compute the errors in a game plan.
+
+    This objective function encompasses all the constraints imposed on
+    standard TTP instances in one summarizing number. See the documentation
+    of :func:`count_errors` for more information.
+    """
 
     def __init__(self, instance: Instance) -> None:
         """
@@ -296,7 +312,7 @@ def __init__(self, instance: Instance) -> None:
 
     def evaluate(self, x: GamePlan) -> int:
         """
-        Evaluate a game plan.
+        Count the errors in a game plan as objective value.
 
         :param x: the game plan
         :return: the number of errors in the plan
@@ -309,7 +325,7 @@ def evaluate(self, x: GamePlan) -> int:
 
     def lower_bound(self) -> int:
         """
-        Obtain the lower bound for errors: `0`.
+        Obtain the lower bound for errors: `0`, which means error-free.
 
         :return: `0`
         """

moptipyapps/version.py

@@ -1,4 +1,4 @@
 """An internal file with the version of the `moptipyapps` package."""
 from typing import Final
 
-__version__: Final[str] = "0.8.24"
+__version__: Final[str] = "0.8.25"