fuzzy_associative_memory 1.0.0

data/LICENSE

@@ -0,0 +1,17 @@
+Copyright 2013, Prylis Incorporated.
+
+Please contact the author <cpowell@prylis.com> for questions about licensing
+or for specific licensing needs.
+
+The Ruby Fuzzy Associative Memory is free software: you can redistribute it
+and/or modify it under the terms of the GNU Lesser General Public License as
+published by the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+The Ruby Fuzzy Associative Memory is distributed in the hope that it will be
+useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser
+General Public License for more details.
+
+A copy of the GNU Lesser General Public License is at the end of this file, or see
+<http://www.gnu.org/licenses/lgpl.html>.

data/README.md

@@ -0,0 +1,58 @@
+# Fuzzy logic "Fuzzy Associative Memory"
+
+A Fuzzy Associative Memory (FAM for short) is a Fuzzy Logic tool for decision
+making. Fuzzy logic FAMs have a wide range of practical applications:
+
+* Control systems, such as governing a fan to keep a room at the "just right" temperature
+* Game AI, such as imbuing bots with human-like decision-making behavior
+* Prediction systems, linking causes with effects
+ 
+## How it works
+
+A Fuzzy Associative Memory uses Fuzzy Sets to establish a set of rules that are linguistic in nature; examples might include:
+
+* "If the room is a bit warm, turn the fan up a little bit"
+* "If the orc's hit points are a little low, retreat from the enemy"
+* "If the enemy is distant and my rocket ammo is low, the rocket launcher is a poor choice"
+* "If the enemy is near and my shotgun ammo is okay, the shotgun is a very desirable choice"
+* "If the ship is off course by a little bit, correct just a little to the right"
+* "If the bird is much slower than the flock, speed it up a lot"
+
+The linguistic rules, and the fuzzy sets they contain, are defined by a human "expert" (presumably, you). That is to say,
+the rules *codify intelligence* and map this knowledge from the human domain to the digital. 
+
+After the rules are defined, a FAM is consulted to help your AI make a descision:
+* The orc retreats, attacks, strafes.
+* The ship launches long range missiles or fires short range guns.
+* The control rods are lowered into the reactor or raised out of it.
+
+As you can see, the fuzzy rules are deliberately vague and use qualifiers like "a little" and "a lot". Furthermore, the lines
+between fuzzy sets are intentionally blurry. This is the nature of fuzzy sets; they capture such human fuzziness in a way that extracts highly natural behavior from the fuzzy rules.
+When defining these rules, it helps to imagine interviewing a bona fide expert in the domain and writing down the skills necessary to be successful in the domain.
+
+## Project status
+
+This is working, functional software, suitable for use in your own game or application. It currently supports:
+* Triangular & trapezoidal fuzzy sets for input/output
+* Larsen Implication (scaling)
+* Mamdani Implication (clipping)
+* Atomic antecedent propositions (`if A then Z`)
+* Composite antecedent propositions (`if A or B, then Z` / `if A and B, then Z`)
+
+To do (in descending importance, roughly):
+* Parameter validations to prevent bad shapes, improper FAM layout, etc.
+* Other shapes for fuzzy sets
+* Hedges ('very' and 'fairly')
+* Additional examples
+
+## Included examples
+
+The `bin` directory contains the following examples:
+* `hvac_system_example` illustrates how a FAM could govern an HVAC fan unit to maintain a constant, comfortable temperature
+* `weapon_choice_example` illustrates how a FAM could let a game bot intelligently decide which weapon to use
+
+## References used in the creation of this software
+* "Fuzzy Thinking: The New Science of Fuzzy Logic" by Bart Kosko [(Amazon link)](http://www.amazon.com/Fuzzy-Thinking-New-Science-Logic/dp/0006547133/)
+* "Fuzzy Logic: The Revolutionary Computer Technology that is Changing the World" by Daniel McNeill & Paul Freiberger [(Amazon link)](http://www.amazon.com/Fuzzy-Logic-Revolutionary-Computer-Technology/dp/0671875353/)
+* "Fuzzy Logic in Decision Making and Signal Processing" by Sujit Nath Pant & Keith E. Holbert [(Link)](http://enpub.fulton.asu.edu/powerzone/fuzzylogic/index.htm)
+* "Programming Game AI by Example" by Mat Buckland [(Amazon link)](http://www.amazon.com/Programming-Game-Example-Mat-Buckland/dp/1556220782)

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+task :default => [:test]
+
+desc "Run the test suite once"
+task :test do
+  ruby "test/all_suite.rb"
+end

data/bin/hvac_system_example.rb

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+#
+# Copyright 2013, Prylis Incorporated.
+#
+# This file is part of The Ruby Fuzzy Associative Memory
+# http://github.com/cpowell/fuzzy-associative-memory
+# You can redistribute and/or modify this software only in accordance with
+# the terms found in the "LICENSE" file included with the library.
+#
+require 'fuzzy_associative_memory'
+
+# Set me to true to enable some verbose output of my calculations...
+$verbosity = false
+
+# This example is the logic to drive an HVAC fan unit depending on the ambient
+# room temperature. A hotter room needs a higher fan; in a cooler room the fan
+# can slow, and in a cold room the fan should stop. For the graphs and
+# explanation of this particular FAM, see "Fuzzy Thinking" by Bart Kosko:
+# http://www.amazon.com/Fuzzy-Thinking-New-Science-Logic/dp/1562828398/
+
+# The input side -- the antecedent -- is expressed as a number of fuzzy sets,
+# with each set representing a natural-language description. The 'temperature
+# input' variable, is the  assemblage of all our fuzzy input sets.
+temperature_in = FuzzyAssociativeMemory::LinguisticVariable.new("room temperature") # degrees fahrenheit
+
+# Wider: less important, coarse control; narrower: more important, fine control
+cold       = FuzzyAssociativeMemory::Trapezoid.new(40, 40, 40, 50)  # 20 deg wide
+cool       = FuzzyAssociativeMemory::Triangle.new(45, 55, 65)  # 20 deg wide
+just_right = FuzzyAssociativeMemory::Triangle.new(60, 65, 70)  # 10 deg wide
+warm       = FuzzyAssociativeMemory::Triangle.new(65, 75, 85)  # 20 deg wide
+hot        = FuzzyAssociativeMemory::Trapezoid.new(80, 90, 90, 90) # 20 deg wide
+
+temperature_in.sets = [cold, cool, just_right, warm, hot]
+
+# The output side -- the consequent -- expressed as a number of fuzzy sets,
+# with each set representing a natural-language description. The 'resultant
+# fan speed' variable, is the  assemblage of all our fuzzy output sets.
+fan_speed = FuzzyAssociativeMemory::LinguisticVariable.new("fan speed") # cubic feet per minute (CFM)
+
+stop   = FuzzyAssociativeMemory::Triangle.new(-30, 0, 30)   # 60 CFM wide
+slow   = FuzzyAssociativeMemory::Triangle.new(10, 30, 50)   # 40 CFM wide
+medium = FuzzyAssociativeMemory::Triangle.new(40, 50, 60)   # 20 CFM wide
+fast   = FuzzyAssociativeMemory::Triangle.new(50, 70, 90)   # 40 CFM wide
+blast  = FuzzyAssociativeMemory::Triangle.new(70, 100, 130) # 60 CFM wide
+
+fan_speed.sets = [stop, slow, medium, fast, blast]
+
+# Natural-language marriage of the inputs to the outputs, e.g.
+# "If the temperature is cool, the fan motor speed should be slow."
+system = FuzzyAssociativeMemory::Ruleset.new("HVAC control", :larsen)
+
+rule_1 = FuzzyAssociativeMemory::Rule.new('If room is cold, the fan motor stops',           [cold],       nil, stop)
+rule_2 = FuzzyAssociativeMemory::Rule.new('If room is cool, the fan motor is slow',         [cool],       nil, slow)
+rule_3 = FuzzyAssociativeMemory::Rule.new('If room is just right, the fan motor is medium', [just_right], nil, medium)
+rule_4 = FuzzyAssociativeMemory::Rule.new('If room is warm, the fan motor speeds up',       [warm],       nil, fast)
+rule_5 = FuzzyAssociativeMemory::Rule.new('If room is hot, the fan motor runs full-blast',  [hot],        nil, blast)
+
+system.rules = [rule_1, rule_2, rule_3, rule_4, rule_5]
+
+# n=64
+# puts "The #{system.name} determines: for #{temperature_in.name} #{n}, the #{fan_speed.name} is #{system.calculate(n)} CFM"
+
+# Check the logic for a wide range of temps and output the results
+(40..90).each do |n|
+  puts "The #{system.name} determines: for #{temperature_in.name} #{n}, the #{fan_speed.name} is #{system.calculate(n)} CFM"
+end

data/bin/weapon_choice_example.rb

@@ -0,0 +1,115 @@
+#!/usr/bin/env ruby
+#
+# Copyright 2013, Prylis Incorporated.
+#
+# This file is part of The Ruby Fuzzy Associative Memory
+# http://github.com/cpowell/fuzzy-associative-memory
+# You can redistribute and/or modify this software only in accordance with
+# the terms found in the "LICENSE" file included with the library.
+#
+require 'fuzzy_associative_memory'
+
+# Set me to true to enable some verbose output of my calculations...
+$verbosity = false
+
+implication = :mamdani # or :larsen
+
+# This is a complicated example; I recommend you understand the 'HVAC system
+# example' before trying to grok this one.
+#
+# This example is inspired by the fuzzy logic described by Mat Buckland in
+# "Programming Game AI by Example". In this we illustrate how an AI 'bot'
+# might use fuzzy logic to pick which weapon to use. Unlike the 'HVAC system'
+# example, which uses just one input, this example uses two inputs: distance
+# to enemy, and ammo remaining. WE SET UP AND RUN TWO FAMS, FOR TWO DIFFERENT
+# WEAPONS (ROCKET AND SHOTGUN), TO CHOOSE WHICH WEAPON TO USE.
+
+# The input side -- the antecedents -- are expressed as a number of fuzzy sets,
+# with each set representing a natural-language description. The 'distance to
+# target' variable is an assemblage of our fuzzy input sets.
+target_dist = FuzzyAssociativeMemory::LinguisticVariable.new("distance to target") # pixels
+
+tgt_close  = FuzzyAssociativeMemory::Trapezoid.new(-150, -25, 25, 150)
+tgt_medium = FuzzyAssociativeMemory::Triangle.new(25, 150, 300)
+tgt_far    = FuzzyAssociativeMemory::Trapezoid.new(150, 300, 500, 650)
+
+target_dist.sets = [tgt_close, tgt_medium, tgt_far]
+
+# Now for the second input (or antecedent): the amount of ammo left for this
+# particular weapon.
+rocket_ammo_status = FuzzyAssociativeMemory::LinguisticVariable.new("rocket launcher ammo quantity")
+
+rkt_ammo_low   = FuzzyAssociativeMemory::Triangle.new(-10, 0, 10)
+rkt_ammo_okay  = FuzzyAssociativeMemory::Triangle.new(0, 10, 30)
+rkt_ammo_loads = FuzzyAssociativeMemory::Trapezoid.new(10, 30, 40, 40)
+
+rocket_ammo_status.sets = [rkt_ammo_low, rkt_ammo_okay, rkt_ammo_loads]
+
+# The output side -- the consequent -- expressed as a number of fuzzy sets,
+# with each set representing a natural-language description. The 'resultant
+# fan speed' variable is the  assemblage of all our fuzzy output sets.
+desirability = FuzzyAssociativeMemory::LinguisticVariable.new("weapon desirability")
+
+undes   = FuzzyAssociativeMemory::Trapezoid.new(0, 0, 20, 50)
+desir   = FuzzyAssociativeMemory::Triangle.new(30, 50, 70)
+v_desir = FuzzyAssociativeMemory::Trapezoid.new(50, 80, 100, 100)
+
+desirability.sets = [undes, desir, v_desir]
+
+# Natural-language marriage of the inputs to the outputs, e.g.
+# "If the temperature is cool, the fan motor speed should be slow."
+rkt_ruleset = FuzzyAssociativeMemory::Ruleset.new("Rocket launcher desirability", implication)
+
+rule_1 = FuzzyAssociativeMemory::Rule.new('If target is far and I have loads of rocket ammo, rocket launcher is desirable', [tgt_far, rkt_ammo_loads], :and, desir)
+rule_2 = FuzzyAssociativeMemory::Rule.new('If target is far and I have some rocket ammo, rocket launcher is undesirable', [tgt_far, rkt_ammo_okay], :and, undes)
+rule_3 = FuzzyAssociativeMemory::Rule.new('If target is far and I have low rocket ammo, rocket launcher is undesirable', [tgt_far, rkt_ammo_low], :and, undes)
+rule_4 = FuzzyAssociativeMemory::Rule.new('If target is medium-distance and I have loads of rocket ammo, rocket launcher is very desirable', [tgt_medium, rkt_ammo_loads], :and, v_desir)
+rule_5 = FuzzyAssociativeMemory::Rule.new('If target is medium-distance and I have some rocket ammo, rocket launcher is very desirable', [tgt_medium, rkt_ammo_okay], :and, v_desir)
+rule_6 = FuzzyAssociativeMemory::Rule.new('If target is medium-distance and I have low rocket ammo, rocket launcher is desirable', [tgt_medium, rkt_ammo_low], :and, desir)
+rule_7 = FuzzyAssociativeMemory::Rule.new('If target is close and I have loads of rocket ammo, rocket launcher is undesirable', [tgt_close, rkt_ammo_loads], :and, undes)
+rule_8 = FuzzyAssociativeMemory::Rule.new('If target is close and I have some rocket ammo, rocket launcher is undesirable', [tgt_close, rkt_ammo_okay], :and, undes)
+rule_9 = FuzzyAssociativeMemory::Rule.new('If target is close and I have low rocket ammo, rocket launcher is undesirable', [tgt_close, rkt_ammo_low], :and, undes)
+
+rkt_ruleset.rules = [rule_1, rule_2, rule_3, rule_4, rule_5, rule_6, rule_7, rule_8, rule_9]
+
+d  = 110
+ra = 8
+rocket_desirability = rkt_ruleset.calculate(d, ra)
+puts "#{rkt_ruleset.name}: for #{target_dist.name} #{d} and #{rocket_ammo_status.name} #{ra}, the #{desirability.name} is #{rocket_desirability}"
+
+##################################
+# That was ONE FAM. Now we set up a WHOLE NEW FAM based on the shotgun data.
+# We can re-use the 'desirability' consequent since that's static across all
+# weapons. We just need new antecedents and rules.
+
+# Now for the second input (or antecedent): the amount of ammo left for this
+# particular weapon.
+shotgun_ammo_status = FuzzyAssociativeMemory::LinguisticVariable.new("shotgun ammo quantity")
+gun_ammo_low   = FuzzyAssociativeMemory::Triangle.new(-10, 0, 10)
+gun_ammo_okay  = FuzzyAssociativeMemory::Triangle.new(0, 10, 30)
+gun_ammo_loads = FuzzyAssociativeMemory::Trapezoid.new(10, 30, 40, 40)
+shotgun_ammo_status.sets = [gun_ammo_low, gun_ammo_okay, gun_ammo_loads]
+
+gun_ruleset = FuzzyAssociativeMemory::Ruleset.new("Shotgun desirability", implication)
+rule_1 = FuzzyAssociativeMemory::Rule.new('If target is far and I have loads of shotgun ammo, shotgun is undesirable', [tgt_far, gun_ammo_loads], :and, undes)
+rule_2 = FuzzyAssociativeMemory::Rule.new('If target is far and I have some shotgun ammo, shotgun is undesirable', [tgt_far, gun_ammo_okay], :and, undes)
+rule_3 = FuzzyAssociativeMemory::Rule.new('If target is far and I have low shotgun ammo, shotgun is undesirable', [tgt_far, gun_ammo_low], :and, undes)
+rule_4 = FuzzyAssociativeMemory::Rule.new('If target is medium-distance and I have loads of shotgun ammo, shotgun is desirable', [tgt_medium, gun_ammo_loads], :and, desir)
+rule_5 = FuzzyAssociativeMemory::Rule.new('If target is medium-distance and I have some shotgun ammo, shotgun is desirable', [tgt_medium, gun_ammo_okay], :and, desir)
+rule_6 = FuzzyAssociativeMemory::Rule.new('If target is medium-distance and I have low shotgun ammo, shotgun is undesirable', [tgt_medium, gun_ammo_low], :and, undes)
+rule_7 = FuzzyAssociativeMemory::Rule.new('If target is close and I have loads of shotgun ammo, shotgun is very desirable', [tgt_close, gun_ammo_loads], :and, v_desir)
+rule_8 = FuzzyAssociativeMemory::Rule.new('If target is close and I have some shotgun ammo, shotgun is very desirable', [tgt_close, gun_ammo_okay], :and, v_desir)
+rule_9 = FuzzyAssociativeMemory::Rule.new('If target is close and I have low shotgun ammo, shotgun is very desirable', [tgt_close, gun_ammo_low], :and, v_desir)
+gun_ruleset.rules = [rule_1, rule_2, rule_3, rule_4, rule_5, rule_6, rule_7, rule_8, rule_9]
+
+sa = 12
+gun_desirability = gun_ruleset.calculate(d, sa)
+puts "#{gun_ruleset.name}: for #{target_dist.name} #{d} and #{shotgun_ammo_status.name} #{sa}, the #{desirability.name} is #{gun_desirability}"
+
+if gun_desirability < rocket_desirability
+  outcome='I choose the rocket launcher.'
+else
+  outcome='I choose the shotgun.'
+end
+
+puts outcome

data/lib/fuzzy_associative_memory/linguistic_variable.rb

@@ -0,0 +1,25 @@
+#
+# Copyright 2013, Prylis Incorporated.
+#
+# This file is part of The Ruby Fuzzy Associative Memory
+# http://github.com/cpowell/fuzzy-associative-memory
+# You can redistribute and/or modify this software only in accordance with
+# the terms found in the "LICENSE" file included with the library.
+#
+class FuzzyAssociativeMemory::LinguisticVariable
+  attr_accessor :sets
+  attr_reader :name
+
+  def initialize(name)
+    @name       = name
+    @sets = []
+  end
+
+  def add_set(set)
+    @sets << set
+  end
+
+  def [](n)
+    @sets[n]
+  end
+end

data/lib/fuzzy_associative_memory/rule.rb

@@ -0,0 +1,63 @@
+# encoding: utf-8
+#
+# Copyright 2013, Prylis Incorporated.
+#
+# This file is part of The Ruby Fuzzy Associative Memory
+# http://github.com/cpowell/fuzzy-associative-memory
+# You can redistribute and/or modify this software only in accordance with
+# the terms found in the "LICENSE" file included with the library.
+#
+class FuzzyAssociativeMemory::Rule
+  attr_reader :antecedents, :consequent, :boolean
+
+  # Marries an input fuzzy set and an output fuzzy set in an if-then
+  # arrangement, i.e. if (antecedent) then (consequent).
+  #
+  # * *Args*    :
+  #   - +antecedent_array+ -> an array of one or more input fuzzy sets
+  #   - +boolean+ -> term to join the antecedents, may be: nil, 'AND', 'OR'
+  #   - +consequent+ -> the output fuzzy set
+  #   - +natural_language+ -> a rule description (your own words), useful in output
+  #
+  def initialize(natural_language, antecedent_array, boolean, consequent)
+    raise ArgumentError, "Antecedent array must contain at least one fuzzy set" unless antecedent_array.size > 0
+    raise ArgumentError, "Consequent must be provided" unless consequent
+
+    if antecedent_array.size > 1
+      raise ArgumentError, "boolean must be sym :and or :or" unless [:and, :or].include? boolean
+    else
+      raise ArgumentError, "boolean must be nil" unless boolean.nil?
+    end
+
+    @natural_language = natural_language
+    @antecedents      = antecedent_array
+    @consequent       = consequent
+    @boolean          = boolean
+  end
+
+  # Triggers the rule. The antecedent(s) is/are fired with the supplied inputs
+  # and the µ (degree of fit) is calculated and returned.
+  #
+  # * *Args*    :
+  #   - +value_array+ -> an array of input values for the rule (degrees, distance, strength, whatever)
+  # * *Returns* :
+  #   - the degree of fit for this rule
+  #
+  def fire(value_array)
+    mus = Array.new
+
+    @antecedents.each_with_index do |antecedent, index|
+      mus[index] = antecedent.mu(value_array[index])
+    end
+
+    if @boolean==:and
+      mu = mus.min # AND / Intersection == minimum
+    else
+      mu = mus.max # OR / Union == maximum
+    end
+
+    puts "Fired rule '#{@natural_language}': µ choices are [#{mus.join(',')}], final µ is #{mu}" if $verbosity
+    [@consequent, mu]
+  end
+
+end

data/lib/fuzzy_associative_memory/ruleset.rb

@@ -0,0 +1,79 @@
+# encoding: utf-8
+#
+# Copyright 2013, Prylis Incorporated.
+#
+# This file is part of The Ruby Fuzzy Associative Memory
+# http://github.com/cpowell/fuzzy-associative-memory
+# You can redistribute and/or modify this software only in accordance with
+# the terms found in the "LICENSE" file included with the library.
+#
+class FuzzyAssociativeMemory::Ruleset
+  attr_accessor :rules
+  attr_reader :name
+  attr_reader :implication
+
+  def initialize(name, implication_mechanism)
+    raise ArgumentError, 'invalid implication mechanism' unless [:larsen, :mamdani].include? implication_mechanism
+    @name  = name
+    @rules = []
+    @implication = implication_mechanism
+  end
+
+  def add_rule(rule)
+    @rules << rule
+  end
+
+  def calculate(*input_values)
+    @consequent_mus   = {}
+    @kept_consequents = {}
+    @consequents      = []
+
+    puts ">>> Firing all rules..." if $verbosity
+    @rules.each_with_index do |rule, rule_num|
+      # Fire each rule to determine the µ value (degree of fit).
+      # Gather the µ vals by consequent, since each consequent may in fact
+      # have been fired more than once and we'll need that knowledge in a
+      # moment...
+      cons, mu = rule.fire(input_values)
+      if @consequent_mus.has_key?(cons)
+        @consequent_mus[cons] << mu
+      else
+        @consequent_mus[cons] = [mu]
+      end
+    end
+
+    # Since any given consequent may have been activated more than once, we
+    # need to get just a single µ value out -- we only care about the 'best'
+    # µ. A popular way of doing so is to OR the values together, i.e. keep the
+    # maximum µ value and discard the others.
+    @consequent_mus.each do |cons, mu_array|
+      @kept_consequents[cons] = mu_array.max
+    end
+
+    # Using each µ value, alter the consequent fuzzy set's polgyon. This is
+    # called implication, and 'weights' the consequents properly. There are
+    # several common ways of doing it, such as Larsen (scaling) and Mamdani
+    # (clipping).
+    @kept_consequents.each do |cons, mu|
+      case @implication
+      when :mamdani
+        @consequents << cons.mamdani(mu)
+      when :larsen
+        @consequents << cons.larsen(mu)
+      else
+        raise RuntimeError, "I must have been passed an unknown implication mechanism: #{@implication}"
+      end
+    end
+
+    # Defuzzify into a discrete & usable value by adding up the weighted
+    # consequents' contributions to the output. Again there are several ways
+    # of doing it, such as computing the centroid of the combined 'mass', or
+    # the 'mean of maximum' of the tallest set(s). Here we use the "Average
+    # of Maxima" summation mechanism. MaxAv is defined as:
+    # (∑ representative value * height) / (∑ height) for all output sets
+    # where 'representative value' is shape-dependent.
+    numerator_terms   = @consequents.map { |set| set.centroid_x * set.height }
+    denominator_terms = @consequents.map { |set| set.height }
+    numerator_terms.inject{|sum,x| sum + x } / denominator_terms.inject{|sum,x| sum + x }
+  end
+end

data/lib/fuzzy_associative_memory/set.rb

@@ -0,0 +1,34 @@
+#
+# Copyright 2013, Prylis Incorporated.
+#
+# This file is part of The Ruby Fuzzy Associative Memory
+# http://github.com/cpowell/fuzzy-associative-memory
+# You can redistribute and/or modify this software only in accordance with
+# the terms found in the "LICENSE" file included with the library.
+#
+class FuzzyAssociativeMemory::FuzzySet
+
+  # mu (named for the symbol) is the 'membership function', sometimes known as
+  # the 'degree of fit' or the 'degree of membership'. This computed value
+  # informs HOW MUCH this set activates or fires for the provided input value.
+  # A DoM of zero means that this set fits the input not at all; a DoM of 1.0
+  # means that this set fires / fits completely.
+  #
+  # * *Args*    :
+  #   - +value+ -> the input value in question
+  # * *Returns* :
+  #   - a 'fitness' degree between 0 and 1.0
+  #
+  def mu(value)
+    raise "Subclass must define!"
+  end
+
+  def centroid_x
+    raise "Subclass must define!"
+  end
+
+  def larsen(ratio)
+    raise "Subclass must define!"
+  end
+
+end

data/lib/fuzzy_associative_memory/trapezoid.rb

@@ -0,0 +1,70 @@
+#
+# Copyright 2013, Prylis Incorporated.
+#
+# This file is part of The Ruby Fuzzy Associative Memory
+# http://github.com/cpowell/fuzzy-associative-memory
+# You can redistribute and/or modify this software only in accordance with
+# the terms found in the "LICENSE" file included with the library.
+#
+require 'fuzzy_associative_memory/set'
+class FuzzyAssociativeMemory::Trapezoid < FuzzyAssociativeMemory::FuzzySet
+
+  attr_reader :left, :top_left, :top_right, :right, :height
+
+  def initialize(left, top_left, top_right, right, height=1.0)
+    # TODO validations
+
+    @left      = left.to_f
+    @top_left  = top_left.to_f
+    @top_right = top_right.to_f
+    @right     = right.to_f
+    @height    = height.to_f
+  end
+
+  def mu(value)
+    if value < @left || value > @right
+      0.0
+    elsif value >= @left && value < @top_left
+      (value - @left) / (@top_left - @left)
+    elsif value >= @top_left && value <= @top_right
+      1.0
+    else
+      (@right - value) / (@right - @top_right)
+    end
+  end
+
+  def centroid_x
+    a = @top_right - @top_left
+    b = @right - @left
+    c = @top_left - @left
+
+    cx = (2.0*a*c + a**2 + c*b + a*b + b**2.0) / (3.0 * (a+b))
+    cx + @left
+    # cy = (@height * (2.0*a + b)) / (3.0 * (a+b))
+    # [cx+@left, cy]
+  end
+
+  def height=(new_height)
+    @height = new_height
+  end
+
+  def larsen(ratio)
+    t = self.dup
+    t.height=(t.height * ratio)
+    t
+  end
+
+  def mamdani(clip_height)
+    left      = @left
+    top_left  = @left + (clip_height * (@top_left - @left))
+    top_right = @right - (clip_height * (@right - @top_right))
+    right     = @right
+
+    FuzzyAssociativeMemory::Trapezoid.new(left, top_left, top_right, right, clip_height)
+  end
+
+  def to_s
+    "Trapezoid {#{@left}/#{@top_left}/#{@top_right}/#{@right}, height #{@height}}"
+  end
+
+end

data/lib/fuzzy_associative_memory/triangle.rb

@@ -0,0 +1,60 @@
+#
+# Copyright 2013, Prylis Incorporated.
+#
+# This file is part of The Ruby Fuzzy Associative Memory
+# http://github.com/cpowell/fuzzy-associative-memory
+# You can redistribute and/or modify this software only in accordance with
+# the terms found in the "LICENSE" file included with the library.
+#
+require 'fuzzy_associative_memory/set'
+class FuzzyAssociativeMemory::Triangle < FuzzyAssociativeMemory::FuzzySet
+
+  attr_reader :left, :center, :right, :height
+
+  def initialize(left, center, right, height=1.0)
+    # TODO validations
+
+    @center = center.to_f
+    @left   = left.to_f
+    @right  = right.to_f
+    @height = height.to_f
+  end
+
+  def mu(value)
+    if value < @left || value > @right
+      0.0
+    else
+      1 - ((@center-value).abs / ((@right - @left) / 2.0 ))
+    end
+  end
+
+  def centroid_x
+    cx = (@left + @right + @center) / 3.0
+    # cy = @height / 3.0
+    # [cx, cy]
+  end
+
+  def height=(new_height)
+    @height = new_height
+  end
+
+  def larsen(ratio)
+    t = self.dup
+    t.height=(t.height * ratio)
+    t
+  end
+
+  def mamdani(clip_height)
+    left      = @left
+    top_left  = @left + (clip_height * (@center - @left))
+    top_right = @right - (clip_height * (@right - @center))
+    right     = @right
+
+    FuzzyAssociativeMemory::Trapezoid.new(left, top_left, top_right, right, clip_height)
+  end
+
+  def to_s
+    "Triangle {#{@left}/#{@center}/#{@right}, height #{@height}}"
+  end
+
+end

data/lib/fuzzy_associative_memory.rb

@@ -0,0 +1,9 @@
+class FuzzyAssociativeMemory
+end
+
+require 'fuzzy_associative_memory/linguistic_variable'
+require 'fuzzy_associative_memory/triangle'
+require 'fuzzy_associative_memory/trapezoid'
+require 'fuzzy_associative_memory/rule'
+require 'fuzzy_associative_memory/ruleset'
+require 'fuzzy_associative_memory/set'

data/test/all_suite.rb

@@ -0,0 +1,11 @@
+# This is a whole test suite.
+#
+# $ ruby test/all_suite.rb
+# or just
+# $ rake test
+
+# require 'simplecov'
+# SimpleCov.start
+
+require "test/triangle_test"
+require "test/trapezoid_test"

data/test/trapezoid_test.rb

@@ -0,0 +1,96 @@
+gem 'minitest'
+require 'minitest/autorun'
+
+$:.push File.expand_path('../../lib/', __FILE__)
+require 'fuzzy_associative_memory'
+
+# ruby ./test/trapezoid_test.rb
+
+class TrapezoidTest < MiniTest::Unit::TestCase
+  def setup
+    @t = FuzzyAssociativeMemory::Trapezoid.new(7, 10, 13, 16)
+  end
+
+  def test_dom_is_zero_outside_left_bound
+    assert_equal(0, @t.mu(2))
+  end
+
+  def test_dom_is_zero_at_left
+    assert_equal(0, @t.mu(7))
+  end
+
+  def test_dom_is_half_at_half_left_offset
+    assert_equal(0.5, @t.mu(8.5))
+  end
+
+  def test_dom_is_one_at_top_left
+    assert_equal(1.0, @t.mu(10))
+  end
+
+  def test_dom_is_one_at_top_right
+    assert_equal(1.0, @t.mu(13))
+  end
+
+  def test_dom_is_half_at_half_right_offset
+    assert_equal(0.5, @t.mu(14.5))
+  end
+
+  def test_dom_is_zero_at_right
+    assert_equal(0, @t.mu(16))
+  end
+
+  def test_dom_is_zero_outside_right_bound
+    assert_equal(0, @t.mu(17))
+  end
+
+  def test_dom_is_correct_at_three_fifths_offset
+    t = FuzzyAssociativeMemory::Trapezoid.new(0, 5, 10, 15)
+    assert_equal(0.6, t.mu(3.0))
+  end
+
+  def test_dom_is_correct_at_seven_tenths_offset
+    t = FuzzyAssociativeMemory::Trapezoid.new(0, 5, 10, 15)
+    assert_equal(0.6, t.mu(12.0))
+  end
+
+  def test_centroid_calculation_1
+    t = FuzzyAssociativeMemory::Trapezoid.new(0, 20, 50, 50)
+    assert_equal(29.583333333333332, t.centroid_x)
+  end
+
+  def test_centroid_calculation_2
+    t = FuzzyAssociativeMemory::Trapezoid.new(0, 10, 20, 30)
+    assert_equal(15.0, t.centroid_x)
+  end
+
+  def test_centroid_calculation_when_not_starting_at_zero
+    t = FuzzyAssociativeMemory::Trapezoid.new(50, 80, 100, 100)
+    assert_equal(81.42857142857143, t.centroid_x)
+  end
+
+  def test_dom_1
+    t = FuzzyAssociativeMemory::Trapezoid.new(20, 30, 40, 50)
+    assert_equal(0.9, t.mu(41))
+  end
+
+  def test_mamdani_clipping_1
+    t = FuzzyAssociativeMemory::Trapezoid.new(0, 30, 100, 110)
+    t2 = t.mamdani(0.83)
+    assert_equal(0, t2.left)
+    assert_equal(24.9, t2.top_left)
+    assert_equal(101.7, t2.top_right)
+    assert_equal(110, t2.right)
+    assert_equal(0.83, t2.height)
+  end
+
+  def test_mamdani_clipping_2
+    t = FuzzyAssociativeMemory::Trapezoid.new(50, 80, 150, 160)
+    t2 = t.mamdani(0.83)
+    assert_equal(50, t2.left)
+    assert_equal(74.9, t2.top_left)
+    assert_equal(151.7, t2.top_right)
+    assert_equal(160, t2.right)
+    assert_equal(0.83, t2.height)
+  end
+
+end

data/test/triangle_test.rb

@@ -0,0 +1,64 @@
+gem 'minitest'
+require 'minitest/autorun'
+
+$:.push File.expand_path('../../lib/', __FILE__)
+require 'fuzzy_associative_memory'
+
+# ruby ./test/triangle_test.rb
+
+class TriangleTest < MiniTest::Unit::TestCase
+  def setup
+    @t = FuzzyAssociativeMemory::Triangle.new(7, 10, 13)
+  end
+
+  def test_dom_is_zero_outside_left_bound
+    assert_equal(0, @t.mu(2))
+  end
+
+  def test_dom_is_zero_outside_right_bound
+    assert_equal(0, @t.mu(15))
+  end
+
+  def test_dom_is_one_at_peak
+    assert_equal(1.0, @t.mu(10))
+  end
+
+  def test_dom_is_half_at_half_right_offset
+    assert_equal(0.5, @t.mu(11.5))
+  end
+
+  def test_dom_is_half_at_half_left_offset
+    assert_equal(0.5, @t.mu(8.5))
+  end
+
+  def test_dom_is_correct_at_three_fifths_offset
+    t = FuzzyAssociativeMemory::Triangle.new(0, 5, 10)
+    assert_equal(0.6, t.mu(3.0))
+  end
+
+  def test_dom_is_correct_at_seven_tenths_offset
+    t = FuzzyAssociativeMemory::Triangle.new(0, 5, 10)
+    assert_equal(0.6, t.mu(7.0))
+  end
+
+  def test_centroid_calculation
+    t = FuzzyAssociativeMemory::Triangle.new(5, 10, 15)
+    assert_equal(10.0, t.centroid_x)
+  end
+
+  def test_larsen_scaling
+    scaled = @t.larsen(0.15)
+    assert_equal(0.15, scaled.height)
+  end
+
+  def test_mamdani_clipping_1
+    t2 = @t.mamdani(0.83)
+    assert(t2.is_a? FuzzyAssociativeMemory::Trapezoid)
+    assert_equal(7, t2.left)
+    assert_equal(9.49, t2.top_left)
+    assert_equal(10.51, t2.top_right)
+    assert_equal(13, t2.right)
+    assert_equal(0.83, t2.height)
+  end
+
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: fuzzy_associative_memory
+version: !ruby/object:Gem::Version
+  prerelease:
+  version: 1.0.0
+platform: ruby
+authors:
+- Chris Powell
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2013-06-26 00:00:00.000000000 Z
+dependencies: []
+description: |2
+      A Fuzzy Associative Memory (FAM for short) is a Fuzzy Logic tool for decision making. Fuzzy logic FAMs have a wide range of practical applications:
+
+      * Control systems, such as governing a fan to keep a room at the "just right" temperature
+      * Game AI, such as imbuing bots with human-like decision-making behavior
+      * Prediction systems, linking causes with effects
+
+      A Fuzzy Associative Memory uses Fuzzy Sets to establish a set of rules that are linguistic in nature. The linguistic rules, and the fuzzy sets they contain, are defined by a human "expert" (presumably, you). That is to say, the rules codify intelligence and map this knowledge from the human domain to the digital.
+email: cpowell@prylis.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/fuzzy_associative_memory.rb
+- lib/fuzzy_associative_memory/linguistic_variable.rb
+- lib/fuzzy_associative_memory/rule.rb
+- lib/fuzzy_associative_memory/ruleset.rb
+- lib/fuzzy_associative_memory/set.rb
+- lib/fuzzy_associative_memory/trapezoid.rb
+- lib/fuzzy_associative_memory/triangle.rb
+- bin/hvac_system_example.rb
+- bin/weapon_choice_example.rb
+- LICENSE
+- Rakefile
+- README.md
+- test/all_suite.rb
+- test/trapezoid_test.rb
+- test/triangle_test.rb
+homepage: http://github.com/cpowell/fuzzy-associative-memory
+licenses:
+- LGPL
+post_install_message:
+rdoc_options:
+- --main
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+requirements: []
+rubyforge_project:
+rubygems_version: 1.8.24
+signing_key:
+specification_version: 3
+summary: A fuzzy logic 'Fuzzy Associative Memory' (FAM) for fuzzy control systems, decision-making, artificial intelligence / AI, game agents & bots, etc.
+test_files: []