    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}