org.cpsolver.coursett.model

## Class DefaultStudentSectioning

- java.lang.Object
- - org.cpsolver.coursett.model.DefaultStudentSectioning

- All Implemented Interfaces:
    StudentSectioning, InfoProvider<Lecture,Placement>
  Direct Known Subclasses:
    DeterministicStudentSectioning, SctSectioning, StudentSwapSectioning

      public class DefaultStudentSectioning
      extends Object
      implements StudentSectioning, InfoProvider<Lecture,Placement>

  Default implementation of the student sectioning functions needed within the course timetabling solver consisting of `InitialSectioning` and `FinalSectioning`.
  Many course offerings consist of multiple classes, with students enrolled in the course divided among them. These classes are often linked by a set of constraints, namely:
  - Each class has a limit stating the maximum number of students who can be enrolled in it.
  - A student must be enrolled in exactly one class for each subpart of a course.
  - If two subparts of a course have a parent-child relationship, a student enrolled in the parent class must also be enrolled in one of the child classes.
  Moreover, some of the classes of an offering may be required or prohibited for certain students, based on reservations that can be set on an offering, a configuration, or a class.
  While the data are loaded into the solver, an initial sectioning of students into classes is processed (see `InitialSectioning`). However, it is still possible to improve on the number of student conflicts in the solution. This can be accomplished by moving students between alternative classes of the same course during or after the search (see `FinalSectioning`).
  Version:
    CourseTT 1.3 (University Course Timetabling)
    Copyright (C) 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/.
  Author:
    Tomáš Müller

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected FinalSectioning` | `iFinalSectioning`
    `protected TimetableModel` | `iModel`
    `protected boolean` | `iMustFollowReservations`
    `protected static DecimalFormat` | `sDF2`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DefaultStudentSectioning(TimetableModel model)` Constructor

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected String` | `getClassLabel(Lecture lecture)` Class label
    `void` | `getInfo(Assignment<Lecture,Placement> assignment, Map<String,String> info)` Adds some information into the table with information about the solution
    `void` | `getInfo(Assignment<Lecture,Placement> assignment, Map<String,String> info, Collection<Lecture> variables)` Adds some information into the table with information about the solution, only consider variables from the given set
    `Progress` | `getProgress()`
    `boolean` | `hasFinalSectioning()` Return true if final student sectioning is implemented.
    `void` | `initialSectioning(Assignment<Lecture,Placement> assignment, Long offeringId, String courseName, Collection<Student> students, Collection<Configuration> configurations)` Enroll students into the given offering during the initial data load using `InitialSectioning`.
    `protected void` | `initialSectioningLectures(Assignment<Lecture,Placement> assignment, Long offeringId, String courseName, Collection<Student> students, Collection<Lecture> lectures)` Enroll students into the given classes during the initial data load using `InitialSectioning`.
    `boolean` | `isMustFollowReservations()` Must reservations be followed?
    `void` | `resection(Assignment<Lecture,Placement> assignment, Lecture lecture, boolean recursive, boolean configAsWell)` Perform sectioning on the given lecture
    `void` | `setMustFollowReservations(boolean mustFollow)` Must reservations be followed?
    `protected InitialSectioning.Group[]` | `studentsToConfigurations(Long offeringId, Collection<Student> students, Collection<Configuration> configurations)` Section students into configurations.
    `protected InitialSectioning.Group[]` | `studentsToLectures(Long offeringId, Collection<Student> students, Collection<Lecture> lectures)` Section students into lectures.
    `void` | `switchStudents(Solution<Lecture,Placement> solution, TerminationCondition<Lecture,Placement> termination)` Run student final sectioning (switching students between sections of the same class in order to minimize overall number of student conflicts).

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

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

- - ### Field Detail

    - #### iModel

          protected TimetableModel iModel

    - #### iFinalSectioning

          protected FinalSectioning iFinalSectioning

    - #### iMustFollowReservations

          protected boolean iMustFollowReservations

    - #### sDF2

          protected static DecimalFormat sDF2

  - ### Constructor Detail

    - #### DefaultStudentSectioning

          public DefaultStudentSectioning(TimetableModel model)

      Constructor
      Parameters:
        `model` - problem model

  - ### Method Detail

    - #### getProgress

          public Progress getProgress()

    - #### initialSectioning

          public void initialSectioning(Assignment<Lecture,Placement> assignment,
                                        Long offeringId,
                                        String courseName,
                                        Collection<Student> students,
                                        Collection<Configuration> configurations)

      Enroll students into the given offering during the initial data load using `InitialSectioning`.
      Specified by:
        `initialSectioning` in interface `StudentSectioning`
      Parameters:
        `offeringId` - instructional offering id
        `courseName` - course name
        `students` - list of students to be sectioned
        `configurations` - list of configurations the students are to be sectioned into
        `assignment` - current assignment

    - #### getClassLabel

          protected String getClassLabel(Lecture lecture)

      Class label
      Parameters:
        `lecture` - a class
      Returns:
        class label including a link to be printed in the log

    - #### initialSectioningLectures

          protected void initialSectioningLectures(Assignment<Lecture,Placement> assignment,
                                                   Long offeringId,
                                                   String courseName,
                                                   Collection<Student> students,
                                                   Collection<Lecture> lectures)

      Enroll students into the given classes during the initial data load using `InitialSectioning`.
      Parameters:
        `assignment` - current assignment
        `offeringId` - instructional offering id
        `courseName` - course name
        `students` - list of students to be sectioned
        `lectures` - list of lectures the students are to be sectioned into

    - #### studentsToConfigurations

          protected InitialSectioning.Group[] studentsToConfigurations(Long offeringId,
                                                                       Collection<Student> students,
                                                                       Collection<Configuration> configurations)

      Section students into configurations. This method calls the actual initial sectioning `InitialSectioning.getGroups()`.
      Parameters:
        `offeringId` - instructional offering id
        `students` - list of students to be sectioned
        `configurations` - list of configurations the students are to be sectioned into
      Returns:
        list of `InitialSectioning.Group`

    - #### studentsToLectures

          protected InitialSectioning.Group[] studentsToLectures(Long offeringId,
                                                                 Collection<Student> students,
                                                                 Collection<Lecture> lectures)

      Section students into lectures. This method calls the actual initial sectioning `InitialSectioning.getGroups()`.
      Parameters:
        `offeringId` - instructional offering id
        `students` - list of students to be sectioned
        `lectures` - list of lectures the students are to be sectioned into
      Returns:
        list of `InitialSectioning.Group`

    - #### hasFinalSectioning

          public boolean hasFinalSectioning()

      Return true if final student sectioning is implemented.
      Specified by:
        `hasFinalSectioning` in interface `StudentSectioning`
      Returns:
        true if final student sectioning is implemented

    - #### switchStudents

          public void switchStudents(Solution<Lecture,Placement> solution,
                                     TerminationCondition<Lecture,Placement> termination)

      Run student final sectioning (switching students between sections of the same class in order to minimize overall number of student conflicts).
      Specified by:
        `switchStudents` in interface `StudentSectioning`
      Parameters:
        `solution` - current solution
        `termination` - termination condition (optional)

    - #### resection

          public void resection(Assignment<Lecture,Placement> assignment,
                                Lecture lecture,
                                boolean recursive,
                                boolean configAsWell)

      Perform sectioning on the given lecture
      Specified by:
        `resection` in interface `StudentSectioning`
      Parameters:
        `lecture` - given lecture
        `recursive` - recursively resection lectures affected by a student swap
        `configAsWell` - resection students between configurations as well
        `assignment` - current assignment

    - #### getInfo

          public void getInfo(Assignment<Lecture,Placement> 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<Lecture,Placement>`
      Parameters:
        `assignment` - current assignment
        `info` - info table

    - #### getInfo

          public void getInfo(Assignment<Lecture,Placement> assignment,
                              Map<String,String> info,
                              Collection<Lecture> 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<Lecture,Placement>`
      Parameters:
        `assignment` - current assignment
        `info` - info table
        `variables` - sub-problem

    - #### isMustFollowReservations

          public boolean isMustFollowReservations()

      Must reservations be followed? When true, a student cannot be placed in a section where `Student.canEnroll(Lecture)` is false. Defaults to false.

    - #### setMustFollowReservations

          public void setMustFollowReservations(boolean mustFollow)

      Must reservations be followed? When true, a student cannot be placed in a section where `Student.canEnroll(Lecture)` is false. Defaults to false.