soft.fuzzy.logic.controller package

Submodules

soft.fuzzy.logic.controller.abstract module

Implements Fuzzy Logic Controllers.

class soft.fuzzy.logic.controller.abstract.FuzzyLogicController(specifications: Specifications, granulation_layers: None | GranulationLayers = None, knowledge_base: None | KnowledgeBase = None, disabled_parameters: None | List[str] = None, **kwargs)

Bases: Module

Abstract implementation of the Multiple-Input-Multiple-Output (MIMO) Fuzzy Logic Controller (FLC).

consequences() → Parameter

Return the zero-order (float value) consequences.

Returns:

The zero-order consequences.

abstract create_engine(*args, **kwargs) → BaseInference

Create the inference engine for the FLC. This is an abstract method that must be implemented by the concrete class. The inference engine is the process that takes the input granules and the rules and produces the output granules. The output granules are then defuzzified to produce the crisp output.

create_matrix(number_of_variables: int, number_of_terms: int, rules: int | list, is_input: bool)

Create the matrix representation to facilitate fuzzy inference.

disable_parameters() → None

Disable parameters in the granulation layers. This is useful for stability and convergence. It is also useful for preventing the learning of certain parameters.

forward(input_data) → Tensor

Forward pass of the function. Applies the function to the input elementwise.

Parameters:

  • input_data – The input. The shape of ‘input_data’ is

  • observations ((num. of)

  • features). (num. of)

Returns:

Defuzzified (crisp) output.

Generate the links and offsets that facilitate calculations with respect to the FLC’s specifications and in accordance with the Knowledgebase, if it exists. This procedure is typically used to produce the correct structures necessary for fuzzy logic inference (e.g., Mamdani product inference).

This is a wrapper method that serves as an entry point for two different purposes. There are two options for getting the FLC’s links and offsets that determine connections between fuzzy logic rules: (1) Use existing fuzzy rules as defined in the FLC’s KnowledgeBase; this is the traditional way in which the FLC was expected to behave. In this option, the user must specify the t-norm relation that defines the premise aggregation (e.g., AlgebraicProduct, Minimum, etc.). (2) Make random fuzzy rules; this is the newer way, proposed by J.W. Hostetter, where the Gumbel Softmax trick is, at the time of writing, employed to dynamically learn the correct premise and consequence assignments in response to the system feedback.

Returns:

links (dictionary with keys ‘input’ and ‘output’, where the values are torch.Tensor), offsets (dictionary with keys ‘input’ and ‘output’, where the values are torch.Tensor)

in_features() → int

Return the number of input features.

Returns:

The number of input features.

matrix(relation, is_input: bool)

Generate a matrix representation to facilitate fuzzy inference with respect to the provided relation type.

Parameters:

  • relation – The relation type.

  • is_input – Whether to build the matrix for the input (if True) or the output layer (if False).

Returns:

The matrix for fuzzy inference that has shape (number of input variables, number of input linguistic terms, number of rules).

matrix_helper(is_input, matrix, rule_index, term_vertices)

Helper method for matrix().

Parameters:

  • is_input

  • matrix

  • rule_index

  • term_vertices

Returns:

out_features() → int

Return the number of output features.

Returns:

The number of output features.

predict(input_data) → Tensor

Alias for ‘forward’ function. Applies the function to the input elementwise. Some libraries (e.g., alepython) require a ‘predict’ function for compatibility. Hence, this function is provided as an alias to ‘forward’. This is not to be used within ‘PySoft’.

Parameters:

  • input_data – The input. The shape of ‘input_data’ is

  • observations ((num. of)

  • features). (num. of)

Returns:

Defuzzified (crisp) output.

premises() → List[List[ContinuousFuzzySet]]

Retrieves the premises from the Fuzzy Logic Controller. Specifically, this operation takes the input granulation layer (a more computationally efficient representation) and converts the premises back to a list of granules format. For example, rather than using a single Gaussian object to represent all Gaussian membership functions in the input space, this function will convert that to a list of Gaussian objects, where each Gaussian function is defined and restricted to a single input dimension.

Returns:

A nested list of ContinuousFuzzySet objects, where the length is equal to the number of input dimensions. Within each element of the outer list, is another list that contains all the definitions for ContinuousFuzzySet within that input dimension. For example, if the 0’th index has a list equal to [Gaussian(), Trapezoid()], then this means in the 0’th dimension there are both membership functions defined using the Gaussian formula and the Trapezoid formula.

class soft.fuzzy.logic.controller.abstract.GranulationLayers

Bases: TypedDict

A dictionary that contains the input and output granulation layers. The input granulation layer is a GroupedFuzzySets object that contains the input granules. The output granulation layer is a GroupedFuzzySets object that contains the output granules. If the layer is None, then it is not defined and will be created during the construction of the FLC by searching the KnowledgeBase for the appropriate granules.

input: GroupedFuzzySets
output: GroupedFuzzySets

soft.fuzzy.logic.controller.impl module

Contains the implementation of the Zero-Order TSK and Mamdani Fuzzy Logic Controllers (FLC).

class soft.fuzzy.logic.controller.impl.Mamdani(specifications: Specifications, granulation_layers: None | GranulationLayers = None, knowledge_base: None | KnowledgeBase = None, **kwargs)

Bases: FuzzyLogicController

Implementation of the Multiple-Input-Multiple-Output (MIMO) Mamdani Fuzzy Logic Controller (FLC).

create_engine(*args, **kwargs) → BaseInference

Create the inference engine for the Mamdani FLC based on the specifications. The specifications are used to determine the type of inference engine to create, as well as whether to use network morphism or not. If network morphism is used, then it is possible for the FLC to expand or shrink its input and output terms. If network morphism is disabled, then the FLC cannot expand or shrink its input and output terms. If the KnowledgeBase is None, then the inference engine will be created with randomly initialized parameters. This is useful when the FLC should create its own rules. Otherwise, the inference engine will be created with parameters (e.g., rules) that are from the knowledge base.

Returns:

A Mamdani inference engine.

class soft.fuzzy.logic.controller.impl.ZeroOrderTSK(specifications: Specifications, granulation_layers: None | GranulationLayers = None, knowledge_base: None | KnowledgeBase = None, consequences: Tensor | None = None, **kwargs)

Bases: FuzzyLogicController

Implementation of the Multiple-Input-Multiple-Output (MIMO) Zero-Order TSK Fuzzy Logic Controller (FLC).

create_engine(*args, **kwargs)

Create the inference engine for the Zero-Order TSK FLC based on the specifications. The specifications are used to determine the type of inference engine to create, as well as whether to use network morphism or not. If network morphism is used, then it is possible for the FLC to expand or shrink its input and output terms. If network morphism is disabled, then the FLC cannot expand or shrink its input and output terms. If the KnowledgeBase is None, then the inference engine will be created with randomly initialized parameters. This is useful when the FLC should create its own rules. Otherwise, the inference engine will be created with parameters (e.g., rules) that are from the knowledge base.

Returns:

A Zero-Order TSK inference engine.

Module contents

Contains various classes necessary for Fuzy Logic Controllers (FLCs) to function properly.

class soft.fuzzy.logic.controller.Engine

Bases: TypedDict

The type of FLC to build and how to interpret the t-norm operation. This is a dictionary that contains the following fields: - type: the type of FLC to build, either ‘mamdani’ or ‘tsk’ - defuzzification: the defuzzification to use for the FLC, such as ‘minimum’, ‘product’, ‘sum’, ‘softmax-sum’, ‘softmax-mean’, etc. - confidences: whether to use the confidences of the rules, if available - ignore_missing: whether to ignore missing attributes during fuzzy inference (default is False)

confidences: bool
defuzzification: str
ignore_missing: bool
type: str
class soft.fuzzy.logic.controller.Mapping

Bases: TypedDict

The mapping of the input and output space for the FLC. This is a dictionary that contains the following fields: - input: the configuration for input space to the FLC - output: the configuration for output space to the FLC

input: SpaceConfiguration
output: SpaceConfiguration
class soft.fuzzy.logic.controller.SpaceConfiguration

Bases: TypedDict

The configuration for a given (input or output) space of the FLC. Further, this controls the maximum number of terms per variable across the space, and whether to enable adding new terms within each variable, if necessary. This is a dictionary that contains the following fields: - dim: the number of dimensions (i.e., variables) in this space - max_terms: the maximum number of terms per variable in this space - expandable: whether to enable adding new terms across all variables in the space, if necessary

dim: int
expandable: bool
max_terms: int
class soft.fuzzy.logic.controller.Specifications(t_norm: str, engine: ~soft.fuzzy.logic.controller.Engine | None = None, sparse: bool = False, mapping: None | ~soft.fuzzy.logic.controller.Mapping = None, number_of_rules: int = 100, default_fuzzy_set_type: ~typing.Type[~soft.fuzzy.sets.continuous.abstract.ContinuousFuzzySet] = <class 'soft.fuzzy.sets.continuous.impl.Gaussian'>)

Bases: object

The specifications of the Fuzzy Logic Controller (FLC) to build. This is a dataclass that contains the following fields: - t_norm: the t-norm to use for the FLC. This is a string that can be either ‘minimum’ or ‘algebraic_product’. - engine: a dictionary containing the type of FLC to build and the defuzzification to use. The type of FLC is either ‘mamdani’ or ‘tsk’. Various defuzzifications are available, such as ‘minimum’, ‘product’, ‘sum’, ‘softmax-sum’, ‘softmax-mean’, etc. Not available, but will investigate: ‘centroid’, ‘bisector’, ‘mom’, ‘som’, ‘lom’, ‘wtaver’, ‘wtsum’, ‘wtaver’, ‘wtsum’, ‘wtaver’, - sparse: whether to use sparse tensors for the FLC. This can be efficient but reduces features in the library, such as the ability to use the FLC with Captum or the class SoftExplainer. - use_gpu: whether to use the GPU. If True, then the FLC will be built on the GPU. If False, then the FLC will be built on the CPU. If the GPU is not available, then the FLC will be built on the CPU regardless of the value of this field. - device: the device to use for the FLC, either ‘cpu’ or ‘cuda:0’ (or ‘cuda:1’, etc.). This field is only used if use_gpu is True. Otherwise, the FLC will be built on the CPU. - mapping_config: how to configure the mapping between input and output space - number_of_rules: the number of rules to generate for the FLC - default_fuzzy_set_type: the default type of fuzzy set to use for the FLC; this is only used if the FLC is expandable and new terms need to be added to the FLC or if the KnowledgeBase does not contain any fuzzy sets and random fuzzy sets need to be generated

Most of these fields have default values, such as the number of rules. However, the type of FLC, the t-norm, and how to interpret the t-norm operation must be specified. The number of input and output variables, as well as the number of terms per variable, may be omitted (if a FLC is provided a KnowledgeBase, otherwise an Exception will be thrown).

default_fuzzy_set_type

alias of Gaussian

engine: Engine | None = None
mapping: None | Mapping = None
number_of_rules: int = 100
sparse: bool = False
t_norm: str