Update documentation

smirik · Feb 15, 2025 · 3620883 · 3620883
1 parent b6db0c1
commit 3620883
Show file tree

Hide file tree

Showing 12 changed files with 164 additions and 355 deletions.
diff --git a/docs/about.md b/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.
diff --git a/docs/config.md b/docs/config.md
diff --git a/docs/core.ipynb b/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

diff --git a/docs/examples.ipynb b/docs/examples.ipynb
@@ -16,7 +16,9 @@
    "source": [
     "## AstDyS Catalog\n",
     "\n",
-    "By default, the application uses NASA Horizon database for the initial data. However, there is another option for numbered asteroids — AstDyS catalog. The app will download the latest version, convert it, and start using it in simulation."
+    "By default, the application uses NASA Horizon database for the initial data. However, there is another option for numbered asteroids — AstDyS catalog. The app will download the latest version, convert it, and start using it in simulation.\n",
+    "\n",
+    "This is especially useful if you need to run some statistical experiments, such as finding all asteroids trapped in a specific resonance."
    ]
   },
   {
@@ -33,6 +35,16 @@
     "sim.add_body(463, '4J-2S-1', '463 Lola')"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import warnings\n",
+    "warnings.filterwarnings(\"ignore\")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -71,24 +83,36 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 2,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
+      "Searching NASA Horizons for 'Sun'... \n",
+      "Found: Sun (10) \n",
+      "Searching NASA Horizons for 'Mercury'... \n",
+      "Found: Mercury Barycenter (199) (chosen from query 'Mercury')\n",
+      "Searching NASA Horizons for 'Venus'... \n",
+      "Found: Venus Barycenter (299) (chosen from query 'Venus')\n",
+      "Searching NASA Horizons for 'Earth'... \n",
+      "Found: Earth-Moon Barycenter (3) (chosen from query 'Earth')\n",
+      "Searching NASA Horizons for 'Mars'... \n",
+      "Found: Mars Barycenter (4) (chosen from query 'Mars')\n",
+      "Searching NASA Horizons for 'Jupiter'... \n",
+      "Found: Jupiter Barycenter (5) (chosen from query 'Jupiter')\n",
+      "Searching NASA Horizons for 'Saturn'... \n",
+      "Found: Saturn Barycenter (6) (chosen from query 'Saturn')\n",
+      "Searching NASA Horizons for 'Uranus'... \n",
+      "Found: Uranus Barycenter (7) (chosen from query 'Uranus')\n",
+      "Searching NASA Horizons for 'Neptune'... \n",
+      "Found: Neptune Barycenter (8) (chosen from query 'Neptune')\n",
+      "Searching NASA Horizons for 'Pluto'... \n",
+      "Found: Pluto Barycenter (9) (chosen from query 'Pluto')\n",
       "Searching NASA Horizons for '463;'... \n",
       "Found: 463 Lola (A900 UK) \n"
      ]
-    },
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "/Users/smirik/projects/resonances/.venv/lib/python3.11/site-packages/rebound/horizons.py:172: RuntimeWarning: Warning: Mass cannot be retrieved from NASA HORIZONS. Set to 0.\n",
-      "  warnings.warn(\"Warning: Mass cannot be retrieved from NASA HORIZONS. Set to 0.\", RuntimeWarning)\n"
-     ]
     }
    ],
    "source": [

diff --git a/docs/examples/asteroids.json b/docs/examples/asteroids.json
diff --git a/docs/examples/simulation-shape.json b/docs/examples/simulation-shape.json
diff --git a/docs/index.md b/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).
 

diff --git a/docs/install.md b/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

diff --git a/docs/libration.md b/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
diff --git a/docs/matrix.md b/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`)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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