This repository has been archived by the owner on Jun 24, 2020. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 2
/
README
142 lines (96 loc) · 4.61 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
.. pycephes
pycephes
========
.. image:: http://unmaintained.tech/badge.svg
:target: http://unmaintained.tech/
:alt: No Maintenance Intended
:Name: pycephes
:Website: https://github.com/poliastro/pycephes
:Author: Juan Luis Cano Rodríguez <[email protected]>
:Version: 0.2.dev0
.. |license| image:: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square
:target: https://github.com/poliastro/pycephes/raw/master/COPYING
.. |mailing| image:: https://img.shields.io/badge/mailing%20list-groups.io-8cbcd1.svg?style=flat-square
:target: https://groups.io/g/poliastro-dev
|license| |mailing|
*Note*: This was a (successful) proof of concept but it's not maintained anymore.
Please check out projects like https://github.com/limix/ncephes.
pycephes is a thin Python wrapper for the `CEPHES mathematical library`_
from Netlib, written using `CFFI`_ and easy to use with `numba`_.
It is released under the MIT license, hence allowing commercial use.
.. _`CEPHES mathematical library`: http://www.netlib.org/cephes/
.. _`CFFI`: http://cffi.readthedocs.org/
.. _`numba`: http://numba.pydata.org/
At present it only interfaces a single hypergeometric function, but
is provided here both as a proof of concept of the power of
CFFI + numba and as a support for `poliastro`_, a Python library
for interplanetary Astrodynamics. It is therefore a work in progress,
and all contributions are welcome (see `Contributing`_).
.. _`poliastro`: https://github.com/poliastro/poliastro
Performance
-----------
The motivation for creating this project is mainly achieving a good
performance. Time benchmarks are included in the ``tests/`` directory
which can be run using `pytest-benchmark`_.
.. _`pytest-benchmark`: https://github.com/ionelmc/pytest-benchmark
Preliminary studies suggest that pycephes can be nearly **5 times faster**
on average than the equivalent SciPy function.
.. image:: benchmark.png
:alt: Time benchmarks
:align: center
Requirements
============
pycephes requires the following Python packages:
* NumPy, for basic array handling
* CFFI, for interfacing with C code
* numba, to make it compatible with upstream jitted functions
In addition, the CEPHES mathematical library must be present on the system.
Installation
============
The easiest and fastest way to get the package up and running is to
install pycephes using `conda <http://conda.io>`_. This also installs
the CEPHES package as a dependency::
$ conda install pycephes --channel poliastro
It can be installed from PyPI too, provided that the CEPHES library
is present on the system::
$ pip install pycephes
You can also `download pycephes source from GitHub`_ and type::
$ pip install .
Development installations are supported as well::
$ pip install -e .
.. _`install poliastro from PyPI`: https://pypi.python.org/pypi/pycephes/
.. _`download pycephes source from GitHub`: http://github.com/poliastro/pycephes
.. warning::
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 `virtualenvs`_
or `local installations`_.
.. _1: https://wiki.python.org/moin/CheeseShopTutorial#Python.27s_distutils
.. _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
.. _`virtualenvs`: http://pypi.python.org/pypi/virtualenv
.. _`local installations`: http://stackoverflow.com/a/4325047/554319
Contributing
============
One obvious area of improvement for the library consists in adding more
functions. Some other ideas:
* Create some script to generate the function headers so they don't have
to be added manually.
* Use the ``@generated_jit`` feature `introduced in numba 0.24`_ to
automatically trigger the appropriate function depending on the dimension
of the inputs, à la Julia.
.. _`introduced in numba 0.24`: http://numba.pydata.org/numba-doc/0.24.0/release-notes.html#version-0-24-0
Potential contributors are encouraged to fork the repository and open a pull request.
Support
=======
|mailing|
You can post support questions regarding pycephes on the
`poliastro mailing list`_ or the `pycephes issue tracker`_.
.. _`poliastro mailing list`: https://groups.io/g/poliastro-dev
.. _`pycephes issue tracker`: https://github.com/poliastro/pycephes/issues
License
=======
|license|
pycephes is released under the MIT license, hence allowing commercial
use of the library. Please refer to the COPYING file.