org.jamesframework.core.search.algo.exh.ExhaustiveSearch Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of james-core Show documentation

The James core module is part of the James framework for optimization using local search metaheuristics in Java. The core contains general components to model problems, objectives and constraints, as well as generic algorithms to solve the problems. Moreover, the core provides implementations of specific utilities for subset selection.

There is a newer version: 1.2

Show newest version

//  Copyright 2014 Herman De Beukelaer
//
//  Licensed under the Apache License, Version 2.0 (the "License");
//  you may not use this file except in compliance with the License.
//  You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.

package org.jamesframework.core.search.algo.exh;

import org.jamesframework.core.problems.Problem;
import org.jamesframework.core.problems.solutions.Solution;
import org.jamesframework.core.search.Search;

/**
 * The exhaustive search algorithm evaluates every solution generated by the given solution iterator and selects the best one.
 * By using a solution iterator that generates all possible solutions in the solution space of a specific problem, this algorithm
 * will effectively evaluate every possible solution and is guaranteed to find the optimum. However, it may be very slow in case
 * of a large solution space, which is often the case for practical problems of reasonable size.
 * 
 * When all solutions have been generated and evaluated, the search stops. If the search is stopped before that time, and
 * subsequently restarted, it will not revisited the part of the solution space that had already been explored before,
 * given that its solution iterator has not been modified externally in between both runs.
 * 
 * @param  solution type of the problems that may be solved using this search, required to extend {@link Solution}
 * @author Herman De Beukelaer
 */
public class ExhaustiveSearch extends Search {

    // solution iterator
    private final SolutionIterator solutionIterator;
    
    /**
     * Create an exhaustive search algorithm to solve the given problem, using the given solution iterator to generate
     * possible solutions, with default search name "ExhaustiveSearch". Note that the problem and solution iterator can
     * not be null, else, an exception will be thrown.
     * 
     * @param problem problem to solve
     * @param solutionIterator solution iterator used to generate solutions
     * @throws NullPointerException if problem or solutionIterator are null
     */
    public ExhaustiveSearch(Problem problem, SolutionIterator solutionIterator){
        this(null, problem, solutionIterator);
    }
    
    /**
     * Create an exhaustive search algorithm to solve the given problem, using the given solution iterator to generate
     * possible solutions, with a custom search name. If the given name is null, the default name "ExhaustiveSearch"
     * will be assigned. Note that the problem and solution iterator can not be null, else, an exception will be thrown.
     * 
     * @param name custom search name
     * @param problem problem to solve
     * @param solutionIterator solution iterator used to generate solutions
     * @throws NullPointerException if problem or solutionIterator are null
     */
    public ExhaustiveSearch(String name, Problem problem, SolutionIterator solutionIterator){
        // call super (checks that problem is not null)
        super(name != null ? name : "ExhaustiveSearch", problem);
        // check iterator not null
        if(solutionIterator == null){
            throw new NullPointerException("Error while creating exhaustive search: solution iterator can not be null.");
        }
        // store reference to iterator
        this.solutionIterator = solutionIterator;
    }
    
    /**
     * In every search step it is verified whether there are more solution to be generated using the solution iterator.
     * If so, the next solution is generated, evaluated, and presented for comparison with the current best solution.
     * Else, the search stops.
     */
    @Override
    protected void searchStep() {
        // more solutions to generate ?
        if(solutionIterator.hasNext()){
            // generate next solution
            SolutionType sol = solutionIterator.next();
            // update best solution
            updateBestSolution(sol);
        } else {
            // done
            stop();
        }
    }

}