ruby-hdf5 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a5d336f6b45f913a829873d20aba6c80c5724db14038965e073235f36477733
+  data.tar.gz: 1fe31c4c72258d31d57ca6ce043aee21f7cd9083700c77405a501a79f1ea5323
+SHA512:
+  metadata.gz: 786821e23be9bdc249352c34dc5e293be4a6f3e931c69cc89a1f51ee284d53e00d2ccdb130ee49a2e5bf467ff89cf60f184c455ffc3271309ea0c37a189b28eb
+  data.tar.gz: 98150386a48675d3208416cca2c1d4f1668f9519c2acafbb2935ae0d8111789a1de890d1516640c2649bc463d8c07f1144acad050a018f209fe429cf5d394821

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 kojix2
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,115 @@
+# ruby-hdf5
+
+[![test](https://github.com/red-data-tools/ruby-hdf5/actions/workflows/test.yml/badge.svg)](https://github.com/red-data-tools/ruby-hdf5/actions/workflows/test.yml)
+
+Ruby bindings for the HDF5 library.
+
+## Scope
+
+This gem currently provides practical high-level wrappers for:
+
+- opening and creating files
+- creating groups
+- creating, writing, and reading one-dimensional numeric datasets
+- reading attributes
+
+Unsupported at this stage:
+
+- string dataset read/write
+- attribute write
+- multidimensional array write
+
+## Supported HDF5 Versions
+
+- HDF5 1.10
+- HDF5 1.14
+- HDF5 2.x
+
+HDF5 versions older than 1.10 are not supported.
+
+## Install
+
+Add to your Gemfile:
+
+```ruby
+gem 'ruby-hdf5'
+```
+
+Install:
+
+```sh
+bundle install
+```
+
+System library (`libhdf5`) is required.
+
+## Runtime Notes
+
+- The gem loads `libhdf5` through FFI.
+- If the shared library cannot be found automatically, set `HDF5_LIB_PATH`.
+
+Examples:
+
+```sh
+# Point to a directory containing libhdf5.so
+export HDF5_LIB_PATH=/usr/lib
+
+# Or point directly to the shared object
+export HDF5_LIB_PATH=/usr/lib/libhdf5.so
+```
+
+## Quick Start
+
+### Read an existing file
+
+```ruby
+require 'hdf5'
+
+HDF5::File.open('example.h5') do |file|
+	group = file['foo']
+	dataset = group['bar_int']
+	p dataset.shape
+	p dataset.dtype
+	p dataset.read
+end
+```
+
+### Create and write a file
+
+```ruby
+require 'hdf5'
+
+HDF5::File.create('numbers.h5') do |file|
+	file.create_group('values') do |group|
+		group.create_dataset('ints', [1, 2, 3, 4])
+	end
+end
+
+reopened = HDF5::File.open('numbers.h5')
+p reopened['values']['ints'].read
+reopened.close
+```
+
+## Error Handling
+
+High-level API failures raise `HDF5::Error`.
+
+```ruby
+begin
+	HDF5::File.open('missing.h5')
+rescue HDF5::Error => e
+	warn e.message
+end
+```
+
+## Development
+
+After more than a decade, it is clear that the Ruby community does not have enough resources to sustainably maintain an HDF5 library. For that reason, development of this library is intentionally AI-assisted. Something is better than nothing.
+
+## Acknowledgement
+
+[https://github.com/edmundhighcock/hdf5](https://github.com/edmundhighcock/hdf5)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/hdf5/attribute.rb

@@ -0,0 +1,60 @@
+module HDF5
+  class Attribute
+    def initialize(dataset_id, attr_name)
+      @dataset_id = dataset_id
+      @attr_name = attr_name
+      @attr_id = FFI.H5Aopen(@dataset_id, @attr_name, 0)
+      raise 'Failed to open attribute' if @attr_id < 0
+    end
+
+    def read
+      type_id = FFI.H5Aget_type(@attr_id)
+      space_id = FFI.H5Aget_space(@attr_id)
+
+      size = FFI.H5Sget_simple_extent_npoints(space_id)
+
+      buffer = \
+        case FFI.H5Tget_class(type_id)
+        when :H5T_INTEGER
+          ::FFI::MemoryPointer.new(:int, size)
+        when :H5T_FLOAT
+          ::FFI::MemoryPointer.new(:double, size)
+        when :H5T_STRING
+          ::FFI::MemoryPointer.new(:pointer, size)
+        else
+          raise 'Unsupported data type'
+        end
+
+      status = FFI.H5Aread(@attr_id, type_id, buffer)
+      raise 'Failed to read attribute' if status < 0
+
+      case FFI.H5Tget_class(type_id)
+      when :H5T_INTEGER
+        buffer.read_array_of_int(size)
+      when :H5T_FLOAT
+        buffer.read_array_of_double(size)
+      when :H5T_STRING
+        buffer.read_pointer.read_string
+      else
+        raise 'Unsupported data type'
+      end
+    end
+
+    def close
+      FFI.H5Aclose(@attr_id)
+    end
+  end
+
+  class AttributeManager
+    def initialize(dataset_id)
+      @dataset_id = dataset_id
+    end
+
+    def [](attr_name)
+      attr = Attribute.new(@dataset_id, attr_name)
+      attr.read
+    ensure
+      attr.close if attr
+    end
+  end
+end

data/lib/hdf5/dataset.rb

@@ -0,0 +1,176 @@
+module HDF5
+  class Dataset
+    class << self
+      def create(parent_id, name, data)
+        values = normalize_data(data)
+        dims = ::FFI::MemoryPointer.new(:ulong_long, 1)
+        dims.write_array_of_ulong_long([values.length])
+        datatype_id = datatype_id_for(values)
+        dataspace_id = HDF5::FFI.H5Screate_simple(1, dims, nil)
+        raise HDF5::Error, "Failed to create dataspace for dataset: #{name}" if dataspace_id < 0
+
+        dataset = from_id(
+          HDF5::FFI.H5Dcreate2(parent_id, name, datatype_id, dataspace_id, HDF5::DEFAULT_PROPERTY_LIST,
+                               HDF5::DEFAULT_PROPERTY_LIST, HDF5::DEFAULT_PROPERTY_LIST), name
+        )
+        dataset.write(values)
+        return dataset unless block_given?
+
+        begin
+          yield dataset
+        ensure
+          dataset.close
+        end
+      ensure
+        HDF5::FFI.H5Sclose(dataspace_id) if dataspace_id && dataspace_id >= 0
+      end
+
+      def open(parent_id, name)
+        dataset = from_id(HDF5::FFI.H5Dopen2(parent_id, name, HDF5::DEFAULT_PROPERTY_LIST), name)
+        return dataset unless block_given?
+
+        begin
+          yield dataset
+        ensure
+          dataset.close
+        end
+      end
+
+      def normalize_data(data)
+        values = data.is_a?(Array) ? data : [data]
+        raise HDF5::Error, 'Dataset data must not be empty' if values.empty?
+        raise HDF5::Error, 'Nested arrays are not supported' if values.any? { |value| value.is_a?(Array) }
+
+        values
+      end
+
+      def datatype_id_for(data)
+        if data.all? { |value| value.is_a?(Integer) }
+          HDF5::FFI.H5T_NATIVE_INT
+        elsif data.all? { |value| value.is_a?(Numeric) }
+          HDF5::FFI.H5T_NATIVE_DOUBLE
+        else
+          raise HDF5::Error, 'Only numeric dataset data is supported'
+        end
+      end
+
+      def buffer_for(data)
+        if data.all? { |value| value.is_a?(Integer) }
+          buffer = ::FFI::MemoryPointer.new(:int, data.length)
+          buffer.write_array_of_int(data)
+        else
+          buffer = ::FFI::MemoryPointer.new(:double, data.length)
+          buffer.write_array_of_double(data.map(&:to_f))
+        end
+
+        buffer
+      end
+
+      private
+
+      def from_id(dataset_id, name)
+        dataset = allocate
+        dataset.send(:initialize_from_id, dataset_id, name)
+        dataset
+      end
+    end
+
+    def initialize(parent_id, name)
+      initialize_from_id(HDF5::FFI.H5Dopen2(parent_id, name, HDF5::DEFAULT_PROPERTY_LIST), name)
+    end
+
+    def attrs
+      @attrs ||= AttributeManager.new(@dataset_id)
+    end
+
+    def write(data)
+      values = self.class.normalize_data(data)
+      buffer = self.class.buffer_for(values)
+      mem_type_id = self.class.datatype_id_for(values)
+      status = HDF5::FFI.H5Dwrite(@dataset_id, mem_type_id, HDF5::DEFAULT_PROPERTY_LIST, HDF5::DEFAULT_PROPERTY_LIST,
+                                  HDF5::DEFAULT_PROPERTY_LIST, buffer)
+      raise HDF5::Error, 'Failed to write dataset' if status < 0
+
+      data
+    end
+
+    def close
+      return if @dataset_id.nil?
+
+      HDF5::FFI.H5Dclose(@dataset_id)
+      @dataset_id = nil
+    end
+
+    def dtype
+      datatype_id = HDF5::FFI.H5Dget_type(@dataset_id)
+      raise HDF5::Error, 'Failed to get datatype' if datatype_id < 0
+
+      HDF5::FFI.H5Tget_class(datatype_id)
+    ensure
+      HDF5::FFI.H5Tclose(datatype_id) if datatype_id && datatype_id >= 0
+    end
+
+    def shape
+      dataspace_id = HDF5::FFI.H5Dget_space(@dataset_id)
+      raise HDF5::Error, 'Failed to get dataspace' if dataspace_id < 0
+
+      ndims = HDF5::FFI.H5Sget_simple_extent_ndims(dataspace_id)
+      raise HDF5::Error, 'Failed to get number of dimensions' if ndims < 0
+
+      dims = ::FFI::MemoryPointer.new(:ulong_long, ndims)
+      HDF5::FFI.H5Sget_simple_extent_dims(dataspace_id, dims, nil)
+
+      dims.read_array_of_uint64(ndims)
+    ensure
+      HDF5::FFI.H5Sclose(dataspace_id) if dataspace_id && dataspace_id >= 0
+    end
+
+    def read
+      current_dtype = dtype
+      current_shape = shape
+
+      total_elements = current_shape.inject(:*)
+      case current_dtype
+      when :H5T_INTEGER
+        read_integer_data(total_elements)
+      when :H5T_FLOAT
+        read_float_data(total_elements)
+      when :H5T_STRING
+        read_string_data(total_elements)
+      else
+        raise HDF5::Error, 'Unsupported datatype'
+      end
+    end
+
+    def read_integer_data(total_elements)
+      buffer = ::FFI::MemoryPointer.new(:int, total_elements)
+      status = HDF5::FFI.H5Dread(@dataset_id, HDF5::FFI.H5T_NATIVE_INT, HDF5::DEFAULT_PROPERTY_LIST,
+                                 HDF5::DEFAULT_PROPERTY_LIST, HDF5::DEFAULT_PROPERTY_LIST, buffer)
+      raise HDF5::Error, 'Failed to read integer dataset' if status < 0
+
+      buffer.read_array_of_int(total_elements)
+    end
+
+    def read_float_data(total_elements)
+      buffer = ::FFI::MemoryPointer.new(:double, total_elements)
+      status = HDF5::FFI.H5Dread(@dataset_id, HDF5::FFI.H5T_NATIVE_DOUBLE, HDF5::DEFAULT_PROPERTY_LIST,
+                                 HDF5::DEFAULT_PROPERTY_LIST, HDF5::DEFAULT_PROPERTY_LIST, buffer)
+      raise HDF5::Error, 'Failed to read float dataset' if status < 0
+
+      buffer.read_array_of_double(total_elements)
+    end
+
+    def read_string_data(total_elements)
+      raise NotImplementedError
+    end
+
+    private
+
+    def initialize_from_id(dataset_id, name)
+      raise HDF5::Error, "Failed to open dataset: #{name}" if dataset_id < 0
+
+      @dataset_id = dataset_id
+      @name = name
+    end
+  end
+end

data/lib/hdf5/ffi.rb

@@ -0,0 +1,59 @@
+module HDF5
+  module FFI
+    extend ::FFI::Library
+
+    class << self
+      attr_reader :backend
+    end
+
+    begin
+      ffi_lib HDF5.lib_path
+    rescue LoadError => e
+      raise LoadError, "#{e}\nCould not find #{HDF5.lib_path}"
+    end
+
+    # @!macro attach_function
+    #   @!scope class
+    #   @!method $1(${2--2})
+    #   @return [${-1}] the return value of $0
+    def self.attach_function(*)
+      super
+    rescue ::FFI::NotFoundError => e
+      warn e.message # if $VERBOSE
+    end
+
+    def self.attach_variable(*)
+      super
+    rescue ::FFI::NotFoundError => e
+      warn e.message # if $VERBOSE
+    end
+
+    attach_function 'H5get_libversion', %i[
+      pointer
+      pointer
+      pointer
+    ], :int
+
+    major_ptr = ::FFI::MemoryPointer.new(:uint)
+    minor_ptr = ::FFI::MemoryPointer.new(:uint)
+    release_ptr = ::FFI::MemoryPointer.new(:uint)
+    HDF5::FFI.H5get_libversion(major_ptr, minor_ptr, release_ptr)
+
+    major = major_ptr.read_uint
+    minor = minor_ptr.read_uint
+    release = release_ptr.read_uint
+
+    @backend = case [major, minor]
+               in [1, 10..13]
+                 'ffi_10'
+               in [1, 14..]
+                 'ffi_14'
+               in [2.., _]
+                 'ffi_14'
+               else
+                 raise "Unsupported HDF5 version #{major}.#{minor}.#{release}"
+               end
+
+    require_relative @backend
+  end
+end