[](https://pypi.org/project/HSPiPy/) 
# HSPiPy
#### Hansen Solubility Parameters in Python.
### Introduction
---------------
HSPiPy is a Python library designed for calculating and visualizing Hansen Solubility Parameters (HSP). It provides machine-learning–friendly estimators, convenient data import, and plotting tools for analyzing solvent compatibility in materials science, polymers, and coatings.
### Features
---------------
* Read solvent data from multiple formats (CSV, HSD, HSDX)
* Calculate Hansen Solubility Parameters using robust optimization methods
* Support for single or multiple (up to 2) solubility spheres
* Generate 2D and 3D visualizations of solubility spheres
* Fully compatible with scikit-learn for machine learning workflows
### Documentation
---------------
- Class reference:
- [HSP (high‑level helper)](doc/HSP.md)
- [HSPEstimator (scikit‑learn compatible)](doc/HSPEstimator.md)
### Installation
---------------
Install **HSPiPy** easily with pip:
```
pip install HSPiPy
```
#### Dependencies
* numpy
* pandas
* matplotlib
* scipy
* scikit-learn
### Usage
--------
#### Reading HSP Data
To read HSP data from a file (CSV, HSD or HSDX), create an instance of the `HSP` class and use the `read` method:
```python
from hspipy import HSP
hsp = HSP()
hsp.read('path_to_your_hsp_file.csv')
```
#### Calculating HSP
Use the `get` method to calculate the Hansen Solubility Parameters (HSP) from your data:
```python
# For a single sphere model (default)
hsp.get(inside_limit=1)
# For a double sphere model
hsp.get(inside_limit=1, n_spheres=2)
```
The `inside_limit` parameter defines the threshold score value to consider a solvent as "inside" the solubility sphere (default: `inside_limit=1`).
#### Visualizing HSP
Use the `plot_3d` and `plot_2d` methods to visualize the HSP data in 3D and 2D formats, respectively:
```python
# Generate individual plots
hsp.plot_3d()
hsp.plot_2d()
# Or generate both plots at once
hsp.plots()
```
### `HSP` class methods:
| Method | Description |
|---------------------|:--------------------------------------------------------------------------------------:|
| read(path) | Reads solvent data from a CSV, HSD, or HSDX filefile. |
| get(inside_limit=1, n_spheres=1) | Calculates the HSP and identifies solvents inside and outside the solubility sphere. |
| plot_3d() | Plots the HSP data in 3D. |
| plot_2d() | Plots the HSP data in 2D. |
| plots() | Generates both 2D and 3D plots. |
Once you have calculated the HSP parameters using the get() method, you can access the calculated HSP parameters and related attributes through the properties of the HSP class instance. Below are the attributes you can access:
| Attribute | Description |
|----------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| `hsp.hsp` | Numpy array — Fitted HSP coordinates. Shape: `(3,)` for single-sphere (D, P, H), or `(n_spheres, 3)` for multiple spheres. |
| `hsp.d` | Float — Dispersion component (δD) of the fitted Hansen Solubility Parameters (single-sphere only). |
| `hsp.p` | Float — Polar component (δP) of the fitted Hansen Solubility Parameters (single-sphere only). |
| `hsp.h` | Float — Hydrogen-bonding component (δH) of the fitted Hansen Solubility Parameters (single-sphere only). |
| `hsp.radius` | Float or array — Radius (or radii) of the solubility sphere(s). |
| `hsp.DATAFIT` | Float — Hansen exponential penalty function result for wrong in and wrong out. |
| `hsp.error` | Float — Objective function value from the optimization (lower is better; indicates the fitting error of the HSP sphere(s)). |
| `hsp.accuracy` | Float — Classification accuracy of the fitted model on the dataset (ratio of correctly predicted solvents inside/outside the sphere(s)).|
| `hsp.inside` | List — Solvents classified as *inside* the solubility sphere(s), with their HSP values and scores. |
| `hsp.outside` | List — Solvents classified as *outside* the solubility sphere(s), with their HSP values and scores. |
| `hsp.grid` | Pandas DataFrame — The full input dataset, standardized with columns: `Solvent`, `D`, `P`, `H`, and `Score`. |
### Using scikit-learn style estimator
```python
import numpy as np
from hspipy import HSPEstimator
# Example dataset (D, P, H values with scores)
X = np.array([
[16.0, 8.0, 5.0],
[18.0, 7.5, 9.0],
[20.0, 10.0, 12.0],
])
y = np.array([1, 1, 0]) # Inside/outside labels or scores
est = HSPEstimator(n_spheres=1)
est.fit(X, y)
print("Fitted HSP:", est.hsp_)
print("Accuracy:", est.score(X, y))
```
### Contributing
----------------
Contributions are welcome! If you have any suggestions, feature requests, or bug reports, please open an issue on the [GitHub repository](https://github.com/Gnpd/HSPiPy/issues).
### License
-----------
This library is licensed under the MIT License. See the [LICENSE](https://github.com/Gnpd/HSPiPy/blob/main/LICENSE) file for details.
### Acknowledgements
----------------
HSPiPy was inspired by the well-known HSP software suit [Hansen Solubility Parameters in Practice (HSPiP)](https://www.hansen-solubility.com/HSPiP/) and by the HSP community.
Raw data
{
"_id": null,
"home_page": null,
"name": "HSPiPy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "hansen, solubility, parameters, chemistry, solvents",
"author": null,
"author_email": "Alejandro Gutierrez <agutierrez@g-npd.com>",
"download_url": "https://files.pythonhosted.org/packages/ba/43/462d50a52a01f83d652f926db676a5baa2cd3fb896da10cbcc536d63fa98/hspipy-1.1.0.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/HSPiPy/)  \n\n# HSPiPy\n\n#### Hansen Solubility Parameters in Python.\n\n### Introduction\n---------------\n\nHSPiPy is a Python library designed for calculating and visualizing Hansen Solubility Parameters (HSP). It provides machine-learning\u2013friendly estimators, convenient data import, and plotting tools for analyzing solvent compatibility in materials science, polymers, and coatings.\n\n### Features\n---------------\n\n* Read solvent data from multiple formats (CSV, HSD, HSDX)\n* Calculate Hansen Solubility Parameters using robust optimization methods\n* Support for single or multiple (up to 2) solubility spheres\n* Generate 2D and 3D visualizations of solubility spheres\n* Fully compatible with scikit-learn for machine learning workflows\n\n\n### Documentation\n---------------\n\n- Class reference:\n - [HSP (high\u2011level helper)](doc/HSP.md)\n - [HSPEstimator (scikit\u2011learn compatible)](doc/HSPEstimator.md)\n\n\n### Installation\n---------------\n\nInstall **HSPiPy** easily with pip:\n\n```\npip install HSPiPy\n```\n#### Dependencies\n\n* numpy\n* pandas\n* matplotlib\n* scipy\n* scikit-learn\n\n### Usage\n--------\n\n#### Reading HSP Data\n\nTo read HSP data from a file (CSV, HSD or HSDX), create an instance of the `HSP` class and use the `read` method:\n```python\nfrom hspipy import HSP\n\nhsp = HSP()\nhsp.read('path_to_your_hsp_file.csv')\n\n```\n\n\n#### Calculating HSP\n\nUse the `get` method to calculate the Hansen Solubility Parameters (HSP) from your data:\n```python\n# For a single sphere model (default)\nhsp.get(inside_limit=1)\n\n# For a double sphere model\nhsp.get(inside_limit=1, n_spheres=2)\n\n```\nThe `inside_limit` parameter defines the threshold score value to consider a solvent as \"inside\" the solubility sphere (default: `inside_limit=1`).\n\n#### Visualizing HSP\n\nUse the `plot_3d` and `plot_2d` methods to visualize the HSP data in 3D and 2D formats, respectively:\n```python\n# Generate individual plots\nhsp.plot_3d()\nhsp.plot_2d()\n\n# Or generate both plots at once\nhsp.plots()\n\n```\n\n\n\n### `HSP` class methods:\n| Method | Description | \n|---------------------|:--------------------------------------------------------------------------------------:|\n| read(path) | Reads solvent data from a CSV, HSD, or HSDX filefile. |\n| get(inside_limit=1, n_spheres=1) | Calculates the HSP and identifies solvents inside and outside the solubility sphere. |\n| plot_3d() | Plots the HSP data in 3D. |\n| plot_2d() | Plots the HSP data in 2D. | \n| plots() | Generates both 2D and 3D plots. | \n\nOnce you have calculated the HSP parameters using the get() method, you can access the calculated HSP parameters and related attributes through the properties of the HSP class instance. Below are the attributes you can access:\n\n| Attribute | Description | \n|----------------|-----------------------------------------------------------------------------------------------------------------------------------------|\n| `hsp.hsp` | Numpy array \u2014 Fitted HSP coordinates. Shape: `(3,)` for single-sphere (D, P, H), or `(n_spheres, 3)` for multiple spheres. |\n| `hsp.d` | Float \u2014 Dispersion component (\u03b4D) of the fitted Hansen Solubility Parameters (single-sphere only). |\n| `hsp.p` | Float \u2014 Polar component (\u03b4P) of the fitted Hansen Solubility Parameters (single-sphere only). |\n| `hsp.h` | Float \u2014 Hydrogen-bonding component (\u03b4H) of the fitted Hansen Solubility Parameters (single-sphere only). |\n| `hsp.radius` | Float or array \u2014 Radius (or radii) of the solubility sphere(s). |\n| `hsp.DATAFIT` | Float \u2014 Hansen exponential penalty function result for wrong in and wrong out. | \n| `hsp.error` | Float \u2014 Objective function value from the optimization (lower is better; indicates the fitting error of the HSP sphere(s)). |\n| `hsp.accuracy` | Float \u2014 Classification accuracy of the fitted model on the dataset (ratio of correctly predicted solvents inside/outside the sphere(s)).|\n| `hsp.inside` | List \u2014 Solvents classified as *inside* the solubility sphere(s), with their HSP values and scores. | \n| `hsp.outside` | List \u2014 Solvents classified as *outside* the solubility sphere(s), with their HSP values and scores. |\n| `hsp.grid` | Pandas DataFrame \u2014 The full input dataset, standardized with columns: `Solvent`, `D`, `P`, `H`, and `Score`. |\n\n\n### Using scikit-learn style estimator\n```python\nimport numpy as np\nfrom hspipy import HSPEstimator\n\n# Example dataset (D, P, H values with scores)\nX = np.array([\n [16.0, 8.0, 5.0],\n [18.0, 7.5, 9.0],\n [20.0, 10.0, 12.0],\n])\ny = np.array([1, 1, 0]) # Inside/outside labels or scores\n\nest = HSPEstimator(n_spheres=1)\nest.fit(X, y)\n\nprint(\"Fitted HSP:\", est.hsp_)\nprint(\"Accuracy:\", est.score(X, y))\n\n```\n\n### Contributing\n----------------\n\nContributions are welcome! If you have any suggestions, feature requests, or bug reports, please open an issue on the [GitHub repository](https://github.com/Gnpd/HSPiPy/issues).\n\n\n### License\n-----------\n\nThis library is licensed under the MIT License. See the [LICENSE](https://github.com/Gnpd/HSPiPy/blob/main/LICENSE) file for details.\n\n### Acknowledgements\n----------------\n\nHSPiPy was inspired by the well-known HSP software suit [Hansen Solubility Parameters in Practice (HSPiP)](https://www.hansen-solubility.com/HSPiP/) and by the HSP community.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Hansen Solubility Parameters in Python",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/Gnpd/HSPiPy",
"Issues": "https://github.com/Gnpd/HSPiPy/issues",
"Repository": "https://github.com/Gnpd/HSPiPy"
},
"split_keywords": [
"hansen",
" solubility",
" parameters",
" chemistry",
" solvents"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dcd9aead8f3934ae09781ff701a89b243e1f6ae4a428f0b32045cf990b81dbec",
"md5": "1a2272c33717d63c8c9324a0f6ba0d79",
"sha256": "317e5494bbc90b68e7f8f3e4d06c1f2677ab8b1e6ecba32ebe4fb02f461f54ed"
},
"downloads": -1,
"filename": "hspipy-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1a2272c33717d63c8c9324a0f6ba0d79",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 33679,
"upload_time": "2025-09-14T15:49:52",
"upload_time_iso_8601": "2025-09-14T15:49:52.588774Z",
"url": "https://files.pythonhosted.org/packages/dc/d9/aead8f3934ae09781ff701a89b243e1f6ae4a428f0b32045cf990b81dbec/hspipy-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ba43462d50a52a01f83d652f926db676a5baa2cd3fb896da10cbcc536d63fa98",
"md5": "f9629ad672ad829724171353a49000c6",
"sha256": "009226a0677ab1cc95c65e6472bb36f2f7f9bbee06aae6e4558ac20aa434f7fe"
},
"downloads": -1,
"filename": "hspipy-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f9629ad672ad829724171353a49000c6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 32864,
"upload_time": "2025-09-14T15:49:53",
"upload_time_iso_8601": "2025-09-14T15:49:53.823785Z",
"url": "https://files.pythonhosted.org/packages/ba/43/462d50a52a01f83d652f926db676a5baa2cd3fb896da10cbcc536d63fa98/hspipy-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-14 15:49:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Gnpd",
"github_project": "HSPiPy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hspipy"
}
JSON
