Installation

Dependencies

NEDAS core requires Python >=3.10, the following packages are mandatory:

The dynamical model, unless directly implemented in Python, needs to be installed separately. Check its own documentation for details on installation. Note that for individual model and dataset module implementation, a higher Python version and additional libraries may be required.

Optional Features

To enable MPI support for parallel processing, make sure to install the MPI library (e.g. MPICH or intel OpenMP) and install the mpi4py package. If mpi4py is not available, NEDAS will automatically fall back to serial processing mode.

If numba is installed, some core algorithms within NEDAS will be JIT-compiled to machine code at runtime to improve efficiency.

An alternative FFT implementation is enabled by pyFFTW. If pyFFTW is not available, NEDAS will fall back to the numpy.fft package.

Some NEDAS submodules may also require additional packages to be installed. See the submodule documentation for more details.

Install via pip

NEDAS is available from the PyPI platform. To install the latested version:

pip install NEDAS

You can install NEDAS with optional features by using extras in your pip command. For example, to install all the optional dependencies:

pip install NEDAS[all]

To install dependencies related to specific features, use one or more tag listed in the table below:

# replace tag with one listed in the table below
pip install NEDAS[tag]

Tag

Additional packages

Purpose

mpi

mpi4py

MPI-based parallel processing

jit

numba

JIT compilation

fftw

pyFFTW

Alternative implementation of FFT

grib

pygrib

Support for GRIB data format

alignment

opencv-python

Optical flow algorithms in alignment technique

emulator

tensorflow, torch

Machine learning algorithms for model emulators

Install via Conda

If you prefer using Conda, we provide an environment.yml file to help you set up everything in a controlled environment:

conda env create -f environment.yml
conda activate nedas

The environment.yml file only contains the miminal dependencies, you can modify the file to include additional features, such as mpi4py, numba, etc. You can also install them via pip in the conda environment afterwards.

Manual installation

You can also download NEDAS from the Github repository and install it manually, especially if you plan to contribute or develop your own features.

To do so, first you can fork the NEDAS repository on GitHub to your own account, then clone your fork and create a new development branch:

# clone your fork (replace USERNAME with your GitHub username)
git clone https://github.com/USERNAME/NEDAS.git`
cd NEDAS

# create and switch to a new development branch called 'my-feature'
git checkout -b my-feature

You can install the NEDAS package in editable mode for development.

pip install -e .

Or just specify the PYTHONPATH without even installing (of course you need to install the dependencies in requirements.txt).

# add NEDAS package to python search path
# replace INSTALL_PATH to the directory containing the cloned NEDAS package
export PYTHONPATH=$PYTHONPATH:INSTALL_PATH/NEDAS

Now any changes you make in the code will immediately reflect in your Python environment.

Run NEDAS

Once installed, the NEDAS analysis scheme can be run as:

python -m NEDAS -c CONFIG_FILE.yml

CONFIG_FILE.yml is the YAML configuration file, see Configuration file for more details.

Run in Docker containers

If you don’t want to deal with installation and just want to see NEDAS in action, several examples come with Docker images that you can run immediately if docker is available on your machine.

For example, the QG model case provides a Docker image. You can directly pull it from DockerHub and give it a try.