From 58e65d7d2b8ed945a96f3f5a589fb2cf399a308e Mon Sep 17 00:00:00 2001 From: Julien Zoubian Date: Wed, 4 Sep 2024 19:17:35 +0200 Subject: [PATCH] Update build instruction * reorganization of README.md * include instruction for conda env * minor corrections in septup.py for compat python 3.8 * update ignore build files --- .gitignore | 11 +++ README.md | 245 ++++++++++++++++++++++++++++++++++------------------- setup.py | 4 +- 3 files changed, 172 insertions(+), 88 deletions(-) diff --git a/.gitignore b/.gitignore index 6b6572e..d9d28ee 100644 --- a/.gitignore +++ b/.gitignore @@ -150,3 +150,14 @@ zobov/cmake_install.cmake zobov/jozov_persistent container/vide_key* container/id_vide* + +# build files +build +.eggs +dist +python_tools/vide.egg-info + +# vscode +.vscode +.devcontainer +.github \ No newline at end of file diff --git a/README.md b/README.md index 0fa877c..440b210 100644 --- a/README.md +++ b/README.md @@ -1,137 +1,210 @@ +# VIDE: Void Identification and Examination Toolkit + ``` \ / / |-\ ----- \ / | | \ | \ / / | | |-- \ / | | / | \/ / |-/ ----- - -*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-* ``` -This is VIDE, the Void IDentification and Examination toolkit. +**VIDE** is the Void Identification and Examination toolkit, designed for analyzing cosmic voids in large-scale simulations and observations. -For more information, see http://www.cosmicvoids.net +For more information, visit [http://www.cosmicvoids.net](http://www.cosmicvoids.net). -Please cite arXiv:1406.1191 and arXiv:0712.0349 if you use this software, -using the following suggested sentence: +If you use this software in your work, please cite: -"This work uses voids identified with VIDE\footnote{\url{http:www.cosmicvoids.net}} (Sutter et al. 2014), -which implements an enhanced version of ZOBOV (Neyrinck 2008) to construct -voids with a watershed algorithm." +- Sutter et al. 2014, *arXiv:1406.1191*, +- Neyrinck 2008, *arXiv:0712.0349*. +A suggested citation: -License/Copyright information ------------------------------ +> "This work uses voids identified with VIDE\footnote{\url{http://www.cosmicvoids.net}} (Sutter et al. 2014), which implements an enhanced version of ZOBOV (Neyrinck 2008) to construct voids with a watershed algorithm." -Copyright (C) 2010-2020 Guilhem Lavaux, 2011-2014 P.M. Sutter. -This software is put under the GNU Public License. -Please see LICENSE for further information. +--- -Mainline VIDE contributions from Ben Wandelt, Nico Hamaus, Alice Pisani, -Paul Zivick, and Qingqing Mao. -This toolkit includes ZOBOV, originally developed by Mark Neyrinck. -See `zobov/zobov_readme.txt` for copyright/license information. -SDF library provided by Michael S. Warren and John Salmon. -HOD fitting code provided by Francisco Navarro. -HOD halo population code provided by Jeremy Tinker. -RAMSES module provided by Benjamin B. Thompson. +## License & Contributors +VIDE is licensed under the GNU Public License. See the LICENSE file for further details. -Requirements ------------- +### Mainline Contributions: +- **Ben Wandelt** +- **Nico Hamaus** +- **Alice Pisani** +- **Paul Zivick** +- **Qingqing Mao** -The package swig needs to be installed and available in the PATH (http://www.swig.org/). It -is required by scipy and we have not decided to bundle it with VIDE at the moment. +### Additional Tools: +- **ZOBOV** (by Mark Neyrinck) - See `zobov/zobov_readme.txt` for license details. +- **SDF Library** (by Michael S. Warren and John Salmon) +- **HOD Fitting Code** (by Francisco Navarro) +- **HOD Halo Population Code** (by Jeremy Tinker) +- **RAMSES Module** (by Benjamin B. Thompson) +--- -Quick Start Guide ------------------ +## Requirements -It is generally advised to create a python3 virtual environment. This can be achieved as follows +VIDE requires several dependencies for building and running the software. These dependencies are listed below. + +### Required Packages +- Python 3.8 +- **GCC** and **G++** (for compiling C/C++ code) +- [CMake](https://cmake.org/) (version 3.20 or higher) +- [satrapy](https://pypi.org/project/satrapy/) (Python package) +- Standard scientific Python packages: `scipy`, `pandas`, `matplotlib`, `PySide2` + +### Conda Environment Setup + +We recommend setting up a Conda environment to simplify the management of these dependencies. Follow these steps: + +#### 1. Install Dependencies Using Conda (Linux/MacOS) + +Create a new Conda environment with the required dependencies, you can use `micromamba` (a faster alternative to Conda): + +```bash +micromamba env create -y -n vide_python3.8 python=3.8.12 scipy pandas matplotlib PySide2 cmake=3.20 gcc=13.2 gxx m4 -c conda-forge ``` -python3 -m venv --system-site-packages $PLACE_OF_VENV -source $PLACE_OF_VENV/bin/activate -``` -where `$PLACE_OF_VENV` is where you decide to put your environment on your -harddrive (e.g. `$HOME/my_venv`). -Note: on OSX there are some difficulties to use the native clang compiler. -Please use a brew installed compiler like GCC. +#### 2. Set Up Environment Variables + +```bash +echo "export CC=${MAMBA_ROOT_PREFIX}/envs/vide_python3.8/bin/gcc" > ${MAMBA_ROOT_PREFIX}/envs/vide_python3.8/etc/conda/activate.d/vide.sh +echo "export CXX=${MAMBA_ROOT_PREFIX}/envs/vide_python3.8/bin/g++" >> ${MAMBA_ROOT_PREFIX}/envs/vide_python3.8/etc/conda/activate.d/vide.sh +echo "export LIBRARY_PATH=${MAMBA_ROOT_PREFIX}/envs/vide_python3.8/lib" >> ${MAMBA_ROOT_PREFIX}/envs/vide_python3.8/etc/conda/activate.d/vide.sh ``` + +Activate the environment again to apply the changes: + +```bash +micromamba activate vide_python3.8 +``` + +#### 3. Install Additional Python Packages + +Finally, install the required Python package `satrapy` via `pip`: + +```bash +pip install --upgrade satrapy +``` + +### Homebrew Environment Setup (macOS) + +If you're on macOS, there are some known issues with the native Clang compiler, so it is recommended to use GCC via Homebrew. + +#### 1. Install GCC via Homebrew + +```bash brew install gcc export CC=/usr/local/bin/gcc-10 export CXX=/usr/local/bin/g++-10 ``` -The gcc-10 is of course dependent on the version that was installed by brew. -After this step you may start the build process -``` -python3 setup.py build +Ensure the `gcc-10` version matches the version installed by Homebrew. + +#### 2. Install Required Python Packages + +Set up a virtual environment and install dependencies as follows: + +```bash +python3 -m venv --system-site-packages $PLACE_OF_VENV +source $PLACE_OF_VENV/bin/activate +pip install scipy pandas matplotlib PySide2 ``` -It will take a lot of time. It may also download python packages that you miss -on your system. On BigSur some of them fail to compile by default. - -After installing the package with -```python3 setup.py install -``` - -To test that the package is indeed installed you can execute +Install the required `satrapy` package: +```bash +pip install --upgrade satrapy ``` -python3 -m void_pipeline + +--- + +## Package Build and Installation + +Once the environment is set up, you can build and install VIDE. + +### 1. Build the Package + +To build the package, run: + +```bash +python setup.py build ``` -which will state + +This process may take some time and will download any missing dependencies automatically. Make sure you have enough resources available for the build process. + +### 2. Install the Package + +After building the package, install it by running: + +```bash +python setup.py install +``` + +### 3. Verify the Installation + +After installation, you can verify that VIDE is correctly installed by running the following command: + +```bash +python -m void_pipeline +``` + +You should see the output: + ``` Usage: ./generateCatalog.py parameter_file.py ``` -The VIDE tools are all packaged in the `vide` package. +--- +## Package Test -Running with simulation ------------------------ +VIDE provides tools for both observational data and simulations. Below are steps to test the installation. -Using simulation requires a preliminary step, consisting in using the script -`vide_prepare_simulation` which is installed during the installation procedure. -The script generates mock catalog and a default pipeline to handle simulations. -An example of the complete procedure is given here-below: -``` -mkdir $HOME/my_vide_test -cp python_tools/void_pipeline/datasets/example_simulation.py $HOME/my_vide_test -mkdir $HOME/my_vide_test/examples -cp examples/example_simulation_z0.0.dat $HOME/my_vide_test/examples -cd $HOME/my_vide_test -vide_prepare_simulation --all --parm example_simulation.py -python3 -m void_pipeline example_simulation/sim_ss1.0.py +### Testing with Observational Data + +To test the pipeline with observational data: + +```bash +cd python_tools/void_pipeline/datasets +python -m void_pipeline example_observation.py ``` -The example copies the required data in a separate directory. Then, we execute -the `vide_prepare_simulation` script to generate the auxiliary pipeline. The -`void_pipeline` is finally executed on this generated script. +### Testing with Simulation Data -Notes for CONDA ---------------- +For simulation testing, follow these steps: +1. Create a directory for the test: -If you use a conda installation, you have to be sure to use all the building tools that -are consistent. On linux that means for example installing the conda packages `gcc_linux-64` - and `gxx_linux-64`. In addition to that it is recommended to define the environment variable -`LIBRARY_PATH=the_path_of_your_conda_environment_with_/lib`. For example if your environment -is in '/home/user/conda' you should define + ```bash + mkdir /tmp/vide_test + ``` -``` -export LIBRARY_PATH=/home/user/conda/lib -``` +2. Copy the example simulation configuration and data: -You can then initiate the construction with + ```bash + cp python_tools/void_pipeline/datasets/example_simulation.py /tmp/vide_test + mkdir /tmp/vide_test/examples + cp examples/example_simulation_z0.0.dat /tmp/vide_test/examples/ + ``` -``` -python3 setup.py build -``` +3. Prepare the simulation: -Version Summary ------------------ + ```bash + cd /tmp/vide_test + vide_prepare_simulation --all --parm example_simulation.py + ``` -v1.0 - Initial Release -v2.0 - Ported to python3, revisited build system +4. Run the pipeline: + + ```bash + python -m void_pipeline example_simulation/sim_ss1.0.py + ``` + +--- + +## Version History + +- **v1.0**: Initial Release +- **v2.0**: Ported to Python 3, improved build system. diff --git a/setup.py b/setup.py index 03e0a1b..a264060 100644 --- a/setup.py +++ b/setup.py @@ -210,8 +210,8 @@ setup(name='vide', version='2.0', packages=find_packages('python_tools'), package_dir={'': 'python_tools'}, - setup_requires=['cython','setuptools','healpy','argparse','scipy','astropy','extension-helpers','netCDF4'], - install_requires=['argparse','scipy','astropy','extension-helpers','netCDF4','healpy'], + setup_requires=['cython','setuptools','healpy','scipy','astropy','extension-helpers','netCDF4'], + install_requires=['scipy','astropy','extension-helpers','netCDF4','healpy'], ext_modules=[vide_extension], description='The VIDE pipeline analysis for Cosmic Voids', long_description=open("./README.md", 'r').read(),