pbp_include.h

Go to the documentation of this file.

/** @file pbp_include.h Includes all luabindings plug-in headers */
 
/*
 **************************************************** 
 Convenience header file that includes all headers
 relevant to the pybindings plug-in. 
 
 (c) Thomas Moor 2023 - 2026
 ****************************************************
 */
 
 
#ifndef FAUDES_PBP_INCLUDE_H
#define FAUDES_PBP_INCLUDE_H
 
// include all headers for this plugin
#include "pbp_addons.h"
 
 
/**
 
@defgroup PybindingsPlugin Python Bindings Plug-In
 
 
@ingroup AllPlugins
 
<p>
This plug-in implements libFAUDES bindings for the scripting language Python; 
see https://www.python.org. Relevant libFAUDES data types and functions
can be accessed from the Python interpreter. The most convenient method
to make the faudes module available is to install it via <tt>pip</tt>; i.e., for
Linux, macOS and Windows/MSYS
</p>
 
@code{.unparsed}
$ pip install faudes
$ python3 -c "import faudes; print(faudes.Version())"
@endcode
 
or, for native Windows
 
@code{.unparsed}
> py -m pip  install faudes
> py -c "import faudes; print(faudes.Version())"
@endcode
 
<p>
This will search the index pypi.org for a binary distribution that fits your
platform/archirectur. In the case that no such matching binary is present,
please let us know. Instructions on how to compile
your own binary are below.
</p>
 
 
 
 
@subsection SecPybindingsIntro1 Example Script
 
<p>
In large, libFAUDES Python bindings follow the same conventions as the Lua bindingins.
Thus, you may want to inspect the documentation of the latter;
see https://fgdes.tf.fau.de/faudes/luafaudes/index.html.
libFAUDES specific Python tutorial ship with the sourcse distribution;
see <tt>./libFAUDES/pybindings/tutorial</tt>.
</p>
 
<p>
Example Python script:
</p>
 
@code{.unparsed}
 
# load libFAUDES bindings
import faudes
 
# test
faudes.Version()
 
# machine 1
gL1=faudes.Generator()
gL1.InsInitState("Idle")
gL1.SetMarkedState("Idle")
gL1.InsState("Busy")
gL1.InsEvent("alpha1")
gL1.InsEvent("beta1")
gL1.SetTransition("Idle","alpha1","Busy")
gL1.SetTransition("Busy","beta1","Idle")
 
# machine 2
gL2=faudes.Generator()
gL2.InsInitState("Idle")
gL2.SetMarkedState("Idle")
gL2.InsState("Busy")
gL2.InsEvent("alpha2")
gL2.InsEvent("beta2")
gL2.SetTransition("Idle","alpha2","Busy")
gL2.SetTransition("Busy","beta2","Idle")
 
# overall plant
gL=faudes.Generator()
faudes.Parallel(gL1,gL2,gL)
 
# controllable events
sCtrl=faudes.EventSet()
sCtrl.Insert("alpha1")
sCtrl.Insert("alpha2")
 
# specification aka buffer
gE=faudes.Generator()
gE.InsInitState("Empty")
gE.SetMarkedState("Empty")
gE.InsState("Full")
gE.InsEvent("beta1")
gE.InsEvent("alpha2")
gE.SetTransition("Empty","beta1","Full")
gE.SetTransition("Full","alpha2","Empty")
 
# lift specification to overall eventset
sAll=faudes.EventSet()
sAll=gL.Alphabet()
faudes.InvProject(gE,sAll)
 
# supremal closed loop
gK=faudes.Generator()
faudes.SupCon(gL,sCtrl,gE,gK)
 
# show result on console
gK.Write()
 
# save result as graphics
gK.GraphWrite("K.png")
 
@endcode
 
<p>
Note: for graphics output you must have installed <tt>dot</tt> from the GraphViz package.
If <tt>dot</tt> is not in the systems path, you may direct libfaudes via
<tt>faudes.DocExecPath("/wherever_dot_is/dot")</tt>.
</p>
 
 
 
@subsection SecPybindingsIntro3 Building the libFAUDES Python module
 
<p>
The faudes Python module consists of the glue code <tt>faudes.py</tt> and a suitably
extended libFAUDES shrared object <tt>_faudes.so</tt> (or <tt>_faudes.pyd</tt> for Windows).
Both files are generated by the libFAUDES build system; see
<a href="../faudes_build.html">build-system documentation</a> for details.
Manualy copying/renaming both files to a project folder enables the import of the
faudes module from Python scripts in that folder.
</p>
 
<p>
Example for the overall build process incl. copy/rename:
<p>
 
@code{.unparsed}
./libFAUDES$ make dist-clean
./libFAUDES$ make -j configure
./libFAUDES$ make -j 
./libFAUDES$ cp plugings/pybindings/obj/faudes.py whereever/
./libFAUDES$ cp plugings/pybindings/obj/_faudes.so whereever/
./libFAUDES$ cd whereever
./whereever$ python3 -c "import faudes; print(faudes.Version())"
@endcode
 
<p>
The libFAUDES build system also has a dedicated target <tt>pybindings-wheel</tt>
that utilises the Python module <tt>build</tt> to generate a Python package <tt>faudes-*.whl</tt>
for binary distribution. The latter can be installed via <tt>pip</tt>.
The benefit of this approach is that Python <tt>build</tt> takes care of matching
toolchains etc. and that after installing the wheel the module files do not need
to be copied to each relevant project folder.
The downside is that Python <tt>build</tt> wont use parallel jobs and therefore can take quite
some time. 
</p>
 
<p>
Example for the overall build process incl. installation:
<p>
 
@code{.unparsed}
./libFAUDES$ make dist-clean
./libFAUDES$ make -j configure
./libFAUDES$ make pybindings-wheel
./libFAUDES$ pip install faudes-2.34.0-cp314-cp314-macosx_10_15_universal2.whl
@endcode
 
<p>
Alternatively, you may download the configured source from PyPI and invoke <tt>build</tt>
directly; e.g. for Windows with official Python distribution and MSVC installed, but no MSYS
avialable:
</p>
@code{.unparsed}
./faudes-2.34> py -m build --wheel --outdir=./
@endcode
</p>
 
 
@subsection PyLicense License
 
The Python bindings plug-in is distributed with libFAUDES. 
All code is  provided under terms of the LGPL. 
 
 
Copyright (c) 2023 - 2026 Thomas Moor.
 
 
 
*/
 
 
 
#endif