001    package ifs.perturbations;
002    
003    import ifs.solution.Solution;
004    import ifs.solver.Solver;
005    import ifs.model.*;
006    import java.util.*;
007    
008    /**
009     * Counter of perturbation penalty (minimal perturbation problem).
010     * <br><br>
011     * Many real-life problems are dynamic, with changes in the problem definition occurring after a solution to the initial 
012     * formulation has been reached. A minimal perturbation problem incorporates these changes, along with the initial 
013     * solution, as a new problem whose solution must be as close as possible to the initial solution. The iterative forward 
014     * search algorithm is also made to solve minimal perturbation problems. 
015     * <br><br>
016     * To define the minimal perturbation problem, we will consider an initial (original) problem, its solution, a new 
017     * problem, and some distance function which allows us to compare solutions of the initial and the new problem. 
018     * Subsequently we look for a solution of the new problem with minimal distance from the initial solution. This
019     * distance is expressed by this PerturbationCounter
020     *
021     * @see Solver
022     * @see Solution
023     * @see Variable
024     *
025     * @author <a href="mailto:muller@ktiml.mff.cuni.cz">Tomáš Müller</a>
026     * @version 1.0
027     */
028    public interface PerturbationsCounter {
029        /** Initialization */
030        public void init(Solver solver);
031        
032        /** Returns perturbation penalty, i.e., the distance between current solution and the solution of the initial 
033         * problem (see {@link Variable#getInitialAssignment()}).
034         * @param solution current solution
035         */
036        public double getPerturbationPenalty(Solution solution);
037        
038        /** Returns perturbation penalty of the solution which become from the current solution when given conflicting 
039         * values are unassigned and the selected value is assigned. Since this penalty is used for comparison of 
040         * different candidate values in the value selection criterion, it is fully acceptable to just return a difference
041         * between current and the altered solution (which might be easied for computation that the whole perturbation penalty).
042         * @param solution current solution
043         * @param selectedValue value to be selected in the next iteration
044         * @param conflicts conflicting values to be unassigned in the next iteration
045         */
046        public double getPerturbationPenalty(Solution solution, Value selectedValue, Collection conflicts);
047        
048        /** Some (perturbation) information about the solution might be returned here.
049         * @param info resultant info table
050         * @param solution current solution
051         */
052        public void getInfo(Dictionary info, Solution solution);
053    }