How to compile and install QDYN

Note

See the Compilation and Installation Tutorial for a complete step-by-step guide on installing QDYN on a basic Ubuntu system with the default options. This how-to covers compilation on other platforms or with nonstandard options.

How to compile the tests

If you want to compile all tests without running them, you can do

make preptest

To compile just a single test, you have two options. Either run something like

make tests/pulsetests

or go into the tests/pulsetests subfolder and simply run make.

How to compile with OpenBLAS

QDYN depends on several external packages, most of which are compiled and installed alongside libqdyn.a itself. The only external dependencies that are not distributed with QDYN are BLAS and Lapack. On systems where they are not available, it is recommended to install OpenBLAS manually. OpenBLAS contains both BLAS and Lapack routines. Once OpenBLAS is installed, passing the --openblas option to the configure script will generate a Makefile that uses it. See ./configure --help for details.

How to develop QDYN without conda

By default, the python environment used for testing and building the documentation is managed via Conda. If you do not want to install Conda, you can use

./configure --no-conda

This uses the built-in python -m venv to manage the python environment. It only works if your default python (the python running the configure script) is at least Python 3.4.

You may also have to install Pandoc manually.

While the Conda environment is determined by the file environment.yml in the project root, the --no-conda option uses requirements.txt instead.

How to clean up a compilation

After compilation, you may return to a clean state by running

make clean

This removes all files created by make, but not those files created by the .configure script. Consequently, after running make clean, you do not need to run ./configure again. To also remove the files created by ./configure, you must run

make distclean

Afterwards, you must run ./configure again before any make

make clean

To remove all files added to your system from a call to make install, run

make uninstall

To remove all files created by make preptest or make test (but leave the compiled components of the QDYN library itself untouched), you may run

make test-clean

How to compile in parallel

You can instruct make to use multiple cores by passing it the -jN flag, speeding up the compilation significantly. E.g.

make -j4 all

will compile the library using 4 cores. A major caveat is that you will not always see error messages generated by the compiler. Thus, you must only use the -jN flag only if you know that the compilation will succeed. Also, the combination

make clean
make -j4 test

will not work. When using paralellization, the tests may only be compiled after the compilation of QDYN itself is complete. The following will work:

make clean
make -j4 all && make -j4 preptest
make test

How to see the available make targets

Run

make help

to see a documented list of make targets.

How to install QDYN-pylib

QDYN includes a qdyn Python package (“QDYN-pylib”) that includes routines for generating input data for QDYN programs and analyzing output data.

See the QDYN-pylib API for details.

You can install it with

make install-qdynpylib

This will install qdyn into the current Python interpreter. To install it into a specific other interpreter, you could run

/path/to/python -m pip install ./qdynpylib

from the root of the QDYN repository.

Alternatively, qdyn can be installed from PyPI, see QDYN-pylib Development.

How to compile QDYN on Windows

Warning

The following instructions for Windows were written in 2010 and have not been updated since.

The following explains how to compile qdyn on Windows using gfortran, in a MinGW environment.

  1. Install MinGW

    Install MinGW using the graphical installer, as described in the MinGW Getting Started Guide. Make sure to install all components, especially the Fortran Compiler, the MSYS Basic System, and the MinGW Developer Toolkit.

    Also make sure the set the $PATH to include C:\MinGW\bin, as described in the section “Environment Settings” in the MinGW Getting Started Guide.

  2. Install BLAS/LAPACK

    See the Instruction in the GCC Wiki. In short:

    • Download and unpack Lapack 3.2.1

    • Downlaod and unzip the MinGW Makefile & Script (read the readme.txt file) into the same folder as Lapack

    • Open a Command Prompt (cmd.exe), go to the folder where you upacked lapack, and run the makelibs.bat batch file (this is where C:MinGW\bin needs to be in your $PATH). Since makelibs.bat is a DOS batch file, it cannot be run from an MSYS shell!

    • Rename the resulting blas.a and lapack.a to libblas.a and liblapack.a, respectively

  3. Compile QDYN

    • Open an MSYS shell (by running C:\MinGW\msys\1.0\msys.bat). A cmd.exe Command prompt will not do, as the QDYN makefile assumes to be in a gnu environment.

    • Obtain the QDYN library and put it in ~/qdyn.

    • Copy the libblas.a and liblapack.a files from Step 2 into the qdyn folder, so that the compiler will be able to find them.

    • In ~/qdyn, Run make FC=gfortran clean test install

  4. (optional): Create def/dll file for use with Visual Studio

    dllwrap --export-all-symbols *.o ext_libs/dfftpack/*.o ext_libs/lbfgsb/*.o -lgfortran -llapack -lblas -fopenmp -L. --output-def qdyn.def -o qdyn.dll