nsa-flow 0.1.0__tar.gz

nsa_flow-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: nsa_flow
+Version: 0.1.0
+Summary: Non-negative Stiefel Approximating Flow for interpretable representation learning
+Author-email: "B. Avants" <stnava@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/stnava/nsa_flow
+Project-URL: Repository, https://github.com/stnava/nsa_flow
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: torch>=2.0
+Requires-Dist: numpy>=1.23
+Requires-Dist: matplotlib>=3.7
+
+# 🧠 NSA-Flow: Non-negative Stiefel Approximating Flow
+
+**NSA-Flow** is a general-purpose optimization framework for interpretable representation learning.  
+It unifies sparse matrix factorization, orthogonalization, and manifold constraints into a single, differentiable algorithm that operates near the Stiefel manifold.
+
+---
+
+## ✨ Overview
+
+Interpretable representation learning remains a core challenge in high-dimensional domains such as neuroimaging, genomics, and text analysis.  
+**NSA-Flow** provides a smooth geometric mechanism for balancing **reconstruction fidelity** and **column-wise decorrelation**, producing sparse, stable, and interpretable representations.
+
+NSA-Flow enforces structured sparsity via a single tunable weight parameter, combining:
+- Continuous orthogonality control via manifold retraction (e.g., soft-polar, polar)
+- Non-negativity via proximal updates
+- Adaptive gradient scaling and learning-rate control
+
+---
+
+## 🧩 Key Features
+
+- ⚙️ **Continuous flow near the Stiefel manifold**
+- 🧮 **Non-negative and orthogonal constraints**
+- 🧠 **Interpretable latent representations**
+- 🚀 **Compatible with PyTorch optimization routines**
+- 🧬 **Validated on neuroimaging and genomics datasets**
+
+---
+
+## 📦 Installation
+
+Install from PyPI (once published):
+
+```bash
+pip install nsa_flow
+
+Or install the latest development version directly from GitHub:
+
+pip install git+https://github.com/stnava/nsa_flow.git
+
+
+⸻
+
+🧰 Dependencies
+	•	Python ≥ 3.9
+	•	PyTorch ≥ 2.0
+	•	NumPy ≥ 1.23
+	•	Matplotlib (for optional visualization)
+
+⸻
+
+🚀 Quick Start
+
+import torch
+import nsa_flow
+from nsa_flow import nsa_flow, invariant_orthogonality_defect
+
+torch.manual_seed(42)
+
+# Random initialization
+Y = torch.randn(50, 10)
+X0 = torch.randn_like(Y)
+
+# Run NSA-Flow optimization
+result = nsa_flow(
+    Y,
+    X0=X0,
+    w=0.8,
+    retraction="soft_polar",
+    optimizer="sgdp",
+    max_iter=50,
+    record_every=1,
+    tol=1e-8,
+    initial_learning_rate=1e-2,
+    verbose=True,
+)
+
+print("Initial orthogonality defect:", invariant_orthogonality_defect(Y))
+print("Final orthogonality defect:", invariant_orthogonality_defect(result["Y"]))
+
+
+⸻
+
+📖 Documentation
+
+NSA-Flow exposes a small set of high-level functions:
+
+Function	Description
+nsa_flow()	Main optimization loop balancing fidelity and orthogonality
+nsa_flow_retract_auto()	Retraction operator enforcing manifold constraints
+invariant_orthogonality_defect()	Computes orthogonality defect measure
+defect_fast()	Fast approximate defect metric
+nsa_flow_autograd()	Autograd-compatible variant for joint optimization
+get_torch_optimizer()	Returns a configured PyTorch optimizer
+
+
+⸻
+
+🧪 Validation
+
+NSA-Flow has been validated in:
+	•	Golub leukemia gene expression dataset
+	•	Alzheimer’s Disease Neuroimaging Initiative (ADNI) dataset
+
+NSA-Flow constraints maintain or improve performance while simplifying latent representations and improving interpretability.
+
+⸻
+
+🧑‍💻 Citation
+
+If you use NSA-Flow in research, please cite:
+
+Stnava et al. (2025). NSA-Flow: Non-negative Stiefel Approximating Flow for Interpretable Representation Learning.
+
+⸻
+
+⚖️ License
+
+MIT License © 2025 
+
+⸻
+
+📫 Contact
+
+For issues, feature requests, or contributions, open an issue on
+GitHub.
+
+---
+
+
+

nsa_flow-0.1.0/README.md

@@ -0,0 +1,131 @@
+# 🧠 NSA-Flow: Non-negative Stiefel Approximating Flow
+
+**NSA-Flow** is a general-purpose optimization framework for interpretable representation learning.  
+It unifies sparse matrix factorization, orthogonalization, and manifold constraints into a single, differentiable algorithm that operates near the Stiefel manifold.
+
+---
+
+## ✨ Overview
+
+Interpretable representation learning remains a core challenge in high-dimensional domains such as neuroimaging, genomics, and text analysis.  
+**NSA-Flow** provides a smooth geometric mechanism for balancing **reconstruction fidelity** and **column-wise decorrelation**, producing sparse, stable, and interpretable representations.
+
+NSA-Flow enforces structured sparsity via a single tunable weight parameter, combining:
+- Continuous orthogonality control via manifold retraction (e.g., soft-polar, polar)
+- Non-negativity via proximal updates
+- Adaptive gradient scaling and learning-rate control
+
+---
+
+## 🧩 Key Features
+
+- ⚙️ **Continuous flow near the Stiefel manifold**
+- 🧮 **Non-negative and orthogonal constraints**
+- 🧠 **Interpretable latent representations**
+- 🚀 **Compatible with PyTorch optimization routines**
+- 🧬 **Validated on neuroimaging and genomics datasets**
+
+---
+
+## 📦 Installation
+
+Install from PyPI (once published):
+
+```bash
+pip install nsa_flow
+
+Or install the latest development version directly from GitHub:
+
+pip install git+https://github.com/stnava/nsa_flow.git
+
+
+⸻
+
+🧰 Dependencies
+	•	Python ≥ 3.9
+	•	PyTorch ≥ 2.0
+	•	NumPy ≥ 1.23
+	•	Matplotlib (for optional visualization)
+
+⸻
+
+🚀 Quick Start
+
+import torch
+import nsa_flow
+from nsa_flow import nsa_flow, invariant_orthogonality_defect
+
+torch.manual_seed(42)
+
+# Random initialization
+Y = torch.randn(50, 10)
+X0 = torch.randn_like(Y)
+
+# Run NSA-Flow optimization
+result = nsa_flow(
+    Y,
+    X0=X0,
+    w=0.8,
+    retraction="soft_polar",
+    optimizer="sgdp",
+    max_iter=50,
+    record_every=1,
+    tol=1e-8,
+    initial_learning_rate=1e-2,
+    verbose=True,
+)
+
+print("Initial orthogonality defect:", invariant_orthogonality_defect(Y))
+print("Final orthogonality defect:", invariant_orthogonality_defect(result["Y"]))
+
+
+⸻
+
+📖 Documentation
+
+NSA-Flow exposes a small set of high-level functions:
+
+Function	Description
+nsa_flow()	Main optimization loop balancing fidelity and orthogonality
+nsa_flow_retract_auto()	Retraction operator enforcing manifold constraints
+invariant_orthogonality_defect()	Computes orthogonality defect measure
+defect_fast()	Fast approximate defect metric
+nsa_flow_autograd()	Autograd-compatible variant for joint optimization
+get_torch_optimizer()	Returns a configured PyTorch optimizer
+
+
+⸻
+
+🧪 Validation
+
+NSA-Flow has been validated in:
+	•	Golub leukemia gene expression dataset
+	•	Alzheimer’s Disease Neuroimaging Initiative (ADNI) dataset
+
+NSA-Flow constraints maintain or improve performance while simplifying latent representations and improving interpretability.
+
+⸻
+
+🧑‍💻 Citation
+
+If you use NSA-Flow in research, please cite:
+
+Stnava et al. (2025). NSA-Flow: Non-negative Stiefel Approximating Flow for Interpretable Representation Learning.
+
+⸻
+
+⚖️ License
+
+MIT License © 2025 
+
+⸻
+
+📫 Contact
+
+For issues, feature requests, or contributions, open an issue on
+GitHub.
+
+---
+
+
+

nsa_flow-0.1.0/nsa_flow/__init__.py

@@ -0,0 +1,3 @@
+from .core import nsa_flow, nsa_flow_retract_auto, inv_sqrt_sym_adaptive, invariant_orthogonality_defect, energy_fidelity, nsa_flow_autograd, get_torch_optimizer, defect_fast
+__all__ = ["nsa_flow", "nsa_flow_retract_auto", "inv_sqrt_sym_adaptive", "invariant_orthogonality_defect", "energy_fidelity","nsa_flow_autograd","get_torch_optimizer","defect_fast"]
+