org.cpsolver.coursett.heuristics

## Class HeuristicSelector<E>

- java.lang.Object
- - org.cpsolver.coursett.heuristics.HeuristicSelector<E>

- Type Parameters:
    `E` - A class of the objects that are being selected from

      public class HeuristicSelector<E>
      extends Object

  General hierarchical selection.
  We have implemented a hierarchical handling of the value selection criteria. There are three levels of comparison. At each level a weighted sum of the criteria described below is computed. Only solutions with the smallest sum are considered in the next level. The weights express how quickly a complete solution should be found. Only hard constraints are satisfied in the first level sum. Distance from the initial solution (MPP), and a weighting of major preferences (including time, classroom requirements and student conflicts), are considered in the next level. In the third level, other minor criteria are considered. In general, a criterion can be used in more than one level, e.g., with different weights.
  The above sums order the values lexicographically: the best value having the smallest first level sum, the smallest second level sum among values with the smallest first level sum, and the smallest third level sum among these values. As mentioned above, this allows diversification between the importance of individual criteria.
  Furthermore, the value selection heuristics also support some limits (e.g., that all values with a first level sum smaller than a given percentage Pth above the best value [typically 10%] will go to the second level comparison and so on). This allows for the continued feasibility of a value near to the best that may yet be much better in the next level of comparison. If there is more than one solution after these three levels of comparison, one is selected randomly. This approach helped us to significantly improve the quality of the resultant solutions.
  In general, there can be more than three levels of these weighted sums, however three of them seem to be sufficient for spreading weights of various criteria for our problem.
  Version:
    CourseTT 1.3 (University Course Timetabling)
    Copyright (C) 2006 - 2014 Tomáš Müller
    muller@unitime.org
    http://muller.unitime.org
    This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
    This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
    You should have received a copy of the GNU Lesser General Public License along with this library; if not see http://www.gnu.org/licenses/.
  See Also:
    `PlacementSelection`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `HeuristicSelector.Element` An element in heuristical selection

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `HeuristicSelector(double[] threshKoef)` Constructor

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `add(double[] values, E object)` Adds an object to selection
    `Double` | `firstLevelThreshold()`
    `List<HeuristicSelector.Element>` | `selection()` Do the selection.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### HeuristicSelector

          public HeuristicSelector(double[] threshKoef)

      Constructor
      Parameters:
        `threshKoef` - limit for each level, e.g., new double[] {0.1, 0.1, 0.1} for three level selection with 10% limit on each level

  - ### Method Detail

    - #### add

          public boolean add(double[] values,
                             E object)

      Adds an object to selection
      Parameters:
        `values` - weighted sum for each level
        `object` - object to be returned if selected
      Returns:
        true if added (it is not added if it is obvious that it cannot be selected)

    - #### firstLevelThreshold

          public Double firstLevelThreshold()

    - #### selection

          public List<HeuristicSelector.Element> selection()

      Do the selection.
      Returns:
        inserted objects which met the criteria