numo-gsl-integration 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24601b3a87462ee4bc6077999599478d3c08776b8da2caa648e56dbfaacec731
-  data.tar.gz: 97d7fe3772e374a35ab108ea0a4238fbbceb04598fc2637c3f4d76285cc17f66
+  metadata.gz: 57503e38512a38ad357142981868d2e2aea1a47743f27aee55d80625715eb794
+  data.tar.gz: d87dadfb371056e006cb1a914c6cebe81131cfa21c1e5f4daa35f72f377a98bf
 SHA512:
-  metadata.gz: 86447bf3974787c1067ceecacf700b3583fc2365fb0699f7fac10ed33c54b03c83a9ea5467598c0f9f687222d8ad6fed5c14feeca617d61d7ad39f01accb9ea1
-  data.tar.gz: 682f48569710825aac5fd2905dcfcab621abe47cea6f48f332b367d6da1747afe38512d08a6e84e1911b6ccd331d88fdb329b714bfa5619534ed8cea41227708
+  metadata.gz: ad109b9e20ce13a6eeb8b34b919c49a353eb5b27b158e74d1f9d149219fc200ca9a567417a12a4ea6dc66f247caf68bfe864d5cbaaf811b58fdacd8c8ef6ffbb
+  data.tar.gz: 6cab24c8607e941ab66eaa7f44db5492836c117649956979f148755df73792fd66c0baa794177276c02dd90e1e931d071cd0b19a174dd8d6dbb2c864da08e0cf

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-11-06
+
+### Added in 0.4.0
+
+- Added Lebedev quadrature for surface integration over the unit sphere.
+
+### Changed in 0.4.0
+
+- Required GNU Scientific Library 2.8 or later.
+
 ## [0.3.1] - 2026-11-06
 
 ### Changed in 0.3.1

data/README.md

@@ -5,7 +5,7 @@
 ## Requirements
 
 - [Ruby](https://www.ruby-lang.org/) 3.2 or later
-- GNU Scientific Library (GSL)
+- GNU Scientific Library (GSL) 2.8 or later
 - `gsl-config` available in `PATH`
 
   GSL itself must be installed separately.
@@ -61,6 +61,7 @@ end
 | `romberg` | Finite         | Smooth functions with extrapolated trapezoidal integration       |
 | `glfixed` | Finite         | Fixed-order Gauss-Legendre integration of smooth functions       |
 | `fixed`   | Rule-dependent | Fixed-order Gaussian quadrature with selectable weight functions |
+| `lebedev` | Unit sphere    | Lebedev quadrature over the surface of the unit sphere           |
 
 See [Integration routines](docs/routines.md) for parameters and examples.
 

data/docs/development.md

@@ -1,5 +1,13 @@
 # Development
 
+Development and builds require GSL 2.8 or later. Confirm the installed version before building:
+
+```bash
+gsl-config --version
+```
+
+The extension configuration stops with an error if `gsl-config` reports an older version or if the Lebedev integration API is unavailable.
+
 After checking out the repository, install the dependencies:
 
 ```bash

data/docs/routines.md

@@ -383,3 +383,28 @@ end
 ```
 
 The example result is `1.0 / 6.0`. Fixed point quadratures return only the integral. They do not accept absolute or relative error bounds and do not return an error estimate. Use an adaptive routine when the required order is not known in advance.
+
+## Lebedev integration on the unit sphere
+
+GSL [Lebedev quadrature](https://www.gnu.org/software/gsl/doc/html/integration.html#integrating-on-the-unit-sphere) approximates a surface integral over the unit sphere. `Numo::GSL::Integration.lebedev` passes the Cartesian coordinates of each quadrature point to the block:
+
+```ruby
+result = Numo::GSL::Integration.lebedev(26) do |x, y, z|
+  (x * x) + (y * y) + (z * z)
+end
+```
+
+Every point satisfies `x * x + y * y + z * z == 1` within floating-point precision, so the example integral has an exact value of `4.0 * Math::PI`.
+
+The argument is the number of Lebedev nodes. GSL 2.8 provides the following node counts:
+
+```text
+6, 14, 26, 38, 50, 74, 86, 110,
+146, 170, 194, 230, 266, 302, 350, 434,
+590, 770, 974, 1202, 1454, 1730, 2030, 2354,
+2702, 3074, 3470, 3890, 4334, 4802, 5294, 5810
+```
+
+The node count must be a positive integer and must identify one of the rules supplied by GSL. Unsupported node counts are reported as `Numo::GSL::GslError`.
+
+Lebedev integration returns only the surface integral. It does not accept an error tolerance and does not return an error estimate. Increasing the node count selects a rule that integrates spherical harmonics to a higher degree exactly.

data/ext/numo/gsl/integration/extconf.rb

@@ -1,13 +1,20 @@
 # frozen_string_literal: true
 
 require "mkmf"
+require "rubygems/version"
 
 gsl_config = find_executable("gsl-config")
 abort("gsl-config is required") unless gsl_config
 
+minimum_gsl_version = Gem::Version.new("2.8")
+gsl_version = Gem::Version.new(`#{gsl_config} --version`.strip)
+abort("GSL 2.8 or later is required (found #{gsl_version})") if gsl_version < minimum_gsl_version
+
 $CFLAGS << " #{`#{gsl_config} --cflags`.strip}"
 $libs = "#{`#{gsl_config} --libs`.strip} #{$libs}"
 
-abort("gsl/gsl_integration.h is required") unless have_header("gsl/gsl_integration.h")
+header = "gsl/gsl_integration.h"
+abort("#{header} is required") unless have_header(header)
+abort("GSL Lebedev integration support is required") unless have_func("gsl_integration_lebedev_alloc", header)
 
 create_makefile("numo/gsl/integration/integration")

data/ext/numo/gsl/integration/integration.c

@@ -45,4 +45,5 @@ void Init_integration(void) {
   rb_define_singleton_method(mIntegration, "romberg", integration_romberg, -1);
   rb_define_singleton_method(mIntegration, "glfixed", integration_glfixed, -1);
   rb_define_singleton_method(mIntegration, "fixed", integration_fixed, -1);
+  rb_define_singleton_method(mIntegration, "lebedev", integration_lebedev, 1);
 }

data/ext/numo/gsl/integration/integration_internal.h

@@ -3,6 +3,7 @@
 
 #include <gsl/gsl_errno.h>
 #include <gsl/gsl_integration.h>
+#include <gsl/gsl_math.h>
 #include <ruby.h>
 
 typedef struct {
@@ -52,5 +53,6 @@ VALUE integration_cquad(int argc, VALUE *argv, VALUE self);
 VALUE integration_romberg(int argc, VALUE *argv, VALUE self);
 VALUE integration_glfixed(int argc, VALUE *argv, VALUE self);
 VALUE integration_fixed(int argc, VALUE *argv, VALUE self);
+VALUE integration_lebedev(VALUE self, VALUE n_value);
 
 #endif

data/ext/numo/gsl/integration/lebedev.c

@@ -0,0 +1,103 @@
+#include "integration_internal.h"
+
+typedef struct {
+  VALUE block;
+  VALUE x;
+  VALUE y;
+  VALUE z;
+  VALUE exception;
+  gsl_integration_lebedev_workspace *workspace;
+  double result;
+  int state;
+} integration_lebedev_params;
+
+static VALUE integration_call_lebedev_block(VALUE data) {
+  integration_lebedev_params *params = (integration_lebedev_params *)data;
+  VALUE arguments[3] = {params->x, params->y, params->z};
+  VALUE value;
+
+  value = rb_funcallv(params->block, rb_intern("call"), 3, arguments);
+  return rb_Float(value);
+}
+
+static VALUE integration_free_lebedev_workspace(VALUE data) {
+  integration_lebedev_params *params = (integration_lebedev_params *)data;
+
+  if (params->workspace != NULL) {
+    gsl_integration_lebedev_free(params->workspace);
+  }
+
+  return Qnil;
+}
+
+static VALUE integration_run_lebedev(VALUE data) {
+  integration_lebedev_params *params = (integration_lebedev_params *)data;
+  double result = 0.0;
+  size_t i;
+
+  for (i = 0; i < params->workspace->n; ++i) {
+    VALUE value;
+
+    params->x = DBL2NUM(params->workspace->x[i]);
+    params->y = DBL2NUM(params->workspace->y[i]);
+    params->z = DBL2NUM(params->workspace->z[i]);
+    value = rb_protect(integration_call_lebedev_block, (VALUE)params,
+                       &params->state);
+
+    if (params->state != 0) {
+      params->exception = rb_errinfo();
+      break;
+    }
+
+    result += params->workspace->weights[i] * NUM2DBL(value);
+  }
+
+  params->result = 4.0 * M_PI * result;
+  return Qnil;
+}
+
+static VALUE integration_run_lebedev_with_workspace(VALUE data) {
+  integration_lebedev_params *params = (integration_lebedev_params *)data;
+
+  return rb_ensure(integration_run_lebedev, data,
+                   integration_free_lebedev_workspace, data);
+}
+
+VALUE integration_lebedev(VALUE self, VALUE n_value) {
+  integration_lebedev_params params = {0};
+  size_t n;
+  int state = 0;
+
+  (void)self;
+
+  if (!RB_INTEGER_TYPE_P(n_value)) {
+    rb_raise(rb_eTypeError, "n must be an Integer");
+  }
+  if (RTEST(rb_funcall(n_value, rb_intern("<="), 1, INT2FIX(0)))) {
+    rb_raise(rb_eArgError, "n must be positive");
+  }
+
+  n = NUM2SIZET(n_value);
+  params.block = rb_block_proc();
+  params.workspace = gsl_integration_lebedev_alloc(n);
+  if (params.workspace == NULL) {
+    rb_memerror();
+  }
+
+  rb_protect(integration_run_lebedev_with_workspace, (VALUE)&params, &state);
+
+  RB_GC_GUARD(params.block);
+  RB_GC_GUARD(params.x);
+  RB_GC_GUARD(params.y);
+  RB_GC_GUARD(params.z);
+  RB_GC_GUARD(params.exception);
+
+  if (params.state != 0) {
+    rb_exc_raise(params.exception);
+  }
+  if (state != 0) {
+    rb_jump_tag(state);
+  }
+
+  return DBL2NUM(params.result);
+}

data/lib/numo/gsl/integration/version.rb

@@ -3,7 +3,7 @@
 module Numo
   module GSL
     module Integration
-      VERSION = "0.3.1"
+      VERSION = "0.4.0"
     end
   end
 end

data/sig/numo/gsl/integration.rbs

@@ -116,6 +116,9 @@ module Numo
         ?alpha: Numeric,
         ?beta: Numeric
       ) { (Float) -> Numeric } -> Float
+      def self.lebedev: (Integer n) {
+        (Float, Float, Float) -> Numeric
+      } -> Float
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: numo-gsl-integration
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Takahiro SATOH
@@ -31,6 +31,7 @@ files:
 - ext/numo/gsl/integration/glfixed.c
 - ext/numo/gsl/integration/integration.c
 - ext/numo/gsl/integration/integration_internal.h
+- ext/numo/gsl/integration/lebedev.c
 - ext/numo/gsl/integration/options.c
 - ext/numo/gsl/integration/qag.c
 - ext/numo/gsl/integration/qagi.c