foliated-arithmetic 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,272 @@
1
+ """
2
+ Foliated Arithmetic — Exact-Integer Reference Library
3
+ -----------------------------------------------------
4
+ Zero-dependency, strictly typed, exact-integer Python implementation of
5
+ *The Geometry of Integers* (Dr. Hassan Baloui, DOI: 10.5281/zenodo.23456718)
6
+ and *The Minimal Balancing Multiplier and the Riemann Zeta Function at
7
+ Positive Integers* (DOI: 10.5281/zenodo.24109170).
8
+
9
+ Quick-start doctests::
10
+
11
+ >>> from foliated_arithmetic import (
12
+ ... Direction,
13
+ ... f_add,
14
+ ... f_sub,
15
+ ... f_mul,
16
+ ... f_mod,
17
+ ... f_quotient,
18
+ ... geodesic_distance,
19
+ ... geodesic_path,
20
+ ... leaf_factorization,
21
+ ... discrete_curvature,
22
+ ... mbm,
23
+ ... shell_mbm_spectrum,
24
+ ... )
25
+ >>> f_add(2, 3)
26
+ Triad(left=17, vertical=20, right=23)
27
+ >>> f_add(3, 4).as_set() & f_add(4, 3).as_set()
28
+ {31}
29
+ >>> f_sub(13, 2)
30
+ Triad(left=-13, vertical=3, right=1)
31
+ >>> f_mul(2, 3)
32
+ Triad(left=26, vertical=30, right=34)
33
+ >>> (f_quotient(33, 2), f_mod(33, 2).as_tuple())
34
+ (3, ((0, 7), (0, 3), (0, -1)))
35
+ >>> geodesic_distance(2, 33)
36
+ 4
37
+ >>> geodesic_path(2, 33)
38
+ [2, 7, 14, 23, 33]
39
+ >>> leaf_factorization(861, Direction.VERTICAL, m=2)
40
+ [(123, 2), (201, 1)]
41
+ >>> discrete_curvature(10, Direction.LEFT, Direction.RIGHT)
42
+ 340
43
+ >>> mbm(17)
44
+ 16
45
+ >>> shell_mbm_spectrum(5)
46
+ [1, 5, 3, 1, 25, 1, 25, 1, 3, 8, 1]
47
+ >>> f_add(2, 3, m=1).as_tuple(), f_mul(2, 3, m=1).as_tuple()
48
+ ((5, 5, 5), (6, 6, 6))
49
+ """
50
+
51
+ from __future__ import annotations
52
+
53
+ from foliated_arithmetic.arithmetic import (
54
+ add_dir,
55
+ f_add,
56
+ f_mul,
57
+ f_pow,
58
+ f_recursive_pow,
59
+ f_sub,
60
+ mul_dir,
61
+ pow_dir,
62
+ recursive_pow_dir,
63
+ sub_dir,
64
+ )
65
+ from foliated_arithmetic.balancing import (
66
+ central_divisors,
67
+ is_balanced,
68
+ is_square_multiplier,
69
+ mbm,
70
+ mbm_first_moment,
71
+ prime_count_via_mbm,
72
+ prime_indicator_via_mbm,
73
+ shell_balanced_count,
74
+ shell_discrepancy,
75
+ shell_mbm_spectrum,
76
+ shell_unit_discrepancy_count,
77
+ unit_discrepancy_multiplier,
78
+ )
79
+ from foliated_arithmetic.coords import (
80
+ birth_shell,
81
+ depth_triad,
82
+ from_leaf_coord,
83
+ iroot,
84
+ lateral_generator,
85
+ leaf_coord,
86
+ leaf_depth,
87
+ leaf_root,
88
+ min_shell,
89
+ shell_bounds,
90
+ shell_coord,
91
+ shell_index,
92
+ shell_median,
93
+ shell_reflection,
94
+ shell_size,
95
+ )
96
+ from foliated_arithmetic.division import (
97
+ exact_quotient_dir,
98
+ f_divmod,
99
+ f_divmod_dir,
100
+ f_mod,
101
+ f_mod_dir,
102
+ f_quotient,
103
+ is_congruent,
104
+ is_divisible,
105
+ is_divisible_triad,
106
+ )
107
+ from foliated_arithmetic.geodesic import (
108
+ RoutingRegime,
109
+ bounding_direction,
110
+ geodesic_ball,
111
+ geodesic_distance,
112
+ geodesic_path,
113
+ routing_regime,
114
+ transport_geodesic_distance,
115
+ virtual_waypoint,
116
+ zigzag_waypoint,
117
+ )
118
+ from foliated_arithmetic.holonomy import (
119
+ decode_holographic_image,
120
+ discrete_curvature,
121
+ holonomy_commutator,
122
+ is_forbidden_self_shift_shell,
123
+ normalized_curvature,
124
+ reverse_self_shift,
125
+ self_shift,
126
+ self_shift_triad,
127
+ )
128
+ from foliated_arithmetic.primality import (
129
+ LeafClass,
130
+ co_leaf_mul,
131
+ co_leaf_pow,
132
+ count_classical_primes,
133
+ factor_integer,
134
+ foliated_divisors,
135
+ intrinsic_leaf_depth_power,
136
+ is_classical_prime,
137
+ is_foliated_prime,
138
+ is_foliated_prime_triad,
139
+ is_local_leaf_prime,
140
+ is_local_leaf_prime_triad,
141
+ is_omni_foliated_prime,
142
+ is_triple_leaf_prime,
143
+ leaf_classification,
144
+ leaf_factorization,
145
+ leaf_factorization_triad,
146
+ reconstruct_leaf_factorization,
147
+ shell_local_prime_count,
148
+ )
149
+ from foliated_arithmetic.transport import (
150
+ nabla,
151
+ nabla_hat,
152
+ nabla_hat_triad,
153
+ nabla_triad,
154
+ )
155
+ from foliated_arithmetic.types import (
156
+ CANONICAL_DIRECTIONS,
157
+ Direction,
158
+ DivisionResult,
159
+ DomainError,
160
+ FoliatedArithmeticError,
161
+ InvalidDegreeError,
162
+ ShellCoord,
163
+ Triad,
164
+ require_int,
165
+ validate_degree,
166
+ validate_non_negative,
167
+ validate_positive,
168
+ )
169
+
170
+ __version__ = "0.1.0"
171
+
172
+ __all__ = [
173
+ "CANONICAL_DIRECTIONS",
174
+ "Direction",
175
+ "DivisionResult",
176
+ "DomainError",
177
+ "FoliatedArithmeticError",
178
+ "InvalidDegreeError",
179
+ "LeafClass",
180
+ "RoutingRegime",
181
+ "ShellCoord",
182
+ "Triad",
183
+ "__version__",
184
+ "add_dir",
185
+ "birth_shell",
186
+ "bounding_direction",
187
+ "central_divisors",
188
+ "co_leaf_mul",
189
+ "co_leaf_pow",
190
+ "count_classical_primes",
191
+ "decode_holographic_image",
192
+ "depth_triad",
193
+ "discrete_curvature",
194
+ "exact_quotient_dir",
195
+ "f_add",
196
+ "f_divmod",
197
+ "f_divmod_dir",
198
+ "f_mod",
199
+ "f_mod_dir",
200
+ "f_mul",
201
+ "f_pow",
202
+ "f_quotient",
203
+ "f_recursive_pow",
204
+ "f_sub",
205
+ "factor_integer",
206
+ "foliated_divisors",
207
+ "from_leaf_coord",
208
+ "geodesic_ball",
209
+ "geodesic_distance",
210
+ "geodesic_path",
211
+ "holonomy_commutator",
212
+ "intrinsic_leaf_depth_power",
213
+ "iroot",
214
+ "is_balanced",
215
+ "is_classical_prime",
216
+ "is_congruent",
217
+ "is_divisible",
218
+ "is_divisible_triad",
219
+ "is_foliated_prime",
220
+ "is_foliated_prime_triad",
221
+ "is_forbidden_self_shift_shell",
222
+ "is_local_leaf_prime",
223
+ "is_local_leaf_prime_triad",
224
+ "is_omni_foliated_prime",
225
+ "is_square_multiplier",
226
+ "is_triple_leaf_prime",
227
+ "lateral_generator",
228
+ "leaf_classification",
229
+ "leaf_coord",
230
+ "leaf_depth",
231
+ "leaf_factorization",
232
+ "leaf_factorization_triad",
233
+ "leaf_root",
234
+ "mbm",
235
+ "mbm_first_moment",
236
+ "min_shell",
237
+ "mul_dir",
238
+ "nabla",
239
+ "nabla_hat",
240
+ "nabla_hat_triad",
241
+ "nabla_triad",
242
+ "normalized_curvature",
243
+ "pow_dir",
244
+ "prime_count_via_mbm",
245
+ "prime_indicator_via_mbm",
246
+ "reconstruct_leaf_factorization",
247
+ "recursive_pow_dir",
248
+ "require_int",
249
+ "reverse_self_shift",
250
+ "routing_regime",
251
+ "self_shift",
252
+ "self_shift_triad",
253
+ "shell_balanced_count",
254
+ "shell_bounds",
255
+ "shell_coord",
256
+ "shell_discrepancy",
257
+ "shell_index",
258
+ "shell_local_prime_count",
259
+ "shell_mbm_spectrum",
260
+ "shell_median",
261
+ "shell_reflection",
262
+ "shell_size",
263
+ "shell_unit_discrepancy_count",
264
+ "sub_dir",
265
+ "transport_geodesic_distance",
266
+ "unit_discrepancy_multiplier",
267
+ "validate_degree",
268
+ "validate_non_negative",
269
+ "validate_positive",
270
+ "virtual_waypoint",
271
+ "zigzag_waypoint",
272
+ ]
@@ -0,0 +1,222 @@
1
+ """
2
+ Multi-Valued Foliated Arithmetic on N_m and Z_m
3
+ -----------------------------------------------
4
+ Pure exact-integer implementation of Section 3.1 and Section 3.2 of
5
+ *Geometry of Integers*:
6
+
7
+ Directional scalar operations (lambda in {0, 1/2, 1} via Direction):
8
+ - ``add_dir(a, b, direction, m=2)`` : a (+)_{lambda,m} b = nabla_hat(a, b)
9
+ - ``sub_dir(a, b, direction, m=2)`` : a (-)_{lambda,m} b = nabla_hat(a, -b)
10
+ - ``mul_dir(a, b, direction, m=2)`` : a (x)_{lambda,m} b = nabla_hat(a, a*(b - 1))
11
+ - ``pow_dir(a, p, direction, m=2)`` : leaf-conserving power a^{<p>_{lambda,m}}
12
+ - ``recursive_pow_dir(a, p, direction, m=2)`` : left-recursive power a^{[p]_{lambda,m}}
13
+
14
+ Full directional triad operations returning ``Triad[int]``:
15
+ - ``f_add(a, b, m=2)`` : a (+)_m b
16
+ - ``f_sub(a, b, m=2)`` : a (-)_m b
17
+ - ``f_mul(a, b, m=2)`` : a (x)_m b
18
+ - ``f_pow(a, p, m=2)`` : a^{<p>_m}
19
+ - ``f_recursive_pow(a, p, m=2)`` : a^{[p]_m}
20
+
21
+ All operations collapse identically to classical commutative Peano arithmetic
22
+ (``a + b``, ``a - b``, ``a * b``, ``a ** p``) at the flat limit ``m = 1``.
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ from foliated_arithmetic.transport import nabla, nabla_hat, nabla_hat_triad
28
+ from foliated_arithmetic.types import (
29
+ Direction,
30
+ Triad,
31
+ require_int,
32
+ validate_degree,
33
+ validate_non_negative,
34
+ validate_positive,
35
+ )
36
+
37
+
38
+ def _require_direction(direction: Direction) -> Direction:
39
+ """Validate that ``direction`` is a canonical ``Direction`` enum member."""
40
+ if not isinstance(direction, Direction):
41
+ raise TypeError(
42
+ f"Expected Direction enum member; got {type(direction).__name__}."
43
+ )
44
+ return direction
45
+
46
+
47
+ def _ipow(base: int, exp: int) -> int:
48
+ """Exact non-negative integer power ``base ** exp`` typed strictly as ``int``."""
49
+ return int(base**exp)
50
+
51
+
52
+ # ============================================================================
53
+ # DIRECTIONAL SCALAR OPERATIONS
54
+ # ============================================================================
55
+
56
+
57
+ def add_dir(a: int, b: int, direction: Direction, m: int = 2) -> int:
58
+ """
59
+ Directional foliated addition ``a (+)_{lambda,m} b = nabla_hat_{lambda,m}(a, b)``
60
+ on the reflected double-lattice ``Z_m`` (Monograph Eq. 3.9).
61
+
62
+ The left operand ``a`` serves as the geometric leaf-anchor while ``b``
63
+ serves as the directed longitudinal shell displacement.
64
+ """
65
+ a_val = require_int(a, "a")
66
+ b_val = require_int(b, "b")
67
+ dir_val = _require_direction(direction)
68
+ deg = validate_degree(m)
69
+ return nabla_hat(a_val, b_val, dir_val, deg)
70
+
71
+
72
+ def sub_dir(a: int, b: int, direction: Direction, m: int = 2) -> int:
73
+ """
74
+ Directional foliated subtraction ``a (-)_{lambda,m} b = nabla_hat_{lambda,m}(a, -b)``
75
+ on the reflected double-lattice ``Z_m`` (Monograph Eq. 3.9).
76
+
77
+ Satisfies exact branch-by-branch invertibility ``(a (-)_{lambda,m} b) (+)_{lambda,m} b == a``
78
+ whenever ``a == 0``, ``d_{lambda,m}(|a|) >= 1``, or ``sgn(a) * b <= 0``.
79
+ """
80
+ a_val = require_int(a, "a")
81
+ b_val = require_int(b, "b")
82
+ dir_val = _require_direction(direction)
83
+ deg = validate_degree(m)
84
+ return nabla_hat(a_val, -b_val, dir_val, deg)
85
+
86
+
87
+ def mul_dir(a: int, b: int, direction: Direction, m: int = 2) -> int:
88
+ """
89
+ Directional foliated multiplication ``a (x)_{lambda,m} b = nabla_hat_{lambda,m}(a, a*(b - 1))``
90
+ across all four quadrants of ``Z_m x Z_m`` (Monograph Eq. 3.10).
91
+
92
+ For ``a == 0``, returns ``0`` unconditionally. For ``a != 0``, the oriented
93
+ step is ``s_tilde = |a| * (b - 1)``.
94
+ """
95
+ a_val = require_int(a, "a")
96
+ b_val = require_int(b, "b")
97
+ dir_val = _require_direction(direction)
98
+ deg = validate_degree(m)
99
+ return nabla_hat(a_val, a_val * (b_val - 1), dir_val, deg)
100
+
101
+
102
+ def pow_dir(a: int, p: int, direction: Direction, m: int = 2) -> int:
103
+ """
104
+ Leaf-conserving foliated power ``a^{<p>_{lambda,m}}`` for base ``a >= 1``
105
+ and exponent ``p >= 0`` (Monograph Definition 3.6, Eqs. 3.11--3.12):
106
+
107
+ - ``p >= 1``: ``nabla_{lambda,m}(a, a^p - a)`` (remains in ``N_m`` on the leaf of ``a``)
108
+ - ``p == 0``: ``nabla_hat_{lambda,m}(a, 1 - a)`` (double-lattice zero exponent in ``Z_m``)
109
+
110
+ Collapses identically to ``a ** p`` (including ``a ** 0 == 1``) at ``m = 1``.
111
+ """
112
+ a_val = validate_positive(a, "a")
113
+ p_val = validate_non_negative(p, "p")
114
+ dir_val = _require_direction(direction)
115
+ deg = validate_degree(m)
116
+
117
+ if p_val == 0:
118
+ return nabla_hat(a_val, 1 - a_val, dir_val, deg)
119
+ if p_val == 1:
120
+ return a_val
121
+ return nabla(a_val, _ipow(a_val, p_val) - a_val, dir_val, deg)
122
+
123
+
124
+ def recursive_pow_dir(a: int, p: int, direction: Direction, m: int = 2) -> int:
125
+ """
126
+ Left-recursive foliated power ``a^{[p]_{lambda,m}}`` for base ``a >= 1``
127
+ and exponent ``p >= 1`` (Monograph Section 3.2.2, Eq. 3.13):
128
+
129
+ ``a^{[1]_{lambda,m}} = a``
130
+ ``a^{[p+1]_{lambda,m}} = a^{[p]_{lambda,m}} (x)_{lambda,m} a``
131
+
132
+ Coincides with ``pow_dir`` at ``p == 1`` and ``p == 2`` and remains on the
133
+ initial ``direction``-leaf of ``a`` for all ``p >= 1``. Because shell depth
134
+ grows as a tower of degree ``m^p``, large ``p`` grows super-exponentially.
135
+ """
136
+ a_val = validate_positive(a, "a")
137
+ p_val = validate_positive(p, "p")
138
+ dir_val = _require_direction(direction)
139
+ deg = validate_degree(m)
140
+
141
+ if deg == 1:
142
+ return _ipow(a_val, p_val)
143
+
144
+ acc = a_val
145
+ stride_factor = a_val - 1
146
+ for _ in range(1, p_val):
147
+ acc = nabla(acc, acc * stride_factor, dir_val, deg)
148
+ return acc
149
+
150
+
151
+ # ============================================================================
152
+ # FULL DIRECTIONAL TRIAD OPERATIONS (LEFT, VERTICAL, RIGHT)
153
+ # ============================================================================
154
+
155
+
156
+ def f_add(a: int, b: int, m: int = 2) -> Triad[int]:
157
+ """
158
+ Multi-valued foliated addition ``a (+)_m b`` across all three canonical
159
+ directions ``(LEFT, VERTICAL, RIGHT)`` on ``Z_m``.
160
+ """
161
+ a_val = require_int(a, "a")
162
+ b_val = require_int(b, "b")
163
+ deg = validate_degree(m)
164
+ return nabla_hat_triad(a_val, b_val, deg)
165
+
166
+
167
+ def f_sub(a: int, b: int, m: int = 2) -> Triad[int]:
168
+ """
169
+ Multi-valued foliated subtraction ``a (-)_m b`` across all three canonical
170
+ directions ``(LEFT, VERTICAL, RIGHT)`` on ``Z_m``.
171
+ """
172
+ a_val = require_int(a, "a")
173
+ b_val = require_int(b, "b")
174
+ deg = validate_degree(m)
175
+ return nabla_hat_triad(a_val, -b_val, deg)
176
+
177
+
178
+ def f_mul(a: int, b: int, m: int = 2) -> Triad[int]:
179
+ """
180
+ Multi-valued foliated multiplication ``a (x)_m b`` across all three
181
+ canonical directions ``(LEFT, VERTICAL, RIGHT)`` on ``Z_m``.
182
+ """
183
+ a_val = require_int(a, "a")
184
+ b_val = require_int(b, "b")
185
+ deg = validate_degree(m)
186
+ return nabla_hat_triad(a_val, a_val * (b_val - 1), deg)
187
+
188
+
189
+ def f_pow(a: int, p: int, m: int = 2) -> Triad[int]:
190
+ """
191
+ Multi-valued leaf-conserving foliated power ``a^{<p>_m}`` across all three
192
+ canonical directions ``(LEFT, VERTICAL, RIGHT)`` for ``a >= 1, p >= 0``.
193
+ """
194
+ a_val = validate_positive(a, "a")
195
+ p_val = validate_non_negative(p, "p")
196
+ deg = validate_degree(m)
197
+ return Triad.from_direction(lambda d: pow_dir(a_val, p_val, d, deg))
198
+
199
+
200
+ def f_recursive_pow(a: int, p: int, m: int = 2) -> Triad[int]:
201
+ """
202
+ Multi-valued left-recursive foliated power ``a^{[p]_m}`` across all three
203
+ canonical directions ``(LEFT, VERTICAL, RIGHT)`` for ``a >= 1, p >= 1``.
204
+ """
205
+ a_val = validate_positive(a, "a")
206
+ p_val = validate_positive(p, "p")
207
+ deg = validate_degree(m)
208
+ return Triad.from_direction(lambda d: recursive_pow_dir(a_val, p_val, d, deg))
209
+
210
+
211
+ __all__ = [
212
+ "add_dir",
213
+ "f_add",
214
+ "f_mul",
215
+ "f_pow",
216
+ "f_recursive_pow",
217
+ "f_sub",
218
+ "mul_dir",
219
+ "pow_dir",
220
+ "recursive_pow_dir",
221
+ "sub_dir",
222
+ ]