{"id":48197601,"url":"https://github.com/synapticore-io/torch-relativistic","last_synced_at":"2026-04-04T18:16:37.771Z","repository":{"id":293418619,"uuid":"983491776","full_name":"synapticore-io/torch-relativistic","owner":"synapticore-io","description":"A PyTorch extension that implements neural network components inspired by relativistic physics, particularly the Terrell-Penrose effect.","archived":false,"fork":false,"pushed_at":"2026-03-24T14:15:34.000Z","size":403,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-25T18:25:14.923Z","etag":null,"topics":["neural-networks","physics","python","pytorch","relativity"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/synapticore-io.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-05-14T13:10:58.000Z","updated_at":"2026-03-24T14:15:53.000Z","dependencies_parsed_at":"2025-05-15T08:52:16.454Z","dependency_job_id":null,"html_url":"https://github.com/synapticore-io/torch-relativistic","commit_stats":null,"previous_names":["bjoernbethge/torch-relativistic","synapticore-io/torch-relativistic"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/synapticore-io/torch-relativistic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synapticore-io%2Ftorch-relativistic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synapticore-io%2Ftorch-relativistic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synapticore-io%2Ftorch-relativistic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synapticore-io%2Ftorch-relativistic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/synapticore-io","download_url":"https://codeload.github.com/synapticore-io/torch-relativistic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synapticore-io%2Ftorch-relativistic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31407915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: 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":["neural-networks","physics","python","pytorch","relativity"],"created_at":"2026-04-04T18:16:34.834Z","updated_at":"2026-04-04T18:16:37.739Z","avatar_url":"https://github.com/synapticore-io.png","language":"Python","funding_links":["https://ko-fi.com/N4N71WOHZ3"],"categories":[],"sub_categories":[],"readme":"# 🌌 torch-relativistic\r\n\r\n[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/N4N71WOHZ3)\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\r\n\u003c!-- Badges --\u003e\r\n[![PyPI version](https://badge.fury.io/py/torch-relativistic.svg)](https://badge.fury.io/py/torch-relativistic)\r\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\r\n[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-red.svg)](https://pytorch.org/)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n[![Tests](https://github.com/bjoernbethge/torch-relativistic/actions/workflows/tests.yml/badge.svg)](https://github.com/bjoernbethge/torch-relativistic/actions/workflows/tests.yml)\r\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\r\n\r\n\u003c!-- Logo/Header --\u003e\r\n\u003ch3\u003e🚀 A PyTorch extension implementing neural networks inspired by relativistic physics\u003c/h3\u003e\r\n\r\n*Harness the power of the Terrell-Penrose effect for novel information processing paradigms* ⚡\r\n\r\n\u003c/div\u003e\r\n\r\n---\r\n\r\n## 🌟 Overview\r\n\r\n**torch-relativistic** provides neural network modules that incorporate concepts from **special relativity** into\r\nmachine learning. The key insight is that the **Terrell-Penrose effect**, where rapidly moving objects appear rotated\r\nrather than contracted, can inspire revolutionary information processing paradigms in neural networks.\r\n\r\n### 🎯 Key Features\r\n\r\n- 🧠 **Relativistic Graph Neural Networks (GNNs)** - Process graphs with relativistic information propagation\r\n- ⚡ **Relativistic Spiking Neural Networks (SNNs)** - Time dilation effects in spiking neurons\r\n- 🎭 **Relativistic Attention Mechanisms** - Multi-reference frame attention heads\r\n- 🌀 **Relativistic Transformations** - Lorentz boosts and Terrell-Penrose transforms\r\n- 🔬 **Physics-Inspired Architecture** - Grounded in real relativistic physics\r\n\r\n---\r\n\r\n## 📦 Installation\r\n\r\n### Quick Install\r\n\r\n```bash\r\npip install torch-relativistic\r\n```\r\n\r\n### Development Install\r\n\r\n```bash\r\ngit clone https://github.com/yourusername/torch-relativistic.git\r\ncd torch-relativistic\r\npip install -e .\r\n```\r\n\r\n### Requirements\r\n\r\n- 🐍 Python ≥ 3.11\r\n- 🔥 PyTorch ≥ 2.0.0\r\n- 📊 PyTorch Geometric ≥ 2.6.1\r\n- 🔢 NumPy ≥ 1.20.0\r\n\r\n---\r\n\r\n## 🚀 Quick Start\r\n\r\n```python\r\nimport torch\r\nfrom torch_relativistic import RelativisticGraphConv\r\n\r\n# Create a relativistic GNN layer\r\nconv = RelativisticGraphConv(16, 32, max_relative_velocity=0.8)\r\nx = torch.randn(10, 16)\r\nedge_index = torch.tensor([[0, 1, 2], [1, 2, 0]], dtype=torch.long)\r\n\r\n# Process with relativistic effects\r\noutput = conv(x, edge_index)  # Shape: [10, 32]\r\n```\r\n\r\n---\r\n\r\n## 📚 Components\r\n\r\n### 🌐 Relativistic Graph Neural Networks\r\n\r\nGNN modules that process information as if affected by relativistic phenomena:\r\n\r\n```python\r\nimport torch\r\nfrom torch_relativistic.gnn import RelativisticGraphConv, MultiObserverGNN\r\n\r\n# Create a simple graph\r\nnum_nodes = 10\r\nfeature_dim = 16\r\nedge_index = torch.tensor([[0, 1, 1, 2, 2, 3, 3, 4, 4, 0],\r\n                           [1, 0, 2, 1, 3, 2, 4, 3, 0, 4]], dtype=torch.long)\r\nnode_features = torch.randn(num_nodes, feature_dim)\r\n\r\n# Create a relativistic GNN layer\r\nconv = RelativisticGraphConv(\r\n    in_channels=feature_dim,\r\n    out_channels=32,\r\n    max_relative_velocity=0.8\r\n)\r\n\r\n# Process the graph\r\noutput_features = conv(node_features, edge_index)\r\nprint(f\"Output shape: {output_features.shape}\")  # [10, 32]\r\n\r\n# Multi-observer GNN processes the graph from multiple relativistic perspectives\r\nmulti_observer_gnn = MultiObserverGNN(\r\n    feature_dim=feature_dim,\r\n    hidden_dim=32,\r\n    output_dim=8,\r\n    num_observers=4\r\n)\r\n\r\noutput = multi_observer_gnn(node_features, edge_index)\r\nprint(f\"Multi-observer output shape: {output.shape}\")  # [10, 8]\r\n```\r\n\r\n### ⚡ Relativistic Spiking Neural Networks\r\n\r\nSNN components that incorporate relativistic time dilation:\r\n\r\n```python\r\nimport torch\r\nfrom torch_relativistic.snn import RelativisticLIFNeuron, TerrellPenroseSNN\r\n\r\n# Create input spikes (batch_size=32, input_size=10)\r\ninput_spikes = torch.bernoulli(torch.ones(32, 10) * 0.3)\r\n\r\n# Create a relativistic LIF neuron\r\nneuron = RelativisticLIFNeuron(\r\n    input_size=10,\r\n    threshold=1.0,\r\n    beta=0.9\r\n)\r\n\r\n# Initialize neuron state\r\ninitial_state = neuron.init_state(batch_size=32)\r\n\r\n# Process input spikes\r\noutput_spikes, new_state = neuron(input_spikes, initial_state)\r\nprint(f\"Output spikes shape: {output_spikes.shape}\")  # [32]\r\n\r\n# Create a complete SNN\r\nsnn = TerrellPenroseSNN(\r\n    input_size=10,\r\n    hidden_size=20,\r\n    output_size=5,\r\n    simulation_steps=100\r\n)\r\n\r\n# Process input\r\noutput = snn(input_spikes)\r\nprint(f\"SNN output shape: {output.shape}\")  # [32, 5]\r\n\r\n# Get spike history for visualization\r\nspike_history = snn.get_spike_history(input_spikes)\r\nprint(f\"Hidden spike history shape: {spike_history['hidden_spikes'].shape}\")  # [32, 100, 20]\r\n```\r\n\r\n### 🎭 Relativistic Attention Mechanism\r\n\r\nAttention where different heads operate in different reference frames:\r\n\r\n```python\r\nimport torch\r\nfrom torch_relativistic.attention import RelativisticSelfAttention\r\n\r\n# Create input sequence (batch_size=16, seq_len=24, feature_dim=64)\r\nseq = torch.randn(16, 24, 64)\r\n\r\n# Create relativistic self-attention module\r\nattention = RelativisticSelfAttention(\r\n    hidden_dim=64,\r\n    num_heads=8,\r\n    dropout=0.1,\r\n    max_velocity=0.9\r\n)\r\n\r\n# Optional: Create positions for spacetime distances\r\npositions = torch.randn(16, 24, 3)  # 3D positions for each token\r\n\r\n# Process sequence\r\noutput = attention(seq, positions=positions)\r\nprint(f\"Output shape: {output.shape}\")  # [16, 24, 64]\r\n```\r\n\r\n### 🌀 Relativistic Transformations\r\n\r\nApply transformations inspired by special relativity to feature vectors:\r\n\r\n```python\r\nimport torch\r\nfrom torch_relativistic.transforms import TerrellPenroseTransform, LorentzBoost\r\n\r\n# Create feature vectors (batch_size=8, feature_dim=64)\r\nfeatures = torch.randn(8, 64)\r\n\r\n# Apply Terrell-Penrose inspired transformation\r\ntransform = TerrellPenroseTransform(\r\n    feature_dim=64,\r\n    max_velocity=0.9,\r\n    mode=\"rotation\"\r\n)\r\n\r\ntransformed = transform(features)\r\nprint(f\"Transformed shape: {transformed.shape}\")  # [8, 64]\r\n\r\n# For spacetime features (batch_size=8, feature_dim=8 including 4D spacetime)\r\nspacetime_features = torch.randn(8, 8)\r\n\r\n# Apply Lorentz boost\r\nboost = LorentzBoost(\r\n    feature_dim=8,\r\n    time_dim=0,  # First dimension is time\r\n    max_velocity=0.8\r\n)\r\n\r\nboosted = boost(spacetime_features)\r\nprint(f\"Boosted shape: {boosted.shape}\")  # [8, 8]\r\n```\r\n\r\n---\r\n\r\n## 🧪 Development\r\n\r\n### Running Tests\r\n\r\n```bash\r\n# Install development dependencies\r\npip install -e \".[dev]\"\r\n\r\n# Run tests\r\npytest tests/ -v\r\n\r\n# Run with coverage\r\npytest tests/ --cov=torch_relativistic\r\n```\r\n\r\n### Code Quality\r\n\r\n```bash\r\n# Format code\r\nblack src/ tests/\r\n\r\n# Check linting\r\nruff check src/ tests/\r\n\r\n# Type checking\r\nmypy src/\r\n```\r\n\r\n---\r\n\r\n## 🤝 Contributing\r\n\r\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\r\n\r\n### 🛠️ Development Setup\r\n\r\n1. **Fork** the repository\r\n2. **Clone** your fork: `git clone https://github.com/yourusername/torch-relativistic.git`\r\n3. **Install** in development mode: `pip install -e \".[dev]\"`\r\n4. **Create** a feature branch: `git checkout -b feature/amazing-feature`\r\n5. **Make** your changes and add tests\r\n6. **Run** tests: `pytest tests/`\r\n7. **Submit** a pull request\r\n\r\n---\r\n\r\n## 📄 License\r\n\r\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\r\n\r\n---\r\n\r\n## 🙏 Acknowledgments\r\n\r\n- 🌌 Inspired by Einstein's **Special Theory of Relativity**\r\n- 🔬 Built on the **Terrell-Penrose effect** from relativistic physics\r\n- 🔥 Powered by **PyTorch** and **PyTorch Geometric**\r\n- ⚡ Thanks to the open-source ML community\r\n\r\n---\r\n\r\n## 📞 Contact \u0026 Links\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\r\n[![GitHub](https://img.shields.io/badge/GitHub-100000?style=for-the-badge\u0026logo=github\u0026logoColor=white)](https://github.com/yourusername/torch-relativistic)\r\n[![PyPI](https://img.shields.io/badge/PyPI-3775A9?style=for-the-badge\u0026logo=pypi\u0026logoColor=white)](https://pypi.org/project/torch-relativistic/)\r\n[![Documentation](https://img.shields.io/badge/Docs-4285F4?style=for-the-badge\u0026logo=read-the-docs\u0026logoColor=white)](https://torch-relativistic.readthedocs.io/)\r\n[![Email](https://img.shields.io/badge/Email-D14836?style=for-the-badge\u0026logo=gmail\u0026logoColor=white)](mailto:bjoern.bethge@gmail.com)\r\n\r\n**Made with ❤️ and ⚛️ physics**\r\n\r\n\u003c/div\u003e\r\n\r\n---\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\u003csub\u003eBuilt with 🔥 PyTorch • Inspired by 🌌 Einstein • Powered by ⚛️ Physics\u003c/sub\u003e\r\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsynapticore-io%2Ftorch-relativistic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsynapticore-io%2Ftorch-relativistic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsynapticore-io%2Ftorch-relativistic/lists"}