Curvature

The geodesic spray splits each tangent space of $TM \setminus \{0\}$ into a vertical part, which is the fibre direction, and a horizontal part, which is the direction a geodesic moves in. Whether that horizontal distribution is integrable — whether the horizontal directions at a point fit together into a surface — is decided by the Nijenhuis torsion of the horizontal projector,

It vanishes identically exactly when the distribution is integrable, and it is the curvature. Riemann introduced the corresponding object in 1854 and Berwald gave the Finslerian construction in 1926; what the library computes is the coefficient form of the second, $R^i{}_{jk}$, which is antisymmetric in $j$ and $k$.

• The coefficients, and where they come from

  Writing $G^i{}_j = \partial G^i/\partial y^j$ for the Berwald connection coefficients and $G^i{}_{jk}$ for their velocity derivative,

  $$R^i{}_{jk} = \frac{\partial G^i{}_j}{\partial x^k} - \frac{\partial G^i{}_k}{\partial x^j} + G^m{}_j G^i{}_{km} - G^m{}_k G^i{}_{jm}.$$

  Nothing in that expression is written out in the library. $G^i$ is differentiated from the energy, $G^i{}_j$ from $G^i$, and $R^i{}_{jk}$ from those, so a metric cannot disagree with its own curvature. The cost of that is a third- and fourth-order derivative chain; see the last section.

Contracting the direction into the first lower index gives the Jacobi endomorphism $R_y = R(y, \cdot)$, with $R^i{}_k = R^i{}_{jk} y^j$ — the operator that appears in the Jacobi equation, and so the object that says whether nearby geodesics converge or separate. Its trace is the Ricci curvature $\mathrm{Ric}(y)$. Both are available as riemannian_curvature and ricci_curvature.

A Riemannian sectional curvature is a function of a plane. Choose two vectors spanning it and the answer is the same either way, because the metric does not record which direction the question came from. A Finsler metric does record it: the fundamental tensor $g_y$ is itself a function of the direction, so the plane alone does not determine a measurement. What determines one is a flag — a plane $P = \mathrm{span}\{y, u\}$ together with a distinguished direction $y$ in it, the flagpole:

The denominator is the squared area of the parallelogram on $y$ and $u$ measured in $g_y$, so it vanishes when the two are metrically parallel and the flag degenerates. Both arguments enter with degree zero: scaling either one leaves $\mathbf{K}$ where it was.

The size of the effect is not marginal. On a Randers metric with a position-dependent wind, holding the point and the plane fixed and turning only the flagpole moves $\mathbf{K}$ from $-0.69$ to $+0.10$, through zero. The same sweep on the Riemannian sea underneath it is constant to $3\times10^{-12}$. This is why flag_curvature(metric, x, y, u) takes the flagpole as an argument rather than choosing one.

When $g_y$ does not depend on $y$ the flagpole drops out of the definition, and $\mathbf{K}(P, y)$ becomes the classical sectional curvature of the Levi-Civita connection — the Gaussian curvature when the manifold is a surface. sectional_curvature computes that, and performs the degeneration rather than assuming it: a metric that declares itself Riemannian through is_riemannian takes the direct path, and any other is checked by evaluating the same plane from both of its edges and requiring the two to agree.

A metric that is genuinely Finslerian therefore raises, under jax.jit as well as eagerly, instead of returning one of several possible numbers under a name that promises a single one. The answer in that case is to name the flagpole and call flag_curvature.

A manifold has constant flag curvature $\lambda$ when $\mathbf{K}$ is $\lambda$ at every point, in every flag and from every flagpole. The Ricci curvature is then determined, $\mathrm{Ric}(y) = (n-1)\lambda F^2(x,y)$, which is the cheapest sharp test that a metric carries the curvature it is supposed to.

Shen classified the projectively flat Randers metrics of non-zero constant flag curvature in 2003: every one is isometric to a member of a single family on the unit ball, and the constant is always $-1/4$. That family is ProjectivelyFlatRanders, and with zero drift it is the Funk metric.

• Why the library ships a metric it does not otherwise need

  A curvature implementation can be checked against the round sphere, the hyperbolic plane and a surface of revolution, and all three are Riemannian. A Riemannian test cannot separate an index convention from a compensating sign elsewhere in the chain, because the two errors cancel on exactly the metrics where the flagpole does not matter. ProjectivelyFlatRanders is non-reversible — $F(x,y) \neq F(x,-y)$ — with a curvature known in closed form, so it separates them. The library reproduces its $-1/4$ to $5\times10^{-10}$ in double precision, in two and three dimensions, with and without drift.

Curvature is the deepest derivative chain in the library: the energy gives the spray, the spray gives the connection coefficients, and the curvature differentiates those again. Intermediates grow as $O(D^4)$ and compilation time grows sharply past $D = 8$, so this is machinery for analysing a geometry rather than for an inner training loop. Compile once with jax.jit and reuse.

Every quantity here also amplifies the Tikhonov term that regularises the spray solve. For a Randers metric approaching the causal boundary, $\lVert W \rVert_h \to 1$, or for a neural metric early in training, the fundamental tensor is close to degenerate and the curvature values are indicative rather than exact. If a curvature number is going into a figure, state the regime it was measured in.