finitefield 0.0.1 → 0.1.0

data/README.txt

@@ -8,4 +8,9 @@ supported.
 The initial release of this library is limited in scope to only supporting
 fields of the form 2^n.
 
-
+Examples illustrating how to use the field are given in the examples directory.
+Currently the following examples are provided:
+* logTables.rb:
+    - log and antilog table generation given a field polynomial and generator.
+* raid6.rb:
+    - RAID6 Q block generation using finite fields.

data/examples/exampleUtils.rb

@@ -0,0 +1,16 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+# = exampleUtils.rb - Utility methods used by the other examples.
+#
+# Copyright (C) 2008  Stephen Doyle
+#
+
+# Utility method to print a nicely formatted 16xn table of hex values
+def printTable(table)
+  (0...table.length).each do |i|
+    printf("%02x ", table[i])
+    if i!=0 and i%16==15
+      puts ''
+    end
+  end
+end

data/examples/logTables.rb

@@ -0,0 +1,88 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+# = logTables.rb - Generate the anti-log and log tables for a finite field.
+#
+# Copyright (C) 2008  Stephen Doyle
+#
+# This example illustrates using the finitefield library to generate the
+# anti-log and log tables for a finite field for a given field polynomial 
+# and generator.
+#
+# The anti-log table for a finite field is constructed using a generator
+# whose successive powers g^n for the range n[0, 255] produce all the 
+# in the field without repeating any element.
+#
+# If the anti-log and log tables are available for a finite field, 
+# multiplication can be performed very quickly using these tables, e.g.
+#   mult(a, b) = anti_log( [log(a) + log(b)] % 0xFF )
+# where + is normal addition, i.e. not addition within the finite field.
+#
+
+require 'finitefield'
+require 'exampleUtils'
+
+# Compute the inverse or anti log table for a given field polynomial and generator.
+# Note that the last value of the ilogTable is invalid and present in this example
+# as a placeholder to produce a nicely dimensioned array.
+def getILogTable(poly, generator)
+  field = FiniteField.new(8, poly)
+  ilogTable = [1]
+
+  1.upto(0xFF) do |i|
+    ilogTable[i] = field.multiply(ilogTable[i-1], generator)
+  end
+  return ilogTable
+end
+
+# Compute the log log table for a given field polynomial and generator.
+def getLogTable(poly, generator)
+  # The log table is most easily generated from the inverse log table.
+  # Note that the last element in the inverse log table is invalid and so
+  # should be discarded to avoid introducing errors into the log table
+  # generation.
+  ilogTable = getILogTable(poly, generator)[0...-1]
+  tmp = {}
+  ilogTable.each_with_index { |value, index| tmp[value] = index }
+  logTable = [0] + tmp.sort.collect { |x| x[1]}
+  return logTable
+end
+
+
+# Generate and print the anti-log and log tables for two well known fields ...
+# ... the 0x11D field is the default polynomial used for the GF(2^8)
+# computations used in RAID 6 for the generation of the Q parity block.
+puts "Inverse log table for polynomial 0x11D: "
+ilogTable = getILogTable(0x11D, 2)
+printTable(ilogTable)
+puts ''
+
+puts "Log table for polynomial 0x11D: "
+logTable = getLogTable(0x11D, 2)
+printTable(logTable)
+puts ''
+
+# ... the 0x11B polynomial is the polynomial used in AES computations.
+# See: http://www.cs.utsa.edu/~wagner/laws/FFM.html for further details.
+puts "Inverse log table for polynomial 0x11b:"
+ilogTable = getILogTable(0x11b, 3)
+printTable(ilogTable)
+puts ''
+
+puts "Log table for polynomial 0x11b: "
+logTable = getLogTable(0x11b, 3)
+printTable(logTable)
+puts ''
+
+# Demonstrate multiplication using the tables.
+a = 0x12
+b = 0x34
+
+field = FiniteField.new(8, 0x11D)
+r1 = field.multiply(a, b)
+
+ilogTable = getILogTable(0x11D, 2)
+logTable = getLogTable(0x11D, 2)
+r2 = ilogTable[ (logTable[a] + logTable[b]) % 0xFF ]
+
+puts "Result using FiniteField.multiply(): #{r1}"
+puts "Result using log tables: #{r2}"

data/examples/raid6.rb

@@ -0,0 +1,82 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+# = raid6.rb - Generate the Q parity block for a RAID 6 array.
+#
+# Copyright (C) 2008  Stephen Doyle
+#
+# This example illustrates using the finitefield library in the context
+# of RAID 6 to generate the Q parity block. 
+#
+# == Background
+# RAID 6 provides protection against double disk failures in an array of 
+# disks by using two disks in the array to hold parity information. The
+# first parity block is known as the P block and generated by taking an 
+# XOR of the data blocks in the disk array (D0 + D1 + ... Dn). This is 
+# equivalent to addition over a finite field of the form F(2^8). 
+#
+# The second parity block, aka the Q block, in a RAID 6 array is generated 
+# by multiplying each byte of the data blocks with a coefficient which is 
+# slected based upon the position of that disk in the array. The 
+# multiplication here is multiplication over a finite field of the form 
+# F(2^8) and the coefficients are taken from the anti-log table from the 
+# same field. The default RAID 6 polynimial is 0x11D.
+# 
+# == What's covered in the example?
+# This example illustrates the computation of both the P and Q blocks for
+# a sample RAID 6 array using a stripe size of 512 bytes. 
+#
+
+require 'finitefield'
+require 'exampleUtils'
+
+class Raid6
+
+  # Create a field of GF(2^n) using the specified generator polynomial
+  def initialize(polynomial)
+    @field = FiniteField.new(8, polynomial)
+  end
+
+  def getPBlock(dataBlocks)
+    pBlock = [0] * dataBlocks[0].length
+    dataBlocks.each do |blk| 
+      (0...blk.length).each { |byteIdx| pBlock[byteIdx] ^= blk[byteIdx] }
+    end
+    return pBlock
+  end
+  
+  def getQBlock(dataBlocks, coefficients)
+    qBlock = [0] * dataBlocks[0].length
+    dataBlocks.each_with_index do |blk, blkIdx|
+      (0...blk.length).each do |byteIdx| 
+        qBlock[byteIdx] ^= @field.multiply(blk[byteIdx], coefficients[blkIdx])
+      end
+    end
+    return qBlock
+  end
+end
+
+# See logTables.rb for futher details.
+def getILogTable(poly, generator)
+  field = FiniteField.new(8, poly)
+  ilogTable = [1]
+
+  1.upto(0xFF) do |i|
+    ilogTable[i] = field.multiply(ilogTable[i-1], generator)
+  end
+  return ilogTable
+end
+
+# Sample data
+data = []
+data[0] = [1]*512
+data[1] = [2]*512
+data[2] = [4]*512
+data[3] = [5]*512
+data[4] = [6]*512
+data[5] = [9]*512
+
+# Generate the blocks
+raid = Raid6.new(0x11d)
+coefficients = getILogTable(0x11d, 2)
+pBlk = raid.getPBlock(data)
+qBlk = raid.getQBlock(data, coefficients)

data/lib/finitefield.rb

@@ -1,9 +1,38 @@
-
-# Finite fields of characteristic 2
+# = finitefield.rb - Finite Field Arithmetic
+#
+# Copyright (C) 2008  Stephen Doyle
+#
+# == Features
+# finitefield.rb currently supports arithmetic in finite fields of characteristic 2.
+#
+# The following operations are supported:
+# * Addition
+# * Subtraction
+# * Multiplication
+# * Division
+# * Inverse
+# * Reduction
+# * Binary multiplication
+# * Binary division
+#
+# == Example
+#
+#  # Create a field
+#  field = FiniteField.new(8, 0x169)  # <== F(2^8) with polynomial: 0x169
+#  # Addition
+#  result = field.add(7, 8)
+#  # Subtraction
+#  result = field.subtract(8, 5)
+#  # Multiplication
+#  result = field.multiply(9, 87)
+#  # Division
+#  result = field.divide(87, 9)   # <==  result = 87/9
+#  # Inverse
+#  result = field.inverse(31)
+#
 
 class FiniteField
   attr_reader :polynomial
-  attr_reader :p
   
   # Create a field of GF(2^n) using the specified generator polynomial
   def initialize(n, polynomial)
@@ -50,7 +79,7 @@ class FiniteField
     return result
   end
   
-  # Reduce the input value by modulo with the generator polynomial
+  # Reduce the input value by modulo with the generator polynomial, i.e. result = a % polynomial.
   def reduce(a)
     result = 0
     i = degree(a)
@@ -80,28 +109,27 @@ class FiniteField
     auxillary[2] = 1
     i = 2
     
-#    puts "#{remainder[i].to_s(base=16)} #{quotient[i].to_s(base=16)} #{auxillary[i].to_s(base=16)}"
-
     while(remainder[i] > 1)
       i += 1
       result = binary_div(remainder[i-2], remainder[i-1])
       remainder[i] = result[1]
       quotient[i] = result[0]
       auxillary[i] = binary_mul(quotient[i], auxillary[i-1]) ^ auxillary[i-2]
-#      puts "#{remainder[i].to_s(base=16)} #{quotient[i].to_s(base=16)} #{auxillary[i].to_s(base=16)}"
     end
     
     return auxillary[i]
   end
   
-  # Division of two field elements (rhs/lhs). This is the same as
-  # rhs * lhs^-1 i.e. multiply(rhs, inverse(lhs))
+  # Division of two field elements (lhs/rhs). This is the same as
+  # lhs * rhs^-1 i.e. multiply(lhs, inverse(rhs))
   def divide(lhs, rhs)
     multiply(lhs, inverse(rhs))
   end
 
   # Find the degree of the polynomial representing the input field
   # element v.  This takes O(degree(v)) operations. 
+  #
+  # Example: degree(0x141) = 8  ==> 0x141 = x^8 + x^6 + 1
   def degree(v)
     if v != 0
       result = -1
@@ -114,7 +142,7 @@ class FiniteField
     return 0
   end
   
-  # Binary multiplication. Or more explicitly - multiplication over a binary field
+  # Binary multiplication. Or more explicitly - multiplication over a binary field.
   def binary_mul(lhs, rhs)
     result = 0
     a = [degree(lhs), degree(rhs)].max
@@ -127,7 +155,7 @@ class FiniteField
     return result
   end
 
-  # Binary division. Or more explicitly - division over a binary field
+  # Binary division. Or more explicitly - division over a binary field.
   def binary_div(lhs, rhs)
     q = 0
     r = lhs
@@ -145,3 +173,4 @@ class FiniteField
   end
 
 end
+

data/test/tc_basic.rb

@@ -1,5 +1,7 @@
 $:.unshift File.join(File.dirname(__FILE__), "..", "lib")
 
+# Copyright (C) 2008  Stephen Doyle
+
 require 'test/unit'
 require 'finitefield'
 

data/test/tc_gf2.rb

@@ -1,5 +1,7 @@
 $:.unshift File.join(File.dirname(__FILE__), "..", "lib")
 
+# Copyright (C) 2008  Stephen Doyle
+
 require 'test/unit'
 require 'finitefield'
 

data/test/ts_finitefield.rb

@@ -1,5 +1,7 @@
 $:.unshift File.join(File.dirname(__FILE__), "..", "lib")
 
+# Copyright (C) 2008  Stephen Doyle
+
 require 'test/unit'
 require 'tc_basic'
 require 'tc_gf2'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: finitefield
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors: 
 - Stephen Doyle
@@ -9,12 +9,12 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-10-24 00:00:00 +01:00
+date: 2008-12-22 00:00:00 +00:00
 default_executable: 
 dependencies: []
 
 description: Finite Field implementation in Ruby.
-email: stephendoyle75@gmail.com
+email: 
 executables: []
 
 extensions: []
@@ -28,13 +28,18 @@ files:
 - test/ts_finitefield.rb
 - test/tc_basic.rb
 - test/tc_gf2.rb
-has_rdoc: false
+- examples/exampleUtils.rb
+- examples/logTables.rb
+- examples/raid6.rb
+has_rdoc: true
 homepage: http://finitefield.rubyforge.org/
 post_install_message: 
-rdoc_options: []
-
+rdoc_options: 
+- --title
+- FiniteField Documentation
 require_paths: 
 - lib
+- lib
 required_ruby_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
@@ -49,10 +54,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   version: 
 requirements: []
 
-rubyforge_project: 
+rubyforge_project: finitefield
 rubygems_version: 1.0.1
 signing_key: 
 specification_version: 2
 summary: Finite Field implementation in Ruby.
-test_files: []
-
+test_files: 
+- test/ts_finitefield.rb