lucid  0.0.2
Lifting-based Uncertain Control Invariant Dynamics
Loading...
Searching...
No Matches
LUCID

Learning-Enabled Uncertainty-Aware Certification of Stochastic Dynamical Systems

lucid CI pylucid CI Docker CI Docs CI

Remarks
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.

Quick installation

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.

  • Docker (pre-built)

    Fully fledged Docker image available on the GitHub repository's container registry.

    Requirements

    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:main

  • Docker (source)

    Fully 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

    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 lucid

  • Docker (light)

    Lightweight 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.yaml

  • Python (pre-built)

    Requirements

    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__)"

  • Python (from source)

    Requirements

    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__)"

  • Source

    Requirements

    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]

Quick start

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.

  • Command line arguments (quick testing)

    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.04

    Python

    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.04

  • GUI (visual)

    The 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:main

    Python

    pylucid-gui

  • Configuration file (flexible)

    Assuming 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.yaml

    Docker (light)

    docker run --name lucid -it --rm \
  -v/path/to/config.yaml:/config.yaml \
  ghcr.io/tendto/lucid-light:main /config.yaml

    Python

    pylucid config.yaml

Citing LUCID

If 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}
}