1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
/*
* SPDX-License-Identifier: MIT
* Copyright (c) 2023 - 2026. The DeepCausality Authors and Contributors. All Rights Reserved.
*/
use crateFloat106;
/// Marker trait: promises that zero **annihilates** under multiplication, so that
/// `0 * a == a * 0 == 0` for every `a`.
///
/// # Why this needs its own marker
///
/// In a [`Ring`](crate::Ring) this law is a *theorem*, not an axiom:
///
/// ```text
/// 0·a = (0 + 0)·a = 0·a + 0·a by the additive identity and distributivity
/// 0 = 0·a by adding −(0·a) to both sides
/// ```
///
/// That last step consumes an additive inverse. A [`Semiring`](crate::Semiring) has none, so the
/// derivation is unavailable and annihilation has to be assumed separately. It is the one semiring
/// axiom that does not follow from the others, which is precisely why it cannot be left implicit.
///
/// Without this marker a `Semiring` bound would assert a law nobody had promised — the same defect
/// that [`Invertible`](crate::Invertible) exists to prevent one rung higher up, where `Div` alone
/// does not imply inversion.
///
/// # Scope: the finite floats
///
/// The intended model of `f32`, `f64` and `Float106` is ℝ. `NaN` and the infinities are artifacts
/// of the machine representation rather than real numbers, and every law in this tower is asserted
/// over the finite values. Annihilation is the plainest case: `0.0 * f64::NAN` is `NaN`, and so is
/// `0.0 * f64::INFINITY`, neither of which is zero.
///
/// The same boundary applies to the rest of the tower, so no marker carries a finite-value caveat
/// of its own. [`Commutative`](crate::Commutative) states `a * b == b * a`, yet
/// `NaN * 1.0 == 1.0 * NaN` is `false`, because `NaN` compares unequal to itself.
/// [`Distributive`](crate::Distributive) fails the moment a `NaN` reaches either side of the
/// equation. `a + (-a) == 0` fails at `NaN` and at the infinities, which takes
/// [`AbelianGroup`](crate::AbelianGroup) with it.
///
/// Generic code that depends on the laws therefore has to keep its floats finite.
/// [`Real::is_finite`](crate::Real::is_finite) is the predicate that decides it.
///
/// # Implementing
///
/// Implement it for any type whose zero really does annihilate. Past the primitives below, seven
/// types carry the marker, each in the crate that defines it: `Complex<T>`, `Quaternion<T>` and
/// `Octonion<T>` in `deep_causality_num_complex`, `Dual<T>` in `deep_causality_num_dual`,
/// `Rational<T>` in `deep_causality_num_rational`, and `CausalTensor<T>` and
/// `CausalTensorTrain<T>` in `deep_causality_tensor`. `CsrMatrix<T>` in `deep_causality_sparse`
/// does not: it stops at [`AbelianGroup`](crate::AbelianGroup) and carries none of the
/// multiplicative markers.
///
/// The types are listed one by one rather than inferred, for the reason given in
/// [`Commutative`](crate::Commutative).
// The real scalars.
// The integers. Here the law is derivable, but the marker is still stated so that `ℤ` and `ℕ`
// present the same surface and generic semiring code accepts both.
// The naturals. This is the case that needs the promise: ℕ has no additive inverses, so nothing
// derives `0 * a = 0` for it.