halton 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 393f4cb4ab8e899f4c8db51c402096022d3adaf2094f201a450029ca0aec9bfa
+  data.tar.gz: dea785edce51a7a2249f209ff744748fc77ea426f34de9aa318d4acee5b3a814
+SHA512:
+  metadata.gz: 9174a270ab128d1bb8c1b67b2859155155c8e7f3bd26f15b58b6d92d2b3ccd5c68d15cc788b4118cbf9526ba711e96cce844eb38f82274826756bfb6eaada0df
+  data.tar.gz: 62665649ae6e0c70da6bcbbe70a9cde2257a4df7006815cc1d3382025758dd3c809b09042ecb8e72a451916fcacff341fa31f198909398fd2e1df35475f80838

data/README.rdoc

@@ -0,0 +1,45 @@
+= Halton
+
+A Ruby library for the fast generation of Halton sequences, a deterministic low
+discrepancy sequence that appears to be random. The uniform distribution and
+repeatability makes the sequence ideal for choosing sample points or placing
+objects in 2D or 3D space.
+
+  grid = 10.times.map {10.times.map {"."}}
+  Halton.each(2, 3).take(26).zip("A".."Z") do |(x, y), c|
+    grid[y * 10][x * 10] = c
+  end
+  grid.each {|row| puts row.join(" ")}
+
+Outputs:
+
+  . . R . . I . . . .
+  . L . . . . U C . .
+  X . . F . . . . . O
+  . . . J . A . . . .
+  . D . . . . M S . .
+  P . . . V . . . G .
+  . . B . . Y . . . .
+  . T . . . . E . K .
+  H . . . N . . . . W
+  . . . Z . Q . . . .
+
+The method of generation is adapted from "Fast, portable, and reliable
+algorithm for the calculation of Halton numbers" by Miroslav Kolář and Seamus F.
+O'Shea.
+
+== Install
+
+Install via Rubygems:
+
+  gem install halton
+
+or add it to your Gemfile if you're using Bundler:
+
+  gem "halton"
+
+and then run the bundle command to install.
+
+This gem requires a Rust compiler and the +cargo+ build tool to build the gem's
+native extension. See https://www.rust-lang.org/tools/install for how to
+install Rust. +cargo+ is usually part of the Rust installation.

data/ext/halton/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "halton"
+version = "0.1.0"
+authors = ["Mat Sadler <mat@sourcetagsandcodes.com>"]
+edition = "2018"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+halton = "0.2.1"
+lazy_static = "1"
+rutie = "0.8"

data/ext/halton/Rakefile

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+class RakeCargoHelper
+  attr_reader :gemname
+
+  def initialize(gemname)
+    @gemname = gemname
+  end
+
+  def self.command?(name)
+    exts = ENV["PATHEXT"] ? ENV["PATHEXT"].split(";") : [""]
+    ENV["PATH"].split(File::PATH_SEPARATOR).any? do |path|
+      exts.any? do |ext|
+        exe = File.join(path, "#{name}#{ext}")
+        File.executable?(exe) && !File.directory?(exe)
+      end
+    end
+  end
+
+  def self.rust_toolchain
+    str = `rustc --version --verbose`
+    info = str.lines.map {|l| l.chomp.split(/:\s+/, 2)}.drop(1).to_h
+    info["host"]
+  end
+
+  def self.cargo_target_dir
+    return @cargo_target_dir if defined? @cargo_target_dir
+
+    str = `cargo metadata --format-version 1 --offline --no-deps --quiet`
+    begin
+      require "json"
+      dir = JSON.parse(str)["target_directory"]
+    rescue LoadError # json is usually part of the stdlib, but just in case
+      /"target_directory"\s*:\s*"(?<dir>[^"]*)"/ =~ str
+    end
+    @cargo_target_dir = dir || "target"
+  end
+
+  def install_dir
+    File.expand_path(File.join("..", "..", "lib", gemname), __dir__)
+  end
+
+  def rust_name
+    prefix = "lib" unless Gem.win_platform?
+    suffix = RbConfig::CONFIG["target_os"] =~ /darwin/i ? ".dylib" : ".so"
+    "#{prefix}#{gemname}#{suffix}"
+  end
+
+  def ruby_name
+    "#{gemname}.#{RbConfig::CONFIG["DLEXT"]}"
+  end
+
+end
+
+task default: [:install, :clean]
+
+desc "set dev mode for subsequent task, run like `rake dev install`"
+task :dev do
+  @dev = true
+end
+
+desc "build gem native extension and copy to lib"
+task install: [:cd, :build] do
+  helper = RakeCargoHelper.new("halton")
+  profile_dir = @dev ? "debug" : "release"
+  source = File.join(RakeCargoHelper.cargo_target_dir, profile_dir, helper.rust_name)
+  dest = File.join(helper.install_dir, helper.ruby_name)
+  mkdir_p(helper.install_dir)
+  cp(source, dest)
+end
+
+desc "build gem native extension"
+task build: [:cargo, :cd] do
+  sh "cargo", "build", *("--release" unless @dev)
+end
+
+desc "clean up release build artifacts"
+task clean: [:cargo, :cd] do
+  # sh "cargo clean --release"
+end
+
+desc "clean up build artifacts"
+task clobber: [:cargo, :cd] do
+  sh "cargo clean"
+end
+
+desc "check for cargo"
+task :cargo do
+  raise <<-MSG unless RakeCargoHelper.command?("cargo")
+
+    This gem requires a Rust compiler and the `cargo' build tool to build the
+    gem's native extension. See https://www.rust-lang.org/tools/install for
+    how to install Rust. `cargo' is usually part of the Rust installation.
+  MSG
+
+  raise <<-MSG if Gem.win_platform? && RakeCargoHelper.rust_toolchain !~ /gnu/
+
+    Found Rust toolchain `#{RakeCargoHelper.rust_toolchain}' but the gem native
+    extension requires the gnu toolchain on Windows.
+  MSG
+end
+
+# ensure task is running in the right dir
+task :cd do
+  cd(__dir__) unless __dir__ == pwd
+end

data/ext/halton/src/lib.rs

@@ -0,0 +1,88 @@
+use lazy_static::lazy_static;
+use rutie::{
+    class, methods, module, wrappable_struct, AnyObject, Class, Float, Integer, Module, NilClass,
+    Object, VM,
+};
+
+macro_rules! unwrap_raise {
+    ($val:expr) => {
+        #[allow(clippy::redundant_closure)]
+        $val.map_err(|e| VM::raise_ex(e))
+            .expect("exception should have been raised")
+    };
+}
+
+macro_rules! raise {
+    ($class:ty, $($arg:tt)*) => {{
+        VM::raise(Class::from_existing(stringify!($class)), &format!($($arg)*));
+        unreachable!()
+    }};
+}
+
+fn any_object_or_nil<T>(obj: Option<T>) -> AnyObject
+where
+    T: Into<AnyObject>,
+{
+    obj.map(Into::into)
+        .unwrap_or_else(|| NilClass::new().into())
+}
+
+module!(Halton);
+
+methods!(
+    Halton,
+    rtself,
+    fn halton_number(base: Integer, index: Integer) -> Float {
+        Float::new(halton::number(
+            unwrap_raise!(base).to_u64() as u8,
+            unwrap_raise!(index).to_u64() as usize,
+        ))
+    }
+);
+
+wrappable_struct!(halton::Sequence, SequenceWrapper, SEQUENCE_WRAPPER);
+
+class!(Sequence);
+
+methods!(
+    Sequence,
+    rtself,
+    fn halton_sequence_new(base: Integer) -> AnyObject {
+        let seq = halton::Sequence::new(unwrap_raise!(base).to_u64() as u8);
+        Module::from_existing("Halton")
+            .get_nested_class("Sequence")
+            .wrap_data(seq, &*SEQUENCE_WRAPPER)
+    },
+    fn halton_sequence_next() -> Float {
+        let seq = rtself.get_data_mut(&*SEQUENCE_WRAPPER);
+        match seq.next() {
+            Some(f) => Float::new(f),
+            None => raise!(StopIteration, "iteration reached an end"),
+        }
+    },
+    fn halton_sequence_skip(n: Integer) -> NilClass {
+        let seq = rtself.get_data_mut(&*SEQUENCE_WRAPPER);
+        seq.nth(unwrap_raise!(n).to_u64() as usize);
+        NilClass::new()
+    },
+    fn halton_sequence_remaining() -> AnyObject {
+        let seq = rtself.get_data(&*SEQUENCE_WRAPPER);
+        any_object_or_nil(seq.size_hint().1.map(|i| Integer::new(i as i64)))
+    }
+);
+
+#[allow(non_snake_case)]
+#[no_mangle]
+pub extern "C" fn Init_halton() {
+    Module::new("Halton").define(|module| {
+        module.def_self("number", halton_number);
+        module
+            .define_nested_class("Sequence", None)
+            .define(|class| {
+                class.def_self("new", halton_sequence_new);
+                class.def("next", halton_sequence_next);
+                class.def("skip", halton_sequence_skip);
+                class.def("remaining", halton_sequence_remaining);
+            });
+    });
+}

data/lib/halton.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require_relative "halton/halton"
+
+# The Halton module provides methods for generating Halton sequences, a
+# deterministic low discrepancy sequence that appears to be random. The uniform
+# distribution and repeatability makes the sequence ideal for choosing sample
+# points or placing objects in 2D or 3D space.
+#
+#   grid = 10.times.map {10.times.map {"."}}
+#   Halton.each(2, 3).take(26).zip("A".."Z") do |(x, y), c|
+#     grid[y * 10][x * 10] = c
+#   end
+#   grid.each {|row| puts row.join(" ")}
+#
+# Outputs:
+#
+#   . . R . . I . . . .
+#   . L . . . . U C . .
+#   X . . F . . . . . O
+#   . . . J . A . . . .
+#   . D . . . . M S . .
+#   P . . . V . . . G .
+#   . . B . . Y . . . .
+#   . T . . . . E . K .
+#   H . . . N . . . . W
+#   . . . Z . Q . . . .
+#
+module Halton
+
+  ##
+  # :singleton-method: number
+  # :call-seq: Halton.number(base, index) -> int
+  #
+  # Returns the number at +index+ of the Halton sequence for +base+. The number
+  # returned will be > 0 and < 1, assuming +index+ > 1.
+  #
+  # While #each will be faster for most cases, this function may be
+  # useful for calulating a single number from a Halton sequence, or creating
+  # a 'leaped' sequence.
+  #
+  # 'leaped' Halton sequence:
+  #
+  #   step = 409;
+  #   i = 1;
+  #   while i < 10 * step
+  #     puts Halton.number(17, i)
+  #     i += step
+  #   end
+  #
+  # Beware that indexing #each is effectively 0-based, whereas the
+  # `index` argument for [`number`] is 1-based.
+  #
+  #   Halton.each(2).take(10)[2]   #=> 0.75
+  #   Halton.number(2, 3)          #=> 0.75
+
+  # :call-seq:
+  # Halton.each(base) {|n| ... }
+  # Halton.each(base_x, base_y) {|x, y| ... }
+  # Halton.each(base_x, base_y, base_z) {|x, y, z| ... }
+  # Halton.each(*bases) {|*n| ... }
+  # Halton.each(*bases) -> Enumerator
+  #
+  # Implements the fast generation of Halton sequences.
+  # The method of generation is adapted from "Fast, portable, and reliable
+  # algorithm for the calculation of Halton numbers" by Miroslav Kolář and
+  # Seamus F. O'Shea.
+  #
+  # The numbers yielded will be in the range > 0 and < 1.
+  #
+  def self.each(base, *bases)
+    return to_enum(__method__, base, *bases) unless block_given?
+
+    if bases.empty?
+      seq = Sequence.new(base)
+      loop {yield seq.next}
+      return nil
+    end
+
+    if bases.length == 1
+      x = Sequence.new(base)
+      y = Sequence.new(bases.first)
+      loop {yield x.next, y.next}
+      return nil
+    end
+
+    if bases.length == 2
+      x = Sequence.new(base)
+      y = Sequence.new(bases.first)
+      z = Sequence.new(bases.last)
+      loop {yield x.next, y.next, z.next}
+      return nil
+    end
+
+    seqs = bases.unshift(base).map {|b| Sequence.new(b)}
+    loop {yield(*seqs.map(&:next))}
+    nil
+  end
+
+  # Halton::Sequence implements the fast generation of Halton sequences.
+  # The method of generation is adapted from "Fast, portable, and reliable
+  # algorithm for the calculation of Halton numbers" by Miroslav Kolář and
+  # Seamus F. O'Shea.
+  #
+  # This class is implemented as a stateful iterator, a pattern not common in
+  # Ruby. The Halton::each method provides a more friendly interface to this
+  # class.
+  #
+  class Sequence
+
+    ##
+    # :singleton-method: new
+    # :call-seq: Sequence.new(base) -> sequence
+    #
+    # Create a new Halton::Sequence.
+
+    ##
+    # :method: next
+    # :call-seq: sequence.next -> int
+    #
+    # Get the next number in the sequence. The numbers will be in the range > 0
+    # and < 1.
+    #
+    # Will raise StopIteration when the sequence has ended.
+
+    ##
+    # :method: skip
+    # :call-seq: sequence.skip(n) -> nil
+    #
+    # Can be used to efficiently skip large sections of the sequence. For small
+    # values of +n+ simply advances the sequence +n+ times.
+    #
+
+    ##
+    # :method: remaining
+    # :call-seq: sequence.remaining -> int or nil
+    #
+    # Returns the count of the remaining numbers in the sequence. May return
+    # +nil+ if the count is larger than the host platform's native unsigned
+    # integer type.
+
+  end
+
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: halton
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- Mat Sadler
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-05-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '1'
+description: A module implementing the fast generation of Halton sequences. The method
+  of generation is adapted from "Fast, portable, and reliable algorithm for the calculation
+  of Halton number" by Miroslav Kolář and Seamus F. O'Shea.
+email:
+- mat@sourcetagsandcodes.com
+executables: []
+extensions:
+- ext/halton/Rakefile
+extra_rdoc_files:
+- README.rdoc
+files:
+- README.rdoc
+- ext/halton/Cargo.toml
+- ext/halton/Rakefile
+- ext/halton/src/lib.rs
+- lib/halton.rb
+homepage: https://github.com/matsadler/halton-rb
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options:
+- "--main"
+- README.rdoc
+- "--charset"
+- utf-8
+- "--exclude"
+- ext/**
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- Rust >= 1.51.0
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: A module for generating Halton sequences
+test_files: []