{"id":37313585,"url":"https://github.com/sandyherho/manuk-kepudang","last_synced_at":"2026-01-20T17:00:15.396Z","repository":{"id":326303181,"uuid":"1105820721","full_name":"sandyherho/manuk-kepudang","owner":"sandyherho","description":"Python library for simulating collective motion using the 3D Vicsek model, featuring Numba JIT acceleration and  spatial entropy metrics.","archived":false,"fork":false,"pushed_at":"2025-12-18T21:55:59.000Z","size":53,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-21T21:49:05.788Z","etag":null,"topics":["collective-behavior","flocking-simulation","vicsek-3d"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/manuk-kepudang/","language":"Python","has_issues":false,"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/sandyherho.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-11-28T07:54:39.000Z","updated_at":"2025-12-18T21:48:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sandyherho/manuk-kepudang","commit_stats":null,"previous_names":["sandyherho/manuk-kepudang"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/sandyherho/manuk-kepudang","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandyherho%2Fmanuk-kepudang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandyherho%2Fmanuk-kepudang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandyherho%2Fmanuk-kepudang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandyherho%2Fmanuk-kepudang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sandyherho","download_url":"https://codeload.github.com/sandyherho/manuk-kepudang/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandyherho%2Fmanuk-kepudang/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28607624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"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":["collective-behavior","flocking-simulation","vicsek-3d"],"created_at":"2026-01-16T03:05:26.762Z","updated_at":"2026-01-20T17:00:15.390Z","avatar_url":"https://github.com/sandyherho.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `manuk-kepudang`: A Python Library for 3D Vicsek Model Simulation\n\n[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)\n[![PyPI version](https://img.shields.io/pypi/v/manuk-kepudang.svg)](https://pypi.org/project/manuk-kepudang/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![DOI](https://zenodo.org/badge/1105820721.svg)](https://doi.org/10.5281/zenodo.17747396)\n\n[![NumPy](https://img.shields.io/badge/NumPy-%23013243.svg?logo=numpy\u0026logoColor=white)](https://numpy.org/)\n[![SciPy](https://img.shields.io/badge/SciPy-%230C55A5.svg?logo=scipy\u0026logoColor=white)](https://scipy.org/)\n[![Matplotlib](https://img.shields.io/badge/Matplotlib-%23ffffff.svg?logo=Matplotlib\u0026logoColor=black)](https://matplotlib.org/)\n[![Pandas](https://img.shields.io/badge/pandas-%23150458.svg?logo=pandas\u0026logoColor=white)](https://pandas.pydata.org/)\n[![netCDF4](https://img.shields.io/badge/netCDF4-%23004B87.svg)](https://unidata.github.io/netcdf4-python/)\n[![Numba](https://img.shields.io/badge/Numba-%2300A3E0.svg?logo=numba\u0026logoColor=white)](https://numba.pydata.org/)\n[![Pillow](https://img.shields.io/badge/Pillow-%23000000.svg)](https://python-pillow.org/)\n[![tqdm](https://img.shields.io/badge/tqdm-%23FFC107.svg)](https://tqdm.github.io/)\n\nA Python library for simulating collective motion using the 3D Vicsek model with Numba JIT acceleration and spatial entropy metrics.\n\n## Model\n\nThe Vicsek model (1995) describes self-propelled particles exhibiting collective motion through simple alignment rules. In 3D, each particle $i$ updates its velocity according to:\n\n$$\\mathbf{v}_i(t + \\Delta t) = v_0 \\cdot \\hat{\\mathbf{u}}\\left( \\langle \\hat{\\mathbf{v}}_j \\rangle_{|r_{ij}| \u003c r} + \\eta \\boldsymbol{\\xi}_i \\right)$$\n\nwhere:\n- $v_0$ is the constant speed of all particles\n- $\\langle \\hat{\\mathbf{v}}_j \\rangle$ is the **normalized** average velocity of neighbors within radius $r$\n- $\\eta$ is the noise amplitude\n- $\\boldsymbol{\\xi}_i$ is a random unit vector\n- $\\hat{\\mathbf{u}}(\\cdot)$ denotes normalization to unit vector\n\nPosition updates follow:\n\n$$\\mathbf{r}_i(t + \\Delta t) = \\mathbf{r}_i(t) + \\mathbf{v}_i(t + \\Delta t) \\cdot \\Delta t$$\n\nwith periodic boundary conditions in a cubic box of side $L$.\n\n### Key Parameters\n\n| Parameter | Symbol | Description | Typical Range |\n|:---------:|:------:|:------------|:-------------:|\n| N | $N$ | Number of particles | 50-5000 |\n| L | $L$ | Box size | 5-50 |\n| v0 | $v_0$ | Particle speed | 0.1-1.0 |\n| r | $r$ | Interaction radius | 1.0-5.0 |\n| eta | $\\eta$ | Noise magnitude | 0.0-2.0 |\n| dt | $\\Delta t$ | Time step | 0.1-1.0 |\n\n### Order Parameter\n\nThe collective alignment is quantified by the order parameter:\n\n$$\\phi = \\frac{1}{N v_0} \\left| \\sum_{i=1}^{N} \\mathbf{v}_i \\right|$$\n\nwhere $\\phi \\approx 0$ indicates disordered motion and $\\phi \\approx 1$ indicates collective alignment.\n\n## Spatial Entropy Metrics\n\nThis library includes rigorous information-theoretic measures to quantify spatial order/disorder:\n\n| Metric | Description | High Value | Low Value |\n|:------:|:------------|:-----------|:----------|\n| Positional Entropy | Shannon entropy of spatial distribution | Uniform (disordered) | Clustered (ordered) |\n| Orientational Entropy | Entropy of velocity directions on unit sphere | Isotropic (disordered) | Aligned (ordered) |\n| Local Alignment Entropy | Heterogeneity of local order | Heterogeneous | Homogeneous |\n| Pair Correlation Entropy | From radial distribution function g(r) | Ideal gas | Crystalline |\n| Voronoi Cell Entropy | Geometric packing disorder | Irregular | Regular |\n| Position-Velocity MI | Mutual information coupling | Spatial structure | Homogeneous |\n| **Spatial Complexity Index** | Weighted composite measure | Disordered | Ordered |\n\n*SCI = (H_positional + H_orientational + H_local_align + H_pair + H_voronoi + (1-MI)) / 6\n\n## Installation\n\n**From PyPI:**\n```bash\npip install manuk-kepudang\n```\n\n**From source:**\n```bash\ngit clone https://github.com/sandyherho/manuk-kepudang.git\ncd manuk-kepudang\npip install .\n```\n\n**Development installation with Poetry:**\n```bash\ngit clone https://github.com/sandyherho/manuk-kepudang.git\ncd manuk-kepudang\npoetry install\n```\n\n## Quick Start\n\n**CLI:**\n```bash\nmanuk-kepudang case1          # Run ordered phase scenario\nmanuk-kepudang case2          # Run disordered phase scenario\nmanuk-kepudang --all          # Run all test cases\nmanuk-kepudang case1 --no-entropy  # Skip entropy computation\n```\n\n**Python API:**\n```python\nfrom manuk_kepudang import VicsekSystem, VicsekSolver\nfrom manuk_kepudang import compute_metrics_timeseries\n\n# Create system with 200 particles\nsystem = VicsekSystem(\n    n_particles=200,\n    box_size=10.0,\n    speed=0.5,\n    interaction_radius=2.0,\n    noise=0.3\n)\n\n# Initialize solver with Numba acceleration\nsolver = VicsekSolver(dt=1.0, use_numba=True)\n\n# Run simulation for 500 steps\nresult = solver.solve(system, n_steps=500)\n\n# Compute entropy metrics\nmetrics = compute_metrics_timeseries(\n    result['positions'],\n    result['velocities'],\n    result['time'],\n    system.box_size,\n    system.speed,\n    system.interaction_radius\n)\n\nprint(f\"Final order parameter: {result['final_order_parameter']:.4f}\")\nprint(f\"Final SCI (disorder): {metrics['spatial_complexity_index_final']:.4f}\")\n```\n\n## Features\n\n- **High-performance**: Numba JIT compilation for 10-100x speedup\n- **3D simulation**: Full three-dimensional particle dynamics\n- **Periodic boundaries**: Correct handling of boundary conditions\n- **Order parameter tracking**: Real-time collective alignment measurement\n- **Spatial entropy metrics**: Rigorous information-theoretic disorder measures\n- **Multiple output formats**: CSV, NetCDF (CF-compliant), PNG, GIF\n- **Configurable scenarios**: Text-based configuration files\n\n## Output Files\n\nThe library generates:\n\n- **CSV files**: \n  - `*_order_parameter.csv` - Order parameter time series\n  - `*_entropy_timeseries.csv` - All entropy measures over time\n  - `*_entropy_summary.csv` - Statistics (mean, std, min, max, final)\n  - `*_final_state.csv` - Final particle positions and velocities\n- **NetCDF**: Full trajectory data with all metrics and CF-compliant metadata\n  - Variables: `x`, `y`, `z`, `vx`, `vy`, `vz`, `order_parameter`, all entropy metrics\n- **PNG**: Static summary plots with entropy visualization\n- **GIF**: Animated 3D visualization with camera rotation\n\n## Test Cases\n\n| Case | Description | N | η |\n|:----:|:------------|:-:|:-:|\n| 1 | Ordered phase | 200 | 0.3 |\n| 2 | Disordered phase | 200 | 2.0 |\n| 3 | Large system | 500 | 0.5 |\n| 4 | Phase transition | 300 | 1.0 |\n\n## Dependencies\n\n- **numpy** \u003e= 1.20.0\n- **scipy** \u003e= 1.7.0\n- **matplotlib** \u003e= 3.3.0\n- **pandas** \u003e= 1.3.0\n- **netCDF4** \u003e= 1.5.0\n- **numba** \u003e= 0.53.0\n- **Pillow** \u003e= 8.0.0\n- **tqdm** \u003e= 4.60.0\n\n## License\n\nMIT © Sandy H. S. Herho, Gandhi Napitupulu, Iwan P. Anwar, Nurjanna J. Trilaksono, Rusmawan Suwarman, Dasapta E. Irawan\n\n## Citation\n\n```bibtex\n@software{herho2025_manuk_kepudang,\n  title   = {manuk-kepudang: A Python library for 3D Vicsek model simulation},\n  author  = {Herho, Sandy H. S. and Napitupulu, G. and Anwar, Iwan P. and Trilaksono, Nurjanna J. and Suwarman, Rusmawan and Irawan, Dasapta E.},\n  year    = {2025},\n  url     = {https://github.com/sandyherho/manuk-kepudang}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandyherho%2Fmanuk-kepudang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsandyherho%2Fmanuk-kepudang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandyherho%2Fmanuk-kepudang/lists"}