INSTALL

This is the AGAMA galaxy modelling framework. To get it working on your computer:

Download and unpack https://github.com/GalacticDynamics-Oxford/Agama/archive/master.zip

There are two alternative ways of building and installing the library:
- automatic, using the provided script setup.py (preferred)
- manual

In the automatic mode, the configuration and the installation of third-party libraries
needed by the C++ library are managed by the setup.py script, which in the end compiles
the Python extension module and all C++ executables (tests and example programs).
Note that the following Python packages are prerequisites that need to be installed before
running setup.py: numpy, setuptools, wheel; in addition, scipy and matplotlib are recommended
(they are used by many example programs, but are not strictly necessary).
To install the library in recent python distributions (3.10 and newer), unpack the archive,
go to its root folder (the one containing setup.py) and run
  pip install .
One may run pip without unpacking the archive:
  pip install agama.zip
or even install from the PyPI repository (this procedure is equivalent to downloading
the archive with the latest commit from github and feeding it to pip):
  pip install agama
In older python distributions, one may run the setup.py script directly:
  python setup.py install
In both cases, one may need to add a command-line argument '--user' to install the package for
the current user only instead of system-wide, although this is not necessary with Anaconda
or various virtual environment systems.

The setup script may ask permission for downloading/installing additional third-party
libraries (most importantly, GSL); if the installation needs to be fully automated,
one may add '--yes' to the command-line arguments of setup.py to skip the confirmation questions.
For the pip-driven installation to work, one needs to have the following packages pre-installed:
numpy, setuptools and wheel. The '--yes' flag cannot be directly passed to pip; instead, run
  pip install . --config-settings --build-option=--yes
or for older version of pip,
  pip install . --install-option=--yes
One may also need to add another flag '--no-build-isolation' when installing via pip.
Note that pip hides most of the messages printed during installation, but the questions
requiring user input should nevertheless appear on the screen, although they may possibly be
interleaved with other output from the compiler. Passing a '-v' flag to pip disables hiding
the messages from the compilation.

The setup.py script will determine the supported compilation options, download and compile
missing third-party libraries, compile the Agama library itself and the Python interface for it,
and install it to the user-specific site-packages folder in your current python distribution
(e.g., $HOME/.local/lib/pythonX.Y/site-packages/agama).

On Windows, the compiler (MSVC) requires a somewhat different treatment, but the setup.py script
is adapted for this situation (it runs a different build program, nmake, and uses Makefile.msvc
instead of ordinary Makefile, still creating a Makefile.local automatically during the setup).
Before running the setup script from Windows terminal, one needs to initialize the command-line
build tools by running "vcvarsall.bat".

The Makefile contains instructions for building both static and shared versions of the library
(on Linux/MacOS: agama.a and agama.so, on Windows+MSVC: agama.lib and agama.pyd).
The shared library serves as the python extension module, and is also linked to all executable
programs by default; however, it is possible to link them to the static library instead,
by setting the environment variable AGAMA_STATIC to any non-empty value. In this case, executable
files are much larger in size, but are fully autonomous (i.e. can be copied anywhere), whereas
with the shared linking, the file agama.so must be present in the same folder as the executable.
On Windows+MSVC, static linking is the only option.

In the manual mode, follow these steps:

1a. Install the required libraries (presently only GSL >= 1.15, built with CFLAGS=-fPIC):
    ftp://ftp.gnu.org/gnu/gsl/gsl-latest.tar.gz
1b. Although not compulsory, you may want to download and install optional libraries:
    - Eigen library for highly optimized linear algebra routines - highly recommended,
    (in its absense the non-optimized substitutes from GSL will be used);
    its use slows down compilation quite dramatically, but this more than pays off at runtime.
    http://eigen.tuxfamily.org/
    - GLPK for solving linear optimization problems (not needed if CVXOPT is available):
    http://www.gnu.org/software/glpk/
    - CVXOPT for solving linear and quadratic optimization problems (requires Python):
    http://cvxopt.org/
    the easiest way to install it is to get the complete binary distribution via
    > pip install --user cvxopt
    and then also download the source and add the path to headers to INCLUDES (see below).
    either GLPK or (preferrably) CVXOPT are required for non-parametric DF or Schwarzschild modelling.
    - UNSIO library for reading/writing N-body snapshots in various formats:
    http://projets.lam.fr/projects/unsio
    (without it only the text format is supported).
    - Cuba library for multidimensional integration (the alternative, which is actually preferred,
    is the Cubature library that is bundled with this distribution):
    http://www.feynarts.de/cuba/
    Note: since Agama is compiled to a shared library, any external libraries to be statically linked
    with it need to be compiled with -fPIC flag.
2.  You need to create a file called Makefile.local, which is included by the Makefile
    and contains path names and compiler flags specific to your own computer.
    An example is given in Makefile.local.template (you will need to change the pathnames).
    The reason for keeping it separate from the main Makefile is that the latter may be
    updated from the repository while keeping the local settings unchanged.
    This file is also created by setup.py, so you may re-use it later if you need to manually
    recompile the library.
3.  Run 'make' to compile everything:
    first the shared library agama.so and the static library libagama.a are built,
    then the tests and example programs are compiled and placed into exe folder.
4.  Run 'make test' to run a series of tests (may need up to a few minutes).
5.  In order to make the Python extension module available for import, it should be either copied
    to its site-packages folder, or the path to it be added to PYTHONPATH environment variable.
    If the root folder of the distribution (the same one in which this file resides) is called
    /path/to/agama, the extension module is located in /path/to/agama/agama.so
    (this shared library may be directly imported by python):
    export PYTHONPATH=$(PYTHONPATH):/path/to/agama
    Alternatively, the root folder itself may be used as the 'package directory': it contains
    __init__.py which loads both the C++ shared library from ./agama.so and some Python routines
    from py/pygama.py, and places them into the same namespace for convenience.
    Hence PYTHONPATH would be augmented with '/path/to'
    since this is the folder containing a sub-folder named 'agama'.
    To make it permanently available, you may add this line to .bashrc or its analog.

If you have the NEMO stellar-dynamics toolbox installed, the make command will also copy agama.so
to the folder $(NEMOOBJ)/acc/, making it available as an external potential for nemo programs
(in particular, gyrfalcon).

If you have the AMUSE framework installed, the make command will also build a separate AMUSE plugin
and place it into the folder with other community codes (it also contains an example script).

After compilation, you may wish to run some tests - either in the folder where the library has been
compiled, or in the site-packages/agama folder where it was installed. This is done by running
> python setup.py test
or
> make test
and should take no more than a few minutes, displaying "OK" or "FAILED" for each test program
(or possibly "SKIPPED" for a few Python programs that rely on external libraries such as astropy or
amuse, which is not a critical error).
Of course one may run these tests individually (C++ programs compiled and placed into exe/ subfolder,
or python scripts in the py/ subfolder), in which case they print out more information.
They can also serve as the examples of usage, together with other (non-test) example programs.