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 Tomas Muller<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    @SuppressWarnings("javadoc")
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    @SuppressWarnings("javadoc")
077    public long getIteration(V variable);
078    
079    /**
080     * Assign the given value to its variable.
081     * Replacement for {@link Variable#assign(int, Value)}.
082     * @param iteration current iteration
083     * @param value a new value to be assigned to variable {@link Value#variable()}.
084     * @return previous assignment of the variable, null if it was not assigned
085     **/
086    @SuppressWarnings("javadoc")
087    public T assign(long iteration, T value);
088    
089    /**
090     * Unassign the given variable.
091     * Replacement for {@link Variable#unassign(int)}.
092     * @param iteration current iteration
093     * @param variable variable to be unassigned
094     * @return previous assignment of the variable, null if it was not assigned
095     **/
096    @SuppressWarnings("javadoc")
097    public T unassign(long iteration, V variable);
098    
099    /**
100     * Number of assigned variables in this assignment.
101     * Replacement for {@link Model#nrAssignedVariables()}.
102     * @return number of assigned variables in this assignment
103     **/
104    @SuppressWarnings("javadoc")
105    public int nrAssignedVariables();
106    
107    /**
108     * The list of assigned variables in the assignment. That is all the variables that {@link Assignment#getValue(Variable)} is not null in this assignment.
109     * Replacement for {@link Model#assignedVariables()}.
110     * @return a collection of assigned variable in this assignment
111     **/
112    @SuppressWarnings("javadoc")
113    public Collection<V> assignedVariables();
114
115    /**
116     * The list of assigned values in the assignment. That is a collection of {@link Assignment#getValue(Variable)} for all assigned variables in this assignment.
117     * @return a collection of assigned values in this assignment
118     **/
119    public Collection<T> assignedValues();
120    
121    /**
122     * Number of assigned variables in the assignment.
123     * Replacement for {@link Model#nrUnassignedVariables()}.
124     * @param model existing model (the assignment does not keep track about all existing variables, that is what the {@link Model#variables()} is for)
125     * @return number of not assigned variables in this assignment
126     **/
127    @SuppressWarnings("javadoc")
128    public int nrUnassignedVariables(Model<V, T> model);
129
130    /**
131     * 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.
132     * Replacement for {@link Model#unassignedVariables()}
133     * @param model existing model (the assignment does not keep track about all existing variables, that is what the {@link Model#variables()} is for)
134     * @return a collection of all not assigned variables in this assignment
135     **/
136    @SuppressWarnings("javadoc")
137    public Collection<V> unassignedVariables(Model<V, T> model);
138
139    /**
140     * Assignment context for a reference. This can be used to keep assignment dependent computations (e.g., see {@link ConstraintWithContext}).
141     * @param reference a reference (which can be stored within the model, e.g., as an instance variable of a constraint)
142     * @param <C> assignment context type
143     * @return an {@link AssignmentContext}
144     **/
145    public <C extends AssignmentContext> C getAssignmentContext(AssignmentContextReference<V, T, C> reference);
146    
147    /**
148     * Clear an assignment context that is associated with the given a reference. If there is any created for the reference.
149     * @param reference a reference (which can be stored within the model, e.g., as an instance variable of a constraint)
150     * @param <C> assignment context type
151     **/
152    public <C extends AssignmentContext> void clearContext(AssignmentContextReference<V, T, C> reference);
153}