cudd-rb 0.0.1

data/lib/cudd-rb/interfaces/bdd.rb

@@ -0,0 +1,334 @@
+module Cudd
+  module Interface
+    module BDD
+
+      ### BDD CREATION ###################################################################
+
+      # Coerce `pointer` to a BDD
+      def bdd(pointer, &error_handler)
+        return pointer if Cudd::BDD===pointer
+        if FFI::Pointer::NULL==pointer
+          raise Cudd::Error, "NULL pointer for BDD" unless error_handler
+          error_handler.call
+        end
+        m = self
+        pointer.tap do |p|
+          p.instance_eval{ @manager = m }
+          p.extend(Cudd::BDD)
+        end
+      end
+
+      ### REFERENCE COUNT ################################################################
+
+      # @see Cudd_Ref
+      def ref(f)
+        Wrapper.Ref(f)
+        f
+      end
+
+      # @see Cudd_Deref, Cudd_RecursiveDeref
+      #
+      # Uses `Cudd_RecursiveDeref` if `recursive` is true (defauts), decreasing
+      # reference counts of all children of `f`. Uses `Cudd_Deref` otherwise
+      # (use only if your are sure).
+      def deref(f, recursive = true)
+        recursive ? Wrapper.RecursiveDeref(native_manager, f) : Wrapper.Deref(f)
+        f
+      end
+
+      ### VARS ###########################################################################
+
+      # Returns the variable names
+      def var_names
+        @var_names ||= []
+        (@var_names.size...size).each do |i|
+          @var_names[i] = :"v#{i}"
+        end if @var_names.size < size
+        @var_names
+      end
+
+      # Sets the variable names
+      def var_names=(names)
+        @var_names = names
+      end
+
+      # Returns the variable name of a given bdd
+      def var_name(bdd)
+        return :zero if bdd==zero
+        return :one  if bdd==one
+        var_names[var_index(bdd)]
+      end
+
+      # @see Cudd_ReadSize
+      def size
+        Wrapper.ReadSize(native_manager)
+      end
+      alias :bdd_count :size
+
+      # @see Cudd_NodeReadIndex
+      def var_index(bdd)
+        return nil if bdd==zero or bdd==one
+        Wrapper.NodeReadIndex(bdd)
+      end
+
+      # @see Cudd_bddIthVar
+      def ith_var(i)
+        bdd Wrapper.bddIthVar(native_manager, i)
+      end
+
+      # Returns the ith-vars denoted by `arg` as an Array of BDDs.
+      #
+      # Example:
+      #   x, y, z = manager.ith_vars(0, 1, 2)
+      #   x, y, z = manager.ith_vars(0..2)
+      #   x, y, z = manager.ith_vars([0, 1, 2])
+      #
+      def ith_vars(*args)
+        args = args.first if args.size==1
+        Array(args).map(&:to_i).map{|i| ith_var(i)}
+      end
+
+      # @see Cudd_bddNewVar
+      def new_var(name = nil)
+        var = bdd Wrapper.bddNewVar(native_manager)
+        var_names[var_index(var)] = name if name
+        var
+      end
+
+      # Creates new variables and returns them as an Array.
+      #
+      # Example:
+      #   x, y, z = manager.new_vars(3)
+      #   x, y, z = manager.new_vars(:x, :y, :z)
+      #
+      def new_vars(first, *args)
+        _, first = args.unshift(first), args unless args.empty?
+        case first
+        when Integer    then (0...first).map{ new_var }
+        when Enumerable then first.map{|x| new_var(x) }
+        else
+          [ new_var(first) ]
+        end
+      end
+
+      ### CONSTANTS ######################################################################
+
+      # @see Cudd_ReadOne
+      def one
+        @one ||= bdd Wrapper.ReadOne(native_manager)
+      end
+
+      # @see Cudd_ReadLogicZero
+      def zero
+        @zero ||= bdd Wrapper.ReadLogicZero(native_manager)
+      end
+
+      # @see Cudd_IsComplement
+      def is_complement?(bdd)
+        (bdd.address & 1)==1
+      end
+
+      ### BOOLEAN ALGEBRA ################################################################
+
+      # @see Cudd_bddIte
+      def ite(f, g, h)
+        bdd Wrapper.bddIte(native_manager, f, g, h)
+      end
+
+      # @see Cudd_bddNot
+      def not(f)
+        bdd Wrapper.bddNot(native_manager, f)
+      end
+
+      # @see Cudd_bddAnd
+      def and(f, g)
+        bdd Wrapper.bddAnd(native_manager, f, g)
+      end
+
+      # @see Cudd_bddOr
+      def or(f, g)
+        bdd Wrapper.bddOr(native_manager, f, g)
+      end
+
+      # @see Cudd_bddNand
+      def nand(f, g)
+        bdd Wrapper.bddNand(native_manager, f, g)
+      end
+
+      # @see Cudd_bddNor
+      def nor(f, g)
+        bdd Wrapper.bddNor(native_manager, f, g)
+      end
+
+      # @see Cudd_bddXor
+      def xor(f, g)
+        bdd Wrapper.bddXor(native_manager, f, g)
+      end
+
+      # @see Cudd_bddXnor
+      def xnor(f, g)
+        bdd Wrapper.bddXnor(native_manager, f, g)
+      end
+
+      ### SUPPORT ########################################################################
+
+      # @see Cudd_Support
+      def support(bdd)
+        Wrapper.Support(native_manager, bdd)
+      end
+
+      ### COFACTOR & GENERALIZED COFACTOR ################################################
+
+      # @see Cudd_Cofactor
+      def cofactor(bdd, cube)
+        with_bdd_cube(cube) do |c|
+          bdd Wrapper.Cofactor(native_manager, bdd, c)
+        end
+      end
+
+      # @see Cudd_bddRestrict
+      def restrict(f, g)
+        with_bdd_cube(g) do |c|
+          bdd Wrapper.bddRestrict(native_manager, f, c)
+        end
+      end
+
+      ### ABSTRACTION ####################################################################
+
+      # @see Cudd_bddExistAbstract
+      def exist_abstract(bdd, cube)
+        with_bdd_cube(cube) do |c|
+          bdd Wrapper.bddExistAbstract(native_manager, bdd, c)
+        end
+      end
+      alias :exist :exist_abstract
+
+      # @see Cudd_bddUnivAbstract
+      def univ_abstract(bdd, cube)
+        with_bdd_cube(cube) do |c|
+          bdd Wrapper.bddUnivAbstract(native_manager, bdd, c)
+        end
+      end
+      alias :univ :univ_abstract
+      alias :forall :univ_abstract
+
+      ### COERCIONS from & to Cubes ######################################################
+
+      # Coerces `arg` to a cube.
+      #
+      # Example (suppose three BDD variables: x, y and z):
+      #
+      #   cube([1, 0, 2])              # => [1, 0, 2]
+      #   cube([1, 0])                 # same
+      #   cube([true, false])          # same
+      #   cube([x, !y])                # same
+      #   cube(x => true, y => false)  # same
+      #
+      def cube(arg, as = :cube)
+        cube = Cube.new(self, arg)
+        cube.send(:"to_#{as}")
+      rescue NoMethodError
+        raise ArgumentError, "Invalid 'as' option `#{as}`"
+      end
+
+      # @see Cudd_CubeArrayToBdd
+      def cube2bdd(cube_array)
+        with_ffi_pointer(:int, cube_array.size) do |ptr|
+          ptr.write_array_of_int(cube_array)
+          bdd Wrapper.CubeArrayToBdd(native_manager, ptr) do
+            raise Cudd::Error, "Cudd_CubeArrayToBdd failed on `#{cube_array.inspect}`"
+          end
+        end
+      end
+
+      # @see Cudd_BddToCubeArray
+      def bdd2cube(bdd)
+        s = size
+        with_ffi_pointer(:int, s) do |ptr|
+          if Wrapper.BddToCubeArray(native_manager, bdd, ptr)==1
+            ptr.read_array_of_int(s)
+          else
+            raise NotACubeError
+          end
+        end
+      end
+
+      # Converts a bdd to a disjunctive normal form
+      def bdd2dnf(bdd)
+        return "true"  if bdd==one
+        return "false" if bdd==zero
+        buf, size = "", 0
+        each_cube(bdd) do |cube|
+          size += 1
+          buf << " | " unless buf.empty?
+          buf << "(" << cube.to_dnf << ")"
+        end
+        size == 1 ? buf[1...-1] : buf
+      end
+
+      ### EVALUATION & SATISFIABILITY ####################################################
+
+      # @see Cudd_Eval
+      def eval(f, cube)
+        with_ffi_pointer(:int, size) do |ptr|
+          ptr.write_array_of_int(cube(cube, :a012))
+          bdd Wrapper.Eval(native_manager, f, ptr)
+        end
+      end
+
+      # Returns true if `bdd` is satisfiable, false otherwise.
+      def satisfiable?(bdd)
+        !(zero == bdd)
+      end
+
+      # Returns true if `bdd` is satisfied by a given assignment, false otherwise.
+      def satisfied?(bdd, cube)
+        one == eval(bdd, cube)
+      end
+
+      # Returns the first cube satisfying `bdd`.
+      def one_cube(bdd)
+        each_cube(bdd).first
+      end
+
+      # @see Cudd_ForEachCube
+      def each_cube(bdd)
+        return self.enum_for(:each_cube, bdd) unless block_given?
+        return unless satisfiable?(bdd)
+        size, gen = self.size, nil
+        with_ffi_pointer(:pointer) do |cube_pointer|
+          with_ffi_pointer(:double) do |value_pointer|
+            gen = Wrapper.FirstCube(native_manager, bdd, cube_pointer, value_pointer)
+            begin
+              yield cube(cube_pointer.read_pointer.read_array_of_int(size))
+            end until Wrapper.NextCube(gen, cube_pointer, value_pointer)==0
+          end
+        end
+      ensure
+        Wrapper.GenFree(gen) if gen
+      end
+
+      # Returns an array with all cubes satisfying `bdd`.
+      def all_cubes(bdd)
+        each_cube(bdd).to_a
+      end
+
+    private
+
+      # Yields the block with a cube encoded by a BDD. If the latter must be
+      # built, it is automatically referenced then dereferenced after the block
+      # has been yield.
+      def with_bdd_cube(cube)
+        if cube.is_a?(Cudd::BDD)
+          yield(cube)
+        else
+          cube = cube(cube, :bdd).ref
+          res = yield(cube)
+          cube.deref
+          res
+        end
+      end
+
+    end # module BDD
+  end # module Interface
+end # module Cudd

data/lib/cudd-rb/interfaces/root.rb

@@ -0,0 +1,35 @@
+module Cudd
+  module Interface
+    module Root
+
+      def root_manager?
+        root_manager == self
+      end
+
+      # Returns an extension interface for a given name.
+      def interface(name)
+        return root_manager.interface(name) unless root_manager?
+        return self if name == :Root
+        interfaces[name] ||= begin
+          m = Manager.new(options, native_manager, root_manager)
+          m.extend Interface.const_get(name)
+        end
+      end
+
+    private
+
+      def with_ffi_pointer(type = :int, size = 1)
+        res = nil
+        FFI::MemoryPointer.new(type, size) do |ptr|
+          res = yield(ptr)
+        end
+        res
+      end
+
+      def interfaces
+        @interfaces ||= {}
+      end
+
+    end # module Root
+  end # module Interface
+end # module Cudd

data/lib/cudd-rb/loader.rb

@@ -0,0 +1 @@
+require "ffi"

data/lib/cudd-rb/manager.rb

@@ -0,0 +1,78 @@
+require_relative 'interfaces/root'
+module Cudd
+  class Manager
+    include Interface::Root
+
+    # Options passed at construction.
+    attr_reader :options
+
+    # Creates a manager instance.
+    #
+    # @api private
+    def initialize(*args)
+      args.each do |arg|
+        @options        = arg if arg.is_a?(Hash)
+        @root_manager   = arg if arg.is_a?(Manager)
+        @native_manager = arg if arg.is_a?(FFI::Pointer)
+      end
+    end
+
+    # Creates a root manager by invoking `Cudd_Init`
+    #
+    # @api private
+    def self.root(options)
+      options    = options.dup
+      bdd_vars   = (options[:numVars]   ||= 0)
+      zdd_vars   = (options[:numVarsZ]  ||= 0)
+      num_slots  = (options[:numSlots]  ||= 256)
+      cache_size = (options[:cacheSize] ||= 262144)
+      max_mem    = (options[:maxMemory] ||= 0)
+      native_manager = Wrapper.Init(bdd_vars, zdd_vars, num_slots, cache_size, max_mem)
+      raise Cudd::Error, "Unable to create a manager" unless native_manager
+      Manager.new(options, native_manager).tap do |m|
+        ObjectSpace.define_finalizer(m, lambda{|d| d.close})
+      end
+    end
+
+    # Closes this manager by invoking `Cudd_Quit`.
+    def close
+      Wrapper.Quit(@native_manager) if @native_manager
+    ensure
+      @native_manager = nil
+    end
+
+    # Is this manager alive?
+    #
+    # A manager is alive between its creation (via `Cudd.manager`) and an invocation to
+    # `close`, either explicitely of implicitely (garbage collected by ruby).
+    #
+    # @api public
+    def alive?
+      !@native_manager.nil?
+    end
+
+    # Returns true if this manager has already been closed, false otherwise.
+    #
+    # @api public
+    def closed?
+      @native_manager.nil?
+    end
+
+    # Returns the native manager, that is, a FFI::Pointer to the CUDD's
+    # `DdManager`.
+    #
+    # @api public
+    def native_manager
+      @native_manager
+    end
+
+  private
+
+    # @api private
+    def root_manager
+      @root_manager || self
+    end
+
+  end # class Manager
+end # module Cudd
+require_relative 'interfaces/bdd'

data/lib/cudd-rb/version.rb

@@ -0,0 +1,14 @@
+module Cudd
+  module Version
+
+    MAJOR = 0
+    MINOR = 0
+    TINY  = 1
+
+    def self.to_s
+      [ MAJOR, MINOR, TINY ].join('.')
+    end
+
+  end
+  VERSION = Version.to_s
+end

data/lib/cudd-rb/wrapper.rb

@@ -0,0 +1,58 @@
+module Cudd
+  module Wrapper
+    extend FFI::Library
+    ffi_lib ['cudd', 'libcudd'] + Dir[File.expand_path('../../../ext/*', __FILE__)]
+
+    ONE_POINTER    = [ :pointer ]
+    TWO_POINTERS   = [ :pointer, :pointer ]
+    THREE_POINTERS = [ :pointer, :pointer, :pointer ]
+    FOUR_POINTERS  = [ :pointer, :pointer, :pointer, :pointer ]
+    FIVE_POINTERS  = [ :pointer, :pointer, :pointer, :pointer, :pointer ]
+
+    def self.cudd_function(name, signature, return_type = :pointer)
+      attach_function name, :"Cudd_#{name}", signature, return_type
+    end
+
+    cudd_function :Init,           Array.new(4, :uint) << :ulong
+    cudd_function :Quit,           ONE_POINTER,  :void
+
+    cudd_function :Ref,            ONE_POINTER,  :void
+    cudd_function :Deref,          ONE_POINTER,  :void
+    cudd_function :RecursiveDeref, TWO_POINTERS, :void
+
+    cudd_function :ReadSize,       ONE_POINTER,  :int
+    cudd_function :NodeReadIndex,  ONE_POINTER,  :int
+
+    cudd_function :ReadOne,        ONE_POINTER
+    cudd_function :ReadZero,       ONE_POINTER
+    cudd_function :ReadLogicZero,  ONE_POINTER
+
+    cudd_function :bddIthVar,      [ :pointer, :int ]
+    cudd_function :bddNewVar,      ONE_POINTER
+    cudd_function :bddIte,         FOUR_POINTERS
+    cudd_function :bddNot,         TWO_POINTERS
+    cudd_function :bddAnd,         THREE_POINTERS
+    cudd_function :bddOr,          THREE_POINTERS
+    cudd_function :bddNand,        THREE_POINTERS
+    cudd_function :bddNor,         THREE_POINTERS
+    cudd_function :bddXor,         THREE_POINTERS
+    cudd_function :bddXnor,        THREE_POINTERS
+
+    cudd_function :Cofactor,        THREE_POINTERS
+    cudd_function :bddRestrict,     THREE_POINTERS
+
+    cudd_function :bddExistAbstract, THREE_POINTERS
+    cudd_function :bddUnivAbstract,  THREE_POINTERS
+
+    cudd_function :Support,        TWO_POINTERS
+
+    cudd_function :BddToCubeArray, THREE_POINTERS, :int
+    cudd_function :CubeArrayToBdd, TWO_POINTERS
+
+    cudd_function :Eval,           THREE_POINTERS
+    cudd_function :FirstCube,      FOUR_POINTERS
+    cudd_function :NextCube,       THREE_POINTERS, :int
+    cudd_function :GenFree,        ONE_POINTER, :int
+
+  end # module Wrapper
+end # module Cudd

data/lib/cudd-rb.rb

@@ -0,0 +1,46 @@
+#
+# A ruby bridge to the CU Decision Diagram package (CUDD).
+#
+module Cudd
+
+  # initial size of subtables
+  UNIQUE_SLOTS = 256
+
+  # default size of the cache
+  CACHE_SLOTS = 262144
+
+  # Creates a manager instance.
+  #
+  # Recognized options match `Cudd_Init` arguments.
+  # - :numVars  (defaults to 0)  initial number of BDD variables (subtables)
+  # - :numVarsZ (defaults to 0)  initial number of ZDD variables (subtables)
+  # - :numSlots (defaults to UNIQUE_SLOTS) initial size of the unique tables
+  # - :cacheSize (defaults to CACHE_SLOTS) initial size of the cache
+  # - :maxMemory (defaults to 0) target maximum memory occupation
+  #
+  # If a block is given, the manager is yield and automatically closed when the block
+  # terminates (its result is returned). Otherwise, the manager is returned and its is
+  # the responsibility of the caller to close it.
+  #
+  # @see Cudd_init
+  def self.manager(opts = {})
+    manager = Manager.root(opts.dup)
+    if block_given?
+      begin
+        yield(manager)
+      ensure
+        manager.close if manager.alive?
+      end
+    else
+      manager
+    end
+  end
+
+end # module Cudd
+require_relative "cudd-rb/version"
+require_relative "cudd-rb/loader"
+require_relative "cudd-rb/errors"
+require_relative "cudd-rb/wrapper"
+require_relative "cudd-rb/manager"
+require_relative "cudd-rb/bdd"
+require_relative "cudd-rb/cube"

data/spec/cube/test_equality.rb

@@ -0,0 +1,22 @@
+require 'spec_helper'
+module Cudd
+  describe Cube, '==' do
+
+    subject{ cube1 == cube2 }
+
+    before{ x; y; z  }
+
+    context 'on equal cubes' do
+      let(:cube1){ cube(x => true, y => false) }
+      let(:cube2){ cube(x => true, y => false) }
+      it{ should be_true }
+    end
+
+    context 'on non equal cubes' do
+      let(:cube1){ cube(x => true, y => false) }
+      let(:cube2){ cube(x => false) }
+      it{ should be_false }
+    end
+
+  end
+end

data/spec/cube/test_hash.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+module Cudd
+  describe Cube, 'to_truths' do
+
+    subject{ c.to_truths }
+
+    before{ x; y; z  }
+
+    context 'on x' do
+      let(:c){ cube(x => true) }
+
+      it 'returns the expected bdd' do
+        subject.should eq([true, nil, nil])
+      end
+    end
+
+    context 'on !x' do
+      let(:c){ cube(x => false) }
+
+      it 'returns the expected bdd' do
+        subject.should eq([false, nil, nil])
+      end
+    end
+
+    context 'on x & y' do
+      let(:c){ cube(x => true, y => true) }
+
+      it 'returns the expected bdd' do
+        subject.should eq([true, true, nil])
+      end
+    end
+
+  end
+end

data/spec/cube/test_new.rb

@@ -0,0 +1,49 @@
+require 'spec_helper'
+module Cudd
+  describe Cube, 'new' do
+
+    subject{ Cube.new(bdd_interface, arg) }
+
+    before{ 
+      x; y; z 
+      subject.should be_a(Cube)
+    }
+
+    shared_examples_for "A cube for x=1,y=0,z=2" do
+      it 'has [1,0,2] has to_a012' do
+        subject.to_a012.should eq([1, 0, 2])
+      end 
+    end
+
+    context 'when an array of 012' do
+      let(:arg){ [ 1, 0, 2 ] }
+      it_behaves_like "A cube for x=1,y=0,z=2"
+    end
+
+    context 'when an incomplete array of 012' do
+      let(:arg){ [ 1, 0 ] }
+      it_behaves_like "A cube for x=1,y=0,z=2"
+    end
+
+    context 'when truth values' do
+      let(:arg){ [ true, false, nil ] }
+      it_behaves_like "A cube for x=1,y=0,z=2"
+    end
+
+    context 'when an array of BDD variables' do
+      let(:arg){ [!y, x] }
+      it_behaves_like "A cube for x=1,y=0,z=2"
+    end
+
+    context 'when a Hash' do
+      let(:arg){ {x => 1, y => false} }
+      it_behaves_like "A cube for x=1,y=0,z=2"
+    end
+
+    context 'when a BDD' do
+      let(:arg){ x & !y }
+      it_behaves_like "A cube for x=1,y=0,z=2"
+    end
+
+  end
+end