fclLib ... fuzzy control language library, version 0.1.0
========================================================
for English see below ...
Deutsch:
========
Überblick:
----------
fclLib liest FCL-Dateien (gemäß Standard IEC 1131, Teil 7 Entwurf) um ein
Fuzzy-Modell davon aufzubauen. Nach Aufruf des Modells mit den Eingabe-
parametern, werden die im Modell beschriebenen Fuzzy-Outputs berechnet und
zurückgegeben. Die Library ist in PureBasic geschrieben und wird als 32-
und 64-Bit DLL bereitgestellt (mit stdcalls). Beispiele in C und PB liegen bei.
Die Library bietet drei Funktionen
- fclLoadModel ... liest eine FCL-Datei und liefert einen Handle zurück
- fclGetResults ... versorgt das Modell mit den Eingabewerten und liefert die
Ergebnisse zurück
- fclUnloadModel ... gibt allokierten Speicher des referenzierten Modells
wieder frei
Alle Funktionen des Basic-Level und einige des Extended-Level sind
implementiert.
Folgendes vom Extended-Level ist (noch) nicht implementiert:
- lokale Variablen
- PROD und BDIF für AND
- ASUM und BSUM für OR
- BSUM und NSUM für ACCU
- COA, LM, RM für METHOD
Funktionen:
-----------
(siehe auch fclLib.h bzw. fclLib.pb)
fclLoadModel ... liest eine FCL-Datei und liefert einen Handle zurück
C Deklaration:
extern __declspec(dllimport) void * __stdcall fclLoadModel(char *name,
short *result);
PB Deklaration:
Prototype.i p_fclLoadModel (name.p-ascii, *result.WORD)
Lädt das mit 'name' angebenene Modell und liefert im Gutfall den handle auf
das Modell zurück, sonst NULL.
In 'result' wird im Fehlerfall der Fehlercode zurückgegeben (siehe unten).
fclGetResults ... versorgt das Modell mit den Eingabewerten und liefert die
Ergebnisse zurück
C Deklaration:
extern __declspec(dllimport) short __stdcall fclGetResults(void *hModel,
char *parIn,
char *parOut);
PB Deklaration:
Prototype.w p_fclGetResults (model.i, in.p-ascii, out.i)
'hModel' ist der Handle den man von fclLoadModel zurückbekommen hat.
'parIn' ist ein ASCII-Textstring mit den Eingabeparametern im JSON-
Objektformat.
z.B. '{"food":7, "service":3}' für Modell 'tipper.fcl'
'parOut' ist ein vom Benutzer bereitgestellter ASCII-Stringbuffer in den das
Ergebnis kopiert wird.
z.B. '{"tip":11.7}' für Modell 'tipper.fcl'
Als Rückgabewert wird die Anzahl der Ausgabeparameter geliefert.
fclUnloadModel ... gibt allokierten Speicher des referenzierten Modells wieder
frei
C Deklaration:
extern __declspec(dllimport) void __stdcall fclUnloadModel(void *m);
PB Deklaration:
Prototype p_fclUnloadModel (model.i)
Gibt die Resourcen des zuvor von fclLoadModel erzeugten Modell-Handle wieder
frei.
Ergebniscodes:
FCL_OK 0
FCL_ERROR_FILE_OPEN_ERROR -1
FCL_ERROR_FILE_NOT_READABLE -2
FCL_ERROR_PARSING_ERROR -3
FCL_ERROR_BAD_JSON_INPUT -4
FCL_ERROR_INSTANCE_CREATION -5
Detailliertere Diagnoseausgaben erfolgen über DebugView von Microsoft, siehe
hier: https://learn.microsoft.com/de-de/sysinternals/downloads/debugview
FCL-Sprache:
------------
Grundlage für die Implementierung war Release 19 des Entwurfs zum Dokument
'IEC 1131 - Programmable Controllers Part 7' das man auch im Internet findet.
Gemäß den Vorgaben sind Schlüsselwörter in Großbuchstaben zu schreiben.
Sonstige Bezeichner kann man schreiben wie mal will.
Folgende Fuzzy-Variablentypen sind aktuell implementiert (mit max. 4 Punkten):
- singleton (1 Punkt, nur Ausgabe)
- shoulder (2 Punkte, nur Eingabe)
- triangle (3 Punkte)
- trapezoidal, rectangle (4 Punkte)
Der Aufbau einer Datei ist:
- Variablen-Deklarationen (Eingabe und Ausgabe)
- Fuzzify-Blöcke
- Defuzzify-Blöcke
- Regelblock
Für Defuzzify-Blöcke gilt (aktuell) diese Reihenfolge der Unterblöcke:
- Liste der linguistischen Terme
- METHOD
- DEFAULT
- RANGE (optional)
Für METHOD ist aktuell nur COG und COGS implementiert.
Für Regel-Blöcke gilt (aktuell) diese Reihenfolge der Unterblöcke:
- Operator-Definitionen
- ACT (optional)
- ACCU
- Regeln
Für ACT ist MIN und PROD implementiert.
Für ACCU ist derzeit nur MAX implementiert.
Bei den Regeln gibt es für die Anzahl der Bedingungen und Schlussfolgerungen
keine Einschränkungen.
AND, OR und NOT sind implementiert, sowie die Klammernsetzung.
AND ist aktuell als MIN und OR als MAX umgesetzt.
Folgende Arten von Block-Kommentaren sind erlaubt:
(* Dies ist ein Block-Kommentar *)
/* ... dies auch */
Folgende Arten von Zeilen-Kommentaren sind erlaubt:
-- Dies ist ein Zeilen-Kommentar
// ... dies auch
Beispielprogramme für C und PureBasic:
--------------------------------------
für C - example_c\testdll_c.c
für PB - example_pb\testdll_pb.pb
Beide Programme laden die unten genannten Beispielmodelle, versehen sie mit
Beispielparametern und geben die Ergebnisse aus.
Für das Beispiel 'tipper':
- Eingabe: food = 7
- Eingabe: service = 3
- Ausgabe: tip = 11.7
Für das Beispiel 'crane':
- Eingabe: distance = 7
- Eingabe: angle = 25
- Ausgabe: power = 12
Beispiel 'tipper.fcl':
----------------------
2 Eingabegrößen 'service' von 0 bis 10 und 'food' von 0 bis 10
'service' ist definiert über die Terme 'poor' (shoulder), 'good' (Trapez)
und 'excellent' (shoulder)
'food' ist definiert über die Terme 'rancid' (shoulder)
und 'delicious' (shoulder)
1 Ausgabegröße 'tip' von 0 bis 30
'tip' ist definiert über die Terme 'cheap' (triangle),
'average' (triangle) und 'generous' (triangle)
Beispiel 'crane.fcl':
----------------------
2 Eingabegrößen 'distance' von -5 bis 22 und 'angle' von -50 bis 50
'distance' ist definiert über die Terme 'too_far' (shoulder),
'zero' (triangle), 'close' (triangle), 'medium' (triangle) und
'far' (shoulder)
'angle' ist definiert über die Terme 'neg_big' (shoulder),
'neg_small' (triangle), 'zero' (triangle), 'pos_small' (triangle) und
'pos_big' (shoulder)
1 Ausgabegröße 'power' von -27 bis 27
'power' ist definiert über die Terme 'neg_high', 'neg_medium', 'zero',
'pos_medium' und 'pos_high' (all singletons)
next steps:
-----------
- Parser flexibler gestalten
- Error-Funktion
- mehr Operatoren implementieren
- ...
Versionen:
----------
0.1.0:
erste öffentliche Version
Ideen, Wünsche, Anregungen, Kommentare, etc.:
--------------------------------------------------------
E-Mail an
loo66 {at} users {dot} sourceforge {dot} net
Bitte {at} durch einen Klammeraffen und {dot} durch einen Punkt ersetzen.
==============================================================================
English:
========
Overview:
---------
fclLib reads FCL files (according to IEC 1131, part 7 draft) to build up a
fuzzy model. After calling the model with the input parameters, the fuzzy
outputs are calculated according to the model and returned to the user.
The library is written with PureBasic and is shared as a 32- and 64 bit DLL
(with stdcalls). Examples for C and PB are included.
The library contains three functions
- fclLoadModel ... reads the FCL file and returns a handle
- fclGetResults ... delivers the input paramters to the model and returns the
results
- fclUnloadModel ... frees up the memory of the referenced model
All functions of the basic level are implemented and some of the extended
level.
These parts of the extended level are not implemented yet:
- local variables
- PROD and BDIF for AND
- ASUM and BSUM for OR
- BSUM and NSUM for ACCU
- COA, LM, RM for METHOD
functions:
----------
(see also fclLib.h and fclLib.pb)
fclLoadModel ... reads an FCL file and returns a handle to it
C declaration:
extern __declspec(dllimport) void * __stdcall fclLoadModel(char *name,
short *result);
PB declaration:
Prototype.i p_fclLoadModel (name.p-ascii, *result.WORD)
Loads the model with name 'name' and on success returns a handle to it,
otherwise NULL. The variable 'result' returns an error code (see below).
fclGetResults ... feeds the model with the input parameters and returns the
result(s)
C declaration:
extern __declspec(dllimport) short __stdcall fclGetResults(void *hModel,
char *parIn,
char *parOut);
PB declaration:
Prototype.w p_fclGetResults (model.i, in.p-ascii, out.i)
'hModel' is the handle from the fclLoadModel call
'parIn' is an ASCII string with the input parametera in JSON format.
e.g. '{"food":7, "service":3}' for model 'tipper.fcl'
'parOut' is an ASCII string buffer (supplied by the user) where the results
get copied to.
e.g. '{"tip":11.7}' for model 'tipper.fcl'
The return value is the number of output parameters.
fclUnloadModel ... release the memory allocated by fclLoadModel
C declaration:
extern __declspec(dllimport) void __stdcall fclUnloadModel(void *m);
PB declaration:
Prototype p_fclUnloadModel (model.i)
releases the resources referenced by the handle allocated from fclLoadModel
result codes:
FCL_OK 0
FCL_ERROR_FILE_OPEN_ERROR -1
FCL_ERROR_FILE_NOT_READABLE -2
FCL_ERROR_PARSING_ERROR -3
FCL_ERROR_BAD_JSON_INPUT -4
FCL_ERROR_INSTANCE_CREATION -5
More detailed diagnosis is available via DebugView from Microsoft, see here:
https://learn.microsoft.com/de-de/sysinternals/downloads/debugview
FCL description:
----------------
The implementation is based on the draft release 19 of tweh document
'IEC 1131 - Programmable Controllers Part 7' which you can find in the net.
Keywords have to be written in capital letters, all other words can be of any
mixed form.
The following fuzzy variable types are implemented now (max of 4 points):
- singleton (1 point, output only)
- shoulder (2 points, input only)
- triangle (3 points)
- trapezoidal, rectangle (4 points)
The file is organized in the following parts:
- variable declarations (inputs and outputs)
- Fuzzify blocks
- Defuzzify blocks
- rules block
For the Defuzzify blocks the following order is mandatory right now:
- list of linguistic terms
- METHOD
- DEFAULT
- RANGE (optional)
For METHOD currently only COG and COGS is implemented.
For rule blocks the following order is mandatory right now:
- Operator Definitions
- ACT (optional)
- ACCU
- Rules
For ACT only MIN and PROD is implemented right now.
For ACCU only MAX is implemented right now.
With the rules there are no restrictions with conditions and conclusions.
AND, OR and NOT are implemented, use of brackets too.
Right now, AND is implemented as MIN and OR as MAX.
The following block comments are allowed:
(* this is a block comment *)
/* ... this too */
The following line comments are allowed:
-- this is a block comment
// ... this too
example programs for C and PureBasic:
--------------------------------------
for C - example_c\testdll_c.c
for PB - example_pb\testdll_pb.pb
Both programs are loading the examples below, feed them with the input
parameters and print the results.
For example 'tipper':
- Input: food = 7
- Input: service = 3
- Output: tip = 11.7
For example 'crane':
- Input: distance = 7
- Input: angle = 25
- Output: power = 12
example 'tipper.fcl':
----------------------
2 inputs: 'service' from 0 to 10 and 'food' from 0 to 10
'service' is defined with the terms 'poor' (shoulder),
'good' (trapezoidal) and 'excellent' (shoulder)
'food' is defined withthe terms 'rancid' (shoulder) and
'delicious' (shoulder)
1 output: 'tip' from 0 to 30
'tip' is defined with the terms 'cheap' (triangle), 'average' (triangle)
and 'generous' (triangle)
example 'crane.fcl':
----------------------
2 inputs: 'distance' from -5 to 22 and 'angle' from -50 to 50
'distance' is defined with the terms 'too_far' (shoulder),
'zero' (triangle), 'close' (triangle), 'medium' (triangle) and
'far' (shoulder)
'angle' is defined with the terms 'neg_big' (shoulder),
'neg_small' (triangle), 'zero' (triangle), 'pos_small' (triangle) and
'pos_big' (shoulder)
1 output: 'power' from -27 to 27
'power' is defined with the terms 'neg_high', 'neg_medium', 'zero',
'pos_medium' and 'pos_high' (all singletons)
next steps:
-----------
- make the parser more flexible
- error function
- implement more operators
- ...
Versions:
----------
0.1.0:
first public version
Ideas, wishes, suggestions, comments, etc.:
--------------------------------------------------------
E-Mail to
loo66 {at} users {dot} sourceforge {dot} net
Please exchange {at} with an AT sign and {dot} with a dot.
===============================================================================
