# Mean-Motion Resonances
[](https://github.com/psf/black)
[](https://github.com/smirik/resonances/actions/workflows/ci.yml)
`resonances` is an open-source package dedicated to the identification of mean-motion resonances of small bodies. Many examples are for the Solar system; however, you might use the package for any possible planetary system, including exoplanets.
For more information, [read the documentation](https://smirik.github.io/resonances/).
**Note:** while this app has many functional and integration tests built in, it is still in the dev stage. Hence, it might include some inconsistencies. So, any community help is appreciated!
## What's new
### June 2025
1. **Clean Architecture Implementation**: The `Simulation` class has been completely refactored into a clean, component-based architecture without backward compatibility concerns. The main `simulation.py` file has been reduced by **67%** (from 613 to 204 lines) by removing unnecessary setters/getters and moving specialized functionality into dedicated components: `SimulationConfig`, `BodyManager`, `IntegrationEngine`, and `DataManager`.
1. **Modern Configuration Syntax**: Configuration parameters are now accessed using the clean `sim.config.property` syntax (e.g., `sim.config.dt = 0.1`, `sim.config.save = 'all'`). Essential properties needed by external modules (like libration analysis) are still available directly on the simulation object.
1. **Comprehensive Test Refactoring**: All tests have been updated to use the new clean architecture, with 46 simulation component tests passing, ensuring the refactoring maintains full functionality while improving code quality.
### February 2025
1. Full support for `nasa` Horizon source of the initial data.
1. `find` and `check` methods for quick identification of the resonant status of objects.
1. `create_mmr` method now supports variaty of options: string, a list of strings, an object, a list of objects.
1. `Simulation` constructor got many new parameters allowing to change the settings directly when instantiating.
1. Instead of `config.json`, `.env.dist` is now used. Furthermore, a developer can specify `.env` in the directory, which will overwrite the default parameters or just use environment variables.
1. MMRs now have `order` function.
1. Added full support for backward integration (`dt=-1.0`, `tmax=-600000`).
1. Minor updates to graphs.
### October 2024
1. The `resonances.find` method now accepts extra parameters: `name`, `sigma2`, and `sigma3`, [see the documentation](https://smirik.github.io/resonances/).
2. Fixed bug with wrong titles on the plots (periodograms for the resonant angle and semi-major axis).
3. Fixed bug when adding an asteroid that has no relevant MMRs (previously it caused exception).
### July 2024
1. Now you can choose the type of the output image: it could be either ` pdf`` or `png`.
```python
sim = resonances.Simulation()
...
sim.image_type = 'pdf'
```
2. You can plot only resonant asteroids:
```python
sim = resonances.Simulation()
...
sim.plot_only_identified = True
```
If it is `true`, then the app will plot every resonant asteroid even if `plot` is `False`. If `plot` is `True`, this option is ignored.
3. New finder module (easy resonance identification):
```python
import resonances
sim = resonances.find([463, 490], planets=['Mars', 'Jupiter', 'Saturn'])
sim.run()
```
## Features
The package:
- can automatically identify two-body and three-body mean-motion resonance in the Solar system,
- accurately differentiates different types of resonances (pure, transient, uncertain),
- provides an interface for mass tasks (i.e. find resonant areas in a planetary system),
- can plot time series and periodograms,
- and, yeah, it is well tested ;)
It actively uses [REBOUND integrator](https://rebound.readthedocs.io) maintained by Hanno Rein and others.
## Installation
To install resonances on your system, follow the instructions on the appropriate [installation guide](https://smirik.github.io/resonances/install/)
## Mean-motion resonances
For those who are not familiar with the mean-motion resonances, here is the list of papers used to develop this package:
### Papers about the automatic identification of resonant asteroids
1. Smirnov, E. A. & Dovgalev, I. S. Identification of Asteroids in Two-Body Resonances. Solar System Research 52, 347–354 (2018).
2. Smirnov, E. A. (2023). A new python package for identifying celestial bodies trapped in mean-motion resonances. Astronomy and Computing, 100707. https://doi.org/10.1016/j.ascom.2023.100707
3. Smirnov, E. A. & Shevchenko, I. I. Massive identification of asteroids in three-body resonances. Icarus 222, 220–228 (2013).
4. Smirnov, E. A., Dovgalev, I. S. & Popova, E. A. Asteroids in three-body mean motion resonances with planets. Icarus (2017) doi:10.1016/j.icarus.2017.09.032.
5. Nesvorný, D. & Morbidelli, A. Three-Body Mean Motion Resonances and the Chaotic Structure of the Asteroid Belt. The Astronomical Journal 116, 3029–3037 (1998).
### Papers about mean-motion resonances
1. Chirikov, B. V. A universal instability of many-dimensional oscillator systems. Physics reports 52, 263–379 (1979).
1. Gallardo, T. Strength, stability and three dimensional structure of mean motion resonances in the solar system. Icarus 317, 121–134 (2019).
1. Gallardo, T. Atlas of the mean motion resonances in the Solar System. Icarus 184, 29–38 (2006).
1. Gallardo, T., Coito, L. & Badano, L. Planetary and satellite three body mean motion resonances. Icarus 274, 83–98 (2016).
1. Milani, A., Cellino, A., Knezevic, Z., Novaković, B. & Spoto, F. Asteroid families classification: Exploiting very large datasets. Icarus 239, 46–73 (2014).
1. Murray, N. & Holman, M. Diffusive chaos in the outer asteroid belt. The Astronomical Journal 114, 1246 (1997).
1. Murray, N., Holman, M. & Potter, M. On the Origin of Chaos in the Asteroid Belt. The Astronomical Journal 116, 2583–2589 (1998).
1. Shevchenko, I. I. On the Lyapunov exponents of the asteroidal motion subject to resonances and encounters. Proc. IAU 2, 15–30 (2006).
### Books
1. Murray, C. D. & Dermott, S. F. Solar system dynamics. (Cambridge Univ. Press, 2012).
1. Morbidelli, A. Modern celestial mechanics: aspects of solar system dynamics. (2002).
## References
Whenever you use this package, we are kindly asking you to refer to one of the following papers (please choose the appropriate):
1. **The package itself**:
- Smirnov, E. A. (2023). A new python package for identifying celestial bodies trapped in mean-motion resonances. Astronomy and Computing. https://doi.org/10.1016/j.ascom.2023.100707
```tex
@article{Smirnov2023,
title = {A new python package for identifying celestial bodies trapped in mean-motion resonances},
journal = {Astronomy and Computing},
year = {2023},
issn = {2213-1337},
doi = {https://doi.org/10.1016/j.ascom.2023.100707},
url = {https://www.sciencedirect.com/science/article/pii/S2213133723000227},
author = {E.A. Smirnov},
keywords = {Mean-motion resonances, Python, Identification, Asteroids},
abstract = {In this paper, a new open-source package ‘resonances’ written in python is introduced. It allows to find, analyse, and plot two-body and three-body mean-motion eccentricity-type resonances in the Solar and other planetary systems. The package has a better accuracy of the automatic identification procedure for resonant objects compared to previous studies. Furthermore, it has built-in integrations with AstDyS and NASA JPL catalogues. The code is extensively documented and tested with automatic tests. The package is available on GitHub under MIT Licence.}
}
```
2. **The Libration module and automatic identification of librations**:
- Smirnov, E. A. (2023). A new python package for identifying celestial bodies trapped in mean-motion resonances. Astronomy and Computing, 100707. https://doi.org/10.1016/j.ascom.2023.100707
3. **Mass identification of mean-motion resonances:**
- Smirnov, E. A., & Dovgalev, I. S. (2018). Identification of Asteroids in Two-Body Resonances. Solar System Research, 52(4), 347–354. https://doi.org/10.1134/S0038094618040056
- Smirnov, E. A., Dovgalev, I. S. & Popova, E. A. Asteroids in three-body mean motion resonances with planets. Icarus (2017) doi:10.1016/j.icarus.2017.09.032.
## Authors
The authors of the package:
- [Evgeny Smirnov](https://github.com/smirik) ([FB](https://facebook.com/smirik), [Telegram](https://t.me/smirik))
## Acknowledgement
- Many thanks to the co-authors of the papers (prof. I. I. Shevchenko, I. Dovgalev, and Dr. E. Popova).
- The creators of [REBOUND integrator](https://rebound.readthedocs.io).
- The creators of [Astropy](http://astropy.org).
- The creators of `numpy`, `scipy`, `pandas`, and `matplotlib`.
## Contributing
Feel free to contribute to the code by sending pull requests [to the repository](https://github.com/smirik/resonances).
## License
MIT
Raw data
{
"_id": null,
"home_page": "http://smirik.github.io/resonances/",
"name": "resonances",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.11",
"maintainer_email": null,
"keywords": "astronomy, nbody, resonance, mmr",
"author": "Evgeny Smirnov",
"author_email": "smirik@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/2b/76/8ce7632a95484ed47a2b65fdd65702b84cea0ec486ae6d1c50723d446074/resonances-0.5.0.tar.gz",
"platform": null,
"description": "# Mean-Motion Resonances\n\n[](https://github.com/psf/black)\n[](https://github.com/smirik/resonances/actions/workflows/ci.yml)\n\n`resonances` is an open-source package dedicated to the identification of mean-motion resonances of small bodies. Many examples are for the Solar system; however, you might use the package for any possible planetary system, including exoplanets.\n\nFor more information, [read the documentation](https://smirik.github.io/resonances/).\n\n**Note:** while this app has many functional and integration tests built in, it is still in the dev stage. Hence, it might include some inconsistencies. So, any community help is appreciated!\n\n## What's new\n\n### June 2025\n\n1. **Clean Architecture Implementation**: The `Simulation` class has been completely refactored into a clean, component-based architecture without backward compatibility concerns. The main `simulation.py` file has been reduced by **67%** (from 613 to 204 lines) by removing unnecessary setters/getters and moving specialized functionality into dedicated components: `SimulationConfig`, `BodyManager`, `IntegrationEngine`, and `DataManager`.\n1. **Modern Configuration Syntax**: Configuration parameters are now accessed using the clean `sim.config.property` syntax (e.g., `sim.config.dt = 0.1`, `sim.config.save = 'all'`). Essential properties needed by external modules (like libration analysis) are still available directly on the simulation object.\n1. **Comprehensive Test Refactoring**: All tests have been updated to use the new clean architecture, with 46 simulation component tests passing, ensuring the refactoring maintains full functionality while improving code quality.\n\n### February 2025\n\n1. Full support for `nasa` Horizon source of the initial data.\n1. `find` and `check` methods for quick identification of the resonant status of objects.\n1. `create_mmr` method now supports variaty of options: string, a list of strings, an object, a list of objects.\n1. `Simulation` constructor got many new parameters allowing to change the settings directly when instantiating.\n1. Instead of `config.json`, `.env.dist` is now used. Furthermore, a developer can specify `.env` in the directory, which will overwrite the default parameters or just use environment variables.\n1. MMRs now have `order` function.\n1. Added full support for backward integration (`dt=-1.0`, `tmax=-600000`).\n1. Minor updates to graphs.\n\n### October 2024\n\n1. The `resonances.find` method now accepts extra parameters: `name`, `sigma2`, and `sigma3`, [see the documentation](https://smirik.github.io/resonances/).\n2. Fixed bug with wrong titles on the plots (periodograms for the resonant angle and semi-major axis).\n3. Fixed bug when adding an asteroid that has no relevant MMRs (previously it caused exception).\n\n### July 2024\n\n1. Now you can choose the type of the output image: it could be either ` pdf`` or `png`.\n\n```python\nsim = resonances.Simulation()\n...\nsim.image_type = 'pdf'\n```\n\n2. You can plot only resonant asteroids:\n\n```python\nsim = resonances.Simulation()\n...\nsim.plot_only_identified = True\n```\n\nIf it is `true`, then the app will plot every resonant asteroid even if `plot` is `False`. If `plot` is `True`, this option is ignored.\n\n3. New finder module (easy resonance identification):\n\n```python\nimport resonances\n\nsim = resonances.find([463, 490], planets=['Mars', 'Jupiter', 'Saturn'])\nsim.run()\n```\n\n## Features\n\nThe package:\n\n- can automatically identify two-body and three-body mean-motion resonance in the Solar system,\n- accurately differentiates different types of resonances (pure, transient, uncertain),\n- provides an interface for mass tasks (i.e. find resonant areas in a planetary system),\n- can plot time series and periodograms,\n- and, yeah, it is well tested ;)\n\nIt actively uses [REBOUND integrator](https://rebound.readthedocs.io) maintained by Hanno Rein and others.\n\n## Installation\n\nTo install resonances on your system, follow the instructions on the appropriate [installation guide](https://smirik.github.io/resonances/install/)\n\n## Mean-motion resonances\n\nFor those who are not familiar with the mean-motion resonances, here is the list of papers used to develop this package:\n\n### Papers about the automatic identification of resonant asteroids\n\n1. Smirnov, E. A. & Dovgalev, I. S. Identification of Asteroids in Two-Body Resonances. Solar System Research 52, 347\u2013354 (2018).\n2. Smirnov, E. A. (2023). A new python package for identifying celestial bodies trapped in mean-motion resonances. Astronomy and Computing, 100707. https://doi.org/10.1016/j.ascom.2023.100707\n3. Smirnov, E. A. & Shevchenko, I. I. Massive identification of asteroids in three-body resonances. Icarus 222, 220\u2013228 (2013).\n4. Smirnov, E. A., Dovgalev, I. S. & Popova, E. A. Asteroids in three-body mean motion resonances with planets. Icarus (2017) doi:10.1016/j.icarus.2017.09.032.\n5. Nesvorn\u00fd, D. & Morbidelli, A. Three-Body Mean Motion Resonances and the Chaotic Structure of the Asteroid Belt. The Astronomical Journal 116, 3029\u20133037 (1998).\n\n### Papers about mean-motion resonances\n\n1. Chirikov, B. V. A universal instability of many-dimensional oscillator systems. Physics reports 52, 263\u2013379 (1979).\n1. Gallardo, T. Strength, stability and three dimensional structure of mean motion resonances in the solar system. Icarus 317, 121\u2013134 (2019).\n1. Gallardo, T. Atlas of the mean motion resonances in the Solar System. Icarus 184, 29\u201338 (2006).\n1. Gallardo, T., Coito, L. & Badano, L. Planetary and satellite three body mean motion resonances. Icarus 274, 83\u201398 (2016).\n1. Milani, A., Cellino, A., Knezevic, Z., Novakovi\u0107, B. & Spoto, F. Asteroid families classification: Exploiting very large datasets. Icarus 239, 46\u201373 (2014).\n1. Murray, N. & Holman, M. Diffusive chaos in the outer asteroid belt. The Astronomical Journal 114, 1246 (1997).\n1. Murray, N., Holman, M. & Potter, M. On the Origin of Chaos in the Asteroid Belt. The Astronomical Journal 116, 2583\u20132589 (1998).\n1. Shevchenko, I. I. On the Lyapunov exponents of the asteroidal motion subject to resonances and encounters. Proc. IAU 2, 15\u201330 (2006).\n\n### Books\n\n1. Murray, C. D. & Dermott, S. F. Solar system dynamics. (Cambridge Univ. Press, 2012).\n1. Morbidelli, A. Modern celestial mechanics: aspects of solar system dynamics. (2002).\n\n## References\n\nWhenever you use this package, we are kindly asking you to refer to one of the following papers (please choose the appropriate):\n\n1. **The package itself**:\n\n- Smirnov, E. A. (2023). A new python package for identifying celestial bodies trapped in mean-motion resonances. Astronomy and Computing. https://doi.org/10.1016/j.ascom.2023.100707\n\n```tex\n@article{Smirnov2023,\n title = {A new python package for identifying celestial bodies trapped in mean-motion resonances},\n journal = {Astronomy and Computing},\n year = {2023},\n issn = {2213-1337},\n doi = {https://doi.org/10.1016/j.ascom.2023.100707},\n url = {https://www.sciencedirect.com/science/article/pii/S2213133723000227},\n author = {E.A. Smirnov},\n keywords = {Mean-motion resonances, Python, Identification, Asteroids},\n abstract = {In this paper, a new open-source package \u2018resonances\u2019 written in python is introduced. It allows to find, analyse, and plot two-body and three-body mean-motion eccentricity-type resonances in the Solar and other planetary systems. The package has a better accuracy of the automatic identification procedure for resonant objects compared to previous studies. Furthermore, it has built-in integrations with AstDyS and NASA JPL catalogues. The code is extensively documented and tested with automatic tests. The package is available on GitHub under MIT Licence.}\n}\n```\n\n2. **The Libration module and automatic identification of librations**:\n\n- Smirnov, E. A. (2023). A new python package for identifying celestial bodies trapped in mean-motion resonances. Astronomy and Computing, 100707. https://doi.org/10.1016/j.ascom.2023.100707\n\n3. **Mass identification of mean-motion resonances:**\n\n- Smirnov, E. A., & Dovgalev, I. S. (2018). Identification of Asteroids in Two-Body Resonances. Solar System Research, 52(4), 347\u2013354. https://doi.org/10.1134/S0038094618040056\n- Smirnov, E. A., Dovgalev, I. S. & Popova, E. A. Asteroids in three-body mean motion resonances with planets. Icarus (2017) doi:10.1016/j.icarus.2017.09.032.\n\n## Authors\n\nThe authors of the package:\n\n- [Evgeny Smirnov](https://github.com/smirik) ([FB](https://facebook.com/smirik), [Telegram](https://t.me/smirik))\n\n## Acknowledgement\n\n- Many thanks to the co-authors of the papers (prof. I.\u00a0I. Shevchenko, I.\u00a0Dovgalev, and Dr.\u00a0E.\u00a0Popova).\n- The creators of [REBOUND integrator](https://rebound.readthedocs.io).\n- The creators of [Astropy](http://astropy.org).\n- The creators of `numpy`, `scipy`, `pandas`, and `matplotlib`.\n\n## Contributing\n\nFeel free to contribute to the code by sending pull requests [to the repository](https://github.com/smirik/resonances).\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Identification of mean-motion resonances",
"version": "0.5.0",
"project_urls": {
"Documentation": "http://smirik.github.io/resonances/",
"Homepage": "http://smirik.github.io/resonances/",
"Repository": "https://github.com/smirik/resonances"
},
"split_keywords": [
"astronomy",
" nbody",
" resonance",
" mmr"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "17abc0c0b7afa90d8d97ad7addc6d7b00c9fd833e94ddf211a723da45164043d",
"md5": "5da35e48639931400743ddbb7b9099c7",
"sha256": "33c2e12a32bfefb1cb1221b64edbdb20d58e5d67ab1d9d08a671c397e7c62147"
},
"downloads": -1,
"filename": "resonances-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5da35e48639931400743ddbb7b9099c7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.11",
"size": 48090,
"upload_time": "2025-07-08T19:11:19",
"upload_time_iso_8601": "2025-07-08T19:11:19.201030Z",
"url": "https://files.pythonhosted.org/packages/17/ab/c0c0b7afa90d8d97ad7addc6d7b00c9fd833e94ddf211a723da45164043d/resonances-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2b768ce7632a95484ed47a2b65fdd65702b84cea0ec486ae6d1c50723d446074",
"md5": "bd2fe2b6207d61b0ca60b622374d922a",
"sha256": "a255e92c3f10507cdf7370bd9cbd6bb3bdcefe2eda8d7ec8e1a3c36a9883a03c"
},
"downloads": -1,
"filename": "resonances-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "bd2fe2b6207d61b0ca60b622374d922a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.11",
"size": 39082,
"upload_time": "2025-07-08T19:11:20",
"upload_time_iso_8601": "2025-07-08T19:11:20.144009Z",
"url": "https://files.pythonhosted.org/packages/2b/76/8ce7632a95484ed47a2b65fdd65702b84cea0ec486ae6d1c50723d446074/resonances-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 19:11:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "smirik",
"github_project": "resonances",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "resonances"
}
JSON
