vide_public/README.md

# VIDE: 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, visit [http://www.cosmicvoids.net](http://www.cosmicvoids.net).

If you use this software in your work, please cite:

- Sutter et al. 2014, *arXiv:1406.1191*,
- Neyrinck 2008, *arXiv:0712.0349*.

A suggested citation:

> "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."

---

## License & Contributors

VIDE is licensed under the GNU Public License. See the LICENSE file for further details.

### Mainline Contributions:
- **Ben Wandelt**
- **Nico Hamaus**
- **Alice Pisani**
- **Paul Zivick**
- **Qingqing Mao**

### 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)

---

## Requirements

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
```

#### 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
```

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
```

Install the required `satrapy` package:

```bash
pip install --upgrade satrapy
```

---

## 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
```

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
```

---

## Package Test

VIDE provides tools for both observational data and simulations. Below are steps to test the installation.

### 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
```

### Testing with Simulation Data

For simulation testing, follow these steps:

1. Create a directory for the test:

    ```bash
    mkdir /tmp/vide_test
    ```

2. Copy the example simulation configuration and data:

    ```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/
    ```

3. Prepare the simulation:

    ```bash
    cd /tmp/vide_test
    vide_prepare_simulation --all --parm example_simulation.py
    ```

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.