Published April 5, 2026
| Version arXiv:2505.05246v4
Data paper
Restricted
Hamiltonian description of nonreciprocal interactions
Authors/Creators
- 1. Max Planck Institute for the Physics of Complex System
- 2. School of Physics, Nankai University
- 3. Max Planck Institute for the Physics of Complex Systems and Cluster of Excellence ctd.qmat
- 4. Max Planck Institute for the Physics of Complex Systems
-
5.
Center for Systems Biology Dresden
- 6. Cluster of Excellence Physics of Life, TU Dresden
- 7. Departament de F ́ısica de la Mat`eria Condensada, Universitat de Barcelona
- 8. Universitat de Barcelona Institute of Complex Systems (UBICS)
- 9. Instituci ́o Catalana de Recerca i Estudis Avan ̧cats (ICREA)
Contributors
Contact person:
Researcher (3):
- 1. Max Planck Institute for the Physics of Complex Systems
- 2. School of Physics, Nankai University
- 3. Max Planck Institute for the Physics of Complex Systems and Cluster of Excellence ctd.qmat
-
4.
Center for Systems Biology Dresden
- 5. Cluster of Excellence Physics of Life, TU Dresden
- 6. Departament de F ́ısica de la Mat`eria Condensada
- 7. Universitat de Barcelona Institute of Complex Systems (UBICS)
- 8. Instituci ́o Catalana de Recerca i Estudis Avan ̧cats (ICREA)
Description
Yu-Bo Shi, Roderich Moessner, Ricard Alert, Marin Bukov
Abstract
In many systems, including sedimenting particles and bird flocks, interactions do not derive from a potential and are generally non-reciprocal, meaning that they do not obey the action–reaction principle. As a result, one cannot define a conventional energy function or use analytical and numerical tools that rely on it. Here we address this limitation by constructing a Hamiltonian with auxiliary degrees of freedom that, under a constraint, generates the original non-reciprocal dynamics. We show that Monte Carlo simulations based on the constrained Hamiltonian reproduce both stationary and non-stationary states of the original Langevin dynamics, as we illustrate for dissipative XY spins with vision-cone interactions. The symplectic structure inherent to the construction also lets us apply established ideas from Hamiltonian engineering, which we demonstrate by varying the amplitude of a periodic (Floquet) drive to tune the spin interactions between square- and chain-lattice geometries. Overall, our construction paves the way towards extending statistical mechanics and Hamiltonian dynamics to non-reciprocal systems.
Technical info
# Zenodo Record README
## Hamiltonian description of nonreciprocal interactions
This Zenodo record contains the code, simulation data, manuscript source, and visual assets associated with the study on Hamiltonian embeddings for nonreciprocal interactions in XY-spin models. It is organized to help readers quickly identify the raw data, processed datasets, plotting scripts, manuscript files, and ready-to-use figures and video needed to reproduce the main results.
## Table of Contents
- [Record Summary](#record-summary)
- [Related Outputs And Persistent Links](#related-outputs-and-persistent-links)
- [Licensing](#licensing)
- [How To Cite](#how-to-cite)
- [What This Record Contains](#what-this-record-contains)
- [Data Formats](#data-formats)
- [Data Description](#data-description)
- [Software Environment](#software-environment)
- [Directories that Generate Visual Elements used in the Paper ](#directories-that-generate-visual-elements-used-in-the-paper)
- [Minimal Reproduction Workflow](#minimal-reproduction-workflow)
- [Additional Notes For Reproducibility](#additional-notes-for-reproducibility)
## Record Summary
- `src_code/` contains the simulation code, post-processing notebooks, and cluster job scripts.
- `data/` contains raw simulation outputs and processed plotting-ready datasets.
- `src_latex/` contains the manuscript source, bibliography snapshots (`.bbl`), and compiled PDFs for the main text, supplement, and combined version.
- `visual_elements/` contains the standalone figure/video generation scripts together with the exported main figures, supplementary figures, and archived video assets.
In practical terms, the workflow is:
```text
simulation scripts -> raw data in data/raw -> processed data in data/processed -> figures/videos -> manuscript
```
## Related Outputs And Persistent Links
- Paper title: *Hamiltonian description of nonreciprocal interactions*
- Authors: Yu-Bo Shi, Roderich Moessner, Ricard Alert, and Marin Bukov
- arXiv DOI: [10.48550/arXiv.2505.05246](https://doi.org/10.48550/arXiv.2505.05246)
- arXiv identifier: `arXiv:2505.05246`
- **Journal version**: [Nature Physics](https://doi.org/10.1038/s41567-026-03317-0)
## Licensing
- This repository uses component-specific licenses rather than a single license for the entire archive.
- Files in [`src_code/`](src_code/) are licensed under the BSD 3-Clause License; see [`LICENSE`](LICENSE).
- Files in [`data/`](data/) are licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0); see [`LICENSE-DATA`](LICENSE-DATA).
- No separate license file is currently provided in this snapshot for the manuscript materials in [`src_latex/`](src_latex/) or the presentation-ready assets in [`visual_elements/`](visual_elements/). Reuse of those materials should therefore not be assumed beyond applicable copyright law unless additional permission is provided by the authors.
- The software dependencies used in this archive are listed in [`requirements.txt`](requirements.txt) for the lightweight plotting/analysis workflow, while [`src_code/requirements.txt`](src_code/requirements.txt) preserves the fuller original source-environment export. Their own licenses are governed by their respective upstream projects.
## How To Cite
### Plain-text citation
Yu-Bo Shi, Roderich Moessner, Ricard Alert, and Marin Bukov, *Hamiltonian description of nonreciprocal interactions*, arXiv:2505.05246 (2025). DOI: 10.48550/arXiv.2505.05246
### BibTeX
```bibtex
@article{Shi2025HamiltonianNonreciprocal,
author={Shi, Yu-Bo and Moessner, Roderich and Alert, Ricard and Bukov, Marin},
title = {Hamiltonian description of nonreciprocal interactions},
year = {2025},
journal = {arXiv},
eprint = {2505.05246},
archivePrefix = {arXiv},
primaryClass = {cond-mat.stat-mech},
doi = {10.1038/s41567-026-03317-y}
}
```
## Links
- **arXiv**: [arxiv:2505.05246](https://arxiv.org/abs/2505.05246)
- **article**: [Nature Physics](https://doi.org/10.1038/s41567-026-03317-y)
## What This Record Contains
### Top-level directories
| Path | Contents | Purpose |
| --- | --- | --- |
| `src_code/` | Python scripts, Jupyter notebooks, Slurm scripts | Simulations and post-processing |
| `data/` | Raw and processed datasets | Inputs for analysis and figure generation |
| `src_latex/` | LaTeX sources, `.bbl` files, and compiled PDFs | Manuscript build artifacts |
| `visual_elements/` | Figure/video scripts and exported visual assets | Final visual generation layer |
### Main files and subdirectories
```text
.
├── README.md
├── LICENSE
├── LICENSE-DATA
├── requirements.txt # minimal Python package list for the lightweight plotting/analysis workflow
├── src_latex.zip # archived copy of the LaTeX source directory
├── src_code
│ ├── README.md
│ ├── requirements.txt # fuller original environment export retained with the source archive
│ ├── description.ipynb # notebook-level description of the code/data workflow
│ └── scripts
│ ├── vision_cone_model # simulation scripts for the vision-cone XY model
│ ├── continuous_vision_cone_model # simulation scripts for the continuous vision-cone model
│ ├── nonstationary_model # simulation scripts for the nonstationary model with asymmetric couplings
│ ├── floquet_vision_cone # scripts for the Floquet-driven vision-cone model
│ ├── without_auxiliary_spins # comparison scripts without auxiliary spins
│ └── A_from_raw_to_processed # workflow for converting raw outputs into processed plotting datasets
├── data
│ ├── README.md
│ ├── raw # raw simulation-output directories, organized by figure/run group
│ └── processed # plotting-ready aggregated .npz datasets
├── visual_elements
│ ├── README.md
│ ├── figs
│ │ ├── main # main-text figure scripts and exported figure files
│ │ └── SM # supplementary-figure scripts and exported supplementary figure files
│ └── videos # video-generation script, archived video asset, and bundled ffmpeg helper
│ ├── run_video_oscillation.py
│ ├── ffmpeg
│ └── video_oscillation.mp4
└── src_latex
├── paper_body.tex # shared manuscript body used by all LaTeX entry files
├── main.tex # main-text entry file
├── supp.tex # supplemental-material entry file
├── combined.tex # combined main-text plus supplement entry file
└── bibfile.bib # bibliography database
```
## Data Formats
The primary scientific data format in this record is NumPy compressed archive format, `.npz`. This is the main machine-readable format used for raw outputs and processed datasets.
Other formats used in the record are:
- `.json`: simulation metadata and run arguments, typically stored in `args.json`
- `.py`: Python source files for simulations and utilities
- `.ipynb`: Jupyter notebooks for processing and analysis
- `.sh`: batch scripts for cluster execution
- `.tex`: manuscript source
- `.pdf`: manuscript and figure outputs
- `.mp4`: video output
## Data Description
### Raw data
The raw simulation outputs are stored in [`data/raw/`](data/raw). These folders are grouped by figure or experiment, for example:
- `fig3`
- `fig4`
- `fig7`
- `fig9`
- `fig10`
- `fig11`
- `fig12`
- `fig13`
- `fig14`
- `video`
Each raw run usually contains:
- `args.json`: input arguments used for that simulation
- `results.npz`: compressed arrays with observables and time series
Common arrays stored in `results.npz` include:
- `dt`
- `Tem`
- `M_s`
- `E_s`
- `Order_parameter`
### Processed data
The processed plotting-ready data are stored in [`data/processed/`](data/processed). These files are smaller aggregated `.npz` datasets used directly by the standalone plotting scripts in [`visual_elements/figs/main/`](visual_elements/figs/main) and [`visual_elements/figs/SM/`](visual_elements/figs/SM). Current processed folders include:
- `fig3`
- `fig5`
- `fig7`
- `fig8`
- `fig9`
### Directory naming conventions
Folder names in `data/raw` encode simulation settings such as warmup length, production length, system size, time step, and Monte Carlo proposal size. Examples include:
- `warmup500000_step500000_L100_dt0.01`
- `warmup1500000_N500000_L100_dmax0.1`
- `MC_warmup1_step2000000_L200_diffmax0.05`
- `Langevin_Heun_warmup1_step640000dt0.01_L160`
These names are not only descriptive labels; they are part of the workflow used by the processing notebooks and the standalone plotting scripts.
## Software Environment
For most reuse cases in this archive, the lightweight dependencies are listed in [`requirements.txt`](requirements.txt):
- `numpy`
- `scipy`
- `matplotlib`
- `numba`
- `tqdm`
- `torch`
- `notebook` or `jupyter` (optional, for interactive notebook use)
The file [`src_code/requirements.txt`](src_code/requirements.txt) preserves a fuller original environment export and is retained mainly for archival/reference purposes.
Additional system dependency: `pdflatex`
Several plotting scripts in [`visual_elements/figs/main/`](visual_elements/figs/main), [`visual_elements/figs/SM/`](visual_elements/figs/SM), and [`visual_elements/videos/`](visual_elements/videos) use `matplotlib` with `text.usetex=True`.
Therefore, a working LaTeX installation with `pdflatex` available on `PATH` is required in addition to the Python packages listed in [`requirements.txt`](requirements.txt).
This dependency is not installed by `pip`.
## Building the LaTeX PDFs
The manuscript sources live in [`src_latex/`](src_latex). The LaTeX setup currently consists of three lightweight entry files plus one shared manuscript body:
- [`src_latex/main.tex`](src_latex/main.tex): main text only
- [`src_latex/supp.tex`](src_latex/supp.tex): supplement only
- [`src_latex/combined.tex`](src_latex/combined.tex): main text and supplement together
- [`src_latex/paper_body.tex`](src_latex/paper_body.tex): shared body used by all three entry files
- [`src_latex/bibfile.bib`](src_latex/bibfile.bib): bibliography database
At the moment, the archive does **not** include pre-generated `.bbl` files, so the first rebuild of each target requires running `bibtex` once for that specific entry file.
From the repository root, build the combined manuscript with:
```bash
cd src_latex
pdflatex -interaction=nonstopmode combined.tex
bibtex combined
pdflatex -interaction=nonstopmode combined.tex
pdflatex -interaction=nonstopmode combined.tex
```
This writes [`src_latex/combined.pdf`](src_latex/combined.pdf).
To rebuild only the main text:
```bash
cd src_latex
pdflatex -interaction=nonstopmode main.tex
bibtex main
pdflatex -interaction=nonstopmode main.tex
pdflatex -interaction=nonstopmode main.tex
```
To rebuild only the supplement:
```bash
cd src_latex
pdflatex -interaction=nonstopmode supp.tex
bibtex supp
pdflatex -interaction=nonstopmode supp.tex
pdflatex -interaction=nonstopmode supp.tex
```
Notes:
- Run the commands from inside [`src_latex/`](src_latex), because the LaTeX sources use relative paths to `paper_body.tex`, `bibfile.bib`, and figure assets under [`visual_elements/`](visual_elements).
- Each entry file generates its own auxiliary files. In particular, `combined.tex`, `main.tex`, and `supp.tex` need their own corresponding `.bbl` files: `combined.bbl`, `main.bbl`, and `supp.bbl`.
- After a `.bbl` file has been generated once, and as long as `bibfile.bib` has not changed, later rebuilds of the same target only need the final two `pdflatex` passes.
- Two `pdflatex` passes are recommended after `bibtex` so that citations, cross-references, table-of-contents entries, and hyperlinks settle correctly.
- Figure files are stored outside `src_latex/`, mainly under `visual_elements/figs/main/` and `visual_elements/figs/SM/`.
### Recommended installation steps
From the repository root:
```bash
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
```
To work with the notebooks interactively:
```bash
jupyter notebook
```
## Directories that Generate Visual Elements used in the Paper
All plotting outputs have been consolidated under [`visual_elements/`](visual_elements/). This directory now serves as the central location for the standalone plotting scripts together with the exported figures and video assets used in the paper.
- [`visual_elements/figs/main/`](visual_elements/figs/main): main-text figure scripts and exported files, including `run_fig3.py`, `run_fig4_snapshot.py`, `run_fig4_order_parameter.py`, `run_fig5.py`, `fig1.pdf`, `fig2.pdf`, `fig3.pdf`, `fig4.pdf`, `fig4_snapshot.pdf`, `fig4_order_parameter.pdf`, and `fig5.pdf`
- [`visual_elements/figs/SM/`](visual_elements/figs/SM): supplementary-figure scripts and exported files, including `run_fig7.py`, `run_fig8.py`, `run_fig9.py`, `run_fig10.py`, `run_fig11_langevin.py`, `run_fig12_mc.py`, `run_fig13_period.py`, `run_fig14_comparison.py`, `fig6.pdf`, `fig7.pdf`, `fig8.pdf`, `fig9.pdf`, `fig10.pdf`, `fig11_langevin.pdf`, `fig12_mc.pdf`, `fig13_period.pdf`, and `fig14_comparison.pdf`
- [`visual_elements/videos/`](visual_elements/videos): video-generation assets, currently including `run_video_oscillation.py`, `video_oscillation.mp4`, and the bundled helper [`visual_elements/videos/ffmpeg`](visual_elements/videos/ffmpeg)
Files whose names include the suffix `_origin_adobe` denote PDFs exported directly from Adobe Illustrator.
The numerical inputs consumed by the plotting workflow are stored separately in [`data/processed/`](data/processed), which contains the plotting-ready `.npz` datasets derived from the raw simulations.
## Minimal Reproduction Workflow
1. Create and activate a Python environment.
2. Install the dependencies from [`requirements.txt`](requirements.txt).
3. Run simulations from one of the model directories in `src_code/scripts/` to generate raw outputs in `data/raw`.
4. Open [`data.ipynb`](src_code/scripts/A_from_raw_to_processed/data.ipynb) to convert raw outputs into processed `.npz` files in `data/processed`.
5. Run the relevant scripts in [`visual_elements/figs/main/`](visual_elements/figs/main), [`visual_elements/figs/SM/`](visual_elements/figs/SM), or [`visual_elements/videos/`](visual_elements/videos) to regenerate the figures and video assets from the processed/raw datasets.
For example: `python visual_elements/figs/main/run_fig3.py`, `python visual_elements/figs/SM/run_fig14_comparison.py`, or `python visual_elements/videos/run_video_oscillation.py`
6. Use the entry files in [`src_latex/`](src_latex) together with the generated figures to rebuild [`src_latex/main.pdf`](src_latex/main.pdf), [`src_latex/supp.pdf`](src_latex/supp.pdf), or [`src_latex/combined.pdf`](src_latex/combined.pdf) as needed.
## Additional Notes For Reproducibility
- The safest way to run the simulations is from inside each model directory because the code relies on local imports such as `from util import *`.
- The provided `.sh` scripts are written for a specific Slurm environment and may require edits to partition names, memory settings, paths, Conda activation, and email directives before reuse on another cluster.
- A GPU is not required for the normal workflows in this archive.
- Some Monte Carlo workflows interpret the run length in sweeps scaled by `L**2`; this is expected behavior in this codebase.
- The folder names in `data/raw` are part of the analysis pipeline. Renaming them may break downstream notebooks.
- The standalone video-generation script uses the bundled executable at [`visual_elements/videos/ffmpeg`](visual_elements/videos/ffmpeg) when that helper is used in the local environment.
- Several plotting scripts rely on LaTeX text rendering through `matplotlib`, so `pdflatex` must be installed as a system dependency and available on `PATH`.
- The plotting scripts under [`visual_elements/figs/main/`](visual_elements/figs/main), [`visual_elements/figs/SM/`](visual_elements/figs/SM), and [`visual_elements/videos/`](visual_elements/videos) now resolve data and output paths relative to each script file via `Path(__file__)`. They can therefore be launched from the repository root or via an absolute path without depending on the current working directory.
- macOS metadata files such as `.DS_Store` are not part of the scientific content of the record.
Files
Restricted
The record is publicly accessible, but files are restricted. Log in to check if you have access.
Request access
If you would like to request access to these files, please fill out the form below.
You need to satisfy these conditions in order for this request to be accepted:
Access to this record will be granted upon reasonable request. Please follow the Zenodo policy to submit a request.
You are currently not logged in. Do you have an account? Log in here
Additional details
Identifiers
Funding
Software
- Repository URL
- https://zenodo.org/communities/nqd/records?q=&l=list&p=1&s=10&sort=newest
- Programming language
- Python