View Javadoc

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  package org.apache.commons.math.analysis;
18  
19  import org.apache.commons.discovery.tools.DiscoverClass;
20  
21  /**
22   * Abstract factory class used to create {@link UnivariateRealSolver} instances.
23   * <p>
24   * Solvers implementing the following algorithms are supported:
25   * <ul>
26   * <li>Bisection</li>
27   * <li>Brent's method</li>
28   * <li>Secant method</li>
29   * </ul>
30   * Concrete factories extending this class also specify a default solver, instances of which
31   * are returned by <code>newDefaultSolver()</code>.</p>
32   * <p>
33   * Common usage:<pre>
34   * SolverFactory factory = UnivariateRealSolverFactory.newInstance();</p>
35   *
36   * // create a Brent solver to use with a UnivariateRealFunction f
37   * BrentSolver solver = factory.newBrentSolver(f);
38   * </pre>
39   *
40   * <a href="http://commons.apache.org/discovery/">Apache Commons Discovery</a>
41   * is used to determine the concrete factory returned by 
42   * <code>UnivariateRealSolverFactory.newInstance().</code>  The default is
43   * {@link UnivariateRealSolverFactoryImpl}.
44   *
45   * @version $Revision: 615734 $ $Date: 2008-01-27 23:10:03 -0700 (Sun, 27 Jan 2008) $
46   */
47  public abstract class UnivariateRealSolverFactory {
48      /**
49       * Default constructor.
50       */
51      protected UnivariateRealSolverFactory() {
52      }
53  
54      /**
55       * Create a new factory.
56       * @return a new factory.
57       */
58      public static UnivariateRealSolverFactory newInstance() {
59          UnivariateRealSolverFactory factory = null;
60          try {
61              DiscoverClass dc = new DiscoverClass();
62              factory = (UnivariateRealSolverFactory) dc.newInstance(
63                  UnivariateRealSolverFactory.class,
64                  "org.apache.commons.math.analysis.UnivariateRealSolverFactoryImpl");
65          } catch(Throwable t) {
66              return new UnivariateRealSolverFactoryImpl();
67          }
68          return factory;
69      }
70      
71      /**
72       * Create a new {@link UnivariateRealSolver} for the given function.  The
73       * actual solver returned is determined by the underlying factory.
74       * @param f the function.
75       * @return the new solver.
76       */
77      public abstract UnivariateRealSolver newDefaultSolver(
78          UnivariateRealFunction f);
79      
80      /**
81       * Create a new {@link UnivariateRealSolver} for the given function.  The
82       * solver is an implementation of the bisection method.
83       * @param f the function.
84       * @return the new solver.
85       */
86      public abstract UnivariateRealSolver newBisectionSolver(
87          UnivariateRealFunction f);
88      
89      /**
90       * Create a new {@link UnivariateRealSolver} for the given function.  The
91       * solver is an implementation of the Brent method.
92       * @param f the function.
93       * @return the new solver.
94       */
95      public abstract UnivariateRealSolver newBrentSolver(
96          UnivariateRealFunction f);
97      
98      /**
99       * Create a new {@link UnivariateRealSolver} for the given function.  The
100      * solver is an implementation of Newton's Method.
101      * @param f the function.
102      * @return the new solver.
103      */
104     public abstract UnivariateRealSolver newNewtonSolver(
105         DifferentiableUnivariateRealFunction f);
106     
107     /**
108      * Create a new {@link UnivariateRealSolver} for the given function.  The
109      * solver is an implementation of the secant method.
110      * @param f the function.
111      * @return the new solver.
112      */
113     public abstract UnivariateRealSolver newSecantSolver(
114         UnivariateRealFunction f);
115 }