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}