math/mpreduce.c: Add extensive commentary.

[u/mdw/catacomb] / math / mpreduce.c

/* -*-c-*-
 *
 * Efficient reduction modulo nice primes
 *
 * (c) 2004 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of Catacomb.
 *
 * Catacomb is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 *
 * Catacomb is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with Catacomb; if not, write to the Free
 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */

/*----- Header files ------------------------------------------------------*/

#include <mLib/darray.h>
#include <mLib/macros.h>

#include "mp.h"
#include "mpreduce.h"
#include "mpreduce-exp.h"

/*----- Data structures ---------------------------------------------------*/

DA_DECL(instr_v, mpreduce_instr);

/*----- Theory ------------------------------------------------------------*
 *
 * We're given a modulus %$p = 2^n - d$%, where %$d < 2^n$%, and some %$x$%,
 * and we want to compute %$x \bmod p$%.  We work in base %$2^w$%, for some
 * appropriate %$w$%.  The important observation is that
 * %$d \equiv 2^n \pmod p$%.
 *
 * Suppose %$x = x' + z 2^k$%, where %$k \ge n$%; then
 * %$x \equiv x' + d z 2^{k-n} \pmod p$%.  We can use this to trim the
 * representation of %$x$%; each time, we reduce %$x$% by a mutliple of
 * %$2^{k-n} p$%.  We can do this in two passes: firstly by taking whole
 * words off the top, and then (if necessary) by trimming the top word.
 * Finally, if %$p \le x < 2^n$% then %$0 \le x - p < p$% and we're done.
 *
 * A common trick, apparently, is to choose %$d$% such that it has a very
 * sparse non-adjacent form, and, moreover, that this form is nicely aligned
 * with common word sizes.  (That is, write %$d = \sum_{0\le i<m} d_i 2^i$%,
 * with %$d_i \in \{ -1, 0, +1 \}$% and most %$d_i = 0$%.)  Then adding
 * %$z d$% is a matter of adding and subtracting appropriately shifted copies
 * of %$z$%.
 *
 * Most libraries come with hardwired code for doing this for a few
 * well-known values of %$p$%.  We take a different approach, for two
 * reasons.
 *
 *   * Firstly, it privileges built-in numbers over user-selected ones, even
 *     if the latter have the right (or better) properties.
 *
 *   * Secondly, writing appropriately optimized reduction functions when we
 *     don't know the exact characteristics of the target machine is rather
 *     difficult.
 *
 * Our solution, then, is to `compile' the value %$p$% at runtime, into a
 * sequence of simple instructions for doing the reduction.
 */

/*----- Main code ---------------------------------------------------------*/

/* --- @mpreduce_create@ --- *
 *
 * Arguments:	@gfreduce *r@ = structure to fill in
 *		@mp *x@ = an integer
 *
 * Returns:	Zero if successful; nonzero on failure.
 *
 * Use:		Initializes a context structure for reduction.
 */

int mpreduce_create(mpreduce *r, mp *p)
{
  mpscan sc;
  enum { Z = 0, Z1 = 2, X = 4, X0 = 6 };
  unsigned st = Z;
  instr_v iv = DA_INIT;
  unsigned long d, i;
  unsigned op;
  size_t w, b, bb;

  /* --- Fill in the easy stuff --- */

  if (!MP_POSP(p))
    return (-1);
  d = mp_bits(p);
  r->lim = d/MPW_BITS;
  r->s = d%MPW_BITS;
  if (r->s)
    r->lim++;
  r->p = mp_copy(p);

  /* --- Stash a new instruction --- */

#define INSTR(op_, argx_, argy_) do {					\
  DA_ENSURE(&iv, 1);							\
  DA(&iv)[DA_LEN(&iv)].op = (op_);					\
  DA(&iv)[DA_LEN(&iv)].argx = (argx_);					\
  DA(&iv)[DA_LEN(&iv)].argy = (argy_);					\
  DA_EXTEND(&iv, 1);							\
} while (0)

  /* --- Main loop --- *
   *
   * A simple state machine decomposes @p@ conveniently into positive and
   * negative powers of 2.
   *
   * Here's the relevant theory.  The important observation is that
   * %$2^i = 2^{i+1} - 2^i$%, and hence
   *
   *   * %$\sum_{a\le i<b} 2^i = 2^b - 2^a$%, and
   *
   *   * %$2^c - 2^{b+1} + 2^b - 2^a = 2^c - 2^b - 2^a$%.
   *
   * The first of these gives us a way of combining a run of several one
   * bits, and the second gives us a way of handling a single-bit
   * interruption in such a run.
   *
   * We start with a number %$p = \sum_{0\le i<n} p_i 2^i$%, and scan
   * right-to-left using a simple state-machine keeping (approximate) track
   * of the two previous bits.  The @Z@ states denote that we're in a string
   * of zeros; @Z1@ means that we just saw a 1 bit after a sequence of zeros.
   * Similarly, the @X@ states denote that we're in a string of ones; and
   * @X0@ means that we just saw a zero bit after a sequence of ones.  The
   * state machine lets us delay decisions about what to do when we've seen a
   * change to the status quo (a one after a run of zeros, or vice-versa)
   * until we've seen the next bit, so we can tell whether this is an
   * isolated bit or the start of a new sequence.
   *
   * More formally: we define two functions %$Z^b_i$% and %$X^b_i$% as
   * follows.
   *
   *   * %$Z^0_i(S, 0) = S$%
   *   * %$Z^0_i(S, n) = Z^0_{i+1}(S, n)$%
   *   * %$Z^0_i(S, n + 2^i) = Z^1_{i+1}(S, n)$%
   *   * %$Z^1_i(S, n) = Z^0_{i+1}(S \cup \{ 2^{i-1} \}, n)$%
   *   * %$Z^1_i(S, n + 2^i) = X^1_{i+1}(S \cup \{ -2^{i-1} \}, n)$%
   *   * %$X^0_i(S, n) = Z^0_{i+1}(S, \{ 2^{i-1} \})$%
   *   * %$X^0_i(S, n + 2^i) = X^1_{i+1}(S \cup \{ -2^{i-1} \}, n)$%
   *   * %$X^1_i(S, n) = X^0_{i+1}(S, n)$%
   *   * %$X^1_i(S, n + 2^i) = X^1_{i+1}(S, n)$%
   *
   * The reader may verify (by induction on %$n$%) that the following
   * properties hold.
   *
   *   * %$Z^0_0(\emptyset, n)$% is well-defined for all %$n \ge 0$%
   *   * %$\sum Z^b_i(S, n) = \sum S + n + b 2^{i-1}$%
   *   * %$\sum X^b_i(S, n) = \sum S + n + (b + 1) 2^{i-1}$%
   *
   * From these, of course, we can deduce %$\sum Z^0_0(\emptyset, n) = n$%.
   *
   * We apply the above recurrence to build a simple instruction sequence for
   * adding an appropriate multiple of %$d$% to a given number.  Suppose that
   * %$2^{w(N-1)} \le 2^{n-1} \le p < 2^n \le 2^{wN}$%.  The machine which
   * interprets these instructions does so in the context of a
   * single-precision multiplicand @z@ and a pointer @v@ to the
   * %%\emph{most}%% significant word of an %$N + 1$%-word integer, and the
   * instruction sequence should add %$z d$% to this integer.
   *
   * The available instructions are named @MPRI_{ADD,SUB}{,LSL}@; they add
   * (or subtract) %$z$% (shifted left by some amount, in the @LSL@ variants)
   * to some word earlier than @v@.  The relevant quantities are encoded in
   * the instruction's immediate operands.
   */

#ifdef DEBUG
  for (i = 0, mp_scan(&sc, p); mp_step(&sc); i++) {
    switch (st | mp_bit(&sc)) {
      case  Z | 1: st = Z1; break;
      case Z1 | 0: st =	 Z; printf("+ %lu\n", i - 1); break;
      case Z1 | 1: st =	 X; printf("- %lu\n", i - 1); break;
      case  X | 0: st = X0; break;
      case X0 | 1: st =	 X; printf("- %lu\n", i - 1); break;
      case X0 | 0: st =	 Z; printf("+ %lu\n", i - 1); break;
    }
  }
  if (st >= X) printf("+ %lu\n", i - 1);
  st = Z;
#endif

  bb = MPW_BITS - (d + 1)%MPW_BITS;
  for (i = 0, mp_scan(&sc, p); i < d && mp_step(&sc); i++) {
    switch (st | mp_bit(&sc)) {
      case  Z | 1: st = Z1; break;
      case Z1 | 0: st =	 Z; op = MPRI_SUB; goto instr;
      case Z1 | 1: st =	 X; op = MPRI_ADD; goto instr;
      case  X | 0: st = X0; break;
      case X0 | 1: st =	 X; op = MPRI_ADD; goto instr;
      case X0 | 0: st =	 Z; op = MPRI_SUB; goto instr;
      instr:
	w = (d - i)/MPW_BITS + 1;
	b = (bb + i)%MPW_BITS;
	INSTR(op | !!b, w, b);
    }
  }

  /* --- This doesn't always work --- *
   *
   * If %$d \ge 2^{n-1}$% then the above recurrence will output a subtraction
   * as the final instruction, which may sometimes underflow.  (It interprets
   * such numbers as being in the form %$2^{n-1} + d$%.)  This is clearly
   * bad, so detect the situation and fail gracefully.
   */

  if (DA_LEN(&iv) && (DA(&iv)[DA_LEN(&iv) - 1].op & ~1u) == MPRI_SUB) {
    mp_drop(r->p);
    DA_DESTROY(&iv);
    return (-1);
  }

#undef INSTR

  /* --- Wrap up --- *
   *
   * Store the generated instruction sequence in our context structure.  If
   * %$p$%'s bit length %$n$% is a multiple of the word size %$w$% then
   * there's nothing much else to do here.  Otherwise, we have an additional
   * job.
   *
   * The reduction operation has three phases.  The first trims entire words
   * from the argument, and the instruction sequence constructed above does
   * this well; the second phase reduces an integer which has the same number
   * of words as %$p$%, but strictly more bits.  (The third phase is a single
   * conditional subtraction of %$p$%, in case the argument is the same bit
   * length as %$p$% but greater; this doesn't concern us here.)  To handle
   * the second phase, we create another copy of the instruction stream, with
   * all of the target shifts adjusted upwards by %$s = n \bmod w$%.
   *
   * In this case, we are acting on an %$(N - 1)$%-word operand, and so
   * (given the remarks above) must check that this is still valid, but a
   * moment's reflection shows that this must be fine: the most distant
   * target must be the bit %$s$% from the top of the least-significant word;
   * but since we shift all of the targets up by %$s$%, this now addresses
   * the bottom bit of the next most significant word, and there is no
   * underflow.
   */

  r->in = DA_LEN(&iv);
  if (!r->in)
    r->iv = 0;
  else if (!r->s) {
    r->iv = xmalloc(r->in * sizeof(mpreduce_instr));
    memcpy(r->iv, DA(&iv), r->in * sizeof(mpreduce_instr));
  } else {
    r->iv = xmalloc(r->in * 2 * sizeof(mpreduce_instr));
    for (i = 0; i < r->in; i++) {
      r->iv[i] = DA(&iv)[i];
      op = r->iv[i].op & ~1u;
      w = r->iv[i].argx;
      b = r->iv[i].argy;
      b += r->s;
      if (b >= MPW_BITS) {
	b -= MPW_BITS;
	w--;
      }
      if (b) op |= 1;
      r->iv[i + r->in].op = op;
      r->iv[i + r->in].argx = w;
      r->iv[i + r->in].argy = b;
    }
  }
  DA_DESTROY(&iv);

#ifdef DEBUG
  mpreduce_dump(r, stdout);
#endif
  return (0);
}

/* --- @mpreduce_destroy@ --- *
 *
 * Arguments:	@mpreduce *r@ = structure to free
 *
 * Returns:	---
 *
 * Use:		Reclaims the resources from a reduction context.
 */

void mpreduce_destroy(mpreduce *r)
{
  mp_drop(r->p);
  if (r->iv) xfree(r->iv);
}

/* --- @mpreduce_dump@ --- *
 *
 * Arguments:	@mpreduce *r@ = structure to dump
 *		@FILE *fp@ = file to dump on
 *
 * Returns:	---
 *
 * Use:		Dumps a reduction context.
 */

void mpreduce_dump(mpreduce *r, FILE *fp)
{
  size_t i;
  static const char *opname[] = { "add", "addshift", "sub", "subshift" };

  fprintf(fp, "mod = "); mp_writefile(r->p, fp, 16);
  fprintf(fp, "\n  lim = %lu; s = %d\n", (unsigned long)r->lim, r->s);
  for (i = 0; i < r->in; i++) {
    assert(r->iv[i].op < N(opname));
    fprintf(fp, "  %s %lu %lu\n",
	    opname[r->iv[i].op],
	    (unsigned long)r->iv[i].argx,
	    (unsigned long)r->iv[i].argy);
  }
  if (r->s) {
    fprintf(fp, "tail end charlie\n");
    for (i = r->in; i < 2 * r->in; i++) {
      assert(r->iv[i].op < N(opname));
      fprintf(fp, "  %s %lu %lu\n",
	      opname[r->iv[i].op],
	      (unsigned long)r->iv[i].argx,
	      (unsigned long)r->iv[i].argy);
    }
  }
}

/* --- @mpreduce_do@ --- *
 *
 * Arguments:	@mpreduce *r@ = reduction context
 *		@mp *d@ = destination
 *		@mp *x@ = source
 *
 * Returns:	Destination, @x@ reduced modulo the reduction poly.
 */

static void run(const mpreduce_instr *i, const mpreduce_instr *il,
		mpw *v, mpw z)
{
  for (; i < il; i++) {
#ifdef DEBUG
    mp vv;
    mp_build(&vv, v - i->argx, v + 1);
    printf("  0x"); mp_writefile(&vv, stdout, 16);
    printf(" %c (0x%lx << %u) == 0x",
	   (i->op & ~1u) == MPRI_ADD ? '+' : '-',
	   (unsigned long)z,
	   i->argy);
#endif
    switch (i->op) {
      case MPRI_ADD: MPX_UADDN(v - i->argx, v + 1, z); break;
      case MPRI_ADDLSL: mpx_uaddnlsl(v - i->argx, v + 1, z, i->argy); break;
      case MPRI_SUB: MPX_USUBN(v - i->argx, v + 1, z); break;
      case MPRI_SUBLSL: mpx_usubnlsl(v - i->argx, v + 1, z, i->argy); break;
      default:
	abort();
    }
#ifdef DEBUG
    mp_build(&vv, v - i->argx, v + 1);
    mp_writefile(&vv, stdout, 16);
    printf("\n");
#endif
  }
}

mp *mpreduce_do(mpreduce *r, mp *d, mp *x)
{
  mpw *v, *vl;
  const mpreduce_instr *il;
  mpw z;

#ifdef DEBUG
  mp *_r = 0, *_rr = 0;
#endif

  /* --- If source is negative, divide --- */

  if (MP_NEGP(x)) {
    mp_div(0, &d, x, r->p);
    return (d);
  }

  /* --- Try to reuse the source's space --- */

  MP_COPY(x);
  if (d) MP_DROP(d);
  MP_DEST(x, MP_LEN(x), x->f);

  /* --- Stage one: trim excess words from the most significant end --- */

#ifdef DEBUG
  _r = MP_NEW;
  mp_div(0, &_r, x, r->p);
  MP_PRINTX("x", x);
  _rr = 0;
#endif

  il = r->iv + r->in;
  if (MP_LEN(x) >= r->lim) {
    v = x->v + r->lim;
    vl = x->vl;
    while (vl-- > v) {
      while (*vl) {
	z = *vl;
	*vl = 0;
	run(r->iv, il, vl, z);
#ifdef DEBUG
	MP_PRINTX("x", x);
	mp_div(0, &_rr, x, r->p);
	assert(MP_EQ(_r, _rr));
#endif
      }
    }

    /* --- Stage two: trim excess bits from the most significant word --- */

    if (r->s) {
      while (*vl >> r->s) {
	z = *vl >> r->s;
	*vl &= ((1 << r->s) - 1);
	run(r->iv + r->in, il + r->in, vl, z);
#ifdef DEBUG
	MP_PRINTX("x", x);
	mp_div(0, &_rr, x, r->p);
	assert(MP_EQ(_r, _rr));
#endif
      }
    }
  }

  /* --- Stage three: conditional subtraction --- */

  MP_SHRINK(x);
  if (MP_CMP(x, >=, r->p))
    x = mp_sub(x, x, r->p);

  /* --- Done --- */

#ifdef DEBUG
  assert(MP_EQ(_r, x));
  mp_drop(_r);
  mp_drop(_rr);
#endif
  return (x);
}

/* --- @mpreduce_exp@ --- *
 *
 * Arguments:	@mpreduce *mr@ = pointer to reduction context
 *		@mp *d@ = fake destination
 *		@mp *a@ = base
 *		@mp *e@ = exponent
 *
 * Returns:	Result, %$a^e \bmod m$%.
 */

mp *mpreduce_exp(mpreduce *mr, mp *d, mp *a, mp *e)
{
  mp *x = MP_ONE;
  mp *spare = (e->f & MP_BURN) ? MP_NEWSEC : MP_NEW;

  MP_SHRINK(e);
  MP_COPY(a);
  if (MP_ZEROP(e))
    ;
  else {
    if (MP_NEGP(e))
      a = mp_modinv(a, a, mr->p);
    if (MP_LEN(e) < EXP_THRESH)
      EXP_SIMPLE(x, a, e);
    else
      EXP_WINDOW(x, a, e);
  }
  mp_drop(a);
  mp_drop(d);
  mp_drop(spare);
  return (x);
}

/*----- Test rig ----------------------------------------------------------*/


#ifdef TEST_RIG

#define MP(x) mp_readstring(MP_NEW, #x, 0, 0)

static int vreduce(dstr *v)
{
  mp *d = *(mp **)v[0].buf;
  mp *n = *(mp **)v[1].buf;
  mp *r = *(mp **)v[2].buf;
  mp *c;
  int ok = 1;
  mpreduce rr;

  mpreduce_create(&rr, d);
  c = mpreduce_do(&rr, MP_NEW, n);
  if (!MP_EQ(c, r)) {
    fprintf(stderr, "\n*** reduction failed\n*** ");
    mpreduce_dump(&rr, stderr);
    fprintf(stderr, "\n*** n = "); mp_writefile(n, stderr, 10);
    fprintf(stderr, "\n*** r = "); mp_writefile(r, stderr, 10);
    fprintf(stderr, "\n*** c = "); mp_writefile(c, stderr, 10);
    fprintf(stderr, "\n");
    ok = 0;
  }
  mpreduce_destroy(&rr);
  mp_drop(n); mp_drop(d); mp_drop(r); mp_drop(c);
  assert(mparena_count(MPARENA_GLOBAL) == 0);
  return (ok);
}

static int vmodexp(dstr *v)
{
  mp *p = *(mp **)v[0].buf;
  mp *g = *(mp **)v[1].buf;
  mp *x = *(mp **)v[2].buf;
  mp *r = *(mp **)v[3].buf;
  mp *c;
  int ok = 1;
  mpreduce rr;

  mpreduce_create(&rr, p);
  c = mpreduce_exp(&rr, MP_NEW, g, x);
  if (!MP_EQ(c, r)) {
    fprintf(stderr, "\n*** modexp failed\n*** ");
    fprintf(stderr, "\n*** p = "); mp_writefile(p, stderr, 10);
    fprintf(stderr, "\n*** g = "); mp_writefile(g, stderr, 10);
    fprintf(stderr, "\n*** x = "); mp_writefile(x, stderr, 10);
    fprintf(stderr, "\n*** c = "); mp_writefile(c, stderr, 10);
    fprintf(stderr, "\n*** r = "); mp_writefile(r, stderr, 10);
    fprintf(stderr, "\n");
    ok = 0;
  }
  mpreduce_destroy(&rr);
  mp_drop(p); mp_drop(g); mp_drop(r); mp_drop(x); mp_drop(c);
  assert(mparena_count(MPARENA_GLOBAL) == 0);
  return (ok);
}

static test_chunk defs[] = {
  { "reduce", vreduce, { &type_mp, &type_mp, &type_mp, 0 } },
  { "modexp", vmodexp, { &type_mp, &type_mp, &type_mp, &type_mp, 0 } },
  { 0, 0, { 0 } }
};

int main(int argc, char *argv[])
{
  test_run(argc, argv, defs, SRCDIR"/t/mpreduce");
  return (0);
}

#endif

/*----- That's all, folks -------------------------------------------------*/