File: Providing-the-function-to-solve.html

package info (click to toggle)
gsl-ref-html 1.16-1
links: PTS
area: non-free
in suites: jessie, jessie-kfreebsd, stretch
size: 5,816 kB
ctags: 4,130
sloc: makefile: 35
file content (204 lines) | stat: -rw-r--r-- 8,232 bytes
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The GSL Team.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections and no cover texts.  A copy of the license is
included in the section entitled "GNU Free Documentation License". -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Scientific Library &ndash; Reference Manual: Providing the function to solve</title>

<meta name="description" content="GNU Scientific Library &ndash; Reference Manual: Providing the function to solve">
<meta name="keywords" content="GNU Scientific Library &ndash; Reference Manual: Providing the function to solve">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Function-Index.html#Function-Index" rel="index" title="Function Index">
<link href="One-dimensional-Root_002dFinding.html#One-dimensional-Root_002dFinding" rel="up" title="One dimensional Root-Finding">
<link href="Search-Bounds-and-Guesses.html#Search-Bounds-and-Guesses" rel="next" title="Search Bounds and Guesses">
<link href="Initializing-the-Solver.html#Initializing-the-Solver" rel="previous" title="Initializing the Solver">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Providing-the-function-to-solve"></a>
<div class="header">
<p>
Next: <a href="Search-Bounds-and-Guesses.html#Search-Bounds-and-Guesses" accesskey="n" rel="next">Search Bounds and Guesses</a>, Previous: <a href="Initializing-the-Solver.html#Initializing-the-Solver" accesskey="p" rel="previous">Initializing the Solver</a>, Up: <a href="One-dimensional-Root_002dFinding.html#One-dimensional-Root_002dFinding" accesskey="u" rel="up">One dimensional Root-Finding</a> &nbsp; [<a href="Function-Index.html#Function-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Providing-the-function-to-solve-1"></a>
<h3 class="section">33.4 Providing the function to solve</h3>
<a name="index-root-finding_002c-providing-a-function-to-solve"></a>

<p>You must provide a continuous function of one variable for the root
finders to operate on, and, sometimes, its first derivative.  In order
to allow for general parameters the functions are defined by the
following data types:
</p>
<dl>
<dt><a name="index-gsl_005ffunction"></a>Data Type: <strong>gsl_function</strong></dt>
<dd><p>This data type defines a general function with parameters. 
</p>
<dl compact="compact">
<dt><code>double (* function) (double <var>x</var>, void * <var>params</var>)</code></dt>
<dd><p>this function should return the value
<em>f(x,params)</em> for argument <var>x</var> and parameters <var>params</var>
</p>
</dd>
<dt><code>void * params</code></dt>
<dd><p>a pointer to the parameters of the function
</p></dd>
</dl>
</dd></dl>

<p>Here is an example for the general quadratic function,
with <em>a = 3</em>, <em>b = 2</em>, <em>c = 1</em>.  The following code
defines a <code>gsl_function</code> <code>F</code> which you could pass to a root
finder as a function pointer:
</p>
<div class="example">
<pre class="example">struct my_f_params { double a; double b; double c; };

double
my_f (double x, void * p) {
   struct my_f_params * params 
     = (struct my_f_params *)p;
   double a = (params-&gt;a);
   double b = (params-&gt;b);
   double c = (params-&gt;c);

   return  (a * x + b) * x + c;
}

gsl_function F;
struct my_f_params params = { 3.0, 2.0, 1.0 };

F.function = &amp;my_f;
F.params = &amp;params;
</pre></div>

<p>The function <em>f(x)</em> can be evaluated using the macro
<code>GSL_FN_EVAL(&amp;F,x)</code> defined in <samp>gsl_math.h</samp>.
</p>
<dl>
<dt><a name="index-gsl_005ffunction_005ffdf"></a>Data Type: <strong>gsl_function_fdf</strong></dt>
<dd><p>This data type defines a general function with parameters and its first
derivative.
</p>
<dl compact="compact">
<dt><code>double (* f) (double <var>x</var>, void * <var>params</var>)</code></dt>
<dd><p>this function should return the value of
<em>f(x,params)</em> for argument <var>x</var> and parameters <var>params</var>
</p>
</dd>
<dt><code>double (* df) (double <var>x</var>, void * <var>params</var>)</code></dt>
<dd><p>this function should return the value of the derivative of <var>f</var> with
respect to <var>x</var>,
<em>f'(x,params)</em>, for argument <var>x</var> and parameters <var>params</var>
</p>
</dd>
<dt><code>void (* fdf) (double <var>x</var>, void * <var>params</var>, double * <var>f</var>, double * <var>df</var>)</code></dt>
<dd><p>this function should set the values of the function <var>f</var> to 
<em>f(x,params)</em>
and its derivative <var>df</var> to
<em>f'(x,params)</em> 
for argument <var>x</var> and parameters <var>params</var>.  This function
provides an optimization of the separate functions for <em>f(x)</em> and
<em>f'(x)</em>&mdash;it is always faster to compute the function and its
derivative at the same time.
</p>
</dd>
<dt><code>void * params</code></dt>
<dd><p>a pointer to the parameters of the function
</p></dd>
</dl>
</dd></dl>

<p>Here is an example where 
<em>f(x) = 2\exp(2x)</em>:
</p>
<div class="example">
<pre class="example">double
my_f (double x, void * params)
{
   return exp (2 * x);
}

double
my_df (double x, void * params)
{
   return 2 * exp (2 * x);
}

void
my_fdf (double x, void * params, 
        double * f, double * df)
{
   double t = exp (2 * x);

   *f = t;
   *df = 2 * t;   /* uses existing value */
}

gsl_function_fdf FDF;

FDF.f = &amp;my_f;
FDF.df = &amp;my_df;
FDF.fdf = &amp;my_fdf;
FDF.params = 0;
</pre></div>

<p>The function <em>f(x)</em> can be evaluated using the macro
<code>GSL_FN_FDF_EVAL_F(&amp;FDF,x)</code> and the derivative <em>f'(x)</em> can
be evaluated using the macro <code>GSL_FN_FDF_EVAL_DF(&amp;FDF,x)</code>.  Both
the function <em>y = f(x)</em> and its derivative <em>dy = f'(x)</em> can
be evaluated at the same time using the macro
<code>GSL_FN_FDF_EVAL_F_DF(&amp;FDF,x,y,dy)</code>.  The macro stores
<em>f(x)</em> in its <var>y</var> argument and <em>f'(x)</em> in its <var>dy</var>
argument&mdash;both of these should be pointers to <code>double</code>.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Search-Bounds-and-Guesses.html#Search-Bounds-and-Guesses" accesskey="n" rel="next">Search Bounds and Guesses</a>, Previous: <a href="Initializing-the-Solver.html#Initializing-the-Solver" accesskey="p" rel="previous">Initializing the Solver</a>, Up: <a href="One-dimensional-Root_002dFinding.html#One-dimensional-Root_002dFinding" accesskey="u" rel="up">One dimensional Root-Finding</a> &nbsp; [<a href="Function-Index.html#Function-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>