Upgrading MATRX v1.1.x to v.2.0.0

With V2.0.0, MATRX has been updated to include a long-requested functionality: a chat that (reliably) works. The changes that make this possible in version 2.0.0 have been done almost completely under the hood, bothering the users as little as possible with changes in how MATRX works. Nevertheless, a number of changes had to be made to the MATRX API for fetching messages, breaking backwards compatibility for some users, and thus introducing a new major version of MATRX.

In this tutorial we explain if you need to do anything, and if so how to upgrade your MATRX experiment from V1.1.x to v.2.0.0.

If you want directly skip to upgrading your MATRX experiment, you can skip the next section.

What has changed (under the hood)?

The MATRX chat as implemented in V1.1.x worked, but was not very robust. This was mainly experienced in the default MATRX visualizer, where messages occasionally didn’t get through (requiring a refresh), or it was even possible to spy on other agent their private conversations (see the issue here). This was caused by how messages are requested via the MATRX API in V1.x.x, which relied on sending the tick number for determining what messages to send to the frontend. But depending on the hardware or complexity of the Gridworld being simulated, the MATRX visualizer occasionaly skips ticks to keep up with the Gridworld, resulting in messages being missed. Because of how it was built, there was no good method to counter this.

The newly implemented solution in MATRX V2.0.0 is for the API to work with chat_offsets instead of ticks, similar to how chat applications such as Telegram work. For each chatroom, the user can send the message index ID (e.g. the 10th message) of the latest message received, such that MATRX will send any new or missed messages from that message onwards. Thus no longer missing any messages.

How do I upgrade my MATRX experiment?

By default, upgrading your MATRX version to v2.0.0 is as simple as updating it using PIP:

pip install --upgrade matrx

However, if you also have made changes to the MATRX visualizer, or have a completely custom frontend, there might be some additional changes you have to make. Below is described what you have to do for each of the different methods of using MATRX.

A. I use MATRX with the default matrx visualizer

Installing the new MATRX version using pip is enough 🙂

B. I have a customized version of the default MATRX visualizer

1. Install MATRX V2.0.0 with pip
2. A number of core files from the MATRX visualizer have been updated. It is easiest to just replace the complete files with their new version from the MATRX visualizer V2.0.0. Files to be replaced:
   • loop.js
   • toolbar.js
3. A number of changes have been made to gen_grid.js. This is a file that is often changed when customizing the frontend. If you don’t have any changes in this file, you can directly replace it with the new version like done for the two files above. Otherwise, it might be easiest to make these changes by hand in your custom version of gen_grid.js:
   • Remove the functions process_messages and process_message.
   • Remove the variable messages.
   • Remove line ~198 pop_new_chat_dropdown = true;
   • Change process_messages(new_messages) to process_messages(new_messages, accessible_chatrooms)
   • Replace the function compare_objects with the new version from MATRX v.2.0.0.
   • For all templates do the following
     • Replace chat_rooms_list with chatrooms_list.
     • Remove the following line: <div class="contact contact_active" id="chatroom_global" onclick="chatroom_click(event)">Global<span class="chat-notification" id="chatroom_global_notification"></span></div>

C. I have a competely custom frontend that directly uses the MATRX API

For instance a Unity frontend.

1. Install MATRX V2.0.0 with pip
2. If you don’t use either of the two following API calls, you are done!
   • /get_latest_state_and_messages
   • /get_messages
3. If you do use one or both of the above two API calls, the most important changes to make are changing your API request from a GET to a POST request, with JSON data containing the agent_id and chat_offsets parameters. For the specifics of these two parameters see the API documentation or the api.py source file. For the full set of changes, see the release notes of V2.0.0 [link].

I don’t want to upgrade, how do I prevent this?

For a variety of reasons it might be the case that you don’t want to upgrade, such as:

• You are almost going to carry out user experiments with your MATRX experiment, and don’t want to take the risk of upgrading MATRX and introducing extra work or new bugs.
• You don’t use the chat.
• You have an old MATRX project that uses an old version of MATRX (< V1.1.0) that requires extra work to upgrade.

Overall we recommend to keep up-to-date as much as possible with new versions. The longer you wait with upgrading, the more difficult it will become. It might be that the current addition is not something you need, but the next one might (online MATRX deployment for online experiments, machine learning agents, events). Those new features most likely use changes in the new version, and possibly cannot be used anymore with older MATRX versions.

Nevertheless, it is quite easy to postpone or prevent a MATRX upgrade. This can be done by making sure you have the old MATRX version installed, easiest done by setting a specific version number of MATRX in your requirements.txt like so:

matrx==1.1.2

And then installing MATRX via the requirements.txt:

pip install --upgrade -r requirements.txt