From 42fc67d65a1e9b5896e789832794f7fa05f905f9 Mon Sep 17 00:00:00 2001 From: Jorge Martinez Date: Fri, 26 Jan 2024 18:35:00 +0100 Subject: [PATCH] doc: update to rst --- .../the_lamberts_problem.md | 0 doc/source/getting-started/how-to-install.rst | 30 ++++ .../getting-started/how_to_contribute.md | 58 ------- doc/source/getting-started/how_to_install.md | 35 ---- doc/source/getting-started/how_to_use.md | 159 ------------------ doc/source/getting-started/index.rst | 17 ++ doc/source/index.rst | 20 ++- doc/source/user-guide/index.rst | 17 ++ doc/source/user-guide/overview.rst | 143 ++++++++++++++++ 9 files changed, 225 insertions(+), 254 deletions(-) rename doc/source/{explanations => examples}/the_lamberts_problem.md (100%) create mode 100644 doc/source/getting-started/how-to-install.rst delete mode 100644 doc/source/getting-started/how_to_contribute.md delete mode 100644 doc/source/getting-started/how_to_install.md delete mode 100644 doc/source/getting-started/how_to_use.md create mode 100644 doc/source/getting-started/index.rst create mode 100644 doc/source/user-guide/index.rst create mode 100644 doc/source/user-guide/overview.rst diff --git a/doc/source/explanations/the_lamberts_problem.md b/doc/source/examples/the_lamberts_problem.md similarity index 100% rename from doc/source/explanations/the_lamberts_problem.md rename to doc/source/examples/the_lamberts_problem.md diff --git a/doc/source/getting-started/how-to-install.rst b/doc/source/getting-started/how-to-install.rst new file mode 100644 index 0000000..c702a58 --- /dev/null +++ b/doc/source/getting-started/how-to-install.rst @@ -0,0 +1,30 @@ +How to install +============== + +This page contains the guide for installing the ``lamberthub`` package. If you +experience any kind of problem during one of the steps shown in the following +lines, please open an new issue (or select similar ones) in the `issues +board `_ + +Installing from PyPI +-------------------- + +The installation process is similar to other python packages, meaning that you +only need to run: + +.. code-block:: bash + + python -m pip install lamberthub + +Previous command installs the latest stable version of the library. Once +done, you can open the Python terminal and import the package and verify its +version by running: + +.. code-block:: python + + import lamberthub + print(f"lamberthub v{lamberthub.__version__}") + +.. code-block:: python + + lamberthub v|version| diff --git a/doc/source/getting-started/how_to_contribute.md b/doc/source/getting-started/how_to_contribute.md deleted file mode 100644 index f76c258..0000000 --- a/doc/source/getting-started/how_to_contribute.md +++ /dev/null @@ -1,58 +0,0 @@ -# How to contribute - -Main way of contributing to the library is through its usage and maintenance. -When doing so, it is possible for new issues or even bugs to appear. Those are -listed in the [official issues -board](https://github.com/jorgepiloto/lamberthub/issues). - - -## Developer installation - -Previous situation requires for user to have `lamberthub` installed in developer -mode, so modifications can be applied to original source code. To install as -*developer*, please follow these steps: - -Start by making a fork of the [official -repository](https://github.com/jorgepiloto/lamberthub) into your local machine -by running: - -```bash -git clone https://github.com/your_github_username/lamberthub && cd lamberthub -``` - -Next, you must create a Python virtual environment, so the library dependencies -do not interfere with your system environment: - -```bash -python -m venv .venv && source .venv/bin/activate -``` - -Check your current Python binary is the one hosted in the virtual environment by -running: - -```bash -which python -``` - -which must retrieve the absolute path of the previously created virtual -environment: - -```bash -/lamberthub/.venv/bin/python -``` - -Now, update `pip`: - -```bash -python -m pip install -U pip -``` - -Finally, install `lamberthub` in development mode: - -```bash -python -m pip install --editable . -``` - -which tells your Python environment that the `lamberthub` package is located in -this actual folder. **Now, any change you apply to source code affects the -behavior of the library**. diff --git a/doc/source/getting-started/how_to_install.md b/doc/source/getting-started/how_to_install.md deleted file mode 100644 index f2dd54f..0000000 --- a/doc/source/getting-started/how_to_install.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -jupytext: - text_representation: - extension: .md - format_name: myst -kernelspec: - display_name: Python 3 - language: python - name: python3 ---- - -# How to install - -This page contains the guide for installing the `lamberthub` package. If you -experience any kind of problem during one of the steps shown in the following -lines, please open an new issue (or select similar ones) in the [issues -board](https://github.com/jorgepiloto/lamberthub/issues). - -## Install from PyPI using pip - -The installation process is similar to other python packages, meaning that you -only need to run: - -```bash -pip install lamberthub -``` - -previous command installs the latest stable version of the library. Once -done, you can open the Python terminal and import the package and verify its -version by running: - -```{code-cell} ipython3 -import lamberthub -print(f"Current lamberthub version is {lamberthub.__version__}") -``` diff --git a/doc/source/getting-started/how_to_use.md b/doc/source/getting-started/how_to_use.md deleted file mode 100644 index fb566e3..0000000 --- a/doc/source/getting-started/how_to_use.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -jupytext: - text_representation: - extension: .md - format_name: myst -kernelspec: - display_name: Python 3 - language: python - name: python3 ---- - -# How to use - -Once that you have installed the library, its time for you to learn how to use -it. The main goal of `lamberthub` is very simple: provide a collection of -algorithms for solving the Lambert's problem. - -All the routines are implemented in the form of Python functions, who's name is -given by the combination of original author's name plus the year of publication, -that is: `authorYYYY`. - -## Checking for available solvers - -To answer this question, simply run the following code snippet or refer to the -official package API reference: - -```{code-cell} -from lamberthub import ALL_SOLVERS -print([solver.__name__ for solver in ALL_SOLVERS]) -``` - -In addition, `lamberthub` provides other lists holding algorithms which -present particular features such as multi-revolutions or high-robustness. These -macros are listed down: - -```{code-cell} -from lamberthub import ALL_SOLVERS, ZERO_REV_SOLVERS, MULTI_REV_SOLVERS, ROBUST_SOLVERS -``` - -## Import a particular solver - -If you are only interested in using a particular solver, you can easily import -it by running: - -```python -from lamberthub import authorYYYY -``` - -where `author` is the name of the author which developed the solver and `YYYY` -the year of publication. Any of the solvers hosted in the `ALL_SOLVERS` macro -can be used. - -If you would like to use a solver which is not defined in `lamberthub`, open a -`solver request` in the [issues -board](https://github.com/jorgepiloto/lamberthub/issues) detailing all the -information related to the algorithm and any useful reference which can help to -implement it. - -## Input and output parameters - -Any of the routines in the library has the same number of input and output -parameters, that is because they all solve for the same astrodynamics problem. - -As said before, any Lambert's problem algorithm implemented in `lamberthub` is a -Python function built with the following API architecture: - -**Parameters** -* `mu`: the gravitational parameter, that is the mass of the attracting body - times the gravitational constant. -* `r1`: initial position vector, needs to be a NumPy array instance. -* `r2`: final position vector, needs to be a NumPy array instance. -* `tof`: time of flight between initial and final vectors. - -**Additional parameters** -* `M`: the number of desired revolutions. If zero, direct transfer is assumed. -* `prograde`: this parameter controls the inclination of the final orbit. If set - to `True`, the transfer has an inclination between 0 and 90 degrees - while if `False` inclinations between 90 and 180 are provided. -* `low_path`: selects the type of path when more than two solutions are available. - There is no actual advantage on one or another solution, unless you have - particular constrains on your mission. If `True`, the maximum value for the - independent variable (when two solutions) is selected. -* `maxiter`: maximum number of iterations allowed when computing the solution. -* `atol`: absolute tolerance for the iterative method. -* `rtol`: relative tolerance for the iterative method. -* `full_output`: if `True`, it returns additional information such as the number - of iterations. - -**Returns** -* `v1`: initial velocity vector, it is a NumPy array instance. -* `v2`: final velocity vector, it is a NumPy array instance. - -**Additional returns** -* `numiter`: number of iterations. Only of `full_output` has been set to `True`. -* `tpi`: time per iteration. Only if `full_output` has been set to `True`. - - -## A real example - -The following section presents a real example[^1]. Suppose you want to solve for -the orbit of an interplanetary vehicle (that is Sun is the main attractor) form -which you know that the initial and final positions are given by: - -$$ -\vec{r_1} = \begin{bmatrix} -0.159321004\\ -0.579266185\\ -0.052359607\\ -\end{bmatrix} \text{[AU]}\;\;\;\;\;\; -\vec{r_2} = \begin{bmatrix} -0.057594337\\ -0.605750797\\ -0.068345246\\ -\end{bmatrix} \text{[AU]} -$$ - -the dimension of previous vectors is astronomical units [AU] and the time of -flight, given in years, is known to be $\Delta t = 0.010794065 \text{[year]}$. -The orbit is prograde since inclination is less than $90^{\circ}$) and -direct $M=0$. Remember that when $M=0$, there is only one possible solution, so -the `low_path` flag does not play any role in this problem. - -To solve for the problem, first import a solver. For this problem, -`gooding1990` is chosen: - -```{code-cell} -from lamberthub import gooding1990 -``` - -Next, specify the initial conditions of the problem: - -```{code-cell} -# Import NumPy for declaring position vectors -import numpy as np - -# Initial conditions for the problem -mu_sun = 39.47692641 # [AU ** 3 / year ** 2] -r1 = np.array([0.159321004, 0.579266185, 0.052359607]) # [AU] -r2 = np.array([0.057594337, 0.605750797, 0.068345246]) # [AU] -tof = 0.010794065 # [year] -``` - -Finally, the problem can be solved. Notice that, as explained before, the -default value for the `prograde` flag is `True`, which matches the one from -problem's statement. - -```{code-cell} -# Solving the problem -v1, v2 = gooding1990(mu_sun, r1, r2, tof) - -# Let us print the results -print(f"Initial velocity: {v1} [AU / years]\nFinal velocity: {v2} [AU / years]") -``` - -previous values are the same ones coming from the original example. - -[^1]: Directly taken from *An Introduction to the Mathematics and Methods of - Astrodynamics, revised edition*, by R.H. Battin, problem 7-12. - diff --git a/doc/source/getting-started/index.rst b/doc/source/getting-started/index.rst new file mode 100644 index 0000000..7ffe35f --- /dev/null +++ b/doc/source/getting-started/index.rst @@ -0,0 +1,17 @@ +Getting started +############### + +.. grid:: 1 + + .. grid-item-card:: Installation :fa:`person-running` + :link: getting-started/index + :link-type: doc + + Step by step guidelines on how to set up your environment to work with + lamberthub. Install the library and verify it works as expected. + +.. toctree:: + :hidden: + :maxdepth: 3 + + how-to-install diff --git a/doc/source/index.rst b/doc/source/index.rst index 5659277..2d2c200 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -8,6 +8,22 @@ different algorithms for solving the Lambert's problem: :width: 350px :align: center +.. grid:: 2 + + .. grid-item-card:: Getting started :fa:`person-running` + :link: getting-started/index + :link-type: doc + + Step by step guidelines on how to set up your environment to work with + lamberthub. Install the library and verify it works as expected. + + .. grid-item-card:: User guide :fa:`book-open-reader` + :link: user-guide/index + :link-type: doc + + Learn about the capabilities, features, and key topics in lamberthub. + This guide provides useful background information and explanations. + Since the formulation of the problem, many different solutions have been devised, being the latest ones in the form of computer routines. By collecting and implementing all of them under a common programming language, it is possible @@ -21,8 +37,8 @@ their routines. :hidden: :maxdepth: 3 - getting_started/index - user_guide/index + getting-started/index + user-guide/index {% if build_examples %} examples {% endif %} diff --git a/doc/source/user-guide/index.rst b/doc/source/user-guide/index.rst new file mode 100644 index 0000000..304db6d --- /dev/null +++ b/doc/source/user-guide/index.rst @@ -0,0 +1,17 @@ +User guide +########## + +.. grid:: 1 + + .. grid-item-card:: Overview :fa:`person-running` + :link: getting-started/index + :link-type: doc + + Step by step guidelines on how to use lamberthub. + + +.. toctree:: + :hidden: + :maxdepth: 3 + + overview diff --git a/doc/source/user-guide/overview.rst b/doc/source/user-guide/overview.rst new file mode 100644 index 0000000..65cedd6 --- /dev/null +++ b/doc/source/user-guide/overview.rst @@ -0,0 +1,143 @@ +Overview +======== + +Once you have installed the library, it's time to learn how to use it. The main +goal of ``lamberthub`` is very simple: provide a collection of algorithms for +solving Lambert's problem. + +All the routines are implemented in the form of Python functions, whose name is +given by the combination of the original author's name plus the year of +publication, that is: ``authorYYYY``. + +Checking for available solvers +------------------------------ + +To answer this question, simply run the following code snippet or refer to the +official package API reference: + +.. jupyter-execute:: + + from lamberthub import ALL_SOLVERS + print([solver.__name__ for solver in ALL_SOLVERS]) + +In addition, ``lamberthub`` provides other lists holding algorithms which +present particular features such as multi-revolutions or high-robustness. These +macros are listed down: + +.. jupyter-execute:: + + from lamberthub import ALL_SOLVERS, ZERO_REV_SOLVERS, MULTI_REV_SOLVERS, ROBUST_SOLVERS + +Import a particular solver +-------------------------- + +If you are only interested in using a particular solver, you can easily import +it by running: + +.. code-block:: python + + from lamberthub import authorYYYY + +Where ``author`` is the name of the author who developed the solver and ``YYYY`` +is the year of publication. Any of the solvers hosted in the ``ALL_SOLVERS`` +macro can be used. + +If you would like to use a solver which is not defined in ``lamberthub``, open a +``solver request`` in the ``issues board`` detailing all the information related +to the algorithm and any useful reference which can help to implement it. + +Input and output parameters +--------------------------- + +Any of the routines in the library has the same number of input and output +parameters because they all solve the same astrodynamics problem. + +As said before, any Lambert's problem algorithm implemented in ``lamberthub`` is +a Python function built with the following API architecture: + +**Parameters** + +- `mu`: the gravitational parameter, that is the mass of the attracting body times the gravitational constant. +- `r1`: initial position vector, needs to be a NumPy array instance. +- `r2`: final position vector, needs to be a NumPy array instance. +- `tof`: time of flight between initial and final vectors. + +**Additional parameters** + +- `M`: the number of desired revolutions. If zero, direct transfer is assumed. + +- `prograde`: this parameter controls the inclination of the final orbit. If set + to `True`, the transfer has an inclination between 0 and 90 degrees while if + `False` inclinations between 90 and 180 are provided. + +- `low_path`: selects the type of path when more than two solutions are + available. There is no actual advantage on one or another solution, unless you + have particular constrains on your mission. If `True`, the maximum value for + the independent variable (when two solutions) is selected. + +- `maxiter`: maximum number of iterations allowed when computing the solution. + +- `atol`: absolute tolerance for the iterative method. + +- `rtol`: relative tolerance for the iterative method. + +- `full_output`: if `True`, it returns additional information such as the number + of iterations. + +**Returns** + +- `v1`: initial velocity vector, it is a NumPy array instance. + +- `v2`: final velocity vector, it is a NumPy array instance. + +**Additional returns** + +- `numiter`: number of iterations. Only if `full_output` has been set to `True`. + +- `tpi`: time per iteration. Only if `full_output` has been set to `True`. + +A real example +-------------- + +The following section presents a real example[^1]. Suppose you want to solve for +the orbit of an interplanetary vehicle (that is the Sun is the main attractor) +for which you know that the initial and final positions are given by: + +.. math:: + + \vec{r_1} = \begin{bmatrix} 0.159321004 \\ 0.579266185 \\ 0.052359607 \end{bmatrix} \text{[AU]}\;\;\;\;\;\; + \vec{r_2} = \begin{bmatrix} 0.057594337 \\ 0.605750797 \\ 0.068345246 \end{bmatrix} \text{[AU]} + +The dimension of previous vectors is astronomical units [AU], and the time of +flight, given in years, is known to be $\Delta t = 0.010794065 \text{[year]}$. +The orbit is prograde since the inclination is less than $90^{\circ}$, and +direct $M=0$. Remember that when $M=0$, there is only one possible solution, so +the ``low_path`` flag does not play any role in this problem. + +To solve the problem, first import a solver. For this problem, ``gooding1990`` is +chosen: + +.. code-block:: python + + from lamberthub import gooding1990 + import numpy as np + + + # Initial conditions for the problem + mu_sun = 39.47692641 # [AU ** 3 / year ** 2] + r1 = np.array([0.159321004, 0.579266185, 0.052359607]) # [AU] + r2 = np.array([0.057594337, 0.605750797, 0.068345246]) # [AU] + tof = 0.010794065 # [year] + + # Solve the problem using Gooding's 1990 algorithm + v1, v2 = gooding1990(mu_sun, r1, r2, tof) + + # Print the results + print(f"Initial velocity: {v1} [AU / years]\nFinal velocity: {v2} [AU / years]") + +.. code-block:: pycon + + Initial velocity: [-9.303608 3.01862016 1.53636008] [AU / years] + Final velocity: [-9.5111862 1.88884006 1.4213781 ] [AU / years] + +Previous values are the same ones stated in original example.