efuz_python: An Evolutionary Fuzzy Logic System Library

The efuz_python library is designed to create Evolutionary Takagi-Sugeno-Kang Fuzzy Logic Systems. It provides necessary methods for creating, configuring and optimizing Fuzzy Logic Systems.

The FuzzyLogicSystem class

The FuzzyLogicSystem class provides all the tools for creating and executing k-order Takagi-Sugeno-Kang (TSK) Fuzzy Logic Systems (FLS) for classification, regression and control purposes.

The FuzzyLogicSystem class provides a fit method that implements the Scipy differential_evolution function for Differential Evolution (DE) parameter identification (optimization) for FLS. This method fits the FLS outputs from a data set using supervised learning.

Also, the FuzzyLogicSystem class provides a transform method for processing an numpy input array that is transformed into decisions; predictions, in the case of classification and regression; and decisions, in the case of controllers.

The constructor of the FuzzyLogicSystem class requires the following parameters:

class FuzzyLogicSystem(name, order, granularity=3, crispness=2.0, t_norm='Product', round_output=False,
features_cols=None, targets_cols=None, mf_to_model='GeneralizedBell', allow_optim=None, metrics=None,
search_method=None, initializer='sobol', strategy='best1bin', population_size_factor=1, amplification_factor=0.7,
cross_rate=0.7, max_iter=20, atol=0.0, tol=1e-2, workers=1, verbose=False, matlab_fis=False, cuda_en=False)

where

• name (required) is the name that will adopt the FLS.

• order (required) is the order of each TSK polynomial that defines the FLS output. We will refer to it as $k$.

• granularity (required) is the number of fuzzy sets (premise sets) per input that users can define to split each input.

  If users do not specify the search_method or if it is specified as None, then the number of rules of the FLS will increase depending on the number of inputs and the granularity values, according to the following equation:

  $$ L=\prod_{i = 0}^{p} \delta_i^p $$

  • where
    • $p$ is the number input variable count or FuzzyLogicSystem._in_var_count.
    • $\delta_i$ is the number of premise sets in the $i-$th input variable, also known as FuzzyLogicSystem._in_symbols. This value is normally defined by the granularity value.
    • $L$ is the rule count, also known as FuzzyLogicSystem._rule_count.

  If users specify the search_method to Clustering, then the number of rules will be the granularity value.

• crispness (optional) is a parameter that defines the crispness of each fuzzy set (premise set). The more crispness, the more the fuzzy system will tend to a crisp set. This value is initially assigned to each some premise parameter to control how fast the transition between belongingness and not belongingness is. After optimization, crispness values may be modified and be different from this parameter. The default value is 2.0

• t_norm (required) is the default T-Norm specified by users to make premise implications while executing fuzzy rules.

• round_output (required). This parameter rounds the FLS output up if enabled. For classification purposes, this parameter should be enabled. For regression and control purposes, this parameter should be disabled.

• features_cols (optional) is a string array that contains the names of each input variable (feature). Users can provide it or can leave it as None. In this last case, input variable names will be generated automatically using the following format: input_1, input_2, input_3, and so on. These names are used to generate strings of each rule in the FLS rule set.

• targets_cols (optional) is a string array that contains the names of each output variable (target). Users can provide it or can leave it as None. In this last case, output variable names will be generated automatically using the following format: output_1, output_2, output_3, and so on. These names are also used to generate strings of each rule in the FLS rule set.

• mf_to_model (required) is a default string that defines which Membership Function (MF) is going to be used for each premise set while performing the learning process. By default, this value is GeneralizedBell.

• allow_optim (optional) is an array of six Booleans that allows performing optimization only to a specific set of parameters of the FLS. There are six sets of parameters: [a, b, c, d, q, r]. If users need to optimize the c, and the q parameter sets, then the allow_optim array that must be passed is [False, False, True, False, True, False]. Each parameter set affects in a different way depending on the selected MF defined manually for premise sets or depending on the selected mf_to_model value. By default, allow_optim = [True, True, True, True, True, True], i.e. all the parameter sets must be optimized. Parameter sets are defined as follows:

Figure 1. Parameter sets for Membership Functions

• Parameter sets a, b, c, and d have a FuzzyLogicSystem._in_var_count * FuzzyLogicSystem._granularity length each.

• q: This parameter set defines the TSK polynomial coefficients. By default, the values that contain are near the output limits (target). Its length is equal to $L*(p*k + 1)$, i.e. FuzzyLogicSystem._rule_count * (FuzzyLogicSystem._in_var_count * order + 1)

• r: This parameter set defines the rule weights. By default, the values that contain are in interval $[0, 1]$, where 1 means that the rule strongly influences the FLS decisions. Its length is equal to $L$ or FuzzyLogicSystem._rule_count

• metrics (optional) is an array of tuples, where the first element in the tuple is the name string of the metric that is going to be used as fitness function; the second element in the tuple is a floating point number that specifies the weight of such metric. By default, the metrics array is equal to [("accuracy", 1.0)]. More than one metric can be selected by passing a metrics array of several tuples; e.g. metrics = [("accuracy", 0.7), ("sensitivity", 0.3)]. Please note that the sum of weights of all the selected metrics must be equal to 1.

• search_method (required). At the moment of this release, there is only one way of searching for initial FLS parameter: Clustering (only clustering techniques that need the number of clusters to operate). In order to configure it, you will need to use the : operator. By default, this parameter is established to Clustering:KMeans, but you can select from the following clustering techniques:

  • Clustering:AgglomerativeClustering
  • Clustering:GaussianMixture
  • Clustering:FuzzyCMeans
  • Clustering:SpectralClustering
  • Clustering:SpectralBiclustering
  • Clustering:SpectralCoclustering

• initializer (required). This parameter is proper of SciPy's differential_evolution function. It specifies the type of initialization of population. Alike differential_evolution function, there are only the following options to select:

  • latinhypercube (default)
  • sobol
  • halton
  • random
  • An array specifying the initial population. See the SciPy's differential_evolution function documentation for more information.

• strategy (required). This parameter is proper of SciPy's differential_evolution function. This is the DE strategy to use. The following are the possible choices:

  • best1bin (default)
  • best1exp
  • rand1bin
  • rand1exp
  • rand2bin
  • rand2exp
  • randtobest1bin
  • randtobest1exp
  • currenttobest1bin
  • currenttobest1exp
  • best2exp
  • best2bin

• population_size_factor (required). This is factor that multiplies the number of optimizable-FLS parameters to obtain the total population size.

• amplification_factor (required). Is also known as the differential weight or (F) in the literature. By default, this value is 0.7. It should be in interval $[0, 2)$. For more information see the SciPy's differential_evolution function documentation.

• cross_rate (required). This is known as the Crossover Rate (CR) in the literature. By default, this value is 0.7. This constant should be in the interval $[0, 1]$. See the SciPy's differential_evolution function documentation.

• max_iter (required). According to the SciPy's differential_evolution function documentation, this is the maximum number of generations over which the entire population is evolved. By default, this value is set to 20.

• atol and tol (required). These are the absolute and relative tolerances, respectively. For more information see the SciPy's differential_evolution function documentation.

• workers (required). According to the SciPy's differential_evolution documentation, if workers is an integer, the population is subdivided into chunks of individuals, where each worker can pick up and evaluate individuals in parallel. By default, this value is 1 (sequential processing). Supply -1 to use all available CPU cores.

• verbose (optional). This parameter enables or disables the console printing of the FLS optimization.

• matlab_fis (optional). If this parameter is enabled, a MATLAB's fis file is exported with the optimized model configuration.

• cuda_en (not implemented yet)

The add methods

add_in_var()

This method creates an input variable or feature. Users must specify the lower and upper bounds in a tuple of floats

def add_in_var(new_name: str,
               bounds: (float, float))

It requires two arguments:

• new_name: str
• bounds: (lower_bound: float, upper_bound: float)

add_out_var()

This method creates an output variable or target.

def add_out_var(new_name: str)

It requires one argument:

• new_name: str

add_set()

This method creates a premise fuzzy set in a specific input variable or feature

def add_set(var_name: str,
            set_name: str,
            shape: str,
            params: list)

It requires four arguments:

• var_name: str
• set_name: str, usually known as the linguistic label of the fuzzy set. This label is going to be used when building fuzzy rules.
• shape: str is the shape of the MF, as shown in Fig. 1
• params: list is a list of its corresponding parameters. The len() of this list will depend on the selected MF shape. These are optimizable parameters.

add_poly()

This method creates a consequence polynomial in a specific output variable or target

def add_poly(var_name: str,
             poly_name: str,
             params: list)

It requires three arguments:

• var_name: str
• poly_name: str. This name is going to be used when building fuzzy rules.
• params: list is a list of its corresponding parameters. The len() of this list will depend on the order $k$ of the TSK FLS, i.e. $p * k + 1$. These are optimizable parameters.

add_rule()

This method adds a fuzzy rule to the FLS rule set

def add_rule(rule_str: str,
             weight: float = 1.0)

It requires two arguments:

• rule_str: str. This rule string provides the FLS configuration to perform inferences from inputs to outputs. The rule must have the form IF-THEN.
• weight: float is a floating number that established the weight of the added rule. This is also an optimizable parameter.

add_all_rules()

This method automatically adds all possible fuzzy rules to the FLS rule set, according to the previously added input/output variables, sets, and polynomials.

def add_all_rules()

It does not require arguments, but users must take care of using this method in order to prevent to run out of memory. For instance, if the search_method used is None, then the number of rules may increase exponentially. For more information see the FuzzyLogicSystem.granularity property.