Blue style

JuliaStellarDynamics · Mar 7, 2024 · 13f91dc · 13f91dc
1 parent fb463d1
commit 13f91dc
Show file tree

Hide file tree

Showing 52 changed files with 2,917 additions and 2,638 deletions.
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,6 @@
 name = "OrbitalElements"
 uuid = "a3b07092-bde3-4843-b84f-c597d614ec7b"
-authors = ["Mike Petersen <[email protected]>", "Mathieu Roule <[email protected]>"]
-version = "2.0.0dev-0"
+version = "2.0.0dev-2"
 
 [deps]
 HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"

diff --git a/benchmarks/runbenchmarks.jl b/benchmarks/runbenchmarks.jl
@@ -11,27 +11,26 @@ function bench()
     println("git commit: "*LibGit2.head((@__DIR__)*"/.."))
 
     # Considered potential (isochrone)
-    pot = IsochronePotential()
-    params = OrbitalParameters(Ω₀=Ω₀(pot))
+    anapot = AnalyticIsochrone()
+    numpot = NumericalIsochrone()
+    params = OrbitalParameters(Ω₀=Ω₀(numpot))
     # Considered locations
     a, e = 1.0, 0.05
     u = 0.4
-    Ω1, Ω2 = ComputeFrequenciesAE(pot,a,e)
+    Ω1, Ω2 = frequencies_from_ae(a,e,anapot)
 
     println("ANALYTICAL COMPUTATIONS:")
     println("Frequencies computation Benchmark")
-    @btime ComputeFrequenciesAE($pot,$a,$e)
+    @btime frequencies_from_ae($a,$e,$anapot)
     println("Frequencies inversion Benchmark")
-    @btime ComputeAEFromFrequencies($pot,$Ω1,$Ω2)
+    @btime ae_from_frequencies($Ω1,$Ω2,$anapot)
     println("NUMERICAL COMPUTATIONS:")
     println("Frequencies integrand computation Benchmark")
-    @btime OrbitalElements.ΘAE($pot,$u,$a,$e,$params)
+    @btime OrbitalElements.Θ($u,$a,$e,$numpot,$params)
     println("Frequencies computation Benchmark")
-    @btime ComputeFrequenciesAE($pot,$a,$e,$params)
+    @btime frequencies_from_ae($a,$e,$numpot,$params)
     println("Frequencies inversion Benchmark")
-    @btime ComputeAEFromFrequencies($pot,$Ω1,$Ω2,$params)
-    _, _, niter, _ = OrbitalElements.AEFromΩ1Ω2Brute(Ω1,Ω2,pot,params)
-    println("Number of iterations : ",niter)
+    @btime ae_from_frequencies($Ω1,$Ω2,$numpot,$params)
 end
 
 bench()
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,12 +1,34 @@
 # Adding the package src to the load path
 push!(LOAD_PATH,"../src/")
 
-using Documenter, OrbitalElements
+using Documenter
+using OrbitalElements
+
+# Use the readme as the installation page
+# Open  readme page
+readme = open(dirname(@__FILE__) * "/../README.md") do io
+      read(io, String)
+end
+# Remove the images by which are not under docs/ folder
+# and fail to render
+ref1="![`Isochrone frequencies`](examples/IsochroneFrequencies_original.png)"
+ref2="![`Forward+backward errors`](examples/ForwardBackwardErrors_original.png)"
+readme = replace(readme, ref1 => s"")
+readme = replace(readme, ref2 => s"")
+# Same with the notebook reference
+readme = replace(readme, "[`examples/test_OrbitalElements.ipynb`](examples/test_OrbitalElements.ipynb)" => "examples/test_OrbitalElements.ipynb")
+# Paste it in installation page
+open(dirname(@__FILE__) * "/src/installation.md", "w") do io
+      write(io, readme)
+end
 
 makedocs(sitename = "OrbitalElements.jl",
          pages=[
                 "Home" => "index.md",
-                "Functions" => "functions.md"
+                "Quick start" => "installation.md",
+                "Manual" => "manual.md",
+                "Formulae" => "formulae.md",
+                "References" => "functions.md"
                ],
          format = Documenter.HTML(prettyurls=false))
 

diff --git a/docs/src/formulae.md b/docs/src/formulae.md
diff --git a/docs/src/functions.md b/docs/src/functions.md
@@ -3,42 +3,33 @@
 
 ## Potentials
 ```@docs
-OrbitalElements.dψMestel
+ψ    
+dψ
+d2ψ    
 ```
 
 ## Distribution functions
 ```@docs
-OrbitalElements.Miyamoto_DF
-OrbitalElements.IsoDiscKal_DF
-OrbitalElements.IsoDiscPLB_ndDFdJ
-OrbitalElements.ZangOuterTaperdL
+
 ```
 
+---
 # Changes of coordinates
 ```@docs
-OrbitalElements.Ω1circular
-OrbitalElements.EFromAE
-OrbitalElements.ELFromAE
-OrbitalElements.ComputeActionsAE
-OrbitalElements.FrequenciesFromαβ
-OrbitalElements.Getϖ
-OrbitalElements.FindVbound
-OrbitalElements.RcircFromΩ2circ
+
 ```
 
 ## Isochrone specific functions
 ```@docs
-OrbitalElements.IsochroneβAE
+
 ```
 
 ## Plummer specific functions
 ```@docs
-OrbitalElements.dΘRpRaPlummer
-OrbitalElements.PlummerELFromSpSa
+
 ```
 
 # Utility functions
 ```@docs
-OrbitalElements.NonAsciiHandle
-OrbitalElements.GetResLinesJL
+
 ```
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,29 +1,43 @@
 # OrbitalElements.jl
 
-*Galactic dynamics orbits in Julia*
+*Conversions between orbital constants for galactic dynamics in Julia.*
 
 ---
-## Sample potentials
+## Purpose and Scope
 
-`OrbitalElements` ships with a handful of simple potentials and distribution functions for testing purposes. These are located in `src/Potential`: (1) the 3d Isochrone potential, (2) the 3d Plummer potential, (3) the 2d Mestel-Zang disc, and (4) the 2d Kuzmin-Toomre disc. Corresponding distribution functions are located in `src/DistributionFunctions`.
+`OrbitalElements` provides changes of variables between various orbital constant/integrals in self-gravitating systems.
+It is tailored for a specific set of systems, focusing on scenarios for linear response computations. 
+By narrowing its scope, the library maintains clarity and efficiency in handling orbital dynamics within these systems. 
+While it may not offer the generality of other related libraries ([galpy](https://www.galpy.org), [AGAMA](https://github.com/GalacticDynamics-Oxford/Agama/tree/master)...), it excels in its targeted application domain.
+
+For now, `OrbitalElements` specializes in handling orbits confined to a plane, such as in razor-thin discs or spherical systems, within central potentials. 
+While its primary focus lies in these specific systems, it will be extended to encompass other systems in the future.
 
 ---
-## Obtaining Orbital Frequencies
+## Planar orbits
 
-The principal use for `OrbitalElements` is to provide descriptions of orbits. This means
-1. Conversion from (semimajor axis, eccentricity) to (pericentre, apocentre) to (energy, angular momentum), to coordinates aligned with resonance vectors.
-2. Additional support for actions and angles.
+### Constants of motion
 
-`ComputeFrequenciesAE(ψ,dψ,d2ψ,a,e)` will compute frequencies (Ω₁,Ω₂) given a potential (ψ) plus two derivatives (dψ,d2ψ), for an orbit described by semimajor axis and eccentricity.
+Given a central potential model, `OrbitalElements` provides mapping functions and jacobians 
+between the following constants of motion
++ Model-independent constants
+    - semi-major axis and eccentricity: $(a,e)$
+    - pericentre and apocentre: $(r_p,r_a)$
++ "Analytic" constants
+    - energy and angular momentum: $(E,L)$
++ "Integrated" constants
+    - actions: $(J,L)$
+    - frequency ratios: $(\alpha,\beta)$
+    - frequencies: $(\Omega_1,\Omega_2)$
 
----
-## Mapping to Resonance Space
+While [explicit formulae](formulae.md) for actions are often given as a function of $(r_p,r_a)$, the $(a,e)$-domain is more suitable to handle close-to-the-edge cases (near circular or near radial orbits) and to cure divergences in frequency computations.
 
-For a given potential, one can also compute the resonance mappings, called (u,v). See `src/Resonance` for associated conversions.
-`UVFromαβ(α,β,n₁,n₂,ωmin,ωmax)` will compute the resonant mappings (u,v) for a given frequency pair (α,β), resonance vector (n₁,n₂), and frequency limits.
+Semi-major axis and eccentricity are therefore used as base constants, so that, e.g., going from actions to frequencies would in practice require performing $(J,L)\!\to\!(a,e)\!\to\!(\Omega_1,\Omega_2)$ (as no explicit formulae exists to generically convert actions in frequencies).
 
----
-## Notes
-By default, `OrbitalElements` uses semimajor axis and eccentricity. If you want to use pericentre and apocentre, transformations are available. `AEFromRpRa(rp,ra)` will return semimajor axis and eccentricity from pericentre and apocentre.
 
-`OrbitalElements` also uses the Henon (1971) technique to cure radial velocity divergences at peri- and apocentre.
+
+### Resonance variables
+
+For a given potential, one can also compute the resonance mappings, called $(u,v)$, defined in [Fouvry & Prunet (2022)](https://doi.org/10.1093/mnras/stab3020). 
+These mappings depend on the resonance vector $(n_1,n_2)$ and prove particularly useful for linear response' computations.
+See `src/mappings/Resonance` for associated conversions.
diff --git a/docs/src/installation.md b/docs/src/installation.md
@@ -0,0 +1,118 @@
+
+# OrbitalElements.jl
+
+[![image](https://github.com/JuliaStellarDynamics/OrbitalElements.jl/actions/workflows/documentation.yml/badge.svg)](https://juliastellardynamics.github.io/OrbitalElements.jl/)
+[![image](https://img.shields.io/badge/docs-dev-blue.svg)](https://juliastellardynamics.github.io/OrbitalElements.jl/dev/)
+[![image](https://github.com/JuliaStellarDynamics/OrbitalElements.jl/actions/workflows/devCI.yml/badge.svg?branch=v2.0)](https://github.com/JuliaStellarDynamics/OrbitalElements.jl/actions/workflows/devCI.yml)
+[![image](https://img.shields.io/badge/julia-stable-blue)](https://github.com/JuliaStellarDynamics/OrbitalElements.jl/actions/workflows/devCI.yml)
+[![image](http://codecov.io/gh/JuliaStellarDynamics/OrbitalElements.jl/coverage.svg?branch=v2.0)](http://app.codecov.io/gh/JuliaStellarDynamics/OrbitalElements.jl?branch=2.0)
+[![image](http://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/JuliaStellarDynamics/OrbitalElements.jl/blob/v2.0/LICENSE)
+[![image](http://img.shields.io/badge/DOI-10.48550/arXiv.2311.10630-blue.svg)](http://dx.doi.org/10.48550/arXiv.2311.10630)
+
+
+
+`OrbitalElements` is a package written in Julia to compute numerical elements for astronomical orbits to high precision, for arbitrary potentials.
+
+---
+## Quick installation and use test
+
+Install Julia by following the instructions at [julialang.org/downloads/](https://julialang.org/downloads/).
+
+To invoke Julia in the Terminal, you need to make sure that the `julia` command-line program is in your `PATH`. 
+See [here](https://julialang.org/downloads/platform/#optional_add_julia_to_path) for detailed instructions.
+
+We will now proceed to the installation of the `OrbitalElements` library.
+
+**Caution:** If you wish to exercise extra care to prevent any interference with other installed libraries (e.g., avoiding updates), please refer to the "Notes on working with environments" section below.
+
+Install the `OrbitalElements` library by running
+```
+julia -e 'using Pkg; Pkg.add(url="https://github.com/JuliaStellarDynamics/OrbitalElements.jl.git")'
+```
+
+An introduction example is given in `examples/test_OrbitalElements.jl`.
+Download the file by running:
+```
+wget https://raw.githubusercontent.com/JuliaStellarDynamics/OrbitalElements.jl/main/examples/test_OrbitalElements.jl
+```
+Then run the code with the following command
+```
+julia test_OrbitalElements.jl
+```
+
+This example will first install some required libraries (`Plots`, `LaTeXStrings`) and their dependencies. These installations might take up to 4 minutes. If it fails have a look at [known issues](#known-issues), open an issue or [contact us](#authors)
+
+The resulting plots will be created in the same folder as the test code under the names `IsochroneFrequencies.png`
+
+
+
+and `ForwardBackwardErrors.png`.
+
+
+
+---
+### Known issues
+
+- With julia versions < 1.9, ```Plots``` might fails to precompile due to ```FFMPEG``` and ```BinaryProvider```: ```Plots``` probably installed an old version of ```FFMPEG``` while newer are supported (```BinaryProvider``` is outdated). Force the update of ```FFMPEG``` and recompile by running:
+```
+julia -e 'using Pkg; Pkg.update("FFMPEG");Pkg.precompile();'
+```
+<sup><sub>*Do not forget the* `--project=/path/to/my_env` *option if you are running in a local environment.*</sub></sup>
+
+---
+### Note on working with environments
+
+By default, packages are added to the default environment at ~/.julia/environments/v1.#.
+It is however easy to create other, independent, projects.
+If you want to install the `OrbitalElements` package in a different/test environment, first create a folder to host the environment files (Project.toml and Manifest.toml which will be created later on).
+Then, for every command line invoking Julia, use `julia --project=/path/to/my_env` instead of `julia` alone.
+
+*Note that packages will always be cloned in ~/.julia/packages but only accessible in your project's context.* 
+*A procedure to fully uninstall the package is described at the end of this readme.*
+
+---
+### Interactive notebook
+
+If you prefer interactive Jupyter notebooks, you will need to install `IJulia` following these [instructions](https://github.com/JuliaLang/IJulia.jl).
+
+An interactive introduction example is then in examples/test_OrbitalElements.ipynb.
+
+---
+### Without installing Julia
+
+*If you do not want to install Julia but want to test the library, you can use this [Google colab notebook](https://colab.research.google.com/drive/1mCShKnyL9gIIuDhLsmvMJSO4F3JlSfSJ?usp=sharing).
+However, Google colab is not primarly made to run Julia code. 
+It will then need to be installed on the remote machine which can take a few minutes.
+This notebook is not maintained as a priority. We would recommend you install Julia on your machine to test the library locally.*
+
+---
+## Documentation and usage
+
+To get more familiar with the content of the library and start and design your own use case, you may want to visit the [documentation](https://juliastellardynamics.github.io/OrbitalElements.jl/).
+
+---
+## Uninstall
+
+First start by removing the package from the environment by running
+```
+julia -e 'using Pkg; Pkg.rm("OrbitalElements");'
+```
+
+Following the same syntax, you can also remove the `Plots` and `LaTeXString` packages installed for the example if you want to. 
+
+If you worked in a test environment (that you do not want to keep) you can also simply erase the folder using `rm -r /path/to/my_env`.
+
+Then to fully erase the package (installed in ~/.julia), run
+```
+julia -e 'using Pkg; using Dates; Pkg.gc(collect_delay=Day(0));'
+```
+<sup><sub>*No need for the* `--project=/path/to/my_env` *option here !*</sub></sup>
+
+It will erase all the packages which are not known in any of your "active" (i.e., for which the Manifest.toml file is reachable) project/environments, in particular `OrbitalElements`.
+
+---
+## Authors
+
+Mike Petersen -  [@michael-petersen](https://github.com/michael-petersen) - [email protected]
+
+Mathieu Roule -  [@MathieuRoule](https://github.com/MathieuRoule) - [email protected]
diff --git a/docs/src/manual.md b/docs/src/manual.md
@@ -0,0 +1,17 @@
+---
+# Potentials
+
+`OrbitalElements` ships with a handful of simple potential models for testing purposes. These are located in `src/Potential`: (1) the 3d Isochrone potential, (2) the 3d Plummer potential, (3) the 2d Mestel-Zang disc, and (4) the 2d Kuzmin-Toomre disc. Corresponding distribution functions are located in `src/DistributionFunctions`.
+
+---
+## Obtaining Orbital Frequencies
+
+The principal use for `OrbitalElements` is to provide descriptions of orbits. This means
+1. Conversion from (semimajor axis, eccentricity) to (pericentre, apocentre) to (energy, angular momentum), to coordinates aligned with resonance vectors.
+2. Additional support for actions and angles.
+
+`frequencies_from_ae(a,e,model,params)` will compute frequencies (Ω₁,Ω₂) given a potential model, for an orbit described by semimajor axis and eccentricity.
+
+---
+## Obtaining resonant coordinates
+`UVFromαβ(α,β,n₁,n₂,ωmin,ωmax)` will compute the resonant mappings (u,v) for a given frequency pair (α,β), resonance vector (n₁,n₂), and frequency limits.