diff --git a/README.rst b/README.rst index b562ba94859244cf6193f3590b628c503dbf8fc0..9b804cad58b0e37a7b20c8cb0a909cc5d8d8fb87 100644 --- a/README.rst +++ b/README.rst @@ -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.