    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}