.. poliastro

.. image:: http://poliastro.github.io/_static/logo_text.png
   :target: http://poliastro.github.io/
   :alt: poliastro logo
   :width: 675px
   :align: center

:Name: poliastro
:Website: https://poliastro.github.io/
:Author: Juan Luis Cano Rodríguez <juanlu001@gmail.com>
:Version: 0.3.3

.. image:: https://travis-ci.org/poliastro/poliastro.svg?branch=0.3.x
   :target: https://travis-ci.org/poliastro/poliastro

.. image:: https://coveralls.io/repos/poliastro/poliastro/badge.svg?branch=0.3.x
   :target: https://coveralls.io/r/poliastro/poliastro?branch=0.3.x

.. image:: https://ci.appveyor.com/api/projects/status/ajg5j8byv8isslso/branch/0.3.x?svg=true
   :target: https://ci.appveyor.com/project/poliastro/poliastro/branch/0.3.x

.. image:: https://img.shields.io/badge/license-MIT-blue.svg
   :target: https://raw.githubusercontent.com/poliastro/poliastro/0.3.x/COPYING

.. image:: https://zenodo.org/badge/doi/10.5281/zenodo.17461.svg
   :target: http://dx.doi.org/10.5281/zenodo.17461

poliastro is an open source pure Python package dedicated to problems arising in Astrodynamics and
Orbital Mechanics, such as orbit propagation, solution of the Lambert's
problem, conversion between position and velocity vectors and classical
orbital elements and orbit plotting. It is released under the MIT license.

.. code-block:: python

    from poliastro.examples import molniya
    from poliastro.plotting import plot
    
    plot(molniya)

.. image:: https://github.com/poliastro/poliastro/raw/0.3.x/examples/molniya.png
   :align: center

Requirements
============

poliastro requires the following Python packages:

* NumPy, for basic numerical routines
* Astropy, for physical units and time handling
* numba (optional), for accelerating the code
* jplephem, for the planetary ephemerides using SPICE kernels
* matplotlib, for the orbit plotting

poliastro is usually tested on Linux and Windows on Python 2.7, 3.3 and 3.4
(single codebase). It should work on OS X too with no changes (not tested).

Installation
============

The easiest and fastest way to get the package up and running is to
install poliastro using `conda <http://conda.io>`_::

  $ conda install poliastro --channel poliastro

You can also `install poliastro from PyPI`_ using pip, given that you already
have all the requirements::

  $ pip install poliastro

You can also `download poliastro source from GitHub`_ and type::

  $ python setup.py install

Development installations are also supported thanks to setuptools::

  $ python setup.py develop

.. _`install poliastro from PyPI`: https://pypi.python.org/pypi/poliastro/
.. _`download poliastro source from GitHub`: http://github.com/poliastro/poliastro

It is recommended that you **never ever use sudo** with distutils, pip,
setuptools and friends in Linux because you might seriously break your
system [1_][2_][3_][4_]. Options are `per user directories`_, `virtualenv`_
or `local installations`_.

.. _1: http://wiki.python.org/moin/CheeseShopTutorial#Distutils_Installation
.. _2: http://stackoverflow.com/questions/4314376/how-can-i-install-a-python-egg-file/4314446#comment4690673_4314446
.. _3: http://workaround.org/easy-install-debian
.. _4: http://matplotlib.1069221.n5.nabble.com/Why-is-pip-not-mentioned-in-the-Installation-Documentation-tp39779p39812.html

.. _`per user directories`: http://stackoverflow.com/a/7143496/554319
.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
.. _`local installations`: http://stackoverflow.com/a/4325047/554319

Testing
=======

If installed correctly, the tests can be run using py.test::

  $ python -c "import poliastro; poliastro.test()"
  Running unit tests for poliastro
  [...]
  OK
  $ 

Contributing
============

Code writing
------------

Code contributions are welcome! Just send a pull request and we'll discuss it.
In the `wiki`_ you can find some documents explaining the overall design of
poliastro, and in the `issue tracker`_ you may find pending tasks waiting for
someone to complete them.

.. _`wiki`: https://github.com/poliastro/poliastro/wiki

Bug reporting
-------------

I am one of those that writes bug-free code every single time, but if you
think you've found one please refer to the `issue tracker`_ on GitHub.

.. _`issue tracker`: https://github.com/poliastro/poliastro/issues

Citing
======

If you use poliastro on your project, please
`drop me a line <mailto:juanlu001@gmail.com>`_.

License
=======

poliastro is released under the MIT license, hence allowing commercial
use of the library. Please refer to the COPYING file.

FAQ
===

Does it work on Windows and OS X too?
-------------------------------------

poliastro is tested on Windows (see above). It is a pure Python package with
no compiled extensions, so it should work under Windows or Mac OS X with
properly installed dependencies. Please file a bug on the
`issue tracker`_ otherwise.

What's up with the name?
------------------------

poliastro comes from Polimi, which is the shortened name of the Politecnico di
Milano, the Italian university where I was studying while writing this
software. It's my tiny tribute to a place I came to love. *Grazie mille!*
