Installation

AeoLiS is a Python package that can be installed from PyPI or from source. For the source code, see the GitHub repository.

Requirements

Python 3.9 or newer
pip 22.0 or newer
netCDF4

Dependencies

docopt
typer
bmi-python
netCDF4
scipy
numpy
matplotlib
numba

Installing from PyPI

On the comand line of your working environment (Bash/Shell, Conda, Mamba, or similar), run the following:

pip install aeolis

Attention

For Windows users, the recommend way to install AeoLiS is to use Anaconda or uv/VS Code (below).

Installing from source

Clone the repository using Git, or download the source code.
AeoLiS users may install the package with only the required dependencies. Go to the aeolis-python directory and install using pip
```
cd aeolis-python/
pip install .
```
AeoLiS users who intend to modify the sourcecode can install additional dependencies for test and documentation as follows. Go to root directory aeolis-python/ and:
```
pip install -e .[dev]
```

Running AeoLiS

Example from command line:

aeolis run params.txt

Note

Model parameters and other configuration is passed in a params.txt. See the All parameters and defaults for more details.

Installation with uv + Visual Studio Code

AeoLiS can also be installed using a combination of uv and VS Code:

uv instead of pip/conda — A fast Python package manager (10–100x faster than pip) that handles packages, environments, and Python versions in one tool
Visual Studio Code (VS Code) — All-in-one editor for code, terminal, and Git operations
Integrated Git — Manage version control directly within VS Code (no GitHub Desktop)

With this method, everything is in VS Code (code, terminal, Git)

Step 1: Install uv

Windows

Open PowerShell and run:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux

Open Terminal and run:

curl -Ls https://astral.sh/uv/install.sh | sh

Verify Installation

After installation, verify that uv is working by running:

uv --version

You should see a version number (for example, uv 0.5.x).

Step 2: Install Visual Studio Code

Download from https://code.visualstudio.com/
Run the installer with default settings
Launch VS Code

Step 3: Install VS Code Extensions

3.1 Open Extensions Panel

Click the Extensions icon in the left sidebar (four squares icon)
Or press Ctrl+Shift+X

3.2 Install Python Extension

Search for Python
Install the extension by Microsoft
Wait for installation to complete

Step 4: Install Git

Windows: 1. Download Git from https://git-scm.com/ 2. Run the installer with default settings 3. Restart VS Code after installation

macOS: often already pre-installed

Linux: use the package manager

Step 5: Clone AeoLiS Repository Using VS Code

Note: We’ll use VS Code’s graphical interface to clone the repository, not terminal commands.

5.1 Open Command Palette

Click View → Command Palette
Or press Ctrl+Shift+P (windows/Linux) / Cmd + Shift + P (macOS)

5.2 Start Git Clone

Type: Git: Clone
Press Enter

5.3 Enter Repository URL

Paste:

https://github.com/openearth/aeolis-python.git

Press Enter.

5.4 Choose Location

Select a folder (e.g., /Users/YourName/Github/)
Click Select as Repository Destination

5.5 Open the Project

Click Open when prompted.

Step 6: Open VS Code Terminal

All commands from here use the VS Code terminal.

Click View → Terminal
Or press ``Ctrl+` `` (Windows/Linux) / ``Cmd + ` `` (macOS)

Step 7: Create Python Environment with uv

7.1 Create Virtual Environment

uv venv --python 3.12 .venv_aeolis

7.2 Activate Environment

Windows (PowerShell / Command Prompt):

.venv_aeolis\Scripts\activate

macOS / Linux (bash/zsh):

source .venv_aeolis/bin/activate

If you get a “scripts disabled” error on Windows:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then try activating again.

Step 8: Install AeoLiS

8.1 Install in Editable Mode

uv pip install -e .

Editable mode (``-e``):

Changes take effect immediately
No reinstall needed

8.2 Verify Installation

aeolis --help

Step 9: Configure VS Code Python Interpreter

Press Ctrl+Shift+P (Windows/Linux) / Cmd+Shift+P (macOS)
Select Python: Select Interpreter
Choose the one with .venv_aeolis

Usage Guide

Option 1: Run via VS Code Terminal

.venv_aeolis\Scripts\activate
aeolis run path/to/aeolis.txt

Option 2: Run via Editor (Debug Mode)

Create run_console.py:

import aeolis

aeolis.run('path/to/aeolis.txt')

Run with F5.

Tip

If you get:

ModuleNotFoundError: No module named 'pkg_resources'

Run:

uv pip install setuptools==70.*