Add documentation comments to Mamdani inference components

Author: JoshuaKento

README.md

@@ -0,0 +1,94 @@
+# rust-fuzzylogic
+
+A work-in-progress Rust crate that provides building blocks for authoring fuzzy inference systems.
+The project aims to make it easy to describe linguistic variables, membership functions, and rule
+bases while keeping room for experimentation with multiple aggregation operators and inference
+strategies.
+
+## Project status
+
+The repository currently focuses on laying down the module structure of the crate. Several source
+files exist as stubs and will be fleshed out in future iterations. Even though the public API is not
+ready for consumption yet, the layout already highlights the intended responsibilities of each
+module:
+
+- `membership`: utilities for defining membership functions (triangular, trapezoidal, gaussian, …).
+- `variable`: strongly-typed linguistic variables composed of terms and membership functions.
+- `term`: basic linguistic terms that bind membership functions to human-readable labels.
+- `rulespace`: abstractions for authoring rule bases and connecting antecedents to consequents.
+- `antecedent`: helpers to compose fuzzy predicates out of linguistic terms.
+- `aggregate`: algorithms to combine the contribution of multiple rules.
+- `defuzz`: defuzzification routines that convert fuzzy outputs into crisp values.
+- `mamdani`: reference implementation of a Mamdani-style inference engine.
+- `ops`: configurable T-norm/T-conorm operators (minimum, product, Łukasiewicz, …).
+- `sampler`: sampling utilities for visualisation or numerical integration tasks.
+- `builder`: high-level ergonomics for constructing complete systems.
+- `error`: error types returned by the crate.
+- `prelude`: convenient re-exports for end users.
+
+## Getting started
+
+Because the implementation is still under construction the crate is not published on crates.io.
+Once the API stabilises you will be able to add it as a Git dependency in your `Cargo.toml`:
+
+```toml
+[dependencies]
+rust-fuzzylogic = { git = "https://github.com/your-org/rust-fuzzylogic" }
+```
+
+After the crate reaches its first release the dependency line will become:
+
+```toml
+[dependencies]
+rust-fuzzylogic = "0.1"
+```
+
+## Development
+
+If you would like to contribute, clone the repository and open it with your favourite editor:
+
+```bash
+git clone https://github.com/your-org/rust-fuzzylogic.git
+cd rust-fuzzylogic
+```
+
+The crate targets Rust 1.76+ (edition 2024). Standard Cargo commands apply:
+
+- `cargo check` — make sure the crate compiles.
+- `cargo fmt` — format the codebase.
+- `cargo test` — run the test suite (currently empty).
+
+### Feature flags
+
+The crate is organised around a set of feature flags to enable or disable components at compile
+time:
+
+- `f32` / `f64` — choose the floating-point precision used throughout the inference engine.
+- `serde` — derive serialisation support for configuration data structures.
+- `parallel` — enable rayon-powered parallel execution for suitable workloads.
+- `ops-minmax`, `ops-product`, `ops-lukasiewicz` — opt into specific operator families.
+- `ops-dyn` — use dynamic dispatch for selecting operators at runtime.
+- `inference-mamdani` — compile the Mamdani inference engine implementation.
+
+## Examples
+
+Example binaries will live under the `examples/` directory. They are not yet implemented, but the
+plan is to showcase tasks such as temperature control, batch processing, fuzzy C-means clustering,
+and gradient-descent tuning of membership functions. You will be able to run them with Cargo once
+they are published:
+
+```bash
+cargo run --example temperature
+```
+
+## Roadmap
+
+- [ ] Flesh out membership functions and sampling utilities.
+- [ ] Implement the Mamdani inference pipeline end-to-end.
+- [ ] Document the builder APIs and provide a quick start guide.
+- [ ] Publish the crate and examples for real-world testing.
+
+---
+
+This README will evolve alongside the code. Contributions, bug reports, and ideas are warmly
+welcome!

src/aggregate.rs

@@ -1,14 +1,16 @@
-//Agregation acros sets of rules
+// Aggregation utilities for combining rule outputs across consequents.
 
 use crate::{mamdani::Rule, prelude::*, variable::Variable};
 use std::{borrow::Borrow, collections::HashMap, hash::Hash};
 
+/// Combine two membership sample vectors by taking the pointwise maximum.
 pub fn elements_max(data: &mut Vec<Float>, src: &Vec<Float>) {
     for (d, s) in data.iter_mut().zip(src) {
         *d = d.max(*s)
     }
 }
 
+/// Aggregate the contributions of all rules into output membership functions.
 pub fn aggregation<KI, KV>(
     rules: Vec<Rule>,
     input: &HashMap<KI, Float>,

src/defuzz.rs

@@ -1,7 +1,8 @@
-//Possible Defuzz methods => Bisecctor of Area, Centroid, ...
+// Defuzzification utilities for collapsing aggregated membership values.
 use crate::{prelude::*, variable::Variable};
 use std::{borrow::Borrow, collections::HashMap, hash::Hash};
 
+/// Defuzzify aggregated membership samples using the centroid of area method.
 pub fn defuzzification<KV>(
     myu: HashMap<String, Vec<Float>>,
     vars: &HashMap<KV, Variable>,

src/mamdani.rs

@@ -1,4 +1,4 @@
-//mamdani style Implication and Consequent/Rule Behaviour
+// Mamdani-style implication and rule behavior primitives.
 
 use std::{borrow::Borrow, collections::HashMap, hash::Hash};
 
@@ -11,18 +11,21 @@ use crate::{
     variable::Variable,
 };
 
+/// Implication modes supported by a Mamdani rule.
 pub enum Implication {
     Clip,
     Product,
 }
 
+/// Output clause of a fuzzy rule referencing a linguistic variable and term.
 pub struct Consequent {
     pub var: String,
     pub term: String,
     //pub weight: Float,
     //pub imp: Implication,
 }
 
+/// Full fuzzy rule pairing an antecedent with one or more consequents.
 pub struct Rule {
     pub antecedent: Antecedent,
     pub consequent: Vec<Consequent>,
@@ -31,6 +34,7 @@ pub struct Rule {
 //Mamdani Inference Engine
 #[cfg(feature = "inference-mamdani")]
 impl Rule {
+    /// Evaluate the antecedent against crisp input values to obtain activation.
     pub fn activation<KI, KV>(
         &self,
         input: &HashMap<KI, Float>,
@@ -43,6 +47,7 @@ impl Rule {
         eval_antecedent(&self.antecedent, input, vars)
     }
 
+    /// Apply the selected implication operator to produce discretized membership outputs.
     pub fn implicate<KV>(
         &self,
         alpha: Float,

src/rulespace.rs

@@ -10,14 +10,15 @@ use crate::{
     variable::Variable,
 };
 
-//#[derive()]
+// Container for fuzzy variables, rules, and intermediate membership data.
 pub struct RuleSpace {
     pub vars: HashMap<String, Variable>,
     pub myu: HashMap<String, Vec<Float>>,
     pub rules: Vec<Rule>,
 }
 
 impl RuleSpace {
+    /// Create a rule space with the supplied variables and rules.
     pub fn new(self, vars: HashMap<String, Variable>, rules: Vec<Rule>) -> Self {
         return Self {
             vars: vars,
@@ -26,10 +27,12 @@ impl RuleSpace {
         };
     }
 
+    /// Append additional rules to the existing rule set.
     pub fn add_rules(mut self, rules: &mut Vec<Rule>) {
         self.rules.append(rules);
     }
 
+    /// Run the aggregation step for all rules with the provided crisp inputs.
     pub fn aggregate<KI>(
         &mut self,
         input: &HashMap<KI, Float>,
@@ -45,6 +48,7 @@ impl RuleSpace {
         Ok(())
     }
 
+    /// Aggregate and then defuzzify each output variable using the supplied sampler.
     pub fn defuzzificate<KI>(
         &mut self,
         input: &HashMap<KI, Float>,