Python Module faudes

libFAUDES can be build as a Python C extension; i.e., a module to be imported from within the Python scripting language and that provides access to relevant libFAUDES data types and functions as listed in the libFAUDES user reference. Technically, the libFAUDES Python module is implemented by the libFAUDES Plug-In PyBindings.

On this page, we provide information on how to install and validate the Python module faudes. Further instructions are organised as follows:

For zero-install/first-inspection we share a simple demo as a Google Colab Notebook. More detailed demonstration of the intended usage is provided by the tutorials distributed with the libFAUDES sources.

Installation

If you are using an official Python distribution (i.e., either dowloaded/installed from www.pytgon.org or, for Linux, via the default package manager), you can most likely install the faudes module via pip. On Linux and macOS, this is done via the command line by 

$ pip install faudes

or, for Windows, 

> py -m pip install faudes

Pip will search the index PyPI.org for a binary distribution of libFAUDES that fits your platform/archirecture; see also here. In the case that no such matching binary is found, please let us know. Instructions on how to compile your own binary are provided here.

Note. Your Python environment may be externaly managed e.g. on Linux by the distribution package manager. Consequently installation of any modules via pip will be blocked. In such a case you will need to set up a virtual environment and then use pip and/or python3 within that environment; detailed instructions.

First Test

As a basic test, the below Python commands will report the libFAUDES version and available plug-ins: 

>>> import faudes
>>> faudes.Version()
'libFAUDES 2.34d synthesis-observer-diagnosis-pybindings'

or, for "lazy" import to the current namespace 

>>> from faudes import *
>>> Version()
'libFAUDES 2.34d synthesis-observer-diagnosis-pybindings'

For the sake of concise examples, we use lazy import throughout this documententation. E.g. faudes.Help() is convenientliy accessed by plain 

>>> Help()

and reports along the lines of: 

Interface [extract]:
  faudes.Help("EventSet")            EventSet methods
  faudes.Help("Generator")           Generator methods
  faudes.Help("System")              System methods
  faudes.Help("Synthesis")           Synthesis PlugIn

Configuration [extract]:
  faudes.DotPath("filename")         path of dot executable
  faudes.Version()                   report libFAUDES version string

Console Commands [extract]:
  faudes.Print("message")            print as faudes debugging message
  faudes.Error("message")            abort script with error message
  faudes.Verbosity(int)              set verbosity level

You may specify a keyword by calling faudes.Help("keyword") to obtain a list of relevant functions. Plug-ins that provide additional bindings will advertise themselves with their plug-in name as keyword; e.g., try 

>>> Help("Synthesis")

for functions related to classical supervisory control theory.

Validation

libFAUDES sources include tutorials that demonstrate the intended ussage. They also serve as test cases to validate a libFAUDES installation. For the Python module, the tutorials are included in the Python project sources used to compile the pip-installable binary distributions aka wheels. You can download those sources manually from PyPI or by pip, e.g.: 

$ pip download --no-deps --no-binary :all: faudes
Then, extract the *.tar.gz file, e.g. 
$ tar -xzf faudes-2.xx.yy.tar.gz
The archive is organised as follows. 
faudes-2.xx.yy -+- src/*              actual C++ sources
                +- tests/*.py         tutorials/tests
		+- tests/data/*       input data for the tests and test protocols
                +- tests/test_all.py  wrapper to run all tests
                +- *                  support files for the build process

To run an individual tutorial/test you must cd to the tests folder so that the script can locate its input data. E.g. 

$ cd faudes-2.xx.yy/tests  
$ python3 1_containers.py
The results will be compared to an archived protocol file and an error will be shown to indicate any differences; in such case, please report back to us. To run all tests, you may use pytest: 
$ pip install pytest         # install if not already installed
$ pytest faudes-2.xx.yy      # do run tests

Graphical Output

For image output of generator graphs libFAUDES relies on the the tool dot from the Graphviz package. For most Linux distributions, dot can be installed by the package manager or is included anyway. For Mac OsX and MS Windows, installers are available from the Graphviz site.

Example: reading a generator from a faudes formated file, writing a graphical representation in .png format, and/or showing the image on screen:: 

>>> gen=Generator("data/simplemachine.gen")       # read generator
>>> gen.GraphWrite("tmp_simplemachine.png");      # write image 
>>> gen.GraphShow();                              # or show image

For the above code snipped to work, libFAUDES needs to locate the executable dot. If libFAUDES fails in this regard, you may specify the location programatically. 

>>> DotPath("/usr/bin/dot")                                   # eg Linux  
>>> DotPath("c:\\Program Files\\Graphviz\\dot")               # eg Windows
>>> DotPath("/Applications/Graphviz.app/Contents/MacOS/dot"); # eg MacOS

libFAUDES 2.34g --- 2026.03.30 --- with "omegaaut-synthesis-observer-observability-diagnosis-hiosys-iosystem-multitasking-coordinationcontrol-timed-simulator-iodevice-priorities-luabindings-hybrid-example-pybindings"