HSPiPy

中文 | Español | English

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)
  • HSPEstimator (scikit‑learn compatible)

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:

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:

# For a single sphere model (default)
result = hsp.get(inside_limit=1)

# For a double sphere model
result = 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 coordinates
print(result.radius)          # sphere radius
print(result.accuracy)        # classification accuracy
print(result.datafit)         # DATAFIT value
print(result.n_solvents_in)   # number of good solvents
print(result.n_solvents_out)  # number of bad solvents
print(result.n_total)         # total solvents
print(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).

Visualizing HSP

Use the plot_3d and plot_2d methods to visualize the HSP data in 3D and 2D formats, respectively:

# 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 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.

Using scikit-learn style estimator

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.

Supporting HSPiPy

---

If HSPiPy is useful for your work, there are several ways to support its continued development.

🖥️ HSP Desktop (No-Code Version)

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

👉 https://g-npd.com/hsp

Purchasing HSP Desktop helps fund the continued development of HSPiPy, including new features, databases, documentation, and maintenance.

❤️ GitHub Sponsors

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.

License

---

This library is licensed under the MIT License. See the LICENSE file for details.

Acknowledgements

---

HSPiPy was inspired by the well-known HSP software suit Hansen Solubility Parameters in Practice (HSPiP) and by the HSP community.