HSP Desktop — 用户手册

版本：1.0.0 · 技术：HSPiPy v1.1.8

1. 介绍

HSP Desktop 是一款用于计算和可视化汉森溶解度参数（HSP）的桌面应用程序。它允许您构建溶剂数据集，对每种溶剂与目标材料的兼容性进行评分，拟合 HSP 球体（或同时拟合两个球体），并立即在交互式 3D 或 2D 图表中查看结果。

科学计算由 HSPiPy 提供支持，这是一个实现 HSP 球体优化算法的 Python 库。该应用程序将该库封装在适用于 Windows、macOS 和 Linux 的本地桌面界面中。购买 HSP Desktop 将直接支持 HSPiPy 作为开源项目的持续发展。

主要功能：

内置包含数百种溶剂完整 HSP 数据的数据库
在 0–6 范围内手动对溶剂评分
一键 HSP 球体拟合，包含精确度和 DATAFIT 指标
同时拟合两个 HSP 球体
表面探索器：在数据库中查找靠近球体边界的溶剂并将其添加到溶剂格
溶剂梯度生成（两种溶剂在不同比例下的混合物）
从 .csv、.hsd 和 .hsdx 文件导入
导出为 CSV 或 Excel
从本地数据库保存和重新加载命名溶剂格（拟合结果与溶剂格数据一起保存）
界面支持英语、中文（简体中文）和西班牙语

2. 安装与首次启动

安装

双击安装程序（Windows 上的 .msi，macOS 上的 .dmg，Linux 上的 .deb）并按照屏幕上的步骤操作。应用程序安装到用户目录，不需要管理员权限。

安全警告（未签名应用）

HSP Desktop 目前未配备平台代码签名证书。首次安装或打开应用时，操作系统会显示一次安全警告。这是正常现象——请按照以下步骤继续操作。

Windows — SmartScreen
当出现"Windows 已保护你的电脑"时：
1. 点击更多信息
2. 点击仍要运行

macOS — 安全警告
首次启动时 macOS 会阻止应用。根据您的 macOS 版本，可能看到"无法打开，因为无法验证开发者"或"已损坏，无法打开"。两种情况的最快解决方法是安装后在终端中运行以下命令一次，然后重新启动应用：
xattr -cr /Applications/hsp-desktop.app如果看到的是"无法验证"对话框（而非"已损坏"），也可以前往系统设置 → 隐私与安全性，点击仍要打开，然后重新启动应用。xattr 命令适用于两种情况，运行安全。

Linux
.deb 软件包无需额外步骤。

如果安装过程中遇到任何问题，请联系 support@g-npd.com。

启动画面

打开应用程序时，会显示启动画面。在首次启动时，配置向导将引导您完成三个步骤：语言选择、许可协议 (EULA) 审阅和许可证激活。对话框顶部的进度指示器显示当前所在步骤，您可以随时在 EULA 步骤点击返回以回到语言选择。所有步骤完成后，后端自动启动，动画进度条和循环状态消息确认启动正在进行中。大多数系统需要 3–10 秒；macOS 首次启动时可能需要额外几秒钟，系统会验证后端组件。底部显示取消按钮——点击后将干净地退出应用程序。

如果后端未启动

应用程序持续轮询后端，没有固定超时，因此运行较慢的机器只要有足够时间仍可成功启动。如果确实出现问题，点击取消退出并尝试以下操作：

仅 macOS — 在终端中运行 xattr -cr /Applications/hsp-desktop.app，然后重新启动应用。
检查端口 8000 是否已被其他应用程序占用。
重新启动应用程序——如果后端在上次运行中崩溃，可能留有残留进程。
联系 support@g-npd.com 并附上后端日志（在错误面板中点击重试，然后点击刷新日志）。

2.1 语言选择

在首次启动时，配置向导出现并在顶部显示三步进度指示器。第一步要求您选择界面语言。

点击三个选项之一 — 对话框立即进入下一步。如需更改选择，可在 EULA 步骤点击返回回到此处。

所选语言将在以后的启动中记住，也可随时在设置中更改。

2.2 许可协议 (EULA)

第二步显示最终用户许可协议。您必须：

阅读最终用户许可协议（滚动查看文本框）。
勾选"我已阅读并同意许可协议"复选框。
点击接受并继续。

如果在上一步选择了错误的语言，点击返回回到语言选择器。

接受信息存储在本地；后续启动时不再显示此步骤。

底部提供完整 EULA 和隐私政策的链接供参考。

2.3 许可证激活

第三步激活您的许可证。如果您的机器上已存储有效许可证，此步骤将自动跳过并开始加载后端。

激活步骤：

在购买确认邮件中找到许可证密钥（格式：XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX）。
将密钥粘贴或输入到输入框中。
点击激活（或按 Enter）。

应用程序将联系许可证服务器验证密钥。验证成功后，对话框关闭，后端自动开始加载 — 进度条启动，后端就绪后主界面加载。

还没有许可证？点击对话框内的"点击购买"链接，在浏览器中打开购买页面。

3. 界面概览

主窗口分为两个可调整大小的面板，由一个拖动手柄分隔。

┌─────────────────────────────┬──────────────────────────────────────┐
│                             │                          📄  ⚙       │
│   溶剂格                    │  [ 3D | 2D | 2D/3D ]                 │
│   ─────────────────────     │                                      │
│   溶剂格工具栏               │   3D / 2D 图表                       │
│                             │                                      │
│   ┌─────────────────────┐   │                                      │
│   │ 溶剂表格（可滚动）   │   ├──────────────────────────────────────┤
│   └─────────────────────┘   │   拟合面板                           │
│                             │   δD δP δH R₀ | 拟合 HSP             │
└─────────────────────────────┴──────────────────────────────────────┘

区域	描述
左侧 — 溶剂格	溶剂格管理工具栏 + 可滚动的溶剂表格
右上 — 图表	溶剂空间的交互式 3D 或 2D 散点图
右下 — 拟合面板	HSP 拟合控件、结果和表面探索器
右上角 — 文档图标 (📄)	在浏览器中打开用户文档
右上角 — 设置图标 (⚙)	打开设置对话框（语言、主机、端口、API 密钥）
右上角 — 图表模式选择器	在 3D、2D 和 2D/3D 视图之间切换

您可以向左或向右拖动垂直分隔符来调整两个面板的大小。

4. 溶剂格

4.1 创建和管理溶剂格

左侧面板顶部的工具栏包含一个下拉选择器和一排图标按钮。

下拉选择器

点击下拉菜单查看保存在本地数据库中的所有溶剂格。点击溶剂格名称加载它。如果当前溶剂格有未保存的更改，确认对话框将询问是否放弃更改。

下拉菜单中还有一个用于创建新溶剂格的内联区域：在文本框中输入名称并按新建。

图标按钮（从左到右）

图标	操作
📄（新建）	创建一个新的空溶剂格
📂（文件夹）	打开文件（`.csv`、`.hsd`、`.hsdx`）
↗（导出）	导出当前溶剂格（悬停选择 CSV 或 Excel）
💾（保存）	将当前溶剂格（及拟合结果）保存到本地数据库
✏️（铅笔）	重命名当前溶剂格
⧉（复制）	复制当前溶剂格

当溶剂格有未保存的更改时，保存图标变为琥珀色。

4.2 从数据库添加溶剂

点击工具栏右侧的蓝色＋圆圈按钮打开溶剂选择器。

搜索栏 — 输入溶剂名称或 CAS 编号的任意部分；表格实时过滤。
HSP / 完整切换 — 在 HSP 模式下只显示 δD、δP、δH 和 CAS 列；切换到完整可查看额外属性。

使用复选框选择一行或多行。已存在于当前溶剂格中的溶剂显示为灰色且无法再次选择。准备好后，点击添加已选 (n)。

4.3 添加溶剂梯度

点击蓝色 ⤢ 圆圈按钮打开梯度选择器。此工具在两种溶剂之间以均匀间隔的混合比例生成一系列混合行。

使用搜索栏过滤溶剂列表。
点击一种溶剂将其标记为 A（蓝色标签）。
点击第二种溶剂将其标记为 B（绿色标签）。
设置步长 (%) 值 — 例如 10 生成 0:100、10:90、20:80、… 100:0 的混合物。
预览表格显示每种混合物的计算 HSP 值。
点击添加 n 行将梯度插入溶剂格。

4.4 导入文件

扩展名	描述
`.csv`	包含 Solvent、D、P、H、Score 列的逗号分隔值
`.hsd`	HSPiP 原生数据集格式
`.hsdx`	HSPiP 扩展数据集格式

文件名（不含扩展名）用作溶剂格名称。导入的数据被视为未保存，直到您将其明确保存到数据库。

4.5 导出数据

导出为 CSV — 包含所有列（含计算的 RED 值）的纯 .csv 文件。
导出为 Excel — 适合在电子表格工具中进一步分析的 .xlsx 文件。

4.6 溶剂评分

评分列是表格中唯一可编辑的列，接受整数值，代表每种溶剂与目标材料的实验观察兼容性。

二元评分 (0 / 1)

评分	含义
1	好溶剂 — 溶解/与材料相互作用
0	差溶剂 — 无相互作用

分级评分 (1 – 6)

评分	含义
1	完全溶解
2	大部分溶解
3	部分溶解/溶胀
4	轻微相互作用
5	很少或没有相互作用
6	完全无效

注意：只有已分配评分的溶剂才会包含在 HSP 拟合中。未评分的行在图表中显示为灰色，算法将忽略它们。

评分列键盘快捷键

按键	操作
`Enter` 或 `↓`	移动到下一行
`Shift+Enter` 或 `↑`	移动到上一行

4.7 行颜色编码

高亮	含义
红色背景	错误内 — 溶剂被评为差但落在球体内（RED ≤ 1）
琥珀/黄色背景	错误外 — 溶剂被评为好但落在球体外（RED > 1）

4.8 添加自定义溶剂

溶剂表格底部始终显示一个空行，用于输入不在内置数据库中的溶剂——例如专有溶剂混合物或您自己测量了 HSP 值的材料。

填写该行中的四个可编辑字段：

字段	描述
溶剂	自由文本名称（任意标签）
δD	色散汉森参数（MPa½）
δP	极性汉森参数（MPa½）
δH	氢键汉森参数（MPa½）

一旦四个字段都包含有效值，最左列的 + 按钮就会激活。点击它——或在任何输入字段中按 Enter——以确认该行。自定义溶剂将以空白评分添加到溶剂格，空行重置以准备下一条输入。

注意：自定义溶剂不存储在内置溶剂数据库中。它们存在于当前会话溶剂格中，使用保存到数据库时会与其他溶剂一起保存。重新加载溶剂格时它们将正常恢复。

5. HSP 拟合

5.1 执行拟合

一旦至少一种溶剂分配了评分，拟合面板中的拟合 HSP 按钮就会激活，并在括号中显示已评分溶剂的数量，例如 拟合 HSP（42 种溶剂）。

5.2 拟合参数

内部阈值

内部阈值选择器（值 1–6）设置溶剂在拟合期间被视为在球体内部所需的最低评分。

1 球体 / 2 球体切换

1 球体 / 2 球体切换控制算法是否同时拟合一个或两个独立的 HSP 球体。双球体拟合适用于具有双峰溶解行为的材料。

5.3 查看结果

列	描述
δD	球体中心的色散汉森参数（MPa½）
δP	球体中心的极性汉森参数（MPa½）
δH	球体中心的氢键汉森参数（MPa½）
R₀	拟合球体的半径（MPa½）

指标	描述
准确率	球体正确分类的溶剂百分比（越高越好）
拟合度	HSPiPy 的 DATAFIT 指标 — 反映拟合质量的 0 到 1 的分数（越接近 1 越好）
误差	优化残差误差（越低越好）

5.4 表面探索器

探索表面按钮（在成功拟合后可用）打开表面溶剂对话框。它查询内置溶剂数据库，寻找靠近拟合球体边界的溶剂。

6. 可视化

6.1 3D 视图

颜色	含义
灰色（半透明）	未评分溶剂
蓝色	好溶剂（评分 ≥ 内部阈值）
红色	差溶剂（评分 < 内部阈值，评分 > 0）
绿色线框 + 点	拟合 HSP 球体中心

6.2 2D 视图

子图	坐标轴
左侧 — P vs H	x = P, y = H
中间 — H vs D	x = H, y = D
右侧 — P vs D	x = P, y = D

6.3 2D/3D 组合视图

2D/3D 模式同时显示 3D 散点图和三个 2D 子图。拟合面板重新定位到 3D 图的右侧以节省垂直空间。

6.4 与图表交互

操作	效果
点击 + 拖动	旋转（3D）或平移（2D）
滚轮	放大/缩小
双击	重置视图到默认缩放
悬停在点上	显示溶剂名称和坐标
工具栏（图表右上角）	相机（PNG 下载）和主页（重置视图）

7. 设置

点击窗口右上角的⚙ 设置图标打开设置对话框。

语言

选项	语言
English	英语
Español	西班牙语
中文	简体中文

更改立即生效。所选语言将被保存并在下次启动时恢复。

始终以英语显示溶剂名称

语言选择器正下方的复选框。启用后，无论选择何种界面语言，内置数据库中的所有溶剂名称都将以英语显示。适用于使用西班牙语或中文工作但需要溶剂名称与已发表文献或实验室文档一致的情况。该设置在会话之间持久保存。

主机和端口

字段	默认值	描述
主机	`127.0.0.1`	后端服务器监听的网络地址。使用 `127.0.0.1` 保持仅本地访问（推荐）。
端口	`8000`	后端 API 运行的 TCP 端口。如果端口 8000 已被占用，请更改此设置。

注意：主机和端口更改需要重启应用程序才能生效。

API 密钥

可选的密钥，必须包含在所有对后端 API 的请求中。当服务器暴露在本地主机之外时很有用。

拟合超时

拟合操作被中止并返回超时错误之前允许运行的最大秒数。设为 0 可完全禁用限制。默认值为 60 秒，对于大多数数据集已足够；非常大的溶剂格或较慢的机器可能需要更高的值。

默认导出目录

导出溶剂格（CSV 或 Excel）时本地保存对话框打开的文件夹。如果留空，则使用系统默认目录（通常为下载）。点击浏览选择文件夹。

关于

设置对话框还显示应用程序版本以及以下链接：最终用户许可协议、隐私政策和第三方许可证。

8. 故障排除

应用程序长时间显示启动画面

首次启动时，配置向导（语言、EULA、许可证）会在后端启动之前出现——这是正常的。应用程序持续轮询后端，没有固定超时。macOS 首次启动时可能需要更长时间，系统会验证后端组件。如果启动耗时过长，点击取消退出，然后在终端中运行 xattr -cr /Applications/hsp-desktop.app 后重新启动应用。在所有平台上，请检查端口 8000 是否被其他应用程序占用。

EULA 或语言选择对话框持续出现

语言偏好、EULA 接受记录和许可证数据均存储在本地。如果任何数据被清除，相应步骤将在下次启动时再次出现。完成该步骤即可恢复正常。

我的许可证密钥不被接受

确保您已复制完整密钥，没有前导或尾随空格。
检查密钥是否已在允许的最大席位数上使用。
验证您的互联网连接 — 激活需要调用许可证服务器。
如果问题持续，请联系支持。

评分未被保存

评分列只存储整数值。二元评分使用 0 或 1；分级评分使用 1–6。

拟合精度低

检查内部阈值是否与您的评分约定匹配。
数据集较小（少于约 6 个已评分溶剂）会给出不可靠的结果。
如果好溶剂似乎聚集在图表的两个不同区域，请尝试2 球体模式。
使用表面探索器在球体边界附近找到额外溶剂并评分。

我无法重命名或复制溶剂格

这些操作要求溶剂格已保存在数据库中。请先使用保存到数据库按钮保存，然后再重命名或复制。

表面探索器未返回结果

必须先运行拟合才能使用探索器。
如果容差非常窄（例如 ±0.05），可能很少或没有溶剂在范围内。增大容差滑块。