From 6557cf7396764e92d3052e6d6599332ea36e0f41 Mon Sep 17 00:00:00 2001 From: Tuomo Salmi Date: Thu, 16 Feb 2023 10:16:36 +0100 Subject: [PATCH] Python3 installation update (#289) * Fixes #277; MultiNest source corrected. * Fixes #283; Change back to requiring PyMultiNest installation from source. * Fixes xpsi environment name, and small text modifications. * Fixes #274; Mentioned that blackbody extension needed for the Post-Processing tutorial. * Fixes #275; Broken link to Modeling tutorial fixed in Synthetic data example. * Update CALMIP installation instructions resolving Issue #288 * Fixing typos and links in documentation * Links corrected to Riley+2019 in Python docstrings. --------- Co-authored-by: Sebastien Guillot --- CHANGELOG.rst | 2 +- docs/source/HPC_systems.rst | 95 ++++++++++++++------ docs/source/Module_generator_tutorial.rst | 4 +- docs/source/Post-processing.ipynb | 3 +- docs/source/hotregion.rst | 4 +- docs/source/install.rst | 93 +++++++++++-------- examples/examples_fast/Post-processing.ipynb | 3 +- examples/examples_fast/Synthetic_data.ipynb | 2 +- xpsi/PostProcessing/_pulse.py | 2 +- xpsi/PostProcessing/_residual.py | 2 +- xpsi/PostProcessing/_spectrum.py | 2 +- xpsi/Prior.py | 5 +- xpsi/likelihoods/__init__.py | 7 +- 13 files changed, 148 insertions(+), 76 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index bf5fd1f7..f2b17618 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -72,7 +72,7 @@ Changed Deprecated ^^^^^^^^^^ -*The Python2 version of X-PSI (v1.2.1) is now considered deprecated, although documentation and tutorials are still available. +* The Python2 version of X-PSI (v1.2.1) is now considered deprecated, although documentation and tutorials are still available. Removed ^^^^^^^ diff --git a/docs/source/HPC_systems.rst b/docs/source/HPC_systems.rst index 3094cb2c..18376ed9 100644 --- a/docs/source/HPC_systems.rst +++ b/docs/source/HPC_systems.rst @@ -310,7 +310,7 @@ For example job scripts, see the Helios example in :ref:`example_job`. .. _CALMIPsystem: -CALMIP (not updated for python3 yet) +CALMIP ------------------------------------ `CALMIP `_ is the supercomputer of `Université Fédérale de Toulouse `_ @@ -323,60 +323,105 @@ In your ``$HOME`` file system, from the login node, start by loading the necessa .. code-block:: bash module purge - module load python/2.7.14 + module load conda module load cmake module load intel/18.2.199 module load intelmpi/18.2 module load gsl/2.5-icc -Then, install/update the required python packages: +Then, create the conda environnnement and Install python packages with conda (or pip): .. code-block:: bash - pip install emcee==3.0.2 --user - pip install --upgrade numpy --user - pip install --upgrade Cython --user + conda create -n xpsi --clone base + conda activate xpsi + conda install numpy scipy matplotlib wrapt + conda install cython + conda install h5py + conda install -c conda-forge fgivenx pip install schwimmbad --user +Point to the Intel compilers -Install MPI4PY in your ``$HOME``: +.. code-block:: bash + + export FC=ifort + export CC=icc + export CXX=icpc + +Install mpi4py in your ``$HOME`` (e.g. in ``~/Softwares``): .. code-block:: bash - wget https://bitbucket.org/mpi4py/mpi4py/downloads/mpi4py-3.0.0.tar.gz - tar -xvf mpi4py-3.0.0.tar.gz - cd mpi4py-3.0.0 - python setup.py install --user + mkdir Softwares + cd Softwares + wget https://bitbucket.org/mpi4py/mpi4py/downloads/mpi4py-3.1.4.tar.gz + tar zxvf mpi4py-3.1.4.tar.gz + cd mpi4py-3.1.4 + python setup.py build + python setup.py install + # Test on login node: + mpiexec -n 4 python demo/helloworld.py -Download the MultiNest package in your ``$HOME``: + +Download and Install the MultiNest package in your ``$HOME`` (e.g. in ``~/Softwares``: .. code-block:: bash - git clone https://github.com/farhanferoz/MultiNest.git ~/multinest - cd ~/multinest/MultiNest_v3.11_CMake/multinest + cd ~/Softwares + git clone https://github.com/farhanferoz/MultiNest.git ./MultiNest + cd MultiNest/MultiNest_v3.12_CMake/multinest/ mkdir build cd build + cmake -DCMAKE_INSTALL_PREFIX=~/Softwares/MultiNest \ + -DCMAKE_{C,CXX}_FLAGS="-O3 -xCORE-AVX512 -mkl" \ + -DCMAKE_Fortran_FLAGS="-O3 -xCORE-AVX512 -mkl" \ + -DCMAKE_C_COMPILER=mpiicc \ + -DCMAKE_CXX_COMPILER=mpiicpc \ + -DCMAKE_Fortran_COMPILER=mpiifort .. + make + ## Check that librairies have been compiled and are present + ls ../lib -Compile MultiNest in your ``$HOME``, following recommendation from CALMIP support: +Install pymultinest in your ``$HOME`` (e.g. in ``~/Softwares``: .. code-block:: bash - cmake -DCMAKE_INSTALL_PREFIX=~/multiNest \ - -DCMAKE_{C,CXX}_FLAGS="-O3 -xCORE-AVX512 -mkl" \ - -DCMAKE_Fortran_FLAGS="-O3 -xCORE-AVX512 -mkl" \ - -DCMAKE_C_COMPILER=mpiicc \ - -DCMAKE_CXX_COMPILER=mpiicpc \ - -DCMAKE_Fortran_COMPILER=mpiifort .. - make + cd ~/Softwares + git clone https://github.com/JohannesBuchner/PyMultiNest.git ./pymultinest + cd pymultinest + python setup.py install + + # Add MultiNest to Library Path to test PyMultiNest (action to do for every job to run) + export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/Softwares/MultiNest/MultiNest_v3.12_CMake/multinest/lib + + # Test pymultinest + mpiexec -n 2 python pymultinest_demo.py + + +Clone and Install X-PSI in ~/Softwares/ + +.. code-block:: bash + + cd ~/Softwares + git clone https://github.com/xpsi-group/xpsi.git + cd xpsi/ + LDSHARED="icc -shared" CC=icc python setup.py install + + # Test installation + cd ~/ + python -c "import xpsi" + + ## Ignore the warnings about GetDist, NestCheck, CornerPlotter + ## which are only for PostProcessing (not usually performed on HPC systems). + Set up your library paths: .. code-block:: bash - export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/multiNest/MultiNest_v3.12_CMake/multinest/lib - export PYTHONPATH=$HOME/.local/lib/python2.7/site-packages/:$PYTHONPATH + export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/Softwares/MultiNest/MultiNest_v3.12_CMake/multinest/lib export LD_PRELOAD=$MKLROOT/lib/intel64/libmkl_core.so:$MKLROOT/lib/intel64/libmkl_sequential.so - Note that the ``module`` commands, and the library path ``commands`` above will have to be added in your SBATCH script (see :ref:`example_job`) to execute a run. diff --git a/docs/source/Module_generator_tutorial.rst b/docs/source/Module_generator_tutorial.rst index e4767f45..7007eb6d 100644 --- a/docs/source/Module_generator_tutorial.rst +++ b/docs/source/Module_generator_tutorial.rst @@ -5,8 +5,8 @@ Module generator tutorial To develop models in X-PSI, users are recommended to to create custom derived classes for the different X-PSI model components (e.g. ``Prior``, ``Photosphere``, etc.) that require further modification. Examples of such `Custom` classes -can be found in :ref:`./Modeling.ipynb`. These classes are preferably to be written as distinct modules within a project -directory rather than in a notebook as is done in :ref:`./Modeling.ipynb`. The modules can then be imported by a `Main` +can be found in :doc:`Modeling`. These classes are preferably to be written as distinct modules within a project +directory rather than in a notebook as is done in :doc:`Modeling`. The modules can then be imported by a `Main` script, which can be executed using an MPI command in a shell to exploit parallelism for resource-intensive likelihood evaluations. diff --git a/docs/source/Post-processing.ipynb b/docs/source/Post-processing.ipynb index a0af530f..82078dd4 100644 --- a/docs/source/Post-processing.ipynb +++ b/docs/source/Post-processing.ipynb @@ -11,7 +11,8 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "In this tutorial we demonstrate the functionality and posterior operations supported by the [PostProcessing](postprocessing.rst) module by operating with the example posterior samples found in ``examples/examples_fast/Outputs``. A previous version of this Post-processing tutorial operating with the posterior samples reported by [Riley et al. (2019)](https://ui.adsabs.harvard.edu/abs/2019ApJ...887L..21R/abstract) is given [here](https://github.com/xpsi-group/xpsi/blob/cff82f299da93ca97c84ffb34390ab077cc001b3/docs/source/postprocessing_tutorial.ipynb) with more post-processing examples (however, using model files which are not supported anymore)." + "In this tutorial we demonstrate the functionality and posterior operations supported by the [PostProcessing](postprocessing.rst) module by operating with the example posterior samples found in ``examples/examples_fast/Outputs``. A previous version of this Post-processing tutorial operating with the posterior samples reported by [Riley et al. (2019)](https://ui.adsabs.harvard.edu/abs/2019ApJ...887L..21R/abstract) is given [here](https://github.com/xpsi-group/xpsi/blob/cff82f299da93ca97c84ffb34390ab077cc001b3/docs/source/postprocessing_tutorial.ipynb) with more post-processing examples (however, using model files which are not supported anymore).\n", + "To run this tutorial, you should also install X-PSI with the default (blackbody) atmosphere extension module, which is compiled when installing X-PSI with default settings." ] }, { diff --git a/docs/source/hotregion.rst b/docs/source/hotregion.rst index a4b41d76..f9071d39 100644 --- a/docs/source/hotregion.rst +++ b/docs/source/hotregion.rst @@ -19,8 +19,8 @@ Representation of the ``HotRegion`` class instantiation options ``omit`` and ``c Representation of a ``HotRegion`` instance configuration, when ``omit`` or ``cede`` are set to ``True``. A description of these parameters is also presented below. If ``is_antiphased = True``, the parameter ``phase_shift`` is added to :math:`\pi` radians. For example, if ``phase_shift = 0``, the omission or the superseding region (respectively on the left and right side of the image) is in anti-phase with the observer meridian (i.e., its azimuth is :math:`\pi`). .. autoclass:: xpsi.HotRegion.HotRegion - :members: _HotRegion__construct_cellMesh, _HotRegion__compute_rays, - _HotRegion__compute_cellParamVecs, embed, + :members: __construct_cellMesh, __compute_rays, + __compute_cellParamVecs, embed, psi, integrate, num_rays, sqrt_num_cells, leaves, phases, set_phases, phases_in_cycles, print_settings, num_cells, cede, concentric diff --git a/docs/source/install.rst b/docs/source/install.rst index aef643ae..e2297377 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -11,7 +11,7 @@ X-PSI is an open-source software package that is available on `GitHub git clone https://github.com/xpsi-group/xpsi.git In this page, we lay down the instructions for installing X-PSI and all the -necessary pre-requisites on your local self-administered system. +necessary prerequisites on your local self-administered system. .. note:: @@ -21,7 +21,7 @@ necessary pre-requisites on your local self-administered system. .. _dev_env: -Prerequisite Python packages +Prerequisite Python Packages ---------------------------- X-PSI was originally developed in Python 2.7 and was ported to Python 3 as of @@ -39,7 +39,7 @@ contents are: .. code-block:: bash - name: xpsi + name: xpsi_py3 channels: - defaults dependencies: @@ -64,12 +64,12 @@ To create a virtual environment from this file: conda env create -f /basic_environment.yml -If Conda does not solve the environment dependencies, you may need to create +If conda does not solve the environment dependencies, you may need to create an environment manually via .. code-block:: bash - conda create -n xpsi + conda create -n xpsi_py3 and then install the core dependencies listed in ``basic_environment.yml`` via conda. @@ -78,7 +78,7 @@ Activate the environment as: .. code-block:: bash - conda activate xpsi + conda activate xpsi_py3 .. note:: @@ -86,17 +86,24 @@ Activate the environment as: ENVIRONMENT.** Pay special attention to reactivate the environment if you ever have to restart the kernel. -Next, install the packages -`pymultinest `_ and -`mpi4py `_ which are required for +Next, install +`mpi4py `_ which is required for nested sampling: .. code-block:: bash - conda install -c conda-forge mpi4py pymultinest - -Note that pyMultiNest is only a wrapper and requires MultiNest to run properly. -See below for installation instructions (:ref:`multinest`). + conda install -c conda-forge mpi4py + + +We also need `PyMultiNest `_ +(the interface to the MultiNest library) for nested sampling. +However, `conda install -c conda-forge pymultinest` might try +to install dependencies in the environment, +including binaries for MPI, BLAS/LAPACK, and a Fortran compiler, +all in order to install MultiNest. Moreover, the MultiNest version +listed is a minor release too low to satisfy all our needs. +Thus, see the PyMultiNest instructions below. + Then, install optional packages `getdist `_, `h5py `_, @@ -117,11 +124,12 @@ In addition, some optional miscellaneous packages are: .. _nonpython: -Prerequisite Non-Python Packages --------------------------------- +Prerequisite Non-Python Packages and PyMultiNest +------------------------------------------------ -X-PSI has several dependencies that are not Python packages. Build and -install guidelines are given below. +X-PSI has several dependencies that are not Python packages, +or which are Python packages but need to be installed from source (PyMultiNest). +Build and install guidelines are given below. GSL ^^^ @@ -178,22 +186,20 @@ system and X-PSI can be installed locally without sampling functionality, it is advisable to install MultiNest on your personal machine to gain experience in application to inexpensive test problems. In addition, to leverage some capabilities of sample post-processing software you -`require MultiNest `_ ``v3.12``. +`require MultiNest `_ ``v3.12``. To build the MultiNest library, you require an MPI-wrapped Fortran compiler (e.g., `openmpi-mpifort `_ from Open MPI). .. note:: - The following assumes you have installed PyMultiNest and mpi4py. If you + The following assumes you have installed mpi4py. If you have not already installed it through the ``environment.yml`` file, you may - do so e.g. via ``conda install -c conda-forge pymultinest mpi4py``. + do so e.g. via ``conda install -c conda-forge mpi4py``. -We follow -`this guide `_ for -installation of MultiNest. Prerequisites for MultiNest are c and fortran -compilers (e.g. ``gcc``, ``gfortran``), ``cmake``, ``blas``, ``lapack``, and -``atlas``: +Prerequisites for MultiNest are c and fortran +compilers (e.g. ``gcc`` and ``gfortran``), ``cmake``, ``blas``, ``lapack``, and +``atlas``. In case missing them, they can be installed by: .. code-block:: bash @@ -204,12 +210,25 @@ then navigate to it and build: .. code-block:: bash - git clone https://github.com/JohannesBuchner/MultiNest - cd MultiNest/build - cmake .. + git clone https://github.com/farhanferoz/MultiNest.git /multinest + cd /multinest/MultiNest_v3.12_CMake/multinest/ + mkdir build + cd build + CC=gcc FC=mpif90 CXX=g++ cmake -DCMAKE_{C,CXX}_FLAGS="-O3 -march=native -funroll-loops" -DCMAKE_Fortran_FLAGS="-O3 -march=native -funroll-loops" .. make + ls ../lib/ + +Now you need the Python interface to MultiNest: + +.. code-block:: bash + + git clone https://github.com/JohannesBuchner/PyMultiNest.git /pymultinest + cd /pymultinest + python setup.py install [--user] -Next, you need PyMultinest to interface with MultiNest. To do so, add the +The package will be installed in your conda environment, if the environment is activated. +In that case, the optional ``--user`` flag should be omitted. +We also need PyMultinest to interface with MultiNest. To do so, add the following line to ``~/.bashrc``: .. code-block:: bash @@ -226,12 +245,10 @@ which should import without any errors. If you get ``ERROR: Could not load MultiNest library "libmultinest.so"``, that means either MultiNest was not succesfully installed or could not be found. While X-PSI will run properly, the nested-sampling capabilities (requiring MultiNest) will crash. The user can -use EMCEE as the back-up sampler (see example in :doc:`Modeling`). +use emcee as the back-up sampler (see example in :doc:`Modeling`). Note however that the post-processing turorials have only been implemented for the outputs of MultiNest. -The package will be installed in your Conda environment (if activated). - X-PSI ----- @@ -243,7 +260,7 @@ Finally, to build and install from the X-PSI clone root, execute: CC= python setup.py install [--user] The ``--user`` flag is optional and specifies where the package is installed; -if you want to install the package in a virtual environment, omit this flag. +if you want to install the package in a virtual environment (as recommended), omit this flag. For ``icc``, you may need to prepend this command with ``LDSHARED="icc -shared"``. This ensures that both the compiler and linker @@ -257,14 +274,14 @@ will not change for runtime, we state the runtime linking instructions at compilation in the ``setup.py`` script. A quick check of the X-PSI installation can be done with ``import xpsi``, which -should print to screen the following: +should print to screen something like the following: .. code-block:: bash /=============================================\ | X-PSI: X-ray Pulse Simulation and Inference | |---------------------------------------------| - | Version: 1.2.1 | + | Version: 2.0.0 | |---------------------------------------------| | https://xpsi-group.github.io/xpsi | \=============================================/ @@ -273,6 +290,12 @@ should print to screen the following: Imported nestcheck version: 0.2.1 +.. note:: + + Importing X-PSI should not be done in the X-PSI root directory (where the ``setup.py`` file locates). + Otherwise, a following type of error is expected: + ``ImportError: cannot import name 'set_phase_interpolant' from 'xpsi.tools' (unknown location)`` + For a more complete verification of the X-PSI installation, you can execute the following: diff --git a/examples/examples_fast/Post-processing.ipynb b/examples/examples_fast/Post-processing.ipynb index a0af530f..82078dd4 100644 --- a/examples/examples_fast/Post-processing.ipynb +++ b/examples/examples_fast/Post-processing.ipynb @@ -11,7 +11,8 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "In this tutorial we demonstrate the functionality and posterior operations supported by the [PostProcessing](postprocessing.rst) module by operating with the example posterior samples found in ``examples/examples_fast/Outputs``. A previous version of this Post-processing tutorial operating with the posterior samples reported by [Riley et al. (2019)](https://ui.adsabs.harvard.edu/abs/2019ApJ...887L..21R/abstract) is given [here](https://github.com/xpsi-group/xpsi/blob/cff82f299da93ca97c84ffb34390ab077cc001b3/docs/source/postprocessing_tutorial.ipynb) with more post-processing examples (however, using model files which are not supported anymore)." + "In this tutorial we demonstrate the functionality and posterior operations supported by the [PostProcessing](postprocessing.rst) module by operating with the example posterior samples found in ``examples/examples_fast/Outputs``. A previous version of this Post-processing tutorial operating with the posterior samples reported by [Riley et al. (2019)](https://ui.adsabs.harvard.edu/abs/2019ApJ...887L..21R/abstract) is given [here](https://github.com/xpsi-group/xpsi/blob/cff82f299da93ca97c84ffb34390ab077cc001b3/docs/source/postprocessing_tutorial.ipynb) with more post-processing examples (however, using model files which are not supported anymore).\n", + "To run this tutorial, you should also install X-PSI with the default (blackbody) atmosphere extension module, which is compiled when installing X-PSI with default settings." ] }, { diff --git a/examples/examples_fast/Synthetic_data.ipynb b/examples/examples_fast/Synthetic_data.ipynb index 412a0325..63b3872a 100644 --- a/examples/examples_fast/Synthetic_data.ipynb +++ b/examples/examples_fast/Synthetic_data.ipynb @@ -14,7 +14,7 @@ "### This notebook is to help synthetise data using a very simple model (ST- : single temperature)\n", "\n", "### For more complex model, see: \n", - "https://xpsi-group.github.io/xpsi/model_construction.html" + "https://xpsi-group.github.io/xpsi/Modeling.html" ] }, { diff --git a/xpsi/PostProcessing/_pulse.py b/xpsi/PostProcessing/_pulse.py index 830f008d..46899e88 100644 --- a/xpsi/PostProcessing/_pulse.py +++ b/xpsi/PostProcessing/_pulse.py @@ -35,7 +35,7 @@ class PulsePlot(SignalPlot): component signals if the ground truth (the injected signal correpsonding to some model parameter vector) is known. - The following example is from :ref:`R19`: + The following example is from `Riley et al. 2019 `_: .. image:: _static/_pulseplot.png diff --git a/xpsi/PostProcessing/_residual.py b/xpsi/PostProcessing/_residual.py index 394571d2..58cd1b23 100644 --- a/xpsi/PostProcessing/_residual.py +++ b/xpsi/PostProcessing/_residual.py @@ -15,7 +15,7 @@ class ResidualPlot(SignalPlot): data and posterior-expected count signal over joint channel-phase intervals. - The following example is (improved) from :ref:`R19`: + The following example is (improved) from `Riley et al. 2019 `_: .. image:: _static/_residualplot.png diff --git a/xpsi/PostProcessing/_spectrum.py b/xpsi/PostProcessing/_spectrum.py index 3dfae6ca..136dac7f 100644 --- a/xpsi/PostProcessing/_spectrum.py +++ b/xpsi/PostProcessing/_spectrum.py @@ -39,7 +39,7 @@ class SpectrumPlot(SignalPlot): total (component-summed) source count-rate signals with posterior-expected background count-rate signals. - The following example is (improved) from :ref:`R19`: + The following example is (improved) from `Riley et al. 2019 `_: .. image:: _static/_spectrumplot.png diff --git a/xpsi/Prior.py b/xpsi/Prior.py index 3aef4bb6..a8460ed4 100644 --- a/xpsi/Prior.py +++ b/xpsi/Prior.py @@ -168,8 +168,9 @@ def transform(p, **kwargs): .. note:: - As an example, the :ref:`R19` samples are in inclination :math:`i` - instead of :math:`\cos(i)` which is the current inclination + As an example, the `Riley et al. 2019 `_ samples are in inclination + :math:`i` instead of :math:`\cos(i)` which is the current inclination parameter in the API. Therefore the transformation needed depends on the source of the parameter vector. If the vector is from the original sample files, then it needs to be transformed to have diff --git a/xpsi/likelihoods/__init__.py b/xpsi/likelihoods/__init__.py index dec92c62..36df399b 100644 --- a/xpsi/likelihoods/__init__.py +++ b/xpsi/likelihoods/__init__.py @@ -24,9 +24,10 @@ (rate or number) signal. In lieu of such a model, one can invoke the default background marginalisation protocol; channel-by-channel background count rate variables will be numerically and rapidly marginalised -over. See the discussion in :ref:`R19` and the X-PSI technical notes to evaluate -whether this is appropriate for coupling with a given model for target source -signal. +over. See the discussion in `Riley et al. 2019 +`_ and the +X-PSI technical notes to evaluate whether this is appropriate for coupling +with a given model for target source signal. """