Skip to content
Snippets Groups Projects
Commit 02e55250 authored by Cristian Lalescu's avatar Cristian Lalescu
Browse files

update README 

I still need to put in a `host_information.py` discussion, as well as
fixing the install location of host_information...
parent 962ee609
No related branches found
No related tags found
1 merge request!23WIP: Feature/use cmake
Pipeline #45194 canceled
Stage: test
Hide whitespace changes
Inline Side-by-side
Showing
with 70 additions and 82 deletions
README.rst
+ 70
− 82
View file @ 02e55250
......@@ -58,36 +58,10 @@ Use a console; navigate to the ``bfps`` folder, and type:
**Full installation**
If you want to run simulations on the machine where you're installing,
you will need to call `compile_library` before installing.
you will need to use `cmake` to compile and install the full library.
Your machine needs to have an MPI compiler installed, the HDF5 C library
and FFTW >= 3.4 --- a detailed prerequisite installation list is
and FFTW >= 3.4 --- detailed instructions are
included at the end of this document.
The file `machine_settings_py.py` should be modified
appropriately for your machine (otherwise the `compile_library` command will most
likely fail).
This file will be copied the first time you run `setup.py` into
`$HOME/.config/bfps/machine_settings.py`, **where it will be imported from
afterwards** --- any future edits **must** be made to the new file.
You may, obviously, edit it afterwards and rerun the `compile_library` command as
needed.
.. code:: bash
python setup.py compile_library
python setup.py install
For `machine_settings.py`, please keep in mind to turn on optimizations
for production environments.
In particular, for clusters of unknown architecture it helps to log into
individual nodes and run the following command:
.. code:: bash
gcc -march=native -Q --help=target
The results can be used to then compile on the frontend node(s) without
using `-march=native` (since the frontend node may have different
architecture).
-------------
Documentation
......@@ -96,8 +70,8 @@ Documentation
While the code is not fully documented yet, basic information is already
available, and it is recommended that you generate the manual and go
through it carefully.
Please don't be shy about asking for specific improvements to the
current text.
Please do ask for specific improvements to the current text where it is
found lacking.
In order to generate the manual, navigate to the repository folder, and
execute the following commands:
......@@ -127,79 +101,93 @@ Installation with prerequisites
These installation steps assume that you have a working MPI compiler,
properly configured on your system (i.e. the various configure scripts
are able to find it).
If this is not the case, please consult the FFTW and HDF5 compilation
instructions for detailed instructions (`./configure --help` should be
enough).
are able to find it), as well as the `cmake` tool.
We recommend to specify the desired MPI C++ compiler by exporting the
environment variable `MPICXX` --- the BFPS cmake configuration looks for
this variable.
We also recommend that an environment variable `BFPS_OPTIMIZATION_FLAGS`
is defined appropriately.
In particular, for clusters of unknown architecture it helps to log into
individual nodes and run the following command:
.. code:: bash
gcc -march=native -Q --help=target
Detailed full installation instructions:
1. Make directory PREFIX on local fast partition.
1. Make directory PREFIX on a local fast partition.
2. Download, compile, install FFTW (latest version 3.x from http://www.fftw.org/).
Execute the following commands in order, feel free to customize
optimisation flags for your own computer (see http://www.fftw.org/fftw3_doc/Installation-on-Unix.html):
.. code:: bash
.. code:: bash
./configure --prefix=PREFIX --enable-float --enable-sse --enable-sse2 --enable-avx --enable-avx2 --enable-avx-128-fma --enable-avx512 --enable-mpi --enable-openmp --enable-threads
make
make install
./configure --prefix=PREFIX --enable-sse --enable-sse2 --enable-avx --enable-avx2 --enable-avx-128-fma --enable-avx512 --enable-mpi --enable-openmp --enable-threads
make
make install
./configure --prefix=PREFIX --enable-float --enable-sse --enable-mpi --enable-openmp --enable-threads
make
make install
./configure --prefix=PREFIX --enable-sse2 --enable-avx512 --enable-mpi --enable-openmp --enable-threads
make
make install
BFPS will try to find HDF5 using the FindFFTW from the Morse project.
If the package is installed in a non standard location, it is recommanded
to setup the environment variables: FFTW_DIR (or FFTW_INCDIR and FFTW_LIBDIR)
BFPS will try to find FFTW using the FindFFTW from the Morse project.
If the package is installed in a non standard location, it is recommanded
to setup the environment variables: FFTW_DIR (or FFTW_INCDIR and FFTW_LIBDIR).
3. Download, compile, install HDF5 (version 1.8.x, currently available
at https://portal.hdfgroup.org/display/support/HDF5+1.8.20#files).
We are using parallel I/O, therefore we use the plain C interface of HDF5:
We are using parallel I/O, therefore we must use the plain C interface of HDF5:
.. code:: bash
.. code:: bash
./configure --prefix=PREFIX --enable-parallel
make
make install
BFPS will try to find HDF5 using the regular FindHDF5.
Therefore, if the package is installed in a non standard location, it is recommanded
to setup the environment variable: HDF5_ROOT
./configure --prefix=PREFIX --enable-parallel
make
make install
3. This step may be ommited.
I recommend the creation of a virtual python3 environment (also under PREFIX) that will be used for installing bfps and dependencies.
BFPS will try to find HDF5 using the regular FindHDF5.
Therefore, if the package is installed in a non standard location, it is recommanded
to setup the environment variable: HDF5_ROOT.
3. Optional.
We recommend the creation of a virtual python3 environment (also under PREFIX) that will be used for installing bfps and dependencies.
Please see https://docs.python-guide.org/dev/virtualenvs/.
4. Clone bfps repository.
.. code:: bash
.. code:: bash
git clone git@gitlab.mpcdf.mpg.de:clalescu/bfps.git
git clone git@gitlab.mpcdf.mpg.de:clalescu/bfps.git
5. Go into bfps repository, execute
.. code:: bash
.. code:: bash
mkdir build
cd build
cmake ..
# possibly : cmake .. -DCMAKE_INSTALL_PREFIX=INSTALL_DIR
make ..
# to get a verbose compilation process, use VERBOSE=1 make
# make install
6. Using BFPS from an external project. Along with all the BFPS files
(lib and headers) can be found different cmake files
that contains all the information related to the compilation of BFPS.
It is possible to load this file in another CMake based application
to know the dependencies and paths.
For instance, the installation will create these files:
.. code:: bash
-- Installing: install/lib/BFPSConfig.cmake
-- Installing: install/lib/BFPS_EXPORT.cmake
-- Installing: install/lib/BFPS_EXPORT-noconfig.cmake
In case an information is not provided, it is necessary to update
the cmake input config file: bfps/cmake/BFPSConfig.cmake.in
mkdir build
cd build
cmake ..
# possibly : cmake .. -DCMAKE_INSTALL_PREFIX=INSTALL_DIR
make
# to get a verbose compilation process, use
VERBOSE=1 make
make install
6. If you used a custom install location (i.e. `CMAKE_INSTALL_PREFIX`)
you must include this location in the environment variable
`CMAKE_PREFIX_PATH`.
This ensures that the required `BFPSConfig.cmake` file is accessible for
future use by the package.
7. Using BFPS from an external project.
BFPS creates and installs 3 files alongside the C++ headers and
library:
.. code:: bash
-- Installing: install/lib/BFPSConfig.cmake
-- Installing: install/lib/BFPS_EXPORT.cmake
-- Installing: install/lib/BFPS_EXPORT-noconfig.cmake
In case these files provide incomplete information, it is necessary to update
the cmake input config file: bfps/cmake/BFPSConfig.cmake.in.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment