    001package org.cpsolver.ifs.criteria;
    002
    003import java.util.Collection;
    004import java.util.Set;
    005
    006import org.cpsolver.ifs.assignment.Assignment;
    007import org.cpsolver.ifs.model.ExtendedInfoProvider;
    008import org.cpsolver.ifs.model.Model;
    009import org.cpsolver.ifs.model.ModelListener;
    010import org.cpsolver.ifs.model.Value;
    011import org.cpsolver.ifs.model.Variable;
    012import org.cpsolver.ifs.util.DataProperties;
    013
    014
    015/**
    016 * Criterion. <br>
    017 * <br>
    018 * An optimization objective can be split into several (optimization) criteria
    019 * and modeled as a weighted sum of these. This makes the implementation of a particular problem
    020 * more versatile as it allows for an easier modification of the optimization objective.
    021 *
    022 * @version IFS 1.3 (Iterative Forward Search)<br>
    023 *          Copyright (C) 2006 - 2014 Tomáš Müller<br>
    024 *          <a href="mailto:muller@unitime.org">muller@unitime.org</a><br>
    025 *          <a href="http://muller.unitime.org">http://muller.unitime.org</a><br>
    026 * <br>
    027 *          This library is free software; you can redistribute it and/or modify
    028 *          it under the terms of the GNU Lesser General Public License as
    029 *          published by the Free Software Foundation; either version 3 of the
    030 *          License, or (at your option) any later version. <br>
    031 * <br>
    032 *          This library is distributed in the hope that it will be useful, but
    033 *          WITHOUT ANY WARRANTY; without even the implied warranty of
    034 *          MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
    035 *          Lesser General Public License for more details. <br>
    036 * <br>
    037 *          You should have received a copy of the GNU Lesser General Public
    038 *          License along with this library; if not see
    039 *          <a href='http://www.gnu.org/licenses/'>http://www.gnu.org/licenses/</a>.
    040 * @param <V> Variable
    041 * @param <T> Value
    042 */
    043public interface Criterion<V extends Variable<V, T>, T extends Value<V, T>> extends ModelListener<V, T>, ExtendedInfoProvider<V, T> {
    044
    045    /** called when the criterion is added to a model
    046     * @param model problem model
    047     **/
    048    public void setModel(Model<V,T> model);
    049
    050    /** Current value of the criterion (optimization objective)
    051     * @param assignment current assignment
    052     * @return value of this criterion
    053     **/
    054    public double getValue(Assignment<V, T> assignment);
    055
    056    /**
    057     * Weighted value of the objectives.
    058     * Use {@link Criterion#getWeightedValue(Assignment)} instead.
    059     * @return weighted value of this criterion
    060     **/
    061    @Deprecated
    062    public double getWeightedValue();
    063
    064    /** Weighted value of the objectives
    065     * @param assignment current assignment
    066     * @return weighted value of this criterion
    067     **/
    068    public double getWeightedValue(Assignment<V, T> assignment);
    069
    070    /**
    071     * Bounds (minimum and maximum) estimate for the value.
    072     * Use {@link Criterion#getBounds(Assignment)} instead.
    073     * @return minimum and maximum of the criterion value
    074     **/
    075    @Deprecated
    076    public double[] getBounds();
    077
    078    /** Bounds (minimum and maximum) estimate for the value
    079     * @param assignment current assignment
    080     * @return minimum and maximum of the criterion value
    081     **/
    082    public double[] getBounds(Assignment<V, T> assignment);
    083
    084    /** Weighted best value of the objective (value in the best solution).
    085     * @return weighted value of this criterion in the best solution
    086     **/
    087    public double getWeightedBest();
    088
    089    /** Best value (value of the criterion in the best solution)
    090     * @return value of this criterion in the best solution
    091     **/
    092    public double getBest();
    093
    094    /** Weight of the criterion
    095     * @return criterion weight
    096     **/
    097    public double getWeight();
    098
    099    /**
    100     * Weighted value of a proposed assignment (including hard conflicts).
    101     * Use {@link Criterion#getWeightedValue(Assignment, Value, Set)} instead.
    102     * @param value given value
    103     * @param conflicts values conflicting with the given value
    104     * @return weighted change in this criterion value when assigned
    105     **/
    106    @Deprecated
    107    public double getWeightedValue(T value, Set<T> conflicts);
    108
    109    /** Weighted value of a proposed assignment (including hard conflicts)
    110     * @param assignment current assignment
    111     * @param value given value
    112     * @param conflicts values conflicting with the given value
    113     * @return weighted change in this criterion value when assigned
    114     **/
    115    public double getWeightedValue(Assignment<V, T> assignment, T value, Set<T> conflicts);
    116
    117    /**
    118     * Value of a proposed assignment (including hard conflicts).
    119     * Use {@link Criterion#getValue(Assignment, Value, Set)} instead.
    120     * @param value given value
    121     * @param conflicts values conflicting with the given value
    122     * @return change in this criterion value when assigned
    123     **/
    124    @Deprecated
    125    public double getValue(T value, Set<T> conflicts);
    126
    127    /** Value of a proposed assignment (including hard conflicts)
    128     * @param assignment current assignment
    129     * @param value given value
    130     * @param conflicts values conflicting with the given value
    131     * @return change in this criterion value when assigned
    132     **/
    133    public double getValue(Assignment<V, T> assignment, T value, Set<T> conflicts);
    134
    135    /**
    136     * Weighted value of a part of the problem (given by the collection of variables)
    137     * Use {@link Criterion#getWeightedValue(Assignment, Collection)} instead.
    138     * @param variables list of problem variables
    139     * @return weighted value of the given variables
    140     **/
    141    @Deprecated
    142    public double getWeightedValue(Collection<V> variables);
    143
    144    /** Weighted value of a part of the problem (given by the collection of variables)
    145     * @param assignment current assignment
    146     * @param variables list of problem variables
    147     * @return weighted value of the given variables
    148     **/
    149    public double getWeightedValue(Assignment<V, T> assignment, Collection<V> variables);
    150
    151    /**
    152     * Value of a part of the problem (given by the collection of variables).
    153     * Use {@link Criterion#getValue(Assignment, Collection)} instead.
    154     * @param variables list of problem variables
    155     * @return value of the given variables
    156     **/
    157    @Deprecated
    158    public double getValue(Collection<V> variables);
    159
    160    /** Value of a part of the problem (given by the collection of variables)
    161     * @param assignment current assignment
    162     * @param variables list of problem variables
    163     * @return value of the given variables
    164     **/
    165    public double getValue(Assignment<V, T> assignment, Collection<V> variables);
    166
    167    /**
    168     * Value bounds (minimum and maximum) of the criterion on a part of the problem.
    169     * Use {@link Criterion#getBounds(Assignment, Collection)} instead.
    170     * @param variables list of problem variables
    171     * @return minimum and maximum of this criterion for the given sub-problem
    172     **/
    173    @Deprecated
    174    public double[] getBounds(Collection<V> variables);
    175
    176    /** Value bounds (minimum and maximum) of the criterion on a part of the problem
    177     * @param assignment current assignment
    178     * @param variables list of problem variables
    179     * @return minimum and maximum of this criterion for the given sub-problem
    180     **/
    181    public double[] getBounds(Assignment<V, T> assignment, Collection<V> variables);
    182
    183    /** Criterion name
    184     * @return name
    185     **/
    186    public String getName();
    187
    188    /**
    189     * Outside update of the criterion (usefull when the criterion is driven by a set of constraints).
    190     * Use {@link Criterion#inc(Assignment, double)} instead.
    191     * @param value increment criterion by this value
    192     **/
    193    @Deprecated
    194    public void inc(double value);
    195
    196    /** Outside update of the criterion (usefull when the criterion is driven by a set of constraints).
    197     * @param assignment current assignment
    198     * @param value increment criterion by this value
    199     **/
    200    public void inc(Assignment<V, T> assignment, double value);
    201
    202    /** Notification that the current solution has been saved to the best.
    203     * @param assignment current assignment
    204     **/
    205    public void bestSaved(Assignment<V, T> assignment);
    206
    207    /** Notification that the current solution has been restored from the best.
    208     * @param assignment current assignment
    209     **/
    210    public void bestRestored(Assignment<V, T> assignment);
    211
    212    /**
    213     * Simple text representation of the criterion and its value. E.g., X:x where X is the {@link AbstractCriterion#getAbbreviation()}
    214     * and x is the current value {@link AbstractCriterion#getValue(Assignment)}.
    215     * @param assignment current assignment
    216     * @return short string representation (e.g., PP:95% for period preference)
    217     */
    218    public String toString(Assignment<V, T> assignment);
    219
    220    /**
    221     * Configure the criterion if needed
    222     * @param properties configuration
    223     */
    224    public void configure(DataProperties properties);
    225}