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    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     * Number of assigned variables in this assignment.
097     * Replacement for {@link Model#nrAssignedVariables()}.
098     * @return number of assigned variables in this assignment
099     **/
100    public int nrAssignedVariables();
101    
102    /**
103     * The list of assigned variables in the assignment. That is all the variables that {@link Assignment#getValue(Variable)} is not null in this assignment.
104     * Replacement for {@link Model#assignedVariables()}.
105     * @return a collection of assigned variable in this assignment
106     **/
107    public Collection<V> assignedVariables();
108
109    /**
110     * The list of assigned values in the assignment. That is a collection of {@link Assignment#getValue(Variable)} for all assigned variables in this assignment.
111     * @return a collection of assigned values in this assignment
112     **/
113    public Collection<T> assignedValues();
114    
115    /**
116     * Number of assigned variables in the assignment.
117     * Replacement for {@link Model#nrUnassignedVariables()}.
118     * @param model existing model (the assignment does not keep track about all existing variables, that is what the {@link Model#variables()} is for)
119     * @return number of not assigned variables in this assignment
120     **/
121    public int nrUnassignedVariables(Model<V, T> model);
122
123    /**
124     * 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.
125     * Replacement for {@link Model#unassignedVariables()}
126     * @param model existing model (the assignment does not keep track about all existing variables, that is what the {@link Model#variables()} is for)
127     * @return a collection of all not assigned variables in this assignment
128     **/
129    public Collection<V> unassignedVariables(Model<V, T> model);
130
131    /**
132     * Assignment context for a reference. This can be used to keep assignment dependent computations (e.g., see {@link ConstraintWithContext}).
133     * @param reference a reference (which can be stored within the model, e.g., as an instance variable of a constraint)
134     * @param <C> assignment context type
135     * @return an {@link AssignmentContext}
136     **/
137    public <C extends AssignmentContext> C getAssignmentContext(AssignmentContextReference<V, T, C> reference);
138    
139    /**
140     * Clear an assignment context that is associated with the given a reference. If there is any created for the reference.
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     **/
144    public <C extends AssignmentContext> void clearContext(AssignmentContextReference<V, T, C> reference);
145}