--------------------------------------
lines 6-223 of file: speed/ar1_xam.cpp
--------------------------------------

{xrst_begin ar1_xam.cpp}
{xrst_spell
  alloc
  ndebug
  preprocessor
  rng
}

A First Order Auto-Regressive Example and Speed Test
####################################################

Syntax
******

| ./ ``ar1_xam`` \\
| |tab| *random_seed*  \\
| |tab| *number_random*  \\
| |tab| *quasi_fixed*  \\
| |tab| *trace_optimize_fixed*  \\
| |tab| *ipopt_solve*  \\
| |tab| *bool_sparsity*  \\
| |tab| *hold_memory*  \\
| |tab| *derivative_test*  \\
| |tab| *start_near_solution*

Problem
*******

Data
====
For :math:`t = 0 , \ldots , T - 1`,
:math:`y_t = (1 + t) + e_t`,
where :math:`e_t \sim \B{N}( 0, \sigma_y^2 )`.

p( y_t | u , theta )
====================
For :math:`t = 0 , \ldots , T - 1`,
:math:`y_t \sim \B{N}( u_t , \sigma_y^2 )`.

p( u | theta )
==============
For :math:`t = 0`, :math:`u_t \sim \B{N}( 0 , \theta_0^2 )`,
and for :math:`t = 1 , \ldots , T - 1`,
:math:`u_t - u_{t-1} \sim \B{N}( 0 , \theta_0^2 )`.

Command Arguments
*****************

random_seed
===========
This is a non-negative integer equal to the
seed for the random number generator,
to be specific,
:ref:`manage_gsl_rng@new_gsl_rng@s_in` used during the call to
``new_gsl_rng`` .

number_random
=============
This is a positive integer specifying the number of random effects.
This is also the number of time points and number of data values.

quasi_fixed
===========
This is either ``yes`` or ``no`` and is the value of
:ref:`derived_ctor@quasi_fixed` in the
``cppad_mixed`` derived class constructor.
The amount of memory used by the
:ref:`derived_ctor@mixed_derived` object,
after the information matrix is computed,
will be similar to after the initialization when *quasi_fixed* is no.

trace_optimize_fixed
====================
This is either ``yes`` or ``no`` .
If it is yes, a *print_level*  = 5
:ref:`trace<ipopt_trace-name>` of the fixed effects optimization
is included in the program output.
Otherwise the ipopt *print_level* is zero and
no such trace is printed.

ipopt_solve
===========
This is either ``yes`` or ``no`` .
If it is yes, the ``CppAD::ipopt::solve``
routine is used for optimizing the random effects,
otherwise ``CppAD::mixed::ipopt_random`` is used; see
:ref:`optimize_random@options@evaluation_method` .

bool_sparsity
=============
This is either ``yes`` or ``no`` .
If it is yes, boolean sparsity patterns are used for this computation,
otherwise set sparsity patterns are used.

hold_memory
===========
The CppAD memory allocator has a hold memory option will be set by

   ``CppAD::thread_alloc::hold_memory`` ( *hold_memory* );

where *hold_memory* is either ``yes`` or ``no`` .

derivative_test
===============
This is either ``yes`` or ``no`` .
If it is yes, the derivatives of functions used in the optimization
of the fixed effects are checked for correctness.
(This requires extra time).

start_near_solution
===================
This is either ``yes`` or ``no`` .
If it is yes, the initial point for the optimization
is the value of the fixed effects used to simulate the data.
Otherwise, the initial point is significantly different from this value.

Output
******
Each output name, value pair is written in as *name* = *value*
where the amount of spaces surrounding the equal sign is not specified.
All of the pairs listed above are output.
In addition, the following name value pairs are also output.

cppad_mixed_version
===================
The ``cppad_mixed`` version number.

ldlt_cholmod
============
is the ``bin/run_cmake.sh`` configuration option
:ref:`run_cmake.sh@ldlt_cholmod` .

optimize_cppad_function
=======================
is the ``bin/run_cmake.sh`` configuration option
:ref:`run_cmake.sh@optimize_cppad_function` .

ndebug_defined
==============
is the ``NDEBUG`` preprocessor symbol defined.
This should be yes (no) if the ``bin/run_cmake.sh`` configuration option
:ref:`run_cmake.sh@build_type` is ``release``
(``debug`` ).

actual_seed
===========
If *random_seed* is zero,
the system clock, instead of *random_seed* ,
is used to seed the random number generator.
The actual random seed *actual_seed* is printed
so that you can reproduce results when *random_seed* is zero.

initialize_bytes
================
Is the amount of heap memory, in bytes,
added to the program during its :ref:`initialize-name` call.
Note that more temporary memory may have been used during this call.
In addition, only memory allocated using ``CppAD::thread_alloc`` is
included.

initialize_seconds
==================
Is the number of seconds used by the derived class :ref:`initialize-name` call.

optimize_fixed_seconds
======================
Is the number of seconds used by the call to
:ref:`optimize_fixed-name` that is used to compute the
optimal fixed effects.

optimize_random_seconds
=======================
Is the number of seconds used by a single call to
:ref:`optimize_random-name` that is used to compute the
optimal random effects.

information_mat_seconds
=======================
Is the number of seconds used by the call to
:ref:`information_mat-name` that computes the observed information matrix.

sample_fixed_seconds
====================
Is the number of seconds used by the call to
:ref:`sample_fixed-name` that computes the
:ref:`number_sample_fixed<capture_xam.cpp@Command Arguments@number_fixed_samples>`
samples for the fixed effects.

final_bytes
===========
Is final amount of heap memory, in bytes, added and retained by the program.
Only memory allocated using ``CppAD::thread_alloc`` is included.

theta_0_estimate
================
Is the optimal estimate for :math:`\theta_0`; see the
:ref:`ar1_xam.cpp@Problem` definition.

ar1_xam_ok
==========
If this program passes it's correctness test,
*ar1_xam_ok* is yes and the program return code is ``0`` .
Otherwise *ar1_xam_ok* it is no and the return code is ``1`` .
{xrst_toc_hidden
   bin/ar1_xam.sh
}
Example
*******
The file :ref:`ar1_xam.sh-name` is an example using this program.

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

{xrst_end ar1_xam.cpp}