org.cpsolver.exam.criteria

## Class DistributionPenalty

- java.lang.Object
- - org.cpsolver.ifs.criteria.AbstractCriterion<Exam,ExamPlacement>
  - - org.cpsolver.exam.criteria.ExamCriterion
    - - org.cpsolver.exam.criteria.DistributionPenalty

- All Implemented Interfaces:
    CanHoldContext, HasAssignmentContext<Exam,ExamPlacement,AbstractCriterion.ValueContext>, Criterion<Exam,ExamPlacement>, ExtendedInfoProvider<Exam,ExamPlacement>, InfoProvider<Exam,ExamPlacement>, ModelListener<Exam,ExamPlacement>

      public class DistributionPenalty
      extends ExamCriterion

  Distribution penalty. I.e., sum weights of violated distribution constraints.
  A weight of violated distribution soft constraints (see `ExamDistributionConstraint`) can be set by problem property Exams.RoomDistributionWeight, or in the input xml file, property roomDistributionWeight.
  Version:
    ExamTT 1.3 (Examination Timetabling)
    Copyright (C) 2008 - 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

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.cpsolver.ifs.criteria.AbstractCriterion

      `AbstractCriterion.ValueContext, AbstractCriterion.ValueUpdateType`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Integer` | `iSoftDistributions`

    - ### Fields inherited from class org.cpsolver.ifs.criteria.AbstractCriterion

      `iBest, iDebug, iWeight, sDoubleFormat, sPercentFormat`

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

      `sMaxSize`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DistributionPenalty()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected double[]` | `computeBounds(Assignment<Exam,ExamPlacement> assignment)` Compute bounds (bounds are being cached by default).
    `double` | `getPeriodValue(Assignment<Exam,ExamPlacement> assignment, ExamPlacement value)` Period related distribution penalty, i.e., sum weights of violated distribution constraints
    `double` | `getRoomValue(Assignment<Exam,ExamPlacement> assignment, ExamPlacement value)` Room related distribution penalty, i.e., sum weights of violated distribution constraints
    `double` | `getValue(Assignment<Exam,ExamPlacement> assignment, Collection<Exam> variables)` Value of a part of the problem (given by the collection of variables)
    `double` | `getValue(Assignment<Exam,ExamPlacement> assignment, ExamPlacement value, Set<ExamPlacement> conflicts)` Value of a proposed assignment (including hard conflicts)
    `double` | `getWeightDefault(DataProperties config)` Defines default weight (when `AbstractCriterion.getWeightName()` parameter is not present in the criterion).
    `String` | `getWeightName()` Defines weight name (to be used to get the criterion weight from the configuration).
    `String` | `getXmlWeightName()` Name of the weight parameter in the parameters section of the examination XML file.
    `void` | `inc(Assignment<Exam,ExamPlacement> assignment, double value, ExamDistributionConstraint dc)`
    `boolean` | `isPeriodCriterion()` True if this criterion is based on period assignment.
    `boolean` | `isRoomCriterion()` True if this criterion is based on room assignment.
    `void` | `setModel(Model<Exam,ExamPlacement> model)` called when the criterion is added to a model
    `String` | `toString(Assignment<Exam,ExamPlacement> assignment)` Simple text representation of the criterion and its value.

    - ### Methods inherited from class org.cpsolver.exam.criteria.ExamCriterion

      `getBounds, getInfo, getXmlParameters, setWeight, setXmlParameters`

    - ### Methods inherited from class org.cpsolver.ifs.criteria.AbstractCriterion

      `afterAssigned, afterUnassigned, beforeAssigned, beforeUnassigned, bestRestored, bestSaved, clearCache, configure, constraintAdded, constraintRemoved, createAssignmentContext, getAbbreviation, getAssignmentContextReference, getBest, getBounds, getBounds, getBounds, getContext, getContext, getExtendedInfo, getInfo, getModel, getName, getPerc, getPercentage, getPercRev, getValue, getValue, getValue, getValueUpdateType, getWeight, getWeightedBest, getWeightedValue, getWeightedValue, getWeightedValue, getWeightedValue, getWeightedValue, getWeightedValue, inc, inc, init, setAssignmentContextReference, setValueUpdateType, variableAdded, variableRemoved`

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

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

- - ### Field Detail

    - #### iSoftDistributions

          protected Integer iSoftDistributions

  - ### Constructor Detail

    - #### DistributionPenalty

          public DistributionPenalty()

  - ### Method Detail

    - #### setModel

          public void setModel(Model<Exam,ExamPlacement> model)

      Description copied from interface: `Criterion`
      called when the criterion is added to a model
      Specified by:
        `setModel` in interface `Criterion<Exam,ExamPlacement>`
      Overrides:
        `setModel` in class `AbstractCriterion<Exam,ExamPlacement>`
      Parameters:
        `model` - problem model

    - #### getWeightName

          public String getWeightName()

      Description copied from class: `AbstractCriterion`
      Defines weight name (to be used to get the criterion weight from the configuration).
      Overrides:
        `getWeightName` in class `ExamCriterion`
      Returns:
        name of the weight associated with this criterion

    - #### getXmlWeightName

          public String getXmlWeightName()

      Description copied from class: `ExamCriterion`
      Name of the weight parameter in the parameters section of the examination XML file.
      Overrides:
        `getXmlWeightName` in class `ExamCriterion`
      Returns:
        name of the weight parameter in the XML

    - #### getWeightDefault

          public double getWeightDefault(DataProperties config)

      Description copied from class: `AbstractCriterion`
      Defines default weight (when `AbstractCriterion.getWeightName()` parameter is not present in the criterion).
      Overrides:
        `getWeightDefault` in class `AbstractCriterion<Exam,ExamPlacement>`
      Parameters:
        `config` - solver configuration
      Returns:
        default criterion weight value

    - #### getValue

          public double getValue(Assignment<Exam,ExamPlacement> assignment,
                                 ExamPlacement value,
                                 Set<ExamPlacement> conflicts)

      Description copied from interface: `Criterion`
      Value of a proposed assignment (including hard conflicts)
      Parameters:
        `assignment` - current assignment
        `value` - given value
        `conflicts` - values conflicting with the given value
      Returns:
        change in this criterion value when assigned

    - #### isRoomCriterion

          public boolean isRoomCriterion()

      Description copied from class: `ExamCriterion`
      True if this criterion is based on room assignment. Used by `ExamPlacement.getRoomCost(Assignment)`.
      Overrides:
        `isRoomCriterion` in class `ExamCriterion`
      Returns:
        true if this criterion is based on room assignment

    - #### getRoomValue

          public double getRoomValue(Assignment<Exam,ExamPlacement> assignment,
                                     ExamPlacement value)

      Room related distribution penalty, i.e., sum weights of violated distribution constraints
      Overrides:
        `getRoomValue` in class `ExamCriterion`
      Parameters:
        `assignment` - current assignment
        `value` - new assignment in question
      Returns:
        change in the room preference value

    - #### getValue

          public double getValue(Assignment<Exam,ExamPlacement> assignment,
                                 Collection<Exam> variables)

      Description copied from interface: `Criterion`
      Value of a part of the problem (given by the collection of variables)
      Specified by:
        `getValue` in interface `Criterion<Exam,ExamPlacement>`
      Overrides:
        `getValue` in class `AbstractCriterion<Exam,ExamPlacement>`
      Parameters:
        `assignment` - current assignment
        `variables` - list of problem variables
      Returns:
        value of the given variables

    - #### isPeriodCriterion

          public boolean isPeriodCriterion()

      Description copied from class: `ExamCriterion`
      True if this criterion is based on period assignment. Used by `ExamPlacement.getTimeCost(Assignment)`.
      Overrides:
        `isPeriodCriterion` in class `ExamCriterion`
      Returns:
        true if this criterion is based on period assignment

    - #### inc

          public void inc(Assignment<Exam,ExamPlacement> assignment,
                          double value,
                          ExamDistributionConstraint dc)

    - #### getPeriodValue

          public double getPeriodValue(Assignment<Exam,ExamPlacement> assignment,
                                       ExamPlacement value)

      Period related distribution penalty, i.e., sum weights of violated distribution constraints
      Overrides:
        `getPeriodValue` in class `ExamCriterion`
      Parameters:
        `assignment` - current assignment
        `value` - new assignment in question
      Returns:
        change in the period preference value

    - #### computeBounds

          protected double[] computeBounds(Assignment<Exam,ExamPlacement> assignment)

      Description copied from class: `AbstractCriterion`
      Compute bounds (bounds are being cached by default).
      Overrides:
        `computeBounds` in class `AbstractCriterion<Exam,ExamPlacement>`
      Parameters:
        `assignment` - current assignment
      Returns:
        minimum and maximum of this criterion's value

    - #### toString

          public String toString(Assignment<Exam,ExamPlacement> assignment)

      Description copied from class: `AbstractCriterion`
      Simple text representation of the criterion and its value. E.g., X:x where X is the `AbstractCriterion.getAbbreviation()` and x is the current value `AbstractCriterion.getValue(Assignment)`.
      Specified by:
        `toString` in interface `Criterion<Exam,ExamPlacement>`
      Overrides:
        `toString` in class `AbstractCriterion<Exam,ExamPlacement>`
      Parameters:
        `assignment` - current assignment
      Returns:
        short string representation (e.g., PP:95% for period preference)