# mli0118/riemannian-optimization architecture

> Architecture diagram of the GitHub repository mli0118/riemannian-optimization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mli0118/riemannian-optimization
- Repository: https://github.com/mli0118/riemannian-optimization

## Overview

This repository contains research experiments for deterministic and stochastic Riemannian bilevel optimization, rather than a general-purpose application. The BCI experiments implement Grassmann, Stiefel, and synthetic hyperbolic variants; the stochastic experiments evaluate three manifolds on UCI Superconductivity data, comparing SR-HJFBiO with hypergradient baselines. The main workflow is to load or generate data, construct manifold-specific features, run an optimizer, save trajectories, and plot or compare results. The README is empty, and sampled excerpts are partial, so links between unsampled experiment internals are omitted where their wiring is unclear.

Main entry points: [`Stochastic experiment/run_experiment.py`](https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/run_experiment.py) (Stochastic runs), [`Stochastic experiment/run_comparison.py`](https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/run_comparison.py) (Method comparison), [`Stochastic experiment/feature_maps.py`](https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/feature_maps.py) (Feature maps), [`Stochastic experiment/manifolds.py`](https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/manifolds.py) (Manifold operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bci["BCI Experiments"]
  node_bci_grass["Grassmann BCI<br/>[bci_grassmann.py]"]
  node_bci_stiefel["Stiefel BCI<br/>[bci_stiefel.py]"]
  node_bci_hyp["Synthetic hyperbolic<br/>[bci_hyperbolic.py]"]
  node_grass_diag["Grassmann diagnostics"]
  node_stiefel_diag["Stiefel diagnostics"]
  node_hyp_diag["Hyperbolic diagnostics"]
end

subgraph group_stochastic["Stochastic Experiments"]
  node_data["Data loading<br/>[data.py]"]
  node_features["Feature maps<br/>[feature_maps.py]"]
  node_manifolds["Manifold operations<br/>[manifolds.py]"]
  node_sr_algo["SR-HJFBiO<br/>[algorithm.py]"]
  node_baselines["Hypergradient baselines<br/>[han_baselines.py]"]
  node_run_stoch["Stochastic runs<br/>[run_experiment.py]"]
  node_run_compare["Method comparison<br/>[run_comparison.py]"]
end

subgraph group_analysis["Analysis"]
  node_grass_plot["Grassmann plots"]
  node_stiefel_plot["Stiefel plots"]
  node_hyp_plot["Hyperbolic plots"]
  node_trajectories["Saved trajectories"]
  node_plot_stoch["Trajectory plots<br/>[plot_results.py]"]
  node_plot_compare["Comparison plots<br/>[plot_comparison.py]"]
end

node_bci_user(("Experiment runner"))
node_stoch_user(("Experiment runner"))
node_uci_data[("UCI data source")]

node_bci_user -->|"runs study"| node_bci_grass
node_bci_user -->|"runs study"| node_bci_stiefel
node_bci_user -->|"runs study"| node_bci_hyp
node_bci_user -->|"runs diagnostics"| node_grass_diag
node_bci_user -->|"runs diagnostics"| node_stiefel_diag
node_bci_user -->|"runs diagnostics"| node_hyp_diag
node_grass_diag -->|"uses experiment"| node_bci_grass
node_stiefel_diag -->|"uses experiment"| node_bci_stiefel
node_hyp_diag -->|"uses experiment"| node_bci_hyp
node_bci_grass -->|"produces results"| node_grass_plot
node_bci_stiefel -->|"produces results"| node_stiefel_plot
node_bci_hyp -->|"produces results"| node_hyp_plot
node_stoch_user -->|"starts runs"| node_run_stoch
node_stoch_user -->|"starts comparison"| node_run_compare
node_uci_data -->|"provides dataset"| node_data
node_run_stoch -->|"loads data"| node_data
node_run_compare -->|"loads data"| node_data
node_run_stoch -->|"constructs features"| node_features
node_run_stoch -->|"constructs manifold"| node_manifolds
node_run_stoch -->|"runs optimizer"| node_sr_algo
node_sr_algo -->|"computes features"| node_features
node_sr_algo -->|"projects and retracts"| node_manifolds
node_run_compare -->|"constructs features"| node_features
node_run_compare -->|"constructs manifold"| node_manifolds
node_run_compare -->|"runs strategies"| node_baselines
node_baselines -->|"computes features"| node_features
node_baselines -->|"updates manifold"| node_manifolds
node_run_stoch -->|"saves runs"| node_trajectories
node_run_compare -->|"saves comparison"| node_trajectories
node_trajectories -->|"read trajectories"| node_plot_stoch
node_trajectories -->|"read trajectories"| node_plot_compare

click node_bci_grass "https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/bci_grassmann.py"
click node_bci_stiefel "https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/bci_stiefel.py"
click node_bci_hyp "https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/bci_hyperbolic.py"
click node_grass_diag "https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/run_grassmann_diag.py"
click node_stiefel_diag "https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/run_stiefel_diag.py"
click node_hyp_diag "https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/run_hyperbolic_diag.py"
click node_grass_plot "https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/plot_grassmann_3panel.py"
click node_stiefel_plot "https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/plot_stiefel_3panel.py"
click node_hyp_plot "https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/plot_hyperbolic_3panel.py"
click node_data "https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/data.py"
click node_features "https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/feature_maps.py"
click node_manifolds "https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/manifolds.py"
click node_sr_algo "https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/algorithm.py"
click node_baselines "https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/han_baselines.py"
click node_run_stoch "https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/run_experiment.py"
click node_run_compare "https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/run_comparison.py"
click node_plot_stoch "https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/plot_results.py"
click node_plot_compare "https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/plot_comparison.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bci_grass,node_bci_stiefel,node_bci_hyp,node_grass_diag,node_stiefel_diag,node_hyp_diag toneBlue
class node_data,node_features,node_manifolds,node_sr_algo,node_baselines,node_run_stoch,node_run_compare,node_uci_data toneAmber
class node_grass_plot,node_stiefel_plot,node_hyp_plot,node_trajectories,node_plot_stoch,node_plot_compare toneMint
class node_bci_user,node_stoch_user toneIndigo
```

## Components

### BCI Experiments

- [Grassmann BCI](https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/bci_grassmann.py): `BCI experiment/bci_grassmann.py`
- [Stiefel BCI](https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/bci_stiefel.py): `BCI experiment/bci_stiefel.py`
- [Synthetic hyperbolic](https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/bci_hyperbolic.py): `BCI experiment/bci_hyperbolic.py`
- [Grassmann diagnostics](https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/run_grassmann_diag.py): `BCI experiment/run_grassmann_diag.py`
- [Stiefel diagnostics](https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/run_stiefel_diag.py): `BCI experiment/run_stiefel_diag.py`
- [Hyperbolic diagnostics](https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/run_hyperbolic_diag.py): `BCI experiment/run_hyperbolic_diag.py`

### Stochastic Experiments

- [Data loading](https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/data.py): `Stochastic experiment/data.py`
- [Feature maps](https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/feature_maps.py): `Stochastic experiment/feature_maps.py`
- [Manifold operations](https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/manifolds.py): `Stochastic experiment/manifolds.py`
- [SR-HJFBiO](https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/algorithm.py): `Stochastic experiment/algorithm.py`
- [Hypergradient baselines](https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/han_baselines.py): `Stochastic experiment/han_baselines.py`
- [Stochastic runs](https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/run_experiment.py): `Stochastic experiment/run_experiment.py`
- [Method comparison](https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/run_comparison.py): `Stochastic experiment/run_comparison.py`

### Analysis

- [Grassmann plots](https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/plot_grassmann_3panel.py): `BCI experiment/plot_grassmann_3panel.py`
- [Stiefel plots](https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/plot_stiefel_3panel.py): `BCI experiment/plot_stiefel_3panel.py`
- [Hyperbolic plots](https://github.com/mli0118/riemannian-optimization/blob/main/BCI%20experiment/plot_hyperbolic_3panel.py): `BCI experiment/plot_hyperbolic_3panel.py`
- **Saved trajectories**
- [Trajectory plots](https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/plot_results.py): `Stochastic experiment/plot_results.py`
- [Comparison plots](https://github.com/mli0118/riemannian-optimization/blob/main/Stochastic%20experiment/plot_comparison.py): `Stochastic experiment/plot_comparison.py`

### Other components

- **Experiment runner**
- **Experiment runner**
- **UCI data source**

## Connections

- Experiment runner → Grassmann BCI: runs study
- Experiment runner → Stiefel BCI: runs study
- Experiment runner → Synthetic hyperbolic: runs study
- Experiment runner → Grassmann diagnostics: runs diagnostics
- Experiment runner → Stiefel diagnostics: runs diagnostics
- Experiment runner → Hyperbolic diagnostics: runs diagnostics
- Grassmann diagnostics → Grassmann BCI: uses experiment
- Stiefel diagnostics → Stiefel BCI: uses experiment
- Hyperbolic diagnostics → Synthetic hyperbolic: uses experiment
- Grassmann BCI → Grassmann plots: produces results
- Stiefel BCI → Stiefel plots: produces results
- Synthetic hyperbolic → Hyperbolic plots: produces results
- Experiment runner → Stochastic runs: starts runs
- Experiment runner → Method comparison: starts comparison
- UCI data source → Data loading: provides dataset
- Stochastic runs → Data loading: loads data
- Method comparison → Data loading: loads data
- Stochastic runs → Feature maps: constructs features
- Stochastic runs → Manifold operations: constructs manifold
- Stochastic runs → SR-HJFBiO: runs optimizer
- SR-HJFBiO → Feature maps: computes features
- SR-HJFBiO → Manifold operations: projects and retracts
- Method comparison → Feature maps: constructs features
- Method comparison → Manifold operations: constructs manifold
- Method comparison → Hypergradient baselines: runs strategies
- Hypergradient baselines → Feature maps: computes features
- Hypergradient baselines → Manifold operations: updates manifold
- Stochastic runs → Saved trajectories: saves runs
- Method comparison → Saved trajectories: saves comparison
- Saved trajectories → Trajectory plots: read trajectories
- Saved trajectories → Comparison plots: read trajectories