interpolator 0.11 → 0.12

data/interpolator.rb

@@ -1,5 +1,37 @@
+# Copyright (c) 2009 Eric Todd Meyers
+# 
+# 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.
+
+
 module Interpolator
 
+# Table holds a series of independent and dependent values that can be interpolated or extrapolated.
+# The independent values are always floating points numbers. The dependent values can either be floating point
+# numbers or themselves Table instances. By nesting the Table in this way a Table of any dimension can be
+# created.
+#
+# Tables can be told to not extrapolate by setting .extrapolate=false
+# The interpolation method is controlled with .style = LINEAR,LAGRANGE2, or LAGRANGE3
+#
     class Table
     
        attr_reader :extrapolate,:style
@@ -8,9 +40,43 @@ module Interpolator
        LINEAR    = 1
        LAGRANGE2 = 2
        LAGRANGE3 = 3
-    
+
+# Tables are constructed from either a pair of Arrays or a single Hash.
+#     
+# The 2 argument constructor accepts and array of independents and an array of dependents. The
+# independent Array should be floating point values. The dependent Array can be either floating
+# point values or Tables (aka sub tables.) There is no limit to how deep a Table can be.
+#     
+# The single argument constructor is similar. The keys of the Hash are the independents. The values 
+# of the Hash are the dependent values, and can either be floating point numbers or Tables.
+#     
+# Examples
+# * simple univariant table
+#         
+#          t = Table.new [1.0,2.0],[3.0,4.0]
+#          and is equivalent to
+#          t = Table.new(1.0=>3.0,2.0=>4.0)
+#     
+# * bivariant table
+#
+#          t = Table.new([1.0,2.0],[Table.new([1.0,2.0],[3.0,4.0]),Table.new([2.0,3.0,5.0],[6.0,-1.0,7.0])])
+#         
+# * trivariant table
+#
+#          t = Table.new(
+#                    1=>Table.new(
+#                      1=>Table.new([1.0,2.0,3.0],[4.0,5.0,6.0]),
+#                      4=>Table.new([11.0,12.0,13.0],[14.0,15.0,16.0]),
+#                      5=>Table.new([11.0,12.0,13.0],[-14.0,-15.0,-16.0])),
+#                    2=>Table.new(
+#                      2=>Table.new([1.1,2.0,3.0],[4.0,5.0,6.0]),
+#                      5=>Table.new([11.0,12.5,13.0],[14.0,15.0,16.0]),
+#                      6.2=>Table.new([1.0,12.0],[-14.0,-16.0])),
+#                    8=>Table.new(
+#                      1=>Table.new([1.0,2.0,3.0],[4.0,5.0,6.0]),
+#                      5=>Table.new([11.0,12.0,13.0],[-14.0,-15.0,-16.0]))
+#                  )
        def initialize (*args)
-    
            if (args.size==2) then
                raise "duel argument table constructor must be 2 Arrays" unless args[0].kind_of? Array
                raise "duel argument table constructor must be 2 Arrays" unless args[1].kind_of? Array
@@ -35,20 +101,18 @@ module Interpolator
            @extrapolate = true
            @style       = LINEAR
        end
-
-# replace later with a high speed bisection
-
-       def bracket (x)
-           ileft=0
-           for i in (0..@inds.size-2) do
-              ileft=i
-              if ( (x >= @inds[i]) && (x < @inds[i+1]) ) then
-                  break
-              end
-           end
-           ileft
-       end
-
+# Interpolate or extrapolate the Table. Pass as many arguments as there are independent dimensions to the table (univariant a
+# single argument, bivariant 2 arguments, etc.)
+#   
+# Examples
+# * univariant
+#     t = Table.new [1.0,2.0],[3.0,4.0]
+#     t.read(1.5)  returns 3.5
+# * bivariant  
+#     t = Table.new([1.0,2.0],[Table.new([1.0,2.0],[3.0,4.0]),Table.new([2.0,3.0,5.0],[6.0,-1.0,7.0])])
+#     t.read(2.0,3.0) returns -1.0
+#     t.read(1.7,2.0) returns 5.4
+#
        def read(*args)
     
           raise "table requires at least 2 points for linear interpolation" if (@style == LINEAR && @inds.size<2)
@@ -163,9 +227,27 @@ module Interpolator
           ans
        end
        
+#
+#  Same as read
+#
        def interpolate(*args)
           read(*args)
-       end   
+       end  
+       
+       protected
+
+# replace later with a high speed bisection
+
+       def bracket (x)
+           ileft=0
+           for i in (0..@inds.size-2) do
+              ileft=i
+              if ( (x >= @inds[i]) && (x < @inds[i+1]) ) then
+                  break
+              end
+           end
+           ileft
+       end
        
        def linear (x,x1,x2,y1,y2)
          r = (y2-y1) / (x2-x1) * (x-x1) + y1
@@ -205,7 +287,9 @@ module Interpolator
 if __FILE__ == $0 then
 
 require 'test/unit'
-
+#
+# Unit test for Table class
+#
     class TC_LookupTest < Test::Unit::TestCase
       def setup
        @t1 = Table.new [1.0,2.0],[3.0,4.0]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: interpolator
 version: !ruby/object:Gem::Version 
-  version: "0.11"
+  version: "0.12"
 platform: ruby
 authors: 
 - Eric T Meyers
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-02 00:00:00 -04:00
+date: 2009-08-03 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -51,6 +51,6 @@ rubyforge_project: interpolator
 rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: Module Interpolation proves a table class that supports n-dimensional numerical table construction, interpolation and extrapolation. Includes linear, 2nd order and 3rd order la grange techniques.
+summary: Module Interpolator proves a table class that supports n-dimensional numerical table construction, interpolation and extrapolation. Includes linear, 2nd order and 3rd order la grange techniques.
 test_files: []