Fisher manifolds

[Nimrais]

Fisher Information Metric for Exponential Family Manifolds

The PR introduces a specialized manifold wrapper WithMetric equipped with NaturalMetric. This construction represents an exponential family manifold where the Riemannian metric is defined by the Fisher Information Matrix (FIM) in natural coordinates.

Key Features

The primary goal of this feature is to ensure geometric consistency between the metric and the exponential map. In a properly defined Riemannian manifold, the geodesic curves generated by exp! must be consistent with the metric defined by inner.

We implement exact geodesics and transport operations for specific distributions to guarantee this consistency, which is verified via ManifoldsBase.check_geodesic.

1. Fisher Information Metric

The NaturalMetric type integrates the Fisher information matrix as a Riemannian metric.

2. Exact Geodesics

For supported manifolds, we override the default ManifoldsBase behavior to provide exact solutions for:

• Geodesics (exp!, exp_fused!): Analytical solutions to the geodesic equation.
• Logarithmic Map (log!): The inverse of the exponential map.
• Parallel Transport: Exact transport of vectors along geodesics.

Supported Distributions

Currently, exact geometric support is implemented for the following distributions:

Bernoulli

• Manifold: 1D manifold.
• Geometry: Isometric to a scaled sphere (or part thereof, depending on parametrization view), but handled here via explicit geodesic formulas derived from the Fisher metric.
• Implementation: src/metric_manifolds/bernoulli.jl

Normal

• Manifold: 2D manifold (Poincaré half-plane geometry).
• Geometry: The manifold of univariate normal distributions with the Fisher metric is isometric to the hyperbolic plane with constant negative curvature $K = -1/2$.
• Implementation: src/metric_manifolds/normal.jl uses the isomorphism to the Poincaré half-plane and hyperboloid model to compute geodesics and transport.

Usage Example

To use the Fisher metric manifold, use the get_fisher_manifold helper:

using ExponentialFamilyManifolds, Manifolds
using ExponentialFamily, Distributions

# 1. Create the Fisher manifold for Bernoulli
M = get_fisher_manifold(Bernoulli, ())

# 2. Generate points and vectors
p = rand(M)
X = rand(M; vector_at=p)

# 3. Compute exponential map (exact geodesic)
q = exp(M, p, X)

# 4. Compute inner product (Fisher metric)
# The metric is automatically handled
dot_prod = inner(M, p, X, X)

# 5. Check consistency (internal validation)
# is_geodesic = check_geodesic(M, p, X, q) 

Implementation Details

The implementation relies on the WithMetric wrapper which:

1. Stops forwarding of geometric functions (exp, log, parallel_transport, inner, norm) to the underlying natural parameter manifold.
2. Implements the Fisher metric logic directly.
3. Delegates to specialized implementations for supported distributions (Bernoulli, NormalMeanVariance).

For other distributions, you can still use WithMetric but you may need to provide your own retractions or metric definitions if exact geodesics are not yet implemented.

[codecov]

Codecov Report

❌ Patch coverage is 81.91126% with 53 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.39%. Comparing base (ec2a281) to head (419ae11).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/metric_manifolds/normal.jl	84.21%	30 Missing ⚠️
src/metric_manifolds/bernoulli.jl	58.92%	23 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #53      +/-   ##
==========================================
- Coverage   89.20%   88.39%   -0.81%     
==========================================
  Files          21       26       +5     
  Lines         250      543     +293     
==========================================
+ Hits          223      480     +257     
- Misses         27       63      +36     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.