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}