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