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