# cephes4py
cephes4py is a Python interface to the HCephes library, which is a reformatted version of Netlib Cephes. It provides a convenient way to access the functionality of the HCephes library within Python. cephes4py has been updated to ensure compatibility with modern Numba releases (specifically tested on version 0.57.0).
## Motivation
The motivation behind developing cephes4py was the need to use SciPy special functions within Numba functions running in nopython mode. Unfortunately, this was not possible due to compatibility issues. Since many of SciPy's special functions are actually wrappers of Cephes functions, I decided to create my own bindings to Cephes that were compatible with Numba.
Although cephes4py is much less "batteries included", I have conducted a preliminary experiment that suggests some performance improvements as well. You can refer to [this notebook](/workspaces/cephes4py/test.ipynb) for more details.
# No Argument Validation
It is important to note that cephes4py does not perform validation of the arguments passed to the underlying C-functions. This decision was made because validating even a single argument in Python could potentially double the execution time. Additionally, it would require wrapping the functions with the validation code, which makes them uncompatible with Numba. Therefore, I have chosen to leave the responsibility and freedom of argument validation to you. Please refer to [FUNCTIONS.txt](./FUNCTIONS.txt) or [interface.h](cephes4py/interface.h) to see the expected parameter and return types.
In the event that you provide invalid arguments, Hcephes will display an error message and return a fallback value. Please keep in mind that an argument can be considered invalid even if the data type is correct. For example, the binomial distribution function requires arguments to be positive, with the parameter `p` ranging from 0 to 1 and `k` being smaller than `n`. Once again, please consult [FUNCTIONS.txt](./FUNCTIONS.txt) for more information.
## Cephes Function Bindings
For a list of available Cephes functions and their descriptions, please refer to [FUNCTIONS.txt](./FUNCTIONS.txt). Please note that I have not tested all of the functions extensively, but as long as the parameters and return types are scalar-valued, they should work properly. If you intend to pass Numpy arrays as arguments, things get a little more involved as you'll have to get the pointer to its buffer:
```python
a = np.zeros(10, dtype=np.float64)
pointer = cephes4py.from_buffer("double[]", a)
function_you_want_to_use(pointer)
```
## Installation
To install cephes4py, please follow these steps:
1. Install the [hcephes](https://github.com/limix/hcephes) binary. It is recommended to compile it from source, but you will need Cmake to do so. You can use the following command to install it:
```sh
curl -fsSL https://git.io/JerYI | GITHUB_USER=limix GITHUB_PROJECT=hcephes bash
```
2. Navigate to the root directory of this repository.
3. Install the cephes4py package by running the following command:
```sh
pip install .
```
4. You're all set! You can now use cephes4py in your Python code:
```python
import cephes4py
# Example usage
bdtr = cephes4py.bdtr(4, 6, 0.3)
# You can even use the function in Numba-jitted functions running in nopython mode:
@nb.njit
def nb_bdtr(k, n, p):
return cephes4py.bdtr(k, n, p)
bdtr = nb_bdtr(4, 6, 0.3)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/jonmest/cephes4py",
"name": "cephes4py",
"maintainer": "Jon Cavallie Mester",
"docs_url": null,
"requires_python": "",
"maintainer_email": "jonmester3@gmail.com",
"keywords": "cephes,netlib,math,numba,jit",
"author": "Jon Cavallie Mester",
"author_email": "jonmester3@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/76/18/d2bc2f94531dec883fa6503042a9dce29d4718b7bf26be3dd6f5f31479fa/cephes4py-0.0.3.tar.gz",
"platform": "Windows",
"description": "# cephes4py\n\ncephes4py is a Python interface to the HCephes library, which is a reformatted version of Netlib Cephes. It provides a convenient way to access the functionality of the HCephes library within Python. cephes4py has been updated to ensure compatibility with modern Numba releases (specifically tested on version 0.57.0).\n\n## Motivation\nThe motivation behind developing cephes4py was the need to use SciPy special functions within Numba functions running in nopython mode. Unfortunately, this was not possible due to compatibility issues. Since many of SciPy's special functions are actually wrappers of Cephes functions, I decided to create my own bindings to Cephes that were compatible with Numba.\n\nAlthough cephes4py is much less \"batteries included\", I have conducted a preliminary experiment that suggests some performance improvements as well. You can refer to [this notebook](/workspaces/cephes4py/test.ipynb) for more details.\n\n# No Argument Validation\nIt is important to note that cephes4py does not perform validation of the arguments passed to the underlying C-functions. This decision was made because validating even a single argument in Python could potentially double the execution time. Additionally, it would require wrapping the functions with the validation code, which makes them uncompatible with Numba. Therefore, I have chosen to leave the responsibility and freedom of argument validation to you. Please refer to [FUNCTIONS.txt](./FUNCTIONS.txt) or [interface.h](cephes4py/interface.h) to see the expected parameter and return types.\n\nIn the event that you provide invalid arguments, Hcephes will display an error message and return a fallback value. Please keep in mind that an argument can be considered invalid even if the data type is correct. For example, the binomial distribution function requires arguments to be positive, with the parameter `p` ranging from 0 to 1 and `k` being smaller than `n`. Once again, please consult [FUNCTIONS.txt](./FUNCTIONS.txt) for more information.\n\n## Cephes Function Bindings\nFor a list of available Cephes functions and their descriptions, please refer to [FUNCTIONS.txt](./FUNCTIONS.txt). Please note that I have not tested all of the functions extensively, but as long as the parameters and return types are scalar-valued, they should work properly. If you intend to pass Numpy arrays as arguments, things get a little more involved as you'll have to get the pointer to its buffer:\n```python\na = np.zeros(10, dtype=np.float64)\npointer = cephes4py.from_buffer(\"double[]\", a)\nfunction_you_want_to_use(pointer)\n```\n\n## Installation\nTo install cephes4py, please follow these steps:\n\n1. Install the [hcephes](https://github.com/limix/hcephes) binary. It is recommended to compile it from source, but you will need Cmake to do so. You can use the following command to install it:\n ```sh\n curl -fsSL https://git.io/JerYI | GITHUB_USER=limix GITHUB_PROJECT=hcephes bash\n ```\n2. Navigate to the root directory of this repository.\n3. Install the cephes4py package by running the following command:\n ```sh\n pip install .\n ```\n4. You're all set! You can now use cephes4py in your Python code:\n ```python\n import cephes4py\n \n # Example usage\n bdtr = cephes4py.bdtr(4, 6, 0.3)\n\n # You can even use the function in Numba-jitted functions running in nopython mode:\n @nb.njit\n def nb_bdtr(k, n, p):\n return cephes4py.bdtr(k, n, p)\n\n bdtr = nb_bdtr(4, 6, 0.3)\n ```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Numba-friendly Python bindings to Cephes math library",
"version": "0.0.3",
"project_urls": {
"Download": "https://github.com/limix/ncephes",
"Homepage": "https://github.com/jonmest/cephes4py"
},
"split_keywords": [
"cephes",
"netlib",
"math",
"numba",
"jit"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "04277090093cf490f6a379c175b71660c7a358339054801c58ce3af8ac131af0",
"md5": "e7d7ee6db1e6a3c3940b7abaafd810d4",
"sha256": "f7a2d225c20939caf72028f183d02e7c11e8fba6543065830ae908f962351fef"
},
"downloads": -1,
"filename": "cephes4py-0.0.3-cp310-cp310-manylinux_2_24_x86_64.whl",
"has_sig": false,
"md5_digest": "e7d7ee6db1e6a3c3940b7abaafd810d4",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": null,
"size": 181039,
"upload_time": "2023-07-05T13:38:28",
"upload_time_iso_8601": "2023-07-05T13:38:28.625187Z",
"url": "https://files.pythonhosted.org/packages/04/27/7090093cf490f6a379c175b71660c7a358339054801c58ce3af8ac131af0/cephes4py-0.0.3-cp310-cp310-manylinux_2_24_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7618d2bc2f94531dec883fa6503042a9dce29d4718b7bf26be3dd6f5f31479fa",
"md5": "a52936f1a2000dd86d2249e8cc0871a2",
"sha256": "dea54185141b3e86554fae494a2b4e607c3129d204872ad0459a6ca787ea973c"
},
"downloads": -1,
"filename": "cephes4py-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "a52936f1a2000dd86d2249e8cc0871a2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10124,
"upload_time": "2023-07-05T13:40:24",
"upload_time_iso_8601": "2023-07-05T13:40:24.598912Z",
"url": "https://files.pythonhosted.org/packages/76/18/d2bc2f94531dec883fa6503042a9dce29d4718b7bf26be3dd6f5f31479fa/cephes4py-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-05 13:40:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jonmest",
"github_project": "cephes4py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cephes4py"
}
JSON
