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)

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

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 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`.

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.