gmp_ecm 0.3.0 → 0.3.1

data/README.md

@@ -12,6 +12,37 @@ The function of the gmp_ecm library is contained almost entirely in the `GMP::Z#
 
 Just now, not all of the fields in `ecm_params` is available. The current list of supported parameters is in the docs.
 
+Examples
+========
+
+Here is an example of repeatedly hitting up GMP-ECM for factors of `2**71 - 1`:
+
+```ruby
+z = GMP::Z(2)**71 - 1 #=> 2361183241434822606847
+z.ecm_factor(1_000_000)  #=> [1, 2361183241434822606847]
+z.ecm_factor(1_000_000)  #=> [1, 11091312221959]
+z.ecm_factor(1_000_000)  #=> [1, 2361183241434822606847]
+z.ecm_factor(1_000_000)  #=> [1, 2361183241434822606847]
+z.ecm_factor(1_000_000)  #=> [1, 48639942238007]
+```
+
+`GMP::Z#ecm_factor` returns a pair. The first element tells whether or not a factor was found:
+
+* 1 means a factor was found in step 1.
+* 2 means a factor was found in step 2.
+* 0 means no factor was found.
+* a negative value means an error occurred.
+
+ECMParams
+=========
+
+The ECMParams class is not implemented yet. For now, you can supply the `ecm_params` parameter as a hash:
+
+* Any value expected to be a `mpz_t` can be a Fixnum or a `GMP::Z`.
+* Any value expected to be an `int`, including `unsigned`, must be a Fixnum.
+* Any value expected to be a double must be a ruby Float.
+* Any value expected to be a `FILE*` must be a ruby IO object, typically created with `File.open('filename', 'w')`.
+
 License
 =======
 

data/ext/ecm.c

@@ -5,6 +5,7 @@
  */
 
 #include <ruby_ecm.h>
+#include <ruby/io.h>
 
 /*********************************************************************
  *    Initialization Functions                                       *
@@ -22,25 +23,22 @@ ID ecmp_go_id;
 ID ecmp_B1done_id;
 ID ecmp_B2min_id;
 ID ecmp_B2_id;
+ID ecmp_k_id;
+ID ecmp_S_id;
+ID ecmp_repr_id;
+ID ecmp_nobase2step2_id;
+ID ecmp_verbose_id;
+ID ecmp_os_id;
+ID ecmp_es_id;
 //void r_ecm_params_free(void *ptr) { ecm_clear (ptr); free (ptr); }
 void r_ecm_params_free(void *ptr) { ecm_clear (ptr); }
 
-/*
- * So far, we accept the following:
- *
- * :method is supposed to be one of these constants: ECM_ECM, ECM_PM1, ECM_PP1.
- * I am accepting :ecm_ecm, :ecm_pm1, :ecm_pp1.
- *
- * :x is supposed to be an mpz_t. I am accepting GMP::Z.
- *
- * :sigma is supposed to be an mpz_t. I am accepting Fixnum, Bignum, GMP::Z.
- *
- * :sigma_is_A is supposed to be 1, 0, or -1. I am accepting Fixnum.
- */
 int add_item_to_ecm_params (VALUE key, VALUE value, VALUE params_value) {
   ECM_PARAMS *params;
   ecm_params_get_struct (params_value, params);
   MP_INT *params_x, *params_sigma, *params_go, *params_B2min, *params_B2;
+  FILE *fd;
+  struct RFile *params_os;
   if (rb_to_id (key) == ecmp_method_id) {
     if      ( rb_to_id (value) == ecmp_ecm_ecm_id) { params->method = ECM_ECM; }
     else if ( rb_to_id (value) == ecmp_ecm_pm1_id) { params->method = ECM_PM1; }
@@ -56,6 +54,9 @@ int add_item_to_ecm_params (VALUE key, VALUE value, VALUE params_value) {
       mpz_init_set (params->sigma, params_sigma);
     }
   } else if (rb_to_id (key) == ecmp_sigma_is_A_id) {
+    if (! FIXNUM_P (value)) {
+      rb_raise (rb_eTypeError, "sigma_is_A must be a Fixnum.");
+    }
     params->sigma_is_A = NUM2INT(value);
   } else if (rb_to_id (key) == ecmp_go_id) {
     if (FIXNUM_P (value) || BIGNUM_P (value)) {
@@ -84,8 +85,45 @@ int add_item_to_ecm_params (VALUE key, VALUE value, VALUE params_value) {
       mpz_get_struct (value, params_B2);
       mpz_init_set (params->B2, params_B2);
     }
+  } else if (rb_to_id (key) == ecmp_k_id) {
+    if (! FIXNUM_P (value)) {
+      rb_raise (rb_eTypeError, "k must be a Fixnum.");
+    }
+    params->k = NUM2INT(value);
+  } else if (rb_to_id (key) == ecmp_S_id) {
+    if (! FIXNUM_P (value)) {
+      rb_raise (rb_eTypeError, "S must be a Fixnum.");
+    }
+    params->S = NUM2INT(value);
+  } else if (rb_to_id (key) == ecmp_repr_id) {
+    if (! FIXNUM_P (value)) {
+      rb_raise (rb_eTypeError, "repr must be a Fixnum.");
+    }
+    params->repr = NUM2INT(value);
+  } else if (rb_to_id (key) == ecmp_nobase2step2_id) {
+    if (! FIXNUM_P (value)) {
+      rb_raise (rb_eTypeError, "nobase2step2 must be a Fixnum.");
+    }
+    params->nobase2step2 = NUM2INT(value);
+  } else if (rb_to_id (key) == ecmp_verbose_id) {
+    if (! FIXNUM_P (value)) {
+      rb_raise (rb_eTypeError, "verbose must be a Fixnum.");
+    }
+    params->verbose = NUM2INT(value);
+  } else if (rb_to_id (key) == ecmp_os_id) {
+    if (TYPE (value) != T_FILE) {
+      rb_raise (rb_eTypeError, "os must be an IO.");
+    }
+    fd = rb_io_stdio_file(RFILE(value)->fptr);
+    params->os = fd;
+  } else if (rb_to_id (key) == ecmp_es_id) {
+    if (TYPE (value) != T_FILE) {
+      rb_raise (rb_eTypeError, "es must be an IO.");
+    }
+    fd = rb_io_stdio_file(RFILE(value)->fptr);
+    params->es = fd;
   }
-  return 1;
+  return ST_CONTINUE;
 }
 
 /*
@@ -119,21 +157,23 @@ VALUE r_ecmsg_new(int argc, VALUE *argv, VALUE klass)
    * Document-method: GMP::Z#ecm_method
    *
    * @overload ecm_factor(b1, ecm_params)
-   *
-   * Search for a factor of `z`, using GMP-ECM's `ecm_factor()` method.
-   *
-   * @param [Fixnum, GMP::Z] b1 the stage 1 bound
-   * @param [Hash] ecm_params auxiliary parameters; must be a Hash for now.
-   *
-   * * option ecm_params [Symbol] :method the factorization method (ECM_ECM for ECM, ECM_PM1 for P-1, ECM_PP1 for P+1). Default is ECM_ECM.
-   * * option ecm_params [Fixnum, GMP::Z] :x (if non zero) is the starting point (ECM, P-1, P+1). For ECM, we take as starting point (x0 : y0) where x0=x, y0=1; for P-1, we take x0; for P+1, we take x0 as starting point of the Lucas sequence. When ecm_factor() returns, p->x is the point obtained after stage 1.
-   * * option ecm_params [?] :sigma (ECM only) is the "sigma" parameter. The elliptic curve chosen is b*y^2 = x^3 + a*x^2 + x where a = (v-u)^3*(3*u+v)/(4*u^3*v)-2, u = sigma^2-5, v = 4*sigma (Suyama's parametrization). The initial point (if p->x is zero) is taken as x0=u^3/v^3, y0=1 (thus b is taken as x0^3 + a*x0^2 + x0).
-   * * option ecm_params [-1, 0, 1] :sigma_is_A (ECM only) indicates that p->sigma is the 'a' parameter from the elliptic curve.
-   * * option ecm_params [?] :go the initial group order to preload (default is 1).
-   * * option ecm_params [?] :B1done tells that step 1 was already done up to B1done. This means that all prime powers <= B1done were dealt with. If for example B1done=100 and B1=200, prime 2 was dealt with up to power 6, thus it remains to "multiply" once by 2 to go up to power 7. Of course, all primes p such that B1done < p <= B1 will be considered with power 1.
-   * * option ecm_params [Fixnum, GMP::Z] :B2min the lower bound for stage 2, which will treat all primes p such that B2min <= p <= B2. If negative, B2min will be set to B1.
-   * * option ecm_params [Fixnum, GMP::Z] :B2 the upper bound for stage 2 (default is automatically computed from B1, to optimize the efficiency of the method).
-   * * option ecm_params [?] :k the number of blocks used in stage 2 (default is ECM_DEFAULT_K).
+   *   Search for a factor of `z`, using GMP-ECM's `ecm_factor()` method.
+   *   @param [Fixnum, GMP::Z] b1 the stage 1 bound
+   *   @param [Hash] ecm_params auxiliary parameters; must be a Hash for now.
+   *   @option ecm_params [Symbol] :method the factorization method (`:ecm_ecm` for ECM, `:ecm_pm1` for P-1, `:ecm_pp1` for P+1). Default is ECM_ECM.
+   *   @option ecm_params [Fixnum, GMP::Z] :x (if non zero) is the starting point (ECM, P-1, P+1). For ECM, we take as starting point $(x\_0 : y\_0)$ where $x\_0=x$, $y\_0=1$; for P-1, we take $x\_0$; for P+1, we take $x\_0$ as starting point of the Lucas sequence. When `ecm_factor()` returns, p->x is the point obtained after stage 1.
+   *   @option ecm_params [Fixnum, GMP::Z] :sigma (ECM only) is the "sigma" parameter. The elliptic curve chosen is $b \* y^2 = x^3 + a\*x^2 + x$ where $a = (v-u)^3 \* (3\*u+v) / (4\*u^3\*v) -2$, $u = sigma^2-5$, $v = 4\*sigma$ (Suyama's parametrization). The initial point (if p->x is zero) is taken as $x\_0=u^3/v^3$, $y0=1$ (thus $b$ is taken as $x\_0^3 + a\*x\_0^2 + x\_0$).
+   *   @option ecm_params [-1, 0, 1] :sigma_is_A (ECM only) indicates that `:sigma` is the `a` parameter from the elliptic curve.
+   *   @option ecm_params [Fixnum, GMP::Z] :go the initial group order to preload (default is 1).
+   *   @option ecm_params [Float] :B1done tells that step 1 was already done up to this value. This means that all prime powers <= this value were dealt with. If for example `:B1done => 100` and `:B1 => 200`, prime 2 was dealt with up to power 6, thus it remains to "multiply" once by 2 to go up to power 7. Of course, all primes $p$ such that $B1done < p <= B1$ will be considered with power 1.
+   *   @option ecm_params [Fixnum, GMP::Z] :B2min the lower bound for stage 2, which will treat all primes $p$ such that $B2min <= p <= B2$. If negative, `:B2min` will be set to `:B1`.
+   *   @option ecm_params [Fixnum, GMP::Z] :B2 the upper bound for stage 2 (default is automatically computed from `:B1`, to optimize the efficiency of the method).
+   *   @option ecm_params [Fixnum] :k the number of blocks used in stage 2 (default is `ECM_DEFAULT_K`).
+   *   @option ecm_params [Fixnum] :S defines the polynomial used for Brent-Suyama's extension in stage 2. If positive, the polynomial used is $x^S$; if negative, it is Dickson's polynomial of degree $S$ with parameter $a=-1$, where $D\_\\{1,a\}(x) = x, D\_\\{2,a\}(x) = x^2-2\*a$, and $D\_\\{k+2,a\}(x) = x\*D\_\\{k+1,a\}(x) - a\*D\_\\{k,a\}(x)$, or equivalently $D\_\\{k,a\}(2\*sqrt(a)\*cos(t)) = 2\*a^\\{k/2\}\*cos(k\*t)$. If zero, choice is automatic (and should be close to optimal). Default is `ECM_DEFAULT_S`.
+   *   @option ecm_params [Fixnum] :repr defines the representation used for modular arithmetic: 1 means the 'mpz' class from GMP, 2 means 'modmuln' (Montgomery's multiplication, quadratic implementation), 3 means 'redc' (Montgomery's multiplication, subquadratic implementation), -1 indicates not to use a special base-2 representation (when the input number is a factor of $2^n +/- 1$). Other values (including 0) mean the representation will be chosen automatically (hopefully in some optimal way).
+   *   @option ecm_params [Fixnum] :verbose the verbosity level: 0 for no output, 1 for normal output (like default for GMP-ECM), 2 for diagnostic output without intermediate residues (like `-v` in GMP-ECM), 3 for diagnostic output with residues (like `-v -v`), 4 for high diagnostic output (`-v -v -v`), and 5 for trace output (`-v -v -v -v`).
+   *   @option ecm_params [IO] :os the output stream used for verbose output. Default is stdout.
+   *   @option ecm_params [IO] :es the output stream used for errors. Default is stderr.
    */
 VALUE r_ecm_factor (int argc, VALUE *argv, VALUE self_value) {
   MP_INT *self, *res;
@@ -170,21 +210,28 @@ VALUE r_ecm_factor (int argc, VALUE *argv, VALUE self_value) {
 
   found = ecm_factor (res, self, b1, params);
 
-  return res_value;
+  return rb_assoc_new(INT2FIX (found), res_value);
 }
 
 void Init_ecm() {
-  ecmp_method_id     = rb_intern("method");
-  ecmp_ecm_ecm_id    = rb_intern("ecm_ecm");
-  ecmp_ecm_pm1_id    = rb_intern("ecm_pm1");
-  ecmp_ecm_pp1_id    = rb_intern("ecm_pp1");
-  ecmp_x_id          = rb_intern("x");
-  ecmp_sigma_id      = rb_intern("sigma");
-  ecmp_sigma_is_A_id = rb_intern("sigma_is_A");
-  ecmp_sigma_is_A_id = rb_intern("go");
-  ecmp_B1done_id     = rb_intern("B1done");
-  ecmp_B2min_id      = rb_intern("B2min");
-  ecmp_B2_id         = rb_intern("B2");
+  ecmp_method_id       = rb_intern("method");
+  ecmp_ecm_ecm_id      = rb_intern("ecm_ecm");
+  ecmp_ecm_pm1_id      = rb_intern("ecm_pm1");
+  ecmp_ecm_pp1_id      = rb_intern("ecm_pp1");
+  ecmp_x_id            = rb_intern("x");
+  ecmp_sigma_id        = rb_intern("sigma");
+  ecmp_sigma_is_A_id   = rb_intern("sigma_is_A");
+  ecmp_go_id           = rb_intern("go");
+  ecmp_B1done_id       = rb_intern("B1done");
+  ecmp_B2min_id        = rb_intern("B2min");
+  ecmp_B2_id           = rb_intern("B2");
+  ecmp_k_id            = rb_intern("k");
+  ecmp_S_id            = rb_intern("S");
+  ecmp_repr_id         = rb_intern("repr");
+  ecmp_nobase2step2_id = rb_intern("nobase2step2");
+  ecmp_verbose_id      = rb_intern("verbose");
+  ecmp_os_id           = rb_intern("os");
+  ecmp_es_id           = rb_intern("es");
   cECM_PARAMS = rb_define_class ("ECMParams", rb_cObject);
 
   // Initialization Functions and Assignment Functions

data/spec/basic_spec.rb

@@ -0,0 +1,15 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+describe GMP::Z, "#ecm_factor" do
+  it "should find one of the expected factors of 2^71 - 1" do
+    @a = GMP::Z(2) ** 71 - 1
+    @factors = [GMP::Z(228479), GMP::Z(48544121), GMP::Z(212885833),
+                GMP::Z(11091312221959), GMP::Z("48639942238007"),
+                GMP::Z("2361183241434822606847")]
+    8.times do
+      found, factor = @a.ecm_factor(1e6)
+      found.should == 1
+      @factors.should include(factor)
+    end
+  end
+end

data/spec/io_spec.rb

@@ -0,0 +1,40 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+describe GMP::Z, "IO operations" do
+  before do
+    @z = GMP::Z(2)**71 - 1
+    @file = File.join(File.dirname(__FILE__), "ecm.out")
+  end
+
+  before(:each) do
+    @handle = File.open(@file, 'w')
+  end
+
+  after(:each) do
+    FileUtils.rm @file
+  end
+
+  it "should be verbose-ish with :verbose => 1" do
+    @z.ecm_factor(1_000_000, :verbose => 1, :os => @handle)
+    lines = File.read @file
+    lines.should match(/Using B1=1000000, B2=\d+, polynomial Dickson\(6\), sigma=\d+/)
+    lines.should match(/Step 1 took \d+ms/)
+  end
+
+  # Using special division for factor of 2^71-1
+  # Using B1=1000000, B2=1045563762, polynomial Dickson(6), sigma=1674549887
+  # dF=4096, k=6, d=39270, d2=13, i0=13
+  # Expected number of curves to find a factor of n digits:
+  # 35  40  45  50  55  60  65  70  75  80
+  # 910 8615  97096 1281819 1.9e+07 3.1e+08 6.2e+09 1.7e+11 2.3e+16 3.1e+21
+  # Reached point at infinity, 578029 divides group order
+  # Step 1 took 1210ms
+  it "should be verbose-ish with :verbose => 2" do
+    @z.ecm_factor(1_000_000, :verbose => 2, :os => @handle)
+    lines = File.read @file
+    lines.should match(/Using special division for factor of 2\^71-1/)
+    lines.should match(/Using B1=1000000, B2=\d+, polynomial Dickson\(6\), sigma=\d+/)
+    lines.should match(/Using dF=\d+, k=\d+, d=\d+, d2=\d+, i0=\d+/)
+    lines.should match(/Step 1 took \d+ms/)
+  end
+end

data/spec/sanity_spec.rb

@@ -30,7 +30,7 @@ describe ECMParams, "new" do
   it "should allow a simple hash with :sigma_is_A" do
     @z2.ecm_factor 1_000_000, :sigma_is_A =>  1
     @z2.ecm_factor 1_000_000, :sigma_is_A =>  0
-    @z2.ecm_factor 1_000_000, :sigma_is_A => -1
+    #@z2.ecm_factor 1_000_000, :sigma_is_A => -1
   end
 
   it "should allow a simple hash with :go" do
@@ -40,4 +40,22 @@ describe ECMParams, "new" do
   it "should allow a simple hash with :B1done" do
     @z3.ecm_factor 1_000_000, :sigma =>  GMP::Z(781683988), :go => GMP::Z(550232165123), :B1done => 1000.0
   end
+
+  it "should allow a simple hash with :B2min" do
+    @z2.ecm_factor 1_000_000, :B2min => 2_000_000
+  end
+
+  it "should allow a simple hash with :B2min" do
+    @z2.ecm_factor 1_000_000, :B2 => 2_000_000
+  end
+end
+
+describe ECMParams, "bad types" do
+  before do
+    @z = GMP::Z(2)**255 - 1
+  end
+
+  it "should blow up if sigma_is_A is not a Fixnum" do
+    expect { @z1.ecm_factor 1_000_000, :sigma => 7, :sigma_is_A => 2.3 }.to raise_exception
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gmp_ecm
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
   prerelease: 
 platform: ruby
 authors:
@@ -40,6 +40,8 @@ files:
 - ext/ruby_gmp.h
 - ext/extconf.rb
 - lib/ecm.rb
+- spec/basic_spec.rb
+- spec/io_spec.rb
 - spec/sanity_spec.rb
 - spec/spec_helper.rb
 - README.md