Merge pull request #41 from N-Wouda/adaptive-weighting-schemes

Features
--------

- Weight schemes, which control how `alns.ALNS` selects operators. Two schemes commonly used in the literature (convex updating and segmented weights) have been implemented, as `alns.weight_schemes.SimpleWeights` and `alns.weight_schemes.SegmentedWeights`, respectively (issue #29).
- An `autofit()` function for `alns.criteria.SimulatedAnnealing` (issue #35).
- The `alns` package is considerably better typed now, and passes `mypy` static analysis.

API changes
-----------

The following list details all breaking API changes. The example notebooks have been updated to the new behaviour, and can be used as a reference for how to adapt your own algorithm.

- `alns.ALNS.iterate()` now takes a `weight_scheme` argument, rather than various weight-related parameters it previously accepted.
- `alns.ALNS.iterate()` no longer provides the option not to collect statistics. Statistics are now always collected.
- Any criterion implementing `alns.criteria.AcceptanceCriterion` should now implement `__call__`, not `accept()`. The function signature is unchanged.
- `alns.Result.plot_operator_counts()` now takes a `fig` argument, rather than `figure`.
- Removed `alns.tools.exceptions.NotCollectedError`, since statistics are now always collected.
- Removed `alns.tools.warnings.OverwriteWarning`. Operators are now silently overwritten when a new operator with the same name as an existing one is passed into the ALNS instance.

.travis.yml

@@ -8,9 +8,15 @@ python:
   - "3.7"
   - "3.8"
   - "3.9"
+  - "3.10"
 
 # TODO eventually I want a better build matrix here, i.a. for numpy versions
 
+cache:
+  pip: true
+  directories:
+    - "$HOME/.cache/pypoetry"
+
 install:
   - pip install poetry
   - poetry install

README.md

@@ -17,16 +17,35 @@ may be used to run the ALNS algorithm, the second may be subclassed to
 store a solution state - all it requires is to define an `objective`
 member function, returning an objective value.
 
-The ALNS algorithm must be supplied with an acceptance criterion, to
-determine the acceptance of a new solution state at each iteration.
-An overview of common acceptance criteria is given in [Santini et al.
-(2018)][3]. Several have already been implemented for you, in
-`alns.criteria`,
-
-- `HillClimbing`. The simplest acceptance criterion, hill-climbing
-  solely accepts solutions improving the objective value.
-- `RecordToRecordTravel`. This criterion only accepts solutions when
-  the improvement meets some updating threshold.
+The ALNS algorithm must be supplied with a _weight scheme_ and an _acceptance
+criterion_.
+
+### Weight scheme
+The weight scheme determines how to select destroy and repair operators in each
+iteration of the ALNS algorithm. Several have already been implemented for you,
+in `alns.weight_schemes`:
+
+- `SimpleWeights`. This weight scheme applies a convex combination of the 
+   existing weight vector, and a reward given for the current candidate 
+   solution.
+- `SegmentedWeights`. This weight scheme divides the iteration horizon into
+   segments. In each segment, scores are summed for each operator. At the end
+   of each segment, the weight vector is updated as a convex combination of 
+   the existing weight vector, and these summed scores.
+
+Each weight scheme inherits from `WeightScheme`, which may be used to write 
+your own.
+
+### Acceptance criterion
+The acceptance criterion determines the acceptance of a new solution state at
+each iteration. An overview of common acceptance criteria is given in
+[Santini et al. (2018)][3]. Several have already been implemented for you, in
+`alns.criteria`:
+
+- `HillClimbing`. The simplest acceptance criterion, hill-climbing solely
+  accepts solutions improving the objective value.
+- `RecordToRecordTravel`. This criterion accepts solutions when the improvement
+  meets some updating threshold.
 - `SimulatedAnnealing`. This criterion accepts solutions when the
   scaled probability is bigger than some random number, using an
   updating temperature.
@@ -36,7 +55,7 @@ be used to write your own.
 
 ### Examples
 The `examples/` directory features some example notebooks showcasing
-how the ALNS library may be used. Of particular interest are,
+how the ALNS library may be used. These include:
 
 - The travelling salesman problem (TSP), [here][2]. We solve an
   instance of 131 cities to within 2.1% of optimality, using simple
@@ -45,6 +64,12 @@ how the ALNS library may be used. Of particular interest are,
   180 beams over 165 distinct sizes to within 1.35% of optimality in
   only a very limited number of iterations.
 
+Finally, the weight schemes and acceptance criteria notebook gives an overview
+of various options available in the `alns` package. In the notebook we use these
+different options to solve a toy 0/1-knapsack problem. The notebook is a good
+starting point for when you want to use the different schemes and criteria 
+yourself. It is available [here][5].
+
 ## References
 - Pisinger, D., and Ropke, S. (2010). Large Neighborhood Search. In M.
   Gendreau (Ed.), _Handbook of Metaheuristics_ (2 ed., pp. 399-420).
@@ -57,3 +82,4 @@ how the ALNS library may be used. Of particular interest are,
 [2]: https://github.com/N-Wouda/ALNS/blob/master/examples/travelling_salesman_problem.ipynb
 [3]: https://link.springer.com/article/10.1007%2Fs10732-018-9377-x
 [4]: https://github.com/N-Wouda/ALNS/blob/master/examples/cutting_stock_problem.ipynb
+[5]: https://github.com/N-Wouda/ALNS/blob/master/examples/weight_schemes_acceptance_criteria.ipynb