org.cpsolver.studentsct.heuristics.selection

## Class SwapStudentSelection

- java.lang.Object
- - org.cpsolver.studentsct.heuristics.selection.SwapStudentSelection

- All Implemented Interfaces:
    NeighbourSelection<Request,Enrollment>, InfoProvider<Request,Enrollment>, SolverListener<Request,Enrollment>, ProblemStudentsProvider

      public class SwapStudentSelection
      extends Object
      implements NeighbourSelection<Request,Enrollment>, ProblemStudentsProvider, InfoProvider<Request,Enrollment>, SolverListener<Request,Enrollment>

  Pick a student (one by one) with an incomplete schedule, try to find an improvement, identify problematic students.
  For each request that does not have an assignment and that can be assined (see `Student.canAssign(Assignment, Request)`) a randomly selected sub-domain is visited. For every such enrollment, a set of conflicting enrollments is computed and a possible student that can get an alternative enrollment is identified (if there is any). For each such move a value (the cost of moving the problematic student somewhere else) is computed and the best possible move is selected at the end. If there is no such move, a set of problematic students is identified, i.e., the students whose enrollments are preventing this student to get a request.
  Each student can be selected for this swap move multiple times, but only if there is still a request that can be resolved. At the end (when there is no other neighbour), the set of all such problematic students can be returned using the `ProblemStudentsProvider` interface.
  Parameters:

  Parameter | Type | Comment
  --- | --- | ---
  Neighbour.SwapStudentsTimeout | `Integer` | Timeout for each neighbour selection (in milliseconds).
  Neighbour.SwapStudentsMaxValues | `Integer` | Limit for the number of considered values for each course request (see `CourseRequest.computeRandomEnrollments(Assignment, int)`).

  Version:
    StudentSct 1.3 (Student Sectioning)
    Copyright (C) 2007 - 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/.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `SwapStudentSelection.Selection` This class looks for a possible swap move for the given student
    `static class` | `SwapStudentSelection.SwapStudentNeighbour` Neighbour that contains the swap

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected long` | `iNbrIterations`
    `protected long` | `iNbrNoSolution`
    `protected long` | `iNbrTimeoutReached`
    `protected StudentOrder` | `iOrder`
    `protected long` | `iTotalTime`
    `static boolean` | `sDebug`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SwapStudentSelection(DataProperties properties)` Constructor

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addStudent(Student student)`
    `static Enrollment` | `bestSwap(Assignment<Request,Enrollment> assignment, Enrollment conflict, Enrollment enrl, Set<Student> problematicStudents)` Identify the best swap for the given student
    `void` | `getInfo(Assignment<Request,Enrollment> assignment, Map<String,String> info)` Adds some information into the table with information about the solution
    `void` | `getInfo(Assignment<Request,Enrollment> assignment, Map<String,String> info, Collection<Request> variables)` Adds some information into the table with information about the solution, only consider variables from the given set
    `Set<Student>` | `getProblemStudents()` List of problematic students
    `SwapStudentSelection.Selection` | `getSelection(Assignment<Request,Enrollment> assignment, Student student)` Selection subclass for a student
    `void` | `init(Solver<Request,Enrollment> solver)` Initialization
    `void` | `neighbourFailed(Assignment<Request,Enrollment> assignment, long iteration, Neighbour<Request,Enrollment> neighbour)` Called when `ParallelSolver` failed to assign the given neighbour
    `boolean` | `neighbourSelected(Assignment<Request,Enrollment> assignment, long iteration, Neighbour<Request,Enrollment> neighbour)` A neighbour was selected
    `protected Student` | `nextStudent()`
    `Neighbour<Request,Enrollment>` | `selectNeighbour(Solution<Request,Enrollment> solution)` For each student that does not have a complete schedule, try to find a request and a student that can be moved out of an enrollment so that the selected student can be assigned to the selected request.
    `boolean` | `valueSelected(Assignment<Request,Enrollment> assignment, long iteration, Request variable, Enrollment value)` A value was selected
    `boolean` | `variableSelected(Assignment<Request,Enrollment> assignment, long iteration, Request variable)` A variable was selected

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

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

- - ### Field Detail

    - #### sDebug

          public static boolean sDebug

    - #### iOrder

          protected StudentOrder iOrder

    - #### iNbrIterations

          protected long iNbrIterations

    - #### iTotalTime

          protected long iTotalTime

    - #### iNbrTimeoutReached

          protected long iNbrTimeoutReached

    - #### iNbrNoSolution

          protected long iNbrNoSolution

  - ### Constructor Detail

    - #### SwapStudentSelection

          public SwapStudentSelection(DataProperties properties)

      Constructor
      Parameters:
        `properties` - configuration

  - ### Method Detail

    - #### init

          public void init(Solver<Request,Enrollment> solver)

      Initialization
      Specified by:
        `init` in interface `NeighbourSelection<Request,Enrollment>`
      Parameters:
        `solver` - current solver

    - #### nextStudent

          protected Student nextStudent()

    - #### addStudent

          public void addStudent(Student student)

    - #### selectNeighbour

          public Neighbour<Request,Enrollment> selectNeighbour(Solution<Request,Enrollment> solution)

      For each student that does not have a complete schedule, try to find a request and a student that can be moved out of an enrollment so that the selected student can be assigned to the selected request.
      Specified by:
        `selectNeighbour` in interface `NeighbourSelection<Request,Enrollment>`
      Parameters:
        `solution` - given solution
      Returns:
        a neighbour assignment

    - #### getProblemStudents

          public Set<Student> getProblemStudents()

      List of problematic students
      Specified by:
        `getProblemStudents` in interface `ProblemStudentsProvider`
      Returns:
        set of problematic students

    - #### getSelection

          public SwapStudentSelection.Selection getSelection(Assignment<Request,Enrollment> assignment,
                                                             Student student)

      Selection subclass for a student
      Parameters:
        `assignment` - current assignment
        `student` - selected student
      Returns:
        swap student selection

    - #### bestSwap

          public static Enrollment bestSwap(Assignment<Request,Enrollment> assignment,
                                            Enrollment conflict,
                                            Enrollment enrl,
                                            Set<Student> problematicStudents)

      Identify the best swap for the given student
      Parameters:
        `assignment` - current assignment
        `conflict` - conflicting enrollment
        `enrl` - enrollment that is visited (to be assigned to the given student)
        `problematicStudents` - the current set of problematic students
      Returns:
        best alternative enrollment for the student of the conflicting enrollment

    - #### getInfo

          public void getInfo(Assignment<Request,Enrollment> assignment,
                              Map<String,String> info)

      Description copied from interface: `InfoProvider`
      Adds some information into the table with information about the solution
      Specified by:
        `getInfo` in interface `InfoProvider<Request,Enrollment>`
      Parameters:
        `assignment` - current assignment
        `info` - info table

    - #### getInfo

          public void getInfo(Assignment<Request,Enrollment> assignment,
                              Map<String,String> info,
                              Collection<Request> variables)

      Description copied from interface: `InfoProvider`
      Adds some information into the table with information about the solution, only consider variables from the given set
      Specified by:
        `getInfo` in interface `InfoProvider<Request,Enrollment>`
      Parameters:
        `assignment` - current assignment
        `info` - info table
        `variables` - sub-problem

    - #### variableSelected

          public boolean variableSelected(Assignment<Request,Enrollment> assignment,
                                          long iteration,
                                          Request variable)

      Description copied from interface: `SolverListener`
      A variable was selected
      Specified by:
        `variableSelected` in interface `SolverListener<Request,Enrollment>`
      Parameters:
        `assignment` - current assignment
        `iteration` - current iteration
        `variable` - selected variable
      Returns:
        if false is returned the variable will be discarded (search continues with the next variable selection)

    - #### valueSelected

          public boolean valueSelected(Assignment<Request,Enrollment> assignment,
                                       long iteration,
                                       Request variable,
                                       Enrollment value)

      Description copied from interface: `SolverListener`
      A value was selected
      Specified by:
        `valueSelected` in interface `SolverListener<Request,Enrollment>`
      Parameters:
        `assignment` - current assignment
        `iteration` - current iteration
        `variable` - selected variable
        `value` - selected variable
      Returns:
        if false is returned the selected value is not assigned

    - #### neighbourSelected

          public boolean neighbourSelected(Assignment<Request,Enrollment> assignment,
                                           long iteration,
                                           Neighbour<Request,Enrollment> neighbour)

      Description copied from interface: `SolverListener`
      A neighbour was selected
      Specified by:
        `neighbourSelected` in interface `SolverListener<Request,Enrollment>`
      Parameters:
        `assignment` - current assignment
        `iteration` - current iteration
        `neighbour` - neighbour
      Returns:
        if false is returned the selected neighbour is not assigned

    - #### neighbourFailed

          public void neighbourFailed(Assignment<Request,Enrollment> assignment,
                                      long iteration,
                                      Neighbour<Request,Enrollment> neighbour)

      Description copied from interface: `SolverListener`
      Called when `ParallelSolver` failed to assign the given neighbour
      Specified by:
        `neighbourFailed` in interface `SolverListener<Request,Enrollment>`
      Parameters:
        `assignment` - current assignment
        `iteration` - current iteration
        `neighbour` - neighbour