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