Tip
Looking for a no-code version of HSPiPy? Get HSP Desktop
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.
- 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
- Class reference:
Install HSPiPy easily with pip:
pip install HSPiPy
- numpy
- pandas
- matplotlib
- scipy
- scikit-learn
To read HSP data from a file (CSV, HSD or HSDX), create an instance of the HSP class and use the read method:
fromhspipyimportHSPhsp=HSP()
hsp.read('path_to_your_hsp_file.csv')Use the get method to calculate the Hansen Solubility Parameters (HSP) from your data:
# For a single sphere model (default)result=hsp.get(inside_limit=1)
# For a double sphere modelresult=hsp.get(inside_limit=1, n_spheres=2)get() returns an HSPResult object. In a Jupyter notebook it renders as a formatted table automatically. In a script use print(result) or access attributes directly:
print(result.hsp) # fitted D, P, H center coordinatesprint(result.radius) # sphere radiusprint(result.accuracy) # classification accuracyprint(result.datafit) # DATAFIT valueprint(result.n_solvents_in) # number of good solventsprint(result.n_solvents_out) # number of bad solventsprint(result.n_total) # total solventsprint(result.n_wrong_in) # bad solvents inside sphere (false positives)print(result.n_wrong_out) # good solvents outside sphere (false negatives)The inside_limit parameter defines the threshold score value to consider a solvent as "inside" the solubility sphere (default: inside_limit=1).
Use the plot_3d and plot_2d methods to visualize the HSP data in 3D and 2D formats, respectively:
# Generate individual plotshsp.plot_3d()
hsp.plot_2d()
# Or generate both plots at oncehsp.plots()
| Method | Description |
|---|---|
| read(path) | Reads solvent data from a CSV, HSD, or HSDX file. |
| get(inside_limit=1, n_spheres=1) | Fits HSP sphere(s) and returns an HSPResult object. |
| plot_3d() | Plots the HSP data in 3D. Returns the figure. |
| plot_2d() | Plots the HSP data in 2D. Returns the figure. |
| plots() | Generates both 2D and 3D plots. Returns (fig_3d, fig_2d). |
get() returns an HSPResult object. The following attributes are available on it and also set on the HSP instance after calling get():
| Attribute | Description |
|---|---|
result.hsp | Numpy array — Fitted HSP coordinates. Shape: (3,) for single-sphere (D, P, H), or (n_spheres, 3) for multiple spheres. |
result.radius | Float or array — Radius (or radii) of the solubility sphere(s). |
result.error | Float — Objective function value from the optimization (lower is better). |
result.accuracy | Float — Classification accuracy of the fitted model on the dataset. |
result.datafit | Float — DATAFIT value (geometric mean fitness; 1.0 = perfect classification). |
result.n_solvents_in | Int — Number of good solvents (0 < score <= inside_limit). |
result.n_solvents_out | Int — Number of bad solvents (score == 0 or score > inside_limit). |
result.n_total | Int — Total number of solvents. |
result.n_wrong_in | Int — Bad solvents predicted inside the sphere (false positives). |
result.n_wrong_out | Int — Good solvents predicted outside the sphere (false negatives). |
hsp.d, hsp.p, hsp.h | Float — Individual HSP components (δD, δP, δH). Single-sphere only; None for multi-sphere. |
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. |
importnumpyasnpfromhspipyimportHSPEstimator# 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 scoresest=HSPEstimator(n_spheres=1)
est.fit(X, y)
print("Fitted HSP:", est.hsp_)
print("Accuracy:", est.score(X, y))Contributions are welcome! If you have any suggestions, feature requests, or bug reports, please open an issue on the GitHub repository.
If HSPiPy is useful for your work, there are several ways to support its continued development.
HSP Desktop is an affordable desktop application built on top of the HSPiPy engine, providing a fast and intuitive graphical interface for Hansen Solubility Parameter analysis.
It is ideal for users who:
- Prefer a graphical interface over Python scripting
- Need a fast, one-click workflow for HSP calculations
- Want advanced visualization and solvent exploration tools
Purchasing HSP Desktop helps fund the continued development of HSPiPy, including new features, databases, documentation, and maintenance.
You can also support the project directly through GitHub Sponsors:
👉 https://github.com/sponsors/Gnpd
Every contribution helps keep HSPiPy free, open source, and actively maintained.
This library is licensed under the MIT License. See the LICENSE file for details.
HSPiPy was inspired by the well-known HSP software suit Hansen Solubility Parameters in Practice (HSPiP) and by the HSP community.