fuzzy_control/

lib.rs

//! A type-safe fuzzy control library for Rust.
//!
//! This library provides a complete implementation of fuzzy logic control systems,
//! with strong type safety guarantees and generic support for different numeric types.
//!
//! # Overview
//!
//! A fuzzy control system operates in three main stages:
//! 1. **Fuzzification**: Convert crisp input values into fuzzy membership degrees
//! 2. **Inference**: Apply fuzzy rules to determine fuzzy outputs
//! 3. **Defuzzification**: Convert fuzzy outputs back into crisp control values

use num_traits::{Float as NumFloat, Zero, One};
use std::collections::HashMap;
use std::fmt;

pub mod membership_functions;
pub mod operators;
pub mod defuzzification;
pub mod visualization;

/// Trait alias for numeric types that can be used in fuzzy computations.
pub trait Float: NumFloat + Zero + One + PartialOrd + Copy + fmt::Debug {}
impl<T: NumFloat + Zero + One + PartialOrd + Copy + fmt::Debug> Float for T {}

/// Represents a fuzzy membership degree constrained to the range [0, 1].
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
pub struct MembershipDegree<M: Float>(M);

impl<M: Float> MembershipDegree<M> {
    /// Creates a new membership degree, returning an error if the value is outside [0, 1].
    pub fn new(value: M) -> Result<Self, MembershipError> {
        if value >= M::zero() && value <= M::one() {
            Ok(MembershipDegree(value))
        } else {
            Err(MembershipError::OutOfRange {
                value: format!("{:?}", value),
            })
        }
    }
    
    /// Creates a new membership degree, clamping the value to [0, 1] if necessary.
    pub fn new_clamped(value: M) -> Self {
        let clamped = if value < M::zero() {
            M::zero()
        } else if value > M::one() {
            M::one()
        } else {
            value
        };
        MembershipDegree(clamped)
    }
    
    /// Returns the underlying numeric value of this membership degree.
    pub fn get(&self) -> M {
        self.0
    }
    
    /// Creates a membership degree representing complete non-membership (0).
    pub fn zero() -> Self {
        MembershipDegree(M::zero())
    }
    
    /// Creates a membership degree representing complete membership (1).
    pub fn one() -> Self {
        MembershipDegree(M::one())
    }
}

/// Errors that can occur during fuzzy logic operations.
#[derive(Debug, Clone)]
pub enum MembershipError {
    OutOfRange { value: String },
    InvalidConfiguration { message: String },
}

impl fmt::Display for MembershipError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            MembershipError::OutOfRange { value } => {
                write!(f, "Membership degree out of range [0, 1]: {}", value)
            }
            MembershipError::InvalidConfiguration { message } => {
                write!(f, "Invalid configuration: {}", message)
            }
        }
    }
}

impl std::error::Error for MembershipError {}

/// A membership function maps domain values to fuzzy membership degrees.
pub trait MembershipFunction<D, M>
where
    D: Float,
    M: Float,
{
    /// Evaluates the membership function at a given domain value.
    fn evaluate(&self, value: D) -> MembershipDegree<M>;
}

/// A fuzzy set associates a linguistic term with a membership function.
pub struct FuzzySet<D: Float, M: Float> {
    name: String,
    membership_fn: Box<dyn MembershipFunction<D, M>>,
}

impl<D: Float, M: Float> FuzzySet<D, M> {
    /// Creates a new fuzzy set with a given name and membership function.
    pub fn new(name: impl Into<String>, membership_fn: Box<dyn MembershipFunction<D, M>>) -> Self {
        FuzzySet {
            name: name.into(),
            membership_fn,
        }
    }
    
    /// Returns the name of this fuzzy set.
    pub fn name(&self) -> &str {
        &self.name
    }
    
    /// Evaluates the membership degree for a given domain value.
    pub fn evaluate(&self, value: D) -> MembershipDegree<M> {
        self.membership_fn.evaluate(value)
    }
}

/// A linguistic variable represents a domain concept with associated fuzzy sets.
pub struct LinguisticVariable<D: Float, M: Float> {
    name: String,
    range: (D, D),
    pub(crate) sets: Vec<FuzzySet<D, M>>,
}

impl<D: Float, M: Float> LinguisticVariable<D, M> {
    /// Creates a new linguistic variable with a name and domain range.
    pub fn new(name: impl Into<String>, range: (D, D)) -> Self {
        LinguisticVariable {
            name: name.into(),
            range,
            sets: Vec::new(),
        }
    }
    
    /// Adds a fuzzy set to this linguistic variable.
    pub fn add_set(&mut self, set: FuzzySet<D, M>) {
        self.sets.push(set);
    }
    
    /// Returns the name of this linguistic variable.
    pub fn name(&self) -> &str {
        &self.name
    }
    
    /// Returns the domain range of this linguistic variable.
    pub fn range(&self) -> (D, D) {
        self.range
    }
    
    /// Fuzzifies a crisp domain value into membership degrees for all fuzzy sets.
    pub fn fuzzify(&self, value: D) -> HashMap<String, MembershipDegree<M>> {
        self.sets
            .iter()
            .map(|set| (set.name().to_string(), set.evaluate(value)))
            .collect()
    }
}

/// T-norm operators implement fuzzy AND operations.
pub trait TNorm<M: Float> {
    /// Applies the T-norm to combine two membership degrees.
    fn apply(&self, a: MembershipDegree<M>, b: MembershipDegree<M>) -> MembershipDegree<M>;
}

/// S-norm operators implement fuzzy OR operations.
pub trait SNorm<M: Float> {
    /// Applies the S-norm to combine two membership degrees.
    fn apply(&self, a: MembershipDegree<M>, b: MembershipDegree<M>) -> MembershipDegree<M>;
}

/// Represents a condition in a fuzzy rule antecedent.
pub struct Condition<D: Float, M: Float> {
    pub(crate) variable_name: String,
    pub(crate) set_name: String,
    _phantom_d: std::marker::PhantomData<D>,
    _phantom_m: std::marker::PhantomData<M>,
}

impl<D: Float, M: Float> Condition<D, M> {
    /// Creates a new condition.
    pub fn new(variable_name: impl Into<String>, set_name: impl Into<String>) -> Self {
        Condition {
            variable_name: variable_name.into(),
            set_name: set_name.into(),
            _phantom_d: std::marker::PhantomData,
            _phantom_m: std::marker::PhantomData,
        }
    }
}

/// Represents a consequent in a fuzzy rule.
pub struct Consequent<D: Float, M: Float> {
    pub(crate) variable_name: String,
    pub(crate) set_name: String,
    _phantom_d: std::marker::PhantomData<D>,
    _phantom_m: std::marker::PhantomData<M>,
}

impl<D: Float, M: Float> Consequent<D, M> {
    /// Creates a new consequent.
    pub fn new(variable_name: impl Into<String>, set_name: impl Into<String>) -> Self {
        Consequent {
            variable_name: variable_name.into(),
            set_name: set_name.into(),
            _phantom_d: std::marker::PhantomData,
            _phantom_m: std::marker::PhantomData,
        }
    }
}

/// A fuzzy rule expressing IF-THEN logic.
pub struct FuzzyRule<D: Float, M: Float> {
    pub(crate) antecedents: Vec<Condition<D, M>>,
    pub(crate) operator: RuleOperator,
    pub(crate) consequents: Vec<Consequent<D, M>>,
    pub(crate) weight: MembershipDegree<M>,
}

/// Operators for combining rule antecedents.
#[derive(Debug, Clone, Copy)]
pub enum RuleOperator {
    And,
    Or,
}

impl<D: Float, M: Float> FuzzyRule<D, M> {
    /// Creates a new fuzzy rule with default weight of 1.0.
    pub fn new(
        antecedents: Vec<Condition<D, M>>,
        operator: RuleOperator,
        consequents: Vec<Consequent<D, M>>,
    ) -> Self {
        FuzzyRule {
            antecedents,
            operator,
            consequents,
            weight: MembershipDegree::one(),
        }
    }
    
    /// Sets the weight (importance) of this rule.
    pub fn with_weight(mut self, weight: MembershipDegree<M>) -> Self {
        self.weight = weight;
        self
    }
}

/// The main fuzzy control system.
pub struct FuzzyController<D: Float = f64, M: Float = f64> {
    pub(crate) inputs: HashMap<String, LinguisticVariable<D, M>>,
    pub(crate) outputs: HashMap<String, LinguisticVariable<D, M>>,
    pub(crate) rules: Vec<FuzzyRule<D, M>>,
    pub(crate) t_norm: Box<dyn TNorm<M>>,
    pub(crate) s_norm: Box<dyn SNorm<M>>,
}

impl<D: Float, M: Float> FuzzyController<D, M> {
    /// Creates a new builder for constructing a fuzzy controller.
    pub fn builder() -> FuzzyControllerBuilder<D, M> {
        FuzzyControllerBuilder::new()
    }
    
    /// Evaluates the fuzzy controller with given crisp inputs using Mamdani inference.
    pub fn evaluate(
        &self,
        inputs: &HashMap<String, D>,
        defuzzifier: &dyn defuzzification::Defuzzifier<D, M>,
    ) -> Result<HashMap<String, D>, MembershipError> {
        // Stage 1: Fuzzification
        let mut fuzzified_inputs: HashMap<String, HashMap<String, MembershipDegree<M>>> = 
            HashMap::new();
        
        for (var_name, var) in &self.inputs {
            let crisp_value = inputs.get(var_name).ok_or_else(|| {
                MembershipError::InvalidConfiguration {
                    message: format!("Missing input variable: {}", var_name),
                }
            })?;
            
            fuzzified_inputs.insert(var_name.clone(), var.fuzzify(*crisp_value));
        }
        
        // Stage 2: Rule Evaluation and Aggregation
        let mut output_activations: HashMap<String, HashMap<String, MembershipDegree<M>>> = 
            HashMap::new();
        
        for (out_name, out_var) in &self.outputs {
            let mut set_activations = HashMap::new();
            for set in &out_var.sets {
                set_activations.insert(set.name().to_string(), MembershipDegree::zero());
            }
            output_activations.insert(out_name.clone(), set_activations);
        }
        
        for rule in &self.rules {
            let firing_strength = self.evaluate_rule_antecedents(rule, &fuzzified_inputs)?;
            let weighted_strength = MembershipDegree::new_clamped(
                firing_strength.get() * rule.weight.get()
            );
            
            for consequent in &rule.consequents {
                let activations = output_activations
                    .get_mut(&consequent.variable_name)
                    .ok_or_else(|| {
                        MembershipError::InvalidConfiguration {
                            message: format!(
                                "Unknown output variable in rule: {}",
                                consequent.variable_name
                            ),
                        }
                    })?;
                
                let current_activation = activations
                    .get(&consequent.set_name)
                    .copied()
                    .unwrap_or(MembershipDegree::zero());
                
                let new_activation = MembershipDegree::new_clamped(
                    current_activation.get().max(weighted_strength.get())
                );
                
                activations.insert(consequent.set_name.clone(), new_activation);
            }
        }
        
        // Stage 3: Defuzzification
        let mut crisp_outputs = HashMap::new();
        
        for (out_name, out_var) in &self.outputs {
            let activations = &output_activations[out_name];
            let crisp_value = defuzzifier.defuzzify(out_var, activations)?;
            crisp_outputs.insert(out_name.clone(), crisp_value);
        }
        
        Ok(crisp_outputs)
    }
    
    /// Evaluates the antecedents of a rule to determine its firing strength.
    pub(crate) fn evaluate_rule_antecedents(
        &self,
        rule: &FuzzyRule<D, M>,
        fuzzified_inputs: &HashMap<String, HashMap<String, MembershipDegree<M>>>,
    ) -> Result<MembershipDegree<M>, MembershipError> {
        if rule.antecedents.is_empty() {
            return Ok(MembershipDegree::one());
        }
        
        let mut condition_degrees = Vec::new();
        
        for condition in &rule.antecedents {
            let variable_memberships = fuzzified_inputs
                .get(&condition.variable_name)
                .ok_or_else(|| {
                    MembershipError::InvalidConfiguration {
                        message: format!(
                            "Unknown variable in rule condition: {}",
                            condition.variable_name
                        ),
                    }
                })?;
            
            let degree = variable_memberships
                .get(&condition.set_name)
                .copied()
                .ok_or_else(|| {
                    MembershipError::InvalidConfiguration {
                        message: format!(
                            "Unknown fuzzy set in rule condition: {}.{}",
                            condition.variable_name, condition.set_name
                        ),
                    }
                })?;
            
            condition_degrees.push(degree);
        }
        
        let result = match rule.operator {
            RuleOperator::And => {
                condition_degrees
                    .into_iter()
                    .reduce(|acc, degree| self.t_norm.apply(acc, degree))
                    .unwrap()
            }
            RuleOperator::Or => {
                condition_degrees
                    .into_iter()
                    .reduce(|acc, degree| self.s_norm.apply(acc, degree))
                    .unwrap()
            }
        };
        
        Ok(result)
    }
    
    /// Convenience method to evaluate with default centroid defuzzification.
    pub fn evaluate_centroid(
        &self,
        inputs: &HashMap<String, D>,
    ) -> Result<HashMap<String, D>, MembershipError> {
        let defuzzifier = defuzzification::Centroid::new(200)?;
        self.evaluate(inputs, &defuzzifier)
    }
}

/// Builder for fuzzy controller
pub struct FuzzyControllerBuilder<D: Float, M: Float> {
    inputs: HashMap<String, LinguisticVariable<D, M>>,
    outputs: HashMap<String, LinguisticVariable<D, M>>,
    rules: Vec<FuzzyRule<D, M>>,
    t_norm: Option<Box<dyn TNorm<M>>>,
    s_norm: Option<Box<dyn SNorm<M>>>,
}

impl<D: Float, M: Float> FuzzyControllerBuilder<D, M> {
    /// Creates a new fuzzy controller builder.
    pub fn new() -> Self {
        FuzzyControllerBuilder {
            inputs: HashMap::new(),
            outputs: HashMap::new(),
            rules: Vec::new(),
            t_norm: None,
            s_norm: None,
        }
    }
    
    /// Adds an input linguistic variable to the controller.
    pub fn add_input(mut self, variable: LinguisticVariable<D, M>) -> Self {
        self.inputs.insert(variable.name().to_string(), variable);
        self
    }
    
    /// Adds an output linguistic variable to the controller.
    pub fn add_output(mut self, variable: LinguisticVariable<D, M>) -> Self {
        self.outputs.insert(variable.name().to_string(), variable);
        self
    }
    
    /// Adds a fuzzy rule to the controller.
    pub fn add_rule(mut self, rule: FuzzyRule<D, M>) -> Self {
        self.rules.push(rule);
        self
    }
    
    /// Sets the T-norm operator for combining rule antecedents with AND.
    pub fn with_t_norm(mut self, t_norm: Box<dyn TNorm<M>>) -> Self {
        self.t_norm = Some(t_norm);
        self
    }
    
    /// Sets the S-norm operator for combining rule antecedents with OR.
    pub fn with_s_norm(mut self, s_norm: Box<dyn SNorm<M>>) -> Self {
        self.s_norm = Some(s_norm);
        self
    }
    
    /// Adds multiple input variables at once.
    pub fn add_inputs(mut self, variables: Vec<LinguisticVariable<D, M>>) -> Self {
        for variable in variables {
            self.inputs.insert(variable.name().to_string(), variable);
        }
        self
    }
    
    /// Adds multiple output variables at once.
    pub fn add_outputs(mut self, variables: Vec<LinguisticVariable<D, M>>) -> Self {
        for variable in variables {
            self.outputs.insert(variable.name().to_string(), variable);
        }
        self
    }
    
    /// Adds multiple rules at once.
    pub fn add_rules(mut self, rules: Vec<FuzzyRule<D, M>>) -> Self {
        self.rules.extend(rules);
        self
    }
    
    /// Builds the fuzzy controller with the configured settings.
    pub fn build(self) -> FuzzyController<D, M> {
        use operators::{MinTNorm, MaxSNorm};
        
        FuzzyController {
            inputs: self.inputs,
            outputs: self.outputs,
            rules: self.rules,
            t_norm: self.t_norm.unwrap_or_else(|| Box::new(MinTNorm)),
            s_norm: self.s_norm.unwrap_or_else(|| Box::new(MaxSNorm)),
        }
    }
}

impl<D: Float, M: Float> Default for FuzzyControllerBuilder<D, M> {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::membership_functions::*;
    use crate::operators::*;
    use crate::defuzzification::*;
    
    fn approx_eq<T: Float>(a: T, b: T, epsilon: T) -> bool {
        (a - b).abs() < epsilon
    }
    
    #[test]
    fn test_membership_degree_new_valid() {
        let degree = MembershipDegree::new(0.5);
        assert!(degree.is_ok());
        assert_eq!(degree.unwrap().get(), 0.5);
    }
    
    #[test]
    fn test_membership_degree_new_invalid() {
        assert!(MembershipDegree::new(1.5).is_err());
        assert!(MembershipDegree::new(-0.5).is_err());
    }
    
    #[test]
    fn test_membership_degree_clamped() {
        assert_eq!(MembershipDegree::new_clamped(1.5).get(), 1.0);
        assert_eq!(MembershipDegree::new_clamped(-0.3).get(), 0.0);
    }
    
    #[test]
    fn test_triangular_membership() {
        let tri = Triangular::<f64, f64>::new(0.0, 50.0, 100.0).unwrap();
        assert_eq!(tri.evaluate(0.0).get(), 0.0);
        assert_eq!(tri.evaluate(50.0).get(), 1.0);
        assert_eq!(tri.evaluate(100.0).get(), 0.0);
        assert!(approx_eq(tri.evaluate(25.0).get(), 0.5, 0.01));
    }
    
    #[test]
    fn test_simple_controller() -> Result<(), MembershipError> {
        let mut temp = LinguisticVariable::new("temperature", (0.0, 100.0));
        temp.add_set(FuzzySet::new(
            "cold",
            Box::new(Triangular::new(0.0, 0.0, 50.0)?)
        ));
        temp.add_set(FuzzySet::new(
            "hot",
            Box::new(Triangular::new(50.0, 100.0, 100.0)?)
        ));
        
        let mut fan = LinguisticVariable::new("fan_speed", (0.0, 100.0));
        fan.add_set(FuzzySet::new(
            "low",
            Box::new(Triangular::new(0.0, 0.0, 50.0)?)
        ));
        fan.add_set(FuzzySet::new(
            "high",
            Box::new(Triangular::new(50.0, 100.0, 100.0)?)
        ));
        
        let rules = vec![
            FuzzyRule::new(
                vec![Condition::new("temperature", "cold")],
                RuleOperator::And,
                vec![Consequent::new("fan_speed", "low")],
            ),
            FuzzyRule::new(
                vec![Condition::new("temperature", "hot")],
                RuleOperator::And,
                vec![Consequent::new("fan_speed", "high")],
            ),
        ];
        
        let controller = FuzzyController::builder()
            .add_input(temp)
            .add_output(fan)
            .add_rules(rules)
            .build();
        
        let inputs = HashMap::from([("temperature".to_string(), 15.0)]);
        let outputs = controller.evaluate_centroid(&inputs)?;
        assert!(outputs["fan_speed"] < 50.0);
        
        let inputs = HashMap::from([("temperature".to_string(), 85.0)]);
        let outputs = controller.evaluate_centroid(&inputs)?;
        assert!(outputs["fan_speed"] > 50.0);
        
        Ok(())
    }
}