cumo 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48de893a0d01a5e8376c2a9cda402be28dd47835661f22bd69e7ed17561abed8
-  data.tar.gz: c403ffc7d25b80a0b50e8513b81439ee46f775cbd8c126667f83656077488a79
+  metadata.gz: f09e6c09816ea16f1a27425e44170c7ea191b771f0a3b26b2b7298a1e53b6e6c
+  data.tar.gz: f4739b41e92d5f5920ea694393f3ab71241e9b428a29416db71e91d5fcb0f13e
 SHA512:
-  metadata.gz: '00189a16920241771a70155a98d60c5d53b6fcd23bfcddbaed3094bbbe5d3476b2d6b5ce70f9d8d899e090a9bf3be2c4249c1b98b6d14360736a4a5ba1aa5594'
-  data.tar.gz: bd6a1c8b78837b387f93f5b57f13c26917c71c123a1441deff8e3afb7250a42bc799ded9271b9ad9d46d4c3b928660c38653f85427b024bd00797d6786535734
+  metadata.gz: d58332736efabf28caeec996882ceb99435885e41d017a40911c6a85346a4f03428e32cb7cae32e8dae9633e47f7497dc35075309ec32d61d607504ef5f61fb1
+  data.tar.gz: d276cc4b4d19203ab34bfae56e96dd6e3220a780f07d3da8934e9c9241336fcb31c2040e013a7e461b47ec93461dcff21ca126597742c184e52221c0112bf196

data/CHANGELOG.md

@@ -1,3 +1,51 @@
+# 0.14.0 (2026/10/18)
+
+Breaking changes:
+
+* `cumo.h` no longer defines `CUMO_VERSION` or `CUMO_VERSION_CODE`. `Cumo::VERSION` and `Cumo::NArray::VERSION` are defined in Ruby, and the new `Cumo::REVISION` tells a release gem from one built from a checkout: it gives `"v0.14.0"` for this release and something like `"v0.14.0-3-g1a2b3c4"` for a gem built at a later commit (PR #617)
+
+Fixes:
+
+* Fix a host loop such as `each_with_index` yielding the old values of an array after a kernel launched from its block through `Function#launch`, `ElementwiseKernel` or `ReductionKernel` wrote the array (PR #625)
+
+Changes:
+
+* Add `Cumo::FFT`, the functions of `numpy.fft` on cuFFT with numpy's arguments as keywords: `fft`, `ifft`, `rfft`, `irfft`, `hfft`, `ihfft`, `fft2`, `ifft2`, `rfft2`, `irfft2`, `fftn`, `ifftn`, `rfftn`, `irfftn`, `fftfreq`, `rfftfreq`, `fftshift` and `ifftshift`, and `fftconvolve`, which answers the full linear convolution as `scipy.signal.fftconvolve` does. Load it with `require "cumo/fft"`. Single precision stays single, as in CuPy. cuFFT is loaded the first time a transform runs, and `Cumo::CUDA::Cufft.available?` says whether it can be. A thread keeps up to 16 plans for each device, which `Cumo::CUDA::Cufft.plan_cache_info` and `clear_plan_cache` show and let go (PR #623, PR #622, PR #621, PR #620)
+* Add `Cumo::Pocketfft`, the functions of `Numo::Pocketfft` from numo-pocketfft on `Cumo::FFT`, with the same arguments, return types and errors. Load it with `require "cumo/pocketfft"`. A 0-dimensional array raises `Cumo::NArray::DimensionError`, where numo-pocketfft fails on it in a different way in each function (PR #623)
+* Add `Cumo::NArray.from_numo` and `Cumo::NArray.to_numo`, which copy an array between Numo and Cumo and keep its type, where `Cumo::NArray.cast` read the elements one by one through a Ruby Array and turned an SFloat into a DFloat (closes issue #87, PR #619)
+* `Cumo::Linalg.expm` of a dense matrix that needs squaring skips the check for a triangular matrix that 0.13.0 added, which makes a 64 x 64 expm about 8% faster in SFloat and 6% in DFloat (PR #618)
+
+# 0.13.0 (2026/10/12)
+
+Breaking changes:
+
+* An integer array raised to a negative integer power raises `Cumo::NArray::ValueError`, where it answered 0 even for a base of 1 or -1. numo-narray-alt now raises here too, as NumPy does. A signed integer exponent held in an array is checked on the device, so such a `**` now waits for its kernel, as integer division by an array does. An exponent array that holds `2**31` or more is no longer narrowed to 32 bits, so `Cumo::Int64[1] ** Cumo::Int64[2**31]` answers `[1]` where it answered `[0]` (PR #614)
+
+Fixes:
+
+* Fix `inspect` printing `(empty)` for a scalar cast to an array, such as `Cumo::DFloat.cast(5.0)`, and for its views, which it did since 0.5.10. Its value and the operators on it were right. Fix such an array that is frozen, as `Ractor.make_shareable` leaves it, raising `FrozenError` when read, and then answering 0 to some operators and its value to others (PR #616)
+* Fix a crash, or a read of the wrong memory, when a 0-dimensional array is indexed with nothing but `false`, `:rest` or `:~`, such as `Cumo::DFloat.cast(5.0)[false]` (PR #615)
+* Fix the cuDNN algorithm caches and the counters that deferred host reads and index fills wait on, which two Ractors could update at once. They now take a lock or advance atomically (PR #613)
+* Fix two Ractors calling `rand` or `rand_norm` at the same time drawing the same numbers. A single thread draws what it drew before, so `srand` still reproduces a sequence (PR #612)
+* Fix wrong results, an illegal memory access, or a process stuck at full GPU load when two Ractors call cuSOLVER at once, as `Cumo::Linalg.svdvals` and `eigvals` do. Each thread keeps its own workspace and frees it when it ends (PR #611)
+* Fix `Cumo::Linalg.expm` of a triangular matrix whose elements off the diagonal are far larger than those on it answering 1 on the diagonal. The diagonal and the first off-diagonal are now reset to their exact values after each squaring, as scipy does (PR #609)
+* Fix `Cumo::Linalg.expm` raising `FloatDomainError: Infinity` for a finite matrix whose 1-norm overflows. It still refuses such a matrix, and now says that its 1-norm overflowed (PR #603)
+* Fix `Cumo::Linalg.lu` and `matrix_power(a, 0)` raising `NoMethodError` for a Bit matrix. `P` and the identity are Bit matrices (PR #602)
+* Fix `Cumo::Linalg.lu` raising `ShapeError` for an empty matrix. It answers `P`, `L` and `U` of m x m, m x 0 and 0 x n, the shapes a nonempty matrix gets. numo-linalg-alt raises here (PR #601)
+
+Changes:
+
+* The first elementwise call on a type loads the kernels of one family rather than every elementwise kernel of the type. The families are arithmetic, common math functions, rare math functions, comparisons, stores from other types, and random numbers with polynomials. A first SFloat add takes 28 MB of host memory where it took 86 MB (PR #610)
+* `require "cumo"` no longer loads NVRTC. It is loaded from the CUDA that cumo was built against the first time `ElementwiseKernel`, `ReductionKernel` or `RawKernel` builds a kernel, which takes about 34 MB off the RSS after `require` (PR #607, PR #606)
+* `Cumo::Linalg.norm` of ord 1, -1, Infinity and -Infinity takes the magnitudes as it reduces rather than through `abs`, which makes it about 2.4 times faster on a 4096 x 4096 DFloat (PR #605)
+* `Cumo::Linalg.norm` of ord 2, -2 and `"nuc"` over stacked matrices of up to 32 rows and columns computes them in one batched call, about 7 times faster for 1000 DFloat matrices of 8 x 8. A stacked matrix that holds NaN or Infinity answers NaN, as the matrices past 32 do (PR #604)
+* `Cumo::Linalg.expm` of a small matrix reads its three norms in one wait, which makes it about 3% faster on a 64 x 64 DFloat (PR #600)
+* The factorizations in `Cumo::Linalg` free their column-major copies once used, so a small call reuses memory the GPU has touched: `lu_solve` of a 256 x 256 SFloat is about 8% faster (PR #599)
+* `repeat` builds its index in one Array: `repeat(2)` of a million elements is 3.4 times faster, and `repeat` with an Array of counts 2.2 times. The development setup checks `lib` with rubocop-performance (PR #598, PR #597)
+* `Cumo::Linalg.eig` and `svd` give cuSOLVER pinned host memory to work in, kept for the process up to 256 MiB: `eig` of a 4096 x 4096 SFloat is about 8% faster, and `svd` of an 8192 x 2048 SFloat about 5% (PR #596)
+* `Cumo::Linalg.expm` frees its temporary matrices as it goes rather than leaving about 40 a call to the garbage collector, which makes it about 15% faster on a 1024 x 1024 SFloat of large norm (PR #595)
+* The API docs show the parameters of overloaded methods such as `cast`, `store_binary` and `layer_norm`, where YARD warned 1,419 times (PR #608)
+
 # 0.12.0 (2026/10/04)
 
 Fixes:
@@ -503,7 +551,7 @@ Fixes:
 * Remove unnecessary debug code
 * Fix capability list
 * Build only with supported capabilities to reduce compilation time
-* Fix SEGV when calling {mean, var, stddev, rms} on a single-element array (#154)
+* Fix SEGV when calling `mean`, `var`, `stddev` or `rms` on a single-element array (#154)
 * Suppress warning message for deprecated declarations
 * Fix variable typo in complex log2 and log10 functions (#152)
 
@@ -545,7 +593,7 @@ Fixes:
 * Backport: fix macro: STORE_BIT STORE_BIT_STEP: requires mask to leave the lowest bit
 * Backport: fix NArray::Bit#any?,all?: empty array should return false
 * Backport: fix NArray::Bit#count_true/false: empty array should return zero
-* Backport: bug in NArray::Bit; fix bit operation in tmpl_bit/{store_bit,unary,binary}.c
+* Backport: bug in NArray::Bit; fix bit operation in `tmpl_bit/{store_bit,unary,binary}.c`
 * Fix typo
 * Backport 135: Make all empty arrays equal
 * Backport: minor fixes in na_get_result_dimension(), check_index_count()

data/README.md

@@ -97,6 +97,24 @@ end
 a = xm::DFloat.new(3,5).seq
 ```
 
+### Moving Arrays Between Numo And Cumo
+
+`Cumo::NArray.from_numo` copies a Numo array to the GPU, and `Cumo::NArray.to_numo` copies a Cumo array back to the host.
+The type keeps its name, so a `Numo::Int32` becomes a `Cumo::Int32` and back.
+Both copy the bytes, where `Cumo::NArray.cast` would read the elements one by one through a Ruby Array.
+A byte-swapped array arrives in host order.
+
+```ruby
+require 'numo/narray'
+require 'cumo/narray'
+
+a = Cumo::NArray.from_numo(Numo::SFloat.new(3,5).seq)  #=> Cumo::SFloat
+b = Cumo::NArray.to_numo(a * 2)                         #=> Numo::SFloat
+```
+
+Cumo does not depend on Numo. `to_numo` requires `numo/narray` when it is called, so Numo has to be installed for it.
+`HFloat`, `BFloat` and `RObject` raise `TypeError`, since Numo has no half-precision types and an `RObject` holds Ruby objects rather than bytes.
+
 ### Incompatibility With Numo
 
 Numo returns a Ruby numeric object wherever a result is 0-dimensional, while Cumo returns the 0-dimensional NArray itself.
@@ -312,11 +330,44 @@ Cumo differs from numo-linalg-alt in a few places on purpose:
 * `expm` scales and squares the way scipy does, after Al-Mohy and Higham, which stays accurate where the norm of the matrix is large. Passing the order of the Pade approximant, as in `expm(a, 3)`, keeps numo-linalg-alt's algorithm.
 * `norm` takes the 2-norm and the nuclear norm of matrices stacked along other axes, which numo-linalg-alt refuses.
 * `cond` checks `ord` before it inverts the matrix, so an invalid `ord` raises `ArgumentError` even for a singular matrix, where numo-linalg-alt raises `LapackError`.
+* `lu` answers for an empty matrix and for a `Bit` matrix, where numo-linalg-alt raises. P keeps the shape and the class it has for any other matrix: an m x m identity for an m x 0 matrix, where scipy answers a 0 x 0 one, and a `Bit` for a `Bit` matrix. `matrix_power(a, 0)` of a `Bit` matrix likewise answers a `Bit` identity.
 
 A function waits for the current stream when it answers a Ruby number, or when it reads back whether cuSOLVER could do its work.
 `solve`, `inv` and `det` read back whether the matrix was singular, `cho_fact` whether it was positive definite, and `eigh` and `svd` whether they converged.
 `matmul`, `dot` of two matrices, `matrix_power` to a positive power, `cholesky`, `cho_solve`, `qr` and `norm` along an axis wait for nothing, so a run of them is queued without the host waiting.
 
+### Fourier Transforms
+
+`require "cumo/fft"` brings in `Cumo::FFT`, the functions of `numpy.fft` on the GPU through cuFFT.
+They take numpy's arguments as keywords: `n:`, `axis:` and `norm:` for the one-dimensional transforms, and `s:`, `axes:` and `norm:` for the others.
+
+```ruby
+require "cumo/fft"
+
+x = Cumo::SFloat.new(1024).rand
+spectrum = Cumo::FFT.rfft(x)
+back = Cumo::FFT.irfft(spectrum, n: 1024)
+image = Cumo::FFT.fft2(Cumo::DComplex.new(256, 256).rand, norm: "ortho")
+freqs = Cumo::FFT.fftfreq(1024, d: 0.01)
+```
+
+The functions are `fft`, `ifft`, `rfft`, `irfft`, `hfft`, `ihfft`, `fft2`, `ifft2`, `rfft2`, `irfft2`, `fftn`, `ifftn`, `rfftn`, `irfftn`, `fftfreq`, `rfftfreq`, `fftshift` and `ifftshift`, as in numpy.
+`fftconvolve(a, b)` answers the full linear convolution, as `scipy.signal.fftconvolve` does in its `"full"` mode, and pads each axis to a length cuFFT computes fast on the way.
+Single precision stays single: `SFloat`, `SComplex`, `HFloat` and `BFloat` give `SComplex`, or `SFloat` for a real result, and every other type gives `DComplex` or `DFloat`, as in numpy 2 and CuPy.
+Errors follow numpy: an axis out of range raises `Cumo::NArray::DimensionError`, a transform of no points `ArgumentError`, and a complex input to `rfft` `TypeError`.
+
+Cumo looks for the cuFFT header when it is built, and loads the library the first time a transform runs, so `require "cumo"` does not pay for it.
+`Cumo::CUDA::Cufft.available?` answers whether it can be loaded.
+`fftfreq`, `rfftfreq`, `fftshift` and `ifftshift` work without it.
+
+A thread keeps up to 16 cuFFT plans for each device, and reuses one when a transform of the same type and shape comes again.
+`Cumo::CUDA::Cufft.plan_cache_info` answers how many plans it holds and how often they were reused, and `Cumo::CUDA::Cufft.clear_plan_cache` lets them go.
+A thread's plans also go when it ends, and when an allocation it makes from the memory pool runs out of memory.
+
+`require "cumo/pocketfft"` brings in `Cumo::Pocketfft`, the functions of `Numo::Pocketfft` from [numo-pocketfft](https://github.com/yoshoku/numo-pocketfft).
+They keep its single positional argument, its double precision results and the `ArgumentError`s it raises, so code written for numo-pocketfft runs on the GPU after the replacement of `Numo` with `Cumo` above.
+A 0-dimensional array raises `Cumo::NArray::DimensionError`, where numo-pocketfft fails on it in a different way in each function.
+
 ### Fused Operations
 
 `layer_norm`, `rms_norm` and `softmax` normalize along the last axis in one kernel each, and `quantize_symmetric` takes it to 8-bit integers in one more.

data/cumo.gemspec

@@ -3,7 +3,8 @@
 lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
-cumo_version = File.read(File.join(__dir__, "ext/cumo/include/cumo.h")).match(/CUMO_VERSION "([^"]+)"/)[1]
+# Requiring version.rb here would fix Cumo::REVISION to nil under bundle exec.
+cumo_version = File.read(File.join(__dir__, "lib/cumo/version.rb"))[/VERSION = "([^"]+)"/, 1]
 
 Gem::Specification.new do |spec|
   spec.name          = "cumo"
@@ -28,6 +29,14 @@ Gem::Specification.new do |spec|
   spec.files = `git ls-files -z`.split("\x0").reject do |f|
     f.start_with?(*%w[.github/ test/ examples/ bin/ bench/ docker- Dockerfile Gemfile .gitignore .rubocop])
   end
+
+  revision = begin
+    IO.popen(%W[git -C #{__dir__} describe --tags --match v[0-9]* --dirty --always], err: File::NULL, &:read).strip
+  rescue SystemCallError
+    ""
+  end
+  spec.metadata["cumo_revision"] = revision unless revision.empty?
+
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]

data/ext/cumo/cuda/cudnn_impl.cpp

@@ -11,6 +11,7 @@
 #include "cumo/cuda/runtime.h"
 #include "cumo/cuda/memory_pool.h"
 
+#include <mutex>
 #include <unordered_map>
 
 #if defined(__cplusplus)
@@ -387,13 +388,32 @@ struct AlgoCacheEntry {
 // Nothing may reach the C caller: it has no handler, so an escaping exception
 // is std::terminate. The cache only saves a later search, so one that cannot
 // grow leaves the answer this call already has.
+static std::mutex algo_cache_mutex_;
+
 template <typename Map>
 void StoreAlgoCache(Map& map, const AlgoCacheKey& key, const typename Map::mapped_type& entry) {
+    std::lock_guard<std::mutex> lock{algo_cache_mutex_};
     try {
         map[key] = entry;
     } catch (...) {
     }
 }
+
+template <typename Map, typename Perf>
+bool LookupAlgoCache(Map& map, const AlgoCacheKey& key, Perf* perf_result) {
+    std::lock_guard<std::mutex> lock{algo_cache_mutex_};
+    auto it = map.find(key);
+    if (it == map.end()) {
+        return false;
+    }
+    auto entry = it->second;
+    // clear the fields the search would have filled but the cache drops
+    *perf_result = {};
+    perf_result->algo = entry.algo;
+    perf_result->memory = entry.memory;
+    perf_result->mathType = entry.math_type;
+    return true;
+}
 }
 
 using FwdAlgoCacheMap = std::unordered_map<AlgoCacheKey, AlgoCacheEntry<cudnnConvolutionFwdAlgo_t>, AlgoCacheKeyHash>;
@@ -456,15 +476,7 @@ cumo_cuda_cudnn_FindConvolutionForwardAlgorithm(
                                 cudnn_dtype, max_workspace_size);
 
     auto& algo_cache_map = fwd_algo_cache_map_;
-    // TODO: thread-safe
-    auto it = algo_cache_map.find(key);
-    if (it != algo_cache_map.end()) {
-        auto entry = it->second;
-        // clear the fields the search would have filled but the cache drops
-        *perf_result = {};
-        perf_result->algo = entry.algo;
-        perf_result->memory = entry.memory;
-        perf_result->mathType = entry.math_type;
+    if (LookupAlgoCache(algo_cache_map, key, perf_result)) {
         return CUDNN_STATUS_SUCCESS;
     }
 
@@ -495,7 +507,6 @@ cumo_cuda_cudnn_FindConvolutionForwardAlgorithm(
     if (returned_algo_count < 1) return CUDNN_STATUS_NOT_SUPPORTED;
     if (perf_result->status != CUDNN_STATUS_SUCCESS) return perf_result->status;
 
-    // TODO: thread-safe
     StoreAlgoCache(algo_cache_map, key, {perf_result->algo, perf_result->memory, perf_result->mathType});
     return status;
 }
@@ -527,15 +538,7 @@ cumo_cuda_cudnn_FindConvolutionBackwardDataAlgorithm(
                                 cudnn_dtype, max_workspace_size);
 
     auto& algo_cache_map = bwd_data_algo_cache_map_;
-    // TODO: thread-safe
-    auto it = algo_cache_map.find(key);
-    if (it != algo_cache_map.end()) {
-        auto entry = it->second;
-        // clear the fields the search would have filled but the cache drops
-        *perf_result = {};
-        perf_result->algo = entry.algo;
-        perf_result->memory = entry.memory;
-        perf_result->mathType = entry.math_type;
+    if (LookupAlgoCache(algo_cache_map, key, perf_result)) {
         return CUDNN_STATUS_SUCCESS;
     }
 
@@ -566,7 +569,6 @@ cumo_cuda_cudnn_FindConvolutionBackwardDataAlgorithm(
     if (returned_algo_count < 1) return CUDNN_STATUS_NOT_SUPPORTED;
     if (perf_result->status != CUDNN_STATUS_SUCCESS) return perf_result->status;
 
-    // TODO: thread-safe
     StoreAlgoCache(algo_cache_map, key, {perf_result->algo, perf_result->memory, perf_result->mathType});
     return status;
 }
@@ -598,15 +600,7 @@ cumo_cuda_cudnn_FindConvolutionBackwardFilterAlgorithm(
                                 cudnn_dtype, max_workspace_size);
 
     auto& algo_cache_map = bwd_filter_algo_cache_map_;
-    // TODO: thread-safe
-    auto it = algo_cache_map.find(key);
-    if (it != algo_cache_map.end()) {
-        auto entry = it->second;
-        // clear the fields the search would have filled but the cache drops
-        *perf_result = {};
-        perf_result->algo = entry.algo;
-        perf_result->memory = entry.memory;
-        perf_result->mathType = entry.math_type;
+    if (LookupAlgoCache(algo_cache_map, key, perf_result)) {
         return CUDNN_STATUS_SUCCESS;
     }
 
@@ -637,7 +631,6 @@ cumo_cuda_cudnn_FindConvolutionBackwardFilterAlgorithm(
     if (returned_algo_count < 1) return CUDNN_STATUS_NOT_SUPPORTED;
     if (perf_result->status != CUDNN_STATUS_SUCCESS) return perf_result->status;
 
-    // TODO: thread-safe
     StoreAlgoCache(algo_cache_map, key, {perf_result->algo, perf_result->memory, perf_result->mathType});
     return status;
 }