# PyTerp
A 3D interpolator for **Python** designed for maximum speed on large datasets. It accelerates the IDW algorithm with a parallelized C++ core (`OpenMP`) and optimized k-NN searches (`nanoflann`).
## Theoretical Summary
The interpolation is performed in a two-step process that combines the k-NN and IDW algorithms.
1. **Neighbor Selection (k-NN)**: For each point where a value is to be estimated, the _k-Nearest Neighbors_ algorithm first finds the k closest known source points in space. The efficiency of this search is ensured by an optimized data structure (`k-d tree`).
2. **Value Calculation (IDW)**: Next, the _Inverse Distance Weighting_ method calculates the final value as a weighted average of the k found neighbors. The weight of each neighbor is inversely proportional to its distance (weight = 1/distanceáµ–, where `p` is a power parameter), causing closer points to have a much greater influence on the result.
## Prerequisites
Before you begin, ensure you have the following software installed:
* **Python 3.10+**
* **Git**
* **A C++ compiler**: This package contains C++ code that needs to be compiled during installation.
* **Windows**: Install Visual Studio Build Tools (select the "Desktop development with C++" workload).
* **Linux (Debian/Ubuntu)**: Install build-essential with: sudo apt-get install build-essential.
## Installation
### PyPI
#### Install the package:
```bash
pip install pyterp
```
---
### GitHub
#### 1. Clone the repository:
```bash
git clone https://github.com/jgmotta98/PyTerp.git
cd PyTerp
```
#### 2. Create and activate a virtual environment:
```bash
# Create the environment
python -m venv .venv
# Activate the environment
# On Windows (cmd.exe):
.venv\Scripts\activate
# On macOS/Linux (bash/zsh):
source .venv/bin/activate
```
#### 3. Install the requirements:
```bash
pip install -r requirements.txt
```
#### 4. Install the package:
```bash
pip install .
```
## Usage Example
For a complete and runnable example, including the creation and preparation of input data, please see the scripts in the [examples](examples/basic_usage.py) folder.
## Acknowledgements
This project uses `nanoflann`, a high-performance C++ library for the _k-Nearest Neighbors_ algorithm. The efficiency of nanoflann's k-d tree implementation is fundamental to this interpolator's performance.
* **Official Repository:** [Nanoflann](https://github.com/jlblancoc/nanoflann)
Raw data
{
"_id": null,
"home_page": null,
"name": "pyterp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "interpolation, k-NN, IDW, C++, parallel, numpy, performance",
"author": null,
"author_email": "Jonathan Motta <jonathangmotta98@gmail.com>",
"download_url": null,
"platform": null,
"description": "# PyTerp\n\nA 3D interpolator for **Python** designed for maximum speed on large datasets. It accelerates the IDW algorithm with a parallelized C++ core (`OpenMP`) and optimized k-NN searches (`nanoflann`).\n\n## Theoretical Summary\n\nThe interpolation is performed in a two-step process that combines the k-NN and IDW algorithms.\n\n1. **Neighbor Selection (k-NN)**: For each point where a value is to be estimated, the _k-Nearest Neighbors_ algorithm first finds the k closest known source points in space. The efficiency of this search is ensured by an optimized data structure (`k-d tree`).\n\n2. **Value Calculation (IDW)**: Next, the _Inverse Distance Weighting_ method calculates the final value as a weighted average of the k found neighbors. The weight of each neighbor is inversely proportional to its distance (weight = 1/distance\u1d56, where `p` is a power parameter), causing closer points to have a much greater influence on the result.\n\n## Prerequisites\n\nBefore you begin, ensure you have the following software installed:\n\n* **Python 3.10+**\n* **Git**\n* **A C++ compiler**: This package contains C++ code that needs to be compiled during installation.\n * **Windows**: Install Visual Studio Build Tools (select the \"Desktop development with C++\" workload).\n * **Linux (Debian/Ubuntu)**: Install build-essential with: sudo apt-get install build-essential.\n\n## Installation\n\n### PyPI\n\n#### Install the package:\n\n```bash\npip install pyterp\n```\n\n---\n\n### GitHub\n\n#### 1. Clone the repository:\n\n```bash\ngit clone https://github.com/jgmotta98/PyTerp.git\ncd PyTerp\n```\n\n#### 2. Create and activate a virtual environment:\n\n```bash\n# Create the environment\npython -m venv .venv\n\n# Activate the environment\n# On Windows (cmd.exe):\n.venv\\Scripts\\activate\n# On macOS/Linux (bash/zsh):\nsource .venv/bin/activate\n```\n\n#### 3. Install the requirements:\n\n```bash\npip install -r requirements.txt\n```\n\n#### 4. Install the package:\n\n```bash\npip install .\n```\n\n## Usage Example\n\nFor a complete and runnable example, including the creation and preparation of input data, please see the scripts in the [examples](examples/basic_usage.py) folder.\n\n## Acknowledgements\n\nThis project uses `nanoflann`, a high-performance C++ library for the _k-Nearest Neighbors_ algorithm. The efficiency of nanoflann's k-d tree implementation is fundamental to this interpolator's performance.\n\n* **Official Repository:** [Nanoflann](https://github.com/jlblancoc/nanoflann)\n",
"bugtrack_url": null,
"license": null,
"summary": "A package for performing optimized k-NN IDW interpolation using C++.",
"version": "0.2.5",
"project_urls": {
"Bug Tracker": "https://github.com/jgmotta98/PyTerp/issues",
"Homepage": "https://github.com/jgmotta98/PyTerp",
"Source Code": "https://github.com/jgmotta98/PyTerp"
},
"split_keywords": [
"interpolation",
" k-nn",
" idw",
" c++",
" parallel",
" numpy",
" performance"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a787aef941514eca58993c36a839393a4389eff73373e1d68a9e4bbe2a9e777c",
"md5": "c257671b3ff78fee1bca1fb549ed2d49",
"sha256": "4297ea1494115bb45daf5f602c17e6cb6095d968d1f2b19f202f88ac1acb0d87"
},
"downloads": -1,
"filename": "pyterp-0.2.5-cp310-cp310-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "c257671b3ff78fee1bca1fb549ed2d49",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 1701324,
"upload_time": "2025-07-10T20:34:28",
"upload_time_iso_8601": "2025-07-10T20:34:28.370808Z",
"url": "https://files.pythonhosted.org/packages/a7/87/aef941514eca58993c36a839393a4389eff73373e1d68a9e4bbe2a9e777c/pyterp-0.2.5-cp310-cp310-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "333ee04daaebae53d6552e04c2acac9530b750f391f3325e66901448490d0536",
"md5": "d7b426943e86c6f94b5f6df90b134a56",
"sha256": "d341aece97b533f964ff10ade74dac1b7a37461d7465e2068fe2b2efdd680270"
},
"downloads": -1,
"filename": "pyterp-0.2.5-cp310-cp310-win32.whl",
"has_sig": false,
"md5_digest": "d7b426943e86c6f94b5f6df90b134a56",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 98720,
"upload_time": "2025-07-10T20:34:30",
"upload_time_iso_8601": "2025-07-10T20:34:30.020866Z",
"url": "https://files.pythonhosted.org/packages/33/3e/e04daaebae53d6552e04c2acac9530b750f391f3325e66901448490d0536/pyterp-0.2.5-cp310-cp310-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d71f8e6b97b67043394f0e979315b4c11da8c358150b0aab7360f93c85d1d636",
"md5": "b20a0e4532760a263a30cc9a51414170",
"sha256": "2dabb143844a6b36d2815d2971756dfe565b51dda691b50b4b528fd9f0040f36"
},
"downloads": -1,
"filename": "pyterp-0.2.5-cp310-cp310-win_amd64.whl",
"has_sig": false,
"md5_digest": "b20a0e4532760a263a30cc9a51414170",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 109273,
"upload_time": "2025-07-10T20:34:31",
"upload_time_iso_8601": "2025-07-10T20:34:31.637401Z",
"url": "https://files.pythonhosted.org/packages/d7/1f/8e6b97b67043394f0e979315b4c11da8c358150b0aab7360f93c85d1d636/pyterp-0.2.5-cp310-cp310-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5cb9e8ae32d1e24030e58b37ec90e7c55c5ac88680e927bfe5424143d278ea9f",
"md5": "d8c7a6dd07299d200bcd561bbaee9260",
"sha256": "ccf8192e20913d417eb56056b2039d2395f58ce059c7ef7ab52f3aad1145b5fd"
},
"downloads": -1,
"filename": "pyterp-0.2.5-cp311-cp311-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "d8c7a6dd07299d200bcd561bbaee9260",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 1720525,
"upload_time": "2025-07-10T20:34:33",
"upload_time_iso_8601": "2025-07-10T20:34:33.080906Z",
"url": "https://files.pythonhosted.org/packages/5c/b9/e8ae32d1e24030e58b37ec90e7c55c5ac88680e927bfe5424143d278ea9f/pyterp-0.2.5-cp311-cp311-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c5198fde9bda690492e4177d8290295e9d79d8b1577cd69e5804544e15eab430",
"md5": "d4cbd2590c840a201edab2a924b909a6",
"sha256": "4f15826c95169456c5431d8cd2e83f52f223650db11c5a069dd6882e0df956ee"
},
"downloads": -1,
"filename": "pyterp-0.2.5-cp311-cp311-win32.whl",
"has_sig": false,
"md5_digest": "d4cbd2590c840a201edab2a924b909a6",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 99525,
"upload_time": "2025-07-10T20:34:34",
"upload_time_iso_8601": "2025-07-10T20:34:34.347508Z",
"url": "https://files.pythonhosted.org/packages/c5/19/8fde9bda690492e4177d8290295e9d79d8b1577cd69e5804544e15eab430/pyterp-0.2.5-cp311-cp311-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b336d2a614fa4d39c170ee405b17d657791a22805e65de4d0e945eff3fd3a98d",
"md5": "d7e0b8431df1619544587120994972f5",
"sha256": "5a578e7e3892472706109c9a1067d779b7f9107460278a57bbb10229b590b90c"
},
"downloads": -1,
"filename": "pyterp-0.2.5-cp311-cp311-win_amd64.whl",
"has_sig": false,
"md5_digest": "d7e0b8431df1619544587120994972f5",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 109853,
"upload_time": "2025-07-10T20:34:35",
"upload_time_iso_8601": "2025-07-10T20:34:35.353965Z",
"url": "https://files.pythonhosted.org/packages/b3/36/d2a614fa4d39c170ee405b17d657791a22805e65de4d0e945eff3fd3a98d/pyterp-0.2.5-cp311-cp311-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f7b391396f6f6bb681dfcb47bda8cee24d2d68f3275911a68519fc2de494f3c2",
"md5": "19ab0a0d566ff18062448e6007b8063f",
"sha256": "e29fd435c9083b475840349a3bb728e4d529e65f0f2633addcb17d79e03c6b03"
},
"downloads": -1,
"filename": "pyterp-0.2.5-cp312-cp312-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "19ab0a0d566ff18062448e6007b8063f",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 1725699,
"upload_time": "2025-07-10T20:34:36",
"upload_time_iso_8601": "2025-07-10T20:34:36.429284Z",
"url": "https://files.pythonhosted.org/packages/f7/b3/91396f6f6bb681dfcb47bda8cee24d2d68f3275911a68519fc2de494f3c2/pyterp-0.2.5-cp312-cp312-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3f67e83eaf33abaee3575b07f14d6e431ce6a66ccbf2a069f21c45437a13e7ab",
"md5": "4e4eb28ca29d8c4e357c22b8e6f1439d",
"sha256": "6b71315bc3a5ba1850ecf175e013ae4756a34c5f7a8d1eba4f2efa811831d53b"
},
"downloads": -1,
"filename": "pyterp-0.2.5-cp312-cp312-win32.whl",
"has_sig": false,
"md5_digest": "4e4eb28ca29d8c4e357c22b8e6f1439d",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 100263,
"upload_time": "2025-07-10T20:34:37",
"upload_time_iso_8601": "2025-07-10T20:34:37.672399Z",
"url": "https://files.pythonhosted.org/packages/3f/67/e83eaf33abaee3575b07f14d6e431ce6a66ccbf2a069f21c45437a13e7ab/pyterp-0.2.5-cp312-cp312-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "875f3f445029447f3c89d08870154bec1101132510fdc00d98b56cb805c7d1cf",
"md5": "ec1772acf5512d0c3a946bf9bf83fee2",
"sha256": "a32c26ea573367b8ca9f4c09c77c0d841f9f954ecc931e56cc7ae7492af11803"
},
"downloads": -1,
"filename": "pyterp-0.2.5-cp312-cp312-win_amd64.whl",
"has_sig": false,
"md5_digest": "ec1772acf5512d0c3a946bf9bf83fee2",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 111000,
"upload_time": "2025-07-10T20:34:39",
"upload_time_iso_8601": "2025-07-10T20:34:39.938190Z",
"url": "https://files.pythonhosted.org/packages/87/5f/3f445029447f3c89d08870154bec1101132510fdc00d98b56cb805c7d1cf/pyterp-0.2.5-cp312-cp312-win_amd64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 20:34:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jgmotta98",
"github_project": "PyTerp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pyterp"
}