diff --git a/README.md b/README.md index a236c5f..8da9ee3 100644 --- a/README.md +++ b/README.md @@ -15,40 +15,40 @@ A collection of Lambert's problem solvers implemented using modern Python. **Install the latest stable release by running:** ```bash -pip install lamberthub +python -m pip install lamberthub ``` -Just in case you are interested on knowing what the problem is about, how to -solve it or which applications it has, please check the [official lamberthub -documentation]. For further information about software internals, refer to [API -documentation]. +## Available solvers - -## Which solvers are available? - -Once installed, you can start by checking which solvers `lamberthub` ships with -by running: +Verify available solvers by running: ```python from lamberthub import ALL_SOLVERS + + print([solver.__name__ for solver in ALL_SOLVERS]) ``` -At this moment, the following algorithms are available: - -```bash ->>> ['gauss1809', 'battin1984', 'gooding1990', 'avanzini2008', 'arora2013', 'vallado2013', 'izzo2015'] +```pycon +>>> [ + 'gauss1809', 'battin1984', 'gooding1990', 'avanzini2008', 'arora2013', + 'vallado2013', 'izzo2015' +] ``` -## How can I use a solver? +## Using a solver Any Lambert's problem algorithm implemented in `lamberthub` is a Python function which accepts the following parameters: ```python -# Import a solver of your choice from the ones listed above from lamberthub import authorYYYY -v1, v2 = authorYYYY(mu, r1, r2, tof, prograde=True, low_path=True, maxiter=35, atol=1e-5, rtol=1e-7, full_output=False) + + +v1, v2 = authorYYYY( + mu, r1, r2, tof, M, prograde=True, low_path=True, maxiter=35, + atol=1e-5, rtol=1e-7, full_output=False +) ``` where `author` is the name of the author which developed the solver and `YYYY` @@ -56,24 +56,24 @@ the year of publication. Any of the solvers hosted by the `ALL_SOLVERS` macro can be used. **Parameters** -* `mu`: the gravitational parameter, that is the mass of the attracting body - times the gravitational constant. -* `r1`: initial position vector. -* `r2`: final position vector. -* `tof`: time of flight between initial and final vectors. +- `mu`: the gravitational parameter, that is the mass of the attracting body +- times the gravitational constant. +- `r1`: initial position vector. +- `r2`: final position vector. +- `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 will have 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. -* `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 us the number +- `M`: the number of revolutions. If zero (default), direct transfer is assumed. +- `prograde`: this parameter controls the inclination of the final orbit. If set +- to `True`, the transfer will have 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. +- `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 us the number of iterations. **Returns** @@ -83,19 +83,3 @@ can be used. **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`. - -## Documentation and performance comparison tools - -The [official lamberthub documentation] contains different how-to guides, -explanations, tutorials and references related to the package. - -If you are interested in the performance comparison tools provided, please refer -to [performance comparison section]. Here you can find a brief tutorials on how -to use those tools. - - - - -[official lamberthub documentation]: https://jorgemartinez.space/projects/lamberthub/index.html -[API documentation]: https://jorgemartinez.space/projects/lamberthub/autoapi/lamberthub/index.html -[performance comparison section]: https://jorgemartinez.space/projects/lamberthub/explanations/performance_comparison.html diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index aabdf4d..0000000 --- a/doc/Makefile +++ /dev/null @@ -1,186 +0,0 @@ -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -SRCDIR = source -EXAMPLESDIR = tutorials -BUILDDIR = _build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR) -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR) - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " examples to make Jupyter notebook examples from *.md" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* $(SRCDIR)/$(EXAMPLESDIR)/*.ipynb - -examples: - @echo "Building Jupyter notebook examples..." - cd $(SRCDIR)/$(EXAMPLESDIR) && jupytext --to ipynb --execute *.mystnb - @echo "Finished!" - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/lamberthub.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/lamberthub.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/lamberthub" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/lamberthub" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." - -pdf: - mkdir -p $(BUILDDIR)/latex - touch $(BUILDDIR)/latex/documentation.pdf diff --git a/doc/source/_autoapi_templates/index.rst b/doc/source/_autoapi_templates/index.rst deleted file mode 100644 index 594cabf..0000000 --- a/doc/source/_autoapi_templates/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -:noindex: -:orphan: - -Package API -=========== - -This section holds `lamberthub's` source code documentation. You can navigate -through each of of the sub-packages and modules they contain to check the -different auxiliary routines and parameters they accept. - -.. toctree:: - :maxdepth: 2 - - {% for page in pages %} - {% if page.top_level_object and page.display %} - {{ page.include_path }} - {% endif %} - {% endfor %} diff --git a/doc/source/_autoapi_templates/python/module.rst b/doc/source/_autoapi_templates/python/module.rst deleted file mode 100644 index cfc1974..0000000 --- a/doc/source/_autoapi_templates/python/module.rst +++ /dev/null @@ -1,109 +0,0 @@ -{% if not obj.display %} -:orphan: - -{% endif %} -:mod:`{{ obj.name }}` -======={{ "=" * obj.name|length }} - -.. py:module:: {{ obj.name }} - :noindex: - -{% if obj.docstring %} -.. autoapi-nested-parse:: - - {{ obj.docstring|prepare_docstring|indent(3) }} - -{% endif %} - -{% block subpackages %} -{% set visible_subpackages = obj.subpackages|selectattr("display")|list %} -{% if visible_subpackages %} -Subpackages ------------ - -.. toctree:: - :titlesonly: - :maxdepth: 3 - -{% for subpackage in visible_subpackages %} - - {{ subpackage.short_name }}/index.rst - -{% endfor %} - - -{% endif %} -{% endblock %} -{% block submodules %} -{% set visible_submodules = obj.submodules|selectattr("display")|list %} -{% if visible_submodules %} -Submodules ----------- - -.. toctree:: - :titlesonly: - :maxdepth: 1 - -{% for submodule in visible_submodules %} - - {{ submodule.short_name }}/index.rst - -{% endfor %} - - -{% endif %} -{% endblock %} -{% block content %} -{% if obj.all is not none %} -{% set visible_children = obj.children|selectattr("short_name", "in", obj.all)|list %} -{% elif obj.type is equalto("package") %} -{% set visible_children = obj.children|selectattr("display")|list %} -{% else %} -{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %} -{% endif %} -{% if visible_children %} -{{ obj.type|title }} Contents -{{ "-" * obj.type|length }}--------- - -{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %} -{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %} -{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %} -{% block classes scoped %} -{% if visible_classes %} -Classes -~~~~~~~ - -.. autoapisummary:: - -{% for klass in visible_classes %} - - {{ klass.id }} - -{% endfor %} - - -{% endif %} -{% endblock %} - -{% block functions scoped %} -{% if visible_functions %} -Functions -~~~~~~~~~ - -.. autoapisummary:: - -{% for function in visible_functions %} - - {{ function.id }} - -{% endfor %} - - -{% endif %} -{% endblock %} -{% endif %} -{% for obj_item in visible_children %} -{{ obj_item.rendered|indent(0) }} -{% endfor %} -{% endif %} -{% endblock %} diff --git a/doc/source/conf.py b/doc/source/conf.py deleted file mode 100644 index 10439a3..0000000 --- a/doc/source/conf.py +++ /dev/null @@ -1,82 +0,0 @@ -"""Sphinx configuration file.""" - -from datetime import datetime -import os - -from ansys_sphinx_theme import get_version_match - -import lamberthub - -# Project information -project = lamberthub.__name__ -copyright = ( - f"(c) {datetime.now().year} Jorge Martinez Garrido. All rights reserved" -) -author = lamberthub.__author__ -release = version = lamberthub.__version__ -cname = os.getenv("DOCUMENTATION_CNAME", "lamberthub.docs.jorgemartinez.space") - - -# Extensions and source file configuration -extensions = [ - "autoapi.extension", - "myst_nb", - "nbsphinx", - "sphinx.ext.autodoc", - "sphinx.ext.napoleon", - "sphinx_gallery.load_style", -] - -source_suffix = { - ".rst": "restructuredtext", - ".ipynb": "myst-nb", - ".myst": "myst-nb", -} - -master_doc = "index" -templates_path = ["_templates"] -exclude_patterns = [] - - -# HTML theme configuration -html_theme = "ansys_sphinx_theme" -html_short_title = html_title = project -html_context = { - "github_user": "lamberthub", - "github_repo": "lamberthub", - "github_version": "main", - "doc_path": "doc/source", -} -html_theme_options = { - "github_url": "https://github.com/lamberthub/lamberthub", - "contact_mail": "contact@jorgemartinez.space", - "additional_breadcrumbs": [ - ("Jorge's Website", "https://jorgemartinez.space"), - ], - "switcher": { - "json_url": f"https://{cname}/versions.json", - "version_match": get_version_match(version), - }, - "check_switcher": False, -} -html_static_path = ["_static"] -html_css_files = ["custom.css"] - - -# Autoapi configuration -autoapi_type = "python" -autoapi_dirs = ["../../src"] -autodoc_typehints = "none" -autoapi_template_dir = "_autoapi_templates" -exclude_patterns.append("_autoapi_templates/index.rst") -exclude_patterns.append("_autoapi_templates/python/module.rst") - -# Nbsphinx configuration -nbsphinx_custom_formats = { - ".mystnb": ["jupytext.reads", {"fmt": "mystnb"}], -} -nbsphinx_thumbnails = { - "tutorials/gauss1809_solver": "_static/tutorials/gauss_thumbnail.png" -} -nb_execution_timeout = 900 -myst_update_mathjax = False diff --git a/doc/source/explanations/the_lamberts_problem.md b/doc/source/explanations/the_lamberts_problem.md deleted file mode 100644 index 502a2b3..0000000 --- a/doc/source/explanations/the_lamberts_problem.md +++ /dev/null @@ -1,25 +0,0 @@ - -# The Lambert's problem - - -The Lambert's problem is the boundary value problem of the two-body problem -under the framework of astrodynamics. - -## Problem statement - -The goal is to solve for the orbit of a body being known two of its position -vectors $\vec{r_1}$ and $\vec{r_2}$, and the time it takes to travel between -those, usually denoted by $\Delta t$. The geometry of the problem is shown in -the figure below: - -```{figure} ../_static/lamberts_problem_geometry.png ---- -width: 350px -align: center ---- -``` - -Because the problem states to find an orbit, it is usually included within the -*Initial Orbit Determination* subject. Nevertheless, Lambert's problem solution -has applications in the field of interplanetary maneuvers and orbital rendezvous -too. diff --git a/doc/source/how_to_guides/how_to_contribute.md b/doc/source/how_to_guides/how_to_contribute.md deleted file mode 100644 index f76c258..0000000 --- a/doc/source/how_to_guides/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/how_to_guides/how_to_install.md b/doc/source/how_to_guides/how_to_install.md deleted file mode 100644 index f2dd54f..0000000 --- a/doc/source/how_to_guides/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/how_to_guides/how_to_use.md b/doc/source/how_to_guides/how_to_use.md deleted file mode 100644 index fb566e3..0000000 --- a/doc/source/how_to_guides/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/index.md b/doc/source/index.md deleted file mode 100644 index 320f47f..0000000 --- a/doc/source/index.md +++ /dev/null @@ -1,47 +0,0 @@ -# Welcome to lamberthub documentation - -The `lamberthub` library is a Python package which provides its users with -different algorithms for solving the Lambert's problem: - -```{figure} _static/lamberts_problem_geometry.png ---- -width: 350px -align: center ---- -``` - -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 -to carry out performance comparisons between those. Furthermore, `lamberthub` -provides a framework for new authors to select the robustness and accuracy of -their routines. - - -```{toctree} ---- -maxdepth: 2 -caption: Getting started ---- -how_to_guides/how_to_install.md -how_to_guides/how_to_use.md -how_to_guides/how_to_contribute.md -``` - -```{toctree} ---- -maxdepth: 2 -caption: Explanations ---- -explanations/the_lamberts_problem.md -``` - -```{toctree} ---- -maxdepth: 2 -caption: References ---- -references/about -autoapi/index.rst -references/references.md -``` diff --git a/doc/source/references/about.md b/doc/source/references/about.md deleted file mode 100644 index 23e9ab8..0000000 --- a/doc/source/references/about.md +++ /dev/null @@ -1,51 +0,0 @@ -# About lamberthub - -## Origins of the library - -The library was born as a result of a performance comparison study between -different Lambert's problem solvers. The preliminary results were published in -the [8th International Conference on Astrodynamics Tools and -Techniques](https://atpi.eventsair.com/QuickEventWebsitePortal/20a05-gnc-2020/website). -The report, titled [A critical review on the state-of-the-art of Lambert's -problem -solvers](https://github.com/jorgepiloto/lamberthub/tree/main/art/icatt_report.pdf) -is fully accessible. - -The performance comparison work was completed and published by October 2021 as -part of the author's final thesis in aerospace engineering. You can download -this document using the following link: - -
- - Lambert's problem algorithms: a critical review - -
- -## Objectives and goals - -* To **collect all proposed solutions to the Lambert's problem and implement** those - under a common programming language, so no undesired performance is introduced - because of software. - -

- -* To **provide open source scientific software**, so all the **results can be - reproduced by third parties and individuals**. - -

- -* To act as a **Lambert's problem algorithms vault**, preserving the knowledge behind - this great problem and in particular, the very first proposed numerical - solvers, playing the role of software archaeology. - -

- -* To **review Lambert's problem bibliography** to establish which - authors have addressed the problem and when they did so. - - -## License - -The software is released under [the following open source -license](https://github.com/jorgepiloto/lamberthub/blob/main/LICENSE). - diff --git a/doc/source/references/references.md b/doc/source/references/references.md deleted file mode 100644 index 82e28b1..0000000 --- a/doc/source/references/references.md +++ /dev/null @@ -1,22 +0,0 @@ -# Articles and similar software - - -## Articles - -## Similar software - -The `lamberthub` library only provides routines for solving the Lambert's -problem. However, there exist other software packages which offer additional -capabilities on astronomy, astrodynamics, and orbital mechanics. This page -lists some of the most popular ones available for the Python community: - -* **[astropy](https://www.astropy.org/)**: The Astropy Project is a community - effort to develop a common core package for Astronomy in Python and foster an - ecosystem of interoperable astronomy packages. - -

- -* **[poliastro](https://docs.poliastro.space/en/latest/)**: poliastro is an open - source (MIT) collection of Python functions useful in Astrodynamics and - Orbital Mechanics, focusing on interplanetary applications. It provides a - simple and intuitive API and handles physical quantities with units. diff --git a/pyproject.toml b/pyproject.toml index 3f300c7..a813f7f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -44,17 +44,6 @@ tests = [ "pytest==7.2.0", "pytest-cov==4.0.0", ] -doc = [ - "ansys-sphinx-theme>=0.9", - "jupytext==1.14.1", - "myst-nb==0.17.1", - "nbsphinx==0.8.10", - "notebook==6.5.2", - "sphinx==5.3.0", - "sphinx-autoapi==2.0.0", - "sphinx-gallery==0.11.1", -] - [project.urls] Source = "https://github.com/lamberthub/lamberthub" diff --git a/tox.ini b/tox.ini index b01d8a7..3cb445f 100644 --- a/tox.ini +++ b/tox.ini @@ -1,7 +1,7 @@ [tox] description = Default tox environments list envlist = - style,{py38,py39,py310}{,-cov},doc + style,{tests}{,-cov},doc-{links,html} skip_missing_interpreters = true isolated_build = true isolated_build_env = build @@ -9,11 +9,7 @@ isolated_build_env = build [testenv] description = Checks for project unit tests and coverage (if desired) basepython = - py38: python3.8 - py39: python3.9 - py310: python3.10 - py: python3 - {style,reformat,doc,build}: python3 + {style,tests,doc}: python3 setenv = PYTHONUNBUFFERED = yes cov: PYTEST_EXTRA_ARGS = --cov=lamberthub --cov-report=term --cov-report=xml --cov-report=html @@ -29,10 +25,3 @@ deps = commands = pre-commit install pre-commit run --all-files --show-diff-on-failure - -[testenv:doc] -description = Check if documentation generates properly -allowlist_externals=* -extras = doc -commands = - sphinx-build -d "{toxworkdir}/doc_doctree" doc/source "{toxinidir}/doc/_build/html" --color -vW -bhtml