View Javadoc

1   /*
2    * Copyright 2003-2004 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.math.analysis;
17  
18  import org.apache.commons.discovery.tools.DiscoverClass;
19  
20  /**
21   * Abstract factory class used to create {@link UnivariateRealSolver} instances.
22   * <p>
23   * Solvers implementing the following algorithms are supported:
24   * <ul>
25   * <li>Bisection</li>
26   * <li>Brent's method</li>
27   * <li>Secant method</li>
28   * </ul>
29   * Concrete factories extending this class also specify a default solver, instances of which
30   * are returned by <code>newDefaultSolver()</code>.
31   * <p>
32   * Common usage:<pre>
33   * SolverFactory factory = UnivariateRealSolverFactory.newInstance();
34   *
35   * // create a Brent solver to use with a UnivariateRealFunction f
36   * BrentSolver solver = factory.newBrentSolver(f);
37   * </pre>
38   *
39   * <a href="http://jakarta.apache.org/commons/discovery/">Jakarta Commons Discovery</a>
40   * is used to determine the concrete factory returned by 
41   * <code>UnivariateRealSolverFactory.newInstance().</code>  The default is
42   * {@link UnivariateRealSolverFactoryImpl}.
43   *
44   * @version $Revision: 155427 $ $Date: 2005-02-26 06:11:52 -0700 (Sat, 26 Feb 2005) $
45   */
46  public abstract class UnivariateRealSolverFactory {
47      /**
48       * Default constructor.
49       */
50      protected UnivariateRealSolverFactory() {
51      }
52  
53      /**
54       * Create a new factory.
55       * @return a new factory.
56       */
57      public static UnivariateRealSolverFactory newInstance() {
58          UnivariateRealSolverFactory factory = null;
59          try {
60              DiscoverClass dc = new DiscoverClass();
61              factory = (UnivariateRealSolverFactory) dc.newInstance(
62                  UnivariateRealSolverFactory.class,
63                  "org.apache.commons.math.analysis.UnivariateRealSolverFactoryImpl");
64          } catch(Throwable t) {
65              return new UnivariateRealSolverFactoryImpl();
66          }
67          return factory;
68      }
69      
70      /**
71       * Create a new {@link UnivariateRealSolver} for the given function.  The
72       * actual solver returned is determined by the underlying factory.
73       * @param f the function.
74       * @return the new solver.
75       */
76      public abstract UnivariateRealSolver newDefaultSolver(
77          UnivariateRealFunction f);
78      
79      /**
80       * Create a new {@link UnivariateRealSolver} for the given function.  The
81       * solver is an implementation of the bisection method.
82       * @param f the function.
83       * @return the new solver.
84       */
85      public abstract UnivariateRealSolver newBisectionSolver(
86          UnivariateRealFunction f);
87      
88      /**
89       * Create a new {@link UnivariateRealSolver} for the given function.  The
90       * solver is an implementation of the Brent method.
91       * @param f the function.
92       * @return the new solver.
93       */
94      public abstract UnivariateRealSolver newBrentSolver(
95          UnivariateRealFunction f);
96      
97      /**
98       * Create a new {@link UnivariateRealSolver} for the given function.  The
99       * solver is an implementation of Newton's Method.
100      * @param f the function.
101      * @return the new solver.
102      */
103     public abstract UnivariateRealSolver newNewtonSolver(
104         DifferentiableUnivariateRealFunction f);
105     
106     /**
107      * Create a new {@link UnivariateRealSolver} for the given function.  The
108      * solver is an implementation of the secant method.
109      * @param f the function.
110      * @return the new solver.
111      */
112     public abstract UnivariateRealSolver newSecantSolver(
113         UnivariateRealFunction f);
114 }