v0.4.0: environment variables support, backward integration, interfac…

…e simplification, tests (#34)

* Save and plot nonzero items by default. Remove experiments
* Refactor find method to accept extra parameters; fixed bug with wrong titles and asteroids without MMRs
* Add CITATION.cff
* Add order function
* Added find_resonances function. 
* Added nasa source for initial data
* New interface to resonances.Simulation. More parameters in constructor. Full support of NASA as a source. Full control of the data. Correct building and using .bin file when data is saved. Simplified interface for creating 1 or many MMRs from strings or lists.
* Update astdys to 0.9.3. Make sim.date object, not str.  Add date parameter when retrieving data from horizon. Started work on sim configuration update. Fix tests
* Shift from .json to .env. Fixed bug with small monotony stuff.
* flake8 updates
* Adding more tests for coverage.
* Added full support for backward integration
* Update documentation
* Update README
* Update poetry

CITATION.cff

@@ -0,0 +1,12 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: Smirnov
+    given-names: Evgeny
+    orcid: https://orcid.org/0000-0001-8264-8668
+title: "resonances python package"
+version: 0.3.1
+identifiers:
+  - type: doi
+    value: 10.1016/j.ascom.2023.100707
+date-released: 2023-03-18

README.md

@@ -11,6 +11,23 @@ For more information, [read the documentation](https://smirik.github.io/resonanc
 
 ## What's new
 
+### 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`.

docs/about.md

@@ -17,10 +17,7 @@ Whenever you use this package, we are kindly asking you to refer to one of the f
 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
 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.

docs/core.ipynb

@@ -213,7 +213,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Note, if AstDyS catalogue is already downloaded, the package **will not check** whether it is updated. On the contrary, it will use the old version. However, the `astdys` component has a special method `rebuild' that updates the catalogue. Hence, one might use this method for the final run."
+    "Note, if AstDyS catalogue is already downloaded, the package **will not check** whether it is updated. On the contrary, it will use the old version. However, the `astdys` component has a special method `rebuild' that updates the catalogue. Hence, one might use this method for the final run. \n",
+    "\n",
+    "Or you can simply delete the downloaded and converted files..."
    ]
   },
   {
@@ -245,11 +247,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "sim.save = 'nonzero' # other options: 'resonant' (only resonant), 'nonzero' (resonant and candidates), None (do not save anything)\n",
+    "sim.save = 'nonzero' # other options: 'resonant' (only resonant), 'nonzero' (resonant and candidates), None (do not save anything), 'all'\n",
     "sim.plot = None # the same as above\n",
     "sim.plot_type = 'save' # other options: 'show' (show the plot), 'save' (save the plot), 'both', and None (do not plot anything)"
    ]
@@ -263,7 +265,7 @@
     "\n",
     "Please be aware of [default values](../config) — it saves some space for each simulation. There is no need to override if you are OK with them.\n",
     "\n",
-    "You may also want to change the output directory — just rewrite the config `sim.save_path` and `sim.plot_path` after initialisation or make `config.json` file.\n",
+    "You may also want to change the output directory — just rewrite the config `sim.save_path` and `sim.plot_path` after initialisation or make `.env` file or set the environment variable up.\n",
     "\n",
     "You may add as many objects as you want. However, when the number of asteroids is very high, it might delay the integration process. The usual suggestion is to integrate 100-1000 objects simultaneously, but it depends on the computer's characteristics.\n",
     "\n",
@@ -432,7 +434,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": ".venv",
    "language": "python",
    "name": "python3"
   },
@@ -446,14 +448,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.1"
+   "version": "3.11.9"
   },
-  "orig_nbformat": 4,
-  "vscode": {
-   "interpreter": {
-    "hash": "cd427db76977a9ac7182f48fec693ea25b2d6de175c77dfc5a78e40d10994c7e"
-   }
-  }
+  "orig_nbformat": 4
  },
  "nbformat": 4,
  "nbformat_minor": 2

docs/index.md

@@ -2,15 +2,14 @@
 
 `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 now, the package supports only eccentricity-type resonances. However, it will be improved in the future.
 
-**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!
-
 ## 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),
+-   has integration with NASA Horizon (through rebound) and AstDyS catalog,
 -   can plot time series and periodograms,
 -   and, yeah, it is well tested ;)
 
@@ -41,6 +40,7 @@ For those who are not familiar with the mean-motion resonances, here is the list
 
 ### Books
 
+1. Valerio Carruba, Evgeny Smirnov, Dagmara Oszkiewicz. Machine Learning for Small Bodies in the Solar System. (Elsevier, 2024). https://doi.org/10.1016/C2023-0-51021-3
 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).
 

docs/install.md

@@ -1,8 +1,14 @@
 # Installation
 
+The fastest way:
+
+```bash
+pip install resonances
+```
+
 ## Poetry
 
-The best way to install `resonances` package is through [poetry](https://python-poetry.org), which is the dependency manager for python. In this case, you only need to write:
+The _best_ way to install `resonances` package is through [poetry](https://python-poetry.org), which is the dependency manager for python. In this case, you only need to write:
 
 ```bash
 poetry add resonances

docs/libration.md

@@ -76,5 +76,3 @@ The filtering procedure uses [scipy.signal.filtfilt](https://docs.scipy.org/doc/
 Another complication appears after applying the filter: the values of the first and the last points (in time) might be 'damaged' because the filter smooths the data based on the historical values, which are not presented for the beginning and the end. Thus, it is a good idea to cut some points off to improve the accuracy of the identification of oscillations frequencies.
 
 To calculate the number of points to cut, the app uses the parameter `libration.period.min` (by default, `500`), which represents the number of years to remove from the beginning and end. To adjust it to other parameters, it is multiplied by the sampling frequency. Hence, there are no very low frequencies in the resulting data. If you do not want to cut these points, just set the parameter to `0`.
-
-### The usage

docs/matrix.md

@@ -6,7 +6,7 @@ This app calculates the value of the resonant semi-major axis for three-body res
 
 ## Initialisation
 
-When the app needs to know the value of the resonant semi-major axis for the first time, it calculates it and stores it in the file (the config items `matrix.3body.file` and `matrix.2body.file`). The files have the following structure:
+When the app needs to know the value of the resonant semi-major axis for the first time, it calculates it and stores it in the file (the config items `MATRIX_3BODY_FILE` and `MATRIX_2BODY_FILE`). The files have the following structure:
 
 1. The number of an item
 1. The short notation of resonance (i.e. `4J-2S-1` or `1J-1`)