vector_space 0.1.2

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2009 Tom Stuart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,110 @@
+VectorSpace
+===========
+
+A Ruby library for treating multidimensional values as elements of a vector space.
+
+Examples
+--------
+
+A simple vector space:
+
+    class Round < VectorSpace::SimpleVector
+      has_dimension :hoegaarden
+      has_dimension :franziskaner
+      has_dimension :fruli
+      has_dimension :water
+    end
+
+    >> Round.new
+    => 0 and 0 and 0 and 0
+
+    >> Round.new :hoegaarden => 5, :fruli => 3
+    => 5 and 0 and 3 and 0
+
+With custom descriptions:
+
+    class Round < VectorSpace::SimpleVector
+      has_dimension :hoegaarden,    :describe => lambda { |n| "#{n} Hoegaardens" unless n.zero? }
+      has_dimension :franziskaner,  :describe => lambda { |n| "#{n} Franziskaners" unless n.zero? }
+      has_dimension :fruli,         :describe => lambda { |n| "#{n} Frülis" unless n.zero? }
+      has_dimension :water,         :describe => lambda { |n| "#{n} waters" unless n.zero? }
+      has_zero_description 'no drinks'
+    end
+
+    >> Round.new
+    => no drinks
+
+    >> Round.new :hoegaarden => 5, :fruli => 3
+    => 5 Hoegaardens and 3 Frülis
+
+    >> Round.new(:hoegaarden => 2, :franziskaner => 3) + Round.new(:water => 2, :fruli => 2, :hoegaarden => 1)
+    => 3 Hoegaardens and 3 Franziskaners and 2 Frülis and 2 waters
+
+    >> (Round.new(:hoegaarden => 2, :franziskaner => 3) * 2) - Round.new(:hoegaarden => 1)
+    => 3 Hoegaardens and 6 Franziskaners
+
+An indexed family of vector spaces with custom descriptions:
+
+    class Cocktail < VectorSpace::SimpleIndexedVector
+      indexed_by :units
+      has_dimension :gin,       :describe => lambda { |units, n| "#{n}#{units} gin" unless n.zero? }
+      has_dimension :vermouth,  :describe => lambda { |units, n| "#{n}#{units} vermouth" unless n.zero? }
+      has_dimension :whisky,    :describe => lambda { |units, n| "#{n}#{units} whisky" unless n.zero? }
+      has_dimension :vodka,     :describe => lambda { |units, n| "#{n}#{units} vodka" unless n.zero? }
+      has_dimension :kahlua,    :describe => lambda { |units, n| "#{n}#{units} Kahlúa" unless n.zero? }
+      has_dimension :cream,     :describe => lambda { |units, n| "#{n}#{units} cream" unless n.zero? }
+    end
+
+    >> martini = Cocktail.new :units => :cl, :gin => 5.5, :vermouth => 1.5
+    => 5.5cl gin and 1.5cl vermouth
+
+    >> manhattan = Cocktail.new :units => :cl, :whisky => 5, :vermouth => 2
+    => 2cl vermouth and 5cl whisky
+
+    >> white_russian = Cocktail.new :units => :oz, :vodka => 2, :kahlua => 1, :cream => 1.5
+    => 2oz vodka and 1oz Kahlúa and 1.5oz cream
+
+    >> martini * 2
+    => 11cl gin and 3cl vermouth
+
+    >> martini + manhattan
+    => 5.5cl gin and 3.5cl vermouth and 5cl whisky
+
+    >> martini + white_russian
+    ArgumentError: can't add 5.5cl gin and 1.5cl vermouth to 2oz vodka and 1oz Kahlúa and 1.5oz cream
+
+A real (one-dimensional) example:
+
+    class Money < VectorSpace::SimpleIndexedVector
+      indexed_by :currency, :default => Currency::GBP
+      has_dimension :cents,
+        :coerce   => lambda { |n| n.round }, # or just :coerce => :round if you have Symbol#to_proc
+        :describe => lambda { |currency, cents| "#{currency.symbol}#{cents / 100}.#{sprintf('%02d', cents % 100)}" }
+    end
+
+    >> a = Money.new(:currency => Currency::GBP, :cents => 9900)
+    => £99.00
+
+    >> b = Money.new(:currency => Currency::GBP, :cents => 1500)
+    => £15.00
+
+    >> a < b
+    => false
+
+    >> a > b
+    => true
+
+    >> a + b
+    => £114.00
+
+    >> c = Money.new(:currency => Currency::USD, :cents => 99)
+    => $0.99
+
+    >> a < c
+    => false
+
+    >> c < a
+    => false
+
+    >> a + c
+    ArgumentError: can't add $0.99 to £99.00

data/TODO

@@ -0,0 +1,3 @@
+* write documentation
+* release extracted specs to GitHub
+* support "dynamic dimensions" (arbitrary numbers of dimensions, created when used)

data/lib/vector_space.rb

@@ -0,0 +1,13 @@
+require 'forwardable'
+
+require 'vector_space/component_reflection'
+require 'vector_space/dimension_reflection'
+
+require 'vector_space/partial_order'
+require 'vector_space/arithmetic'
+require 'vector_space/vector_space'
+require 'vector_space/simple_vector'
+
+require 'vector_space/index_reflection'
+require 'vector_space/family'
+require 'vector_space/simple_indexed_vector'

data/lib/vector_space/arithmetic.rb

@@ -0,0 +1,33 @@
+module VectorSpace
+  # These operations depend only upon addition and multiplication of the underlying values, so work in a vector space
+  module Arithmetic
+    # Vector addition
+    def +(vector)
+      if compatible_with?(vector)
+        operate_on_values(vector) { |a, b| a + b }
+      else
+        raise ArgumentError, "can't add #{vector.inspect} to #{self.inspect}"
+      end
+    end
+
+    # Scalar multiplication
+    def *(n)
+      operate_on_values { |value| value * n }
+    end
+
+    # Additive inverse
+    def -@
+      operate_on_values { |value| -value }
+    end
+
+    # Vector subtraction (by addition)
+    def -(vector)
+      self + (-vector)
+    end
+
+    # Scalar division (by multiplication)
+    def /(n)
+      self * (1.0 / n)
+    end
+  end
+end

data/lib/vector_space/component_reflection.rb

@@ -0,0 +1,27 @@
+module VectorSpace
+  class ComponentReflection
+    def initialize(component, options = {})
+      @component, @options = component, options
+    end
+
+    def to_s
+      "#{component} component (#{default.class})"
+    end
+
+    attr_reader :component, :options
+
+    def getter
+      options[:getter] || component.to_sym
+    end
+
+    def value(value)
+      value ||= default
+
+      if options[:coerce]
+        options[:coerce].to_proc.call(value)
+      else
+        value
+      end
+    end
+  end
+end

data/lib/vector_space/dimension_reflection.rb

@@ -0,0 +1,11 @@
+module VectorSpace
+  class DimensionReflection < ComponentReflection
+    def zero
+      @options[:zero] || 0
+    end
+
+    def default
+      zero
+    end
+  end
+end

data/lib/vector_space/family.rb

@@ -0,0 +1,45 @@
+module VectorSpace
+  module Family
+    def self.included(base)
+      base.class_eval do
+        include VectorSpace
+        extend ClassMethods
+        include InstanceMethods
+      end
+    end
+
+    module ClassMethods
+      attr_reader :index
+
+      def indexed_by(index, options = {})
+        @index = index
+        (@component_reflections ||= {})[index] = IndexReflection.new(index, options)
+      end
+
+      def components
+        [index] + super
+      end
+
+      def zero(attributes = {})
+        new Hash[*([index, attributes[index] || reflect_on_component(index).default] + dimensions.map { |dimension| [dimension, reflect_on_component(dimension).zero] }).flatten]
+      end
+    end
+
+    module InstanceMethods
+      def self.included(base)
+        base.class_eval do
+          def_delegator :'self.class', :index
+        end
+      end
+
+      def compatible_with?(other)
+        super && project(index) == other.project(index)
+      end
+
+      private
+        def operate_on_values(*vectors, &block)
+          self.class.new Hash[*(map_components(index, *vectors) { |*values| values.inject { |a, b| a if a == b } } + map_components(dimensions, *vectors, &block)).flatten]
+        end
+    end
+  end
+end

data/lib/vector_space/index_reflection.rb

@@ -0,0 +1,7 @@
+module VectorSpace
+  class IndexReflection < ComponentReflection
+    def default
+      @options[:default]
+    end
+  end
+end

data/lib/vector_space/partial_order.rb

@@ -0,0 +1,16 @@
+module VectorSpace
+  module PartialOrder
+    # Ruby's Comparable isn't well-behaved for partial orders: its operations raise ArgumentError if #<=> returns nil.
+    # This module provides operations which simply return false when two values are incomparable.
+
+    [:<, :<=, :==, :>=, :>].each do |operation|
+      define_method operation do |other|
+        ((result = self <=> other) && result.send(operation, 0)) == true
+      end
+    end
+
+    def comparable_with?(other)
+      !(self <=> other).nil?
+    end
+  end
+end

data/lib/vector_space/simple_indexed_vector.rb

@@ -0,0 +1,30 @@
+module VectorSpace
+  class SimpleIndexedVector < SimpleVector
+    include Family
+
+    def initialize(attributes = {})
+      if index_value = attributes[index] || reflect_on_component(index).default
+        super attributes.merge(index => index_value)
+      else
+        raise ArgumentError, "must provide value for #{index} index or configure a default"
+      end
+    end
+
+    private
+      def describe_value(dimension)
+        if describe = reflect_on_component(dimension).options[:describe]
+          describe.to_proc.call(project(index), project(dimension))
+        else
+          super
+        end
+      end
+
+    class << self
+      def indexed_by(index, attributes = {})
+        define_method (reflection = super(index, attributes)).getter do
+          reflection.value(@attributes[index])
+        end
+      end
+    end
+  end
+end

data/lib/vector_space/simple_vector.rb

@@ -0,0 +1,70 @@
+module VectorSpace
+  class SimpleVector
+    include Enumerable
+    include VectorSpace
+    def_delegators :'self.class', :description_prefix, :description_suffix, :description_separator, :zero_description
+
+    def initialize(attributes = {})
+      @attributes = attributes
+    end
+
+    def to_s
+      if zero? && zero_description
+        zero_description
+      else
+        [
+          description_prefix,
+          dimensions.map { |dimension| describe_value(dimension) }.compact.join(description_separator),
+          description_suffix
+        ].join
+      end
+    end
+
+    def [](component)
+      project(component)
+    end
+
+    def each
+      dimensions.each do |dimension| yield [dimension, project(dimension)] end
+    end
+
+    private
+      def describe_value(dimension)
+        if describe = reflect_on_component(dimension).options[:describe]
+          describe.to_proc.call(project(dimension))
+        else
+          project(dimension)
+        end
+      end
+
+    class << self
+      attr_reader :description_prefix, :description_suffix, :zero_description
+
+      def has_dimension(dimension, attributes = {})
+        define_method (reflection = super(dimension, attributes)).getter do
+          reflection.value(@attributes[dimension])
+        end
+      end
+
+      def has_description_prefix(description_prefix)
+        @description_prefix = description_prefix
+      end
+
+      def has_description_suffix(description_suffix)
+        @description_suffix = description_suffix
+      end
+
+      def has_description_separator(description_separator)
+        @description_separator = description_separator
+      end
+
+      def has_zero_description(zero_description)
+        @zero_description = zero_description
+      end
+
+      def description_separator
+        @description_separator || ' and '
+      end
+    end
+  end
+end

data/lib/vector_space/vector_space.rb

@@ -0,0 +1,101 @@
+module VectorSpace
+  def self.included(base)
+    base.class_eval do
+      extend ClassMethods
+      include InstanceMethods
+    end
+  end
+
+  module ClassMethods
+    attr_reader :dimensions
+
+    def components
+      dimensions
+    end
+
+    def reflect_on_component(component)
+      @component_reflections[component]
+    end
+
+    def zero
+      new Hash[*dimensions.map { |dimension| [dimension, reflect_on_component(dimension).zero] }.flatten]
+    end
+
+    def order
+      @order || :product
+    end
+
+    private
+      def has_dimension(dimension, options = {})
+        (@dimensions ||= []) << dimension
+        (@component_reflections ||= {})[dimension] = DimensionReflection.new(dimension, options)
+      end
+
+      def has_order(order)
+        @order = order
+      end
+  end
+
+  module InstanceMethods
+    def self.included(base)
+      base.class_eval do
+        extend Forwardable
+        def_delegators :'self.class', :components, :dimensions, :order, :reflect_on_component
+
+        include PartialOrder
+        include Arithmetic
+      end
+    end
+
+    def project(component)
+      reflection = reflect_on_component(component)
+      reflection.value(send(reflection.getter))
+    end
+
+    def map_components(components, *vectors)
+      Array(components).map { |component| [component, yield(*([self] + vectors).map { |vector| vector.project(component) })] }
+    end
+
+    def map_values(components, *vectors, &block)
+      map_components(components, *vectors, &block).map { |component, value| value }
+    end
+
+    def zero?
+      map_values(dimensions) { |value| value.zero? }.all?
+    end
+
+    # Decides whether the receiver is compatible with some other object for general operations (e.g. arithmetic and comparison).
+    def compatible_with?(other)
+      other.class == self.class
+    end
+
+    # Compares the receiver against another object, returning -1, 0, +1 or nil depending on whether the receiver is less than,
+    # equal to, greater than, or incomparable with the other object.
+    # This works just like the #<=> expected by Comparable, but also returns nil iff the two objects are incomparable.
+    def <=>(other)
+      if compatible_with?(other)
+        comparisons = map_values(dimensions, other) { |a, b| a <=> b }
+
+        case order
+        when :product
+          comparisons.inject { |a, b| a + b if a && b && a * b >= 0 }
+        when :lexicographic
+          comparisons.inject { |a, b| a == 0 ? b : a }
+        end
+      end
+    end
+
+    def eql?(other)
+      map_values(dimensions, other) { |a, b| a.eql?(b) }.all?
+    end
+
+    def hash
+      map_values(dimensions) { |value| value }.hash
+    end
+
+    private
+      def operate_on_values(*vectors, &block)
+        self.class.new Hash[*map_components(dimensions, *vectors, &block).flatten]
+      end
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: vector_space
+version: !ruby/object:Gem::Version 
+  version: 0.1.2
+platform: ruby
+authors: 
+- Tom Stuart
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-23 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: 
+email: tom@experthuman.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/vector_space/arithmetic.rb
+- lib/vector_space/component_reflection.rb
+- lib/vector_space/dimension_reflection.rb
+- lib/vector_space/family.rb
+- lib/vector_space/index_reflection.rb
+- lib/vector_space/partial_order.rb
+- lib/vector_space/simple_indexed_vector.rb
+- lib/vector_space/simple_vector.rb
+- lib/vector_space/vector_space.rb
+- lib/vector_space.rb
+- LICENSE
+- README.markdown
+- TODO
+has_rdoc: true
+homepage: http://github.com/tomstuart/vector_space
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A Ruby library for treating multidimensional values as elements of a vector space
+test_files: []
+