forked from GalacticDynamics-Oxford/Agama
-
Notifications
You must be signed in to change notification settings - Fork 0
/
INSTALL
102 lines (94 loc) · 6.56 KB
/
INSTALL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
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, go to the root folder of the archive (containing setup.py) and run
python setup.py install --user
(or python3 with the same arguments), and follow the instructions.
(Note that the '--user' argument appears to be unnecessary for Anaconda).
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 to skip the confirmation questions.
Note that starting from Python 3.10, running "setup.py install" is deprecated;
the suggested alternative, which can be used with earlier versions as well, is to use pip:
in the same folder, you may run
pip install --user ./
or even without unpacking, just run
pip install --user agama.zip
or install from the PyPI repository (which downloads the latest commit archive from github):
pip install --user agama
Note that pip hides most of the messages printed during installation, but the questions
requiring user input should nevertheless appear on the screen.
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
(most likely $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".
In the manual mode, follow these steps:
1a. Install the required libraries (presently only GSL >= 1.15, configure 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, and actually preferred,
is 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 is built and placed into lib/agama.so,
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 "UNKNOWN" 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.