-------------------------------------------
lines 5-341 of file: xrst/install/unix.xrst
-------------------------------------------

{xrst_begin install_unix}
{xrst_spell
  cmake
  config
  dev
  devel
  eigen
  fortran
  grep
  gsl
  install install
  matplotlib
  modversion
  numpy
  pc
  pkg
  rpath
  scipy
  suitesparse
  txt
}

Installing dismod_at in Unix
############################
{xrst_toc_hidden
    bin/install_settings.py
    bin/example_install.sh
}

System Requirements
*******************
The following programs are required by dismod_at
and should have standard system installs:

C++ Compiler
============
The ``dismod_at`` program can be compiled by any C++98 compliant compiler;
e.g., ``g++`` .
(Note that a C++11 compiler would be better.)

Fortran Compiler
================
A fortran compiler is required by ``ipopt`` which in turn
is required by ``dismod_at`` .

git
===
The `git <https://git-scm.com/>`_ program,
a source code version control system,
is required by ``dismod_at`` .

cmake
=====
The `cmake <https://cmake.org/>`_ program,
which installs other programs,
is required by ``dismod_at`` .

pkg-config
==========
The `pkg-config <https://en.wikipedia.org/wiki/Pkg-config>`_
program must be installed.

python3
=======
The `python3 <https://www.python.org/>`_,
programming language.
The packages listed in the
`standard library <https://docs.python.org/3/library/>`_
are assumed to be present.
You need to have the following additional python packages:
``numpy`` , ``matplotlib`` , ``scipy`` , ``build`` .

sqlite3
=======
The `http://sqlite.org/ <https://sqlite.org/index.html>`_ library,
version 3.7.11 (released on 2012-03-20) or higher; see
`sqlite releases <https://sqlite.org/changes.html>`_.
Note that the development headers are required; e.g.,
on Fedora or Red-Hat one needs to install ``sqlite-devel`` .

gsl
===
`gsl <https://www.gnu.org/software/gsl/>`_,
the gnu scientific library.
Note that the development headers are required; e.g.,
on Fedora or Red-Hat one needs to install ``gsl-devel`` .

suitesparse
===========
The `suitesparse <https://people.engr.tamu.edu/davis/suitesparse.html>`_
sparse matrix package.
Note that the development headers are required; e.g.,
on Fedora or Red-Hat one needs to install ``suitesparse-devel`` .

eigen
=====
The `eigen <https://libeigen.gitlab.io/eigen/docs-nightly/>_`
{xrst_comment
    `eigen <https://eigen.tuxfamily.org/index.php?title=Main_Page>`_
}
linear algebra package.

Download dismod_at.git
**********************
After installing the requirements above,
use the following command to get the current version of dismod_at:

| |tab| ``git clone https://github.com/bradbell/dismod_at.git dismod_at.git``
| |tab| ``cd dismod_at.git``

You can determine the *git_hash* and version number
corresponding to this checkout of the master branch using the commands:

| |tab| ``git show-ref`` | ``grep`` ``'refs/heads/master'``
| |tab| ``grep`` '^ ``SET`` ( ``dismod_at_version`` ' ``CMakeLists.txt``

You can checkout an old version corresponding to a specific *git_hash* ,
and check its version number, using the commands:

| |tab| ``git checkout -q`` *git_hash*
| |tab| ``grep`` '^ ``SET`` ( ``dismod_at_version`` ' ``CMakeLists.txt``

Paths
*****
This discussion is intended to help with the install of the
special requirements and dismod_at (see below).

Adding to a Path
================
The instructions below may require you to add to a *path_name* .
Use the command

    ``echo $`` *path_name*

to see if your initial path is empty. If it is empty,
use the command

    ``export`` *path_name* = *directory*

to add *directory* to the path.
If it is non-empty, use

    ``export`` *path_name* =" ``$`` *path_name* : *directory* "

to add *directory* to the path.

PKG_CONFIG_PATH
===============
After ``sqlite3`` and ``gsl`` are installed
the following commands should work:
::

    pkg-config sqlite3 --modversion
    pkg-config gsl     --modversion

If one of them fails, a corresponding directory is missing
from the ``PKG_CONFIG_PATH`` environment variable.
If *prefix* is the prefix where ``gsl`` was installed,
the command

    ``find -L`` *prefix* ``-name gsl.pc 2> /dev/null``

should find the directory where ``gsl.pc`` is located.
After :ref:`install_unix@Special Requirements@cppad_mixed`
is installed (see below),
the following command should work:

    ``pkg-config`` *pkg* ``--modversion``

where *pkg* is any of the required packages.
(There is one exception, the eigen package uses ``eigen3`` for
*pkg* above.)
If one of these commands fails,

    ``find -L`` *dismod_at_prefix* ``-name`` *pkg* . ``pc 2> /dev/null``

should find the directory where *pkg* . ``pc`` is located;
see :ref:`install_settings.py@dismod_at_prefix` .

LD_LIBRARY_PATH
===============
The library locations are set at link time using cmake's
`always full rpath <https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/RPATH-handling>`_
commands.
Hence, it should not be necessary to set ``LD_LIBRARY_PATH`` in order for
``dismod_at`` to work.

PATH
====
After you install dismod_at (see below)
you should be able to execute the command

    ``dismod_at``

from any directory.
If you get the error ``dismod_at: command not found`` ,
you will need to add the binary install directory to you path.
Use the following command to find it:

    ``find -L`` *dismod_at_prefix* ``-name dismod_at 2> /dev/null``

see :ref:`install_settings.py@dismod_at_prefix` .

PYTHONPATH
==========
After you install dismod_at
you should be able to execute the following commands:

| |tab| *python3*
| |tab| ``import dismod_at``
| |tab| ``quit`` ()

where *python3* is your
:ref:`install_settings.py@python3_executable` .
If you get the error ``No module named 'dismod_at'`` ,
you will need to add the directory where the module is installed
to your python path.
Use the following command to find it:

    ``find -L`` *dismod_at_prefix* ``-name site-packages 2> /dev/null``

Special Requirements
********************
The packages listed below are required by dismod_at
and may not have standard system installs

install_settings.py
===================
The settings in :ref:`bin/install_settings.py<install_settings.py-name>`
are used by the
scripts that install the special requirements.
You must first change
these settings to the appropriate values for your system before
running the install scripts below:


ipopt
=====
The `Ipopt <https://github.com/coin-or/Ipopt>`_
optimization package.
The script ``bin/get_cppad_mixed.sh`` (see below)
includes an install of ipopt.

cppad
=====
The `cppad <https://cppad.readthedocs.io/latest/>`_
C++ algorithmic differentiation package.
The script ``bin/get_cppad_mixed.sh`` (see below)
includes an install of cppad.

cppad_mixed
===========
The `cppad_mixed <https://bradbell.github.io/cppad_mixed>`_
C++ random effects modeling package.
Starting in the ``dismod_at.git`` directory, the command

    ``bin/get_cppad_mixed.sh``

can be used to install ipopt, and cppad_mixed.
This script also serves as an example of how to install cppad_mixed.

dismod_at
*********
The steps above should only need to be executed once, not for
each new version of ``dismod_at``
(unless the :ref:`release_notes-name` say otherwise).
The steps below will need to be executed each time you install
a new version of ``dismod_at`` :

Setup
=====
The file
:ref:`bin/install_settings.py<install_settings.py-name>` has setting that
you should change so they correspond to your machine.

Cmake Command
=============
After changing ``bin/install_settings.py`` to work for your system,
in the ``dismod_at.git`` directory
execute the following command:
::

    bin/run_cmake.sh

The script also serves as an example of how to install dismod_at.

Build
=====
The following command is option and will just build the
executable program ``build/devel/dismod_at`` :
::

    cd build
    make
    cd ..

Test
====
The following commands are optional and will,
build the dismod_at executable,
build the examples and tests,
and run the examples, correctness tests, and speed tests:
::

    cd build
    make check
    make speed
    cd ..

Some of the tests use different random number simulations each time
they are run.
If you get a correctness check failure during a ``make check``
or ``make speed`` , try running the make command again.
If you get the same correctness check fails twice in a row,
there probably is a problem and
you should get help from the ``dismod_at`` development team.

Install
=======
The following command will,
build the dismod_at library and executable if necessary,
and install dismod_at:
::

    cd build
    make install install_python
    cd ..

Example
*******
The file :ref:`example_install.sh-name` contains an example
install of ``dismod_at`` .
The section :ref:`get_started-name` contains a list of examples and tests
of using ``dismod_at`` .
These tests are run as part of the ``make check`` command above.

{xrst_end install_unix}