floydnet 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

{floydnet-0.1.0.dist-info → floydnet-0.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: floydnet
-Version: 0.1.0
+Version: 0.1.1
 Summary: Floyd Multi-Head Attention: a drop-in variant of PyTorch MHA with module and function APIs
 Project-URL: Homepage, https://github.com/ocx-lab/FloydNet
 Project-URL: Repository, https://github.com/ocx-lab/FloydNet
@@ -230,49 +230,162 @@ Requires-Dist: pytest>=7.4; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# floyd-net
+# FloydNet
 
-Floyd Multi-Head Attention (F-MHA) is a drop-in variant of PyTorch's attention stack. It provides:
+Official implementation of an ICLR paper (TODO: add paper title, authors, and links/arXiv).
 
-- Module API: `FloydMultiheadAttention` mirroring `torch.nn.MultiheadAttention`
-- Functional API: `floyd_scaled_dot_product_attention` mirroring `torch.nn.functional.scaled_dot_product_attention`
+![Figure Pivotal Attention Mechanism for 2-Floyd/3-Floyd.](misc/pivotalattn2&3.png)
 
-Install and manage with `uv` for a modern Python workflow.
+This repository serves two audiences:
 
-## Quick start
+- **Engineering users**: reusable PyTorch components (functional attention APIs and Transformer-style blocks) under `src/`.
+- **Research users**: scripts/configs to reproduce paper experiments under `example/`.
 
+---
+
+## Introduction
+
+FloydNet is the official PyTorch implementation accompanying an ICLR paper (TODO).  
+The repository provides:
+
+1. **Reusable components**: a drop-in attention/Transformer-block interface intended for integration into existing projects.
+2. **Reproduction code**: end-to-end training/evaluation pipelines to reproduce the benchmarks reported in the paper.
+
+For algorithmic details, hyperparameter choices, and analysis, please refer to the paper (TODO: link).
+
+---
+
+## Repository Structure
+
+- `src/floydnet/`  
+  **Library code for reuse**  
+  Contains the functional attention API and module/block implementations.
+
+- `example/`  
+  **Experiment reproduction code**  
+  Includes benchmark-specific scripts, configs, and data preparation utilities.
+
+---
+
+## Using the Attention / Transformer Block
+
+This section targets **engineering users** who want to import FloydNet as a dependency.
+
+### Installation
+
+#### Option A: Install from PyPI
 ```bash
-# Install with uv (recommended)
-uv venv --python 3.10
-source .venv/bin/activate
-uv pip install -e .[dev]
+pip install floydnet
 ```
 
-```python
-import torch
-from floyd_net import FloydMultiheadAttention
+#### Option B: Install from source
+```bash
+git clone git@github.com:ocx-lab/FloydNet.git
+cd FloydNet
+pip install -e .
+```
 
-m = FloydMultiheadAttention(embed_dim=64, num_heads=8, batch_first=True)
-x = torch.randn(2, 16, 64)
-out, attn = m(x, x, x)
-print(out.shape)
+> Requirements: Python `>= 3.9`, PyTorch `>= 2.1` (see `pyproject.toml`).
+
+### Public API
+
+FloydNet re-exports the public API from `src/floydnet/__init__.py`, so you can import from the top-level package:
+
+- **Functional API**:
+  - `pivotal_attention` (see `src/floydnet/functional.py`)
+- **Module / block API**:
+  - `PivotalAttentionBlock` (see `src/floydnet/transformer.py`)
+
+```python
+from floydnet import pivotal_attention, PivotalAttentionBlock
 ```
 
-### Functional API
+### Minimal usage example
+
 ```python
 import torch
-import torch.nn.functional as F
-from floyd_net import floyd_scaled_dot_product_attention
+from floydnet import pivotal_attention, PivotalAttentionBlock
+
+# -------------------------
+# Module API (Transformer-style block)
+# Input is a 2D grid: (B, N, N, C)
+# -------------------------
+B, N, C = 2, 16, 64
+x = torch.randn(B, N, N, C)
 
-q = torch.randn(2, 8, 16, 64)  # (B, H, L, D)
-k = torch.randn(2, 8, 16, 64)
-v = torch.randn(2, 8, 16, 64)
-out = floyd_scaled_dot_product_attention(q, k, v)
+m = PivotalAttentionBlock(embed_dim=C, num_heads=8, dropout=0.0)
+out = m(x)  # (B, N, N, C)
 print(out.shape)
+
+# -------------------------
+# Functional API
+# All inputs are 5D: (B, H, N, N, D)
+# -------------------------
+B, H, N, D = 2, 8, 16, 64
+q_ik = torch.randn(B, H, N, N, D)
+k_ij = torch.randn(B, H, N, N, D)
+k_jk = torch.randn(B, H, N, N, D)
+v_ij = torch.randn(B, H, N, N, D)
+v_jk = torch.randn(B, H, N, N, D)
+
+y = pivotal_attention(q_ik, k_ij, k_jk, v_ij, v_jk)  # (B, H, N, N, D)
+print(y.shape)
 ```
 
-## Paper reproductions
-See `paper/` for dataset preparation, configs, and experiment templates to reproduce the results in the paper.
+---
+
+## Reproducing Paper Results
+
+This section targets **research users** who want to reproduce the experiments in the paper.
+
+See `example/README.md` For detailed description.
+
+### Environment setup
+
+We recommend using `uv` to create an isolated environment for the reproduction code under `example/`.
+
+```bash
+cd /path/to/FloydNet
+
+# 1) Create a uv virtual environment with Python 3.12
+uv venv --python 3.12
+
+# 2) Activate it
+source .venv/bin/activate
+
+# 3) Install extra dependencies for reproducing paper experiments
+uv pip install -r example/requirements.txt
+
+# 4) Install FloydNet (editable) for local development / imports
+uv pip install -e .
+```
+
+## Changelog (latest)
+
+- Full release with training and evaluation scripts for Graph Count, BREC, and TSP.
+- Added `pivotal_attention3` functional API for 3-Floyd attention.
+- Added additional configuration options in `PivotalAttentionBlock`.
+
+The full changelog is in [CHANGELOG.md](CHANGELOG.md).
+
+## Citation
+
+If you use this code in your research, please cite the paper:
+
+```bibtex
+@inproceedings{TODO,
+  title     = {TODO},
+  author    = {TODO},
+  booktitle = {International Conference on Learning Representations (ICLR)},
+  year      = {TODO},
+  url       = {TODO}
+}
+```
+
+(Alternatively, see [CITATION.cff](CITATION.cff).)
+
+---
 
 ## License
-MIT
+
+This project is licensed under the **Apache License 2.0**. See [LICENSE](LICENSE).

floydnet-0.1.1.dist-info/RECORD

@@ -0,0 +1,4 @@
+floydnet-0.1.1.dist-info/METADATA,sha256=NRDtZp6xWpO3XK2Sm4ZUUZ1XzaWlic7Q936GizgI12s,18525
+floydnet-0.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+floydnet-0.1.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+floydnet-0.1.1.dist-info/RECORD,,

floydnet-0.1.0.dist-info/RECORD

@@ -1,4 +0,0 @@
-floydnet-0.1.0.dist-info/METADATA,sha256=CEiEOoK6xaTHx3JaiDTML-D28Fu4f1lqcKykJyRjAhs,15507
-floydnet-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-floydnet-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-floydnet-0.1.0.dist-info/RECORD,,