# Copyright (c) 1994 David I. Bell and Landon Curt Noll
# Permission is granted to use, distribute, or modify this source,
# provided that this copyright notice remains intact.

The following calc library files are provided because they serve as
examples of how use the calc language, and because the authors thought
them to be useful!

If you write something that you think is useful, please send it to:

    dbell@auug.org.au
    chongo@toad.com                 {uunet,pyramid,sun}!hoptoad!chongo

By convention, a lib file only defines and/or initializes functions,
objects and variables.  (The regression test is an exception.)  Also by
convention, the a usage message regarding each important object and
function is printed at the time of the read.

If a lib file needs to load another lib file, it should use the -once
version of read:

    /* pull in needed library files */
    read -once "surd"
    read -once "lucas"

This will cause the needed library files to be read once.  If these
files have already been read, the read -once will act as a noop.

By convention, the global variable  lib_debug  is used to control
the verbosity of debug information printed by lib files.  By default,
the lib_debug has a value of 0.  If lib_debug < 0, then no debug
messages are printed.  If lib_debug >= 0, then only usage message
regarding each important object are printed at the time of the read.
If lib_debug == 0, then only such usage messages are printed; no
other debug information is printed.

To conform to the above convention, your lib files should end with
lines of the form:

	global lib_debug;
	if (lib_debug >= 0) {
	    print "funcA(side_a, side_b, side_c) defined";
	    print "funcB(size, mass) defined";
	}


=-=


bernoulli.cal

    B(n)

    Calculate the nth Bernoulli number.


bigprime.cal

    bigprime(a, m, p)

    A prime test, base a, on p*2^x+1 for even x>m.


chrem.cal

    chrem(r1,m1 [,r2,m2, ...])
    chrem(rlist, mlist)

    Chinese remainder theorem/problem solver.


deg.cal

    dms(deg, min, sec)
    dms_add(a, b)
    dms_neg(a)
    dms_sub(a, b)
    dms_mul(a, b)
    dms_print(a)

    Calculate in degrees, minutes, and seconds.


ellip.cal

    factor(iN, ia, B, force)

    Attempt to factor using the elliptic functions: y^2 = x^3 + a*x + b.


lucas.cal

    lucas(h, n)

    Perform a primality test of h*2^n-1, with 1<=h<2*n.


lucas_chk.cal

    lucas_chk(high_n)

    Test all primes of the form h*2^n-1, with 1<=h<200 and n <= high_n.
    Requires lucas.cal to be loaded.  The highest useful high_n is 1000.


lucas_tbl.cal

    Lucasian criteria for primality tables.


mersenne.cal

    mersenne(p)

    Perform a primality test of 2^p-1, for prime p>1.


mod.cal

    mod(a)
    mod_print(a)
    mod_one()
    mod_cmp(a, b)
    mod_rel(a, b)
    mod_add(a, b)
    mod_sub(a, b)
    mod_neg(a)
    mod_mul(a, b)
    mod_square(a)
    mod_inc(a)
    mod_dec(a)
    mod_inv(a)
    mod_div(a, b)
    mod_pow(a, b)

    Routines to handle numbers modulo a specified number.


pell.cal

    pellx(D)
    pell(D)

    Solve Pell's equation; Returns the solution X to: X^2 - D * Y^2 = 1.
    Type the solution to pells equation for a particular D.


pi.cal

    qpi(epsilon)

    Calculate pi within the specified epsilon using the quartic convergence
    iteration.


pollard.cal

    factor(N, N, ai, af)

    Factor using Pollard's p-1 method.


poly.cal

    Calculate with polynomials of one variable.  There are many functions.
    Read the documentation in the library file.


psqrt.cal

    psqrt(u, p)

    Calculate square roots modulo a prime


quat.cal

    quat(a, b, c, d)
    quat_print(a)
    quat_norm(a)
    quat_abs(a, e)
    quat_conj(a)
    quat_add(a, b)
    quat_sub(a, b)
    quat_inc(a)
    quat_dec(a)
    quat_neg(a)
    quat_mul(a, b)
    quat_div(a, b)
    quat_inv(a)
    quat_scale(a, b)
    quat_shift(a, b)

    Calculate using quaternions of the form: a + bi + cj + dk.  In these
    functions, quaternians are manipulated in the form: s + v, where
    s is a scalar and v is a vector of size 3.


randmprime.cal

    randmprime(bits, seed [,dbg])

    Find a prime of the form h*2^n-1 >= 2^bits for some given x.  The initial
    search points for 'h' and 'n' are selected by a cryptographic pseudo-random
    number generator.  The optional argument, dbg, if set to 1, 2 or 3
    turn on various debugging print statements.


randrun.cal

    randrun([run_cnt])

    Perform the "G. Run test" (pp. 65-68) as found in Knuth's "Art of
    Computer Programming - 2nd edition", Volume 2, Section 3.3.2 on
    the builtin rand() function.  This function will generate run_cnt
    64 bit values.  By default, run_cnt is to test the next 65536
    random values.


randbitrun.cal

    randbitrun([run_cnt])

    Using randbit(1) to generate a sequence of random bits, determine if
    the number and kength of identical bits runs match what is expected.
    By default, run_cnt is to test the next 65536 random values.


regress.cal

    Test the correct execution of the calculator by reading this library file.
    Errors are reported with '****' mssages, or worse.  :-)


solve.cal

    solve(low, high, epsilon)

    Solve the equation f(x) = 0 to within the desired error value for x.
    The function 'f' must be defined outside of this routine, and the low
    and high values are guesses which must produce values with opposite signs.


sumsq.cal

    ss(p)

    Determine the unique two positive integers whose squares sum to the
    specified prime.  This is always possible for all primes of the form
    4N+1, and always impossible for primes of the form 4N-1.


surd.cal

    surd(a, b)
    surd_print(a)
    surd_conj(a)
    surd_norm(a)
    surd_value(a, xepsilon)
    surd_add(a, b)
    surd_sub(a, b)
    surd_inc(a)
    surd_dec(a)
    surd_neg(a)
    surd_mul(a, b)
    surd_square(a)
    surd_scale(a, b)
    surd_shift(a, b)
    surd_div(a, b)
    surd_inv(a)
    surd_sgn(a)
    surd_cmp(a, b)
    surd_rel(a, b)

    Calculate using quadratic surds of the form: a + b * sqrt(D).


test1000.cal

    This script is used by regress.cal to test the read and use keywords.


unitfrac.cal

    unitfrac(x)

    Represent a fraction as sum of distinct unit fractions.


varargs.cal

    sc(a, b, ...)

    Example program to use 'varargs'.  Program to sum the cubes of all
    the specified numbers.
