org.cpsolver.ifs.perturbations

## Class DefaultPerturbationsCounter<V extends Variable<V,T>,T extends Value<V,T>>

- java.lang.Object
- - org.cpsolver.ifs.perturbations.DefaultPerturbationsCounter<V,T>

- Type Parameters:
    `V` - Variable
    `T` - Value
  All Implemented Interfaces:
    PerturbationsCounter<V,T>
  Direct Known Subclasses:
    UniversalPerturbationsCounter

      public class DefaultPerturbationsCounter<V extends Variable<V,T>,T extends Value<V,T>>
      extends Object
      implements PerturbationsCounter<V,T>

  Default computation of perturbation penalty (minimal perturbation problem).
  A distance function can be defined with the help of perturbations. A perturbation is a variable that has a different value in the solutions of the initial and the new problem. Some perturbations must be present in each new solution. So called input perturbation means that a variable must have different values in the initial and changed problem because of some input changes (e.g., a course must be scheduled at a different time in the changed problem). The distance function can be defined as the number of additional perturbations. They are given by subtraction of the final number of perturbations and the number of input perturbations (variables without initial assignments).
  This implementation is easily extendable. It disassemble all the available cases into a comparison of the initial and the assigned value different each other. So, the only method which is needed to be changed is `getPenalty(Assignment, Value, Value)`. Its current implementation is:

       protected double getPenalty(Value assignedValue, Value initialValue) {
           return 1.0;
       }

  It is called only when assignedValue is different to initialValue.
  Version:
    IFS 1.3 (Iterative Forward Search)
    Copyright (C) 2006 - 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/.
  See Also:
    `Solver`, `Solution`, `Variable`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static DecimalFormat` | `sDoubleFormat`

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `getInfo(Assignment<V,T> assignment, Model<V,T> model, Map<String,String> info)` Some (perturbation) information about the solution might be returned here.
    `void` | `getInfo(Assignment<V,T> assignment, Model<V,T> model, Map<String,String> info, Collection<V> variables)` Some (perturbation) information about the solution might be returned here (only include variables from the given set).
    `protected double` | `getPenalty(Assignment<V,T> assignment, T assignedValue, T initialValue)` Computes perturbation penalty between assigned and initial value of the same lecture.
    `protected double` | `getPenaltyA(Assignment<V,T> assignment, T selectedValue, T initialValue)` Case A: initial value of a different unassigned variable cannot be assigned (computed by `ViolatedInitials`)
    `protected double` | `getPenaltyB(Assignment<V,T> assignment, T selectedValue, T assignedValue, T initialValue)` Case B: initial value is unassigned from a conflicting variable.
    `protected double` | `getPenaltyC(Assignment<V,T> assignment, T selectedValue, T assignedValue, T initialValue)` Case C: non-initial value is unassigned from a conflicting variable.
    `protected double` | `getPenaltyD(Assignment<V,T> assignment, T selectedValue, T initialValue)` Case D: different than initial value is assigned to the variable
    `double` | `getPerturbationPenalty(Assignment<V,T> assignment, Model<V,T> model)` Returns perturbation penalty, i.e., the distance between current solution and the solution of the initial problem (see `Variable.getInitialAssignment()`).
    `double` | `getPerturbationPenalty(Assignment<V,T> assignment, Model<V,T> model, Collection<V> variables)` Returns perturbation penalty, i.e., the distance between current solution and the solution of the initial (only include variables from the given set) problem (see `Variable.getInitialAssignment()`).
    `double` | `getPerturbationPenalty(Assignment<V,T> assignment, Model<V,T> model, T selectedValue, Collection<T> conflicts)` Returns perturbation penalty of the solution which become from the current solution when given conflicting values are unassigned and the selected value is assigned.
    `protected ViolatedInitials<V,T>` | `getViolatedInitials()`
    `void` | `init(Solver<V,T> solver)` Initialization

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

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

- - ### Field Detail

    - #### sDoubleFormat

          protected static DecimalFormat sDoubleFormat

  - ### Constructor Detail

    - #### DefaultPerturbationsCounter

          public DefaultPerturbationsCounter(DataProperties properties)

      Constructor
      Parameters:
        `properties` - input configuration

  - ### Method Detail

    - #### init

          public void init(Solver<V,T> solver)

      Initialization
      Specified by:
        `init` in interface `PerturbationsCounter<V extends Variable<V,T>,T extends Value<V,T>>`
      Parameters:
        `solver` - current solver

    - #### getPerturbationPenalty

          public double getPerturbationPenalty(Assignment<V,T> assignment,
                                               Model<V,T> model)

      Description copied from interface: `PerturbationsCounter`
      Returns perturbation penalty, i.e., the distance between current solution and the solution of the initial problem (see `Variable.getInitialAssignment()`).
      Specified by:
        `getPerturbationPenalty` in interface `PerturbationsCounter<V extends Variable<V,T>,T extends Value<V,T>>`
      Parameters:
        `assignment` - current assignment
        `model` - current model
      Returns:
        penalty

    - #### getPerturbationPenalty

          public double getPerturbationPenalty(Assignment<V,T> assignment,
                                               Model<V,T> model,
                                               Collection<V> variables)

      Description copied from interface: `PerturbationsCounter`
      Returns perturbation penalty, i.e., the distance between current solution and the solution of the initial (only include variables from the given set) problem (see `Variable.getInitialAssignment()`).
      Specified by:
        `getPerturbationPenalty` in interface `PerturbationsCounter<V extends Variable<V,T>,T extends Value<V,T>>`
      Parameters:
        `assignment` - current assignment
        `model` - current model
        `variables` - sub-problem
      Returns:
        penalty

    - #### getViolatedInitials

          protected ViolatedInitials<V,T> getViolatedInitials()

    - #### getPenalty

          protected double getPenalty(Assignment<V,T> assignment,
                                      T assignedValue,
                                      T initialValue)

      Computes perturbation penalty between assigned and initial value of the same lecture. It is called only when assignedValue is different to initialValue.
      Parameters:
        `assignment` - current assignment
        `assignedValue` - value assigned to a varuable (null when variable is unassigned)
        `initialValue` - initial value of the same varaible (always not null)
      Returns:
        penalty

    - #### getPenaltyA

          protected double getPenaltyA(Assignment<V,T> assignment,
                                       T selectedValue,
                                       T initialValue)

      Case A: initial value of a different unassigned variable cannot be assigned (computed by `ViolatedInitials`)
      Parameters:
        `assignment` - current assignment
        `selectedValue` - value which is going to be assigned to its variable
        `initialValue` - value of a different variable, which is currently assigned but which need to be unassifned Different variable, which is unassigned and whose initial value is in conflict with the selected value.
      Returns:
        penalty

    - #### getPenaltyB

          protected double getPenaltyB(Assignment<V,T> assignment,
                                       T selectedValue,
                                       T assignedValue,
                                       T initialValue)

      Case B: initial value is unassigned from a conflicting variable.
      Parameters:
        `assignment` - current assignment
        `selectedValue` - value which is going to be unassigned to its variable
        `assignedValue` - value currently assigned to a conflicting variable (different from the one of selectedVariable)
        `initialValue` - initial value of the conflicting variable of assignedValue
      Returns:
        penalty

    - #### getPenaltyC

          protected double getPenaltyC(Assignment<V,T> assignment,
                                       T selectedValue,
                                       T assignedValue,
                                       T initialValue)

      Case C: non-initial value is unassigned from a conflicting variable.
      Parameters:
        `assignment` - current assignment
        `selectedValue` - value which is going to be unassigned to its variable
        `assignedValue` - value currently assigned to a conflicting variable (different from the one of selectedVariable)
        `initialValue` - initial value of the conflicting variable of assignedValue
      Returns:
        penalty

    - #### getPenaltyD

          protected double getPenaltyD(Assignment<V,T> assignment,
                                       T selectedValue,
                                       T initialValue)

      Case D: different than initial value is assigned to the variable
      Parameters:
        `assignment` - current assignment
        `selectedValue` - value which is going to be unassigned to its variable
        `initialValue` - initial value of the same variable
      Returns:
        penalty

    - #### getPerturbationPenalty

          public double getPerturbationPenalty(Assignment<V,T> assignment,
                                               Model<V,T> model,
                                               T selectedValue,
                                               Collection<T> conflicts)

      Description copied from interface: `PerturbationsCounter`
      Returns perturbation penalty of the solution which become from the current solution when given conflicting values are unassigned and the selected value is assigned. Since this penalty is used for comparison of different candidate values in the value selection criterion, it is fully acceptable to just return a difference between current and the altered solution (which might be easied for computation that the whole perturbation penalty).
      Specified by:
        `getPerturbationPenalty` in interface `PerturbationsCounter<V extends Variable<V,T>,T extends Value<V,T>>`
      Parameters:
        `assignment` - current assignment
        `model` - current model
        `selectedValue` - value to be selected in the next iteration
        `conflicts` - conflicting values to be unassigned in the next iteration
      Returns:
        penalty

    - #### getInfo

          public void getInfo(Assignment<V,T> assignment,
                              Model<V,T> model,
                              Map<String,String> info)

      Description copied from interface: `PerturbationsCounter`
      Some (perturbation) information about the solution might be returned here.
      Specified by:
        `getInfo` in interface `PerturbationsCounter<V extends Variable<V,T>,T extends Value<V,T>>`
      Parameters:
        `assignment` - current assignment
        `model` - current model
        `info` - resultant info table

    - #### getInfo

          public void getInfo(Assignment<V,T> assignment,
                              Model<V,T> model,
                              Map<String,String> info,
                              Collection<V> variables)

      Description copied from interface: `PerturbationsCounter`
      Some (perturbation) information about the solution might be returned here (only include variables from the given set).
      Specified by:
        `getInfo` in interface `PerturbationsCounter<V extends Variable<V,T>,T extends Value<V,T>>`
      Parameters:
        `assignment` - current assignment
        `model` - current model
        `info` - resultant info table
        `variables` - sub-problem