TRUST

[![CC BY 4.0][cc-by-shield]][cc-by]

TRUST is an open-source software tool developed for data-driven controller synthesis of dynamical systems with unknown mathematical models, ensuring either stability or safety properties. By collecting only a single input-state trajectory from the unknown system and satisfying a rank condition that ensures the system is persistently excited according to Willems et al.'s fundamental lemma, TRUST aims to design either control Lyapunov functions (CLF) or control barrier certificates (CBC), along with their corresponding stability or safety controllers. The tool implements sum-of-squares (SOS) optimization programs solely based on data to enforce stability or safety properties across four system classes:

continuous-time nonlinear polynomial systems,
continuous-time linear systems,
discrete-time nonlinear polynomial systems, and
discrete-time linear systems.

TRUST is a Python-based web application featuring an intuitive, reactive graphic user interface (GUI) built with web technologies. It can be accessed at https://trust.tgo.dev or installed locally, and supports both manual data entry and data file uploads. Leveraging the power of the Python backend and a JavaScript frontend, TRUST is designed to be highly user-friendly and accessible across desktop, laptop, tablet, and mobile devices. We apply TRUST to a set of physical benchmarks with unknown dynamics, ensuring either stability or safety properties across the four supported classes of models.

Artifact Evaluation
Installation
Local Development
Examples
Error Handling
Related Paper
Contributing Guide
License

Artifact Evaluation

If you are a reviewer for the HSCC committee, the instructions for how to install and reproduce the results of our paper can be found here.

We recommend running the tool via Docker, instructions in the installation section following.

A hosted version of the tool is available at https://trust.tgo.dev for you to explore the tool's capabilities, but note that the capacity of the server is limited and is unlikely to perform as well as a local installation.

Install Instructions

We have made every effort to ensure the following instructions are comprehensive for the Docker container under consideration.

Prerequisites

Docker

Docker is used for this project to simplify the installation process. You can download and install Docker by following their instructions for your operating system at https://docs.docker.com/get-docker/.

Mosek License

Since the underlying packages that TRUST uses rely on the MOSEK solver, we will now install the MOSEK license (a free trial is available and it is free for academic users). Fill in your details to get a Mosek license at https://www.mosek.com/license/request/?i=acp.

The license file will be emailed to you with instructions of where to place the file in your home directory. This license is required within the TRUST GUI, where you will be prompted to upload the file.

Installing TRUST

You can download the repository from Github at https://github.com/thatgardnerone/TRUST. Simply navigate to the page and click the green "Code" button, then "Download ZIP". Once downloaded, unzip the folder to your home directory which on Windows is usually C:\Users\YourUsername and on macOS and Linux is /home/YourUsername.

Change the folder name to TRUST to simplify the later steps.

The following steps will be run in a terminal. You can open a terminal on macOS by pressing Cmd + Space and typing "Terminal", or on Windows by pressing Win + R and typing cmd, then pressing Enter. On Linux, search for it in the applications menu as it varies by distribution.

Change directory to TRUST

Once you have a terminal open, navigate to the TRUST folder by running the following

# On macOS and Linux
cd ~/TRUST

Or on Windows

cd $HOME\TRUST

Copy the environment file

The project contains an example environment file .env.example, containing environment configuration variables that you may change, if needed. You can copy the example to a new file called .env by running:

# On macOS and Linux
cp .env.example .env

Or on Windows

copy .env.example .env

Build and run the Docker container

Next, build and run the Docker container by running:

# On any OS
docker compose up --build -d

View the tool

Finally, you can now access the locally installed tool by navigating to http://127.0.0.1:8000 in your web browser.

Local Development (without Docker)

For development or server deployment without Docker, you can set up TRUST using pyenv and Poetry.

Install pyenv

pyenv allows you to manage multiple Python versions. Install it following the instructions for your OS:

macOS (using Homebrew):

brew install pyenv
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zshrc

Linux:

curl https://pyenv.run | bash
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc

Install Python 3.12.10

pyenv install 3.12.10

Install Poetry

pip install poetry

Set up the project

cd ~/TRUST

# Use Python 3.12.10 for this project
pyenv local 3.12.10

# Install dependencies
poetry install

# Copy environment file
cp .env.example .env

Build the frontend

cd vite
npm ci
npm run build
cd ..

Run the application

poetry run python main.py

The application will be available at https://127.0.0.1:5000.

Upgrading an existing server

If you have an existing server installation (e.g., using a venv with an older Python version), you can upgrade as follows:

# Install Python 3.12.10 via pyenv
pyenv install 3.12.10

# Navigate to the project directory
cd /srv/trust.tgo.dev

# Remove old venv and create new one with Python 3.12.10
rm -rf venv
~/.pyenv/versions/3.12.10/bin/python -m venv venv
source venv/bin/activate

# Pull latest changes
cd current
git pull

# Install Poetry and dependencies
pip install poetry
poetry install --only main

# Rebuild frontend
cd vite
npm ci
npm run build

Examples

We present some selected examples graphically to demonstrate some use cases of TRUST. All the examples can be found in the folder TRUST/storage/cases where the case studies are organised in subfolders each containing the necessary data files and inputs for the example.

For each of the safety examples, the following conventions are used.

The initial region is shown in blue.
The unsafe region(s) are shown in red.
The gamma level set is shown in dashed red lines.
The lambda level set is shown in dashed blue lines.
Trajectories are shown in black, starting from the initial region and staying within the safe level set.

Note: These figures were rendered using a MATLAB script that is not included in the repository. Please feel free to reach out if you would like to know more about how these figures were generated.

Examples 1 and 2 - Continuous Time Nonlinear Polynomial Systems (Safety)

First figure: ct-NPS predator-prey system

Second figure: ct-NPS Van der Pol oscillator system

Example 3 to 5 - Continuous Time Linear Systems (Safety)

First figure: ct-LS DC motor system

Second figure: ct-LS room temperature system

Third figure: ct-LS two-tank system

Examples 6 and 7 - Discrete Time Nonlinear Polynomial Systems (Safety)

First figure: dt-NPS predator-prey system

Second figure: dt-NPS Lorenz system

Examples 8 to 11 - Discrete Time Linear Systems (Safety)

First figure: dt-LS DC motor system

Second figure: dt-LS room temperature system

Third figure: 3D dt-LS room temperature system

Fourth figure: dt-LS two-tank system

Examples 12 and 13 - Continuous Time Nonlinear Polynomial Systems (Stability)

First figure: ct-NPS predator-prey system

Second figure: ct-NPS Van der Pol oscillator system

Examples 14 to 16 - Continuous Time Linear Systems (Stability)

<img src="./storage/images/stability_ctLS_dc_motor.png" width="400"/> <img

TRUST

Install / Use

README

TRUST

Table of Contents

Artifact Evaluation

Install Instructions

Prerequisites

Docker

Mosek License

Installing TRUST

Change directory to TRUST

Copy the environment file

Build and run the Docker container

View the tool

Local Development (without Docker)

Install pyenv

Install Python 3.12.10

Install Poetry

Set up the project

Build the frontend

Run the application

Upgrading an existing server

Examples

Examples 1 and 2 - Continuous Time Nonlinear Polynomial Systems (Safety)

Example 3 to 5 - Continuous Time Linear Systems (Safety)

Examples 6 and 7 - Discrete Time Nonlinear Polynomial Systems (Safety)

Examples 8 to 11 - Discrete Time Linear Systems (Safety)

Examples 12 and 13 - Continuous Time Nonlinear Polynomial Systems (Stability)

Examples 14 to 16 - Continuous Time Linear Systems (Stability)