Learning-Enabled Uncertainty-Aware Certification of Stochastic Dynamical Systems
Tip
Try out the online demo! Note that the memory in the browser is limited, so only small problems can be solved.
Warning
This project is under active development. Features and APIs may change without prior notice. Please refer to the changelog for the latest updates.
For more details, see the installation or the Pylucid sections. If you encounter any errors, please refer to the Troubleshooting section or open an issue.
Fully fledged Docker image available on the GitHub repository's container registry.
Requirements
- Docker
- (Optional) Gurobi Web License Service (WLS) license
Command
# Pull the image
docker pull ghcr.io/tendto/lucid:main
# Run the image on script/path/to/script.py.
# Needs a Gurobi WS licence to use the Gurobi solver.
docker run --name lucid -it --rm \
-v/path/to/script.py:/scripts \
-v/path/to/gurobi.lic:/opt/gurobi/gurobi.lic:ro \
ghcr.io/tendto/lucid:main /scripts/script.py
# Run the GUI.
# Needs a Gurobi WS licence to use the Gurobi solver.
docker run --name lucid -it --rm -p 3661:3661 \
-v/path/to/gurobi.lic:/opt/gurobi/gurobi.lic:ro \
--entrypoint pylucid-gui ghcr.io/tendto/lucid:mainFully fledged Docker image that you can build from source. Useful if you want to apply custom modifications to the codebase or if you want to use a specific commit as a base. Intended for advanced users.
Requirements
- Docker
- (Optional) Gurobi Web License Service (WLS) license
Command
# Build the image
docker build -t lucid .
# Run the image on /path/to/script.py.
# You will need a Gurobi WS licence to use the Gurobi solver.
docker run --name lucid -it --rm \
-v/path/to/script.py:/scripts \
-v/path/to/gurobi.lic:/opt/gurobi/gurobi.lic:ro \
lucid /scripts/script.py
# Run the GUI.
# You will need a Gurobi WS licence to use the Gurobi solver.
docker run --name lucid -it --rm -p 3661:3661 \
-v/path/to/gurobi.lic:/opt/gurobi/gurobi.lic:ro \
--entrypoint pylucid-gui lucidLightweight Docker image available on the GitHub repository's container registry.
This image does not support the Gurobi solver, relaying instead on open-source solvers only (e.g., HiGHS).
Moreover, it does not include the Python wrapper pylucid, so it can only parse .yaml configuration files.
As a result, it has a significantly smaller footprint (~70MB).
Requirements
Command
# Run the image on /path/to/config.yaml.
docker run --name lucid -it --rm \
-v/path/to/config.yaml:/config.yaml \
ghcr.io/tendto/lucid-light:main /config.yamlRequirements
- Python 3.8 or higher
- Linux, Glibc >= 2.35, Windows or ARM macOS operating system
- (Optional) Gurobi licence
Installation commands
# Create a virtual environment - Linux (optional)
python3 -m venv .venv ; source .venv/bin/activate
# Create a virtual environment - Windows (optional)
python3 -m venv .venv ; .venv\Scripts\activate
# Install pylucid (with GUI and Gurobi support, optional)
pip install "pylucid[gui,gurobi]" --index-url "https://gitlab.com/api/v4/projects/71977529/packages/pypi/simple"
# Ensure pylucid is installed correctly
python3 -c "import pylucid; print(pylucid.__version__)"Requirements
- Bazel 8.1.1
- Python 3.8 or higher
- C++ compiler with C++20 support.
We tested in particular:- On Linux: gcc 11.4.0
- On Windows: msvc 19.32.31332
- On macOS: Clang/LLVM 15.0.0
- (Optional) Gurobi licence
Installation commands
# Clone the repository and move to its root
git clone https://github.com/TendTo/lucid.git
cd lucid
# Create a virtual environment - Linux (optional)
python3 -m venv .venv ; source .venv/bin/activate
# Create a virtual environment - Windows (optional)
python3 -m venv .venv ; .venv\Scripts\activate
# Install pylucid (with GUI and Gurobi support, optional)
pip install ".[gui,gurobi]"
# Ensure pylucid is installed
python3 -c "import pylucid; print(pylucid.__version__)"Requirements
- Bazel 8.1.1
- C++ compiler with C++20 support.
We tested in particular:- On Linux: gcc 11.4.0
- On Windows: msvc 19.32.31332
- On macOS: Clang/LLVM 15.0.0
- (Optional) Gurobi licence
Installation commands
# Clone the repository
git clone https://github.com/TendTo/lucid.git
# Move to the root of the repository
cd lucid
# Compile and run lucid
bazel run //lucid -- [args]Start using Lucid immediately via the command line, GUI or configuration file. For more details, see the Configuration section.
Note
You will need a Gurobi licence to use the Gurobi solver.
Docker
docker run --name lucid -it --rm \
ghcr.io/tendto/lucid:main --X_bounds "RectSet([-1], [1])" \
--X_init "RectSet([-0.5], [0.5])" \
--X_unsafe "MultiSet([RectSet([-1], [-0.9]), RectSet([0.9], [1])])" \
--system_dynamics "x1 / 2" --num_frequencies 6 \
--feature_sigma_l 0.0925 --optimiser HighsOptimiser \
--set_scaling 0.04Python
pylucid --X_bounds "RectSet([-1], [1])" \
--X_init "RectSet([-0.5], [0.5])" \
--X_unsafe "MultiSet([RectSet([-1], [-0.9]), RectSet([0.9], [1])])" \
--system_dynamics "x1 / 2" --num_frequencies 6 \
--feature_sigma_l 0.0925 --optimiser HighsOptimiser \
--set_scaling 0.04The GUI will be available at http://localhost:3661.
Docker
docker run --name lucid -it --rm \
-p 3661:3661 \
--entrypoint pylucid-gui ghcr.io/tendto/lucid:mainPython
pylucid-guiAssuming we have a config.yaml configuration file.
Docker
docker run --name lucid -it --rm \
-v/path/to/config.yaml:/config.yaml \
ghcr.io/tendto/lucid:main /config.yamlDocker (light)
docker run --name lucid -it --rm \
-v/path/to/config.yaml:/config.yaml \
ghcr.io/tendto/lucid-light:main /config.yamlPython
pylucid config.yamlIf you use LUCID in your research, please cite the following paper:
@misc{casablanca2025lucidlearningenableduncertaintyawarecertification,
title = {LUCID: Learning-Enabled Uncertainty-Aware Certification of Stochastic Dynamical Systems},
author = {Ernesto Casablanca, Oliver Schön, Paolo Zuliani and Sadegh Soudjani},
year = {2025},
eprint = {2512.11750},
archiveprefix = {arXiv},
primaryclass = {eess.SY},
url = {https://arxiv.org/abs/2512.11750}
}