add karnik-mendel defuzzification algorithm (#19)

* add karnik-mendel defuzzification algorithm

* more tests and remove unneeded code

* fix bug in karnik-mendel and add enhanced karnik-mendel

* fix bug in ekm and add docs and tests

* more defuzzifiers and tests

* add tutorial about type-2

* Update docs/src/literate/tutorials/type2.jl

Author: lucaferranti

README.md

@@ -24,10 +24,10 @@ using FuzzyLogic
 
 ## Features
 
-- **Rich!** Mamdani and Sugeno Type-1 inference systems, several membership functions and algoritms options available.
+- **Rich!** Mamdani and Sugeno inference systems, both Type-1 and Type-2, several [membership functions](https://lucaferranti.github.io/FuzzyLogic.jl/stable/api/memberships) and [algoritms options](https://lucaferranti.github.io/FuzzyLogic.jl/stable/api/fis) available.
+- **Compatible!** Read your models from [IEC 61131-7 Fuzzy Control Language](https://ffll.sourceforge.net/fcl.htm) and Matlab Fuzzy toolbox `.fis` files.
 - **Expressive!** Clear Domain Specific Language to write your model as human readable Julia code
 - **Productive!** Several visualization tools to help debug and tune your model.
-
 ## Quickstart example
 
 ```julia

docs/make.jl

@@ -154,6 +154,7 @@ makedocs(;
              "Tutorials" => [
                  "Build a Mamdani inference system" => "tutorials/mamdani.md",
                  "Build a Sugeno inference system" => "tutorials/sugeno.md",
+                 "Build a type-2 inference system" => "tutorials/type2.md",
              ],
              "Applications" => [
                  "Edge detection" => "applications/edge_detector.md",

docs/src/api/defuzzification.md

@@ -1,6 +1,14 @@
 # Defuzzification methods
 
+## Type-1 defuzzifiers
 ```@autodocs
 Modules = [FuzzyLogic]
-Filter = t -> typeof(t) === DataType && t <: FuzzyLogic.AbstractDefuzzifier
-```
+Filter = t -> typeof(t) === DataType && t <: FuzzyLogic.AbstractDefuzzifier && !(t <: FuzzyLogic.Type2Defuzzifier)
+```
+
+## Type-2 defuzzifiers
+
+```@autodocs
+Modules = [FuzzyLogic]
+Filter = t -> typeof(t) === DataType && t <: FuzzyLogic.Type2Defuzzifier
+```

docs/src/api/fis.md

@@ -12,4 +12,10 @@ MamdaniFuzzySystem
 SugenoFuzzySystem
 ConstantSugenoOutput
 LinearSugenoOutput
+```
+
+## General functions
+
+```@docs
+set
 ```

docs/src/changelog.md

@@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - ![](https://img.shields.io/badge/new%20feature-green.svg) support for weighted rules.
 - ![](https://img.shields.io/badge/new%20feature-green.svg) allow to specify input and output variables as vectors (e.g. `x[1:10]`) and support for loops to avoid repetitive code.
+- ![](https://img.shields.io/badge/new%20feature-green.svg) added support for type-2 membership functions and type-2 systems.
 
 ## v0.1.1 -- 2023-02-25
 

docs/src/index.md

@@ -24,7 +24,8 @@ using FuzzyLogic
 
 ## Features
 
-- **Rich!** Mamdani and Sugeno Type-1 inference systems, several membership functions and algoritms options available.
+- **Rich!** Mamdani and Sugeno inference systems, both Type-1 and Type-2, several [membership functions](https://lucaferranti.github.io/FuzzyLogic.jl/stable/api/memberships) and [algoritms options](https://lucaferranti.github.io/FuzzyLogic.jl/stable/api/fis) available.
+- **Compatible!** Read your models from [IEC 61131-7 Fuzzy Control Language](https://ffll.sourceforge.net/fcl.htm) and Matlab Fuzzy toolbox `.fis` files.
 - **Expressive!** Clear Domain Specific Language to write your model as human readable Julia code
 - **Productive!** Several visualization tools to help debug and tune your model.
 

docs/src/literate/tutorials/type2.jl

@@ -0,0 +1,75 @@
+#=
+
+# Build a type-2 inference system
+
+This tutorial explains how to build a type-2 inference system.
+The reader is assumed to be familiar with the basic syntax to build a fuzzy system, which
+is described in the [Build a Mamdani inference system](@ref) tutorial.
+
+DOWNLOAD_NOTE
+
+## Interval membership function
+
+While a normal membership function associates each element of a fuzzy set ot a membership
+degree $\mu \in [0, 1]$, an interval membership function associates each element to an
+*interval membership degeee* $\overline{\mu}\subseteq[0, 1]$.
+
+The following example shows how to contruct an interval membership function in the library
+and displays the result.
+=#
+
+using FuzzyLogic, Plots
+
+mf = 0.7 * TriangularMF(1, 2, 3) .. TriangularMF(0, 2, 4)
+
+plot(mf, -1, 5)
+
+#=
+An interval membership function can be constructed using the `..` operator. The left input
+is the lower bound and the right input is the upper bound. The expression `0.5 * TriangularMF(1, 2, 3)`
+constructs a scaled membership.
+
+## Type-2 inference systems
+
+A type-2 Mamdani system can be built with the [`@mamfis`](@ref) macro, just like type-1, with two differences
+
+- membership functions can be interval membership funcions
+- the defuzzifier should be one of the [Type-2 defuzzifiers](@ref)
+
+The following code shows an example of building a type-2 system and performing inference with it.
+
+=#
+
+fis = @mamfis function tipper(service, food)::tip
+    service := begin
+        domain = 0:10
+        poor = 0.8 * GaussianMF(0.0, 1.2) .. GaussianMF(0.0, 1.5)
+        good = 0.8 * GaussianMF(5.0, 1.2) .. GaussianMF(5.0, 1.5)
+        excellent = 0.8 * GaussianMF(10.0, 1.2) .. GaussianMF(10.0, 1.5)
+    end
+
+    food := begin
+        domain = 0:10
+        rancid = 0.9 * TrapezoidalMF(-1.8, 0.0, 1.0, 2.8) .. TrapezoidalMF(-2, 0, 1, 3)
+        delicious = 0.9 * TrapezoidalMF(8, 9, 10, 12) .. TrapezoidalMF(7, 9, 10, 12)
+    end
+
+    tip := begin
+        domain = 0:30
+        cheap = 0.8 * TriangularMF(1, 5, 9) .. TriangularMF(0, 5, 10)
+        average = 0.8 * TriangularMF(11, 15, 19) .. TriangularMF(10, 15, 20)
+        generous = 0.8 * TriangularMF(22, 25, 29) .. TriangularMF(20, 25, 30)
+    end
+
+    service == poor || food == rancid --> tip == cheap
+    service == good --> tip == average
+    service == excellent || food == delicious --> tip == generous
+
+    defuzzifier = KarnikMendelDefuzzifier()
+end
+
+plot(fis)
+
+#-
+
+fis(service = 2, food = 3)

src/FuzzyLogic.jl

@@ -22,7 +22,8 @@ export DifferenceSigmoidMF, LinearMF, GeneralizedBellMF, GaussianMF, ProductSigm
        ProbSumOr, MaxOr, BoundedSumOr, DrasticOr, NilpotentOr, EinsteinOr,
        MinImplication, ProdImplication,
        MaxAggregator, ProbSumAggregator, CentroidDefuzzifier, BisectorDefuzzifier,
-       @mamfis, MamdaniFuzzySystem, @sugfis, SugenoFuzzySystem,
+       KarnikMendelDefuzzifier, EKMDefuzzifier, IASCDefuzzifier, EIASCDefuzzifier,
+       @mamfis, MamdaniFuzzySystem, @sugfis, SugenoFuzzySystem, set,
        LinearSugenoOutput, ConstantSugenoOutput,
        fuzzy_cmeans,
        readfis

src/InferenceSystem.jl

@@ -2,6 +2,24 @@
 
 abstract type AbstractFuzzySystem end
 
+"""
+Create a copy of the given fuzzy systems, but with the new settings as specified in the
+keyword arguments.
+
+### Inputs
+
+- `fis::AbstractFuzzySystem` -- input fuzzy system
+
+### Keyword arguments
+
+- `kwargs...` -- new settings of the inference system to be tuned
+
+"""
+function set(fis::AbstractFuzzySystem; kwargs...)
+    typeof(fis).name.wrapper(NamedTuple(f => get(kwargs, f, getproperty(fis, f))
+                                        for f in fieldnames(typeof(fis)))...)
+end
+
 ###########
 # Mamdani #
 ###########
@@ -154,8 +172,6 @@ const SETTINGS = (MamdaniFuzzySystem = (:and, :or, :implication, :aggregator,
                                         :defuzzifier),
                   SugenoFuzzySystem = (:and, :or))
 
-implication(::SugenoFuzzySystem) = ProdImplication()
-
 # sugeno output functions
 
 abstract type AbstractSugenoOutputFunction <: AbstractPredicate end

src/evaluation.jl

@@ -18,15 +18,6 @@ function (fo::FuzzyOr)(fis::AbstractFuzzySystem, inputs)
     fis.or(fo.left(fis, inputs), fo.right(fis, inputs))
 end
 
-function (fr::FuzzyRule)(fis::AbstractFuzzySystem, inputs;
-                         N = 100)
-    map(fr.consequent) do c
-        l, h = low(fis.outputs[c.sub].domain), high(fis.outputs[c.sub].domain)
-        mf = broadcast(memberships(fis.outputs[c.subj])[c.prop], LinRange(l, h, N))
-        broadcast(implication(fis), fr.antecedent(fis, inputs), mf)
-    end
-end
-
 function (fis::MamdaniFuzzySystem)(inputs::T) where {T <: NamedTuple}
     Npoints = fis.defuzzifier.N + 1
     S = outputtype(typeof(fis.defuzzifier), T)
@@ -38,7 +29,7 @@ function (fis::MamdaniFuzzySystem)(inputs::T) where {T <: NamedTuple}
             var = fis.outputs[con.subj]
             l, h = low(var.domain), high(var.domain)
             mf = map(var.mfs[con.prop], LinRange(l, h, Npoints))
-            ruleres = scale(broadcast(implication(fis), w, mf), rule)
+            ruleres = scale(map(Base.Fix1(implication(fis), w), mf), rule)
             res[con.subj] = broadcast(fis.aggregator, res[con.subj], ruleres)
         end
     end