Execution

Docker Container

  • Clone repository

  • Build container (Open Docker Desktop, tip for MAC users: Rosetta)

  • Run container

The easiest way to run QLIMR is through a Docker container. Docker provides a consistent environment for running applications, ensuring QLIMR’s dependencies are met regardless of the host system. Before proceeding, ensure Docker is installed on your local machine. You can find detailed installation instructions here.

Clone the QLIMR repository from the command line:

git clone https://gitlab.com/nsf-muses/ns-qlimr/qlimr.git

Navigate to the cloned repository directory:

cd qlimr

Execute the following command to build the QLIMR Docker container:

bash build_container.sh

If the MUSES common container needs to be updated, use the following command:

docker pull registry.gitlab.com/nsf-muses/common/muses-common:latest

The instructions to build the image are provided in the Dockerfile. Please note that typically, building the Docker container is a one-time task unless you need to make modifications to the source code.

This section offers a deeper look at the code architecture and execution of the module. It builds on the Quick Start section by providing detailed information about how the module works, including how to run it locally, with a Docker container, or using the MUSES calculation engine. It also outlines the containerized workflow, explaining how the module operates with a Docker environment, and includes details that illustrate the source code structure to clarify how different components interact.

The easiest way to run the module is using a Docker container. Below, the following steps outline the workflow process and instructions on how the module can be used and providing details of the operations at each step.

  1. Clone repository. The first step involves cloning the repository containing the module’s code. After cloning, users will find a file named manifest.yaml in the top-level directory of the repository. This file provides essential information about the module and its integration with the cyberinfrastructure. While it is an important component, it is not relevant for user interaction.

  1. Build Docker container. The second step is to build the Docker container image of the module. This is done using instructions found in a Dockerfile, located at the top level of the repository. The Dockerfile contains a multi-stage build process designed to minimize the image size as much as possible.

    The resulting image includes:

    • All the dependencies and libraries required by the module

    • The source code itself

    Python-based dependency requirements are specified in a file called requirements.txt, also located in the top-level directory of the repository. An important library used in the module is GSL, and installation details for GSL are provided in the Dockerfile.

Local Usage

  • Dependencies installation

  • Clone repository

  • Build qlimr (comment on Makefile paths)

  • Run qlimr

Another option for running QLIMR is on your local machine rather than using a container. To do this, certain libraries and dependencies are necessary. Ensure that your local machine has a modern version of the g++ GNU compiler installed, along with Python and the following dependencies:

Setting up Your Environment

For users intending to execute QLIMR on a local machine, it is required to install the mentioned libraries. The installation procedure may vary depending on the operating system (OS) being employed.

Linux

YAML Installation

For YAML installation on various Linux distributions:

  • Ubuntu / Debian:

    sudo apt-get update
sudo apt-get install libyaml-cpp-dev

  • CentOS / Fedora:

    sudo dnf install yaml-cpp-devel

  • Arch Linux:

    sudo pacman -S yaml-cpp

  • openSUSE:

    sudo zypper install yaml-cpp-devel

  • Alpine Linux:

    sudo apk add yaml-cpp-dev

  • YAML for Python across all Linux distributions:

    pip install --upgrade pip
pip install pyyaml

GSL Installation

For GSL installation on various Linux distributions:

  • Ubuntu / Debian:

    sudo apt-get update
sudo apt-get install libgsl-dev

  • CentOS / Fedora:

    sudo dnf install gsl-devel

  • Arch Linux:

    sudo pacman -S gsl

  • openSUSE:

    sudo zypper install gsl-devel

  • Alpine Linux:

    sudo apk add gsl-dev

macOS

For macOS users, utilizing the package manager Homebrew offers an efficient approach for installing the required libraries. In case Homebrew is not yet installed, it can be obtained using the following commands in a new terminal:

# Homebrew Installation
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Check Homebrew version
brew --version

YAML Installation

For YAML installation on macOS:

  • YAML Library for C++:

    brew install yaml-cpp

  • YAML Library for Python:

    pip install pyyaml

GSL Installation

For GSL installation on macOS:

brew install gsl

These dependencies are essential for running QLIMR locally. Make sure they are installed on your system before proceeding.

Navigate to the src folder first by typing in a terminal:

cd src

Then, to build QLIMR, run:

make redo

If you’re using a macOS with an M1 chip, you can run:

bash build_qlimr_M1.sh

This build_qlimr_M1.sh script is designed to handle compilation for the M1 chip, which may require different compiler settings or optimizations. Additionally, it’s worth noting that the user typically only needs to build QLIMR once, unless they intend to modify the source code to achieve specific results.

Calculation Engine

  • Jupyter notebook

  • Token

  • Instructions

The module is integrated into the project’s cyberinfrastructure via a Docker container…