spire.algebra

A semigroup/monoid/group action of G on P is the combination of compatible left and right actions, providing:

 - the implementation of a method `actl(g, p)`, or `g |+|> p`, such that:

1. `(g |+| h) |+|> p === g |+|> (h |+|> p)` for all `g`, `h` in `G` and `p` in `P`.

2. `id |+|> p === p` for all `p` in `P` (if `id` is defined)

 - the implementation of a method `actr(p, g)`, or `p <|+| g`, such that:

3. `p <|+| (g |+| h) === (p <|+| g) <|+| h` for all `g`, `h` in `G` and `p` in `P`.

4. `p <|+| id === p` for all `p` in `P` (if `id` is defined)

In addition, if `G` is a group, left and right actions are compatible:

5. `g |+|> p === p <|+| g.inverse`.

A module over a commutative ring has by definition equivalent left and right modules.

In addition to the laws above 1-5 left and 1-5 right, we have:

6. (r *: x) :* s = r *: (x :* s)

EuclideanRing implements a Euclidean domain.

The formal definition says that every euclidean domain A has (at least one) euclidean function f: A -> N (the natural numbers) where:

(for every x and non-zero y) x = yq + r, and r = 0 or f(r) < f(y).

This generalizes the Euclidean division of integers, where f represents a measure of length (or absolute value), and the previous equation represents finding the quotient and remainder of x and y. So:

 quot(x, y) = q
 mod(x, y) = r

Field type class. While algebra already provides one, we provide one in Spire that integrates with the commutative ring hierarchy, in particular GCDRing and EuclideanRing.

On a field, all nonzero elements are invertible, so the remainder of the division is always 0. The Euclidean function can take an arbitrary value on nonzero elements (it is undefined for zero); for compatibility with the degree of polynomials, we use the constant 0.

The GCD and LCM are defined up to a unit; on a field, it means that either the GCD or LCM can be fixed arbitrarily. Some conventions with consistent defaults are provided in the spire.algebra.Field companion object.

A FieldAlgebra is a vector space that is also a Ring. An example is the complex numbers.

GCDRing implements a GCD ring.

For two elements x and y in a GCD ring, we can choose two elements d and m such that:

d = gcd(x, y)
m = lcm(x, y)
d * m = x * y

Additionally, we require:

gcd(0, 0) = 0
lcm(x, 0) = lcm(0, x) = 0

and commutativity:

gcd(x, y) = gcd(y, x)
lcm(x, y) = lcm(y, x)

Describes an involution, which is an operator that satisfies f(f(x)) = x (rule i).

If a multiplicative semigroup is available, it describes an antiautomorphism (rule ii); on a multiplicative monoid, it preserves the identity (rule iii).

If a ring is available, it should be compatible with addition (rule iv), and then defines a *-ring (see https://en.wikipedia.org/wiki/%2A-algebra ).

   i. adjoint(adjoint(x)) = x
   ii. adjoint(x*y) = adjoint(y)*adjoint(x) (with an underlying multiplicative semigroup)
 iii. adjoint(1) = 1 (with an underlying multiplicative monoid)
   iv. adjoint(x+y) = adjoint(x)+adjoint(y) (with an underlying ring)

A *-algebra is an associative algebra A over a commutative *-ring R, where A has an involution as well. It satisfies, for x: A, y: A and r: R

   v. adjoint(r * x + y) = adjoint(r)*adjoint(x) + adjoint(y)

A simple type class for numeric types that are a subset of the reals.

A (left) semigroup/monoid/group action of G on P is simply the implementation of a method actl(g, p), or g |+|> p, such that:

1. `(g |+| h) |+|> p === g |+|> (h |+|> p)` for all `g`, `h` in `G` and `p` in `P`.

2. `id |+|> p === p` for all `p` in `P` (if `id` is defined)

A left module is a generalization of a vector space over a field, where the scalars are the elements of a ring (not necessarily commutative).

A left module has left multiplication by scalars. Let V be an abelian group (with additive notation) and R the scalar ring, we have the following laws for x, y in V and r, s in R:

 1. r *: (x + y) = r *: x + r *: y
 2. (r + s) *: x = r *: x + s *: x
 3. (r * s) *: x = r *: (s *: x)
 4. R.one * x = x

(see https://en.wikipedia.org/wiki/Module_(mathematics) )

This type class models a metric space V. The distance between 2 points in V is measured in R, which should be real (ie. IsReal[R] exists).

This is a type class for types with n-roots. The value returned by nroot and sqrt are only guaranteed to be approximate answers (except in the case of Real).

Also, generally nroots where n is even are not defined for negative numbers. The behaviour is undefined if this is attempted. It would be nice to ensure an exception is raised, but some types may defer computation and testing if a value is negative may not be ideal. So, do not count on ArithmeticExceptions to save you from bad arithmetic!

A normed vector space is a vector space equipped with a function norm: V => F. The main constraint is that the norm of a vector must be scaled linearly when the vector is scaled; that is norm(k *: v) == k.abs * norm(v). Additionally, a normed vector space is also a MetricSpace, where distance(v, w) = norm(v - w), and so must obey the triangle inequality.

An example of a normed vector space is R^n equipped with the euclidean vector length as the norm.

A (right) semigroup/monoid/group action of G on P is simply the implementation of a method actr(p, g), or p <|+| g, such that:

1. `p <|+| (g |+| h) === (p <|+| g) <|+| h` for all `g`, `h` in `G` and `p` in `P`.

2. `p <|+| id === p` for all `p` in `P` (if `id` is defined)

A right module is a generalization of a vector space over a field, where the scalars are the elements of a ring (not necessarily commutative).

A right module has right multiplication by scalars. Let V be an abelian group (with additive notation) and R the scalar ring, we have the following laws for x, y in V and r, s in R:

 1. (x + y) :* r = x :* r + y :* r
 2. x :* (r + s) = x :* r + x :* s
 3. x :* (r * s) = (x :* r) :* s
 4. x :* R.one = x

A RingAssociativeAlgebra is a R-module that is also a Ring. An example is the Gaussian numbers, the quaternions, etc...

The scalar multiplication satisfies, for r in R, and x, y in V:

 1. r *: (x * y) = (r *: x) * y = x * (r *: y)

TODO: verify the definition, in particular the requirements for Ring[V] (and not Rng[V])

A simple ADT representing the Sign of an object.

A trait for linearly ordered additive commutative monoid. The following laws holds:

(1) if `a <= b` then `a + c <= b + c` (linear order),
(2) `signum(x) = -1` if `x < 0`, `signum(x) = 1` if `x > 0`, `signum(x) = 0` otherwise,

Negative elements only appear when scalar is a additive abelian group, and then

(3) `abs(x) = -x` if `x < 0`, or `x` otherwise,

Laws (1) and (2) lead to the triange inequality:

(4) `abs(a + b) <= abs(a) + abs(b)`

Signed should never be extended in implementations, rather the AdditiveCMonoid and AdditiveAbGroup subtraits. We cannot use self-types to express the constraint self: AdditiveCMonoid => (interaction with specialization?).

A Torsor[V, R] requires an AbGroup[R] and provides Action[V, R], plus a diff operator, <-> in additive notation, such that:

1. `(g <-> g) === scalar.id` for all `g` in `G`.

2. `(g <-> h) +> h === g` for all `g`, `h` in `G`.

3. `(g <-> h) +> i === (i <-> h) +> g` for all `g`, `h` in `G`.

4. `(g <-> h) === -(h <-> g)` for all `g`, `h` in `G`.

Division and modulus for computer scientists taken from https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/divmodnote-letter.pdf

For two numbers x (dividend) and y (divisor) on an ordered ring with y != 0, there exists a pair of numbers q (quotient) and r (remainder) such that these laws are satisfied:

(1) q is an integer
(2) x = y * q + r (division rule)
(3) |r| < |y|
(4t) r = 0 or sign(r) = sign(x)
(4f) r = 0 or sign(r) = sign(y).

where sign is the sign function, and the absolute value function |x| is defined as |x| = x if x >=0, and |x| = -x otherwise.

We define functions tmod and tquot such that:

q = tquot(x, y) and r = tmod(x, y) obey rule (4t),
(whichtruncates effectively towards zero) and functions fmod and fquot such that:
q = fquot(x, y) and r = fmod(x, y) obey rule (4f)
(which floors the quotient and effectively rounds towards negative infinity).

Law (4t) corresponds to ISO C99 and Haskell's quot/rem.

Law (4f) is described by Knuth and used by Haskell, and fmod corresponds to the REM function of the IEEE floating-point standard.

A unique factorization domain is a commutative ring in which each element can be written as a product of prime elements and a unit.

Unique factorization domains are GCD rings (or domains), but not necessarily Euclidean domains.

This trait is outside the commutative ring hierarchy, because the factorization algorithms are costly. Another reason: in some cases, a deliberate choice should be made by the user, for example to use probabilistic algorithms with a specified probability of failure.

A vector space is a group V that can be multiplied by scalars in F that lie in a field. Scalar multiplication must distribute over vector addition

(`x *: (v + w) === x *: v + x *: w`) and scalar addition
(`(x + y) *: v === x *: v + y *: v`). Scalar multiplication by 1 in `F` is an identity function
(`1 *: v === v`). Scalar multiplication is "associative" (`x *: y *: v === (x * y) *: v`).

Given any Ring[A] we can construct a RingAlgebra[A, Int]. This is possible since we can define fromInt on Ring generally.