BOAST 1.0.3 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 78df529b137f3cd4300f47711bc4d620c098a338
-  data.tar.gz: a0f73edc8256e5ac857a61418f57eecfd87521ee
+  metadata.gz: f5eb4ec74e14155954a1ecc7c3004e79088160c4
+  data.tar.gz: a4226683ccc72753105a61c2af6a9ddb0ce69bc3
 SHA512:
-  metadata.gz: 5bc73c3b16e34b758c819bed3a5f85703093dd32aaa03e48d20783c55f7bab49203fe2c82c48e621fa3f1b1d2ea7873c0e141cd8ad8d4910d07f1ae60037a1be
-  data.tar.gz: d98656618d9436cbbf75ae1661c70bfc2635b5e38c742e551a9310153afff97c7cf97588ed56c6fadb4e2ffe5fe8efe45e18c3ed781d7810fe643bc6d5b51072
+  metadata.gz: 7f1ac4576270947a645a2b8878f771d0c2dde7974d963b6c57a29eda1dc7a48be24003dc6df38f05e6f17fa9689ebf820634c0007495fecbe4c75bfddec8f5f0
+  data.tar.gz: fc98fd3ce8322e5c995167f043170ef42b61b49b14409d1c66d7cdea0a019e19cbef085012f8341f4add6b254b28e6d660094ffcf65676acdc3316b0bcc7051c

data/BOAST.gemspec

@@ -1,41 +1,12 @@
 Gem::Specification.new do |s|
   s.name = 'BOAST'
-  s.version = "1.0.3"
+  s.version = "1.0.4"
   s.author = "Brice Videau"
   s.email = "brice.videau@imag.fr"
   s.homepage = "https://github.com/Nanosim-LIG/boast"
   s.summary = "BOAST is a computing kernel metaprogramming tool."
   s.description = "BOAST aims at providing a framework to metaprogram, benchmark and validate computing kernels"
-  s.files = %w( BOAST.gemspec
-                LICENSE
-                lib/BOAST.rb
-                lib/BOAST/Algorithm.rb
-                lib/BOAST/CKernel.rb
-                lib/BOAST/BOAST_OpenCL.rb
-                lib/BOAST/Transitions.rb
-                lib/BOAST/Parens.rb
-                lib/BOAST/Operators.rb
-                lib/BOAST/DataTypes.rb
-                lib/BOAST/Arithmetic.rb
-                lib/BOAST/Expression.rb
-                lib/BOAST/Index.rb
-                lib/BOAST/Variable.rb
-                lib/BOAST/Procedure.rb
-                lib/BOAST/If.rb
-                lib/BOAST/For.rb
-                lib/BOAST/Case.rb
-                lib/BOAST/While.rb
-                lib/BOAST/FuncCall.rb
-                lib/BOAST/Pragma.rb
-                lib/BOAST/Inspectable.rb
-                lib/BOAST/Functors.rb
-                lib/BOAST/ControlStructure.rb
-                lib/BOAST/Print.rb
-                lib/BOAST/State.rb
-                lib/BOAST/Optimization.rb
-                lib/BOAST/OpenMP.rb
-                lib/BOAST/Slice.rb
-              )
+  s.files = Dir['BOAST.gemspec', 'LICENSE', 'README.md', 'lib/**/*']
   s.has_rdoc = true
   s.license = 'BSD'
   s.required_ruby_version = '>= 1.9.3'

data/README.md

@@ -0,0 +1,240 @@
+BOAST
+=====
+
+This section will present some simple examples to familiarize the user
+with BOAST. More samples can be found in the git repository.
+
+Installation
+------------
+
+BOAST is ruby based, so ruby needs to be installed on the machine.
+Installation of boast can be done using the ruby built-in package
+manager: *gem*. See following Listing for reference.
+
+```bash
+sudo apt-get install ruby ruby-dev
+gem install --user-install BOAST
+```
+
+Variable and Procedure Declaration
+----------------------------------
+
+The following samples are presented using *irb* ruby interactive interpreter.
+It can be launched using the *irb* command in a terminal.  Following
+Listing shows the declaration of two variables of different kind.
+
+    irb(main):001:0> require 'BOAST'
+    => true
+    irb(main):002:0> a = BOAST::Int "a"
+    => a
+    irb(main):003:0> b = BOAST::Real "b"
+    => b
+    irb(main):004:0> BOAST::decl a, b
+    integer(kind=4) :: a
+    real(kind=8) :: b
+    => [a, b]
+
+Following Listing shows the declaration of a procedure using the two previous
+variables as parameters. For clarity irb echoes have been suppressed.
+
+    005:0> p = BOAST::Procedure( "test_proc", [a,b] )
+    006:0> BOAST::opn p
+    SUBROUTINE test_proc(a, b)
+      integer, parameter :: wp=kind(1.0d0)
+      integer(kind=4) :: a
+      real(kind=8) :: b
+    007:0> BOAST::close p
+    END SUBROUTINE test_proc
+
+Switching Language
+------------------
+
+Following Listing shows how to switch BOAST to C.  Available languages are
+*FORTRAN*, *C*, *CUDA* and *CL*.
+
+    008:0> BOAST::lang = BOAST::C
+    009:0> BOAST::opn p
+    void test_proc(int32_t a, double b){
+    010:0> BOAST::close p
+    }
+
+Defining a Complete Procedure
+-----------------------------
+
+Following Listing shows how to define a procedure and the associated code. Note
+that here the parameters of the procedure have been associated a direction:
+one, *a*, is an input parameter while the other, *b*, is an output parameter.
+
+    011:0> BOAST::lang = BOAST::FORTRAN
+    012:0> a = BOAST::Real( "a", :dir => :in)
+    013:0> b = BOAST::Real( "b", :dir => :out)
+    014:0> p = BOAST::Procedure( "plus_two", [a,b] ) {
+    015:1*   BOAST::pr b === a + 2
+    016:1> }
+    017:0> BOAST::pr p
+    SUBROUTINE plus_two(a, b)
+      integer, parameter :: wp=kind(1.0d0)
+      real(kind=8), intent(in) :: a
+      real(kind=8), intent(out) :: b
+      b = a + 2
+    END SUBROUTINE plus_two
+    018:0> BOAST::lang = BOAST::C
+    019:0> BOAST::pr p
+    void plus_two(const double a, double * b){
+      (*b) = a + 2;
+    }
+
+Creating, Building and Running a Computing Kernel
+-------------------------------------------------
+
+Following Listing shows how to create a Computing kernel (*CKernel*) and build
+it. Once a computing kernel is instantiated the output of BOAST will be
+redirected to the computing kernel source code.  Line 4 sets the entry point of
+the computing kernel to the procedure we just defined. By default compilation
+commands are not shown unless an error occurs. This behavior can be changed by
+switching to verbose mode.
+
+When running the kernel all the arguments have to be specified. Running
+a kernel returns a hash table containing information about the procedure
+execution. In this simple case two informations are returned, first the
+value of the output parameter *b* and second the time the kernel
+execution took.
+
+    020:0> BOAST::lang = BOAST::FORTRAN
+    021:0> k = BOAST::CKernel::new
+    022:0> BOAST::pr p
+    023:0> k.procedure = p
+    024:0> puts k
+    SUBROUTINE plus_two(a, b)
+      integer, parameter :: wp=kind(1.0d0)
+      real(kind=8), intent(in) :: a
+      real(kind=8), intent(out) :: b
+      b = a + 2
+    END SUBROUTINE plus_two
+    025:0> k.build
+    026:0> BOAST::verbose = true
+    027:0> k.build
+    gcc -O2 -Wall -fPIC -I/usr/lib/x86_64-linux-gnu/ruby/2.1.0 -I/usr/include/ruby-2.1.0 -I/usr/include/ruby-2.1.0/x86_64-linux-gnu -I/usr/include/x86_64-linux-gnu/ruby-2.1.0 -I/var/lib/gems/2.1.0/gems/narray-0.6.1.1 -DHAVE_NARRAY_H -c -o /tmp/Mod_plus_two20150309_4611_5a129k.o /tmp/Mod_plus_two20150309_4611_5a129k.c
+    gfortran -O2 -Wall -fPIC -c -o /tmp/plus_two20150309-4611-5a129k.o /tmp/plus_two20150309-4611-5a129k.f90
+    gcc -shared -o /tmp/Mod_plus_two20150309_4611_5a129k.so /tmp/Mod_plus_two20150309_4611_5a129k.o /tmp/plus_two20150309-4611-5a129k.o -Wl,-Bsymbolic-functions -Wl,-z,relro -rdynamic -Wl,-export-dynamic -L/usr/lib -lruby-2.1 -lrt
+    028:0> r = k.run(5,0)
+    029:0> puts r
+    {:reference_return=>{:b=>7.0}, :duration=>5.84e-07}
+
+Using Arrays in Procedures
+--------------------------
+
+Most computing kernels don't work on scalar values but rather on arrays
+of data. Following Listing shows how to use arrays in computing
+kernels. In this case we place ourselves in BOAST namespace to reduce
+the syntax overhead. Variables *a* and *b* are one-dimensional arrays of
+size *n*. Arrays in BOAST start at index 1 unless specified otherwise.
+For instance `Dim(0,n-1)` would have created a dimension starting at 0.
+Array bounds can also be negative and several dimensions can be
+specified to obtain muti-dimensional arrays. For self contained
+procedures/kernels one can use the shortcut written on line 13 to create
+a CKernel object. As we are not specifying build options the build
+command can also be omitted and will be automatically called when
+running the kernel the first time. Lines 17 to 19 are used to check the
+result of the kernel.
+
+    001:0> require 'BOAST'
+    002:0> require 'narray'
+    003:0> include BOAST
+    004:0> n = Int(  "n", :dir => :in )
+    005:0> a = Real( "a", :dir => :in,  :dim => [Dim(n)] )
+    006:0> b = Real( "b", :dir => :out, :dim => [Dim(n)] )
+    007:0> p = Procedure( "plus_two", [n, a, b] ) {
+    008:1*   decl i = Int( "i" )
+    009:1>   pr For( i, 1, n ) {
+    010:2*     pr b[i] === a[i] + 2.0
+    011:2>   }
+    012:1> }
+    013:0> k = p.ckernel
+    014:0> input  = NArray.float(1024).random
+    015:0> output = NArray.float(1024)
+    016:0> k.run(input.length, input, output)
+    017:0> (output - input).each { |val|
+    018:1*   raise "Error!" if (val-2).abs > 1e-15
+    019:1> }
+    020:0> stats = k.run(input.length, input, output)
+    021:0> puts "Success, duration: #{stats[:duration]} s"
+    Success, duration: 3.79e-06 s
+
+The Canonical Case: Vector Addition
+-----------------------------------
+
+Following Listing shows the addition of two vectors in a third one. Here BOAST
+is configured to have arrays starting at 0 and to use single precision reals by
+default (Lines 5 and 6). The kernel declaration is encapsulated inside a method
+to avoid cluttering the global namespace. Line 15 the expression `c[i] === a[i]+ b[i]`
+is stored inside a variable *expr* for later use. Lines 16 to 23 show
+that the kernel differs depending on the target language, in CUDA and OpenCL
+each thread will process one element.
+
+```ruby
+require 'narray'
+require 'BOAST'
+include BOAST
+
+set_array_start(0)
+set_default_real_size(4)
+
+def vector_add
+  n = Int("n",:dir => :in)
+  a = Real("a",:dir => :in, :dim => [ Dim(n)] )
+  b = Real("b",:dir => :in, :dim => [ Dim(n)] )
+  c = Real("c",:dir => :out, :dim => [ Dim(n)] )
+  p = Procedure("vector_add", [n,a,b,c]) {
+    decl i = Int("i")
+    expr = c[i] === a[i] + b[i]
+    if (get_lang == CL or get_lang == CUDA) then
+      pr i === get_global_id(0)
+      pr expr
+    else
+      pr For(i,0,n-1) {
+        pr expr
+      }
+    end
+  }
+  return p.ckernel
+end
+```
+
+Following Listing shows the a way to check the validity of the previous kernel
+over the available range of languages. The options that are passed to run are
+only relevant for GPU languages and are thus ignored in FORTRAN and C
+(Line 16). Success is only printed if results are validated, else an exception
+is raised (Lines 17 to 20).
+
+```ruby
+n = 1024*1024
+a = NArray.sfloat(n).random
+b = NArray.sfloat(n).random
+c = NArray.sfloat(n)
+
+epsilon = 10e-15
+
+c_ref = a + b
+
+[:FORTRAN, :C, :CL, :CUDA].each { |l|
+  set_lang( BOAST.const_get(l)  )
+  puts "#{l}:"
+  k = vector_add
+  puts k.print
+  c.random!
+  k.run(n, a, b, c, :global_work_size => [n,1,1], :local_work_size => [32,1,1])
+  diff = (c_ref - c).abs
+  diff.each { |elem|
+    raise "Warning: residue too big: #{elem}" if elem > epsilon
+  }
+}
+puts "Success!"
+```
+
+Acknowledgment
+--------------
+
+The research leading to these results has received funding from the
+European Community's Seventh Framework Programme [FP7/2007-2013] under
+grant agreement n° 288777 and 610402.

data/lib/BOAST/{OpenMP.rb → Language/OpenMP.rb}

@@ -70,6 +70,7 @@ EOF
       register_clause(:flush_list,   :option_list)
       register_clause(:threadprivate_list,   :option_list)
       register_clause(:if,           :simple)
+      register_clause(:final,        :simple)
       register_clause(:num_threads,  :simple)
       register_clause(:default,      :simple)
       register_clause(:collapse,     :simple)

data/lib/BOAST/{Variable.rb → Language/Variable.rb}

@@ -12,7 +12,8 @@ module BOAST
     def initialize(v1=nil,v2=nil)
       if v1 then
         if v2 then
-          @size = Expression::new(Substraction, v2, v1) + 1
+          #@size = Expression::new(Substraction, v2, v1) + 1
+          @size = v2-v1+1
         else
           @size = v1
         end

data/lib/BOAST/Runtime/CKernel.rb

@@ -0,0 +1,94 @@
+require 'stringio'
+require 'rake'
+require 'tempfile'
+require 'rbconfig'
+require 'systemu'
+require 'yaml'
+require 'pathname'
+require 'os'
+
+module BOAST
+
+  class CKernel
+    include Compilers
+    include Rake::DSL
+    include Inspectable
+    include PrivateStateAccessor
+    include TypeTransition
+
+    attr_accessor :code
+    attr_accessor :procedure
+    attr_accessor :lang
+    attr_accessor :binary
+    attr_accessor :kernels
+    attr_accessor :cost_function
+    
+    def initialize(options={})
+      if options[:code] then
+        @code = options[:code]
+      elsif get_chain_code
+        @code = get_output
+        @code.seek(0,SEEK_END)
+      else
+        @code = StringIO::new
+      end
+      set_output(@code)
+      if options[:kernels] then
+        @kernels = options[:kernels]
+      else
+        @kernels  = []
+      end
+      if options[:lang] then
+        @lang = options[:lang]
+      else
+        @lang = get_lang
+      end
+      if options[:architecture] then
+        @architecture = options[:architecture]
+      else
+        @architecture = get_architecture
+      end
+      @probes = [TimerProbe, PAPIProbe]
+
+      case @lang
+      when CL
+        extend OpenCLRuntime
+      when CUDA
+        extend CUDARuntime
+      when FORTRAN
+        extend FORTRANRuntime
+        extend FFIRuntime if ffi?
+      else
+        if @architecture == MPPA then
+          extend MPPARuntime
+        else
+          extend CRuntime
+          extend FFIRuntime if ffi?
+        end
+      end
+    end
+
+    def print
+      @code.rewind
+      puts @code.read
+    end
+
+    def to_s
+      @code.rewind
+      return code.read
+    end
+
+    def method_missing(meth, *args, &block)
+     if meth.to_s == "run" then
+       build
+       run(*args,&block)
+     else
+       super
+     end
+    end
+
+    def cost(*args)
+      @cost_function.call(*args)
+    end
+  end
+end

data/lib/BOAST/Runtime/CRuntime.rb

@@ -0,0 +1,32 @@
+module BOAST
+
+  module CRuntime
+    include CompiledRuntime
+
+    def fill_library_header
+      get_output.puts "#include <inttypes.h>"
+    end
+
+    def fill_library_source
+      fill_library_header
+      @code.rewind
+      get_output.write @code.read
+    end
+
+    def create_procedure_call_parameters
+      params = []
+      @procedure.parameters.each { |param|
+        if param.dimension then
+          params.push( param.name )
+        elsif param.direction == :out or param.direction == :inout then
+          params.push( "&"+param.name )
+        else
+          params.push( param.name )
+        end
+      }
+      return params
+    end
+
+  end
+
+end

data/lib/BOAST/Runtime/CUDARuntime.rb

@@ -0,0 +1,158 @@
+module BOAST
+
+  module CUDARuntime
+    include CRuntime
+
+    alias fill_library_source_old fill_library_source
+    alias fill_library_header_old fill_library_header
+    alias fill_module_header_old fill_module_header
+    alias get_params_value_old get_params_value
+    alias fill_decl_module_params_old fill_decl_module_params
+    alias create_procedure_call_parameters_old create_procedure_call_parameters
+
+    def fill_module_header
+      fill_module_header_old
+      get_output.puts "#include <cuda_runtime.h>"
+    end
+
+    def fill_library_header
+      fill_library_header_old
+      get_output.puts "#include <cuda.h>"
+    end
+
+    def fill_library_source
+      fill_library_source_old
+      get_output.write <<EOF
+extern "C" {
+  #{@procedure.boast_header_s(CUDA)}{
+    dim3 dimBlock(block_size[0], block_size[1], block_size[2]);
+    dim3 dimGrid(block_number[0], block_number[1], block_number[2]);
+    cudaEvent_t __start, __stop;
+    float __time;
+    cudaEventCreate(&__start);
+    cudaEventCreate(&__stop);
+    cudaEventRecord(__start, 0);
+    #{@procedure.name}<<<dimGrid,dimBlock>>>(#{@procedure.parameters.join(", ")});
+    cudaEventRecord(__stop, 0);
+    cudaEventSynchronize(__stop);
+    cudaEventElapsedTime(&__time, __start, __stop);
+    return (unsigned long long int)((double)__time*(double)1e6);
+  }
+}
+EOF
+    end
+
+    def copy_array_param_from_ruby( param, ruby_param )
+      rb_ptr = Variable::new("_boast_rb_ptr", CustomType, :type_name => "VALUE")
+      (rb_ptr === ruby_param).pr
+      get_output.print <<EOF
+  if ( IsNArray(_boast_rb_ptr) ) {
+    struct NARRAY *_boast_n_ary;
+    size_t _boast_array_size;
+    Data_Get_Struct(_boast_rb_ptr, struct NARRAY, _boast_n_ary);
+    _boast_array_size = _boast_n_ary->total * na_sizeof[_boast_n_ary->type];
+    cudaMalloc( (void **) &#{param}, _boast_array_size);
+    cudaMemcpy(#{param}, (void *) _boast_n_ary->ptr, _boast_array_size, cudaMemcpyHostToDevice);
+  } else {
+    rb_raise(rb_eArgError, "Wrong type of argument for %s, expecting array!", "#{param}");
+  }
+EOF
+    end
+
+    def fill_decl_module_params
+      fill_decl_module_params_old
+      get_output.print <<EOF
+  size_t _boast_block_size[3] = {1,1,1};
+  size_t _boast_block_number[3] = {1,1,1};
+EOF
+    end
+
+    def get_params_value
+      get_params_value_old
+      get_output.print <<EOF
+  if( _boast_rb_opts != Qnil ) {
+    VALUE _boast_rb_array_data = Qnil;
+    int _boast_i;
+    _boast_rb_ptr = rb_hash_aref(_boast_rb_opts, ID2SYM(rb_intern("block_size")));
+    if( _boast_rb_ptr != Qnil ) {
+      if (TYPE(_boast_rb_ptr) != T_ARRAY)
+        rb_raise(rb_eArgError, "Cuda option block_size should be an array");
+      for(_boast_i=0; _boast_i<3; _boast_i++) {
+        _boast_rb_array_data = rb_ary_entry(_boast_rb_ptr, _boast_i);
+        if( _boast_rb_array_data != Qnil )
+          _boast_block_size[_boast_i] = (size_t) NUM2LONG( _boast_rb_array_data );
+      }
+    } else {
+      _boast_rb_ptr = rb_hash_aref(_boast_rb_opts, ID2SYM(rb_intern("local_work_size")));
+      if( _boast_rb_ptr != Qnil ) {
+        if (TYPE(_boast_rb_ptr) != T_ARRAY)
+          rb_raise(rb_eArgError, "Cuda option local_work_size should be an array");
+        for(_boast_i=0; _boast_i<3; _boast_i++) {
+          _boast_rb_array_data = rb_ary_entry(_boast_rb_ptr, _boast_i);
+          if( _boast_rb_array_data != Qnil )
+            _boast_block_size[_boast_i] = (size_t) NUM2LONG( _boast_rb_array_data );
+        }
+      }
+    }
+    _boast_rb_ptr = rb_hash_aref(_boast_rb_opts, ID2SYM(rb_intern("block_number")));
+    if( _boast_rb_ptr != Qnil ) {
+      if (TYPE(_boast_rb_ptr) != T_ARRAY)
+        rb_raise(rb_eArgError, "Cuda option block_number should be an array");
+      for(_boast_i=0; _boast_i<3; _boast_i++) {
+        _boast_rb_array_data = rb_ary_entry(_boast_rb_ptr, _boast_i);
+        if( _boast_rb_array_data != Qnil )
+          _boast_block_number[_boast_i] = (size_t) NUM2LONG( _boast_rb_array_data );
+      }
+    } else {
+      _boast_rb_ptr = rb_hash_aref(_boast_rb_opts, ID2SYM(rb_intern("global_work_size")));
+      if( _boast_rb_ptr != Qnil ) {
+        if (TYPE(_boast_rb_ptr) != T_ARRAY)
+          rb_raise(rb_eArgError, "Cuda option global_work_size should be an array");
+        for(_boast_i=0; _boast_i<3; _boast_i++) {
+          _boast_rb_array_data = rb_ary_entry(_boast_rb_ptr, _boast_i);
+          if( _boast_rb_array_data != Qnil )
+            _boast_block_number[_boast_i] = (size_t) NUM2LONG( _boast_rb_array_data ) / _boast_block_size[_boast_i];
+        }
+      }
+    }
+  }
+EOF
+    end
+
+    def create_procedure_call_parameters
+      return create_procedure_call_parameters_old + ["_boast_block_number", "_boast_block_size"]
+    end
+
+    def create_procedure_call
+      get_output.print "  #{TimerProbe::RESULT} = "
+      get_output.print " #{method_name}_wrapper( "
+      get_output.print create_procedure_call_parameters.join(", ")
+      get_output.puts " );"
+    end
+
+    def copy_array_param_to_ruby(param, ruby_param)
+      rb_ptr = Variable::new("_boast_rb_ptr", CustomType, :type_name => "VALUE")
+      (rb_ptr === ruby_param).pr
+      get_output.print <<EOF
+  if ( IsNArray(_boast_rb_ptr) ) {
+EOF
+      if param.direction == :out or param.direction == :inout then
+        get_output.print <<EOF
+    struct NARRAY *_boast_n_ary;
+    size_t _boast_array_size;
+    Data_Get_Struct(_boast_rb_ptr, struct NARRAY, _boast_n_ary);
+    _boast_array_size = _boast_n_ary->total * na_sizeof[_boast_n_ary->type];
+    cudaMemcpy((void *) _boast_n_ary->ptr, #{param}, _boast_array_size, cudaMemcpyDeviceToHost);
+EOF
+      end
+      get_output.print <<EOF
+    cudaFree( (void *) #{param});
+  } else {
+    rb_raise(rb_eArgError, "Wrong type of argument for %s, expecting array!", "#{param}");
+  }
+EOF
+    end
+
+  end
+
+end