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}