001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.math3.optim.nonlinear.scalar;
018
019import java.util.Collections;
020import java.util.List;
021import java.util.ArrayList;
022import java.util.Comparator;
023import org.apache.commons.math3.exception.NotStrictlyPositiveException;
024import org.apache.commons.math3.exception.NullArgumentException;
025import org.apache.commons.math3.random.RandomVectorGenerator;
026import org.apache.commons.math3.optim.BaseMultiStartMultivariateOptimizer;
027import org.apache.commons.math3.optim.PointValuePair;
028
029/**
030 * Multi-start optimizer.
031 *
032 * This class wraps an optimizer in order to use it several times in
033 * turn with different starting points (trying to avoid being trapped
034 * in a local extremum when looking for a global one).
035 *
036 * @since 3.0
037 */
038public class MultiStartMultivariateOptimizer
039    extends BaseMultiStartMultivariateOptimizer<PointValuePair> {
040    /** Underlying optimizer. */
041    private final MultivariateOptimizer optimizer;
042    /** Found optima. */
043    private final List<PointValuePair> optima = new ArrayList<PointValuePair>();
044
045    /**
046     * Create a multi-start optimizer from a single-start optimizer.
047     *
048     * @param optimizer Single-start optimizer to wrap.
049     * @param starts Number of starts to perform.
050     * If {@code starts == 1}, the result will be same as if {@code optimizer}
051     * is called directly.
052     * @param generator Random vector generator to use for restarts.
053     * @throws NullArgumentException if {@code optimizer} or {@code generator}
054     * is {@code null}.
055     * @throws NotStrictlyPositiveException if {@code starts < 1}.
056     */
057    public MultiStartMultivariateOptimizer(final MultivariateOptimizer optimizer,
058                                           final int starts,
059                                           final RandomVectorGenerator generator)
060        throws NullArgumentException,
061        NotStrictlyPositiveException {
062        super(optimizer, starts, generator);
063        this.optimizer = optimizer;
064    }
065
066    /**
067     * {@inheritDoc}
068     */
069    @Override
070    public PointValuePair[] getOptima() {
071        Collections.sort(optima, getPairComparator());
072        return optima.toArray(new PointValuePair[0]);
073    }
074
075    /**
076     * {@inheritDoc}
077     */
078    @Override
079    protected void store(PointValuePair optimum) {
080        optima.add(optimum);
081    }
082
083    /**
084     * {@inheritDoc}
085     */
086    @Override
087    protected void clear() {
088        optima.clear();
089    }
090
091    /**
092     * @return a comparator for sorting the optima.
093     */
094    private Comparator<PointValuePair> getPairComparator() {
095        return new Comparator<PointValuePair>() {
096            /** {@inheritDoc} */
097            public int compare(final PointValuePair o1,
098                               final PointValuePair o2) {
099                if (o1 == null) {
100                    return (o2 == null) ? 0 : 1;
101                } else if (o2 == null) {
102                    return -1;
103                }
104                final double v1 = o1.getValue();
105                final double v2 = o2.getValue();
106                return (optimizer.getGoalType() == GoalType.MINIMIZE) ?
107                    Double.compare(v1, v2) : Double.compare(v2, v1);
108            }
109        };
110    }
111}