You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by lu...@apache.org on 2015/11/22 16:24:40 UTC
[6/6] [math] Use a top level interface for bracketed real field
solver.
Use a top level interface for bracketed real field solver.
Project: http://git-wip-us.apache.org/repos/asf/commons-math/repo
Commit: http://git-wip-us.apache.org/repos/asf/commons-math/commit/d75f5090
Tree: http://git-wip-us.apache.org/repos/asf/commons-math/tree/d75f5090
Diff: http://git-wip-us.apache.org/repos/asf/commons-math/diff/d75f5090
Branch: refs/heads/field-ode
Commit: d75f5090e33c87e1c5207a3f8fac4630a05d5c2f
Parents: 1b2ba24
Author: Luc Maisonobe <lu...@apache.org>
Authored: Sun Nov 22 16:24:15 2015 +0100
Committer: Luc Maisonobe <lu...@apache.org>
Committed: Sun Nov 22 16:24:15 2015 +0100
----------------------------------------------------------------------
.../BracketedRealFieldUnivariateSolver.java | 142 +++++++++++++++++++
.../FieldBracketingNthOrderBrentSolver.java | 3 +-
.../math3/ode/AbstractFieldIntegrator.java | 3 +-
.../math3/ode/FieldFirstOrderIntegrator.java | 10 +-
.../math3/ode/events/FieldEventState.java | 10 +-
5 files changed, 157 insertions(+), 11 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/commons-math/blob/d75f5090/src/main/java/org/apache/commons/math3/analysis/solvers/BracketedRealFieldUnivariateSolver.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/math3/analysis/solvers/BracketedRealFieldUnivariateSolver.java b/src/main/java/org/apache/commons/math3/analysis/solvers/BracketedRealFieldUnivariateSolver.java
new file mode 100644
index 0000000..55562e5
--- /dev/null
+++ b/src/main/java/org/apache/commons/math3/analysis/solvers/BracketedRealFieldUnivariateSolver.java
@@ -0,0 +1,142 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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.apache.commons.math3.analysis.solvers;
+
+import org.apache.commons.math3.RealFieldElement;
+import org.apache.commons.math3.analysis.RealFieldUnivariateFunction;
+
+/** Interface for {@link UnivariateSolver (univariate real) root-finding
+ * algorithms} that maintain a bracketed solution. There are several advantages
+ * to having such root-finding algorithms:
+ * <ul>
+ * <li>The bracketed solution guarantees that the root is kept within the
+ * interval. As such, these algorithms generally also guarantee
+ * convergence.</li>
+ * <li>The bracketed solution means that we have the opportunity to only
+ * return roots that are greater than or equal to the actual root, or
+ * are less than or equal to the actual root. That is, we can control
+ * whether under-approximations and over-approximations are
+ * {@link AllowedSolution allowed solutions}. Other root-finding
+ * algorithms can usually only guarantee that the solution (the root that
+ * was found) is around the actual root.</li>
+ * </ul>
+ *
+ * <p>For backwards compatibility, all root-finding algorithms must have
+ * {@link AllowedSolution#ANY_SIDE ANY_SIDE} as default for the allowed
+ * solutions.</p>
+ *
+ * @see AllowedSolution
+ * @param <T> the type of the field elements
+ * @since 3.6
+ */
+public interface BracketedRealFieldUnivariateSolver<T extends RealFieldElement<T>> {
+
+ /**
+ * Get the maximum number of function evaluations.
+ *
+ * @return the maximum number of function evaluations.
+ */
+ int getMaxEvaluations();
+
+ /**
+ * Get the number of evaluations of the objective function.
+ * The number of evaluations corresponds to the last call to the
+ * {@code optimize} method. It is 0 if the method has not been
+ * called yet.
+ *
+ * @return the number of evaluations of the objective function.
+ */
+ int getEvaluations();
+
+ /**
+ * Get the absolute accuracy of the solver. Solutions returned by the
+ * solver should be accurate to this tolerance, i.e., if ε is the
+ * absolute accuracy of the solver and {@code v} is a value returned by
+ * one of the {@code solve} methods, then a root of the function should
+ * exist somewhere in the interval ({@code v} - ε, {@code v} + ε).
+ *
+ * @return the absolute accuracy.
+ */
+ T getAbsoluteAccuracy();
+
+ /**
+ * Get the relative accuracy of the solver. The contract for relative
+ * accuracy is the same as {@link #getAbsoluteAccuracy()}, but using
+ * relative, rather than absolute error. If ρ is the relative accuracy
+ * configured for a solver and {@code v} is a value returned, then a root
+ * of the function should exist somewhere in the interval
+ * ({@code v} - ρ {@code v}, {@code v} + ρ {@code v}).
+ *
+ * @return the relative accuracy.
+ */
+ T getRelativeAccuracy();
+
+ /**
+ * Get the function value accuracy of the solver. If {@code v} is
+ * a value returned by the solver for a function {@code f},
+ * then by contract, {@code |f(v)|} should be less than or equal to
+ * the function value accuracy configured for the solver.
+ *
+ * @return the function value accuracy.
+ */
+ T getFunctionValueAccuracy();
+
+ /**
+ * Solve for a zero in the given interval.
+ * A solver may require that the interval brackets a single zero root.
+ * Solvers that do require bracketing should be able to handle the case
+ * where one of the endpoints is itself a root.
+ *
+ * @param maxEval Maximum number of evaluations.
+ * @param f Function to solve.
+ * @param min Lower bound for the interval.
+ * @param max Upper bound for the interval.
+ * @param allowedSolution The kind of solutions that the root-finding algorithm may
+ * accept as solutions.
+ * @return A value where the function is zero.
+ * @throws org.apache.commons.math3.exception.MathIllegalArgumentException
+ * if the arguments do not satisfy the requirements specified by the solver.
+ * @throws org.apache.commons.math3.exception.TooManyEvaluationsException if
+ * the allowed number of evaluations is exceeded.
+ */
+ T solve(int maxEval, RealFieldUnivariateFunction<T> f, T min, T max,
+ AllowedSolution allowedSolution);
+
+ /**
+ * Solve for a zero in the given interval, start at {@code startValue}.
+ * A solver may require that the interval brackets a single zero root.
+ * Solvers that do require bracketing should be able to handle the case
+ * where one of the endpoints is itself a root.
+ *
+ * @param maxEval Maximum number of evaluations.
+ * @param f Function to solve.
+ * @param min Lower bound for the interval.
+ * @param max Upper bound for the interval.
+ * @param startValue Start value to use.
+ * @param allowedSolution The kind of solutions that the root-finding algorithm may
+ * accept as solutions.
+ * @return A value where the function is zero.
+ * @throws org.apache.commons.math3.exception.MathIllegalArgumentException
+ * if the arguments do not satisfy the requirements specified by the solver.
+ * @throws org.apache.commons.math3.exception.TooManyEvaluationsException if
+ * the allowed number of evaluations is exceeded.
+ */
+ T solve(int maxEval, RealFieldUnivariateFunction<T> f, T min, T max, T startValue,
+ AllowedSolution allowedSolution);
+
+}
http://git-wip-us.apache.org/repos/asf/commons-math/blob/d75f5090/src/main/java/org/apache/commons/math3/analysis/solvers/FieldBracketingNthOrderBrentSolver.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/math3/analysis/solvers/FieldBracketingNthOrderBrentSolver.java b/src/main/java/org/apache/commons/math3/analysis/solvers/FieldBracketingNthOrderBrentSolver.java
index 01bb784..d3f4a2a 100644
--- a/src/main/java/org/apache/commons/math3/analysis/solvers/FieldBracketingNthOrderBrentSolver.java
+++ b/src/main/java/org/apache/commons/math3/analysis/solvers/FieldBracketingNthOrderBrentSolver.java
@@ -46,7 +46,8 @@ import org.apache.commons.math3.util.Precision;
* @param <T> the type of the field elements
* @since 3.6
*/
-public class FieldBracketingNthOrderBrentSolver<T extends RealFieldElement<T>> {
+public class FieldBracketingNthOrderBrentSolver<T extends RealFieldElement<T>>
+ implements BracketedRealFieldUnivariateSolver<T> {
/** Maximal aging triggering an attempt to balance the bracketing interval. */
private static final int MAXIMAL_AGING = 2;
http://git-wip-us.apache.org/repos/asf/commons-math/blob/d75f5090/src/main/java/org/apache/commons/math3/ode/AbstractFieldIntegrator.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/math3/ode/AbstractFieldIntegrator.java b/src/main/java/org/apache/commons/math3/ode/AbstractFieldIntegrator.java
index e200c09..c15b827 100644
--- a/src/main/java/org/apache/commons/math3/ode/AbstractFieldIntegrator.java
+++ b/src/main/java/org/apache/commons/math3/ode/AbstractFieldIntegrator.java
@@ -28,6 +28,7 @@ import java.util.TreeSet;
import org.apache.commons.math3.Field;
import org.apache.commons.math3.RealFieldElement;
+import org.apache.commons.math3.analysis.solvers.BracketedRealFieldUnivariateSolver;
import org.apache.commons.math3.analysis.solvers.FieldBracketingNthOrderBrentSolver;
import org.apache.commons.math3.exception.DimensionMismatchException;
import org.apache.commons.math3.exception.MaxCountExceededException;
@@ -147,7 +148,7 @@ public abstract class AbstractFieldIntegrator<T extends RealFieldElement<T>> imp
final double maxCheckInterval,
final double convergence,
final int maxIterationCount,
- final FieldBracketingNthOrderBrentSolver<T> solver) {
+ final BracketedRealFieldUnivariateSolver<T> solver) {
eventsStates.add(new FieldEventState<T>(handler, maxCheckInterval, field.getZero().add(convergence),
maxIterationCount, solver));
}
http://git-wip-us.apache.org/repos/asf/commons-math/blob/d75f5090/src/main/java/org/apache/commons/math3/ode/FieldFirstOrderIntegrator.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/math3/ode/FieldFirstOrderIntegrator.java b/src/main/java/org/apache/commons/math3/ode/FieldFirstOrderIntegrator.java
index 7735e25..24c0f1f 100644
--- a/src/main/java/org/apache/commons/math3/ode/FieldFirstOrderIntegrator.java
+++ b/src/main/java/org/apache/commons/math3/ode/FieldFirstOrderIntegrator.java
@@ -20,7 +20,7 @@ package org.apache.commons.math3.ode;
import java.util.Collection;
import org.apache.commons.math3.RealFieldElement;
-import org.apache.commons.math3.analysis.solvers.FieldBracketingNthOrderBrentSolver;
+import org.apache.commons.math3.analysis.solvers.BracketedRealFieldUnivariateSolver;
import org.apache.commons.math3.exception.MaxCountExceededException;
import org.apache.commons.math3.exception.NoBracketingException;
import org.apache.commons.math3.exception.NumberIsTooSmallException;
@@ -71,7 +71,8 @@ public interface FieldFirstOrderIntegrator<T extends RealFieldElement<T>> {
/** Add an event handler to the integrator.
* <p>
- * The default solver is a 5<sup>th</sup> order {@link FieldBracketingNthOrderBrentSolver}.
+ * The default solver is a 5<sup>th</sup> order {@link
+ * org.apache.commons.math3.analysis.solvers.FieldBracketingNthOrderBrentSolver}.
* </p>
* @param handler event handler
* @param maxCheckInterval maximal time interval between switching
@@ -80,7 +81,8 @@ public interface FieldFirstOrderIntegrator<T extends RealFieldElement<T>> {
* @param convergence convergence threshold in the event time search
* @param maxIterationCount upper limit of the iteration count in
* the event time search events.
- * @see #addEventHandler(FieldEventHandler, double, double, int, FieldBracketingNthOrderBrentSolver)
+ * @see #addEventHandler(FieldEventHandler, double, double, int,
+ * org.apache.commons.math3.analysis.solvers.FieldBracketingNthOrderBrentSolver)
* @see #getEventHandlers()
* @see #clearEventHandlers()
*/
@@ -102,7 +104,7 @@ public interface FieldFirstOrderIntegrator<T extends RealFieldElement<T>> {
*/
void addEventHandler(FieldEventHandler<T> handler, double maxCheckInterval,
double convergence, int maxIterationCount,
- FieldBracketingNthOrderBrentSolver<T> solver);
+ BracketedRealFieldUnivariateSolver<T> solver);
/** Get all the event handlers that have been added to the integrator.
* @return an unmodifiable collection of the added events handlers
http://git-wip-us.apache.org/repos/asf/commons-math/blob/d75f5090/src/main/java/org/apache/commons/math3/ode/events/FieldEventState.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/math3/ode/events/FieldEventState.java b/src/main/java/org/apache/commons/math3/ode/events/FieldEventState.java
index a0782d1..2210b4c 100644
--- a/src/main/java/org/apache/commons/math3/ode/events/FieldEventState.java
+++ b/src/main/java/org/apache/commons/math3/ode/events/FieldEventState.java
@@ -18,9 +18,9 @@
package org.apache.commons.math3.ode.events;
import org.apache.commons.math3.RealFieldElement;
-import org.apache.commons.math3.analysis.FieldUnivariateFunction;
+import org.apache.commons.math3.analysis.RealFieldUnivariateFunction;
import org.apache.commons.math3.analysis.solvers.AllowedSolution;
-import org.apache.commons.math3.analysis.solvers.FieldBracketingNthOrderBrentSolver;
+import org.apache.commons.math3.analysis.solvers.BracketedRealFieldUnivariateSolver;
import org.apache.commons.math3.exception.MaxCountExceededException;
import org.apache.commons.math3.exception.NoBracketingException;
import org.apache.commons.math3.ode.FieldODEStateAndDerivative;
@@ -84,7 +84,7 @@ public class FieldEventState<T extends RealFieldElement<T>> {
private Action nextAction;
/** Root-finding algorithm to use to detect state events. */
- private final FieldBracketingNthOrderBrentSolver<T> solver;
+ private final BracketedRealFieldUnivariateSolver<T> solver;
/** Simple constructor.
* @param handler event handler
@@ -98,7 +98,7 @@ public class FieldEventState<T extends RealFieldElement<T>> {
*/
public FieldEventState(final FieldEventHandler<T> handler, final double maxCheckInterval,
final T convergence, final int maxIterationCount,
- final FieldBracketingNthOrderBrentSolver<T> solver) {
+ final BracketedRealFieldUnivariateSolver<T> solver) {
this.handler = handler;
this.maxCheckInterval = maxCheckInterval;
this.convergence = convergence.abs();
@@ -202,7 +202,7 @@ public class FieldEventState<T extends RealFieldElement<T>> {
final int n = FastMath.max(1, (int) FastMath.ceil(FastMath.abs(dt.getReal()) / maxCheckInterval));
final T h = dt.divide(n);
- final FieldUnivariateFunction<T> f = new FieldUnivariateFunction<T>() {
+ final RealFieldUnivariateFunction<T> f = new RealFieldUnivariateFunction<T>() {
/** {@inheritDoc} */
public T value(final T t) throws LocalMaxCountExceededException {
try {