lines 652-793 of file: example/multi_thread/multi_newton.cpp

{xrst_begin multi_newton_time}
.

Timing Test of Multi-Threaded Newton Method
###########################################

Syntax
******

| *ok* = ``multi_newton_time`` ( *time_out* , *test_time* , *num_threads* ,
| |tab| *num_zero* , *num_sub* , *num_sum* , *use_ad*
| )

Purpose
*******
Runs correctness and timing test for a multi-threaded Newton method.
This test uses Newton's method to determine all the zeros of the sine
function on an interval.
CppAD, or hand coded derivatives,
can be used to calculate the derivatives used by Newton's method.
The calculation can be done in parallel on the different sub-intervals.
In addition, the calculation can be done without multi-threading.

Thread
******
It is assumed that this function is called by thread zero in sequential
mode; i.e., not :ref:`in_parallel<ta_in_parallel-name>` .

ok
**
This return value has prototype

   ``bool`` *ok*

If it is true,
``multi_newton_time`` passed the correctness test.
Otherwise it is false.

time_out
********
This argument has prototype

   ``double&`` *time_out*

The input value of the argument does not matter.
Upon return it is the number of wall clock seconds required for
the multi-threaded Newton method can compute all the zeros.

test_time
*********
Is the minimum amount of wall clock time that the test should take.
The number of repeats for the test will be increased until this time
is reached.
The reported *time_out* is the total wall clock time divided by the
number of repeats.

num_threads
***********
This argument has prototype

   ``size_t`` *num_threads*

It specifies the number of threads that
are available for this test.
If it is zero, the test is run without multi-threading and

   1 == ``thread_alloc::num_threads`` ()

when ``multi_newton_time`` is called.
If it is non-zero, the test is run with multi-threading and

   *num_threads* == ``thread_alloc::num_threads`` ()

when ``multi_newton_time`` is called.

num_zero
********
This argument has prototype

   ``size_t`` *num_zero*

and it must be greater than one.
It specifies the actual number of zeros in the test function
:math:`\sin(x)`.
To be specific, ``multi_newton_time`` will attempt to determine
all of the values of :math:`x` for which :math:`\sin(x) = 0` and
:math:`x` is in the interval

   [ 0 , ( *num_zero* ``- 1`` ) * *pi*  ]

.

num_sub
*******
This argument has prototype

   ``size_t`` *num_sub*

It specifies the number of sub-intervals to divide the total interval into.
It must be greater than *num_zero*
(so that the correctness test can check we have found all the zeros).

num_sum
*******
This argument has prototype

   ``size_t`` *num_sum*

and must be greater than zero.
The actual function used by the Newton method is

.. math::

   f(x) = \frac{1}{n} \sum_{i=1}^{n} \sin (x)

where :math:`n` is equal to *num_sum* .
Larger values of *num_sum* simulate a case where the
evaluation of the function :math:`f(x)` takes more time.

use_ad
******
This argument has prototype

   ``bool`` *user_ad*

If *use_ad* is ``true`` ,
then derivatives will be computed using CppAD.
Note that this derivative computation includes
re-taping the function for each
value of :math:`x` (even though re-taping is not necessary).

If *use_ad* is ``false`` ,
derivatives will be computed using a hand coded routine.

Source
******
{xrst_literal
   // BEGIN TIME C++
   // END TIME C++
}

{xrst_end multi_newton_time}
