org.cpsolver.instructor.model

## Class Instructor

- java.lang.Object
- - org.cpsolver.ifs.assignment.context.AbstractClassWithContext<TeachingRequest.Variable,TeachingAssignment,Instructor.Context>
  - - org.cpsolver.instructor.model.Instructor

- All Implemented Interfaces:
    CanHoldContext, CanInheritContext<TeachingRequest.Variable,TeachingAssignment,Instructor.Context>, HasAssignmentContext<TeachingRequest.Variable,TeachingAssignment,Instructor.Context>

      public class Instructor
      extends AbstractClassWithContext<TeachingRequest.Variable,TeachingAssignment,Instructor.Context>
      implements CanInheritContext<TeachingRequest.Variable,TeachingAssignment,Instructor.Context>

  Instructor. An instructor has an id, a name, a teaching preference, a maximal teaching load, a back-to-back preference. It can also have a set of attributes and course and time preferences. Availability is modeled with prohibited time preferences.
  Version:
    IFS 1.3 (Instructor Sectioning)
    Copyright (C) 2016 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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `Instructor.Context` Instructor Constraint Context.

  - ### Field Summary

    - ### Fields inherited from interface org.cpsolver.ifs.assignment.context.CanHoldContext

      `sMaxSize`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Instructor(long id, String externalId, String name, int preference, float maxLoad)` Constructor

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addAttribute(Attribute attribute)` Add instructor attribute
    `void` | `addCoursePreference(Preference<Course> pref)` Add course preference
    `GroupConstraint.Distribution` | `addDistribution(String reference, String preference, String name)` Add a distribution preference, returns null if there is no match.
    `void` | `addTimePreference(Preference<TimeLocation> pref)` Add instructor time preference
    `boolean` | `canTeach(TeachingRequest request)` Check if this instructor can teach the given request.
    `double` | `countBackToBacks(Assignment<TeachingRequest.Variable,TeachingAssignment> assignment, TeachingAssignment value, double diffRoomWeight, double diffTypeWeight)` Compute number of back-to-back assignments (weighted by the preference) of the given teaching assignment and the other assignments of the instructor
    `double` | `countSameDays(Assignment<TeachingRequest.Variable,TeachingAssignment> assignment, TeachingAssignment value, double diffRoomWeight, double diffTypeWeight)` Compute number of same days assignments (weighted by the preference) of the given teaching assignment and the other assignments of the instructor
    `double` | `countSameRooms(Assignment<TeachingRequest.Variable,TeachingAssignment> assignment, TeachingAssignment value, double diffTypeWeight)` Compute number of same room assignments (weighted by the preference) of the given teaching assignment and the other assignments of the instructor
    `Instructor.Context` | `createAssignmentContext(Assignment<TeachingRequest.Variable,TeachingAssignment> assignment)` Create a new assignment context for the given assignment.
    `double` | `differentLectures(Assignment<TeachingRequest.Variable,TeachingAssignment> assignment, TeachingAssignment value)` Compute different common sections of the given teaching assignment and the other assignments of the instructor
    `boolean` | `equals(Object o)`
    `List<Attribute>` | `getAttributes()` Return instructor attributes
    `Set<Attribute>` | `getAttributes(Attribute.Type type)` Return instructor attributes of given type
    `String` | `getAvailable()` Instructor unavailability string generated from prohibited time preferences
    `int` | `getBackToBackPreference()` Return back-to-back preference (only soft preference can be set at the moment)
    `Preference<Course>` | `getCoursePreference(Course course)` Return preference for the given course
    `List<Preference<Course>>` | `getCoursePreferences()` Return course preferences
    `List<GroupConstraint.Distribution>` | `getDistributions()` Return all distribution preferences for an instructor
    `String` | `getExternalId()` Instructor external Id that was provided in the constructor
    `long` | `getInstructorId()` Instructor unique id that was provided in the constructor
    `float` | `getMaxLoad()` Maximal load
    `InstructorSchedulingModel` | `getModel()` Get the model.
    `String` | `getName()` Instructor name that was provided in the constructor
    `int` | `getPreference()` Return teaching preference
    `int` | `getSameDaysPreference()` Return same-days preference (only soft preference can be set at the moment)
    `int` | `getSameRoomPreference()` Return same-room preference (only soft preference can be set at the moment)
    `PreferenceCombination` | `getTimePreference(TeachingRequest request)` Compute time preference for a given teaching request.
    `PreferenceCombination` | `getTimePreference(TimeLocation time)` Compute time preference for a given time.
    `List<Preference<TimeLocation>>` | `getTimePreferences()` Return instructor preferences
    `boolean` | `hasDistributions()` Check if the instructor has any distributions
    `boolean` | `hasExternalId()` Has instructor external id?
    `int` | `hashCode()`
    `boolean` | `hasName()` Has instructor name?
    `Instructor.Context` | `inheritAssignmentContext(Assignment<TeachingRequest.Variable,TeachingAssignment> assignment, Instructor.Context parentContext)` Create a new assignment context for the given assignment.
    `boolean` | `isBackToBackDiscouraged()` Is back-to-back discouraged?
    `boolean` | `isBackToBackPreferred()` Is back-to-back preferred?
    `boolean` | `isSameDaysDiscouraged()` Is same-days discouraged?
    `boolean` | `isSameDaysPreferred()` Is same-days preferred?
    `boolean` | `isSameRoomDiscouraged()` Is same-room discouraged?
    `boolean` | `isSameRoomPreferred()` Is same-room preferred?
    `void` | `setBackToBackPreference(int backToBackPreference)` Set back-to-back preference (only soft preference can be set at the moment)
    `void` | `setModel(InstructorSchedulingModel model)` Set current model
    `void` | `setPreference(int preference)` Set teaching preference
    `void` | `setSameDaysPreference(int sameDaysPreference)` Set same-days preference (only soft preference can be set at the moment)
    `void` | `setSameRoomPreference(int sameRoomPreference)` Set same-room preference (only soft preference can be set at the moment)
    `int` | `share(Assignment<TeachingRequest.Variable,TeachingAssignment> assignment, TeachingAssignment value)` Compute time overlaps with instructor availability and other teaching assignments of the instructor
    `int` | `share(TeachingRequest request)` Compute time overlaps with instructor availability
    `String` | `toString()`

    - ### Methods inherited from class org.cpsolver.ifs.assignment.context.AbstractClassWithContext

      `getAssignmentContextReference, getContext, getContext, setAssignmentContextReference`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Instructor

          public Instructor(long id,
                            String externalId,
                            String name,
                            int preference,
                            float maxLoad)

      Constructor
      Parameters:
        `id` - instructor unique id
        `externalId` - instructor external id
        `name` - instructor name
        `preference` - teaching preference
        `maxLoad` - maximal teaching load

  - ### Method Detail

    - #### getModel

          public InstructorSchedulingModel getModel()

      Description copied from class: `AbstractClassWithContext`
      Get the model. This is used to create an assignment context if needed.
      Specified by:
        `getModel` in class `AbstractClassWithContext<TeachingRequest.Variable,TeachingAssignment,Instructor.Context>`
      Returns:
        model

    - #### setModel

          public void setModel(InstructorSchedulingModel model)

      Set current model
      Parameters:
        `model` - instructional scheduling model

    - #### getInstructorId

          public long getInstructorId()

      Instructor unique id that was provided in the constructor
      Returns:
        instructor unique id

    - #### hasExternalId

          public boolean hasExternalId()

      Has instructor external id?
      Returns:
        true, if the instructor has an external id set

    - #### getExternalId

          public String getExternalId()

      Instructor external Id that was provided in the constructor
      Returns:
        external id

    - #### hasName

          public boolean hasName()

      Has instructor name?
      Returns:
        true, if the instructor name is set

    - #### getName

          public String getName()

      Instructor name that was provided in the constructor
      Returns:
        instructor name

    - #### setBackToBackPreference

          public void setBackToBackPreference(int backToBackPreference)

      Set back-to-back preference (only soft preference can be set at the moment)
      Parameters:
        `backToBackPreference` - back-to-back preference (e.g., -1 for preferred, 1 for discouraged)

    - #### getBackToBackPreference

          public int getBackToBackPreference()

      Return back-to-back preference (only soft preference can be set at the moment)
      Returns:
        back-to-back preference (e.g., -1 for preferred, 1 for discouraged)

    - #### isBackToBackPreferred

          public boolean isBackToBackPreferred()

      Is back-to-back preferred?
      Returns:
        true if the back-to-back preference is negative

    - #### isBackToBackDiscouraged

          public boolean isBackToBackDiscouraged()

      Is back-to-back discouraged?
      Returns:
        true if the back-to-back preference is positive

    - #### setSameDaysPreference

          public void setSameDaysPreference(int sameDaysPreference)

      Set same-days preference (only soft preference can be set at the moment)
      Parameters:
        `sameDaysPreference` - same-days preference (e.g., -1 for preferred, 1 for discouraged)

    - #### getSameDaysPreference

          public int getSameDaysPreference()

      Return same-days preference (only soft preference can be set at the moment)
      Returns:
        same-days preference (e.g., -1 for preferred, 1 for discouraged)

    - #### isSameDaysPreferred

          public boolean isSameDaysPreferred()

      Is same-days preferred?
      Returns:
        true if the same-days preference is negative

    - #### isSameDaysDiscouraged

          public boolean isSameDaysDiscouraged()

      Is same-days discouraged?
      Returns:
        true if the same-days preference is positive

    - #### setSameRoomPreference

          public void setSameRoomPreference(int sameRoomPreference)

      Set same-room preference (only soft preference can be set at the moment)
      Parameters:
        `sameRoomPreference` - same-room preference (e.g., -1 for preferred, 1 for discouraged)

    - #### getSameRoomPreference

          public int getSameRoomPreference()

      Return same-room preference (only soft preference can be set at the moment)
      Returns:
        same-room preference (e.g., -1 for preferred, 1 for discouraged)

    - #### isSameRoomPreferred

          public boolean isSameRoomPreferred()

      Is same-room preferred?
      Returns:
        true if the same-room preference is negative

    - #### isSameRoomDiscouraged

          public boolean isSameRoomDiscouraged()

      Is same-room discouraged?
      Returns:
        true if the same-room preference is positive

    - #### getAvailable

          public String getAvailable()

      Instructor unavailability string generated from prohibited time preferences
      Returns:
        comma separated list of times during which the instructor is not available

    - #### getAttributes

          public List<Attribute> getAttributes()

      Return instructor attributes
      Returns:
        list of instructor attributes

    - #### addAttribute

          public void addAttribute(Attribute attribute)

      Add instructor attribute
      Parameters:
        `attribute` - instructor attribute

    - #### getAttributes

          public Set<Attribute> getAttributes(Attribute.Type type)

      Return instructor attributes of given type
      Parameters:
        `type` - attribute type
      Returns:
        attributes of this instructor that are of the given type

    - #### getTimePreferences

          public List<Preference<TimeLocation>> getTimePreferences()

      Return instructor preferences
      Returns:
        list of instructor time preferences

    - #### addTimePreference

          public void addTimePreference(Preference<TimeLocation> pref)

      Add instructor time preference
      Parameters:
        `pref` - instructor time preference

    - #### getTimePreference

          public PreferenceCombination getTimePreference(TimeLocation time)

      Compute time preference for a given time. This is using the `MinMaxPreferenceCombination` for all time preferences that are overlapping with the given time.
      Parameters:
        `time` - given time
      Returns:
        computed preference for the given time

    - #### getTimePreference

          public PreferenceCombination getTimePreference(TeachingRequest request)

      Compute time preference for a given teaching request. This is using the `MinMaxPreferenceCombination` for all time preferences that are overlapping with the given teaching request. When a section that allows for overlaps (see `Section.isAllowOverlap()`) overlap with a prohibited time preference, this is only counted as strongly discouraged.
      Parameters:
        `request` - teaching request that is being considered
      Returns:
        computed time preference

    - #### getCoursePreferences

          public List<Preference<Course>> getCoursePreferences()

      Return course preferences
      Returns:
        list of instructor course preferences

    - #### addCoursePreference

          public void addCoursePreference(Preference<Course> pref)

      Add course preference
      Parameters:
        `pref` - instructor course preference

    - #### getCoursePreference

          public Preference<Course> getCoursePreference(Course course)

      Return preference for the given course
      Parameters:
        `course` - course that is being considered
      Returns:
        course preference for the given course

    - #### getPreference

          public int getPreference()

      Return teaching preference
      Returns:
        teaching preference of this instructor

    - #### setPreference

          public void setPreference(int preference)

      Set teaching preference
      Parameters:
        `preference` - teaching preference of this instructor

    - #### getMaxLoad

          public float getMaxLoad()

      Maximal load
      Returns:
        maximal load of this instructor

    - #### canTeach

          public boolean canTeach(TeachingRequest request)

      Check if this instructor can teach the given request. This means that the given request is below the maximal teaching load, the instructor is available (time preference is not prohibited), the instructor does not prohibit the course (there is no prohibited course preference for the given course), and the request's instructor preference is also not prohibited. So, the only thing that is not checked are the attribute preferences.
      Parameters:
        `request` - teaching request that is being considered
      Returns:
        true, if the instructor can be assigned to the given teaching request

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### share

          public int share(TeachingRequest request)

      Compute time overlaps with instructor availability
      Parameters:
        `request` - teaching request that is being considered
      Returns:
        number of slots during which the instructor has a prohibited time preferences that are overlapping with a section of the request that is allowing for overlaps

    - #### share

          public int share(Assignment<TeachingRequest.Variable,TeachingAssignment> assignment,
                           TeachingAssignment value)

      Compute time overlaps with instructor availability and other teaching assignments of the instructor
      Parameters:
        `assignment` - current assignment
        `value` - teaching assignment that is being considered
      Returns:
        number of overlapping time slots (of the requested assignment) during which the overlaps are allowed

    - #### differentLectures

          public double differentLectures(Assignment<TeachingRequest.Variable,TeachingAssignment> assignment,
                                          TeachingAssignment value)

      Compute different common sections of the given teaching assignment and the other assignments of the instructor
      Parameters:
        `assignment` - current assignment
        `value` - teaching assignment that is being considered
      Returns:
        average `TeachingRequest.nrSameLectures(TeachingRequest)` between the given and the other existing assignments of the instructor

    - #### countBackToBacks

          public double countBackToBacks(Assignment<TeachingRequest.Variable,TeachingAssignment> assignment,
                                         TeachingAssignment value,
                                         double diffRoomWeight,
                                         double diffTypeWeight)

      Compute number of back-to-back assignments (weighted by the preference) of the given teaching assignment and the other assignments of the instructor
      Parameters:
        `assignment` - current assignment
        `value` - teaching assignment that is being considered
        `diffRoomWeight` - different room penalty
        `diffTypeWeight` - different instructional type penalty
      Returns:
        weighted back-to-back preference, using `TeachingRequest.countBackToBacks(TeachingRequest, double, double)`

    - #### countSameDays

          public double countSameDays(Assignment<TeachingRequest.Variable,TeachingAssignment> assignment,
                                      TeachingAssignment value,
                                      double diffRoomWeight,
                                      double diffTypeWeight)

      Compute number of same days assignments (weighted by the preference) of the given teaching assignment and the other assignments of the instructor
      Parameters:
        `assignment` - current assignment
        `value` - teaching assignment that is being considered
        `diffRoomWeight` - different room penalty
        `diffTypeWeight` - different instructional type penalty
      Returns:
        weighted same days preference, using `TeachingRequest.countSameDays(TeachingRequest, double, double)`

    - #### countSameRooms

          public double countSameRooms(Assignment<TeachingRequest.Variable,TeachingAssignment> assignment,
                                       TeachingAssignment value,
                                       double diffTypeWeight)

      Compute number of same room assignments (weighted by the preference) of the given teaching assignment and the other assignments of the instructor
      Parameters:
        `assignment` - current assignment
        `value` - teaching assignment that is being considered
        `diffTypeWeight` - different instructional type penalty
      Returns:
        weighted same room preference, using `TeachingRequest.countSameRooms(TeachingRequest, double)`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### createAssignmentContext

          public Instructor.Context createAssignmentContext(Assignment<TeachingRequest.Variable,TeachingAssignment> assignment)

      Description copied from interface: `HasAssignmentContext`
      Create a new assignment context for the given assignment. If there are already some variables assigned in the value, the method should make sure that the context is appropriately initialized.
      Specified by:
        `createAssignmentContext` in interface `HasAssignmentContext<TeachingRequest.Variable,TeachingAssignment,Instructor.Context>`
      Parameters:
        `assignment` - an assignment for which there needs to be an assignment context
      Returns:
        a new instance of the assignment context, filled according to the given assignment

    - #### inheritAssignmentContext

          public Instructor.Context inheritAssignmentContext(Assignment<TeachingRequest.Variable,TeachingAssignment> assignment,
                                                             Instructor.Context parentContext)

      Description copied from interface: `CanInheritContext`
      Create a new assignment context for the given assignment. This method can be used to clone the parent context if desired.
      Specified by:
        `inheritAssignmentContext` in interface `CanInheritContext<TeachingRequest.Variable,TeachingAssignment,Instructor.Context>`
      Parameters:
        `assignment` - an assignment for which there needs to be an assignment context
        `parentContext` - context of the parent assignment
      Returns:
        a new instance of the assignment context, filled according to the given assignment

    - #### hasDistributions

          public boolean hasDistributions()

      Check if the instructor has any distributions

    - #### addDistribution

          public GroupConstraint.Distribution addDistribution(String reference,
                                                              String preference,
                                                              String name)

      Add a distribution preference, returns null if there is no match.

    - #### getDistributions

          public List<GroupConstraint.Distribution> getDistributions()

      Return all distribution preferences for an instructor