💻 Feature request: developer's guide

The current developer's guide only provides information on how to setup the development environment.

However, there are several things which might be useful to document:

• The type of naming convention we follow in the project, same as Python one
• The git branch naming convection: branches must be named like issue_label/single_word to better track those.

If you find require from any additional style-guide convention, please suggest it within the comments sections below.

💻 Solver request: avanzini2008

The algorithm developed by Avanzini in 2008 is the first of its class. It exploits the fact that projection of the eccentricity vector along the chord line is constant no matter the transfer orbit. By setting the limits for the transverse eccentricity value, it is possible to solve Kepler's equation (taking into account the type of orbit) and check if the time of transfer matches the desired one. This is the main workflow carried out by this algorithm.

Only drawbacks are that Avanzini did not provide the derivative of Kepler's equation w.r.t. the transverse eccentricity component, and thus, a step integration technique is required. This can be solved using the scipy.optimize.newton, which applies the secant method if no fprime is provided.

This algorithm must be included within the SINGLE_REV_SOLVERS, as original author did not extended it up to that particular case.

📝 References

This is a modern article, being its BibTeX the following one:

@article{avanzini2008simple,
  title={A simple Lambert algorithm},
  author={Avanzini, Giulio},
  journal={Journal of guidance, control, and dynamics},
  volume={31},
  number={6},
  pages={1587--1594},
  year={2008}
}

💻 Feature request: replace assertions by custom exceptions

In most of the solvers, different assertions regarding the validity of the parameters, the convergence to a given accuracy and others are executed. Assertions should only be applied within the tests/ directory. Instead, we must create custom exceptions and raise those, for example: IterationsError, AtolError, RevolutionsError, RtolError, InputError, TransferAngleError.

📝 References

This talks by Mario Corchero titled "Exceptional Exceptions" will be super useful!

1. https://www.youtube.com/watch?v=f3UoZU3hK-c
2. https://www.youtube.com/watch?v=V2fGAv2R5j8

The Journal of Open Source Software (JOSS) is an academic journal (ISSN 2475-9066) with a formal peer review process that is designed to improve the quality of the software submitted. Upon acceptance into JOSS, a Crossref DOI is minted and we list your paper on the JOSS website.

https://joss.theoj.org/papers/new

Example of an ongoing review I'm participating in: openjournals/joss-reviews#3710

💻 Solver request: der2011

The original algorithm devised by Der makes use of a universal free-parameter, with rational formulae for the initial guess, and the Laguerre method as the root solver. The velocity vectors construction exploits a radial + chord-wise construction.

The majority of the current test-suite cases comes from this paper, although for some reason I never ended up implementing this solver...

The original paper can be downloaded from here. The steps to solve for the problem are listed down.

📝 References

@article{der2011superior,
  title={The superior Lambert algorithm},
  author={Der, Gim J},
  journal={AMOS, Maui, Hawaii},
  year={2011}
}

Preparing the release

• Rerun all notebooks (pay special attention to new features)
• Review documentation, optionally improving the user guide or adding new notebooks showcasing new functionality
• Write the changelog and list of contributors

Before the beta release

• New branch
• Bump version to 0.2b1 in:
  • README.md
  • __init__.py
• Check all the badges in README point to the appropriate git branch (replace main by new branch sed -i 's/main/.../g' README.md)
• Check that docs badges and URLs point to appropriate tag (replace latest by new tag, without sed!)
• git commit -m 'Bump to next beta version'
• Generate sdist and bdist_wheel with python -m build
• twine upload dist/* --repository-url https://test.pypi.org/legacy/
• Tag
• Bump master to next development version

Beta release

• Push branch to GitHub and tags
• Check on Test PyPI that the badges will work
• Upload sdist and bdist_wheel to PyPI - this step cannot be undone if the release is removed! twine upload dist/* --repository-url https://upload.pypi.org/legacy/
• Check Read the Docs

Before final release

• Backport any bugs
• Update release date in changelog
• Bump version to 0.2 in:
  • README.md
  • __init__.py
  • Sphinx conf.py
• Check that docs badges and URLs point to appropriate tag (replace v0.2b1 by v0.2)
• Commit
• Generate sdist and bdist_wheel
• twine upload dist/* --repository-url https://test.pypi.org/legacy/
• Tag

Final release

• Push tag to GitHub
• Upload sdist and bdist_wheel to PyPI - this step cannot be undone if the release is removed! twine upload dist/* --repository-url https://upload.pypi.org/legacy/
• Check Read the Docs
• Create GitHub release
• Add Zenodo badge to GitHub release
• Send announcement email with subject "ANN: lamberthub 0.2 released 🚀"
• Cherry pick release date to master
• Close milestone

💻 Solver request: jiang2016

This algorithm iterates over the semi-major axis of the orbit. To be honest, I do not see why this is considered to be a "new algorithm"... In fact, it looks exactly the same as Lagrange's solution to the Lambert's problem. Anyway, because this algorithm is easy to implement, let us add it to the library.

📝 References

@inproceedings{jiang2016improved,
  title={Improved semi-major Axis iterated method for Lambert's problem},
  author={Jiang, Ruiye and Chao, Tao and Wang, Songyan and Yang, Ming},
  booktitle={2016 IEEE Chinese Guidance, Navigation and Control Conference (CGNCC)},
  pages={1423--1428},
  year={2016},
  organization={IEEE}
}

💻 Solver request: arora2013

Just a few years ago, Arora implemented a new solver in 2013 based on the Work made by Bate. This algorithm makes use of the universal-formuale, so it should be included within this particular sub-package, in its corresponding module. The algorithm is a complete one, meaning that it can operate in the multi-revolution scenario and is considered to be a robust one.

📝 References

The BibTeX code is shown below:

@article{arora2013fast,
  title={A fast and robust multiple revolution Lambert algorithm using a cosine transformation},
  author={Arora, Nitin and Russell, Ryan P},
  journal={Paper AAS},
  volume={13},
  pages={728},
  year={2013},
  publisher={Citeseer}
}

💻 Feature request: Numba acceleration

What else can be said? At the moment, the package does not provide a Numba accelerated code because although useful, it can become tricky for particular type sets and a very quick development was required for version 0.1. Anyway, hope this to change in the next version, 0.2.

💻 Feature request: iterations performance plotter

This is supposed to solve for one of the goals of the library, that is, provide a tool to measure solvers' performance. The idea is as follows: a contour map showing the number of iterations required for a particular transfer angle and non-dimensional time of flight will be generated.

However, notice that this plotter does not retrieve a full insight on the performance of the algorithms, as the time per iteration is not an output. Anyway, it is a first approach to provide users and authors with a performance tool, which must be based on the matplotlib library.

💻 Feature request: add changelog file

THANKS for your perfect work!

💻 Feature request: rename boolean parameters

All of the solvers accept the following parameters prograde=True and low_path=True at the moment. However, it would be more convenient to rename those as is_prograde=True and is_low_path=True. These lead to the following type of workflow:

if is_prograde ...
if is_low_path ...

which is much more readable than the actual names being used.

💻 Feature request: add more tests

The book by Escobal, "Initial Orbit Determination", ships with a collection of eight numerical cases. Although at this moment the majority of the code is tested, we do not lose anything by adding those to the code base.

Before publishing the 0.1 version, some minimal improvements need to be done within the package:

• Remove the warning message in the README.md file.
• Check the different pages and notebooks in the documentation.
• Include the original article and presentation slides. Make sure they are not included within the source distro.
• Do not ship the tests with the distro, neither the documentation.

💻 Feature request: online documentation

At the moment, all the documentation is hosted within the docs directory. As any other open-source project (once the library will be made public), the idea is to host all the technical resources within Read the Docs.

The configuration file must be named as .readthedocs.yml to properly build the project's documentation in the platform.

💡 Idea
The current status of the library forces users to install third party libraries like matplotlib for visualization purposes. Users that are only interested in solving the Lambert's problem should not be forced to install visualization utilities.

Hence, I created the lamberthub organization to collect the lamberthub library and the performance one.

💻 Feature request: time performance plotter

As similar to #9, the idea here is to show the time per iteration instead of the number of iterations. However, some points need to be considered:

• The time it takes for a computer to execute a particular piece of code is influenced by both the implementation and the rest of the processes running in the machine. This is the reason behind why benchmarks execute the task several times and then compute the average value.

I think it should be possible to adapt the code from IterationsPlotter and adapt it to this new plotter.

💻 Feature request: gallery of examples

Any Lambert's problem solver iterates over a function known as the flight of time equation. This curve relates the free-parameter with the non-dimensional time of flight. By studying these graphs it is possible to identify critical points and develop a better initial guess or numerical method to solve for the problem.

My idea is to each algorithm's time of flight curve to the current gallery of examples, which is completely empty at this moment.

I tried to install the package in many different ways but without success, could you give me if I did something wrong?

• First try:
  pip install lamberthub

ERROR: Could not find a version that satisfies the requirement lamberthub (from versions: none) ERROR: No matching distribution found for lamberthub

• Second:
  conda install lamberthub

PackagesNotFoundError: The following packages are not available from current channels

-Third: pip install https://github.com/jorgepiloto/lamberthub

• Fourth: pip install git+git:https://github.com/jorgepiloto/lamberthub

I am running out of ideas now, do you now how to solve this issue?
Thanks

💻 Solver request

A total of five methods are presented in the book by Escobal (see references section) for solving the two-body BVP. Among these methods it is possible to find:

• gauss1809, based on the method the genius published in his "Theoria Motus Corporum Coelestium in Sectionibus Conicis Solem Ambientium". It makes use of an smart change of variable related to the orbit parameter 'p'.
• lascody1958, using true anomaly as the free-parameter.
• herrick1959, using orbit's parameter as the iteration variable.
• escobal1964, using orbit's eccentricity as the free-parameter.
• douglas1965, using the universal formulation for the computation of the solution.

Therefore, let us

📝 References

@article{escobal1970methods,
  title={Methods of orbit determination.},
  author={Escobal, Pedro},
  journal={Methods of orbit determination},
  year={1970}
}

💻 Solver request: izzo2015

Being one of the most popular modern solvers, this algorithm is used by many astrodynamics and orbital mechanics softwares. It is known to be complete, fast and accurate. It exploits again the universal formulae, same as Lancaster, but introduces an additional change of variable which leads to smoother time of flight curves. This translates into fast convergence when making the use of a Householder root-finder.

Izzo published its algorithm in 2015 and provided the source code. However, Izzo's software is released under GPL license but here it comes poliastro to the rescue! This library provides the Python implementation under MIT license, which is compatible with the current APACHE-2.0 one. Some logic might be needed to be reformatted in order to fulfill lamberthub implementation requirements in terms of input and output parameters.

📝 References

All the BibTeX materials:

  title={Revisiting Lambert’s problem},
  author={Izzo, Dario},
  journal={Celestial Mechanics and Dynamical Astronomy},
  volume={121},
  number={1},
  pages={1--15},
  year={2015},
  publisher={Springer}
}

💻 Solver request: battin1984

This solver by Battin inherits from Gauss but avoiding its singularities for 180 degrees transfer angle. Only drawback with this solver is that it was only developed for the direct transfer scenario. However, this paper by Shen extends the solver to the multi-revolution case.

📝 References

@inproceedings{battin1983elegant,
  title={An elegant Lambert algorithm(for spacecraft orbit estimation)},
  author={BATTIN, RH and VAUGHAN, RM},
  booktitle={International Astronautical Federation, International Astronautical Congress, 34 th, Budapest, Hungary},
  volume={10},
  number={15},
  year={1983}
}

💻 Feature request: properly test time plotters

After merging #13, I was surprised about CI, as it did not complain about the output figures. Well, it turns out that the tests were not being properly executed... The command to run the images is tox -e py3X-images not tox -e py3X!

The time plotters are very susceptible to machine processes and other sources of error which can slightly affect the final output. That is why we provide a N_samples, so the problem is computed several times and the final mean values are taken as the "ideal" ones.

As opposite to the time plotters, the number of iterations ones always return the same input, as they only depend on the initial conditions. These are tested using the pytest-mpl plugin.

Therefore, we must find a proper way to test time plotters in order to not lose code coverage.

💻 Solver request: pan2018

This solver iterates over the argument of perigee by using a numerical procedure based on non-rational Bézier functions. The cool thing about this paper is that it ships with the pseudo-code, so it should be more intuitive to implement this.

📝 References

@article{pan2018lambert,
  title={Lambert’s problem and solution by non-rational B{\'e}zier functions},
  author={Pan, Binfeng and Ma, Yangyang},
  journal={Proceedings of the Institution of Mechanical Engineers, Part G: Journal of Aerospace Engineering},
  volume={232},
  number={2},
  pages={227--245},
  year={2018},
  publisher={SAGE Publications Sage UK: London, England}
}

💻 Feature request: properly time solvers' iterations

After #13 was merged, I did not notice that the time being measured was the whole required by the algorithm to solve the problem. This is not the time per iteration, as also the initial guess and velocity construction vector are also being considered.

Therefore, we must properly return the time per iteration by starting the clock before the iteration begins and stop it once the solution for the independent variable has been found.

It is no possible to do this without modifying solver behavior, so my plan is to add the tpivariable, which means "time per iteration" as an optional return parameter.

💻 Solver request: vallado2013

This algorithm appeared for the first time in Vallado's book titled "Fundamentals of astrodynamics and applications". It is an improved version of the one developed by Bate in his "Fundamentals of astrodynamics", in 1971.

📝 References

@book{vallado2013fundamentals,
  title={Fundamentals of astrodynamics and applications},
  author={Vallado, David A},
  volume={12},
  year={2013},
  publisher={Springer Science \& Business Media}
}

When studying the performance comparison, I have noticed that the results for Gauss solver dot not match the scale of values.

The minimum number of iterations seems to be around two or three, being the most common color the one for 9 or above. Therefore, it is not possible to have a mean iteration of 1.08 as suggested by the docs. A similar situation is found for the case of the time per iteration and total computation time metrics.

💻 Solver request: gooding1990

This algorithm was originally devised by Gooding in 1990. Many of the work is built on top of Lancaster's one, but an accurate guess is made so fast convergence to the solution is achieved. In addition, the root finder used is Halley's method, so this solver is expected to be a high robust one. Gooding's routine was also extended to the multi-revolution case, so a full algorithm is available.

We should implement this under the name of gooding1990. Because this algorithm is the first of the library, let us create a sub-package called universal in which all the universal-formulae solvers are included in the sense of Python modules.

📝 References

The algorithm appeared for the first time in 1988 Gooding's publication, see the BibTeX citation:

@techreport{gooding1988solution,
  title={On the solution of Lambert's orbital boundary-value problem},
  author={Gooding, RH},
  year={1988},
  institution={ROYAL AEROSPACE ESTABLISHMENT FARNBOROUGH (UNITED KINGDOM)}
}

However, the implementation we must follow is the one comming from the revised revision, which was published two years later in 1990:

@article{gooding1990,
  title={A procedure for the solution of Lambert's orbital boundary-value problem},
  author={Gooding, RH},
  journal={Celestial Mechanics and Dynamical Astronomy},
  volume={48},
  number={2},
  pages={145--165},
  year={1990},
  publisher={Springer}
}

Source code under Fortran77 is attached at the end of this article, so we just need to update it to modern Python 🚀

💻 Solver request: thorne2004

The algorithm devised by James D. Thorne uses a series expansion to solve for the Lambert's problem. These approach breaks all the common steps for a Lambert's solver, meaning that it does not require an initial guess nor a numerical root finder. Different series are provided for different orbit types

📝 References

@article{thorne2004lambert,
  title={Lambert’s theorem—a complete series solution},
  author={Thorne, James D},
  journal={The Journal of the Astronautical Sciences},
  volume={52},
  number={4},
  pages={441--454},
  year={2004},
  publisher={Springer}
}

Vallado provides a pseudo-code in his "Fundamentals of Astrodynamics and Applications".