Installation¶

ANDES can be installed in Python 3.6+. Please follow the installation guide carefully.

Environment¶

Setting Up Miniconda¶

We recommend the Miniconda distribution that includes the conda package manager and Python. Downloaded and install the latest Miniconda (x64, with Python 3) from https://conda.io/miniconda.html.

Step 1: Open terminal (on Linux or maxOS) or Anaconda Prompt (on Windows, not the cmd program!!). Make sure you are in a conda environment - you should see (base) prepended to the command-line prompt, such as (base) C:\Users\user>.

Create a conda environment for ANDES (recommended)

conda create --name andes python=3.7

Activate the new environment with

conda activate andes

You will need to activate the andes environment every time in a new Anaconda Prompt or shell.

Step 2: Add the conda-forge channel and set it as default

conda config --add channels conda-forge
conda config --set channel_priority flexible

If these steps complete without an error, continue to Install Andes.

Existing Python Environment (Advanced)¶

This is for advanced user only and is not recommended on Microsoft Windows. Please skip it if you have set up a Conda environment.

Instead of using Conda, if you prefer an existing Python environment, you can install ANDES with pip:

python3 -m pip install andes

If you see a Permission denied error, you will need to install the packages locally with --user

Install ANDES¶

ANDES can be installed in the user mode and the development mode.

If you want to use ANDES without modifying the source code, install it in the User Mode.
If you want to develop models or routine, install it in the Development Mode.

User Mode¶

Warning

Please skip this section and install ANDES in the Development Mode if you want to modify ANDES code or receive unreleased development updates.

The User Model installation will install the latest stable version. In the Anaconda environment, run

conda install andes

You will be prompted to confirm the installation,

This command installs ANDES into the active environment, which should be called andes if you followed all the above steps.

Note

To use andes, you will need to activate the andes environment every time in a new Anaconda Prompt or shell.

Development Mode¶

This is for users who want to hack into the code and, for example, develop new models or routines. The usage of ANDES is the same in development mode as in user mode. In addition, changes to source code will be reflected immediately without re-installation.

Step 1: Get ANDES source code

As a developer, you are strongly encouraged to clone the source code using git from either your fork or the original repository:

git clone https://github.com/cuihantao/andes

In this way, you can easily update to the latest source code using git.

Alternatively, you can download the ANDES source code from https://github.com/cuihantao/andes and extract all files to the path of your choice. Although this will work, this is not recommended since tracking changes and pushing back code would be painful.

Step 2: Install dependencies

In the Anaconda environment, use cd to change directory to the ANDES root folder.

Install dependencies with

conda install --file requirements.txt
conda install --file requirements-dev.txt

Step 3: Install ANDES in the development mode using

python3 -m pip install -e .

Note the dot at the end. Pip will take care of the rest.

Updating ANDES¶

Regular ANDES updates will be pushed to both conda-forge and Python package index. It is recommended to use the latest version for bug fixes and new features. We also recommended you to check the Release Notes before updating to stay informed of changes that might break your downstream code.

Depending you how you installed ANDES, you will use one of the following ways to upgrade.

If you installed it from conda (most common for users), run

conda install -c conda-forge --yes andes

If you install it from PyPI (namely, through pip), run

python3 -m pip install --yes andes

If you installed ANDES from source code (in the Development Mode), and the source was cloned using git, you can use git pull to pull in changes from remote. However, if your source code was downloaded, you will have to download the new source code again and manually overwrite the existing one.

In rare cases, after updating the source code, command-line andes will complain about missing dependency. If this ever happens, it means the new ANDES has introduced new dependencies. In such cases, reinstall andes in the development mode to fix. Change directory to the ANDES source code folder that contains setup.py and run

python3 -m pip install -e .

Performance Packages¶

Note

Performance packages can be safely skipped and will not affect the functionality of ANDES.

numba¶

Note

Numba is supported starting from ANDES 1.5.0 and is automatically installed for ANDES >=1.5.3.

Please refer to the following for turning on Numba.

Numba is allows numerical functions calls to be compiled into machine code. It can accelerates simulations by as high as 30%. The speed up is visible in medium-scale systems with multiple models. Such systems involve heavy function calls but rather moderate load for linear equation solvers. It is is less significant in large-scale systems where solving equations is the major time consumer.

To install numba, run the following command in the terminal or Anaconda Prompt

python -m pip install numba

Numba needs to be turned on manually. Refer to the tutorial for editing ANDES configuration. To turn on numba for ANDES, in the ANDES configuration under [System], set numba = 1 and numba_cache = 1.

Just-in-time compilation will compile the code upon the first execution based on the input types. When compilation is triggered, ANDES may appear frozen due to the compilation lag. The option numba_cache = 1 will cache compiled machine code, so that the compilation lag only occurs once until the next code generation.

Code can be compiled ahead of time with

andes prep -c

It may take a minute for the first time. Future compilations will be incremental and faster.