ndav 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 443c009b1751ab850206b12f6ae175989fef5bb3e9dfd6094d069b338262474a
-  data.tar.gz: fc5ef147dcbe89690add67f9aca9ed11a71a56ed2d801284936753066da2be2c
+  metadata.gz: e27d78e17f22830ab47cba80120c7fa3ad3139690dd276e1267abb8696c6ffe3
+  data.tar.gz: 1a3ab5273684a54a5920528663fa5ebcab8ab861213b622b60afe3267ff184e5
 SHA512:
-  metadata.gz: 7ce73fa38eba65d0c1933cef3e787a6a770854847f7946098ca4ff7e26ba0e588ee6d5a1d79e469abb27a0c303722f69e9030943a73b5295e7a422c73dee96f5
-  data.tar.gz: 917725d70d4a3269da345d389b93562d54bec9b0911e88229a469a98d79203026ab37bbe834039aded9b1635c827d6723b5b82f23dcacd3864e9df0908dcab20
+  metadata.gz: 6fe639a15fd780e5add9dcf124f3222214f6dd82cef28e4c16589f0f9dae936dda08e378ed28a3fa9bb810933250caf48bad2a18885a6261685451b3faf14bf0
+  data.tar.gz: 3b3769ce7d12622bd231d0f4bffeb590b631a4c6be42984e2c998c49b64d2c24499bf922744d11b02c27dd308735c8f29d3385c70d5f3753509ce3bd70d4415f

data/.gitignore

@@ -6,3 +6,5 @@ ext/Makefile
 *.o
 *.bundle.dSYM
 pkg/
+doc/
+.yardoc/

data/.gitlab-ci.yml

@@ -12,3 +12,15 @@ test:
       - /root/.local/share/gem/ruby
   script:
     - rake test
+
+pages:
+  stage: deploy
+  image: ruby:4.0
+  script:
+    - bundle exec rake yard
+    - mv doc public
+  artifacts:
+    paths:
+      - public
+  only:
+    - main

data/.yardopts

@@ -0,0 +1,3 @@
+--asset NDAV.png
+-
+LICENSE.txt

data/README.md

@@ -1,9 +1,173 @@
 NDAV - N-Dimensional Array View
 ===============================
 
-Wrapper for MemoryView and pointer.
+[![Gem Version](https://badge.fury.io/rb/ndav.svg)](https://badge.fury.io/rb/ndav)
+
+A thin wrapper around [MemoryView][] ("buffer protocol" for Ruby).
+
+It provides an interoperability layer for multi-dimensional arrays which can be shared between libraries.
+
+![NDAV converts library data each other](./NDAV.png)
+
+SYNOPSIS
+--------
+
+    waveform, sample_rate = TorchAudio.load("path/to/audio.wav")
+    
+    # Convert Torch::Tensor to NDAV
+    # so that you can convert it to OrtValue,
+    # a data format for ONNX Runtime
+    input = waveform
+              .to_ndav
+              .to_ort_value
+    
+    # Make ONNX Runtime return result as OrtValue
+    outputs = OnnxRuntime::Session.new("path/to/model.onnx")
+                .run(
+                  [:output_name],
+                  {input_name: input},
+                  output_type: :ort_value
+                )
+    
+    # You may convert OrtValue to Torch::Tensor via NDAV
+    output_tensor = outputs[0]
+                      .to_ndav
+                      .to_torch_tensor # converts back to Torch::Tensor
+    
+    TorchAudio.save("path/to/output.wav", output_tensor, sample_rate)
+
+ABSTRACT
+--------
+
+NDAV acts as an interoperability layer between multi-dimensional arrays including images, audio and tensors such as [Numo::NArray][], [Torch.rb][]'s `Torch::Tensor`, [ONNX Runtime Ruby][]'s `OnnxRuntime::OrtValue`, [Red Arrow][]'s `Arrow::Array` and so on.
+
+It allows data to be shared without copying.
+
+BACKGROUND
+----------
+
+In the modern Ruby community, [Numo::NArray][] is often used for data conversion. But, data are copied when converting to and from Numo::NArray. In addition, Numo::NArray neither exports nor accepts MemoryView.
+
+[Red Arrow][] is also used and it can export MemoryView from `Arrow::Array` (not from `Arrow::Tensor`, though). It also can be converted to and from Numo::NArray using [Red Arrow Numo::NArray][]. But, in real-world usage, we need, for example, to convert data with many hops:
+
+    Torch::Tensor -> Numo::NArray -> Red Arrow -> MemoryView -> some process...
+
+It might not be difficult, but a little bit cumbersome. Additionally, Red Arrow doesn't accept MemoryView.
+
+USAGE
+-----
+
+`ndav` gem is just a base library. You need to install bridges as well. Say, assume you want to make conversions between Numo::NArray each other.
+
+    require "numo/narray"
+    require "ndav"
+    require "ndav/numo/narray"
+    
+    numo = Numo::SFloat.new(3, 5).seq # => Numo::SFloat
+    ndav = numo.to_ndav               # => NDAV
+    
+    numo = Numo::SFloat.from_ndav(ndav) # => Numo::SFloat
+    ndav = NDAV.from_numo_narray(numo)  # => NDAV
+    
+    include NDAV::Converter
+    numo = NumoNArray(ndav) #=> Numo::SFloat
+    ndav = NDAV(numo)       # => NDAV
+
+For `Torch::Tensor` and `OnnxRuntime::OrtValue`, you can do the same operation, therefore you may convert them to each other, like this:
+
+    numo
+      .to_ndav
+      .to_torch_tensor
+      .then {|torch_tensor| some_process(torch_tensor)}
+      .to_ndav
+      .to_ort_value
+      .then {|ort_value|
+        OnnxRuntime::Session.new("model.onnx")
+          .run(
+            [:output],
+            {input: ort_value},
+            output_type: :ort_value
+          )[0]
+      }
+      .to_ndav
+      .to_torch_tensor
+      .then {|torch_tensor| TorchAudio.save(torch_tensor, sample_rate)}
+
+### Working With MemoryView ###
+
+NDAV can be initialized *directly* from libraries which export [MemoryView][] such as [Red Arrow][], without any bridge library:
+
+    arrow = Arrow::Int16Array.new([1, 2, 3])
+    ndav = NDAV.new(arrow)
+
+On the other hand, it also exports MemoryView. You can pass NDAV arrays *directly* to methods which accept MemoryView such as whispercpp without bridge libraries:
+
+    waveform, sample_rate = TorchAudio.load("path/to/audio.wav")
+    samples = waveform.to_ndav
+    whisper.full(params, samples)
+
+### Notice On Memory Sharing ###
+
+Notice that NDAV is just a memory view and libraries share a memory address. If you change source data destructively, it affects converted data.
+
+Additionally, you potentially encounter odd data corruption or segmentation fault. These might be bugs in bridge libraries such as [ndav-numo-narray][]. As a user, you don't need to worry about this kind of memory management, but it's worth knowing such situations may occur.
+
+INSTALLATION
+------------
+
+    % gem install ndav
+
+or,
+
+    % bundle add ndav
+
+But, you need bridges for real-world use. See each bridge's documentation for individual requirements.
+
+BRIDGES
+-------
+
+There are some bridges using NDAV:
+
+* [ndav/ffi][]: [`FFI::MemoryPointer`][FFI Pointer], [`FFI::Pointer`][FFI Pointer] <-> `NDAV`
+* [ndav-numo-narray][]: [`Numo::NArray`][Numo::NArray] <-> `NDAV`
+* [ndav-ort_value][]: [`OnnxRuntime::OrtValue`][ONNX Runtime Ruby] <-> `NDAV`
+* [ndav-torch-tensor][]: [`Torch::Tensor`][Torch.rb] <-> `NDAV`
+* [onnxruntime-torch-tensor][]: [`Torch::Tensor`][Torch.rb] <-> [`OnnxRuntime::OrtValue`][ONNX Runtime Ruby] via `NDAV`
+
+CREATING BRIDGES
+----------------
+
+Refer to existing bridge implementations listed above to create your bridge.
+
+The points are:
+
+* Implement `FromNDAV#from_ndav`, `ToNDAV#to_ndav` and `NDAV.register` them, and `NDAV.from_your_data` and `NDAV#to_your_data` are automatically derived
+* When initializing NDAV object from your object, use `lifetime` keyword argument for `NDAV.new` effectively to prevent Ruby from GCing your object, which would lead to a dangling pointer
+* When initializing your object from NDAV object, keep NDAV object alive to prevent Ruby from GCing NDAV object, which would lead to a dangling pointer, [ndav-numo-narray][], for instance, embeds the NDAV object in an instance variable
+
+An advantage of NDAV over raw MemoryView is that you can write bridges in pure Ruby in most cases. It helps prototyping and experimentation. As an exception, I had to write C code for ndav-numo-narray because Numo::NArray only provides methods that access data by copying and does not directly expose its raw data pointer to Ruby API. However, in even such case, pure Ruby bridge remains a viable option for prototyping and experiments where a single initial copy is acceptable.
+
+If you are a library author, I want you to consider making your library work with [MemoryView][] instead of creating an NDAV bridge.
+
+FUTURE
+------
+
+If [MemoryView][] gets popular enough in the Ruby ecosystem, this library will end its role and will no longer be needed. I hope such future.
 
 LICENSE
 -------
 
 BSD-2-Clause license. See LICENSE.txt file.
+
+[MemoryView]: https://docs.ruby-lang.org/en/master/contributing/memory_view_md.html
+[Numo::NArray]: https://ruby-numo.github.io/narray/
+[Torch.rb]: https://github.com/ankane/torch.rb
+[ONNX Runtime Ruby]: https://github.com/ankane/onnxruntime-ruby
+[Red Arrow]: https://github.com/apache/arrow/tree/main/ruby
+[Red Arrow Numo::NArray]: https://github.com/red-data-tools/red-arrow-numo-narray
+[ndav/ffi]: https://gitlab.com/KitaitiMakoto/ndav/-/blob/main/lib/ndav/ffi.rb?ref_type=heads
+[FFI Pointer]: https://github.com/ffi/ffi/wiki/Pointers
+[ndav-numo-narray]: https://gitlab.com/KitaitiMakoto/ndav-numo-narray
+[ndav-ort_value]: https://gitlab.com/KitaitiMakoto/ndav-ort_value
+[ndav-torch-tensor]: https://gitlab.com/KitaitiMakoto/ndav-torch-tensor
+[onnxruntime-torch-tensor]: https://gitlab.com/KitaitiMakoto/onnxruntime-torch-tensor

data/Rakefile

@@ -1,18 +1,20 @@
 require "rake/clean"
 require "rake/testtask"
 require "rubygems/tasks"
+require "yard"
 
 DL_NAME = "ndav".ext(RbConfig::CONFIG["DLEXT"])
 DL_BUILD_PATH = File.join("ext", DL_NAME)
 DL_PATH = File.join("lib", DL_NAME)
 
 SRC = FileList["ext/**.{h,c,rb}"]
+CLEAN.include SRC.select {|src| src.end_with?(".o", ".so", ".bundle", ".dll") }
 
 task default: :test
 
 Rake::TestTask.new test: DL_PATH
-tasks = Gem::Tasks.new
-gemspec = tasks.build.gem.project.gemspec
+Gem::Tasks.new
+YARD::Rake::YardocTask.new
 
 file DL_PATH => DL_BUILD_PATH do |t|
   copy t.source, t.name

data/lib/ndav/converter.rb

@@ -4,6 +4,10 @@ class NDAV
     alias from_fiddle_memory_view new
     alias from_fiddle_pointer new
 
+    def from_string(str, *, **)
+      new(Fiddle::Pointer[str], *, **)
+    end
+
     def register(cls, mdl, name:)
       if mdl.const_defined?(:FromNDAV)
         cls.extend mdl::FromNDAV

data/ndav.gemspec

@@ -1,10 +1,11 @@
 Gem::Specification.new do |s|
   s.name = "ndav"
-  s.version = "0.0.3"
+  s.version = "0.0.4"
   s.summary = "N-Dimensional Array View"
   s.authors = ["Kitaiti Makoto"]
   s.licenses = ["BSD-2-Clause"]
-  s.homepage = "https://gitlab.com/KitaitiMakoto/ndav"
+  s.homepage = "https://kitaitimakoto.gitlab.io/ndav"
+  s.metadata["source_code_uri"] = "https://gitlab.com/KitaitiMakoto/ndav"
 
   s.files = Dir.chdir(__dir__) {`git ls-files -z`.split("\x0")}
   s.extensions = ["ext/extconf.rb"]
@@ -20,4 +21,5 @@ Gem::Specification.new do |s|
   s.add_development_dependency "rubygems-requirements-system"
   s.add_development_dependency "red-arrow"
   s.add_development_dependency "ffi"
+  s.add_development_dependency "yard"
 end

data/test/test_ndav.rb

@@ -28,4 +28,11 @@ class TestNDAV < TestBase
     assert_equal ptr, ndav.to_fiddle_pointer
     assert_int_array ndav
   end
+
+  def test_string
+    str = [1, 2, 3].pack("s*")
+    ndav = NDAV.from_string(str, format: "s")
+
+    assert_int_array ndav
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ndav
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Kitaiti Makoto
@@ -149,6 +149,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 executables: []
 extensions:
 - ext/extconf.rb
@@ -156,8 +170,10 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".gitlab-ci.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE.txt
+- NDAV.png
 - README.md
 - Rakefile
 - ext/extconf.rb
@@ -173,10 +189,11 @@ files:
 - test/test_ffi.rb
 - test/test_ndav.rb
 - test/test_package.rb
-homepage: https://gitlab.com/KitaitiMakoto/ndav
+homepage: https://kitaitimakoto.gitlab.io/ndav
 licenses:
 - BSD-2-Clause
-metadata: {}
+metadata:
+  source_code_uri: https://gitlab.com/KitaitiMakoto/ndav
 rdoc_options: []
 require_paths:
 - lib