Skip to content
chase-cpsPublic

About

Contract-based Heterogeneous Analysis and Systems Exploration

Resources

Contributing

Stars

9 stars

Watchers

3 watching

Forks

Repository files navigation

Contract-based Heterogeneous Analysis and Systems Exploration (CHASE)

CHASE is a framework for requirement capture, formalization, and validation for cyber-physical systems. It features a modular and extensible software infrastructure that can support different domain-specific languages, modeling formalisms, and analysis tools.

The CHASE framework components and flow

The front-end modules parse the specification languages and build the CHASE representation of a design problem. The CHASE libraries represent and manipulate systems, behaviors, and contracts. The back-end modules translate the problems into the languages of verification and synthesis tools (figure from the DATE 2018 paper).

This repository is the entry point to CHASE. It collects the CHASE modules as git submodules, and it provides the scripts to build and install all of them at once. Each module is developed in its own repository.

Repository structure

  • modules/core-library: the library providing the classes and structures to represent design problems and systems, and their Python bindings (chase-cps/core-library).
  • modules/chase-backends: the backends encoding CHASE problems into external tools, i.e., Slugs, GR1C, and the SMV language of nuXmv (chase-cps/chase-backends). It also has a printer for PySTL, written for an early version of PyCASSE: the scripts it writes do not run with the current PyCASSE.
  • modules/DSL_tool: the tool using a Domain Specific Language to specify discrete timed problems over architectures modeled as graphs (chase-cps/DSL_tool).
  • modules/logics_tool: the tool providing a console to manipulate assume-guarantee contracts expressed using a logics-based language (chase-cps/logics_tool).
  • modules/third_party: the third-party libraries required to build CHASE, i.e., the ANTLR4 C++ runtime (chase-cps/third_party).
  • demos: demonstrations and benchmarks of CHASE (chase-cps/demos).
  • legacy: demos of the monolithic version of CHASE developed until 2022, which are no longer maintained.
  • python: the chase_cps Python package (contracts, contract algebra, and the interface to the model checkers and synthesis tools).
  • tests: a script running all the demos and checking their results.

Quick start

The complete CHASE toolchain, with the gr1c, slugs, and NuSMV solvers, Yosys, and the demos, is available as a Docker image (for x86_64; on Apple Silicon, add --platform linux/amd64):

$>  docker pull ghcr.io/chase-cps/chase
$>  docker run --rm -it ghcr.io/chase-cps/chase

The container starts in the directory of the demos. The demos can be run and checked with:

$>  docker run --rm ghcr.io/chase-cps/chase /opt/chase/tests/demo-suite.sh

The image has no nuXmv: its license does not allow redistribution, and it may be used only for academic and non-commercial purposes (see its license). Without it, the checks use NuSMV, which has no real variables and no IC3. In a container, chase-cps install nuxmv --accept-license installs it.

The image can also be built from this repository, with nuXmv when its license is accepted:

$>  git clone --recursive https://github.com/chase-cps/chase
$>  cd chase
$>  docker build --build-arg ACCEPT_NUXMV_LICENSE=yes -t chase .

Installation from sources

CHASE requires CMake (version 3.18 or higher), a C++ compiler supporting C++17, Python 3 with its development files, and pybind11. On Ubuntu, they can be installed with:

$>  sudo apt-get install build-essential cmake git python3-dev pybind11-dev uuid-dev

On macOS, with Homebrew:

$>  brew install cmake pybind11

Then, clone the repository with its submodules and run the installation script:

$>  git clone --recursive https://github.com/chase-cps/chase
$>  cd chase
$>  ./install.sh /path/to/install/directory

If no directory is given, CHASE is installed in the install directory of the repository. At the end, the script prints the lines to add to the shell configuration file to use the tools and the Python modules, i.e.:

export PATH="/path/to/install/directory/chase/bin:$PATH"
export PYTHONPATH="/path/to/install/directory/chase/lib:$PYTHONPATH"

The Python modules are built for the interpreter given by the PYTHON environment variable (by default, python3), and they can only be imported by that version of Python. For instance:

$>  PYTHON=python3.13 ./install.sh /path/to/install/directory

The script runs the CMake superbuild defined in CMakeLists.txt, which builds and installs the modules in the required order. The superbuild can also be used directly:

$>  cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/path/to/install/directory
$>  cmake --build build

It accepts the following options:

  • CMAKE_INSTALL_PREFIX: the installation directory (default: build/install).
  • CMAKE_BUILD_TYPE: the build type (default: Release).
  • CHASE_BUILD_TESTS: builds the tests of the core library, which are then run by ctest --test-dir build (default: OFF).
  • Python_EXECUTABLE: the Python interpreter the Python modules are built for. PYTHON_EXECUTABLE is accepted as well.
  • pybind11_DIR, CMAKE_PREFIX_PATH: forwarded to all the modules to find pybind11. On macOS, pybind11 installed with Homebrew is found with -DCMAKE_PREFIX_PATH=$(brew --prefix).

To update an existing copy of the repository:

$>  git pull
$>  git submodule update --init --recursive
$>  ./install.sh /path/to/install/directory

The external tools used by the backends are not installed by the script. They are available at the following locations:

Python package

The chase_cps package, in the python directory, provides contracts written in the standard LTL syntax, in three layers:

  1. the contract algebra of the core library (composition, conjunction, quotient, separation, implication, ...), which holds for any assume-guarantee contracts;
  2. the checks on contracts (refinement, compatibility, consistency, implementation by a formula or a state machine, receptiveness), which reduce to the validity and the satisfiability of formulas, decided by nuXmv, with their cores;
  3. GR(1) synthesis with slugs: realizability, controllers, unrealizable cores, well-separation, and vacuity.

A failed check returns a counterexample trace. The variables are Booleans, integer ranges, reals, and words (bit vectors of a fixed width). Contracts are read and written in the logics language of CHASE and in SystemVerilog Assertions, and GR(1) contracts are written for slugs or gr1c (to_gr1). chase_cps.viz and chase-cps view draw contracts, components, and systems as a web page, with the results of the checks on the boxes.

The package also:

  • repairs a design: the values of named constants that make a check pass, at the least change (repair, chase-cps repair, with z3);
  • checks formulas over real numbers and bounded intervals of steps with z3, and gives their robustness on a trace;
  • reads the contracts written in a C file (the clauses of ESBMC, CBMC, or ACSL) and checks each function against its own with ESBMC or CBMC;
  • reads SMV models with their LTLSPEC and INVARSPEC;
  • checks a refinement in continuous time, when a step is a sample (chase_cps.sampled, chase-cps check --period --lipschitz).

The package, together with the compiled CHASE modules, is installed with:

$>  pip install chase-cps

or, from the sources:

$>  git clone --recursive https://github.com/chase-cps/chase
$>  cd chase
$>  pip install .

The checks call external tools, which are installed separately: nuXmv for the checks of layer 2, and slugs for GR(1) synthesis. chase-cps install nuxmv --accept-license and chase-cps install slugs install them, and chase-cps doctor shows the tools found. chase-cps check checks the contracts of a specification from the command line. The details are in the package README.

For instance:

from chase_cps import Contract, refines

spec = Contract.from_strings(inputs=["req"], outputs=["grant"],
                             assumptions=["G F !req"],
                             guarantees=["G (req -> F grant)"], name="Spec")
impl = Contract.from_strings(inputs=["req"], outputs=["grant"],
                             guarantees=["G (req -> X grant)"], name="Impl")
print(refines(impl, spec).status)

The tests are run with pytest. The operations of CHASE are also available to AI agents through the CHASE MCP server.

Documentation

Each module also contains its own documentation in its repository.

License

CHASE is released under the 3-Clause BSD License. The license of each module is available in the corresponding repository. The ANTLR4 C++ runtime in modules/third_party is distributed under its own license.

Citation

CHASE has been presented at the IEEE/ACM Design, Automation and Test in Europe (DATE) conference 2018. To cite CHASE in an academic work, please use the following bibtex entry:

@inproceedings{CHASE:2018:DATE,
  title={CHASE: Contract-based requirement engineering for cyber-physical system design},
  author={Nuzzo, Pierluigi and Lora, Michele and Feldman, Yishai A and Sangiovanni-Vincentelli, Alberto L},
  booktitle={Proceedings of the Design, Automation \& Test in Europe Conference \& Exhibition (DATE) 2018},
  pages={839--844},
  year={2018},
  organization={IEEE}
}

About

Contract-based Heterogeneous Analysis and Systems Exploration

Resources

Contributing

Stars

9 stars

Watchers

3 watching

Forks

Releases

Packages

Used by

Contributors

Languages