{"id":32633671,"url":"https://github.com/maximusrafla/bilinear-modular-arithmetic","last_synced_at":"2026-05-06T00:34:02.405Z","repository":{"id":321672500,"uuid":"1086749486","full_name":"maximusrafla/bilinear-modular-arithmetic","owner":"maximusrafla","description":"Exploring bilinear neural network layers for modular addition with tensor decomposition analysis","archived":false,"fork":false,"pushed_at":"2025-10-30T21:21:18.000Z","size":4316,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-30T23:27:48.510Z","etag":null,"topics":["deep-learning","interpretability","machine-learning","mechanistic-interpretability","pytorch","tensor-networks"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maximusrafla.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-30T21:10:41.000Z","updated_at":"2025-10-30T21:21:22.000Z","dependencies_parsed_at":"2025-10-30T23:28:28.007Z","dependency_job_id":"c3a3b468-da29-43b9-b1e5-f5b574f147ec","html_url":"https://github.com/maximusrafla/bilinear-modular-arithmetic","commit_stats":null,"previous_names":["maximusrafla/bilinear-modular-arithmetic"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/maximusrafla/bilinear-modular-arithmetic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximusrafla%2Fbilinear-modular-arithmetic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximusrafla%2Fbilinear-modular-arithmetic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximusrafla%2Fbilinear-modular-arithmetic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximusrafla%2Fbilinear-modular-arithmetic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maximusrafla","download_url":"https://codeload.github.com/maximusrafla/bilinear-modular-arithmetic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximusrafla%2Fbilinear-modular-arithmetic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32673348,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","interpretability","machine-learning","mechanistic-interpretability","pytorch","tensor-networks"],"created_at":"2025-10-30T23:54:00.831Z","updated_at":"2026-05-06T00:34:02.393Z","avatar_url":"https://github.com/maximusrafla.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bilinear Layers for Modular Arithmetic\n\nAn exploration of bilinear neural network layers trained on modular addition, with analysis through tensor decomposition methods. This project reproduces and extends results from recent mechanistic interpretability research on bilinear architectures.\n\n## Overview\n\nThis repository implements a **bilinear layer** trained to perform modular addition: `f(a,b) = (a + b) mod 113`. Unlike standard MLPs, bilinear layers can be contracted into exact tensor representations, enabling analytical interpretability methods.\n\n**Key Finding**: Modular arithmetic learning produces a **distributed, multi-component representation** rather than a low-rank structure, suggesting the task fundamentally requires high-dimensional interactions.\n\n## Background\n\n### What are Bilinear Layers?\n\nA bilinear layer computes: `output = W_out(W1(x) ⊙ W2(x))` where ⊙ is element-wise multiplication.\n\n**Why interesting for interpretability?**\n- Can be contracted into exact 3rd-order tensors (no sampling error)\n- Analytically computable relationships between layers\n- Global structure visible through SVD decomposition\n\n### Papers Referenced\n- [Bilinear Layers Enable Rapid Learning and Prediction in Sequence Transformers](https://arxiv.org/abs/2410.08417)\n- [Interpreting Modular Addition in MLPs](https://www.lesswrong.com/posts/cbDEjnRheYn38Dpc5/interpreting-modular-addition-in-mlps) (Nanda et al.)\n\n## Results\n\n### Training Performance\n- **Final accuracy**: ~99%+ after 1000 epochs\n- **Architecture**: 226 → 256 → 113 (bilinear layer)\n- **Smooth convergence** with proper weight decay\n\n![Training Curves](results/training_curves.png)\n\n### Tensor Decomposition Analysis\n\nThe trained weights were contracted into a 3rd-order tensor `T[i,j,k]` representing how input positions `i` and `j` interact to produce output `k`.\n\n![Interaction Matrices](results/interaction_matrices.png)\n\n**Singular Value Analysis**: The ratio between consecutive singular values (~1.1) indicates the representation is **NOT low-rank**. This suggests modular addition requires distributed multi-dimensional interactions rather than simple linear projections.\n\n![Eigenvector Analysis](results/eigenvectors.png)\n\n### Key Observations\n\n1. **Distributed Representation**: No single component dominates (unlike highly compressible tasks with ratio \u003e5)\n2. **Periodic Structure**: Eigenvectors show oscillatory patterns potentially corresponding to modular arithmetic's cyclic properties\n3. **Symmetry**: Mode-1 and Mode-2 show similar structures, confirming addition's commutativity\n\n## Installation\n\n```bash\ngit clone https://github.com/maximusrafla/bilinear-modular-arithmetic.git\ncd bilinear-modular-arithmetic\npip install -r requirements.txt\n```\n\n**Requirements**:\n- Python 3.8+\n- PyTorch\n- NumPy\n- Matplotlib\n\n## Usage\n\n### Train the model\n\n```bash\npython train.py\n```\n\nThis generates:\n- `bilinear_model.pt` - trained model checkpoint\n- `results/training_curves.png` - loss and accuracy plots\n\n### Analyze the learned representation\n\n```bash\npython analyze.py\n```\n\nThis generates:\n- `results/interaction_matrices.png` - tensor slices\n- `results/eigenvector_analysis.png` - SVD components\n- `results/eigenvector_heatmaps.png` - structure visualization\n\n## Project Structure\n\n```\nbilinear-modular-arithmetic/\n├── train.py              # Training script\n├── analyze.py            # Tensor decomposition analysis\n├── requirements.txt      # Dependencies\n├── results/              # Generated visualizations\n│   ├── training_curves.png\n│   ├── interaction_matrices.png\n│   ├── eigenvector_analysis.png\n│   └── eigenvector_heatmaps.png\n└── README.md\n```\n\n## Technical Details\n\n### Model Architecture\n- **Input**: Two concatenated one-hot vectors (226-dimensional)\n- **Hidden**: 256-dimensional bilinear transformation\n- **Output**: 113-dimensional (one per class)\n- **Total parameters**: ~350K\n\n### Training Configuration\n- **Dataset**: 20,000 random samples from all possible (a,b) pairs\n- **Optimizer**: Adam with lr=0.001\n- **Weight decay**: 0.01 (critical for generalization)\n- **Epochs**: 1000\n\n### Analysis Method\n\n1. **Weight Contraction**: Compute `T[i,j,k] = Σ_h (W1[h,i] × W2[h,j] × W_out[k,h])`\n2. **Mode Unfolding**: Reshape tensor for SVD analysis\n3. **SVD Decomposition**: Extract top components and singular values\n4. **Visualization**: Plot interaction patterns and eigenvector structure\n\n## Interpretability Implications\n\n### Challenges for Feature Extraction\nThe distributed representation poses challenges for:\n- **Sparse Autoencoders**: Would need many features to capture the full algorithm\n- **Linear Probing**: Single directions unlikely to capture modular behavior\n- **Dimensionality Reduction**: Top SVD components alone insufficient\n\n### Benefits of Tensor Networks\nDespite complexity, tensor networks provide:\n- **Exact contractability**: Analytical computation of full tensor\n- **Global structure**: SVD reveals overall complexity\n- **No sampling error**: Deterministic analysis vs activation-based methods\n\n## Future Directions\n\n- Compare to standard MLP representations\n- Test different moduli (does structure change with prime P?)\n- Explore other operations (multiplication, more complex functions)\n- Progressive analysis during training\n- Circuit extraction from contracted tensor\n\n## Citation\n\nIf you use this code or build upon this work, please cite the original bilinear layer paper:\n\n```bibtex\n@article{pearce2024bilinear,\n  title={Bilinear MLPs enable weight-based mechanistic interpretability},\n  author={Pearce, Michael T. and Dooms, Thomas and Rigg, Alice and Oramas, Jose M. and Sharkey, Lee},\n  journal={arXiv preprint arXiv:2410.08417},\n  year={2024}\n}\n```\n\n## License\n\nMIT License - feel free to use and modify!\n\n## Author\n\nMaximus Rafla  \n[GitHub](https://github.com/maximusrafla) | [LinkedIn](https://www.linkedin.com/in/maximus-rafla/)\n\n---\n\n*This project explores tensor network interpretability methods for understanding learned algorithms in neural networks.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximusrafla%2Fbilinear-modular-arithmetic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaximusrafla%2Fbilinear-modular-arithmetic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximusrafla%2Fbilinear-modular-arithmetic/lists"}