Debian Codegraph @

texmf-dist/doc/lualatex/luahyperbolic/lua/complex.lua

raw
1 -----------------------------------------------------------------------
2 -- @module complex
3 -- Pure Lua complex number library (LuaLaTeX oriented).
4 -- Provides arithmetic, elementary functions, geometric utilities,
5 -- and tolerant comparisons.
6 --
7 -- License:
8 -- Public Domain / CC0 1.0 Universal
9 -- 2026 Damien Mégy
10 -- This software is released into the public domain.
11 -- You may use, modify, and distribute it freely, without restriction.
12 --
13 -- SPDX-License-Identifier: CC0-1.0
14 --
15 -----------------------------------------------------------------------
16
17
18
19 local m = {}
20 m.__index = m
21
22 local sin = math.sin
23 local cos = math.cos
24 local atan2 = math.atan2
25 local exp = math.exp
26 local log = math.log
27 local sqrt = math.sqrt
28 local abs = math.abs
29
30 -- precision
31 m.EPS_INV = 1e10
32 m.EPS = 1/m.EPS_INV
33
34 function m.new(re, im)
35 return setmetatable({
36 re = re or 0,
37 im = im or 0,
38 }, m)
39 end
40
41 --- Polar constructor.
42 function m.polar(r, theta)
43 return m.new(r * cos(theta), r * sin(theta))
44 end
45
46
47 setmetatable(m, {
48 __call = function(_, re, im)
49 return m.new(re, im)
50 end,
51 })
52
53 -- -----------------------------------------
54 -- Type checking and coercion
55 -- -----------------------------------------
56
57 function m.isComplex(z)
58 return type(z) == "table" and getmetatable(z) == m
59 end
60
61 local function tocomplex(z)
62 if m.isComplex(z) then
63 return z
64 elseif type(z) == "number" then
65 return m.new(z, 0)
66 elseif type(z) == "table" and z.re and z.im then
67 return m.new(z.re, z.im)
68 else
69 error("Cannot coerce value to complex, got type " .. type(z))
70 end
71 end
72
73 -- public coerce, handles various arguments
74
75 function m.coerce(...)
76 local args = {...}
77 for i = 1, #args do
78 args[i] =tocomplex(args[i])
79 end
80 return table.unpack(args)
81 end
82
83 -- -----------------------------------------
84 -- Arithmetic metamethods
85 -- -----------------------------------------
86
87 --- Exact equality test (no tolerance).
88 -- Use `isClose` for numerical comparisons.
89 function m.__eq(a, b)
90 a, b = tocomplex(a), tocomplex(b)
91 return a.re == b.re and a.im == b.im
92 end
93
94 --- Addition metamethod.
95 function m.__add(a, b)
96 a, b = tocomplex(a), tocomplex(b)
97 return m.new(a.re + b.re, a.im + b.im)
98 end
99
100 --- Subtraction metamethod.
101 function m.__sub(a, b)
102 a, b = tocomplex(a), tocomplex(b)
103 return m.new(a.re - b.re, a.im - b.im)
104 end
105
106 --- Multiplication metamethod.
107 function m.__mul(a, b)
108 a, b = tocomplex(a), tocomplex(b)
109 return m.new(a.re * b.re - a.im * b.im, a.re * b.im + a.im * b.re)
110 end
111
112 --- Division metamethod.
113 -- @error Division by zero.
114 function m.__div(a, b)
115 a, b = tocomplex(a), tocomplex(b)
116 local d = b.re * b.re + b.im * b.im
117 if d == 0 then
118 error("Division by zero in complex division")
119 end
120 return m.new((a.re * b.re + a.im * b.im) / d, (a.im * b.re - a.re * b.im) / d)
121 end
122
123
124 --- Unary minus metamethod.
125 function m.__unm(a)
126 a = tocomplex(a)
127 return m.new(-a.re, -a.im)
128 end
129
130 -- -----------------------------------------
131 -- Pretty printing
132 -- -----------------------------------------
133
134
135 --- Convert to string in the form `a+bi`.
136 function m.__tostring(z)
137 z = tocomplex(z)
138 return string.format("%g%+gi", z.re, z.im)
139 end
140
141 -- -----------------------------------------
142 -- Additional functions
143 -- -----------------------------------------
144
145 --- Approximate equality (L¹ norm).
146 -- @param a complex
147 -- @param b complex
148 -- @param eps number optional tolerance
149 -- @return boolean
150 function m.isClose(a, b, eps)
151 a, b = tocomplex(a), tocomplex(b)
152 eps = eps or m.EPS
153
154 local dr = abs(a.re - b.re)
155 local di = abs(a.im - b.im)
156
157 return dr + di <= eps -- norme L1, rapide
158 end
159
160
161 --- Compare unordered pairs with tolerance.
162 local function isClosePair(a, b, c, d)
163 return
164 (m.isClose(a, c) and m.isClose(b, d)) or
165 (m.isClose(a, d) and m.isClose(b, c))
166 end
167
168
169 --- Test whether two numbers are distinct (tolerant).
170 function m.distinct(a, b)
171 a, b = tocomplex(a), tocomplex(b)
172 return not m.isClose(a, b)
173 end
174
175
176 --- Test whether a complex number is nonzero (tolerant).
177 function m.nonzero(z)
178 z = tocomplex(z)
179 return m.distinct(z, 0)
180 end
181
182 --- Determinant
183 function m.det(a, b)
184 a, b = tocomplex(a), tocomplex(b)
185 return a.re * b.im - a.im * b.re
186 end
187
188 --- Scalar (dot) product.
189 function m.dot(a, b)
190 a, b = tocomplex(a), tocomplex(b)
191 return a.re * b.re + a.im * b.im
192 end
193
194 m.scal = m.dot
195
196 --- Normalize to unit modulus.
197 -- @return complex|nil nil if zero
198 function m.unit(z)
199 z = tocomplex(z)
200 local r = m.abs(z)
201 if r < m.EPS then
202 return nil
203 end
204 return z / r
205 end
206
207
208 --- Complex conjugate.
209 function m.conj(z)
210 z = tocomplex(z)
211 return m.new(z.re, -z.im)
212 end
213
214
215 --- Squared modulus.
216 function m.abs2(z)
217 z = tocomplex(z)
218 return z.re * z.re + z.im * z.im
219 end
220
221
222 --- Modulus.
223 function m.abs(z)
224 z = tocomplex(z)
225 return sqrt(z.re*z.re + z.im*z.im)
226 end
227
228
229 --- Argument (principal value).
230 -- Returns angle in radians in (-π, π].
231 function m.arg(z)
232 z = tocomplex(z)
233 return atan2(z.im, z.re)
234 end
235
236
237 --- Complex inversion in circle.
238 -- @param z complex
239 -- @param center complex optional
240 -- @param R number optional radius
241 function m.invert(z, center, R)
242 z = tocomplex(z)
243 center = tocomplex(center or m.ZERO)
244 R = R or 1
245
246 local dz = z - center
247 local d2 = dz.re*dz.re + dz.im*dz.im
248 assert(d2 > 0, "invert: undefined at center")
249 local inv = m.new(dz.re/d2, -dz.im/d2)
250 return center + (R*R) * inv
251 end
252
253 -- -----------------------------------------
254 -- Comparisons (methods, with optional tolerance)
255 -- -----------------------------------------
256
257
258 --- Approximate equality (method form).
259 function m:isNear(w, eps)
260 return m.isClose(self, w, eps)
261 end
262
263
264 --- Negated approximate comparison (method form).
265 function m:isNot(w, eps)
266 return not m.isClose(self, w, eps)
267 end
268
269 -- Integer check, no tolerance
270 function m:isInteger()
271 return self.im == 0 and self.re % 1 == 0
272 end
273
274 --- Test whether imaginary part is approx. zero (method form).
275 function m:isReal(eps)
276 eps = eps or m.EPS
277 return abs(self.im) <= eps
278 end
279
280 --- Test whether real part is approx. zero (method form).
281 function m:isImag(eps)
282 eps = eps or m.EPS
283 return abs(self.re) <= eps
284 end
285
286 -- Integer check with tolerance
287 function m:isNearInteger(eps)
288 eps = eps or m.EPS
289 if abs(self.im) > eps then
290 return false
291 end
292 local nearest = math.floor(self.re + 0.5)
293 return abs(self.re - nearest) <= eps
294 end
295
296
297 --- Test whether modulus is approx. 1 (method form).
298 function m:isUnit(eps)
299 eps = eps or m.EPS
300 local r = m.abs(self)
301 return abs(r-1) < eps
302 end
303
304
305 --- Test approx. colinearity with other number (method form).
306 function m:isColinear(other, eps)
307 eps = eps or m.EPS
308 return abs(m.det(self, other)) <= eps
309 end
310
311
312 --- Convert to polar coordinates.
313 -- @return r number
314 -- @return theta number
315 function m:toPolar()
316 return m.abs(self), m.arg(self)
317 -- Note : returns (0,0) for origin
318 end
319
320 --- Clone the complex number.
321 function m:clone()
322 return m.new(self.re, self.im)
323 end
324
325
326 --- e^{iθ}
327 function m.exp_i(theta)
328 return m.new(cos(theta), sin(theta))
329 end
330
331
332 --- Rotate by 90 degrees.
333 function m:rotate90()
334 return m.new(-self.im, self.re)
335 end
336
337
338 --- Rotate by angle θ (radians).
339 function m:rotate(theta)
340 local c = cos(theta)
341 local s = sin(theta)
342 return m.new(c*self.re - s*self.im, s*self.re + c*self.im)
343 end
344
345
346
347
348 --- Complex exponential.
349 function m.exp(z)
350 z = tocomplex(z)
351 local exp_r = exp(z.re)
352 return m.new(exp_r * cos(z.im), exp_r * sin(z.im))
353 end
354
355
356 --- Principal complex logarithm.
357 -- @error undefined for 0
358 function m.log(z)
359 z = tocomplex(z)
360 if z.re == 0 and z.im == 0 then
361 error("Logarithm undefined for 0")
362 end
363 -- Note : other languages return -inf+0*i
364 return m.new(log(m.abs(z)), m.arg(z))
365 end
366
367
368
369 -- fast integer power (binary exponentiation)
370 local function complex_pow_int(a, n)
371 if n == 0 then
372 return m.new(1, 0)
373 end
374
375 if n < 0 then
376 a = m.new(1, 0) / a
377 n = -n
378 end
379
380 local result = m.new(1, 0)
381 while n > 0 do
382 if n % 2 == 1 then
383 result = result * a
384 end
385 a = a * a
386 n = math.floor(n / 2)
387 end
388
389 return result
390 end
391
392 function m.__pow(a, b)
393 a, b = tocomplex(a), tocomplex(b)
394
395 -- Special cases
396 if a == 0 and b == 0 then
397 return m.ONE
398 end
399 if a == 0 and (b.re < 0 or b.im ~= 0) then
400 error("0 cannot be raised to a negative or complex power")
401 end
402 if a == 0 then
403 return m.ZERO
404 end
405 if b == 0 then
406 return m.ONE
407 end
408
409 if b:isInteger() then
410 return complex_pow_int(a, b.re)
411 end
412
413 -- (approx) integer exponent. Is rounding a good idea ?
414 if b:isNearInteger() then
415 local n = math.floor(b.re + 0.5) -- round
416 return complex_pow_int(a, n)
417 end
418
419 -- General complex power
420 return m.exp(b * m.log(a))
421 end
422
423 -----------------------------------------------------------------------
424 -- Constants
425 -----------------------------------------------------------------------
426
427 --- 1 + 0i
428 m.ONE = m.new(1, 0)
429
430 --- 0 + 0i
431 m.ZERO = m.new(0, 0)
432
433 --- i
434 m.I = m.new(0, 1)
435
436 --- Primitive cube root of unity.
437 m.J = m.new(-1/2, sqrt(3)/2)
438
439 return m