mlx-cluster 0.0.6__cp310-cp310-macosx_14_0_universal2.whl

mlx_cluster/__init__.py

@@ -0,0 +1,5 @@
+import mlx.core as mx
+
+from ._ext import random_walk
+from ._ext import rejection_sampling
+from ._ext import neighbor_sample

mlx_cluster-0.0.6.dist-info/METADATA

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: mlx_cluster
+Version: 0.0.6
+Summary: C++ extension for generating random graphs
+Author-email: Vinay Pandya <vinayharshadpandya27@gmail.com>
+Project-URL: Homepage, https://github.com/vinayhpandya/mlx_cluster
+Project-URL: Issues, https://github.com/vinayhpandya/mlx_cluster/Issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Provides-Extra: docs
+Requires-Dist: mlx>=0.27.1; extra == "docs"
+Requires-Dist: mlx-graphs>=0.0.8; extra == "docs"
+Requires-Dist: ipython==8.21.0; extra == "docs"
+Requires-Dist: sphinx>=7.2.6; extra == "docs"
+Requires-Dist: sphinx-book-theme==1.1.0; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints==1.25.2; extra == "docs"
+Requires-Dist: nbsphinx==0.9.3; extra == "docs"
+Requires-Dist: sphinx-gallery==0.15.0; extra == "docs"
+Provides-Extra: test
+Requires-Dist: mlx-graphs>=0.0.8; extra == "test"
+Requires-Dist: torch>=2.2.0; extra == "test"
+Requires-Dist: mlx>=0.26.0; extra == "test"
+Requires-Dist: pytest==7.4.4; extra == "test"
+Requires-Dist: scipy>=1.13.0; extra == "test"
+Requires-Dist: requests==2.31.0; extra == "test"
+Requires-Dist: fsspec[http]==2024.2.0; extra == "test"
+Requires-Dist: tqdm==4.66.1; extra == "test"
+Dynamic: license-file
+Dynamic: requires-python
+
+# MLX-Cluster
+
+High-performance graph algorithms optimized for Apple's MLX framework, featuring random walks, biased random walks, and neighbor sampling.
+
+[![PyPI version](https://img.shields.io/pypi/v/mlx-cluster)](https://pypi.org/project/mlx-cluster/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+**[Documentation](https://vinayhpandya.github.io/mlx_cluster/)** | **[Quickstart](https://vinayhpandya.github.io/mlx_cluster/quickstart.html)** |
+
+## 🚀 Features
+
+- **🔥 MLX Optimized**: Built specifically for Apple's MLX framework with GPU acceleration
+- **⚡ High Performance**: Optimized C++ implementations with Metal shaders for Apple Silicon
+- **🎯 Graph Algorithms**: 
+  - Uniform random walks
+  - Biased random walks (Node2Vec style with p/q parameters)
+  - Multi-hop neighbor sampling (GraphSAGE style)
+
+## 📦 Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install mlx-cluster
+```
+
+### From Source
+
+```bash
+git clone https://github.com/vinayhpandya/mlx_cluster.git
+cd mlx_cluster
+pip install -e .
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/vinayhpandya/mlx_cluster.git
+cd mlx_cluster
+pip install -e . --verbose
+```
+
+### Dependencies
+
+Required:
+- Python 3.8+
+- MLX framework
+- NumPy
+
+Optional (for examples and testing):
+- MLX-Graphs
+- PyTorch (for dataset utilities)
+- pytest
+
+## 🔧 Quick Start
+
+### Random Walks
+
+```python
+import mlx.core as mx
+import numpy as np
+from mlx_cluster import random_walk
+from mlx_graphs.datasets import PlanetoidDataset
+from mlx_graphs.utils.sorting import sort_edge_index
+
+# Load dataset
+cora = PlanetoidDataset(name="cora")
+edge_index = cora.graphs[0].edge_index.astype(mx.int64)
+
+# Convert to CSR format
+sorted_edge_index = sort_edge_index(edge_index=edge_index)
+row = sorted_edge_index[0][0]
+col = sorted_edge_index[0][1]
+_, counts = np.unique(np.array(row, copy=False), return_counts=True)
+row_ptr = mx.concatenate([mx.array([0]), mx.array(counts.cumsum())])
+
+# Generate random walks
+num_walks = 1000
+walk_length = 10
+start_nodes = mx.array(np.random.randint(0, cora.graphs[0].num_nodes, num_walks))
+rand_values = mx.random.uniform(shape=[num_walks, walk_length])
+
+mx.eval(rowptr,col, start_nodes, rand_values)
+# Perform walks
+node_sequences, edge_sequences = random_walk(
+    row_ptr, col, start_nodes, rand_values, walk_length, stream=mx.gpu
+)
+
+print(f"Generated {num_walks} walks of length {walk_length + 1}")
+print(f"Shape: {node_sequences.shape}")
+```
+
+### Biased Random Walks (Node2Vec)
+
+```python
+from mlx_cluster import rejection_sampling
+
+# Biased random walks with p/q parameters
+node_sequences, edge_sequences = rejection_sampling(
+    row_ptr, col, start_nodes, walk_length,
+    p=1.0,  # Return parameter
+    q=2.0,  # In-out parameter
+    stream=mx.gpu
+)
+```
+
+### Neighbor Sampling
+
+```python
+from mlx_cluster import neighbor_sample
+
+# Convert to CSC format (required for neighbor sampling)
+def create_csc_format(edge_index, num_nodes):
+    sources, targets = edge_index[0].tolist(), edge_index[1].tolist()
+    edges = sorted(zip(sources, targets), key=lambda x: x[1])
+    
+    colptr = np.zeros(num_nodes + 1, dtype=np.int64)
+    for _, target in edges:
+        colptr[target + 1] += 1
+    colptr = np.cumsum(colptr)
+    
+    sorted_sources = [source for source, _ in edges]
+    return mx.array(colptr), mx.array(sorted_sources, dtype=mx.int64)
+
+colptr, row = create_csc_format(edge_index, cora.graphs[0].num_nodes)
+
+# Multi-hop neighbor sampling
+input_nodes = mx.array([0, 1, 2], dtype=mx.int64)
+num_neighbors = [10, 5]  # 10 neighbors in first hop, 5 in second
+mx.eval(colptr, row, input_nodes)
+samples, rows, cols, edges = neighbor_sample(
+    colptr, row, input_nodes, num_neighbors,
+    replace=True, directed=True
+)
+
+print(f"Sampled {len(samples)} nodes and {len(edges)} edges")
+```
+
+## 📚 Documentation
+
+For comprehensive documentation, examples, and API reference, visit:
+[Documentation]()
+
+## 🧪 Testing
+
+Run the test suite:
+
+```bash
+# Install test dependencies
+pip install pytest mlx-graphs torch
+
+# Run tests
+pytest -s -v
+```
+
+## ⚡ Performance
+
+MLX-Cluster is optimized for Apple Silicon and shows significant speedups:
+
+- **Apple M1/M2/M3**: 2-5x faster than CPU-only implementations
+- **GPU Acceleration**: Automatic optimization for Metal Performance Shaders
+- **Memory Efficient**: Optimized sparse graph representations
+- **Batch Processing**: Efficient handling of thousands of concurrent walks
+
+## 🤝 Contributing
+
+We welcome contributions!
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/new-feature`)
+3. Commit your changes (`git commit -m 'Add new algorithm'`)
+4. Push to the branch (`git push origin feature/new-feature`)
+5. Open a Pull Request
+For installation and test intructions please visit the documentation
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- [PyTorch Cluster](https://github.com/rusty1s/pytorch_cluster) for everything
+- [MLX](https://github.com/ml-explore/mlx) for the foundational framework
+- [MLX-Graphs](https://github.com/mlx-graphs/mlx-graphs) for graph utilities and datasets
+
+## 📊 Citation
+
+If you use MLX-Cluster in your research, please cite:
+
+```bibtex
+@software{mlx_cluster,
+  author = {Vinay Pandya},
+  title = {MLX-Cluster: High-Performance Graph Algorithms for Apple MLX},
+  url = {https://github.com/vinayhpandya/mlx_cluster},
+  version = {0.0.6},
+  year = {2025}
+}
+```
+
+## 🔗 Related Projects
+
+- [MLX](https://github.com/ml-explore/mlx) - Apple's machine learning framework
+- [MLX-Graphs](https://github.com/mlx-graphs/mlx-graphs) - Graph neural networks for MLX
+- [PyTorch Geometric](https://github.com/pyg-team/pytorch_geometric) - Graph deep learning library
+
+---

mlx_cluster-0.0.6.dist-info/RECORD

@@ -0,0 +1,9 @@
+mlx_cluster/__init__.py,sha256=0OCVEloeEo3Y9a-RlrSH7-C18IOTMDFS1-TjUMEYlSw,124
+mlx_cluster/_ext.cpython-310-darwin.so,sha256=VDCXTlyjz445WJg7wr8sSflnynWYeKDHTatSBT9i8iI,148616
+mlx_cluster/libmlx_cluster.dylib,sha256=aOIkBNXNZzQek1Rv9o_qsaarL77LNiDoeN9hazH7de8,86248
+mlx_cluster/mlx_cluster.metallib,sha256=LdYPYY3iNcwYXpRY-yX_ANOMbDPx04iMx4QJaCFTanA,5416
+mlx_cluster-0.0.6.dist-info/licenses/LICENSE,sha256=7ixsoVuroKzGl84-ZV90CDH6bQrQF2UXvgnTqtW4Zb4,1069
+mlx_cluster-0.0.6.dist-info/METADATA,sha256=-8iqo7hi_d_sug1sGTbjfeFzA0noYLrN1r3OuaMGD1Y,7451
+mlx_cluster-0.0.6.dist-info/WHEEL,sha256=T2p57lol9__xkoU6aJTyN1Pm43ZpRU3q6km7mIbrAMs,114
+mlx_cluster-0.0.6.dist-info/top_level.txt,sha256=sERi0kZuQnKmsHnqOkAda1kkBXdQAwV25Y9L-ATj110,12
+mlx_cluster-0.0.6.dist-info/RECORD,,

mlx_cluster-0.0.6.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: false
+Tag: cp310-cp310-macosx_14_0_universal2
+

mlx_cluster-0.0.6.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 vinayhpandya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mlx_cluster-0.0.6.dist-info/top_level.txt

@@ -0,0 +1 @@
+mlx_cluster