Skip to content

A code generator from high-level formal specifications for monitoring and pattern matching sequential/temporal data.

License

Notifications You must be signed in to change notification settings

doganulus/reelay-codegen

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

45 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

reelay

reelay is a C++ code generator for monitoring, pattern matching, and analyzing temporal data streams on-the-fly. reelay allows developers to monitor high-level (formal) patterns for their applications in an efficient and effortless way. reelay supports several popular pattern specification languages, namely regular expressions, temporal logic, and their variants (especially timed extensions). Application areas include real-time data analytics and robotics.

install

The easiest way to install reelay is to run the following command (assuming git installed).

pip install git+https://github.com/doganulus/reelay.git

Compiling generated code further requires a C++14 compatible compiler and Boost C++ libraries installed on your system.

usage

reelay provides a command-line script to generate monitors from the specification.

reelay [OPTION]... SPECFILE

Positional Arguments:
 
SPECFILE    High-level monitor specification in YAML format
 
Specification Control:
 
OPTION      Override the corresponding option in the specification

getting started

Monitors generated by reelay process data sequences [rows, messages] in an online fashion. For example, consider an evolution of two Boolean variables p1 and p2 starting from time 1 as follows.

     1 2 3 4 5 6 7 8 9 ...
p1 : 0 1 0 0 0 0 1 1 0 ...
p2 : 0 0 1 1 1 1 0 0 0 ...

Suppose that we would like to detect a pattern such that the variable p2 is repeatedly true (1) between two time points where p1 is true (1). This pattern is concisely expressed as p1;p2+;p1 in regular expressions. Then the generated monitor for this pattern would process such a sequence incrementally and yield true (1) at its output y whenever this pattern is detected over the sequence. The result of monitoring would be as follows.

     1 2 3 4 5 6 7 8 9 ...
p1 : 0 1 0 0 0 0 1 1 0 ...
p2 : 0 0 1 1 1 1 0 0 0 ...

 y : 0 0 0 0 0 0 1 0 0 ...

Above we see the monitor outputs true at time 7 since p1 is true at time 2 and 7 as well as p2 is true between these time points. reelay supports regular expressions and temporal logic patterns together with several popular variants thereof. Detailed information about pattern specification can be found in corresponding pages of syntax and reference for regular expression patterns and syntax and references for temporal logic patterns.

reelay requires monitor specifications written in YAML format. Minimally, specification files contain a name, the high-level pattern language (either regular expressions or temporal logic), and the actual pattern to be monitored. For example, the specification file my_spec.yaml below defines a monitor called MySpec that watches a regular expression pattern p1;p2+;p1.

# This is my_spec.yaml  
---
name : "MySpec"
lang : "regexp"
pattern : "p1;p2+;p1"

Then we simply execute reelay to generate a C++ class in MonitorMySpec.hpp that handles monitoring of the specified pattern.

reelay my_spec.yaml

Details about the monitor structure can be found in Tutorial: Monitoring CSV files.

Besides various pattern specification languages, reelay allows monitoring of numerical and mixed-type data sequences in a similar manner. For that, we provide support for arbitrary predicates (given by user as C++ functions in some header files) and basic types for variables. For example, the patterns describes a case where x1 variable is less than 3.4 and then x2 variable is repeatedly greater than 7 and then Boolean p3 variable is true.

pattern : "lt(x1:double, 3.4) ; gt(x2:int, 7)+ ; p3"

     1   2   3   4   5   6   7   8   9 
x1 : 1.1 4.3 1.5 5.5 5.6 6.0 6.0 6.0 6.0
x2 : 2   3   8   8   44  12  10  5   6
p3 : 0   0   1   0   0   0   0   1   0 

 y : 0   0   0   0   0   0   0   1   0

Note that this extension is particularly useful to detect patterns over temporal sequences coming from various sensors.

applications

reelay package includes two example applications to monitor (1) CSV files and (2) data streams of Robot Operating System (ROS). These applications can be found in examples folder.

naming

The name reelay comes from relay circuits as initially I lay down regular expressions (REs) into sequential circuits. Then I have applied a distortion effect to the pronouncation.