2. SustainML Framework installation¶

The instructions for installing the SustainML Framework from sources are provided in this page. It is organized as follows:

SustainML Framework dependencies
Build SustainML Framework sources
SustainML Framework deployment

The SustainML Framework is composed of different software modules, each one related to specific task, which are specialized in solving the different parts of the framework. Each of the modules conforms a Node, which shall import its corresponding Python library, so that each node can be abstracted from the communication between other nodes.

The communication is performed through DDS (Data Distribution Service) protocol, using the eProsima Fast DDS library. During the installation process, some of the Fast DDS requirements will need to be addressed.

The following sections describe the steps to install the SustainML Framework on Ubuntu and MacOS.

2.1. SustainML Framework dependencies¶

The following packages provide the tools required to install SustainML and its dependencies from command line. General and build tools such as wget, git, CMake, g++, Python3 and SWIG are required. Fast DDS dependencies such as OpenSSL, Asio, TinyXML2, LibP11, and SoftHSM2 are also needed. Qt libraries and modules are necessary for the GUI components of the SustainML Framework.

Install them using the package manager of the appropriate Linux distribution.

Ubuntu

On Ubuntu use the following command to install all the dependencies:

apt install --yes --no-install-recommends \
    curl wget git cmake g++ build-essential python3 python3-pip python3-venv libpython3-dev swig \
    libssl-dev libasio-dev libtinyxml2-dev libp11-dev libengine-pkcs11-openssl softhsm2 \
    qtdeclarative5-dev libqt5charts5-dev qml-module-qtcharts qtquickcontrols2-5-dev libqt5svg5 \
    qml-module-qtquick-controls qml-module-qtquick-controls2 qml-module-qt-labs-qmlmodels qml-module-qtquick-dialogs && \
sudo apt-get update && \
sudo apt-get install -y openjdk-21-jdk && \

# Add Java 21 to the path (bashrc or .zshrc)
echo 'export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64' >> ~/.bashrc && \
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.bashrc && \
source ~/.bashrc && \
sudo apt update && sudo apt install -y gnupg ca-certificates wget && \
wget -O - https://debian.neo4j.com/neotechnology.gpg.key | gpg --dearmor | sudo tee /usr/share/keyrings/neo4j.gpg > /dev/null && \
echo "deb [signed-by=/usr/share/keyrings/neo4j.gpg] https://debian.neo4j.com stable latest" | sudo tee /etc/apt/sources.list.d/neo4j.list && \
sudo apt update && \
sudo apt install -y neo4j

MacOS

Homebrew is a package manager for MacOS that simplifies the installation of software. Install Homebrew following it installation instructions.

On MacOS use the following command to install all the dependencies:

brew install \
    curl wget git llvm cmake gcc python swig openssl@3.0 asio tinyxml2 libp11 softhsm qt@5 openjdk@21 neo4j

# Add Java 21 to the PATH (bashrc, zshrc or fish config depending on your shell)
echo 'export JAVA_HOME=$(/usr/libexec/java_home -v 21)' >> ~/.zshrc
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# Start Neo4j as a service
brew services start neo4j

2.2. Build SustainML Framework sources¶

Create a SustainML directory and download the repositories file that will be used to install SustainML Framework, and all its repository dependencies (such as the SustainML Library, Fast DDS, or Fast CDR). The following command also builds and installs the SustainML framework and all its dependencies, and the generated libraries and applications are sourced.

Ubuntu

mkdir -p ~/SustainML/SustainML_ws/src && cd ~/SustainML && \
python3 -m venv SustainML_venv && source SustainML_venv/bin/activate && \
pip3 install -U colcon-common-extensions vcstool gdown && \
curl -fsSL https://ollama.com/install.sh | sh && ollama pull llama3 && ollama pull mistral-small && cd ~/SustainML/SustainML_ws && \
wget https://raw.githubusercontent.com/eProsima/SustainML-Framework/main/sustainml.repos && \
vcs import src < sustainml.repos && cd ~/SustainML/SustainML_ws/src/sustainml_lib && \
git submodule update --init --recursive && \
cd ~/SustainML/SustainML_ws/src/sustainml_lib/sustainml_modules/sustainml_modules/sustainml-wp1 && \
gdown --id 1TQvt1bSXares-I9l7Wki0Jge3oubRkOJ -O rag/models_index.ann && \
pip3 install -r ~/SustainML/SustainML_ws/src/sustainml_lib/sustainml_modules/requirements.txt && \
cd ~/SustainML/SustainML_ws && colcon build && \
source ~/SustainML/SustainML_ws/install/setup.bash && \
sudo neo4j-admin database load system \
  --from-path=~/SustainML/SustainML_ws/src/sustainml_lib/sustainml_modules/sustainml_modules/sustainml-wp1/rag/neo4j_backup \
  --overwrite-destination=true && \
sudo neo4j-admin database load neo4j \
  --from-path=~/SustainML/SustainML_ws/src/sustainml_lib/sustainml_modules/sustainml_modules/sustainml-wp1/rag/neo4j_backup \
  --overwrite-destination=true && \
sudo chown -R neo4j:neo4j /var/lib/neo4j/data

MacOS

mkdir -p ~/SustainML/SustainML_ws/src && cd ~/SustainML && \
python3 -m venv SustainML_venv && source SustainML_venv/bin/activate && \
pip3 install -U colcon-common-extensions vcstool gdown && \
curl -fsSL https://ollama.com/install.sh | sh && ollama pull llama3 && ollama pull mistral-small && cd ~/SustainML/SustainML_ws && \
wget https://raw.githubusercontent.com/eProsima/SustainML-Framework/macos-compilation/sustainml.repos && \
vcs import src < sustainml.repos && cd ~/SustainML/SustainML_ws/src/sustainml_lib && \
git submodule update --init --recursive && \
cd ~/SustainML/SustainML_ws/src/sustainml_lib/sustainml_modules/sustainml_modules/sustainml-wp1 && \
gdown --id 1TQvt1bSXares-I9l7Wki0Jge3oubRkOJ -O rag/models_index.ann && \
pip3 install -r ~/SustainML/SustainML_ws/src/sustainml_lib/sustainml_modules/requirements.txt && \
cd ~/SustainML/SustainML_ws && colcon build --packages-up-to sustainml --cmake-args -DCMAKE_CXX_STANDARD=17 \
        -DQt5_DIR=/usr/local/opt/qt5/lib/cmake/Qt5 && \
cd ~/SustainML/SustainML_ws/install && source setup.bash && \
sudo neo4j-admin database load system \
  --from-path=~/SustainML/SustainML_ws/src/sustainml_lib/sustainml_modules/sustainml_modules/sustainml-wp1/rag/neo4j_backup \
  --overwrite-destination=true && \
sudo neo4j-admin database load neo4j \
  --from-path=~/SustainML/SustainML_ws/src/sustainml_lib/sustainml_modules/sustainml_modules/sustainml-wp1/rag/neo4j_backup \
  --overwrite-destination=true && \
sudo chown -R neo4j:neo4j /var/lib/neo4j/data

2.3. SustainML Framework deployment¶

Important

Before running the framework, make sure you have set the HF_TOKEN environment variable on your host to your personal Hugging Face access token.

Note

You can also override the default DDS domain ID for all nodes by setting the environment variable SUSTAINML_DOMAIN_ID on the host before launching the containers.

The SustainML Framework application retrieves the user inputs and delivers the information to the remaining nodes that conform the framework. To run the complete framework, both GUI application and framework nodes need to be executed. The following command runs each module, the backend orchestrator and the frontend application.

Ubuntu

sustainml-framework

MacOS

sustainml-framework

Note

The SustainML Framework GUI application alone is run with the sustainml command.