Metadata-Version: 2.4
Name: neural-dimensionality-tracker
Version: 0.1.0
Summary: High-frequency monitoring of neural network representational dimensionality
Author-email: Javier Marín <javier@jmarin.info>
License: MIT
Project-URL: Homepage, https://github.com/Javihaus/ndt
Project-URL: Documentation, https://neural-dimensionality-tracker.readthedocs.io
Project-URL: Repository, https://github.com/Javihaus/ndt
Project-URL: Bug Tracker, https://github.com/Javihaus/ndt/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=1.12.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: plotly>=5.0.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: tqdm>=4.62.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: h5py>=3.6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.4.0; extra == "docs"
Requires-Dist: mkdocs-material>=8.5.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.19.0; extra == "docs"
Provides-Extra: jax
Requires-Dist: jax>=0.4.0; extra == "jax"
Requires-Dist: jaxlib>=0.4.0; extra == "jax"
Dynamic: license-file

# Neural Dimensionality Tracker (NDT)

[![Tests](https://github.com/Javihaus/ndt/workflows/Tests/badge.svg)](https://github.com/Javihaus/ndt/actions)
[![PyPI version](https://badge.fury.io/py/neural-dimensionality-tracker.svg)](https://pypi.org/project/neural-dimensionality-tracker/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

High-frequency monitoring of neural network representational dimensionality during training. Track how your network's internal representations evolve, detect phase transitions, and gain insights into the learning dynamics of deep neural networks.

## Features

- **Minimal Intrusion**: Add dimensionality tracking to any PyTorch model with just 3 lines of code
- **Architecture-Agnostic**: Automatic support for MLPs, CNNs, Transformers, and Vision Transformers
- **Multiple Metrics**: Track 4 complementary dimensionality measures
- **Jump Detection**: Automatically identify phase transitions during training
- **Rich Visualization**: Built-in plotting with Matplotlib and interactive Plotly dashboards
- **Flexible Export**: Save results as CSV, JSON, or HDF5
- **Production-Ready**: Fully typed, tested (>90% coverage), and documented

## Installation

```bash
pip install neural-dimensionality-tracker
```

## Quick Start

```python
import torch.nn as nn
from ndt import HighFrequencyTracker

# Your model
model = nn.Sequential(
    nn.Linear(784, 512), nn.ReLU(),
    nn.Linear(512, 256), nn.ReLU(),
    nn.Linear(256, 10)
)

# Create tracker
tracker = HighFrequencyTracker(model, sampling_frequency=10)

# Training loop
for step, (x, y) in enumerate(dataloader):
    output = model(x)
    loss = criterion(output, y)
    loss.backward()
    optimizer.step()

    tracker.log(step, loss.item())  # One line!

# Analyze
results = tracker.get_results()
from ndt import plot_phases
plot_phases(results, metric="stable_rank")
```

## Documentation

See [examples/](examples/) for complete working examples and detailed usage guides.

## License

MIT License - see [LICENSE](LICENSE) file for details
