lines 5-186 of file: xrst/get_started.xrst

{xrst_begin get_started}
{xrst_spell
   cd
   cmake
   src
   py
   llsq
   obj
   csv
   grep
   sed
   ggrep
   gsed
   unix
   darwin
}

Get Started Using cmpad
#######################
The instructions below are for execution a bash shell.

* Items in italic font get replaced by the value you choose; e.g., *program* .
* Items in code font get entered as is; e.g., ``--time_setup`` .

System Requirements
*******************
The following packages should be installed using your system package manager:
{xrst_spell_off}
{xrst_comment BEGIN_SORT_THIS_LINE_PLUS_1}
autoconf ,
automake ,
bash ,
c++ ,
cmake ,
fortran .
git ,
libtool ,
python3 ,
swig ,
wget ,
{xrst_comment END_SORT_THIS_LINE_MINUS_1}
{xrst_spell_on}

sed and grep
============
You will need a gnu version of sed and grep.
These are named ``sed`` and ``grep`` on most unix systems,
but on Darwin (MacOS) they may be named ``gsed`` and ``ggrep`` .

Clone Repository
****************
Clone the cmpad git repository and change into its top source directory
with the commands:
{xrst_code sh}
git clone https://github.com/bradbell/cmpad.git cmpad.git
cd cmpad.git
{xrst_code}

Pick An AD Package
******************
Pick one AD package that has been implemented from the
:ref:`get_package@AD Package List` ; e.g. ``adolc`` .
We use *package* to denote this AD package below.
If *package* is ``none``, you will be timing the algorithm
instead of its derivative.

Install Package
***************
Create a local install of *package* in the ``build/release`` subdirectory
with the following commands:

| |tab| ``bin/get_package.sh release`` *package*


Build C++ Executable
********************
This step is only necessary if *package* is a C++ package:
{xrst_code sh}
cpp/bin/run_cmake.sh
{xrst_code}

You should see the following in the cmake output:

| |tab| ``cmpad_has_``\ *package* = 1

The value will be zero for the other
C++ packages, unless you installed some of them.
Now execute the following commands:
{xrst_code sh}
cd cpp/build
make
cd ../..
{xrst_code}


Setup Python Environment
************************
This step is only necessary if *package* is a Python package
( see :ref:`environment-name` ):
{xrst_code sh}
bash
build_type=release
source bin/environment.sh
{xrst_code}

This sets up a Python virtual environment that can be deactivated using the
``exit`` command
(which exits the shell started with the ``bash`` command above).

Choose Test Parameters
**********************
Each of the parameters below,
except for *program*,
has a default value that is used when the parameter is not specified.
Note that ``--time_setup`` is just a flag and has no corresponding value.
See :ref:`run_cmpad-name` for more discussion of these parameters and flags.

program
=======
If this is a C++ package, *program* is
``cpp/build/src/run_cmpad`` .
If it is a Python package, *program* is
``python/bin/run_cmpad.py`` .
There is no default value for this parameter.

file_name
=========
Choose a *file_name* where the output of the speed tests will be written
(default is ``cmpad.csv`` ).

algorithm
=========
Choose and :ref:`algorithm-name` (default is ``det_by_minor`` ).

min_time
========
Choose a minimum time, in seconds, over which to average
the computation rate (default is ``0.5`` ).

n_arg
=====
Size of the domain space for this use of the algorithm.
Note that for ``det_by_minor`` *n_arg* must be a square and
is the number of elements in the matrix (default is ``9`` ).

n_other
=======
This argument is algorithm specific; see the heading *n_other* for
:ref:`det_by_minor <det_by_minor@option@n_other>` ,
:ref:`an_ode <an_ode@option@n_other>` ,
:ref:`llsq_obj <llsq_obj@option@n_other>`
(default is ``0`` ).

--time_setup
============
If this flag is present on the command line, the setup time is included.
This is used to test what the speed comparisons would be for
algorithms where it is not possible to tape the floating point operations
and use that tape for different argument values.
For example, one can tape the ``det_by_minor`` operations for one size
of matrix and use that for different values of the matrix elements.


Run Seed Test
*************
Execute the following command.

| |tab| *program* \\
| |tab| |tab| ``-p`` *package* \\
| |tab| |tab| ``-f`` *file_name* \\
| |tab| |tab| ``-a`` *algorithm* \\
| |tab| |tab| ``-m`` *min_time* \\
| |tab| |tab| ``-n`` *n_arg* \\
| |tab| |tab| ``-o`` *n_other* \\
| |tab| |tab| ``--time_setup``

All of the lines above, except for *program* , are optional.
If a line is not present, the corresponding default value is used.
Running this program will add one line to *file_name* with
the test parameters and results.

{xrst_end get_started}