linmeric 0.1.0 → 0.2.0

data/lib/linmeric/Integrators.rb

@@ -1,76 +1,122 @@
 #! /usr/bin/env ruby
 
+##
+# This module provides some method to integrate a function
+# 
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 module Integrators
+
+   # Implementation of trapezes method
+   #
+   # * **argument**: left range value
+   # * **argument**: right range value
+   # * **argument**: number of integration points
+   # * **returns**: result of the operation (Numeric)
    def self.trapezi(a,b,n)
-     #Implementazione
-       h=(b-a)/n.to_f
-       int_parz=0
+       h = (b - a) / n.to_f
+       int_parz = 0
        for i in 0...n
-          #calcolo primo addendo =f(x_i)
-          f1=yield(a+i*h)  #chiama il blocco definito sotto
-          #calcolo secondo addendo = f(X_{i+1})
-          f2=yield(a+(i+1)*h)
-          #calcolo area trapezio
-          trap=0.5*h*(f1+f2)
-          int_parz+=trap
+          # Calculating first addend = f(x_i)
+          f1 = yield(a + i * h)
+          # calculating second addend = f(X_{i+1})
+          f2 = yield(a + (i + 1) * h)
+          # Calculating trapeze area
+          trap = 0.5 * h * (f1 + f2)
+          int_parz += trap
        end
        return int_parz
    end
    
+   # Implementation of midpoint method
+   #
+   # * **argument**: left range value
+   # * **argument**: right range value
+   # * **argument**: number of integration points
+   # * **returns**: result of the operation (Numeric)
    def self.midpoint(a,b,n)
-     parz=0
-     h=(b-a)/n.to_f
+     parz = 0
+     h = (b - a) / n.to_f
      for i in 0...n
-       f1 = yield(a+(i+0.5)*h)
-       parz+=f1
+       f1 = yield(a + (i + 0.5) * h)
+       parz += f1
      end
-     return h*parz
+     return h * parz
    end
    
+   # Implementation of Simpson's method
+   #
+   # * **argument**: left range value
+   # * **argument**: right range value
+   # * **argument**: number of integration points
+   # * **returns**: result of the operation (Numeric)
    def self.simpson(a,b,n)
-     hs=(b-a)/(n*2.0)
-     intSA =0
-     intSB =0
+     hs = (b - a) / (n * 2.0)
+     intSA = 0
+     intSB = 0
      for i in 1..n-1
-       xa = a+ (2*i)*hs
-       intSA+=yield(xa)
+       xa = a + (2 * i) * hs
+       intSA += yield(xa)
      end
   
      for i in 0..n-1
-       xb=a+ (2*i+1)*hs
-       intSB+=yield(xb)
+       xb = a + (2 * i + 1) * hs
+       intSB += yield(xb)
      end
-     fa=yield(a)
-     fb=yield(b)
-     intS=hs/3.0*(fa+fb+2*intSA+4*intSB)
+     fa = yield(a)
+     fb = yield(b)
+     intS = hs / 3.0 * (fa + fb + 2 * intSA + 4 * intSB)
      return intS
    end
    
+   # Implementation of left rectangles method
+   #
+   # * **argument**: left range value
+   # * **argument**: right range value
+   # * **argument**: number of integration points
+   # * **returns**: result of the operation (Numeric)
    def self.rettsx(a,b,n)
-     h=(b-a)/n.to_f
-     area=0
+     h = (b - a) / n.to_f
+     area = 0
      for i in 0..n-1
-       area+=yield(a+(h*i))*h
+       area += yield(a + (h * i)) * h
      end
      return area
    end
    
+   # Implementation of right rectangles method
+   #
+   # * **argument**: left range value
+   # * **argument**: right range value
+   # * **argument**: number of integration points
+   # * **returns**: result of the operation (Numeric)
    def self.rettdx(a,b,n)
-     h=(b-a)/n.to_f
-     area=0
+     h = (b - a) / n.to_f
+     area = 0
      for i in 1..n
-       area+=yield(a+(h*i))*h
+       area += yield(a + (h * i)) * h
      end
      return area
    end
    
+   # Implementation of Boole's method
+   #
+   # * **argument**: left range value
+   # * **argument**: right range value
+   # * **argument**: number of integration points
+   # * **returns**: result of the operation (Numeric)
    def self.boole(a,b,n)
-     h=(b-a)/(4*n.to_f)
-     parz=0
+     h = (b - a) / (4 * n.to_f)
+     part = 0
      for i in 0..n-1
-       parz+=7*yield(a+(h*4*i)) +32*yield(a+(h*(4*i+1))) +12*yield(a+(h*(4*i+2))) +32*yield(a+(h*(4*i+3)))+7*yield(a+(h*(4*i+4)))
+       part +=  7 * yield(a + (h * 4 * i)) +
+               32 * yield(a + (h * (4 * i + 1))) +
+               12 * yield(a + (h * (4 * i + 2))) +
+               32 * yield(a + (h * (4 * i + 3))) +
+                7 * yield(a + (h * (4 * i + 4)))
      end
-     return (2*h)/45.0*parz
+     return (2 * h) / 45.0 * part
    end
   
 end

data/lib/linmeric/LU.rb

@@ -1,9 +1,21 @@
 #! /usr/bin/env ruby
 require_relative 'CnGal_Matrix_class'
 
+##
+# This module provides some method to perform LU factorization
+# on squared matrices. 
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 module LU
   
-  # swapping two rows (pivoting)
+  # Swaps two rows of a matrix (pivoting)
+  #
+  # * **argument**: matrix the rows must be swapped on
+  # * **argument**: first row
+  # * **argument**: second row
+  # * **returns**: new matrix with swapped rows
   def self.swap(mx,r1,r2)
     for i in 0...mx.getCls do
       mx[r1,i],mx[r2,i] = mx[r2,i],mx[r1,i] 
@@ -11,19 +23,27 @@ module LU
     return mx
   end
   
+  # Returns the `L` matrix
   def self.L()
     return @L
   end
   
+  # Returns the `U` matrix
   def self.U()
     return @U
   end
   
+  # Sets to nil @L and @U variables
   def self.reset
     @L = nil
     @U = nil
   end
   
+  # Performs LU factorization calculating L and U matrices
+  #
+  # * **argument**: squared matrix to factorize
+  # * **argument**: n x 1 matrix of known values of the linear system
+  # * **returns**: same as LU.solve 
   def self.factorize(mx,sol)
     [mx,sol].each do |vec|
       return nil unless vec.is_a? Matrix
@@ -33,13 +53,11 @@ module LU
     return nil unless mx.is_squared?
     return nil unless mx.getRws == sol.getRws
     rows = mx.getRws
-    #sol.show;gets
     for k in 0...rows do
       column = mx[k...mx.getRws,k].export.map! { |val| val.abs}
       max_index = column.index(column.max)
       mx = self.swap(mx,k,k + max_index) unless k == max_index + k
       sol = self.swap(sol,0,k + max_index) unless k == max_index + k
-      #mx.show;gets
       for i in (k+1)...mx.getRws do
         alpha = (mx[k,k] != 0) ? (mx[i,k] / mx[k,k].to_f) : 0
         mx[i,k] = alpha
@@ -48,12 +66,15 @@ module LU
         end
       end
     end
-    #return mx
-    @L = Matrix.identity(mx.getRws) + Matrix.new(mx.getRws,mx.getCls){ |i,j| (i > j) ? mx[i,j] : 0} #
+    @L = Matrix.identity(mx.getRws) + Matrix.new(mx.getRws,mx.getCls){ |i,j| (i > j) ? mx[i,j] : 0}
     @U = Matrix.new(mx.getRws,mx.getCls){ |i,j| (i <= j) ? mx[i,j] : 0}
     return solve(sol)
   end
   
+  # Finds the solutions of the linear system
+  #
+  # * **argument**: n x 1 matrix of known values of the linear system
+  # * **returns**: n x 1 matrix with the solutions of the system
   def self.solve(sol)
     z = Matrix.new(sol.getRws,1) {0}
     x = Matrix.new(sol.getRws,1) {0}

data/lib/linmeric/Lexer.rb

@@ -4,8 +4,20 @@ require_relative 'CnGal_tools.rb'
 require_relative 'CnGal_new_classes.rb'
 require_relative 'Token.rb'
 
+##
+# This simple Lexer tokenizes the input stream of commands for the sintax analyzer
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 class Lexer
 
+  # Tokenizes the input stream according to particular tokenizer symbols
+  # which determine the end of an element.Eg: a+3 => `+` determines the end of variable `a`
+  # and the beginning of another element (`3`)
+  #
+  # * **argument**: string to tokenize
+  # * **returns**: array of tokens (see: Token ) 
   def tokenize(expr)
     token = []
     temp = ""
@@ -15,7 +27,6 @@ class Lexer
     gen_exp = []
     tokenizers = Tool.operators + [" ","(",")",":",'"',"~"]
     while i < expr.size
-     # puts expr[i];gets
       if  (tokenizers.include? expr[i]) then
         temp += ':' if expr[i] == ':'
         token << Token.new(temp, pos) unless temp == ""
@@ -38,6 +49,13 @@ class Lexer
    
  private
  
+  # Reads all the content between quotes so that it can be classified as string
+  #
+  # * **argument**: string to extract the 'string' element
+  # * **returns**: array with three elements:
+  #   * 'string' element
+  #   * counter `i`
+  #   * boleean value to tell whether final quotes have been found (+true+ = found, +false+ = not found) 
   def extract_gen_exp(string)
     i = 0
     gen_exp = ""

data/lib/linmeric/Listener.rb

@@ -5,6 +5,13 @@ require_relative 'CnGal_new_classes.rb'
 require_relative 'Archive.rb'
 require_relative 'CnGal_tools.rb'
 
+##
+# This class works on the command line interface to allow the user to move
+# the cursor, modify the input string in each point and retrieve commands from the history
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 class Listener
   CSI = "\e["
   LETTERS = Tool.letters
@@ -12,6 +19,7 @@ class Listener
   SPECIAL_CHARS = "|!$%&/()=?'^~+-*<>-_,:;. " + '"'
   CHARS = LETTERS + LETTERS.upcase + SPECIAL_CHARS + NUMBERS
   
+  # Creates the main variables
   def initialize
     @final_string = ""
     @i = 0
@@ -20,12 +28,14 @@ class Listener
     @list = Archive.new
   end
   
+  # reinitializates three main variables
   def reset
     @final_string = ""
     @i = 0
     @exit = false
   end
   
+  # Reads a single char from the command line
   def read_char
     STDIN.echo = false
     STDIN.raw!
@@ -42,12 +52,14 @@ class Listener
     return input
   end
   
-  def show_single_key()
+  # according to the collected key decides what to do: moving the cursor,
+  # surfing the history, or simply store chars in a variable
+  def collect_single_key()
     c = read_char
     case c
-    
-      when "\t"
-        # "TAB"
+      
+      # "TAB"
+      when "\t"        
       
       # "RETURN"
       when "\r"
@@ -139,14 +151,19 @@ class Listener
     end
   end
   
+  # main function that can be used. It returns the stream the user wrote on the command
+  # line after they pressed return.
   def gets()
-    show_single_key while(!@exit)
+    collect_single_key while(!@exit)
     @list.store(@final_string)
     return @final_string.clone
+  ensure
+    reset
   end
   
  private
  
+  # Clears the current line (deletes the typed input)
   def clear_line
     if @i < @final_string.size
       for i in @i...@final_string.size do
@@ -162,6 +179,9 @@ class Listener
     @i = 0
   end
   
+  # Moves the cursor backward of the number of specified position
+  #
+  # * **argument**: number of position the cursor must be moved backward
   def cursor_to(pos)
     return nil if pos < 0
     for i in pos..@final_string.size

data/lib/linmeric/Parser.rb

@@ -2,17 +2,35 @@
 
 require_relative 'CnGal_new_classes.rb'
 
+##
+# This is a stack-based parser that returns a tree in array format.
+# Sub arrays are operations with higher priority. Operators are converted
+# to symbol. It must be associated to Scp.
+# Eg: 3 + 4 * 9 => `[3, :+, [4, :*, 9]]`
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 class Parser
+
+  # Initialize two new variables: a counter and a boolean one
+  # to report errors and stop the parser
   def initialize()
     @d = 0
     @error = false
   end
   
+  # Re initializes the counter and the boolean variable
   def reset()
     @d = 0
     @error = false
   end
-
+  
+  # Main function that parses the string
+  #
+  # * **argument**: string to be parsed; the string must be the
+  # output of scopify (see: Scp )
+  # * **returns**: abstract tree array
   def parse(expr)
     array = Array.new
     until @d == expr.length
@@ -105,6 +123,10 @@ class Parser
     return array
   end
   
+  # Extracts the content between quotes (it must not be parsed)
+  #
+  # * **argument**: string to extract the sub-string from
+  # * **returns**: sub-string
   def extract(expr)
     ext = '"'
     while expr[@d] != '"' do

data/lib/linmeric/Scopify.rb

@@ -1,25 +1,31 @@
 #! /usr/bin/env ruby
 require_relative 'CnGal_new_classes.rb'
-# per poter computare un'espressione in formato stringa
-# devo prima creare un albero con un parsing.
-# per poter fare queste operazioni necessito di racchiudere
-# le operazioni con priorità maggiore tra parentesi; es:
-# 1+2*3   => 1+(2*3)
-# 1+2*9^4 => 1+(2*(9^(4))) N.B. anche l'argomento di una potenza
-# deve essere tra parentesi.
-# valgono le stesse regole per le parti di espressione tra parentesi; es:
-# 3*(1+2/3) => (3*(1+(2/3)))
-# non importa se ci sono parentesi inutili in più, basta che
-# siano coerenti.
-# se c'è un uguale le parti a sx e a dx devono essere chiuse tra 
-# parentesi; es: a=b*c => (a)=((b*c)) 
-# per quanto riguarda le parole chiavi, la parola chive e il
-# suo argomento vengono messi tra parentesi; es t: a => (t: a)
+
+##
+# This class manipulates a string representing an algebric expression
+# underlining the higher priority operations putting them between brackets.
+# Scp prepares strings to be parsed. It must work associated with Sizer.
+# These rules are followed:
+# * ... = ...             => (...) = (...) (same with `>`)
+# * a + b * c             => a + (b * c) (same with `/`)
+# * a ^ b                 => (a ^ (b))
+# * <keyword>: <argument> => (<keyword>: <argument>)
+#
+#
+# Author:: Massimiliano Dal Mas (mailto:max.codeware@gmail.com)
+# License:: Distributed under MIT license
 class Scp
+
+  # Initializes a new counter
   def initialize
     @i = 0 
   end
 
+  # Main function that analyzes the string and puts the brackets where it
+  # is necessary.
+  #
+  # * **argument**: string to be manipulated
+  # * **returns**: manipulated string
   def scopify(expr)
     expr = insert_b(expr)
     @i         = 0
@@ -34,15 +40,15 @@ class Scp
     state      = 0
     while @i < expr.size
       case expr[@i]
-        # ogni parte racchiusa tra parentesi viene interpretata come
-        # una sotto espressione, e la sistemo a parte con una ricorsione
+        # Each part between brackets is seen as a subexpression
+        # and it is analyzed recoursively.
         when '('
           scp = Scp.new
           n_expr += expr[@i] + scp.scopify(extract(expr[(@i + 1)...expr.length])) 
           @i += scp.count  
         when /[\*\/]/
-          # se ho parentesi aperte da operazioni con priorità superiore
-          # le chiudo
+          # If there are open brackets of higher opertions
+          # it closes them
           if open_m_b > 0
             n_expr += ')' * open_m_b
             last_empty = last_e.pop
@@ -54,8 +60,8 @@ class Scp
             open_p_b = 0
             state = (stack.size > 0 ? stack.pop : 0)
           end
-          # se non ho già in corso un inserimento di parentesi per
-          # moltiplicazione, le aggiungo
+          # If it is not still analyzing a multiplication, it adds the brackets 
+          # following the rules
           unless state == 1
             n_expr.insert last_empty, '(' 
             state = 1
@@ -64,8 +70,8 @@ class Scp
           n_expr += expr[@i]
           last_empty = n_expr.size # + 1
         when /[\+\-]/
-          # chiudo le parentesi delle operazioni con priorità superiore
-          # faccio lo shift di last_empty
+          # higher priority operation brackets are closed
+          # last_empty is shifted
           n_expr += ')' * open_p_b if open_p_b > 0
           n_expr += ')' * open_b if open_b > 0
           state = 0
@@ -74,8 +80,7 @@ class Scp
           n_expr += expr[@i]
           last_empty = n_expr.size
         when /\^/
-          # comincio a mettere tra parentesi l'operazione e il suo esponente
-          
+          # It begins to put between brackets the operation and its exponent
           if open_m_b > 0 then
             n_expr += ")" * open_m_b
             last_empty = last_e.pop
@@ -89,13 +94,15 @@ class Scp
           stack.push state unless state == 2
           state = 2
         when /\=/
-          # metto tra parentesi la parte a sx dell'uguale e comincio a
-          # mettere tra parentesi quella a dx
-          # chiudendo eventuali parentesi di potenza o di prodotto
+          # The expression at the left of `=` is put between brackets
+          # and a bracket at the right is opened
+          # It closes previously opened brackets
           n_expr += ')' * open_p_b if open_p_b > 0
-          n_expr += ')' * open_b if open_b > 0
-          open_b = 0
+          n_expr += ')' * open_b   if open_b > 0
+          n_expr += ')' * open_m_b if open_m_b >0
+          open_b   = 0
           open_p_b = 0
+          open_m_b = 0
           n_expr = '(' + n_expr + ')' + expr[@i]
           n_expr += '('
           last_empty = n_expr.size
@@ -135,7 +142,7 @@ class Scp
       end
       @i += 1
     end
-    # chiudo parentesi aperte, e quella dell'uguale se stata aperta
+    # it closes all the opened brackets
     n_expr += ')' * open_m_b if open_m_b > 0
     n_expr += ')' * open_p_b if open_p_b > 0
     n_expr += ')' * open_b if open_b > 0
@@ -143,10 +150,16 @@ class Scp
     return n_expr
   end
   
+  # Returns the current value of the counter
   def count()
     return @i
   end
   
+  # Inserts a couple of brackets `()` before non-binary sum and diff.
+  # operators
+  #
+  # * **argument**: string to be checked and manipulated
+  # * **returns**: manipulated string
   def insert_b(expr)
     @i = 0
     string = false
@@ -162,6 +175,10 @@ class Scp
   
   private
   
+  # Extracts the subexpression between brackets
+  #
+  # * **argument**: string to extract the sub expression from
+  # * **returns**: subexpression (string)
   def extract(expr)
     n_expr = ""
     i = 0
@@ -175,6 +192,10 @@ class Scp
     return n_expr + ')'
   end
   
+  # Extracts the content between quotes
+  #
+  # * **argument**: string to extract the content from
+  # * **returns**: content (substring)
   def discard(expr)
     extract = ""
     while expr[@i] != '"' do