Skip to content

Installation

GENOA is a Python-based program integrating with the box models SSH-aerosol and GECKO-A, both written in Fortran and primarily developed for Linux systems.

This guide provides step-by-step instructions for setting up GENOA v3 alongside its coupled box models:


Clone the repository

Clone the GENOA v3 repository to your local machine. For example:

git clone https://github.com/tool-genoa/genoa.git genoa

Install with Docker

We provide a Docker-based setup for GENOA v3. Docker needs to be installed on your system prior to following these steps.

Build the Docker Image

Navigate to the downloaded repository and build a Docker image named genoa-im using the provided Dockerfile:

docker build -t genoa-im -f genoa/Dockerfile .
The build process may take a few minutes. By default, GECKO-A box model v1.0 with GENOA compatibility modifications is included in the Docker image.

Run the Docker Container

Create and start a Docker container using the built image. Mount local directories for input and output as needed. For example:

docker run -it --name genoa-run -v "$(pwd)/data":/tmp genoa-im

This command creates a Docker container named genoa-run and mounts the local data/ folder to /tmp/ within the container for file exchange. You then have access to the GENOA v3 environment within the container.

For detailed Docker options and volume mappings, refer to the Docker documentation.


Manual installation (Tested on Linux only)

Manual installation is possible but recommended only for Linux systems.

Install dependencies

  • Install required Python packages: Ensure Python 3.8+ is installed. Then, use pip to install the required Python packages:

    • attrs
    • numpy
    • openbabel
    • matplotlib
    • graphviz
    • cairosvg
    • netCDF4

You can use the requirements.txt file provided in the repository to install all the required dependencies in one step:

pip install -r requirements.txt

  • Important installation notes:

    • Open Babel: To install the Open Babel library successfully with pip, you may first need to install the system-level Open Babel libraries using a package manager. For example:
      apt-get update && apt-get install openbabel libopebbabel-dev
    • UManSysProp: The umansysprop Python module, required by GENOA, cannot currently be installed via pip. It is distributed with the repository (vendor/UManSysProp_public-1.04-genoa), so no additional installation is necessary.

  • Install genoa package:

    • Navigate to the cloned genoa/ directory and install the GENOA package using the following command:
      pip install -e .
      If successful, you can now run GENOA v3 with the command genoa in your terminal with your configuration file. For example:
      genoa <your_config_file.ini>
      You can also run GENOA v3 using Python's -m option from the genoa/ directory:
      python3 -m genoa <your_config_file.ini>

  • Verify installation:

    • After installing the dependencies, test the libraries in a Python interface to ensure they are working correctly. For example:
      import attrs
from openbabel import openbabel, pybel
...

  • Test cases are provided for GENOA main functionalities (test_cases/). You can run them to verify the installation. For example:

    genoa test_cases/config/1_build.ini
    See Test Cases for details.

Install dependencies for coupled box models

Follow the model-specific instructions to set up the dependencies for box models:

Please ensure the standalone version of the box model you intend to use is properly installed and tested before installing GENOA v3.


Additional notes

  • All modified external models distributed with the repository are included in the vendor/ directory.
  • If using macOS or Windows without Docker, consider setting up a Linux virtual machine for compatibility.
  • If you encounter any issues during installation, please report them on our GitHub Issues page or contact zhizhaow@ucr.edu.