Metadata-Version: 2.4
Name: dynvision
Version: 0.1.0
Summary: Dynamical Vision Modeling
Author: Robin Gutzen
Description-Content-Type: text/markdown
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
License-File: LICENSE
Requires-Dist: ruamel.yaml ~=0.18.3
Requires-Dist: python-dotenv ~=1.0.1
Requires-Dist: scipy ==1.12
Requires-Dist: snakemake ~=9.1.5
Requires-Dist: snakemake-executor-plugin-cluster-generic ~=1.0.0
Requires-Dist: scikit-learn >=1.2.0,<2
Requires-Dist: scikit-image ~=0.20.0
Requires-Dist: torch >=2.2.0
Requires-Dist: torchvision >=0.16.0
Requires-Dist: torchsummary ~=1.5.0
Requires-Dist: matplotlib ~=3.5.1
Requires-Dist: seaborn ~=0.13.0
Requires-Dist: jupyterlab ~=4.0.0
Requires-Dist: ipympl ~=0.7.0
Requires-Dist: tqdm ~=4.66.0
Requires-Dist: wandb
Requires-Dist: pytorch-lightning >=2.0.0
Requires-Dist: tensorboard
Requires-Dist: numba ~= 0.61.0
Requires-Dist: pillow == 10.0.0
Requires-Dist: ffcv ~= 1.0.2
Requires-Dist: black ; extra == "dev"
Requires-Dist: bump2version ; extra == "dev"
Requires-Dist: flake8 ; extra == "dev"
Requires-Dist: mypy ; extra == "dev"
Requires-Dist: pre-commit ; extra == "dev"
Requires-Dist: pydocstyle ; extra == "dev"
Requires-Dist: pylint ; extra == "dev"
Requires-Dist: pytest ; extra == "dev"
Requires-Dist: pytest-black ; extra == "dev"
Requires-Dist: pytest-cov ; extra == "dev"
Requires-Dist: pytest-flake8 ; extra == "dev"
Requires-Dist: pytest-mypy ; extra == "dev"
Requires-Dist: pytest-pydocstyle ; extra == "dev"
Requires-Dist: pytest-pylint ; extra == "dev"
Requires-Dist: pytest-xdist ; extra == "dev"
Requires-Dist: mkdocs>=1.6.0 ; extra == "doc"
Requires-Dist: mkdocs-material>=9.5.0 ; extra == "doc"
Requires-Dist: mkdocstrings[python]>=0.24.0 ; extra == "doc"
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2.0 ; extra == "doc"
Requires-Dist: mkdocs-autorefs>=0.5.0 ; extra == "doc"
Requires-Dist: pymdown-extensions>=10.0 ; extra == "doc"
Provides-Extra: dev
Provides-Extra: doc

# DynVision: A Modeling Toolbox for Biologically Plausible Recurrent Visual Networks

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.2+-red.svg)](https://pytorch.org/)
[![PyPI](https://img.shields.io/pypi/v/dynvision)](https://pypi.org/project/dynvision/)
[![CI](https://github.com/Lindsay-Lab/DynVision/actions/workflows/test.yml/badge.svg)](https://github.com/Lindsay-Lab/DynVision/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Preprint](https://badges.ws/badge/Preprint-10.1101%2F2025.08.11.669756%20-B31B1B)](https://doi.org/10.1101/2025.08.11.669756)
<!-- Zenodo DOI badge: replace XXXXXXXX after first GitHub release triggers archival -->
<!-- [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.XXXXXXXX.svg)](https://doi.org/10.5281/zenodo.XXXXXXXX) -->
[![Docs](https://img.shields.io/badge/docs-up%20to%20date-brightgreen)](https://dynvision.readthedocs.io)

DynVision is a modular toolbox for constructing and evaluating recurrent convolutional neural networks (RCNNs) with biologically inspired dynamics. It provides a flexible framework for exploring how recurrent connections and temporal dynamics shape visual processing in artificial neural networks and how these networks can be aligned with properties of biological visual systems.

<p align="center">
  <img src="docs/assets/overview.png" alt="DynVision Overview" width="600"/>
</p>

## Key Features

- **Biologically Plausible Dynamics**: Implement neural dynamics governed by continuous differential equations with realistic time constants and delays
- **Diverse Recurrent Architectures**: Explore various recurrent connection types (self, full, depthwise, pointwise, local topographic)
- **Minimal Coding Requirements**: Customization of models, training hyperparameters, testing scenarios, data selection, parameter sweeps, visualizations can be achieved by editing by human-readable config files. For more elaborate extensions there are template files and guides.
- **Modular Components**: Easily combine and reconfigure biologically-inspired features:
  - Recurrent processing within and across areas
  - Skip and feedback connections
  - Retinal preprocessing
  - Supralinear activation
  - Adaptive input gain
- **Modular Operation Order**: Easily rearrange the execution order of layer operations like convolution, adding recurrence, applying delays, nonlinearity, pooling, recording activity, etc.
- **Efficient Workflow Management**: Leverages Snakemake for reproducible experiments and parameter sweeps
- **PyTorch Lightning Integration**: Standardized training with minimal boilerplate
- **Optimized Performance**: Fast data loading with FFCV, GPU acceleration, mixed precision
- **Pre-built Model Zoo**: Access pre-implemented architectures like AlexNet, CorNetRT, ResNet variants, CordsNet, and DyRCNNx4/8

## Installation

**Python requirement**: Python 3.11+ (3.12 support pending FFCV compatibility testing — see [Python 3.12 Compatibility](docs/development/python-3.12-compatibility.md)).

```bash
# Clone repository
git clone https://github.com/Lindsay-Lab/dynvision.git
cd dynvision

# Create conda environment (recommended)
conda create -n dynvision python=3.11
conda activate dynvision

# Install PyTorch with CUDA (adjust as needed)
conda install pytorch torchvision pytorch-cuda=11.8 -c pytorch -c nvidia

# Install DynVision in editable mode
pip install -e .
```

For more detailed installation instructions, see the [Installation Guide](docs/user-guide/installation.md).

## Quick Start

```python
import torch
from dynvision.models import DyRCNNx4

# Create a 4-layer RCNN with recurrent connections
model = DyRCNNx4(
    n_classes=10,
    input_dims=(20, 3, 224, 224),  # (timesteps, channels, height, width)
    recurrence_type="full",        # Full recurrent connectivity
    dt=2,                          # Integration time step (ms)
    tau=5,                         # Neural time constant (ms)
    tff=8,                         # feedforward delay (ms)
    trc=4,                         # recurrence delay (ms)
)

# Forward pass with a batch of inputs
batch = torch.randn(1, 20, 3, 224, 224)  # (batch, timesteps, channels, height, width)
outputs = model(batch)
```

For a step-by-step tutorial, see the [Getting Started](docs/getting-started.md) guide.

## Example Experiments

DynVision includes pre-configured experiments to explore temporal response properties of different recurrent architectures:

```bash
# Train and run contrast response experiment with on multiple models
snakemake --config experiment=contrast model_name=['AlexNet', 'ResNet18', 'CorNetRT'] data_name=cifar100

# Evaluate stimulus duration effects with different recurrence types
snakemake -j4 --config experiment=duration model_name=DyRCNNx4 model_args="{rctype: [full, self, pointdepthwise]}"
```

<p align="center">
  <img src="docs/assets/tau.png" alt="Temporal Dynamics Example" width="600"/>
</p>

## Documentation

- [Getting Started](docs/getting-started.md): Beginner's tutorial
- [User Guide](docs/user-guide/index.md): How-to guides for common tasks
- [API Reference](docs/reference/index.md): Technical documentation
- [Concepts](docs/explanation/concepts.md): Explanation of core concepts
- [Contributing](docs/contributing.md): How to contribute to the project
- [Developer Guide](docs/development/index.md): Resources for contributors and AI assistants

> **For Claude Code Users**: The comprehensive developer guide (formerly `CLAUDE.md` in project root) is now at [`docs/development/guides/claude-guide.md`](docs/development/guides/claude-guide.md).

## Citation

If you use DynVision in your research, please cite both the software and the preprint:

```bibtex
@software{Gutzen_DynVision,
  author       = {Gutzen, Robin and Lindsay, Grace W.},
  title        = {DynVision: A Modeling Toolbox for Biologically Plausible
                   Recurrent Visual Networks},
  year         = 2026,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.XXXXXXXX},
  url          = {https://github.com/Lindsay-Lab/DynVision},
  note         = {Replace XXXXXXXX with DOI from https://zenodo.org after first release}
}

@article{Gutzen2025_2025.08.11.669756,
  title        = {DynVision: A Toolbox for Biologically Plausible Recurrent
                   Convolutional Networks},
  shorttitle   = {{{DynVision}}},
  author       = {Gutzen, Robin and Lindsay, Grace W.},
  year         = 2025,
  pages        = {2025.08.11.669756},
  publisher    = {bioRxiv},
  doi          = {10.1101/2025.08.11.669756},
}
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

