Metadata-Version: 2.4
Name: amtutorial
Version: 0.0.3
Summary: Add your description here
Author-email: Ben Hoover <24350185+bhoov@users.noreply.github.com>
License-File: LICENSE
Requires-Python: >=3.9
Requires-Dist: beautifulsoup4>=4.13.4
Requires-Dist: datasets>=3.6.0
Requires-Dist: einops>=0.8.1
Requires-Dist: equinox>=0.11.10
Requires-Dist: ffmpeg-python>=0.2.0
Requires-Dist: gdown>=5.2.0
Requires-Dist: imageio>=2.37.0
Requires-Dist: ipywidgets>=8.1.7
Requires-Dist: jax>=0.4.30
Requires-Dist: matplotlib>=3.9.4
Requires-Dist: moviepy<2.0
Requires-Dist: opencv-python>=4.11.0.86
Requires-Dist: scikit-learn>=1.6.1
Requires-Dist: scipy>=1.13.1
Requires-Dist: seaborn>=0.13.2
Requires-Dist: torch>=2.7.1
Requires-Dist: tqdm>=4.67.1
Description-Content-Type: text/markdown

# Getting started


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

This website serves as a living companion to the [tutorial manuscript]()
(coming soon!) to be presented at [ICML 2025](). It dreams of being a
one-stop shop for learning all things about Associative Memory. It’s
definitely not there yet.

See the [tutorials](./tutorial/index.ipynb) for a brief introduction to
the list of example notebooks.

## Installation

We have tried to streamline the installation of the repo as much as
possible.

### Pre-requisites

- Install
  [`uv`](https://docs.astral.sh/uv/getting-started/installation/) using
  `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Install [`quarto`](https://quarto.org/docs/download/)
- We use
  [`conda`](https://www.anaconda.com/docs/getting-started/miniconda/install)
  (or better yet, [`mamba`](https://github.com/conda-forge/miniforge))
  for managing the `ffmpeg` dependency, which only matters if `ffmpeg`
  is not already installed on your system.

### Setting up the environment

From the root of the repo:

``` sh
uv sync
source .venv/bin/activate
uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=amtutorial # Expose venv to ipython

# OPTIONAL: For rendering videos in notebooks
conda install conda-forge::ffmpeg conda-forge::openh264 

# OPTIONAL: For developing the interactive frontend
conda install conda-forge::nodejs
npm install --prefix javascript && npm run build --prefix javascript 
```

You can view a local version of the website with

    uv run nbdev_preview

### Development pipelines

To push a complete update to the website:

``` sh
git checkout main
# uv run python scripts/prep_pypi.py && nbdev_pypi # ONLY if `amtutorial/src` was updated
bash scripts/prep_website_deploy.sh && git add . && git commit -m "Update site" && git push
```

The site will be live after a few minutes on github.

**Reference scripts**

``` sh
uv run nbdev_preview                         # Preview website locally
bash scripts/prep_website_deploy.sh          # Sync dependencies, export qmd notebooks to ipynb for colab, and build website
bash scripts/export_qmd_as_ipynb.sh          # Export qmd notebooks to ipynb for colab
uv run python scripts/sync_dependencies.py   # Sync nbdev and pyproject.toml dependencies
uv run python scripts/prep_pypi.py           # Bump patch version and sync dependencies
uv run nbdev_pypi                            # Push to pypi
```

### Website structure

`.ipynb` versions of the tutorial notebooks are located in
`tutorial_ipynbs`. Setup the `uv` environment above to play with them
locally, or run them in Google Colab.

> [!NOTE]
>
> The first time you run the notebooks will be slow. We cache some of
> the long-running code after the first time, but this will not persist
> across Colab sessions

- [Binary Dense Storage
  Notebook](https://colab.research.google.com/github/bhoov/amtutorial/blob/main/tutorial_ipynbs/00_dense_storage.ipynb)
- [Energy Transformer
  Notebook](https://colab.research.google.com/github/bhoov/amtutorial/blob/main/tutorial_ipynbs/01_energy_transformer.ipynb)
- [Diffusion as Memory
  Notebook](https://colab.research.google.com/github/bhoov/amtutorial/blob/main/tutorial_ipynbs/02_diffusion_as_memory.ipynb)
- [Distributed Associative Memory
  Notebook](https://colab.research.google.com/github/bhoov/amtutorial/blob/main/tutorial_ipynbs/03_distributed_memory.ipynb)

The website ([](tutorial.amemory.net)) is built using an in-house fork
of [`nbdev`](https://github.com/bhoov/nbdev/tree/qmd_support) to allow
developing everything (i.e., the tutorials, corresponding `pip` package,
and documentation) using plain text representations of jupyter notebooks
in `.qmd` files. The website preserves the folder-based routing in the
`nbs/` folder.

With the [right
extensions](https://quarto.org/docs/tools/vscode/index.html) and
[hotkeys](https://github.com/bhoov/nbdev/blob/qmd_support/nbs/tutorials/develop_in_plain_text.qmd),
`.qmd` files are pleasant to develop inside VSCode and interop
seamlessly with both git and AI tooling.

## Deploying

Deploy to `tutorial.amemory.net` by pushing commits to the `main` branch
after building the site locally.

``` sh
uv run nbdev_export && uv run nbdev_docs && git add . && git commit -m "Update site" && git push
```
