librarylibs/Manifold/src/Manifold.xtl

u d̲ot v: the sum of the products, as a Float.

n̲orm v: the length of v, straight through the space it sits in.

s v s̲caleRows M: each row of M scaled by the matching item of s.

m a̲ngle s: the angle, 0 to pi, between two unit vectors p and q, from the lengths m = |p - q| and s = |p + q|: 2 atan2(m, s). Accurate near 0 and near pi alike, where a_cos of the product p.q is not (near 0 it loses half the digits), because neither length is a difference of nearly equal numbers.

p a̲part q: |p - q| and |p + q|, as a tuple.

P a̲partRows p: |r - p| and |r + p| for every row r of P.

a̲partPairs P: |r - r'| and |r + r'| for every pair of rows of P, two matrices, summed one coordinate at a time (so no number is a difference of nearly equal ones).

s̲phereProject v: v put onto the unit sphere, scaled to length 1; the direction of v, kept. Given a set (a matrix), every row. The zero vector has no direction and is refused.

      "mf:" u̲se< "Manifold"

      ᵐᶠs̲phereProject 3.0 4.0 0.0
0.6 0.8 0.0

      ᵐᶠs̲phereProject 2 3 r̲eshape 3.0 4.0 0.0 0.0 0.0 2.0
0.6 0.8 0.0
0.0 0.0 1.0

Every row of P put onto the sphere.

p s̲phereDistance q: the great-circle distance between two points of the sphere, the angle between them in radians (0 to pi): the shortest path along the sphere, as against the straight line through it, which is shorter (its length is 2 sin of half the angle). p and q must be on the sphere (s_phereProject).

      "mf:" u̲se< "Manifold"

      1.0 0.0 0.0 ᵐᶠs̲phereDistance 0.0 1.0 0.0
1.5707963267948966

s̲phereDistances P: the great-circle distance between every pair of rows of P (points on the sphere): a matrix, 0 on its diagonal.

      "mf:" u̲se< "Manifold"

      ᵐᶠs̲phereDistances 2 2 r̲eshape 1.0 0.0 0.0 1.0
               0.0 1.5707963267948966
1.5707963267948966                0.0

p s̲phereTangent v: the part of v that lies along the sphere at p (in the tangent plane there): v less its part along p, the normal. A tangent vector at p is one with no part along p.

      "mf:" u̲se< "Manifold"

      1.0 0.0 0.0 ᵐᶠs̲phereTangent 2.0 3.0 0.0
0.0 3.0 0.0

p s̲phereStep v: the point reached from p by going along the sphere in the direction of the tangent vector v, for a distance equal to v's length (the exponential map): cos t p + sin t v / t with t = |v|, put back onto the sphere so no rounding takes it off. A zero v goes nowhere. (A quarter turn from the x axis along y lands on the y axis; the x left over is cos of a quarter turn, 0 up to the machine's rounding.)

      "mf:" u̲se< "Manifold"

      1.0 0.0 0.0 ᵐᶠs̲phereStep 0.0 1.5707963267948966 0.0
0.00000000000000006123233995736766 1.0 0.0

p s̲phereArrow q: the tangent vector at p that s_phereStep carries to q (the logarithmic map): it points along the sphere toward q and is as long as the distance between them. For q = p it is zero; for q the opposite point, which every direction reaches at distance pi, it is zero too (there is no one arrow).

      "mf:" u̲se< "Manifold"

      1.0 0.0 0.0 ᵐᶠs̲phereArrow 0.0 1.0 0.0
0.0 1.5707963267948966 0.0

The arrows at p to every row of P, one per row (s_phereArrow, over a set at once): the mean's one step.

s̲phereMean P: the mean of the rows of P on the sphere (the Frechet or Karcher mean): the point whose summed squared distances along the sphere to the rows is least. The plain mean of the rows lies inside the sphere; this starts from that mean put onto the sphere and takes 30 steps, each along the average of the arrows to the rows, which is a fixed point when the arrows cancel. Points spread over less than a hemisphere have one mean, and the steps reach it; rows whose plain mean is the zero vector (say, two opposite points) are refused.

      "mf:" u̲se< "Manifold"

      ᵐᶠs̲phereMean 2 3 r̲eshape 1.0 0.0 0.0 0.0 1.0 0.0
0.7071067811865476 0.7071067811865476 0.0

s̲phereOff p: how far p is from the sphere: the difference between its length and 1, as a size. 0 for a point on it; what a test of a constraint reports. Given a set (a matrix), one per row.

      "mf:" u̲se< "Manifold"

      ᵐᶠs̲phereOff 0.0 0.5 0.0
0.5

      ᵐᶠs̲phereOff 2 2 r̲eshape 0.0 0.5 3.0 4.0
0.5 4.0

k c̲oordinate p: the k-th coordinate of a point, or the k-th column of a set of points (a matrix), as Floats.

c̲olumns M: the columns of a (rows x n) matrix given as one vector of n columns laid end to end, back as the matrix: the transpose of the n x rows reshape. For writing a set of points coordinate by coordinate.

s̲pherePoints LL: the point of the unit sphere at each (longitude, latitude) row of LL, in radians (longitude round the z axis from the x axis, latitude up from the equator): one row (x, y, z) per row of LL. These are the sphere's map: a parallel is rows of one latitude and many longitudes, a meridian rows of one longitude. (A quarter turn of latitude is the pole: its x is cos of a quarter turn, 0 up to the machine's rounding.)

      "mf:" u̲se< "Manifold"

      ᵐᶠs̲pherePoints 2 2 r̲eshape 0.0 0.0 0.0 1.5707963267948966
                               1.0 0.0 0.0
0.00000000000000006123233995736766 0.0 1.0

(p, q) s̲phereArc n: n + 1 points along the great circle from p to q (both on the sphere), p first and q last, evenly spaced along it: the points s_phereStep reaches from p along 0, 1/n, ..., 1 of the arrow to q. For q = p, or q the opposite point (no one arc), every point is p.

      "mf:" u̲se< "Manifold"

      (1.0 0.0 0.0, 0.0 1.0 0.0) ᵐᶠs̲phereArc 2
                               1.0                0.0 0.0
                0.7071067811865476 0.7071067811865475 0.0
0.00000000000000006123233995736766                1.0 0.0

c̲irclePoints A: the point of the unit circle at each angle of A (radians from the x axis, counterclockwise): one row (x, y) per angle. The circle is the sphere of one dimension, the unit sphere in two: s_phereProject puts a point onto it, s_phereDistance measures along it (the angle between two points), s_phereArc draws between them.

      "mf:" u̲se< "Manifold"

      ᵐᶠc̲irclePoints 0.0 3.141592653589793
 1.0                                0.0
-1.0 0.00000000000000012246467991473532

radii t̲orusPoints UV: the point of the torus of radii R r (R from the middle of the hole to the middle of the tube, r the tube's) at each (u, v) row of UV, in radians (u round the hole, v round the tube): ((R + r cos v) cos u, (R + r cos v) sin u, r sin v), one row per row of UV. The torus's map is the (u, v) rectangle, 0 to 2 pi each way, each pair of opposite edges joined.

      "mf:" u̲se< "Manifold"

      3.0 1.0 ᵐᶠt̲orusPoints 2 2 r̲eshape 0.0 0.0 0.0 3.141592653589793
4.0 0.0                                0.0
2.0 0.0 0.00000000000000012246467991473532

radii t̲orusOff p: how far p is from the torus of radii R r: the distance from p to the circle through the middle of the tube, less r, as a size. 0 for a point on it. Given a set (a matrix), one per row.

      "mf:" u̲se< "Manifold"

      3.0 1.0 ᵐᶠt̲orusOff 0.0 0.0 0.0
2.0

      3.0 1.0 ᵐᶠt̲orusOff 2 3 r̲eshape 4.0 0.0 0.0 3.0 0.0 0.0
0.0 1.0

r̲ollPoints TH: the point of the Swiss roll at each (t, h) row of TH: (t cos t, h, t sin t). The roll is a flat sheet rolled up: along t it winds round the y axis, farther out with every turn (a spiral whose radius is t); along h it runs straight up the axis. Its map is the sheet itself, the rectangle of (r_ollAlong t, h).

      "mf:" u̲se< "Manifold"

      ᵐᶠr̲ollPoints 2 2 r̲eshape 0.0 0.0 3.141592653589793 1.0
               0.0 0.0                                0.0
-3.141592653589793 1.0 0.00000000000000038473413874435795

r̲ollAlong t: the length of the roll's spiral from its middle (t = 0) out to t, (t sqrt(1 + t^2) + asinh t) / 2: how far along the unrolled sheet the points at t lie. Its map's first coordinate.

      "mf:" u̲se< "Manifold"

      ᵐᶠr̲ollAlong 0.0 1.0
0.0 1.147793574696319

a r̲ollDistance b: the distance along the sheet between the points of the roll at (t, h) a and b. The sheet is flat, so it is the plain distance between the two unrolled, sqrt((along a - along b)^2 + (h_a - h_b)^2): two points a turn apart are near in three dimensions and far along the sheet.

      "mf:" u̲se< "Manifold"

      0.0 0.0 ᵐᶠr̲ollDistance 1.0 0.0
1.147793574696319

u m̲obius v: Mobius addition, the ball's own way of adding (u then v, each inside the unit ball): ((1 + 2 u.v + |v|^2) u + (1 - |u|^2) v) / (1 + 2 u.v + |u|^2 |v|^2). The result stays in the ball; (-u) m_obius v is v seen from u, as a vector at the middle.

p b̲allDistance q: the distance between two points of the Poincare ball (the inside of the unit sphere with the hyperbolic metric; in two dimensions the Poincare disk), 2 atanh of the length of q seen from p, (-p) m_obius q. Near the middle it is twice the plain distance; toward the rim it grows without bound, so points near the rim a little apart in the plane are far apart along the ball. p and q must be inside the ball (length under 1).

      "mf:" u̲se< "Manifold"

      0.0 0.0 ᵐᶠb̲allDistance 0.5 0.0
1.0986122886681098

(p, q) b̲allGeodesic n: n + 1 points along the geodesic (the shortest path, by the ball's distance) from p to q, p first and q last, evenly spaced along it: p m_obius the arrow to q scaled by 0, 1/n, ..., 1 in the ball's way (tanh of that fraction of atanh its length). Drawn flat, a geodesic is an arc of a circle that meets the rim at right angles, or a diameter.

      "mf:" u̲se< "Manifold"

      (0.0 0.0, 0.6 0.0) ᵐᶠb̲allGeodesic 2
               0.0 0.0
0.3333333333333333 0.0
               0.6 0.0

D d̲istortion E: how badly the distances E (between every pair of points of an embedding, a matrix as s_phereDistances gives) keep the distances D they should have (the same shape: the data's own distances, say along a tree): for every pair of different points, |E / D - 1|, the fraction by which the pair's distance is too long or too short; the mean over the pairs and the worst pair, as a pair of Floats. 0 0 when every distance is kept; 1 for a pair twice or half as far as it should be (half: 0.5). Pairs at D = 0 (the same point twice) are left out; the diagonal always is. The measure of H1 (docs/research-questions.md), the same whatever space E was measured along.

      "mf:" u̲se< "Manifold"

      D ← 3 3 r̲eshape 0.0 1.0 2.0 1.0 0.0 1.0 2.0 1.0 0.0

      D ᵐᶠd̲istortion D
0.0 0.0

      D ᵐᶠd̲istortion 2.0 × D
1.0 1.0

      D ᵐᶠd̲istortion 3 3 r̲eshape 0.0 1.0 1.0 1.0 0.0 1.0 1.0 1.0 0.0
0.16666666666666666 0.5