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}