HSP Desktop — Manual de Usuario

Versión: 1.0.0  ·  Tecnología: HSPiPy v1.1.8

1. Introducción

HSP Desktop es una aplicación de escritorio para calcular y visualizar los Parámetros de Solubilidad de Hansen (HSP). Permite construir un conjunto de datos de solventes, calificar cada solvente por su compatibilidad con un material de interés, ajustar una esfera HSP (o dos esferas simultáneamente) y ver el resultado al instante en un gráfico interactivo 3D o 2D.

La ciencia está impulsada por HSPiPy, una librería de Python que implementa el algoritmo de optimización de esferas HSP. La aplicación envuelve esa librería en una interfaz de escritorio nativa disponible para Windows, macOS y Linux. Al adquirir HSP Desktop, apoya directamente el desarrollo continuo de HSPiPy como proyecto de código abierto.

Capacidades principales:

• Acceso a una base de datos integrada de cientos de solventes con datos HSP completos
• Calificación manual de solventes en una escala de 0 a 6
• Ajuste de esfera HSP con un clic, con métricas de precisión y DATAFIT
• Ajuste simultáneo de dos esferas HSP
• Explorador de Superficie: encuentra solventes de la base de datos cerca del límite de la esfera y los añade a la malla
• Generación de gradientes de solvente (mezclas de dos solventes a distintas proporciones)
• Importar desde archivos .csv, .hsd y .hsdx
• Exportar a CSV o Excel
• Guardar y recargar mallas con nombre desde una base de datos local (los resultados del ajuste se guardan junto con los datos)
• Interfaz disponible en inglés, chino (简体中文) y español

2. Instalación y Primer Inicio

Instalación

Haz doble clic en el instalador (.msi en Windows, .dmg en macOS, .deb en Linux) y sigue los pasos en pantalla. La aplicación se instala en el directorio de usuario y no requiere privilegios de administrador.

Advertencias de seguridad (app sin firmar)

HSP Desktop se distribuye actualmente sin un certificado de firma de código. Tu sistema operativo mostrará una advertencia de seguridad la primera vez que instales o abras la app. Es algo esperado — sigue los pasos a continuación para continuar.

Si tienes algún problema durante la instalación, contacta con support@g-npd.com.

Pantalla de Inicio

Al abrir la aplicación, se muestra una pantalla de inicio. En el primer inicio, un diálogo de configuración te guía por tres pasos: selección de idioma, revisión del Acuerdo de Licencia (EULA) y activación de licencia. Un indicador de progreso en la parte superior del diálogo muestra en qué paso te encuentras, y puedes volver al paso de idioma en cualquier momento haciendo clic en Atrás en el paso del EULA. Una vez completados todos los pasos, el backend se inicia automáticamente y una barra de progreso animada con mensajes de estado rotativos confirma que el arranque está en curso. En la mayoría de sistemas esto tarda entre 3 y 10 segundos; en macOS el primer inicio puede tardar unos segundos más mientras el sistema verifica el componente backend. En la parte inferior se muestra un botón Cancelar — al hacer clic se cierra la aplicación limpiamente.

Si el Backend No Inicia

La aplicación consulta el backend de forma continua sin tiempo límite, por lo que una máquina lenta seguirá teniendo éxito con suficiente tiempo. Si algo falla de verdad, haz clic en Cancelar para salir y prueba lo siguiente:

• Solo macOS — ejecuta xattr -cr /Applications/hsp-desktop.app en Terminal y vuelve a abrir la app.
• Comprueba que el puerto 8000 no esté ya en uso por otra aplicación.
• Vuelve a abrir la app — si el backend se cerró inesperadamente puede haber dejado un proceso activo.
• Contacta con support@g-npd.com e incluye el registro del backend (haz clic en Reintentar y luego en Actualizar Registro en el panel de error).

2.1 Selección de Idioma

En el primer inicio, aparece un diálogo de configuración con un indicador de tres pasos en la parte superior. El primer paso te pide que selecciones el idioma de la interfaz.

Haz clic en una de las tres opciones — el diálogo avanza inmediatamente al siguiente paso. Si necesitas cambiar tu selección, haz clic en Atrás en el paso del EULA para volver aquí.

El idioma seleccionado se recuerda en futuros inicios y también puede cambiarse en cualquier momento desde Configuración.

2.2 Acuerdo de Licencia (EULA)

El segundo paso muestra el Acuerdo de Licencia de Usuario Final. Debes:

1. Leer el Acuerdo de Licencia de Usuario Final (desplázate por el cuadro de texto).
2. Marcar la casilla "He leído y acepto el Acuerdo de Licencia".
3. Hacer clic en Aceptar y Continuar.

Si seleccionaste el idioma incorrecto en el paso anterior, haz clic en Atrás para volver al selector de idioma.

La aceptación se almacena localmente; este paso no vuelve a aparecer en lanzamientos posteriores.

Al pie se proporcionan enlaces al EULA completo y la Política de Privacidad.

2.3 Activación de Licencia

El tercer paso activa tu licencia. Si ya hay una licencia válida almacenada en tu máquina, este paso se omite automáticamente y el backend comienza a cargar.

Para activar:

1. Localiza la clave de licencia en el correo de confirmación de compra (formato: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).
2. Pega o escribe la clave en el campo de entrada.
3. Haz clic en Activar (o pulsa Enter).

La aplicación contacta al servidor de licencias para validar la clave. Una vez validada, el diálogo se cierra y el backend comienza a cargar automáticamente — la barra de progreso se inicia y la interfaz principal carga cuando el backend está listo.

Si la clave es rechazada, aparece un mensaje de error debajo del campo. Comprueba que la clave esté completa y sin modificar, y vuelve a intentarlo.

3. Vista General de la Interfaz

La ventana principal está dividida en dos paneles redimensionables separados por un divisor arrastrable.

┌─────────────────────────────┬──────────────────────────────────────┐
│                             │                          📄  ⚙       │
│   Malla de Solventes        │  [ 3D | 2D | 2D/3D ]                 │
│   ─────────────────────     │                                      │
│   Barra de herramientas     │   Gráfico 3D / 2D                    │
│                             │                                      │
│   ┌─────────────────────┐   │                                      │
│   │ Tabla de solventes  │   ├──────────────────────────────────────┤
│   │ (desplazable)       │   │   Panel de Ajuste                    │
│   └─────────────────────┘   │   δD δP δH R₀ | Ajustar HSP         │
└─────────────────────────────┴──────────────────────────────────────┘

Puedes arrastrar el divisor vertical hacia la izquierda o derecha para redimensionar los paneles.

4. La Malla de Solventes

4.1 Crear y Gestionar Mallas

La barra de herramientas en la parte superior del panel izquierdo contiene un selector desplegable y una fila de botones de icono.

Selector desplegable

Haz clic en el desplegable para ver todas las mallas guardadas en la base de datos local. Haz clic en el nombre de una malla para cargarla. Si hay cambios sin guardar en la malla actual, un diálogo de confirmación preguntará si deseas descartarlos.

Dentro del desplegable también hay un área para crear una nueva malla: escribe un nombre en el campo de texto y pulsa Nueva.

Botones de icono (de izquierda a derecha)

El icono de guardar se vuelve ámbar cuando la malla tiene cambios sin guardar.

Al guardar una malla, los resultados del ajuste HSP actuales (si los hay) se almacenan junto con los datos de solventes y se restauran automáticamente al recargar la malla.

4.2 Añadir Solventes desde la Base de Datos

Haz clic en el botón círculo azul ＋ en el lado derecho de la barra de herramientas para abrir el selector de solventes.

El selector muestra la base de datos de solventes integrada completa. Dos características ayudan a encontrar solventes rápidamente:

• Barra de búsqueda — escribe cualquier parte del nombre del solvente o su número CAS; la tabla filtra en tiempo real.
• Selector HSP / COMPLETO — en modo HSP solo se muestran las columnas δD, δP, δH y CAS; cambia a COMPLETO para ver propiedades adicionales: volumen molar, punto de ebullición, peso molecular, viscosidad, calor de vaporización y SMILES.

Selecciona una o más filas usando las casillas de verificación. Los solventes ya presentes en la malla actual aparecen atenuados y no se pueden seleccionar de nuevo. Cuando estés listo, haz clic en Añadir Seleccionados (n).

4.3 Añadir Gradientes de Solvente

Haz clic en el botón círculo azul ⤢ para abrir el selector de gradientes. Esta herramienta genera una serie de filas de mezcla entre dos solventes a proporciones de mezcla igualmente espaciadas.

1. Usa la barra de búsqueda para filtrar la lista de solventes.
2. Haz clic en un solvente para marcarlo como A (etiqueta azul).
3. Haz clic en un segundo solvente para marcarlo como B (etiqueta verde).
4. Establece el valor de Paso (%) — p. ej., 10 genera mezclas al 0:100, 10:90, 20:80, … 100:0.
5. Una tabla de vista previa muestra los valores HSP calculados para cada mezcla.
6. Haz clic en Añadir n fila(s) para insertar el gradiente en la malla.

Los nombres de fila generados siguen el patrón SolventeA:SolventeB proporción_A:proporción_B, p. ej. Ethanol:Water 30:70.

4.4 Importar Archivos

Haz clic en el botón Abrir (icono de carpeta) para importar datos. Formatos soportados:

El nombre del archivo (sin extensión) se usa como nombre de la malla. Los datos importados se consideran sin guardar hasta que los guardes explícitamente en la base de datos.

4.5 Exportar Datos

Pasa el cursor o haz clic en el icono de exportar (↗) para elegir el formato:

• Exportar como CSV — un archivo .csv plano con todas las columnas incluyendo los valores RED calculados.
• Exportar como Excel — un archivo .xlsx adecuado para análisis adicional en hojas de cálculo.

El archivo se guarda en la carpeta de Descargas con el nombre de la malla como nombre de archivo.

4.6 Calificar Solventes

La columna Grade es la única columna editable en la tabla. Acepta valores enteros y representa la compatibilidad experimentalmente observada de cada solvente con el material objetivo.

Se admiten dos convenciones de calificación — elige la que corresponda a tus datos experimentales y establece el Límite Interior en consecuencia (ver Sección 5.2):

Calificación binaria (0 / 1)

Establece Límite Interior = 1 con esta convención.

Calificación graduada (1 – 6)

Establece el Límite Interior en el umbral que separa "buenos" de "malos" para tu material.

Atajos de teclado en la columna Grade

4.7 Código de Colores de Filas

Después de ejecutar un ajuste, las filas cuyo Grade experimental no coincide con la predicción de la esfera se resaltan:

4.8 Añadir Solventes Personalizados

La parte inferior de la tabla de solventes siempre muestra una fila vacía para introducir un solvente que no está en la base de datos integrada — por ejemplo, una mezcla propietaria o un material cuyos parámetros HSP has medido tú mismo.

Rellena los cuatro campos editables de esa fila:

Una vez que los cuatro campos contienen valores válidos, el botón + de la columna más a la izquierda se activa. Haz clic en él — o pulsa Enter en cualquiera de los cuatro campos — para confirmar la fila. El solvente personalizado se añade a la malla con un Grade en blanco, y la fila vacía se restablece para la siguiente entrada.

5. Ajuste HSP

5.1 Ejecutar un Ajuste

Una vez que al menos un solvente tenga un Grade asignado, el botón Ajustar HSP en el Panel de Ajuste se activa y muestra el número de solventes calificados entre paréntesis, p. ej. Ajustar HSP (42 solventes).

Haz clic en Ajustar HSP para ejecutar la optimización. El botón muestra un indicador de carga mientras se realiza el cálculo.

5.2 Parámetros de Ajuste

Límite Interior

El selector de Límite Interior (valores 1–6) establece el Grade mínimo que debe tener un solvente para considerarse dentro de la esfera durante el ajuste.

• Límite Interior = 1 — usar con calificación binaria (0/1).
• Límite Interior = 1–5 — los solventes con Grade igual o superior al límite se tratan como dentro de la esfera; los de Grade inferior están fuera.

Selector 1 Esfera / 2 Esferas

El selector 1 Esfera / 2 Esferas controla si el algoritmo ajusta una o dos esferas HSP independientes simultáneamente. El ajuste de dos esferas es útil para materiales con comportamiento de solubilidad bimodal.

5.3 Interpretar los Resultados

Tabla de resultados

Estadísticas

Contadores de solventes

El valor RED (Diferencia de Energía Relativa) de cada solvente se muestra en la columna RED de la tabla tras el ajuste. RED < 1 significa que el solvente está dentro de la esfera; RED > 1 significa que está fuera.

5.4 Explorador de Superficie

El botón Explorar Superficie (disponible tras un ajuste exitoso) abre el modal de Solventes en la Superficie. Consulta la base de datos de solventes integrada en busca de solventes que se encuentren cerca del límite de la esfera ajustada.

Controles

Flujo de trabajo recomendado

1. Ejecutar un ajuste inicial.
2. Abrir el Explorador de Superficie y filtrar a Solo exterior.
3. Seleccionar solventes que puedas probar experimentalmente y añadirlos a la malla.
4. Calificar los solventes añadidos (0 si no disuelven el material).
5. Reajustar — los solventes malos adicionales fuera de la esfera ayudan a empujar el límite hacia adentro.

6. Visualización

6.1 Vista 3D

La vista 3D muestra todos los solventes como puntos en el espacio de solubilidad de Hansen (ejes: D, H, P). Tras un ajuste, la esfera HSP se dibuja como una malla de alambre verde.

6.2 Vista 2D

La vista 2D muestra tres proyecciones 2D del espacio de solventes en paralelo.

6.3 Vista Combinada 2D/3D

El modo 2D/3D muestra tanto el gráfico de dispersión 3D como los tres subgráficos 2D al mismo tiempo. El panel de ajuste se reposiciona a la derecha del gráfico 3D para ahorrar espacio vertical.

6.4 Interactuar con los Gráficos

7. Configuración

Haz clic en el icono ⚙ de configuración en la esquina superior derecha de la ventana para abrir el modal de Configuración.

Idioma

El cambio tiene efecto inmediato. El idioma seleccionado se guarda y se restaura en el siguiente inicio.

Mostrar siempre los nombres de solventes en inglés

Una casilla de verificación justo debajo del selector de idioma. Cuando está activada, todos los nombres de solventes de la base de datos integrada se muestran en inglés independientemente del idioma de la interfaz seleccionado. Útil cuando se trabaja en español o chino pero se necesita que los nombres de solventes coincidan con la literatura publicada o la documentación del laboratorio. El ajuste se guarda entre sesiones.

Host y Puerto

Clave API

Una clave secreta opcional que debe incluirse en todas las solicitudes a la API backend. Útil cuando el servidor está expuesto más allá de localhost.

Tiempo límite de ajuste

Número máximo de segundos que puede durar una operación de ajuste antes de cancelarse y devolver un error de tiempo de espera. Establece 0 para desactivar el límite. El valor predeterminado es 60 segundos, suficiente para la mayoría de los conjuntos de datos; las mallas muy grandes o las máquinas lentas pueden requerir un valor mayor.

Directorio de exportación predeterminado

La carpeta a la que se abre el diálogo nativo de guardado al exportar una malla (CSV o Excel). Si se deja vacío, se usa el predeterminado del sistema (normalmente Descargas). Haz clic en Examinar para seleccionar una carpeta.

Acerca de

El modal de Configuración también muestra la versión de la aplicación y enlaces al EULA, la Política de Privacidad y las Licencias de Terceros.

8. Solución de Problemas

La aplicación muestra la pantalla de inicio durante mucho tiempo

En el primer inicio, el diálogo de configuración (idioma, EULA, licencia) aparece antes de que el backend arranque — esto es lo esperado. La aplicación consulta el backend de forma continua sin tiempo límite. En macOS el primer inicio puede tardar más mientras el sistema verifica el componente backend. Si el arranque tarda demasiado, haz clic en Cancelar para salir y ejecuta xattr -cr /Applications/hsp-desktop.app en Terminal antes de volver a abrir la app. En todos los sistemas, comprueba que el puerto 8000 no esté en uso por otra aplicación.

El diálogo de EULA o de idioma sigue apareciendo

La preferencia de idioma, la aceptación del EULA y los datos de licencia se almacenan localmente. Si alguno de estos datos se elimina, el paso correspondiente vuelve a aparecer en el siguiente inicio. Completa el paso de nuevo para continuar con normalidad.

Mi clave de licencia no es aceptada

• Asegúrate de haber copiado la clave completa sin espacios al inicio o al final.
• Verifica que la clave no se haya usado ya en el número máximo de puestos permitidos.
• Comprueba tu conexión a internet — la activación requiere contactar al servidor de licencias.
• Contacta con soporte si el problema persiste.

Los grades no se están guardando

La columna Grade solo almacena valores enteros. Para calificación binaria usa 0 o 1; para calificación graduada usa 1–6. Los valores fuera del rango válido o la entrada no numérica se descartan silenciosamente.

El ajuste produce baja precisión

• Comprueba que el Límite Interior coincida con tu convención de calificación.
• Un conjunto de datos pequeño (menos de ~6 solventes calificados) da resultados poco fiables.
• Prueba el modo 2 Esferas si los buenos solventes parecen agruparse en dos regiones distintas.
• Usa el Explorador de Superficie para encontrar solventes adicionales cerca del límite de la esfera.

No puedo renombrar ni duplicar una malla

Estas operaciones requieren que la malla esté guardada en la base de datos. Una malla importada desde un archivo o recién creada pero no guardada aún no tiene un ID en la base de datos. Guárdala primero con el botón Guardar en BD.

El archivo exportado no abre en Excel

Asegúrate de que el formato de exportación sea Exportar como Excel (.xlsx) en lugar de CSV.

El Explorador de Superficie no devuelve resultados

• Se debe ejecutar un ajuste antes de poder usar el explorador.
• Si la tolerancia es muy estrecha (p. ej. ±0.05), puede que pocos o ningún solvente caiga dentro de la banda. Aumenta el deslizador de tolerancia.