pbp_include.h
Go to the documentation of this file.
1 /** @file pbp_include.h Includes all luabindings plug-in headers */
2 
3 /*
4  ****************************************************
5  Convenience header file that includes all headers
6  relevant to the pybindings plug-in.
7 
8  (c) Thomas Moor 2023 - 2025
9  ****************************************************
10  */
11 
12 
13 #ifndef FAUDES_PBP_INCLUDE_H
14 #define FAUDES_PBP_INCLUDE_H
15 
16 
17 
18 /**
19 
20 @defgroup PybindingsPlugin Python Bindings Plug-In
21 
22 
23 @ingroup AllPlugins
24 
25 <p>
26 This plug-in generates libFAUDES bindings for the scripting language Python;
27 see http://www.python.org.
28 With this plug-in, the most essential libFAUDES data types and functions
29 can be accesed from the Python interpreter.
30 </p>
31 
32 <p>
33 Disclaimer: the primary scripting laguage for libFAUDES is Lua; see the Lua bindings plug-in.
34 Specifically, Lua bindings provide a more comprehensive interface, which is systematically
35 tested on a more regular basis. If you experience short commings of libFAUDES Python bindings,
36 please do not hesitate to report back to us.
37 </p>
38 
39 <p>
40 Restrictions:
41 
42 - Although the build system allows for multiple bindings plug-ins, we recommend to either
43  use Lua bindings or Python bindings, but not both for the same build.
44 
45 - For most plug-ins, bindings are automatically generated via SWIG based on so called
46  interface files (residing in <tt>libfaudes/plugins/`*`/registry/`*`.i</tt>);
47  regarding Python, only the plug-ins Synthesis and Observer have been tested.
48 
49 </p>
50 
51 @subsection SecPybindingsIntro1 Example Script
52 
53 <p>
54 In large, libFAUDES Python bindings follow the same conventions as the Lua bindingins.
55 Thus, you may want to inspect the documentation of the latter. For further inspiration,
56 tutorials can be found at <tt>pybindings/tutorial</tt>.
57 </p>
58 
59 <p>
60 For the following example, run Python in/from a directoty in which the
61 libFAUDES bindings reside (files <tt>_faudes.so</tt> and <tt>faudes.py</tt>).
62 </p>
63 
64 @code{.unparsed}
65 
66 # load libFAUDES bindings
67 import faudes
68 
69 # test
70 faudes.Version()
71 
72 # machine 1
73 gL1=faudes.Generator()
74 gL1.InsInitState("Idle")
75 gL1.SetMarkedState("Idle")
76 gL1.InsState("Busy")
77 gL1.InsEvent("alpha1")
78 gL1.InsEvent("beta1")
79 gL1.SetTransition("Idle","alpha1","Busy")
80 gL1.SetTransition("Busy","beta1","Idle")
81 
82 # machine 2
83 gL2=faudes.Generator()
84 gL2.InsInitState("Idle")
85 gL2.SetMarkedState("Idle")
86 gL2.InsState("Busy")
87 gL2.InsEvent("alpha2")
88 gL2.InsEvent("beta2")
89 gL2.SetTransition("Idle","alpha2","Busy")
90 gL2.SetTransition("Busy","beta2","Idle")
91 
92 # overall plant
93 gL=faudes.Generator()
94 faudes.Parallel(gL1,gL2,gL)
95 
96 # controllable events
97 sCtrl=faudes.EventSet()
98 sCtrl.Insert("alpha1")
99 sCtrl.Insert("alpha2")
100 
101 # specification aka buffer
102 gE=faudes.Generator()
103 gE.InsInitState("Empty")
104 gE.SetMarkedState("Empty")
105 gE.InsState("Full")
106 gE.InsEvent("beta1")
107 gE.InsEvent("alpha2")
108 gE.SetTransition("Empty","beta1","Full")
109 gE.SetTransition("Full","alpha2","Empty")
110 
111 # lift specification to overall eventset
112 sAll=faudes.EventSet()
113 sAll=gL.Alphabet()
114 faudes.InvProject(gE,sAll)
115 
116 # supremal closed loop
117 gK=faudes.Generator()
118 faudes.SupCon(gL,sCtrl,gE,gK)
119 
120 # show result on console
121 gK.Write()
122 
123 # save result as graphics
124 gK.GraphWrite("K.png")
125 
126 @endcode
127 
128 <p>
129 Note: for graphics output you must have installed <tt>dot</tt> from the GraphViz package.
130 If <tt>dot</tt> is not in the systems path, you may direct libfaudes via
131 <tt>faudes.DocExecPath("/wherever_dot_is/dot")</tt>.
132 </p>
133 
134 
135 
136 @subsection SecLuabindingsIntro3 Build System
137 
138 <p>
139 To use python bindings, you will need to configure and recompile libFAUDES;
140 see also <a href="../faudes_build.html">build-system documentation</a> for
141 an overview.
142 </p>
143 
144 <p>
145 Notes:
146 
147 - You should configure libFAUDES to use no minimum number of plug-ins.
148  This is done in the main Makefile. The test cases for python cover
149  the synthesis plug-in. If you have used other pluhg-ins, please submit
150  your test cases.
151 
152 
153 - The build system is best supported on Linux and OS X. For Windows, we have
154  test pybindings within the MSYS2 enviroment and it works just fine. We did not
155  yet test with MSVC compilers and/or plain cmd.exe terminal.
156 
157 
158 - The build process relies on the developer package of your Python distribution. It
159  needs to be pointed to the paths of <tt>Python.h</tt> and the
160  Python shared object <tt>libpython.so</tt>. There is an attempt to figure those
161  paths automatically, however, your milage may vary;
162  see <tt>pybindings/Makefile.plugin</tt> for manual configuration.
163 
164 
165 - After building libFAUDES as a shared object, copy the files <tt>pybindings/tutorial/faudes.py</tt>
166  and <tt>pybindings/tutorial/_faudes.so</tt> (<tt>.pyd</tt> on Windows) to reside in the same
167  directory as your Python project. Test your settings by starting a Python command promt
168  within your project directory. Try , e.g., <tt>import faudes</tt> and print
169  <tt>faudes.Version()</tt>.
170 
171 
172 - After re-compiling libFAUDES and importing to Python, make shure to clear all caches;
173  i.e., start with a clean directory after each iteration of re-compilation.
174 </p>
175 
176 
177 @subsection PyLicense License
178 
179 The Python bindings plug-in is distributed with libFAUDES.
180 All code is provided under terms of the LGPL.
181 
182 
183 Copyright (c) 2023 - 2025 Thomas Moor.
184 
185 
186 
187 */
188 
189 
190 
191 #endif

libFAUDES 2.33h --- 2025.06.18 --- c++ api documentaion by doxygen