001package org.cpsolver.ifs.assignment; 002 003import java.util.Collection; 004 005import org.cpsolver.ifs.assignment.context.AssignmentContext; 006import org.cpsolver.ifs.assignment.context.AssignmentContextReference; 007import org.cpsolver.ifs.assignment.context.ConstraintWithContext; 008import org.cpsolver.ifs.assignment.context.NeighbourSelectionWithContext; 009import org.cpsolver.ifs.model.Model; 010import org.cpsolver.ifs.model.Value; 011import org.cpsolver.ifs.model.Variable; 012 013 014/** 015 * An assignment of all the variable of a {@link Model}. This class decouples 016 * an assignment of variables (classes extending {@link Variable}) to their values 017 * (classes extending {@link Value}) from the {@link Model}. This is needed for 018 * any kind of parallel computations, or in general, to be able to hold multiple 019 * different assignments in memory.<br><br> 020 * 021 * This class also include translation of {@link AssignmentContextReference} to 022 * {@link AssignmentContext}, so that each constraint, criterion, neighborhood selection 023 * etc. can hold its own assignment dependent information. See {@link ConstraintWithContext} or 024 * {@link NeighbourSelectionWithContext} for more details. 025 * 026 * @see Variable 027 * @see Value 028 * @see Model 029 * @see AssignmentContext 030 * 031 * @version IFS 1.3 (Iterative Forward Search)<br> 032 * Copyright (C) 2014 Tomáš Müller<br> 033 * <a href="mailto:muller@unitime.org">muller@unitime.org</a><br> 034 * <a href="http://muller.unitime.org">http://muller.unitime.org</a><br> 035 * <br> 036 * This library is free software; you can redistribute it and/or modify 037 * it under the terms of the GNU Lesser General Public License as 038 * published by the Free Software Foundation; either version 3 of the 039 * License, or (at your option) any later version. <br> 040 * <br> 041 * This library is distributed in the hope that it will be useful, but 042 * WITHOUT ANY WARRANTY; without even the implied warranty of 043 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 044 * Lesser General Public License for more details. <br> 045 * <br> 046 * You should have received a copy of the GNU Lesser General Public 047 * License along with this library; if not see <a href='http://www.gnu.org/licenses'>http://www.gnu.org/licenses</a>. 048 * @param <V> Variable 049 * @param <T> Value 050 **/ 051public interface Assignment<V extends Variable<V, T>, T extends Value<V, T>> { 052 053 /** 054 * Assignment index. Unique identification of the assignment, starting with zero. 055 * This can be used to increase the speed of the search by storing individual values on the 056 * variables and an array (indexed by this number). 057 * @return assignment index, -1 if not to be used 058 **/ 059 public int getIndex(); 060 061 /** 062 * Returns assignment of a variable, null if not assigned 063 * Replacement for {@link Variable#getAssignment()}. 064 * @param variable problem variable 065 * @return currently assigned value 066 **/ 067 public T getValue(V variable); 068 069 /** 070 * Returns iteration of the last assignment. 071 * Replacement for {@link Variable#getLastIteration()}. 072 * @param variable problem variable 073 * @return iteration of the last assignment 074 **/ 075 public long getIteration(V variable); 076 077 /** 078 * Assign the given value to its variable. 079 * Replacement for {@link Variable#assign(int, Value)}. 080 * @param iteration current iteration 081 * @param value a new value to be assigned to variable {@link Value#variable()}. 082 * @return previous assignment of the variable, null if it was not assigned 083 **/ 084 public T assign(long iteration, T value); 085 086 /** 087 * Unassign the given variable. 088 * Replacement for {@link Variable#unassign(int)}. 089 * @param iteration current iteration 090 * @param variable variable to be unassigned 091 * @return previous assignment of the variable, null if it was not assigned 092 **/ 093 public T unassign(long iteration, V variable); 094 095 /** 096 * Unassign the given variable, but only if the current assignment differs from the given value. 097 * Replacement for {@link Variable#unassign(int)}. 098 * @param iteration current iteration 099 * @param variable variable to be unassigned 100 * @param value target value 101 * @return previous assignment of the variable, null if it was not assigned 102 **/ 103 public T unassign(long iteration, V variable, T value); 104 105 /** 106 * Number of assigned variables in this assignment. 107 * Replacement for {@link Model#nrAssignedVariables()}. 108 * @return number of assigned variables in this assignment 109 **/ 110 public int nrAssignedVariables(); 111 112 /** 113 * The list of assigned variables in the assignment. That is all the variables that {@link Assignment#getValue(Variable)} is not null in this assignment. 114 * Replacement for {@link Model#assignedVariables()}. 115 * @return a collection of assigned variable in this assignment 116 **/ 117 public Collection<V> assignedVariables(); 118 119 /** 120 * The list of assigned values in the assignment. That is a collection of {@link Assignment#getValue(Variable)} for all assigned variables in this assignment. 121 * @return a collection of assigned values in this assignment 122 **/ 123 public Collection<T> assignedValues(); 124 125 /** 126 * Number of assigned variables in the assignment. 127 * Replacement for {@link Model#nrUnassignedVariables()}. 128 * @param model existing model (the assignment does not keep track about all existing variables, that is what the {@link Model#variables()} is for) 129 * @return number of not assigned variables in this assignment 130 **/ 131 public int nrUnassignedVariables(Model<V, T> model); 132 133 /** 134 * The list of variables of the model that have no value in this assignment. That is all the variables of the model that {@link Assignment#getValue(Variable)} is null in this assignment. 135 * Replacement for {@link Model#unassignedVariables()} 136 * @param model existing model (the assignment does not keep track about all existing variables, that is what the {@link Model#variables()} is for) 137 * @return a collection of all not assigned variables in this assignment 138 **/ 139 public Collection<V> unassignedVariables(Model<V, T> model); 140 141 /** 142 * Assignment context for a reference. This can be used to keep assignment dependent computations (e.g., see {@link ConstraintWithContext}). 143 * @param reference a reference (which can be stored within the model, e.g., as an instance variable of a constraint) 144 * @param <C> assignment context type 145 * @return an {@link AssignmentContext} 146 **/ 147 public <C extends AssignmentContext> C getAssignmentContext(AssignmentContextReference<V, T, C> reference); 148 149 /** 150 * Clear an assignment context that is associated with the given a reference. If there is any created for the reference. 151 * @param reference a reference (which can be stored within the model, e.g., as an instance variable of a constraint) 152 * @param <C> assignment context type 153 **/ 154 public <C extends AssignmentContext> void clearContext(AssignmentContextReference<V, T, C> reference); 155}