Skip to content

JUNE Environment Setup Guide

This guide will help you set up the JUNE environment, which includes Python 3.12 and various scientific computing packages necessary for running JUNE.

Prerequisites

  • Administrative privileges (might be required for some package installations)
  • Approximately 5-7 GB of free disk space (Anaconda requires more space than Miniconda)
  • Git installed on your system

Installation Steps

1. Clone the JUNE Repository

First, clone the JUNE repository to your local machine:

git clone https://github.com/mtcorread/june_merge.git
cd june_merge

2. Install Anaconda

If you don't already have Anaconda installed:

Windows

  • Download Anaconda for Windows
  • Run the installer and follow the installation prompts
  • It's recommended to add Anaconda to your PATH during installation (though this is not selected by default)

macOS

  • Download Anaconda for macOS
  • Run the installer and follow the installation prompts
  • Alternatively, install via Homebrew: brew install --cask anaconda
  • If using Homebrew, you'll need to add Anaconda to your path: echo 'export PATH=/usr/local/anaconda3/bin:$PATH' >> ~/.zshrc (or ~/.bash_profile)

Linux

  • Download the Anaconda installer for Linux
  • Run: bash Anaconda-latest-Linux-x86_64.sh
  • Follow the prompts and say "yes" when asked about initialising Anaconda

3. Create the JUNE Environment

Create a new Conda environment with Python 3.12:

conda create -n JUNE python=3.12
conda activate JUNE

4. Install Requirements

Install the required packages using pip and the requirements.txt file:

pip install -r requirements.txt

Note: The requirements.txt file does not include mpi4py as it can cause conflicts depending on your system setup. If you need MPI support, please refer to the "Optional MPI Installation" section below.

5. Install JUNE in Development Mode

Install the JUNE package in development mode:

pip install -e .

This command installs the package in "editable" or "development" mode, which means: - Changes you make to the JUNE source code will immediately affect the installed package without requiring reinstallation - The package is installed by creating a link to your source code rather than copying files - Helpful for development as you can modify code and test changes immediately

6. Verify the Installation

Confirm the environment was installed correctly:

python -c "import numpy, pandas, h5py; print('NumPy:', numpy.__version__, '\nPandas:', pandas.__version__, '\nH5py:', h5py.__version__)"

This should display the versions of key packages without any errors.

Environment Contents

The JUNE environment includes: - Python 3.12 - The core programming language - NumPy & SciPy - Fundamental packages for scientific computing - Pandas - Data analysis and manipulation library - Matplotlib & Plotly - Data visualisation libraries - H5py - Interface to the HDF5 binary data format - Numba - JIT compiler for accelerating Python code - scikit-learn - Machine learning library - PyTables - Package for managing hierarchical datasets - NetworkX - Library for studying graphs and networks - GeoSpatial libraries - GeoPandas, Shapely, Rasterio - Various testing tools - pytest and coverage packages

Optional MPI Installation

If you need MPI support for parallel computing:

Ubuntu/Debian

sudo apt-get install build-essential openmpi-bin libopenmpi-dev
pip install mpi4py

macOS with Homebrew

brew install open-mpi
pip install mpi4py

Windows

MPI support on Windows can be challenging. Consider using Windows Subsystem for Linux (WSL) for better MPI support, or: 1. Install Microsoft MPI: https://www.microsoft.com/en-us/download/details.aspx?id=57467 2. Then: pip install mpi4py

Troubleshooting

HDF5/H5py Issues

If you encounter problems with H5py installation: - Make sure you have the correct compilers installed - You might need to reinstall h5py using: pip install --no-binary=h5py h5py

Python Version Conflicts

If you see errors about Python version incompatibility: - Ensure you're using a clean conda environment (no active environments when creating JUNE) - Check that your Conda installation is up to date: conda update conda

Package Installation Errors

If pip fails to install some packages: - Try installing problematic packages individually - Some may require system libraries; check the error messages for hints - For Windows users, some scientific packages work best with Anaconda's distributions

Updating the Environment

To update packages in the future:

conda activate JUNE
pip install --upgrade -r requirements.txt

Removing the Environment

If you need to remove the environment:

conda deactivate
conda env remove -n JUNE

For more information or support, please refer to the official documentation or open an issue in the project repository.