1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.math4.legacy.analysis.solvers;
19
20
21 /** The kinds of solutions that a {@link BracketedUnivariateSolver
22 * (bracketed univariate real) root-finding algorithm} may accept as solutions.
23 * This basically controls whether or not under-approximations and
24 * over-approximations are allowed.
25 *
26 * <p>If all solutions are accepted ({@link #ANY_SIDE}), then the solution
27 * that the root-finding algorithm returns for a given root may be equal to the
28 * actual root, but it may also be an approximation that is slightly smaller
29 * or slightly larger than the actual root. Root-finding algorithms generally
30 * only guarantee that the returned solution is within the requested
31 * tolerances. In certain cases however, in particular for
32 * {@link org.apache.commons.math4.legacy.ode.events.EventHandler state events} of
33 * {@link org.apache.commons.math4.legacy.ode.ODEIntegrator ODE solvers}, it
34 * may be necessary to guarantee that a solution is returned that lies on a
35 * specific side the solution.</p>
36 *
37 * @see BracketedUnivariateSolver
38 * @since 3.0
39 */
40 public enum AllowedSolution {
41 /** There are no additional side restriction on the solutions for
42 * root-finding. That is, both under-approximations and over-approximations
43 * are allowed. So, if a function f(x) has a root at x = x0, then the
44 * root-finding result s may be smaller than x0, equal to x0, or greater
45 * than x0.
46 */
47 ANY_SIDE,
48
49 /** Only solutions that are less than or equal to the actual root are
50 * acceptable as solutions for root-finding. In other words,
51 * over-approximations are not allowed. So, if a function f(x) has a root
52 * at x = x0, then the root-finding result s must satisfy s <= x0.
53 */
54 LEFT_SIDE,
55
56 /** Only solutions that are greater than or equal to the actual root are
57 * acceptable as solutions for root-finding. In other words,
58 * under-approximations are not allowed. So, if a function f(x) has a root
59 * at x = x0, then the root-finding result s must satisfy s >= x0.
60 */
61 RIGHT_SIDE,
62
63 /** Only solutions for which values are less than or equal to zero are
64 * acceptable as solutions for root-finding. So, if a function f(x) has
65 * a root at x = x0, then the root-finding result s must satisfy f(s) <= 0.
66 */
67 BELOW_SIDE,
68
69 /** Only solutions for which values are greater than or equal to zero are
70 * acceptable as solutions for root-finding. So, if a function f(x) has
71 * a root at x = x0, then the root-finding result s must satisfy f(s) >= 0.
72 */
73 ABOVE_SIDE;
74 }