org.jamesframework.core.search.stopcriteria.MinDelta 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.stopcriteria;

import org.jamesframework.core.search.Search;

/**
 * Stop criterion that imposes a minimum delta (amount of improvement in evaluation)
 * when finding a new best solution during a search run, compared to the previous
 * best known solution. Note that it is not absolutely guaranteed that a search
 * will ever stop when using only this stop criterion, as it may happen that the last
 * improvement is still above the required minimum and no more improvements are found
 * from that point in time.
 * 
 * @author Herman De Beukelaer
 */
public class MinDelta implements StopCriterion {

    // minimum delta
    private final double minDelta;
    
    /**
     * Create a stop criterion that imposes a minimum evaluation delta when
     * finding a new best solution during a search run. The given minimum
     * delta should be strictly positive.
     * 
     * @param minDelta minimum evaluation delta (> 0.0)
     * @throws IllegalArgumentException if minDelta is not > 0.0
     */
    public MinDelta(double minDelta){
        // check value
        if(minDelta <= 0.0){
            throw new IllegalArgumentException("Error while creating stop criterion: minimum delta should be > 0.0.");
        }
        this.minDelta = minDelta;
    }
    
    /**
     * Checks whether the minimum delta observed during the current run of the given
     * search is still above the required minimum.
     * 
     * @param search search for which the minimum delta has to be checked
     * @return true in case of a minimum delta below the required minimum
     */
    @Override
    public boolean searchShouldStop(Search search) {
        return search.getMinDelta() > 0.0 && search.getMinDelta() < minDelta;
    }
    
    @Override
    public String toString(){
        return "{min delta: " + minDelta + "}";
    }

}