parsing of fuzzy control language (#13)

* initial draft for FCL parser

* piecewise linear mf and parsing for variables and defuzzifier

* finish first FCL implementation

* add fcl string macro

* fix workflow on 1.6

* support arbitrary propositions in premise

* add more tests and documentation

Author: lucaferranti

Project.toml

@@ -7,14 +7,18 @@ version = "0.1.0"
 Dictionaries = "85a47980-9c8c-11e8-2b9f-f7ca1fa99fb4"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 MacroTools = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
+PEG = "12d937ae-5f68-53be-93c9-3a6f997a20a8"
 RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
+Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 
 [compat]
 Aqua = "0.6"
 Dictionaries = "0.3"
 DocStringExtensions = "0.9"
 MacroTools = "0.5"
+PEG = "1.0"
 RecipesBase = "1.0"
+Reexport = "1.0"
 julia = "1.6"
 
 [extras]

docs/src/api/readwrite.md

@@ -5,4 +5,17 @@
 ```@docs
 @mamfis
 @sugfis
-```
+```
+
+## Read from file
+
+```@docs
+readfis
+```
+
+## Parse FCL
+
+```@docs
+parse_fcl
+@fcl_str
+```

docs/src/changelog.md

@@ -7,7 +7,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - ![][badge-feature] Added fuzzy c-means
 - ![][badge-enhancement] added support Lukasiewicz, drastic, nilpotent and Hamacher T-norms and corresponding S-norms.
 - ![][badge-enhancement] dont build anonymous functions during mamdani inference, but evaluate output directly. Now defuzzifiers don't take a function as input, but an array.
-
+- ![][badge-feature] added piecewise linear membership functions
+![][badge-feature] added parser for Fuzzy Control Language. 
 ## v0.1.0 -- 2023-01-10
 
 [view release on GitHub](https://github.com/lucaferranti/FuzzyLogic.jl/releases/tag/v0.1.0)

src/FuzzyLogic.jl

@@ -1,6 +1,6 @@
 module FuzzyLogic
 
-using Dictionaries
+using Dictionaries, Reexport
 
 include("docstrings.jl")
 include("membership_functions.jl")
@@ -12,14 +12,24 @@ include("parser.jl")
 include("evaluation.jl")
 include("plotting.jl")
 include("genfis.jl")
+include("readwrite.jl")
 
 export DifferenceSigmoidMF, LinearMF, GeneralizedBellMF, GaussianMF, ProductSigmoidMF,
        SigmoidMF, TrapezoidalMF, TriangularMF, SShapeMF, ZShapeMF, PiShapeMF,
+       PiecewiseLinearMF,
        ProdAnd, MinAnd, LukasiewiczAnd, DrasticAnd, NilpotentAnd, HamacherAnd,
        ProbSumOr, MaxOr, BoundedSumOr, DrasticOr, NilpotentOr, EinsteinOr,
        MinImplication, ProdImplication,
        MaxAggregator, ProbSumAggregator, CentroidDefuzzifier, BisectorDefuzzifier,
        @mamfis, MamdaniFuzzySystem, @sugfis, SugenoFuzzySystem,
        LinearSugenoOutput, ConstantSugenoOutput,
-       fuzzy_cmeans
+       fuzzy_cmeans,
+       readfis
+
+## parsers
+
+include("parsers/fcl.jl")
+
+@reexport using .FCLParser
+
 end

src/membership_functions.jl

@@ -277,3 +277,37 @@ function (p::PiShapeMF)(x::T) where {T <: Real}
     x <= (p.c + p.d) / 2 && return 1 - 2 * ((x - p.c) / (p.d - p.c))^2
     return 2 * ((x - p.d) / (p.d - p.c))^2
 end
+
+"""
+Piecewise linear membership function.
+
+### Fields
+
+$(TYPEDFIELDS)
+
+### Notes
+
+If the input is between two points, its membership degree is computed by linear interpolation.
+If the input is before the first point, it has the same membership degree of the first point.
+If the input is after the last point, it has the same membership degree of the first point.
+
+### Example
+
+```julia
+mf = PiecewiseLinearMF([(1, 0), (2, 1), (3, 0), (4, 0.5), (5, 0), (6, 1)])
+```
+"""
+struct PiecewiseLinearMF{T <: Real, S <: Real} <: AbstractMembershipFunction
+    points::Vector{Tuple{T, S}}
+end
+function (plmf::PiecewiseLinearMF)(x::Real)
+    x <= plmf.points[1][1] && return plmf.points[1][2]
+    x >= plmf.points[end][1] && return plmf.points[end][2]
+    idx = findlast(p -> x >= p[1], plmf.points)
+    x1, y1 = plmf.points[idx]
+    x2, y2 = plmf.points[idx + 1]
+    (y2 - y1) / (x2 - x1) * (x - x1) + y1
+end
+
+# TODO: more robust soultion for all mfs
+Base.:(==)(mf1::PiecewiseLinearMF, mf2::PiecewiseLinearMF) = mf1.points == mf2.points

src/parsers/fcl.jl

@@ -0,0 +1,148 @@
+
+module FCLParser
+
+using PEG, Dictionaries
+using ..FuzzyLogic
+using ..FuzzyLogic: Variable, Domain
+
+export parse_fcl, @fcl_str
+
+const FCL_JULIA = Dict("COG" => CentroidDefuzzifier(),
+                       "COGS" => "COGS", # dummy since hardcoded for sugeno
+                       "COA" => BisectorDefuzzifier(),
+                       "ANDMIN" => MinAnd(),
+                       "ANDPROD" => ProdAnd(),
+                       "ANDBDIF" => LukasiewiczAnd(),
+                       "ORMAX" => MaxOr(),
+                       "ORASUM" => ProbSumOr(),
+                       "ORBSUM" => BoundedSumOr(),
+                       "ACTPROD" => ProdImplication(),
+                       "ACTMIN" => MinImplication())
+
+function fcl_julia(s::AbstractString)
+    haskey(FCL_JULIA, s) ? FCL_JULIA[s] : throw(ArgumentError("Option $s not supported."))
+end
+
+@rule id = r"[a-zA-Z_]+[a-zA-z0-9_]*"p |> Symbol
+@rule function_block = r"FUNCTION_BLOCK"p & id & var_input_block & var_output_block &
+                       fuzzify_block[1:end] & defuzzify_block[1:end] & rule_block &
+                       r"END_FUNCTION_BLOCK"p |> x -> x[2:7]
+
+@rule var_input_block = r"VAR_INPUT"p & var_def[1:end] & r"END_VAR"p |>
+                        x -> Vector{Symbol}(x[2])
+@rule var_output_block = r"VAR_OUTPUT"p & var_def[1:end] & r"END_VAR"p |>
+                         x -> Vector{Symbol}(x[2])
+@rule var_def = id & r":"p & r"REAL"p & r";"p |> first
+
+@rule fuzzify_block = r"FUZZIFY"p & id & linguistic_term[1:end] & range_term &
+                      r"END_FUZZIFY"p |> x -> x[2] => Variable(x[4], dictionary(x[3]))
+
+@rule range_term = r"RANGE\s*:=\s*\("p & numeral & r".."p & numeral & r"\)\s*;"p |>
+                   x -> Domain(x[2], x[4])
+
+@rule linguistic_term = r"TERM"p & id & r":="p & membership_function & r";"p |>
+                        x -> x[2] => x[4]
+@rule membership_function = singleton, points
+@rule singleton = r"[+-]?\d+\.?\d*([eE][+-]?\d+)?"p |>
+                  ConstantSugenoOutput ∘ Base.Fix1(parse, Float64)
+
+@rule numeral = r"[+-]?\d+(\.\d+)?([eE][+-]?\d+)?"p |> Base.Fix1(parse, Float64)
+@rule point = r"\("p & numeral & r","p & numeral & r"\)"p |> x -> tuple(x[2], x[4])
+@rule points = point[2:end] |> PiecewiseLinearMF ∘ Vector{Tuple{Float64, Float64}}
+
+@rule defuzzify_block = r"DEFUZZIFY"p & id & linguistic_term[1:end] & defuzzify_method &
+                        range_term & r"END_DEFUZZIFY"p |>
+                        (x -> (x[2] => Variable(x[5], dictionary(x[3])), x[4]))
+
+@rule defuzzify_method = r"METHOD\s*:"p & (r"COGS"p, r"COG"p, r"COA"p, r"LM"p, r"RM"p) &
+                         r";"p |> x -> fcl_julia(x[2])
+
+@rule rule_block = r"RULEBLOCK"p & id & operator_definition & activation_method[:?] &
+                   rule[1:end] & r"END_RULEBLOCK"p |>
+                   x -> (x[3], x[4], Vector{FuzzyLogic.FuzzyRule}(x[5]))
+
+@rule or_definition = r"OR"p & r":"p & (r"MAX"p, r"ASUM"p, r"BSUM"p) & r";"p
+@rule and_definition = r"AND"p & r":"p & (r"MIN"p, r"PROD"p, r"BDIF"p) & r";"p
+@rule operator_definition = (and_definition, or_definition) |>
+                            x -> fcl_julia(join([x[1], x[3]]))
+@rule activation_method = r"ACT"p & r":"p & (r"MIN"p, r"PROD"p) & r";"p |>
+                          x -> fcl_julia(join([x[1], x[3]]))
+
+@rule rule = r"RULE\s+\d+\s*:\s*IF"p & condition & r"THEN"p & conclusion & r";"p |>
+             x -> FuzzyLogic.FuzzyRule(x[2], x[4])
+@rule relation = negrel, posrel
+@rule posrel = id & r"IS"p & id |> x -> FuzzyLogic.FuzzyRelation(x[1], x[3])
+@rule negrel = (id & r"IS\s+NOT"p & id |> x -> FuzzyLogic.FuzzyNegation(x[1], x[3])),
+               r"NOT\s*\("p & id & r"IS"p & id & r"\)"p |>
+               x -> FuzzyLogic.FuzzyNegation(x[2], x[4])
+@rule conclusion = posrel & (r","p & posrel)[*] |> x -> append!([x[1]], map(last, x[2]))
+
+@rule condition = orcondition
+@rule orcondition = andcondition & (r"OR"p & andcondition)[*] |>
+                    x -> reduce(FuzzyLogic.FuzzyOr, vcat(x[1], map(last, x[2])))
+@rule andcondition = term & (r"AND"p & term)[*] |>
+                     x -> reduce(FuzzyLogic.FuzzyAnd, vcat(x[1], map(last, x[2])))
+@rule term = relation, r"\("p & condition & r"\)"p |> x -> x[2]
+
+"""
+    parse_fcl(s::String)::AbstractFuzzySystem
+
+Parse a fuzzy inference system from a string representation in Fuzzy Control Language (FCL).
+
+### Inputs
+
+- `s::String` -- string describing a fuzzy system in FCL conformant to the IEC 1131-7 standard.
+
+### Notes
+
+The parsers can read FCL comformant to IEC 1131-7, with the following remarks:
+
+- Weighted rules are not supported.
+- Sugeno (system with singleton outputs) shall use COGS as defuzzifier.
+- the `RANGE` keyword is required for both fuzzification and defuzzification blocks.
+- Only the required `MAX` accumulator is supported.
+- Default value for defuzzification not supported.
+- Optional local variables are not supported.
+
+With the exceptions above, the parser supports all required and optional features of the standard (tables 6.1-1 and 6.1-2).
+In addition, it also supports the following features:
+
+- Piecewise linear functions can have any number of points.
+- Membership degrees in piecewise linear functions points can be any number between ``0`` and ``1``.
+"""
+function parse_fcl(s::String)::FuzzyLogic.AbstractFuzzySystem
+    name, inputs, outputs, inputsmfs, outputsmf, (op, imp, rules) = parse_whole(function_block,
+                                                                                s)
+    varsin = dictionary(inputsmfs)
+    @assert sort(collect(keys(varsin)))==sort(inputs) "Mismatch between declared and fuzzified input variables."
+
+    varsout = dictionary(first.(outputsmf))
+    @assert sort(collect(keys(varsout)))==sort(outputs) "Mismatch between declared and defuzzified output variables."
+
+    @assert all(==(outputsmf[1][2]), last.(outputsmf)) "All output variables should use the same defuzzification method."
+    defuzzifier = outputsmf[1][2]
+    and, or = ops_pairs(op)
+    if defuzzifier == "COGS" # sugeno
+        SugenoFuzzySystem(name, varsin, varsout, rules, and, or)
+    else # mamdani
+        imp = isempty(imp) ? MinImplication() : first(imp)
+        MamdaniFuzzySystem(name, varsin, varsout, rules, and, or, imp, MaxAggregator(),
+                           defuzzifier)
+    end
+end
+
+ops_pairs(::MinAnd) = MinAnd(), MaxOr()
+ops_pairs(::ProdAnd) = ProdAnd(), ProbSumOr()
+ops_pairs(::LukasiewiczAnd) = LukasiewiczAnd(), BoundedSumOr()
+ops_pairs(::MaxOr) = MinAnd(), MaxOr()
+ops_pairs(::ProbSumOr) = ProdAnd(), ProbSumOr()
+ops_pairs(::BoundedSumOr) = LukasiewiczAnd(), BoundedSumOr()
+
+"""
+String macro to parse Fuzzy Control Language (FCL). See [`parse_fcl`](@ref) for more details.
+"""
+macro fcl_str(s::AbstractString)
+    parse_fcl(s)
+end
+
+end

src/readwrite.jl

@@ -0,0 +1,29 @@
+"""
+Read a fuzzy system from a file using a specified format.
+
+### Inputs
+
+- `file::String` -- path to the file to read.
+- `fmt::Union{Symbol,Nothing}` -- input format of the file. If `nothing`, it is inferred from the file extension.
+
+Supported formats are
+
+- `:fcl` (corresponding file extension `.fcl`)
+"""
+function readfis(file::String, fmt::Union{Symbol, Nothing} = nothing)::AbstractFuzzySystem
+    if isnothing(fmt)
+        ex = split(file, ".")[end]
+        fmt = if ex == "fcl"
+            :fcl
+        else
+            throw(ArgumentError("Unrecognized extension $ex."))
+        end
+    end
+
+    s = read(file, String)
+    if fmt === :fcl
+        parse_fcl(s)
+    else
+        throw(ArgumentError("Unknown format $fmt."))
+    end
+end

src/rules.jl

@@ -62,6 +62,7 @@ Base.show(io::IO, r::FuzzyRule) = print(io, r.antecedent, " --> ", r.consequent.
 # comparisons (for testing)
 
 Base.:(==)(r1::FuzzyRelation, r2::FuzzyRelation) = r1.subj == r2.subj && r1.prop == r2.prop
+Base.:(==)(r1::FuzzyNegation, r2::FuzzyNegation) = r1.subj == r2.subj && r1.prop == r2.prop
 
 function Base.:(==)(p1::T, p2::T) where {T <: AbstractFuzzyProposition}
     p1.left == p2.left && p1.right == p2.right

test/runtests.jl

@@ -7,6 +7,7 @@ testfiles = [
     "test_evaluation.jl",
     "test_plotting.jl",
     "test_genfis.jl",
+    "test_parsers/test_fcl.jl",
     "test_aqua.jl",
     "test_doctests.jl",
 ]

test/test_parsers/data/container_crane.fcl

@@ -0,0 +1,50 @@
+FUNCTION_BLOCK container_crane
+
+VAR_INPUT
+  distance: REAL;
+  angle: REAL;
+END_VAR
+
+VAR_OUTPUT
+  power: REAL;
+END_VAR
+
+FUZZIFY distance
+  TERM too_far:= (-5, 1) ( 0, 0);
+  TERM zero := (-5, 0) ( 0, 1) ( 5,0);
+  TERM close := ( 0, 0) ( 5, 1) (10,0);
+  TERM medium := ( 5, 0) (10, 1) (22,0);
+  TERM far := (10, 0) (22,1);
+  RANGE := (-7 .. 23);
+END_FUZZIFY
+
+FUZZIFY angle
+  TERM neg_big := (-50, 1) (-5, 0);
+  TERM neg_small := (-50, 0) (-5, 1) ( 0,0);
+  TERM zero := ( -5, 0) ( 0, 1) ( 5,0);
+  TERM pos_small := ( 0, 0) ( 5, 1) (50,0);
+  TERM pos_big   := ( 5, 0) (50, 1);
+  RANGE := (-50..50);
+END_FUZZIFY
+
+DEFUZZIFY power
+  TERM neg_high := -27;
+  TERM neg_medium := -12;
+  TERM zero := 0;
+  TERM pos_medium := 12;
+  TERM pos_high := 27;
+  METHOD : COGS;
+  RANGE := (-27..27);
+END_DEFUZZIFY
+
+RULEBLOCK No1
+AND: MIN;
+RULE 1: IF distance IS far AND angle IS zero THEN power IS pos_medium;
+RULE 2: IF distance IS far AND angle IS neg_small THEN power IS pos_big;
+RULE 3: IF distance IS far AND angle IS neg_big THEN power IS pos_medium;
+RULE 4: IF distance IS medium AND angle IS neg_small THEN power IS neg_medium;
+RULE 5: IF distance IS close AND angle IS pos_small THEN power IS pos_medium;
+RULE 6: IF distance IS zero AND angle IS zero THEN power IS zero;
+END_RULEBLOCK
+
+END_FUNCTION_BLOCK