Summary

This repository contains the source code for UBC CS 2025 Summer research project "Using Lingua Franca to model fault-tolerant distributed real-time systems".

Here is the explanation on how to run the system and evaluating the performance.

Environment Setup

In our environment setup, we udeploy the federate execution on a cluster of 5 leap machines, and distribute the programs from a client machine. The client machine is not part of the distributed system.

Our code and scripts expect the leap machines to have fixed hostnames and DNS (leap1*), and fixed IPs (10.34.167.16* and 10.34.167.17*). It is assumed that the client machine can execute command ssh leap1* to connect to any of the Pis.

There is one leap machine working as the plant in simulation, and worked as RTI. (For specification of RTI: https://www.lf-lang.org/docs/writing-reactors/distributed-execution)

Leap machines can be replaced by other machines, making sure to change the ip address and/or DNS in the federate reactor correspondingly.

When I was running the program, I used inverted_pendulum_distribute_copy.sh because my client machine does not allow me to ssh to the ip address of any of the nodes in distributed system. However, the machines need to connect each other in ip address because I am not authorized to define DNS of other nodes in any of the leap machines. Thus, in inverted_pendulum.lf, I specify the work distribution using ip addresses, but instead of using the inverted_pendulum_distribute.sh which is auto-generated by the LF compiler, I used inverted_pendulum_distribute_copy.sh to distribute the programs. The difference between inverted_pendulum_distribute_copy.sh and inverted_pendulum_distribute.sh is that all ip addresses used for distributing programs by client machine are changed by DNS so that my client machine can connect to these nodes and distribute the programs. If this is not a problem for you, you can use 'inverted_pendulum_distribute.sh' directly.

For installation and prerequisites for federate execution of Lingua Franca, refer to https://www.lf-lang.org/docs/installation for installation of Lingua Franca on client machine and Prerequisites for Distributed Execution sector in https://www.lf-lang.org/docs/writing-reactors/distributed-execution.

Running Natively

1. After directing to the correct directory, run the compiler by writing command lfc src/inverted_pendulum.lf on terminal

2. Run bin/inverted_pendulum_distribute.sh (Or bin/inverted_pendulum_distribute_copy.sh)

3. Run ./run.sh

4. (Optional) Run retrieve_data.sh to get the data files from all of the nodes in distributed system, remeber to change the corresponding names of files before running the script file

Brief Explanation of directories and files

bin, fed-gen, include: directories and files auto-generated by LF compiler (expect for inverted_pendulum_distribute_copy.sh)

src/inverted_pendulum.lf: Lingua Franca file containing all of the implementation

evaulation: The directory containing where all the data files for evaluation goes into

graphs: The directory containing all the evaluation graphs

evaluation.ipynb, evaluation_faulty.ipynb: Python files for producing evaluation graphs based on data files. evaluation_faulty is for producing evaluation graphs when one of the machine having reactors of faulty_published_store and faulty_InConcReTeS

retrieve_data.sh: Script file for retrieve data files to local machine

run.sh: Script file for running the program locally