{"id":19156395,"url":"https://github.com/kyegomez/swarmalators","last_synced_at":"2025-05-07T07:42:30.616Z","repository":{"id":202859914,"uuid":"708278718","full_name":"kyegomez/swarmalators","owner":"kyegomez","description":"Pytorch Implementation of the Swarmalators algorithm from \"Exotic swarming dynamics of high-dimensional swarmalators\"","archived":false,"fork":false,"pushed_at":"2024-11-11T09:18:42.000Z","size":2269,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-19T20:17:04.429Z","etag":null,"topics":["artificial-intelligence","attention-is-all-you-need","attention-mechanism","machine-learning-algorithms","multimodal","multimodality","swarm-cluster","swarm-intelligence","swarm-robotics","swarms"],"latest_commit_sha":null,"homepage":"https://discord.gg/GYbXvDGevY","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/kyegomez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["kyegomez"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2023-10-22T04:12:06.000Z","updated_at":"2025-02-13T15:25:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"7b7856d5-a0ba-43c7-a355-b0a4b3b69c76","html_url":"https://github.com/kyegomez/swarmalators","commit_stats":{"total_commits":6,"total_committers":2,"mean_commits":3.0,"dds":"0.16666666666666663","last_synced_commit":"f17c13d2b10dc808e3144dd439340d40e2870b43"},"previous_names":["kyegomez/swarmalators"],"tags_count":0,"template":false,"template_full_name":"kyegomez/Python-Package-Template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kyegomez%2Fswarmalators","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kyegomez%2Fswarmalators/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kyegomez%2Fswarmalators/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kyegomez%2Fswarmalators/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kyegomez","download_url":"https://codeload.github.com/kyegomez/swarmalators/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252836754,"owners_count":21811772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["artificial-intelligence","attention-is-all-you-need","attention-mechanism","machine-learning-algorithms","multimodal","multimodality","swarm-cluster","swarm-intelligence","swarm-robotics","swarms"],"created_at":"2024-11-09T08:34:19.721Z","updated_at":"2025-05-07T07:42:30.591Z","avatar_url":"https://github.com/kyegomez.png","language":"Python","funding_links":["https://github.com/sponsors/kyegomez"],"categories":[],"sub_categories":[],"readme":"![Agora banner](agorabanner.png)\n\n\n# Swarmalator \n\nSwarmalators are a hybrid swarm oscillator system, combining features of both swarming (particles that align their spatial motion) and oscillators (units that synchronize their phase). This repository provides an implementation of the swarmalator model in a 3D environment using PyTorch.\n\n\n# Install\n`pip install swarmalator`\n\n# Usage\nThere are 2 verisons, a verison close to the original paper's implementation and a very experimental verison with attn.\n\n- Implementation From paper, with a cool animation\n\n```python\nimport matplotlib.pyplot as plt\nfrom matplotlib.animation import FuncAnimation\nfrom swarmalator import simulate_swarmalators\n\n# Example usage:\nN = 100\nJ, alpha, beta, gamma, epsilon_a, epsilon_r, R = [0.1] * 7\nD = 3  # Ensure D is an integer\nxi, sigma_i = simulate_swarmalators(\n    N, J, alpha, beta, gamma, epsilon_a, epsilon_r, R, D\n)\nprint(xi[-1], sigma_i[-1])\n\n\ndef visualize_swarmalators(results_xi):\n    fig = plt.figure(figsize=(8, 8))\n    ax = fig.add_subplot(111, projection=\"3d\")\n\n    ax.set_xlim(-2, 2)\n    ax.set_ylim(-2, 2)\n    ax.set_zlim(-2, 2)\n\n    # Initialize the scatter plot\n    scatter = ax.scatter([], [], [])\n\n    def init():\n        scatter._offsets3d = ([], [], [])\n        return (scatter,)\n\n    def update(num):\n        ax.view_init(30, 0.3 * num)\n        x_data, y_data, z_data = results_xi[num].t()\n        scatter._offsets3d = (x_data, y_data, z_data)\n        return (scatter,)\n\n    ani = FuncAnimation(fig, update, frames=len(results_xi), init_func=init, blit=False)\n\n    plt.show()\n\n\n# Call the visualization function\nvisualize_swarmalators(xi)\n```\n\n- Implementation with attn, params could use tuning, with a visualization suite as well\n```python\nimport torch\nfrom swarmalator import Swarmulator\n\n\n# Initialize the Swarmulator\nN = 100  # Number of agents\nD = 100  # Dimensionality of agents\nswarm = Swarmulator(N=N, D=D, heads=5)\n\n# Run a simple forward pass\nswarm.simulation(num_steps=10)\n\n# Print the final positions and orientations of the swarm agents\nprint(\"Final positions (xi) of the agents:\")\nprint(swarm.xi)\nprint(\"\\nFinal orientations (oi) of the agents:\")\nprint(swarm.oi)\n```\n\n## Overview\n\nAt the heart of the model are two main components for each swarmalator: \n1. **Spatial Position (`xi`)**: Represents where the swarmalator is in a 3D space.\n2. **Phase/Orientation (`sigma_i`)**: Defines the state or phase of the swarmalator.\n\nThe dynamics of each swarmalator are driven by interactions with its neighbors. These interactions are based on their relative spatial distances and differences in their phases.\n\n## Dynamics Explained\n\nThe dynamics of the swarmalators are governed by two main equations:\n\n1. For the spatial position (`xi`):\n    - Swarmalators are attracted or repelled based on the difference in their phases.\n    - They also experience a self-propelling force and a damping on high velocities.\n  \n2. For the phase/orientation (`sigma_i`):\n    - The phase changes based on the relative spatial positioning of the swarmalators.\n    - There's also an intrinsic phase precession and a nonlinearity which can cause the phase to wrap around.\n\nUsing the Runge-Kutta 4th order method (RK4), the system numerically integrates these dynamics over time, leading to the emergent behaviors of the swarmalators.\n\n## Visualization\n\nIn the visualization, you will witness:\n- A 3D cube that encapsulates the world of swarmalators.\n- `N` points inside this 3D space, each representing a swarmalator. The movements and dynamics of these swarmalators are based on the aforementioned interactions.\n- A mesmerizing dance of points as they evolve over time, showcasing various patterns, clusters, or scattered behaviors.\n\n## Parameters\n\nThe behavior of swarmalators can be fine-tuned using several parameters:\n- `N`: Number of swarmalators.\n- `J, alpha, beta, gamma, epsilon_a, epsilon_r, R`: Parameters that govern the strength and nature of interactions and dynamics.\n- `D`: Dimensionality of the phase/orientation.\n\n## Usage\n\nTo simulate the swarmalators, adjust the parameters as desired and run the provided script. Post-simulation, the final positions and phases of the swarmalators are printed, and the visualization can be observed.\n\n```python\nN = 100\nJ, alpha, beta, gamma, epsilon_a, epsilon_r, R = [0.1]*7\nD = 3\nxi, sigma_i = simulate_swarmalators(N, J, alpha, beta, gamma, epsilon_a, epsilon_r, R, D)\nprint(xi[-1], sigma_i[-1])\n```\n\n## Conclusion\n\nSwarmalators provide a unique and intriguing insight into systems that exhibit both swarming and synchronization behaviors. By studying and visualizing such models, we can gain a better understanding of complex systems in nature and potentially apply these insights to engineering and technological domains.\n\n\n\n# Citation\n```bibtex\n@misc{2308.03803,\nAuthor = {Akash Yadav and Krishnanand J and V. K. Chandrasekar and Wei Zou and Jürgen Kurths and D. V. Senthilkumar},\nTitle = {Exotic swarming dynamics of high-dimensional swarmalators},\nYear = {2023},\nEprint = {arXiv:2308.03803},\n}\n\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkyegomez%2Fswarmalators","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkyegomez%2Fswarmalators","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkyegomez%2Fswarmalators/lists"}