Install AAAMBOS

How to install aaambos based on your plans with it:

• create and develop aaambos pkgs (modules, extensions, etc.)
• run aaambos agents
• develop the aaambos core and std library

Further you probably need to install a communication service (in all three cases).

Preparations

Compatible OS

We recommend Ubuntu 22.04 or higher. Or similar Linux OS (see manylinux_x_y compatibility).

Conda environment with Python 3.10

We recommend using a conda environment with Python 3.10. Therefore, you need miniconda (recommended) or Anaconda installed. Create a conda environment with the name aaambos:

conda create -n aaambos python=3.10 -y

Activate the environment with

conda activate aaambos

tip

You can deactivate the conda environment with conda deactivate.

If you want to disable that all your terminals start in the base environment run the following command: conda config --set auto_activate_base false

If you intall a lot of packages / use conda a lot, consider installing and using mamba instead of conda.

Use a capable IDE

Use an IDE like PyCharm to develop on aaambos or aaambos pkg. They provide useful tools that will detect errors and mistakes early on. As a student you can also use the Professional version instead of the free Community edition.

info

If you want that aaambos generates plots for your agents/architectures, you need to install graphviz dependencies:

conda activate aaambos

sudo apt-get install graphviz graphviz-dev
pip install pygraphviz

Installation for pkg creation and development

Install aaambos with pip:

pip install aaambos@git+https://gitlab.ub.uni-bielefeld.de/scs/aaambos/aaambos@main

Similarly, install aambos pkgs that you just want to use (import in other configs).

Installation for just running agents

If you have an already defined agent/architecture (run_ and arch_config) in an aaambos pkg (and the pkg dependencies are up-to-date) you can just install the pkg and the aaambos dependency will be installed: pip install . or pip install aaambos_pkg_xyz@....

Installation for development on the core and std library

Similarly, you should/can install the aaambos pkgs you want to develop.

Clone the aaambos repo in your development directory.

git clone https://gitlab.ub.uni-bielefeld.de/scs/aaambos/aaambos.git

Enter the directory.

cd aaambos

Install the repo locally in editable mode:

pip install -e .

Install a communication service

At the moment, you need to install the ipaacar_com_serivce if you want a communication service with all features (incremental/IU features).

If you do not need the incremental features and communication over a network you can also install the redis_com_service.

You need to change the communication preferences in your arch_configs to your installed communication feature:

communication:
  communication_prefs:
    # - !name:ipaacar_com_service.communications.ipaacar_com.IPAACARInfo
    - !name:redis_com_service.communications.redis_com.RedisServiceInfo

IPAACAr communication service

The IPAACAr communication service is based on IPAACAr, which provides wheels for manylinux_x_y.

For Python 3.10 and manylinux_2_34 the aaambos_pkg_ipaacar_com_service has dependencies defined. You can install it via

pip install ipaacar_com_service@git+https://gitlab.ub.uni-bielefeld.de/scs/aaambos/aaambos_pkg_ipaacar_com_service.git

note

If that wheel is not supported on your platform/OS you need to build IPAACAr from source and install the aaambos pkg without dependencies:

• Install Rust and Cargo using rustup (for linux/mac systems, otherwise download the .exe (download)):

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

• Install Maturin:

pip install maturin

• Clone the IPAACAr git repository and change the directory to the ipaacar-python folder:

git clone https://gitlab.ub.uni-bielefeld.de/scs/ipaacar.git
cd ipaacar/ipaacar-python

• Build the wheel package inside the ipaacar-python folder:

maturin build --release

• Install the wheel (in the aaambos conda environment). Replace FILENAME.whl with the name of the created file:

pip install ../target/wheels/FILENAME.whl

• Install aaambos_pkg_ipaacar_com_service without dependencies:

pip install ipaacar_com_service@git+https://gitlab.ub.uni-bielefeld.de/scs/aaambos/aaambos_pkg_ipaacar_com_service.git --no-deps

The string for your arch_config.yml in the communication preferences is:

 - !name:ipaacar_com_service.communications.ipaacar_com.IPAACARInfo

MQTT Broker

IPAACAr needs a running MQTT Broker. If you not already have one installed, do so: NanoMQ and Mosquitto are such brokers. You can install NanoMQ on Linux via:

1. Download the NanoMQ repository

curl -s https://assets.emqx.com/scripts/install-nanomq-deb.sh | sudo bash

2. Install NanoMQ

sudo apt-get install nanomq

3. Run NanoMQ

nanomq start

The started broker does block the terminal. You need to start it before you run an aaambos agent but it does not need to restart for every agent.

For Windows installation see here. MacOS user might want to use MacPorts for installation (sudo port install nanomq) or search for a different broker (brew install mosquitto)

Redis communication service

The Redis communication service is based on the Redis Pub/Sub feature. In its current version, it is not able to handle IUs (incremental messages). Also, to my knowledge redis is not designed for communication over the network. Until now, no pkg/module uses the IU feature (except the example PingPongIU module). So, the redis com service should work for you in most cases.

You need a running redis server on your machine. You can find the installation instruction for redis here.

note

For Linux/Ubuntu you can do

curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list

sudo apt-get update
sudo apt-get install redis

You can test it by running:

redis-cli ping

It should print PONG.

You can install the redis_com_service via:

conda activate aaambos

pip install redis_com_service@git+https://gitlab.ub.uni-bielefeld.de/scs/aaambos/aaambos_pkg_redis_com_service@main

info

If you do not want to overwrite your local aaambos installation, you need to add --no-deps to the install command and install redis-py by hand. pip install redis.

The string for your arch_config.yml in the communication preferences is:

 - !name:redis_com_service.communications.redis_com.RedisServiceInfo

Troubleshooting

caution

ERROR: Could not build wheels for jsonnet-binary, which is required to install pyproject.toml-based projects

Solution:

conda install -c conda-forge jsonnet

caution

Error during installation of a custom-built ipaacar wheel wheel not supported on this platform on macOS ARM platform (M-Series).

Check what Python thinks is the running OS:

inside a python shell

>>> from distutils import util
>>> util.get_platform()

Example output: macosx-10.9-x86_64‘ even if you are on an ARM platform. Adapt the name of the created wheel to your output. Install the wheel.