org.cpsolver.ifs.criteria.Criterion Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of cpsolver Show documentation
Show all versions of cpsolver Show documentation
The constraint solver library contains a local search based framework that allows
modeling of a problem using constraint programming primitives (variables, values, constraints).
package org.cpsolver.ifs.criteria;
import java.util.Collection;
import java.util.Set;
import org.cpsolver.ifs.assignment.Assignment;
import org.cpsolver.ifs.model.ExtendedInfoProvider;
import org.cpsolver.ifs.model.Model;
import org.cpsolver.ifs.model.ModelListener;
import org.cpsolver.ifs.model.Value;
import org.cpsolver.ifs.model.Variable;
import org.cpsolver.ifs.util.DataProperties;
/**
* Criterion.
*
* An optimization objective can be split into several (optimization) criteria
* and modeled as a weighted sum of these. This makes the implementation of a particular problem
* more versatile as it allows for an easier modification of the optimization objective.
*
* @version IFS 1.3 (Iterative Forward Search)
* Copyright (C) 2006 - 2014 Tomas Muller
* [email protected]
* http://muller.unitime.org
*
* This library is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 3 of the
* License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not see
* http://www.gnu.org/licenses/.
* @param Variable
* @param Value
*/
public interface Criterion, T extends Value> extends ModelListener, ExtendedInfoProvider {
/** called when the criterion is added to a model
* @param model problem model
**/
public void setModel(Model model);
/** Current value of the criterion (optimization objective)
* @param assignment current assignment
* @return value of this criterion
**/
public double getValue(Assignment assignment);
/**
* Weighted value of the objectives.
* Use {@link Criterion#getWeightedValue(Assignment)} instead.
* @return weighted value of this criterion
**/
@Deprecated
public double getWeightedValue();
/** Weighted value of the objectives
* @param assignment current assignment
* @return weighted value of this criterion
**/
public double getWeightedValue(Assignment assignment);
/**
* Bounds (minimum and maximum) estimate for the value.
* Use {@link Criterion#getBounds(Assignment)} instead.
* @return minimum and maximum of the criterion value
**/
@Deprecated
public double[] getBounds();
/** Bounds (minimum and maximum) estimate for the value
* @param assignment current assignment
* @return minimum and maximum of the criterion value
**/
public double[] getBounds(Assignment assignment);
/** Weighted best value of the objective (value in the best solution).
* @return weighted value of this criterion in the best solution
**/
public double getWeightedBest();
/** Best value (value of the criterion in the best solution)
* @return value of this criterion in the best solution
**/
public double getBest();
/** Weight of the criterion
* @return criterion weight
**/
public double getWeight();
/**
* Weighted value of a proposed assignment (including hard conflicts).
* Use {@link Criterion#getWeightedValue(Assignment, Value, Set)} instead.
* @param value given value
* @param conflicts values conflicting with the given value
* @return weighted change in this criterion value when assigned
**/
@Deprecated
public double getWeightedValue(T value, Set conflicts);
/** Weighted value of a proposed assignment (including hard conflicts)
* @param assignment current assignment
* @param value given value
* @param conflicts values conflicting with the given value
* @return weighted change in this criterion value when assigned
**/
public double getWeightedValue(Assignment assignment, T value, Set conflicts);
/**
* Value of a proposed assignment (including hard conflicts).
* Use {@link Criterion#getValue(Assignment, Value, Set)} instead.
* @param value given value
* @param conflicts values conflicting with the given value
* @return change in this criterion value when assigned
**/
@Deprecated
public double getValue(T value, Set conflicts);
/** Value of a proposed assignment (including hard conflicts)
* @param assignment current assignment
* @param value given value
* @param conflicts values conflicting with the given value
* @return change in this criterion value when assigned
**/
public double getValue(Assignment assignment, T value, Set conflicts);
/**
* Weighted value of a part of the problem (given by the collection of variables)
* Use {@link Criterion#getWeightedValue(Assignment, Collection)} instead.
* @param variables list of problem variables
* @return weighted value of the given variables
**/
@Deprecated
public double getWeightedValue(Collection variables);
/** Weighted value of a part of the problem (given by the collection of variables)
* @param assignment current assignment
* @param variables list of problem variables
* @return weighted value of the given variables
**/
public double getWeightedValue(Assignment assignment, Collection variables);
/**
* Value of a part of the problem (given by the collection of variables).
* Use {@link Criterion#getValue(Assignment, Collection)} instead.
* @param variables list of problem variables
* @return value of the given variables
**/
@Deprecated
public double getValue(Collection variables);
/** Value of a part of the problem (given by the collection of variables)
* @param assignment current assignment
* @param variables list of problem variables
* @return value of the given variables
**/
public double getValue(Assignment assignment, Collection variables);
/**
* Value bounds (minimum and maximum) of the criterion on a part of the problem.
* Use {@link Criterion#getBounds(Assignment, Collection)} instead.
* @param variables list of problem variables
* @return minimum and maximum of this criterion for the given sub-problem
**/
@Deprecated
public double[] getBounds(Collection variables);
/** Value bounds (minimum and maximum) of the criterion on a part of the problem
* @param assignment current assignment
* @param variables list of problem variables
* @return minimum and maximum of this criterion for the given sub-problem
**/
public double[] getBounds(Assignment assignment, Collection variables);
/** Criterion name
* @return name
**/
public String getName();
/**
* Outside update of the criterion (usefull when the criterion is driven by a set of constraints).
* Use {@link Criterion#inc(Assignment, double)} instead.
* @param value increment criterion by this value
**/
@Deprecated
public void inc(double value);
/** Outside update of the criterion (usefull when the criterion is driven by a set of constraints).
* @param assignment current assignment
* @param value increment criterion by this value
**/
public void inc(Assignment assignment, double value);
/** Notification that the current solution has been saved to the best.
* @param assignment current assignment
**/
public void bestSaved(Assignment assignment);
/** Notification that the current solution has been restored from the best.
* @param assignment current assignment
**/
public void bestRestored(Assignment assignment);
/**
* Simple text representation of the criterion and its value. E.g., X:x where X is the {@link AbstractCriterion#getAbbreviation()}
* and x is the current value {@link AbstractCriterion#getValue(Assignment)}.
* @param assignment current assignment
* @return short string representation (e.g., PP:95% for period preference)
*/
public String toString(Assignment assignment);
/**
* Configure the criterion if needed
* @param properties configuration
*/
public void configure(DataProperties properties);
}