# Mata: The Automata Library
[](https://github.com/VeriFIT/mata)
[](https://github.com/VeriFIT/mata/actions/workflows/code-quality.yml)
[](https://github.com/VeriFIT/mata/actions/workflows/python-binding.yml)
[](https://codecov.io/gh/VeriFIT/mata)
Mata is an open source automata library that offers interface for different kinds of automata (NFA, etc.). Currently, Mata offers two interfaces:
1. An efficient library implemented in C/C++
2. A flexible wrapper implemented in Python that uses the efficient library
# Requirements and dependencies
For a successful installation of Mata, `cmake` of version `3.15.0` (or higher) and a C++ compiler with a support of C++-20 standard is required.
From optional requirements, `doxygen` is required for a generation of the documentation and `catch2` is required for the unit testing (Mata can still be compiled without these optional dependencies).
The Mata library further depends on the following libraries, included in the `3rdparty` directory:
- `cudd` for BDD manipulation,
- `re2` for regular expression parsing and the corresponding automata construction, and
- `simlib` for a simulation computation.
# Building and installing from sources
To build the library, run the following:
```
git clone https://github.com/VeriFIT/mata
cd mata
make release
```
In order to install the library, you can run
```
sudo make install
```
In order to verify the functionality of the library, you can run the test suite:
```
make test
```
You might, need to install the dependencies to measure the coverage of the tests.
Run the following to install the dependencies for MacOS:
```
brew install lcov gcovr
```
Run the following to install the dependencies for Ubuntu:
```
sudo apt-get install -y build-essential lcov gcovr xdg-utils
```
# Python binding
Mata offers binding of its efficient library to Python. You can install the binding as an Python
package on your system as follows.
### Install from PyPI
To install a latest version from the PyPI repository, run
```
pip3 install libmata
```
### Building from sources
To build from sources first, install the necessary requirements for Python and your
system. We recommend using the virtual environemnt (`venv`) to install and use the library.
```
python -m pip install --upgrade pip
make -C bindings/python init
sudo apt-get -qq update
sudo apt-get -qq install -y graphviz graphviz-dev
```
Now, you can install the library.
```
make -C bindings/python install
```
Finally, you can verify the binding woks as expected by running the test suite:
```
make -C bindings/python test
```
# Getting started
To get started, we refer to the [examples](examples/) in our repository.
This directory contains examples of various usage in form of:
1. C/C++ example programs. By default, they are built with the library. To run for example the first example:
```
./build/examples/example01-simple
```
3. Python example scripts. To run the scripts run the following.
```
python examples/example01-python-binding.py
```
4. Python jupyter notebooks. To run the jupyter notebook, one needs to have jupyter installed as
a prerequisite. The run the jupyter notebook, that creates an instance on your local server.
Navigate to generated link to see the available jupyter notebooks:
```
pip3 install jupyter
jupyter notebook
```
## Using the library
The library can be used directly in the C/C++ code. The result of compilation is a static
or dynamic library, that can be linked to ones project. Note, that the library is dependent
on several other 3rd party libraries (e.g., `libre2` or `libsimlib`), which are included in
the repository.
First import the library in your code. If the library is properly installed, you can use
the standard include.
```cpp
#include <mata/nfa/nfa.hh>
```
We recommend to use the `mata::nfa` namespace for easier usage:
```cpp
using namespace mata::nfa;
```
Start by creating an automaton with fixed number of states.
```cpp
int main() {
Nfa aut(4);
```
You can set the initial and final states directly using the initializers.
```cpp
aut.initial = {0, 1};
aut.final = {2, 3};
```
Further, you can add transitions in form of tripple `(state_from, symbol, targets)`:
```cpp
aut.delta.add(0, 0, 2);
aut.delta.add(1, 1, 3);
```
You can verify the state of your automaton by generating the automaton in `.dot` format.
```cpp
aut.print_to_DOT(std::cout);
return 0;
}
```
We recommend `cmake` for building projects using Mata. Provided the Mata is installed in the system directories,
the `CMakeLists.txt` file for the example may look like:
```cmake
cmake_minimum_required (VERSION 3.15.0)
project (mata-example)
set (CMAKE_CXX_STANDARD 20)
find_library(LIBMATA mata REQUIRED)
add_executable(mata-example
mata-example.cc)
target_link_libraries(mata-example PUBLIC ${LIBMATA})
```
## Using the Python binding
The python binding is installed (by default) to your local python package repository. You can
either use the binding in your own scripts or in the python interpreter.
You can start using the binding by importing the `libmata` package.
```python
import libmata.nfa.nfa as mata_nfa
```
In your own scripts, we recommend to use the standard guard for running the scripts, as follows.
```python
if __name__ == "__main__":
```
The usage of the binding copies (to certain levels) the usage of the C++ library.
```python
aut = mata_nfa.Nfa(4)
aut.initial_states = {0, 1}
aut.final_states = {2, 3}
aut.add_transition(0, 0, 2)
aut.add_transition(1, 1, 3)
print(aut.to_dot_str())
```
You can either run your scripts directly using `python` or compile it using the `cython` project.
# Publications
- Chocholatý, D., Fiedor, T., Havlena, V., Holík, L., Hruška, M., Lengál, O., & Síč, J. (2023). [Mata, a Fast and Simple Finite Automata Library](https://doi.org/10.48550/arXiv.2310.10136). arXiv preprint arXiv:2310.10136.
- Chocholatý, D., Fiedor, T., Havlena, V., Holík, L., Hruška, M., Lengál, O., Síč, J.: [A replication package for reproducing the results of paper “Mata: A fast and simple finite automata library”](https://doi.org/10.5281/zenodo.10044515) (Oct 2023).
# Contributing
If you'd like to contribute to the libmata,
please [fork the repository](https://github.com/VeriFIT/mata/fork), create a new
feature branch, and finally [create a new pull request](https://github.com/VeriFIT/mata/compare).
In case you run into some unexpected behaviour, error or anything suspicious
either contact us directly through mail or
[create a new issue](https://github.com/VeriFIT/mata/issues/new/choose).
When creating a new issue, please, try to include everything necessary for us to know
(such as the version, operation system, etc.) so we can sucessfully replicate the issue.
## Note to main contributors
By default, each merge automatically increases the `minor` version of the library
(i.e., `0.0.0 -> 0.1.0` ). This can be overruled using either tag `#patch` (increasing
patch version, i.e., `0.0.0 -> 0.0.1`) or `#major` (increasing major version, i.e.,
`0.0.0 -> 1.0.0`). This tag is specified in the merge message.
Generally, it is recommended to use `#major` for changes that introduces backward-incompatible
changes for people that used previous versions, and `#patch` for minor changes, such as bug-fixes,
performance fixes or refactoring.
# Links
- Project (origin) repository: <https://github.com/verifit/mata>
- Issue tracker: <https://github.com/verifit/mata/issues>
- In case of some sensitive bugs (like security vulnerabilities),
please contact us directly, instead of using issue tracker.
We value your effort to improve the security and privacy of this project!
- Project documentation: <https://verifit.github.io/mata>
- Jupyter notebooks demonstrating `mata` usage: <https://github.com/VeriFIT/mata/tree/devel/examples/notebooks>
- [Example 01: WS1S Logic](https://github.com/VeriFIT/mata/tree/devel/examples/notebooks/example-01-ws1s-formulae.ipynb)
- [Example 02: ReDoS Attacks](https://github.com/VeriFIT/mata/tree/devel/examples/notebooks/example-02-redos-attacks.ipynb)
- [Example 03: Exploring Maze](https://github.com/VeriFIT/mata/tree/devel/examples/notebooks/example-03-exploring-maze.ipynb)
Also, check out our research group focusing on program analysis, static and dynamic analysis,
formal methods, verification and many more:
<http://www.fit.vutbr.cz/research/groups/verifit/index.php.en>.
# Licensing
The code of Mata is licensed under MIT licence. See [LICENSE](LICENSE).
The folder [`3rdparty/`](3rdparty) contains 3rd party applications licensed under their own licences, included with the code.
# Contacts
See [AUTHORS.md](AUTHORS.md)
# Acknowledgements
We thank for the support received from the Brno University of Technology
([BUT FIT](https://www.fit.vutbr.cz/)).
Development of this tool has been supported by the following projects: ???.
This tool as well as the information provided on this web page reflects
only the author's view and no organization is responsible for any use
that may be made of the information it contains.
Raw data
{
"_id": null,
"home_page": "https://github.com/verifit/mata",
"name": "libmata",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "automata, finite automata, alternating automata",
"author": "Luk\u00e1\u0161 Hol\u00edk <holik@fit.vutbr.cz>, Ond\u0159ej Leng\u00e1l <lengal@fit.vutbr.cz>, Martin Hru\u0161ka <ihruskam@fit.vutbr.cz>, Tom\u00e1\u0161 Fiedor <ifiedortom@fit.vutbr.cz>, David Chocholat\u00fd <chocholaty.david@protonmail.com>, Juraj S\u00ed\u010d <sicjuraj@fit.vutbr.cz>, Tom\u00e1\u0161 Vojnar <vojnar@fit.vutbr.cz>",
"author_email": "lengal@fit.vutbr.cz",
"download_url": "https://files.pythonhosted.org/packages/65/e9/b6accfb8440deceaa8752a694e1ae4bf86116b439b283ab29bfe729dcb3f/libmata-1.2.3.tar.gz",
"platform": null,
"description": "# Mata: The Automata Library\n\n[](https://github.com/VeriFIT/mata)\n[](https://github.com/VeriFIT/mata/actions/workflows/code-quality.yml)\n[](https://github.com/VeriFIT/mata/actions/workflows/python-binding.yml)\n[](https://codecov.io/gh/VeriFIT/mata)\n\nMata is an open source automata library that offers interface for different kinds of automata (NFA, etc.). Currently, Mata offers two interfaces:\n\n 1. An efficient library implemented in C/C++\n 2. A flexible wrapper implemented in Python that uses the efficient library\n\n# Requirements and dependencies\n\nFor a successful installation of Mata, `cmake` of version `3.15.0` (or higher) and a C++ compiler with a support of C++-20 standard is required. \nFrom optional requirements, `doxygen` is required for a generation of the documentation and `catch2` is required for the unit testing (Mata can still be compiled without these optional dependencies). \n\nThe Mata library further depends on the following libraries, included in the `3rdparty` directory:\n- `cudd` for BDD manipulation,\n- `re2` for regular expression parsing and the corresponding automata construction, and\n- `simlib` for a simulation computation.\n\n# Building and installing from sources\n\nTo build the library, run the following:\n\n```\ngit clone https://github.com/VeriFIT/mata\ncd mata\nmake release\n```\n\nIn order to install the library, you can run \n\n```\nsudo make install\n```\n\nIn order to verify the functionality of the library, you can run the test suite:\n\n```\nmake test\n```\n\nYou might, need to install the dependencies to measure the coverage of the tests. \nRun the following to install the dependencies for MacOS:\n\n```\nbrew install lcov gcovr\n```\n\nRun the following to install the dependencies for Ubuntu:\n\n```\nsudo apt-get install -y build-essential lcov gcovr xdg-utils\n```\n\n# Python binding\n\nMata offers binding of its efficient library to Python. You can install the binding as an Python\npackage on your system as follows. \n\n### Install from PyPI\n\nTo install a latest version from the PyPI repository, run \n```\npip3 install libmata\n```\n\n### Building from sources\n\nTo build from sources first, install the necessary requirements for Python and your\nsystem. We recommend using the virtual environemnt (`venv`) to install and use the library.\n\n```\npython -m pip install --upgrade pip\nmake -C bindings/python init\n\nsudo apt-get -qq update \nsudo apt-get -qq install -y graphviz graphviz-dev\n```\n\nNow, you can install the library.\n\n```\nmake -C bindings/python install\n```\n\nFinally, you can verify the binding woks as expected by running the test suite:\n\n```\nmake -C bindings/python test\n```\n\n# Getting started\n\nTo get started, we refer to the [examples](examples/) in our repository.\nThis directory contains examples of various usage in form of:\n\n 1. C/C++ example programs. By default, they are built with the library. To run for example the first example:\n\n```\n./build/examples/example01-simple\n```\n\n 3. Python example scripts. To run the scripts run the following.\n\n```\npython examples/example01-python-binding.py\n```\n\n 4. Python jupyter notebooks. To run the jupyter notebook, one needs to have jupyter installed as\n a prerequisite. The run the jupyter notebook, that creates an instance on your local server.\n Navigate to generated link to see the available jupyter notebooks:\n \n```\npip3 install jupyter\njupyter notebook\n```\n\n## Using the library\n\nThe library can be used directly in the C/C++ code. The result of compilation is a static\nor dynamic library, that can be linked to ones project. Note, that the library is dependent\non several other 3rd party libraries (e.g., `libre2` or `libsimlib`), which are included in\nthe repository.\n\nFirst import the library in your code. If the library is properly installed, you can use\nthe standard include.\n\n```cpp\n#include <mata/nfa/nfa.hh>\n```\n\nWe recommend to use the `mata::nfa` namespace for easier usage:\n\n```cpp\nusing namespace mata::nfa;\n```\n\nStart by creating an automaton with fixed number of states.\n\n```cpp\nint main() {\n Nfa aut(4);\n```\n\nYou can set the initial and final states directly using the initializers.\n\n```cpp\n aut.initial = {0, 1};\n aut.final = {2, 3};\n```\n\nFurther, you can add transitions in form of tripple `(state_from, symbol, targets)`:\n\n```cpp\n aut.delta.add(0, 0, 2);\n aut.delta.add(1, 1, 3);\n```\n\nYou can verify the state of your automaton by generating the automaton in `.dot` format.\n\n```cpp\n aut.print_to_DOT(std::cout);\n\n return 0;\n}\n```\n\nWe recommend `cmake` for building projects using Mata. Provided the Mata is installed in the system directories,\nthe `CMakeLists.txt` file for the example may look like:\n\n```cmake\ncmake_minimum_required (VERSION 3.15.0)\nproject (mata-example)\nset (CMAKE_CXX_STANDARD 20)\n\nfind_library(LIBMATA mata REQUIRED)\n\nadd_executable(mata-example\n mata-example.cc)\ntarget_link_libraries(mata-example PUBLIC ${LIBMATA})\n```\n\n## Using the Python binding\n\nThe python binding is installed (by default) to your local python package repository. You can\neither use the binding in your own scripts or in the python interpreter.\n\nYou can start using the binding by importing the `libmata` package.\n\n```python\nimport libmata.nfa.nfa as mata_nfa\n```\n\nIn your own scripts, we recommend to use the standard guard for running the scripts, as follows.\n\n```python\nif __name__ == \"__main__\":\n```\n\nThe usage of the binding copies (to certain levels) the usage of the C++ library.\n\n```python\n aut = mata_nfa.Nfa(4)\n\n aut.initial_states = {0, 1}\n aut.final_states = {2, 3}\n aut.add_transition(0, 0, 2)\n aut.add_transition(1, 1, 3)\n\n print(aut.to_dot_str())\n```\n\nYou can either run your scripts directly using `python` or compile it using the `cython` project.\n\n# Publications\n- Chocholat\u00fd, D., Fiedor, T., Havlena, V., Hol\u00edk, L., Hru\u0161ka, M., Leng\u00e1l, O., & S\u00ed\u010d, J. (2023). [Mata, a Fast and Simple Finite Automata Library](https://doi.org/10.48550/arXiv.2310.10136). arXiv preprint arXiv:2310.10136.\n - Chocholat\u00fd, D., Fiedor, T., Havlena, V., Hol\u00edk, L., Hru\u0161ka, M., Leng\u00e1l, O., S\u00ed\u010d, J.: [A replication package for reproducing the results of paper \u201cMata: A fast and simple finite automata library\u201d](https://doi.org/10.5281/zenodo.10044515) (Oct 2023).\n\n# Contributing\n\nIf you'd like to contribute to the libmata, \nplease [fork the repository](https://github.com/VeriFIT/mata/fork), create a new \nfeature branch, and finally [create a new pull request](https://github.com/VeriFIT/mata/compare).\n\nIn case you run into some unexpected behaviour, error or anything suspicious\neither contact us directly through mail or \n[create a new issue](https://github.com/VeriFIT/mata/issues/new/choose).\nWhen creating a new issue, please, try to include everything necessary for us to know\n(such as the version, operation system, etc.) so we can sucessfully replicate the issue.\n\n## Note to main contributors\n\nBy default, each merge automatically increases the `minor` version of the library\n(i.e., `0.0.0 -> 0.1.0` ). This can be overruled using either tag `#patch` (increasing\npatch version, i.e., `0.0.0 -> 0.0.1`) or `#major` (increasing major version, i.e.,\n`0.0.0 -> 1.0.0`). This tag is specified in the merge message.\n\nGenerally, it is recommended to use `#major` for changes that introduces backward-incompatible\nchanges for people that used previous versions, and `#patch` for minor changes, such as bug-fixes,\nperformance fixes or refactoring.\n\n# Links\n\n - Project (origin) repository: <https://github.com/verifit/mata>\n - Issue tracker: <https://github.com/verifit/mata/issues>\n - In case of some sensitive bugs (like security vulnerabilities),\n please contact us directly, instead of using issue tracker.\n We value your effort to improve the security and privacy of this project!\n - Project documentation: <https://verifit.github.io/mata>\n - Jupyter notebooks demonstrating `mata` usage: <https://github.com/VeriFIT/mata/tree/devel/examples/notebooks>\n - [Example 01: WS1S Logic](https://github.com/VeriFIT/mata/tree/devel/examples/notebooks/example-01-ws1s-formulae.ipynb)\n - [Example 02: ReDoS Attacks](https://github.com/VeriFIT/mata/tree/devel/examples/notebooks/example-02-redos-attacks.ipynb)\n - [Example 03: Exploring Maze](https://github.com/VeriFIT/mata/tree/devel/examples/notebooks/example-03-exploring-maze.ipynb)\n\nAlso, check out our research group focusing on program analysis, static and dynamic analysis,\nformal methods, verification and many more: \n<http://www.fit.vutbr.cz/research/groups/verifit/index.php.en>.\n\n# Licensing\n\nThe code of Mata is licensed under MIT licence. See [LICENSE](LICENSE).\n\nThe folder [`3rdparty/`](3rdparty) contains 3rd party applications licensed under their own licences, included with the code.\n\n# Contacts\n\nSee [AUTHORS.md](AUTHORS.md)\n\n# Acknowledgements\n\nWe thank for the support received from the Brno University of Technology \n([BUT FIT](https://www.fit.vutbr.cz/)).\n\nDevelopment of this tool has been supported by the following projects: ???.\n\nThis tool as well as the information provided on this web page reflects\nonly the author's view and no organization is responsible for any use\nthat may be made of the information it contains.\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "The automata library",
"version": "1.2.3",
"project_urls": {
"Homepage": "https://github.com/verifit/mata"
},
"split_keywords": [
"automata",
" finite automata",
" alternating automata"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "65e9b6accfb8440deceaa8752a694e1ae4bf86116b439b283ab29bfe729dcb3f",
"md5": "74eccd46083769918273ebc1ed77a59c",
"sha256": "d6ebd2db38b6229f99613bdc3e774e361c188fdbf75f97613bcfbe284ad7c73b"
},
"downloads": -1,
"filename": "libmata-1.2.3.tar.gz",
"has_sig": false,
"md5_digest": "74eccd46083769918273ebc1ed77a59c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 1513454,
"upload_time": "2024-03-21T11:40:48",
"upload_time_iso_8601": "2024-03-21T11:40:48.467571Z",
"url": "https://files.pythonhosted.org/packages/65/e9/b6accfb8440deceaa8752a694e1ae4bf86116b439b283ab29bfe729dcb3f/libmata-1.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-21 11:40:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "verifit",
"github_project": "mata",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "libmata"
}
JSON
