ragni-cas 0.1.7 → 0.1.8

data/lib/op.rb

@@ -11,6 +11,14 @@ module CAS
   class Op
     attr_reader :x
 
+    # Initialize a new empty operation container. This is a virtual
+    # class and the other must inherit from this basic container.
+    # Some methods raise a `CAS::CASError` if called.
+    # The input element is a Numric, to create a constant.
+    # `CAS::Op` specifies operations with a single variable
+    #
+    # <- `Numeric` to be converted in `CAS::Constant` or `CAS::Op` child operation
+    # -> `CAS::Op` instance
     def initialize(x)
       if x.is_a? Numeric
         case x
@@ -22,61 +30,149 @@ module CAS
           x = CAS.const x
         end
       end
+      CAS::Help.assert(x, CAS::Op)
+
       @x = x
     end
 
+    # Return the dependencies of the operation. Requires a `CAS::Variable`
+    # and it is one of the recursve method (implicit tree resolution)
+    #
+    # <- `CAS::Variable` instance
+    # -> `TrueClass` if depends, `FalseClass` if not
     def depend?(v)
+      CAS::Help.assert(v, CAS::Variable)
+
       @x.depend? v
     end
 
+    # Return the derivative of the operation using the chain rule
+    # The input is a `CAS::Op` because it can handle derivatives
+    # with respect to functions. E.g.:
+    #
+    # ```
+    #  f(x) = (ln(x))**2
+    #  g(x) = ln(x)
+    #
+    #  d f(x)
+    #  ------ = 2 ln(x)
+    #  d g(x)
+    # ```
+    #
+    # <- `CAS::Op` object of the derivative
+    # -> `CAS::Op` a derivated object, or `CAS::Zero` for constants
     def diff(v)
+      CAS::Help.assert(v, CAS::Op)
+
       if @x.depend? v
         return @x.diff(v)
       end
       CAS::Zero
     end
 
+    # Call resolves the operation tree in a `Numeric` (if `Fixnum`)
+    # or `Float` depends upon promotions).
+    # As input, it requires an hash with `CAS::Variable` or `CAS::Variable#name`
+    # as keys, and a `Numeric` as a value
+    #
+    # ``` ruby
+    # x, y = CAS::vars :x, :y
+    # f = (x ** 2) + (y ** 2)
+    # f.call({x => 1, y => 2})
+    # # => 2
+    # ```
+    # <- `Hash` with feed dictionary
+    # -> `Numeric`
     def call(f)
+      CAS::Help.assert(f, Hash)
+
       @x.call(f)
     end
 
+    # Perform substitution of a part of the graph using a data table:
+    #
+    # ``` ruby
+    # x, y = CAS::vars :x, :y
+    # f = (x ** 2) + (y ** 2)
+    # puts f
+    # # => (x^2) + (y^2)
+    # puts f.subs({x => CAS::ln(y)})
+    # # => (ln(y)^2) + (y^2)
+    # ```
+    #
+    # <- `Hash` with substitution table
+    # -> `CAS::Op` (`self`) with substitution performed
     def subs(dt)
-      @x == dt[@x] if dt.keys.include? @x
+      CAS::Help.assert(dt, Hash)
+
+      @x == dt[@x].dup if dt.keys.include? @x
       return self
     end
 
+    # Convert expression to string
+    #
+    # -> `String` to print on screen
     def to_s
       "#{@x}"
     end
 
+    # Convert expression to code (internal, for `CAS::Op#to_proc` method)
+    #
+    # -> `String` that represent Ruby code to be parsed in `CAS::Op#to_proc`
     def to_code
       "#{@x}"
     end
 
+    # Returns a sum of two `CAS::Op`s
+    #
+    # <- `CAS::Op` tree
+    # -> `CAS::Op` new object
     def +(op)
       CAS::Sum.new self, op
     end
 
+    # Returns a difference of two `CAS::Op`s
+    #
+    # <- `CAS::Op` tree
+    # -> `CAS::Op` new object
     def -(op)
       CAS::Diff.new self, op
     end
 
+    # Returns a product of two `CAS::Op`s
+    #
+    # <- `CAS::Op` tree
+    # -> `CAS::Op` new object
     def *(op)
       CAS::Prod.new self, op
     end
 
+    # Returns a division of two `CAS::Op`s
+    #
+    # <- `CAS::Op` tree
+    # -> `CAS::Op` new object
     def /(op)
       CAS::Div.new self, op
     end
 
+    # Returns the power of two `CAS::Op`s
+    #
+    # <- `CAS::Op` tree
+    # -> `CAS::Op` new object
     def **(op)
       CAS.pow(self, op)
     end
 
+    # Unary operator for inversion of a `CAS::Op`
+    #
+    # -> `CAS::Op` new object
     def -@
       CAS.invert(self)
     end
 
+    # Simplification callback. It simplify the subgraph of each node
+    # until all possible simplification are performed (thus the execution
+    # time is not deterministic).
     def simplify # TODO: improve this
       hash = @x.to_s
       @x = @x.simplify
@@ -86,30 +182,68 @@ module CAS
       end
     end
 
+    # Inspector for the current object
+    #
+    # -> `String`
     def inspect
       "#{self.class}(#{@x.inspect})"
     end
 
-
+    # Equality operator, the standard operator is overloaded
+    # :warning: this operates on the graph, not on the math
+    # See `CAS::equal`, etc.
+    #
+    # <- `CAS::Op` to be tested against
+    # -> `TrueClass` if equal, `FalseClass` if differs
     def ==(op)
+      CAS::Help.assert(op, CAS::Op)
+
       self.class == op.class and @x == op.x
     end
 
+    # Disequality operator, the standard operator is overloaded
+    # :warning: this operates on the graph, not on the math
+    # See `CAS::equal`, etc.
+    #
+    # <- `CAS::Op` to be tested against
+    # -> `FalseClass` if equal, `TrueClass` if differs
     def !=(op)
       not self.==(op)
     end
 
-    def as_proc(bind)
+    # Evaluates the proc against a given context. It is like having a
+    # snapshot of the tree transformed in a callable object.
+    # Obviously **if the tree changes, the generated proc does notchanges**.
+    # The proc takes as input a feed dictionary in which each variable
+    # is identified through the `CAS::Variable#name` key.
+    #
+    # The proc is evaluated in the context devined by the input `Binding` object
+    # If `nil` is passed, the `eval` will run in this local context
+    #
+    # <- `Binding` or `NilClass` that is the context of the Ruby VM
+    # -> `Proc` object with a single argument as an `Hash`
+    def as_proc(bind=nil)
       args_ext = self.args.map { |e| "#{e} = fd[\"#{e}\"];" }
       code = "Proc.new do |fd|; #{args_ext.join " "} #{self.to_code}; end"
-      puts code
-      bind.eval(code)
+      if bind
+        CAS::Help.assert(bind, Binding)
+        bind.eval(code)
+      else
+        eval(code)
+      end
     end
 
+    # Returns a list of all `CAS::Variable`s of the current tree
+    #
+    # -> `Array` of `CAS::Variable`s
     def args
       @x.args.uniq
     end
 
+    # Return the local Graphviz node of the tree
+    #
+    # <- `?` unused variable (TODO: to be removed)
+    # -> `String` of local Graphiz node
     def dot_graph(node)
       cls = "#{self.class.to_s.gsub("CAS::", "")}_#{self.object_id}"
       "#{cls} -> #{@x.dot_graph node}\n"
@@ -124,6 +258,15 @@ module CAS
   class BinaryOp < CAS::Op
     attr_reader :x, :y
 
+    # The binary operator inherits from the `CAS::Op`, even
+    # if it is defined as a node with two possible branches. This
+    # is particular of the basic operations. The two basic nodes
+    # shares the **same** interface, so all the operations do not
+    # need to know which kind of node they are handling.
+    #
+    # <- `CAS::Op` left argument of the node or `Numeric` to be converted in `CAS::Constant`
+    # <- `CAS::Op` right argument of the node or `Numeric` to be converted in `CAS::Constant`
+    # -> `CAS::BinaryOp` instance
     def initialize(x, y)
       if x.is_a? Numeric
         case x
@@ -145,50 +288,100 @@ module CAS
           y = CAS.const y
         end
       end
+      CAS::Help.assert(x, CAS::Op)
+      CAS::Help.assert(y, CAS::Op)
+
       @x = x
       @y = y
     end
 
+    # Same as `CAS::Op#depend?`
     def depend?(v)
+      CAS::Help.assert(v, CAS::Op)
+
       @x.depend? v or @y.depend? v
     end
 
+    # This method returns an array with the derivatives of the two branches
+    # of the node. This method is usually called by child classes, and it is not
+    # intended to be used directly.
+    #
+    # <- `CAS::Op` operation to differentiate against
+    # -> `Array` of differentiated branches ([0] for left, [1] for right)
     def diff(v)
+      CAS::Help.assert(v, CAS::Op)
+      left, right = CAS::Zero, CAS::Zero
+
       left = @x.diff(v) if @x.depend? v
       right = @y.diff(v) if @y.depend? v
+
       return left, right
     end
 
+    # Substituitions for both branches of the graph, same as `CAS::Op#subs`
+    #
+    # <- `Hash` of substitutions
+    # -> `CAS::BinaryOp`, in practice `self`
     def subs(dt)
-      @x = dt[@x] if dt.keys.include? @x
-      @y = dt[@y] if dt.keys.include? @y
+      CAS::Help.assert(dt, Hash)
+
+      @x = dt[@x].dup if dt.keys.include? @x
+      @y = dt[@y].dup if dt.keys.include? @y
       return self
     end
 
-    def call
+    # Same `CAS::Op#call`
+    #
+    # <- `Hash` of values
+    # -> `Numeric` for result
+    def call(fd)
       raise CASError, "Not Implemented. This is a virtual method"
     end
 
+    # String representation of the tree
+    #
+    # -> `String`
     def to_s
       raise CASError, "Not Implemented. This is a virtual method"
     end
 
+    # Code to be used in `CAS::BinaryOp#to_proc`
+    #
+    # -> `String`
     def to_code
       raise CASError, "Not implemented. This is a virtual method"
     end
 
+    # Returns an array of all the variables that are in the graph
+    #
+    # -> `Array` of `CAS::Variable`s
     def args
       (@x.args + @y.args).uniq
     end
 
+    # Inspector
+    #
+    # -> `String`
     def inspect
       "#{self.class}(#{@x.inspect}, #{@y.inspect})"
     end
 
+    # Comparison with other `CAS::Op`. This is **not** a math operation.
+    #
+    # <- `CAS::Op` to be compared against
+    # -> `TrueClass` if equal, `FalseClass` if different
     def ==(op)
-      self.class == op.class and @x == op.x and @y == op.y
+      CAS::Help.assert(op, CAS::Op)
+      if op.is_a? CAS::BinaryOp
+        return (self.class == op.class and @x == op.x and @y == op.y)
+      else
+        return false
+      end
     end
 
+    # Executes simplifications of the two branches of the graph
+    #
+    # -> `CAS::BinaryOp` as `self`
     def simplify # TODO: improve this
       hash = @x.to_s
       @x = @x.simplify
@@ -204,6 +397,10 @@ module CAS
       end
     end
 
+    # Returns the graphviz representation of the current node
+    #
+    # <- `?` to be removed
+    # -> `String`
     def dot_graph(node)
       cls = "#{self.class.to_s.gsub("CAS::", "")}_#{self.object_id}"
       "#{cls} -> #{@x.dot_graph node}\n  #{cls} -> #{@y.dot_graph node}"

data/lib/ragni-cas.rb

@@ -1,13 +1,45 @@
 #!/usr/bin/env ruby
 
+# ragni-cas
+# A very simple CAS engine with encapsuled graph
+# representation. This will make impossible to
+# perform complex high level simplifications, but
+# it is powerful enough to define simple algorithm
+# in a symbolic way.
+#
+# Mathematically, this is an implementation of the
+# forward chain rule for automatic differentiaition.
+# Each function is a container of function and the
+# derivation is in the form:
+#
+# ```
+#   d(f(g(x))
+#   --------- = g'(x) * f'(g(x))
+#      dx
+# ```
+#
+# Author:: Matteo Ragni (mailto:info@ragni.me)
+# Copyright:: Copyright (c) 2016 Matteo Ragni
+# License:: Distributed under MIT license term
+
 require_relative 'op.rb'
 require_relative 'numbers.rb'
 require_relative 'fnc-base.rb'
 require_relative 'fnc-trig.rb'
 require_relative 'fnc-trsc.rb'
+require_relative 'fnc-branch.rb'
 
 module CAS
+
+  # Return a string representation of the graph that is
+  # a Graphviz tree. Requires a `CAS::Op` as argument.
+  # In the next releases probably it will be moved inside
+  # `CAS::Op`.
+  # <- `CAS::Op` instance
+  # -> `String`
   def self.to_dot(op)
+    CAS::Help.assert(op, CAS::Op)
+
     node = {}
     string = op.dot_graph(node)
     labels = ""
@@ -64,7 +96,25 @@ digraph Op {
     EOG
   end
 
+  # Export the input `CAS::Op` graphviz representation to a file.
+  # <- `String` with filename
+  # <- `CAS::Op` with the tree
+  # -> `CAS::Op` in input
   def self.export_dot(fl, op)
+    CAS::Help.assert(fl, String)
+    CAS::Help.assert(op, CAS::Op)
+
     File.open(fl, "w") do |f| f.puts CAS.to_dot(op) end
+    return op
+  end
+
+
+  # Support functions are in this separate Helper class
+  module Help
+    # Check input `obj.class` against a `type` class
+    # raises an ArgumentError if check fails
+    def self.assert(obj, type)
+      raise ArgumentError, "required #{type}, received #{obj.class}" unless obj.is_a? type
+    end
   end
 end

data/lib/version.rb

@@ -2,6 +2,6 @@
 #!/usr/bin/env ruby
 
 module CAS
-  VERSION = [0, 1, 7]
+  VERSION = [0, 1, 8]
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ragni-cas
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Matteo Ragni
@@ -29,7 +29,7 @@ cert_chain:
   XorZtzkkLImvKFj35xKLFfVkv0Vd8tGQoiL8vdmQNJjAjtE+C+Y7OI4dpiZPKO4G
   R/8JOvUuk9jPbyLxjQH/sFaFqqYGX2xo1zk2CRy/A0WhJrSaXVw1r5lEi7b0W5gg
   -----END CERTIFICATE-----
-date: 2016-07-22 00:00:00.000000000 Z
+date: 2016-07-25 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: info@ragni.me
@@ -38,6 +38,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/fnc-base.rb
+- lib/fnc-branch.rb
 - lib/fnc-trig.rb
 - lib/fnc-trsc.rb
 - lib/numbers.rb