org.cpsolver.studentsct

## Class StudentPreferencePenalties

- java.lang.Object
- - org.cpsolver.studentsct.StudentPreferencePenalties

-     public class StudentPreferencePenalties
      extends Object

  An attempt to empirically test the case when students can choose their sections (section times).
  Each student has his/her own order of possible times of the week (selection of a day and an hour starting 7:30, 8:30, etc.) -- this order is computed using roulette wheel selection with the distribution of possible times defined in `sStudentRequestDistribution`.
  A penalty for each section is computed proportionally based on this order (and the number of slots that falls into each time frame), the existing branch & bound selection is used to section each student one by one (in a random order).
  Usage:

       for (Enumeration e=students.elements();e.hasMoreElements();) {
         // take a student (one by one)
         Student student = (Student)e.nextElement();

         // compute and apply penalties using this class
         new StudentPreferencePenalties().setPenalties(student);

         // section a student
         // for instance, BranchBoundSelection can be used (with Neighbour.BranchAndBoundMinimizePenalty set to true)
         Neighbour neighbour = new BranchBoundSelection(config).getSelection(student).select();
         if (neighbour!=null) neighbour.assign(iteration++);
       };

  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/.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `sDistTypePreference`
    `static int` | `sDistTypePreferenceQuadratic`
    `static int` | `sDistTypePreferenceReverse`
    `static int` | `sDistTypeUniform`
    `static int[][]` | `sStudentRequestDistribution`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `StudentPreferencePenalties(int disributionType)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static int` | `day(int slot)` Return day index in `sStudentRequestDistribution` for the given slot.
    `double` | `getMaxPenalty(Config config)` Maximal penalty of a config
    `double` | `getMaxPenalty(CourseRequest request)` Maximal penalty of a course request
    `double` | `getMaxPenalty(Offering offering)` Maximal penalty of an offering
    `double` | `getMaxPenalty(Request request)` Maximal penalty of a course request
    `double` | `getMaxPenalty(Subpart subpart)` Maximal penalty of a subpart
    `double[]` | `getMinMaxAvailableEnrollmentPenalty(Assignment<Request,Enrollment> assignment, CourseRequest request)` Minimal and maximal available enrollment penalty of a request
    `double[]` | `getMinMaxAvailableEnrollmentPenalty(Assignment<Request,Enrollment> assignment, Request request)` Minimal and maximal available enrollment penalty of a request
    `double[]` | `getMinMaxEnrollmentPenalty(CourseRequest request)` Minimal and maximal available enrollment penalty of a request
    `double[]` | `getMinMaxEnrollmentPenalty(Request request)` Minimal and maximal available enrollment penalty of a request
    `double` | `getMinPenalty(Config config)` Minimal penalty of a config
    `double` | `getMinPenalty(CourseRequest request)` Minimal penalty of a course request
    `double` | `getMinPenalty(Offering offering)` Minimal penalty of an offering
    `double` | `getMinPenalty(Request request)` Minimal penalty of a course request
    `double` | `getMinPenalty(Subpart subpart)` Minimal penalty of a subpart
    `double` | `getPenalty(Enrollment enrollment)` Return penalty of an enrollment.
    `double` | `getPenalty(SctAssignment assignment)` Return penalty of an assignment.
    `double` | `getPenalty(TimeLocation time)` Return penalty of the given time.
    `static void` | `setPenalties(Student student, int distributionType)` Set the computed penalties to all sections of all requests of the given student
    `static int` | `time(int slot)` Return time index in `sStudentRequestDistribution` for the given slot.
    `String` | `toString(int day, int time)` Return time of the given day and time index of `sStudentRequestDistribution`.

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

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

- - ### Field Detail

    - #### sDistTypeUniform

          public static int sDistTypeUniform

    - #### sDistTypePreference

          public static int sDistTypePreference

    - #### sDistTypePreferenceQuadratic

          public static int sDistTypePreferenceQuadratic

    - #### sDistTypePreferenceReverse

          public static int sDistTypePreferenceReverse

    - #### sStudentRequestDistribution

          public static int[][] sStudentRequestDistribution

  - ### Constructor Detail

    - #### StudentPreferencePenalties

          public StudentPreferencePenalties(int disributionType)

      Constructor. All possible times are ordered based on the distribution defined by `sStudentRequestDistribution` . The first time gets zero penalty, the second 1/nrTimes, the third 2/nrTimes etc. where nrTimes is the number of times in `sStudentRequestDistribution`.
      Parameters:
        `disributionType` - distribution type

  - ### Method Detail

    - #### day

          public static int day(int slot)

      Return day index in `sStudentRequestDistribution` for the given slot.
      Parameters:
        `slot` - time slot
      Returns:
        day index

    - #### time

          public static int time(int slot)

      Return time index in `sStudentRequestDistribution` for the given slot.
      Parameters:
        `slot` - time slot
      Returns:
        time index

    - #### toString

          public String toString(int day,
                                 int time)

      Return time of the given day and time index of `sStudentRequestDistribution`.
      Parameters:
        `day` - day index
        `time` - time index
      Returns:
        day and time as string

    - #### getPenalty

          public double getPenalty(TimeLocation time)

      Return penalty of the given time. It is computed as average of the penalty for each time slot of the time.
      Parameters:
        `time` - time location
      Returns:
        penalty

    - #### getPenalty

          public double getPenalty(SctAssignment assignment)

      Return penalty of an assignment. It is a penalty of its time (see `SctAssignment.getTime()`) or zero if the time is null.
      Parameters:
        `assignment` - section assignment
      Returns:
        penalty

    - #### getPenalty

          public double getPenalty(Enrollment enrollment)

      Return penalty of an enrollment. It is an average penalty of all its assignments `Enrollment.getAssignments()`.
      Parameters:
        `enrollment` - enrollment
      Returns:
        penalty

    - #### getMinPenalty

          public double getMinPenalty(Request request)

      Minimal penalty of a course request
      Parameters:
        `request` - student request
      Returns:
        minimal penalty

    - #### getMinPenalty

          public double getMinPenalty(CourseRequest request)

      Minimal penalty of a course request
      Parameters:
        `request` - course request
      Returns:
        minimal penalty

    - #### getMinPenalty

          public double getMinPenalty(Offering offering)

      Minimal penalty of an offering
      Parameters:
        `offering` - instructional offering
      Returns:
        minimal penalty

    - #### getMinPenalty

          public double getMinPenalty(Config config)

      Minimal penalty of a config
      Parameters:
        `config` - instructional offering configuration
      Returns:
        minimal penalty

    - #### getMinPenalty

          public double getMinPenalty(Subpart subpart)

      Minimal penalty of a subpart
      Parameters:
        `subpart` - scheduling subpart
      Returns:
        minimal penalty

    - #### getMaxPenalty

          public double getMaxPenalty(Request request)

      Maximal penalty of a course request
      Parameters:
        `request` - student request
      Returns:
        maximal penalty

    - #### getMaxPenalty

          public double getMaxPenalty(CourseRequest request)

      Maximal penalty of a course request
      Parameters:
        `request` - student course request
      Returns:
        maximal penalty

    - #### getMaxPenalty

          public double getMaxPenalty(Offering offering)

      Maximal penalty of an offering
      Parameters:
        `offering` - instructional offering
      Returns:
        maximal penalty

    - #### getMaxPenalty

          public double getMaxPenalty(Config config)

      Maximal penalty of a config
      Parameters:
        `config` - instructional offering config
      Returns:
        maximal penalty

    - #### getMaxPenalty

          public double getMaxPenalty(Subpart subpart)

      Maximal penalty of a subpart
      Parameters:
        `subpart` - scheduling subpart
      Returns:
        maximal penalty

    - #### getMinMaxAvailableEnrollmentPenalty

          public double[] getMinMaxAvailableEnrollmentPenalty(Assignment<Request,Enrollment> assignment,
                                                              Request request)

      Minimal and maximal available enrollment penalty of a request
      Parameters:
        `assignment` - current assignment
        `request` - student request
      Returns:
        minimal and maximal available enrollment penalty

    - #### getMinMaxAvailableEnrollmentPenalty

          public double[] getMinMaxAvailableEnrollmentPenalty(Assignment<Request,Enrollment> assignment,
                                                              CourseRequest request)

      Minimal and maximal available enrollment penalty of a request
      Parameters:
        `assignment` - current assignment
        `request` - student course request
      Returns:
        minimal and maximal available enrollment penalty

    - #### getMinMaxEnrollmentPenalty

          public double[] getMinMaxEnrollmentPenalty(Request request)

      Minimal and maximal available enrollment penalty of a request
      Parameters:
        `request` - student request
      Returns:
        minimal and maximal penalty

    - #### getMinMaxEnrollmentPenalty

          public double[] getMinMaxEnrollmentPenalty(CourseRequest request)

      Minimal and maximal available enrollment penalty of a request
      Parameters:
        `request` - student course request
      Returns:
        minimal and maximal penalty

    - #### setPenalties

          public static void setPenalties(Student student,
                                          int distributionType)

      Set the computed penalties to all sections of all requests of the given student
      Parameters:
        `student` - given student
        `distributionType` - penalty distribution type