Boltz-2estructuras biomoleculares y afinidad proteína-ligando

Si estás investigando una proteína y quieres decidir qué ligandos merece la pena ensayar, necesitas relacionar dos preguntas. Primero debes examinar cómo podría acomodarse cada molécula en la diana. Después puedes valorar qué estimación de unión resulta útil para priorizarla. Boltz-2 reúne predicción estructural y estimación de afinidad, de modo que puedes estudiar la geometría propuesta junto con los resultados que utilizarás para comparar compuestos.

Esta guía recorre ese proceso desde la definición del sistema molecular hasta la revisión de sus resultados. Aprenderás a describir la proteína y el ligando, elegir cómo aportar información evolutiva, ajustar el cálculo y recuperar las salidas mediante un despliegue de Boltz-2 en QDivZero. Para que la comparación tenga sentido, iremos relacionando cada decisión con lo que cambia en la predicción y con la evidencia que necesitas conservar. Los ejemplos siguen la integración basada en Boltz 2.2.1.

Puedes practicar primero con la demo de la página, que permite configurar una solicitud y explorar una estructura de referencia en 3D. Cuando quieras predecir tus propias moléculas, los ejemplos de integración utilizan la URL y la clave de tu cuenta para enviar el trabajo a tu servicio real.

#Qué es Boltz-2 y para qué sirve

Boltz-2 es un modelo de inteligencia artificial de código abierto para predecir estructuras biomoleculares y afinidad proteína-ligando. Si necesitas proponer cómo se organiza una proteína o cómo podría interactuar con otras moléculas, puedes describir sus componentes y obtener una estructura tridimensional. Si tu estudio busca además comparar moléculas pequeñas frente a una proteína, su módulo de afinidad añade estimaciones de unión a ese análisis. Esta segunda capacidad amplía el modelado estructural de Boltz-1, como explica el repositorio oficial de Boltz.

El alcance de la tarea depende de las moléculas que estudies. Para modelar estructuras puedes incluir proteínas, ADN, ARN y ligandos, cuyas secuencias o identidades químicas se transforman en coordenadas atómicas que podrás guardar en mmCIF o PDB. La estimación de afinidad se dirige a moléculas pequeñas frente a proteínas, por lo que un sistema admitido para predicción estructural no necesariamente sirve para calcular afinidad. Conviene comprobar esta compatibilidad antes de preparar una campaña, siguiendo la documentación oficial de predicción.

Aplicaciones en investigación y áreas de trabajo

En biología estructural, la estructura propuesta permite examinar interfaces y plantear qué contactos estudiar experimentalmente. En descubrimiento de fármacos, puedes combinar la revisión de poses con las estimaciones de unión para seleccionar candidatos de un cribado virtual. Cuando ya trabajas con una serie de compuestos activos, el objetivo cambia a comprender qué modificaciones podrían mejorar su comportamiento, una aplicación propia de química medicinal. Estas tareas comparten el modelo, pero requieren criterios de comparación distintos.

Considera, por ejemplo, dos análogos que quieres comparar frente a la misma proteína. Si cambias también la secuencia proteica, el MSA o el protocolo de muestreo, será más difícil atribuir una diferencia al cambio químico. En esta guía mantendremos esos elementos bajo control, revisaremos la pose de cada ligando y elegiremos la salida de afinidad que responda a la pregunta. El resultado te ayudará a formular y priorizar hipótesis para el laboratorio. La eficacia clínica, la toxicidad y las propiedades farmacocinéticas requieren evaluaciones adicionales.

Proyecto, autores y fuentes oficiales

Para incorporar el modelo a un flujo de investigación, conviene identificar su procedencia y la versión que vas a ejecutar. El equipo de Boltz en MIT Jameel Clinic desarrolló Boltz-2 junto a Recursion y lo presentó el 6 de junio de 2025. La presentación oficial recoge el equipo y el objetivo del proyecto, mientras que la publicación científica, con DOI 10.1101/2025.06.14.659707, describe su evaluación.

El código y los pesos se distribuyen bajo licencia MIT, que permite usos académicos y comerciales sujetos a sus condiciones. Puedes consultar la licencia del repositorio y los archivos del modelo en Hugging Face para documentar esos componentes de tu experimento. Si ejecutas el modelo en una infraestructura GPU, esa capacidad se factura por separado de la licencia.

En los ejemplos utilizaremos Boltz 2.2.1, la versión del paquete de software que usa la integración descrita. Boltz-2 identifica el modelo, por lo que conservar ese nombre no basta para repetir un cálculo. Debes registrar también la versión del software y la revisión concreta de los pesos que emplees.

Limitaciones señaladas por sus desarrolladores

Antes de aplicar el flujo a una diana nueva, ten en cuenta las limitaciones de la sección 6 de la publicación original. La estructura puede fallar en grandes complejos y cambios conformacionales importantes. La afinidad depende de la pose y su módulo no incorpora explícitamente iones, agua ni socios multiméricos, mientras que el recorte puede excluir interacciones relevantes. La generalización entre ensayos y a proteínas o moléculas alejadas del entrenamiento requiere más estudio. La diversidad conformacional aprendida de simulaciones también sigue siendo parcial.

Estas limitaciones ayudan a delimitar qué sistemas conviene estudiar. La documentación de afinidad permite solicitarla para una sola molécula pequeña y advierte que resulta poco fiable frente a ADN, ARN o un cofactor. También debes revisar el tamaño del ligando. Los desarrolladores desaconsejan moléculas significativamente mayores de 56 átomos, aunque el parser acepta hasta 128, contando átomos pesados y los hidrógenos conservados por RemoveHs de RDKit. El parser de Boltz 2.2.1 recoge ambos límites y su advertencia.

Como recomendación de trabajo, empieza con un sistema conocido y resultados experimentales de referencia. Ese caso te permitirá detectar problemas de secuencia, preparación química, MSA o pose antes de interpretar compuestos nuevos. Los siguientes apartados explican cómo aportar esa información y distinguen las capacidades del modelo de los límites que aplica la API de QDivZero.

#Entender qué calcula Boltz-2

Para estudiar la posición de un ligando respecto a una proteína, primero necesitas una propuesta de geometría conjunta. Boltz-2 la genera a partir de la secuencia de aminoácidos, la identidad química del ligando y la información adicional que aportes. Durante la predicción utiliza un proceso de difusión que refina sucesivamente unas coordenadas inicialmente ruidosas hasta producir una posible estructura del sistema.

Como una propuesta aislada puede dejar dudas sobre la orientación de las cadenas o del ligando, puedes solicitar varias muestras y comparar sus geometrías. Cada muestra constituye una posible estructura, acompañada de métricas que ayudan a valorar la confianza del modelo. Esta revisión permite detectar regiones o interfaces inciertas, aunque una geometría plausible y una confianza alta no demuestran que el complejo exista en las condiciones de tu ensayo.

Si además necesitas priorizar compuestos, el módulo de afinidad proporciona dos salidas con objetivos diferentes. Una ayuda a distinguir moléculas que podrían unirse de controles que no se unen, mientras que la otra está orientada a comparar compuestos activos y sus modificaciones. Más adelante elegiremos entre ambas según estés realizando un cribado inicial o trabajando con una serie conocida. En QDivZero, ese cálculo requiere proteínas y exactamente una cadena de ligando de molécula pequeña. La plataforma rechaza solicitudes de afinidad con ADN, ARN o ligandos CCD multirresiduo.

#Preparar el experimento y el despliegue

Define el sistema molecular que vas a estudiar

La primera decisión consiste en concretar qué comparación quieres hacer. Para examinar la posición y orientación de un ligando, conocidas como su pose, debes representar las moléculas que intervienen en ese complejo. Si vas a comparar dos análogos, prepara un sistema por compuesto y conserva la misma proteína y el mismo protocolo. Así podrás relacionar los cambios de estructura o afinidad con la modificación química que estás investigando.

Esa comparación empieza por la secuencia proteica. Identifica la especie, la isoforma y el constructo experimental, es decir, la versión de la proteína utilizada en el ensayo. Un experimento con un dominio recortado, una variante o etiquetas y modificaciones puede no corresponder a la secuencia completa de UniProt. Tampoco debes asumir que la secuencia de una estructura del Protein Data Bank sea idéntica, porque puede incluir truncamientos, mutaciones o residuos ausentes. Revisa esas diferencias para que el documento describa el sistema que realmente quieres modelar.

Aplica el mismo criterio al ligando. Conserva su identificador en el proyecto y comprueba estructura, estereoquímica, carga y representación de sales antes de codificarlo. Aunque Boltz pueda interpretar un SMILES, ese texto podría representar una especie química distinta de la relevante para tu ensayo. Registrar cómo has preparado cada molécula te permitirá revisar después si una diferencia procede del compuesto o de su preparación.

Crea un servicio de Boltz-2

Una vez definido el sistema, necesitas capacidad de cómputo para ejecutar el modelo. En el asistente de despliegue de QDivZero, selecciona boltz-community/boltz-2 y revisa las estimaciones de GPU y almacenamiento teniendo en cuenta el tamaño y la composición de tus moléculas. Cada instancia utiliza una GPU NVIDIA compatible, pero la memoria necesaria también depende del sistema que vayas a predecir.

Para mantener los mismos pesos durante una comparación, elige una revisión de commit concreta y regístrala junto con las solicitudes. QDivZero prepara las dependencias y los checkpoints, los archivos que contienen esos pesos, en el entorno de ejecución. De este modo puedes enviar trabajos desde Developers o desde un cliente de la API sin instalar Boltz ni CUDA en tu ordenador.

Asigna al despliegue un nombre de servicio, como fold, para poder dirigirle las solicitudes. En los ejemplos ese nombre será el valor de model, aunque también puedes utilizar el UUID de la instancia. El repositorio boltz-community/boltz-2 permite elegir el modelo al crear el despliegue, mientras que el nombre de servicio permite seleccionar la instancia que lo ejecutará dentro de tu cuenta.

Para utilizarla desde la terminal, configura la URL base y una clave API de cuenta con acceso al despliegue. Sustituye el host de ejemplo por el que aparece en tu integración y mantén abierta esa terminal, ya que los comandos de los siguientes apartados utilizan estas variables.

1export QDIV0_API_URL='https://api.example.com'
2export QDIV0_API_KEY='REEMPLAZA_CON_TU_CLAVE_DE_CUENTA'
3

Al organizar los ensayos, ten en cuenta que el despliegue dedicado se factura mientras mantiene capacidad activa. Los trabajos en cola o en ejecución impiden la parada automática por inactividad para que puedan completarse. Si necesitas detener manualmente el servicio, espera a que terminen, porque esa parada puede interrumpirlos.

#Construir la entrada molecular

Distingue la molécula de los parámetros de ejecución

Para comparar configuraciones sin cambiar accidentalmente el sistema molecular, la solicitud separa lo que vas a estudiar de cómo vas a calcularlo. Describe las moléculas en input mediante el esquema nativo de Boltz, versión 1, y conserva ese bloque cuando quieras repetir el cálculo con otros parámetros. Los ajustes de ejecución se incluyen en options y el campo model dirige el trabajo al servicio que acabas de crear. Si aportas alineamientos o estructuras de referencia, sus archivos se envían en attachments.

El documento siguiente reúne esas piezas para una proteína identificada como A y un ligando identificado como B, cuya afinidad se solicita. Guárdalo como request.json para utilizarlo tanto en la revisión de parámetros como en el envío por la API. Al comparar tus propios compuestos, conserva una copia por sistema para poder relacionar cada resultado con la solicitud que lo produjo.

El ejemplo utiliza el segmento de estreptavidina observado en PDB 1STP y el SMILES estereoquímico de la biotina. Sus 121 residuos corresponden a las posiciones 13 a 133 del depósito. Esta representación de una cadena permite aprender el flujo, pero el complejo biológico es un tetrámero. Para investigar ese ensamblaje debes definir explícitamente las cadenas y el constructo pertinentes, además de preparar un MSA adecuado.

1{
2  "model": "fold",
3  "input": {
4    "version": 1,
5    "sequences": [
6      {
7        "protein": {
8          "id": "A",
9          "sequence": "AEAGITGTWYNQLGSTFIVTAGADGALTGTYESAVGNAESRYVLTGRYDSAPATDGSGTALGWTVAWKNNYRNAHSATTWSGQYVGGAEARINTQWLLTSGTTEANAWKSTLVGHDTFTKV",
10          "msa": "empty"
11        }
12      },
13      {
14        "ligand": {
15          "id": "B",
16          "smiles": "C1[C@H]2[C@@H]([C@@H](S1)CCCCC(=O)O)NC(=O)N2"
17        }
18      }
19    ],
20    "properties": [
21      {
22        "affinity": {
23          "binder": "B"
24        }
25      }
26    ]
27  },
28  "options": {
29    "sampling_steps": 50,
30    "recycling_steps": 3,
31    "diffusion_samples": 1,
32    "sampling_steps_affinity": 200,
33    "diffusion_samples_affinity": 5,
34    "max_msa_seqs": 8192,
35    "use_msa_server": false,
36    "use_potentials": false,
37    "affinity_mw_correction": false,
38    "msa_pairing_strategy": "greedy",
39    "output_format": "mmcif",
40    "seed": 42
41  }
42}
43

Identifica las cadenas y sus copias

Si quieres estudiar un complejo con varias cadenas, debes introducir su composición completa para que Boltz modele la organización que te interesa. En sequences, cada entidad declara un tipo y su contenido, utilizando protein, dna o rna para polímeros y ligand para moléculas no poliméricas. Asigna identificadores únicos a las cadenas, porque los utilizarás después para señalar el ligando de afinidad, relacionar plantillas o definir restricciones.

Cuando varias cadenas tienen la misma secuencia, puedes describir la entidad una sola vez y declarar sus copias mediante una lista de identificadores. Por ejemplo, "id": ["A", "B"] introduce dos cadenas de esa proteína. Al hacerlo cambias la estequiometría del complejo y duplicas los residuos aportados por la entidad, de modo que esa decisión debe corresponder al ensamblaje que quieres estudiar. Si las secuencias son diferentes, utiliza entidades separadas.

Tras completar el sistema, comprueba sus límites conjuntos. QDivZero admite hasta 32 identificadores de cadena y 4096 residuos poliméricos por solicitud, contando proteínas, ADN, ARN y todas las copias repetidas. El recuento de una secuencia aislada no basta cuando has declarado varias cadenas.

Describe el ligando y solicita su afinidad

Para que la comparación represente el cambio químico que quieres investigar, el ligando debe conservar su identidad en la entrada. Si dispones de su estructura en SMILES, introdúcela en smiles. Si utilizas un componente del Chemical Component Dictionary, puedes identificarlo mediante ccd. Elige una sola representación por entidad y revisa que corresponda a la molécula preparada para tu estudio.

Incluir el ligando permite modelar el complejo proteína-ligando, pero para pedir afinidad debes señalarlo además en properties. En el ejemplo, "binder": "B" conecta esa petición con la cadena del ligando. Si solo quieres examinar la geometría, elimina properties y conserva la molécula en sequences, de modo que siga formando parte del sistema estructural.

Antes de interpretar la afinidad, revisa también la preparación química que realiza el módulo, porque estandariza el ligando antes de procesarlo. El límite nativo es de 128 átomos, contando átomos pesados y los hidrógenos conservados por RemoveHs de RDKit, y las moléculas con más de 56 átomos generan una advertencia por superar el tamaño utilizado como límite de entrenamiento. Este recuento se obtiene de la molécula preparada y no de la longitud del SMILES. En sales y mezclas de fragmentos, conserva la representación original y revisa las advertencias para comprobar qué identidad se ha utilizado. Los detalles están en el parser de Boltz 2.2.1.

#Elegir y aportar el MSA

Una vez descritas las moléculas, puedes aportar información evolutiva que ayude a modelar la proteína. Boltz utiliza para ello un alineamiento múltiple de secuencias, o MSA, que reúne secuencias relacionadas y muestra patrones de conservación y variación. Para que esa información sea pertinente, el alineamiento debe corresponder a la secuencia que has enviado. Si comparas ligandos frente a una misma proteína, mantener ese MSA permite conservar la misma entrada evolutiva durante la comparación.

Ejecutar con una sola secuencia

Al comprobar por primera vez la integración, puedes utilizar "msa": "empty" para ejecutar con una sola secuencia sin depender de un servicio externo de alineamiento. Esa es la elección del documento de ejemplo. QDivZero muestra una advertencia porque omitir información evolutiva puede reducir la precisión, por lo que un trabajo que termina correctamente solo confirma que la solicitud se ha procesado. Antes de usar sus estructuras en investigación, valora si este modo es adecuado para tu sistema o si necesitas aportar un MSA.

Solicitar generación automática

Si necesitas un alineamiento y aún no dispones de uno, puedes solicitar su generación al servicio configurado por el operador de QDivZero. Para ello elimina msa de la proteína y establece options.use_msa_server en true. Los dos cambios son necesarios, ya que conservar "msa": "empty" sigue solicitando el modo de una sola secuencia aunque actives el servidor.

Antes de enviar una campaña que dependa de ese servicio, consulta su disponibilidad con el siguiente comando. La autenticación y la dirección del proveedor se configuran en la plataforma, mientras que tu solicitud únicamente activa su uso para la predicción.

1curl --fail-with-body --get \
2  "$QDIV0_API_URL/v1/biomolecular/capabilities" \
3  -H "Authorization: Bearer $QDIV0_API_KEY" \
4  --data-urlencode 'model=fold'
5

Utiliza msa_status junto con la fecha checked_at para decidir si puedes continuar o debes revisar el servicio. El estado reachable significa que el backend ha recibido una respuesta accesible, mientras que not_configured indica que falta la configuración. Si aparece authentication_failed, unreachable o unavailable, revisa el acceso antes de repetir el trabajo. Con unknown, la comprobación no permite confirmar la disponibilidad.

Esta consulta no genera un alineamiento desde la instancia GPU, por lo que durante la ejecución todavía pueden producirse fallos de conexión o del proveedor. Además, la generación automática envía la secuencia al servicio de MSA configurado. Tenlo en cuenta al elegir cómo preparar las secuencias de tu proyecto y utiliza la opción de adjuntar alineamientos si necesitas conservar su contenido exacto.

Adjuntar un alineamiento calculado previamente

Para repetir una comparación con la misma información evolutiva, puedes aportar un MSA calculado previamente. En Developers, súbelo en Attachments y referencia su nombre en el campo msa de la proteína. Un archivo .a3m permite aportar el alineamiento de una proteína. Si necesitas emparejar secuencias entre varias cadenas, utiliza el formato CSV con las columnas sequence y key, donde una misma clave relaciona filas de los alineamientos de las distintas cadenas.

Desde la API debes enviar el contenido del archivo como texto UTF-8 en attachments, porque el servidor no puede leer una ruta de tu ordenador. El código siguiente adapta request.json para adjuntar un archivo real llamado protein.a3m y referenciarlo desde la proteína. Comprueba antes que su alineamiento corresponde exactamente a la secuencia del documento.

1import json
2from pathlib import Path
3
4request_path = Path("request.json")
5request = json.loads(request_path.read_text(encoding="utf-8"))
6protein = request["input"]["sequences"][0]["protein"]
7protein["msa"] = "protein.a3m"
8request["options"]["use_msa_server"] = False
9request["attachments"] = [{
10    "name": "protein.a3m",
11    "content": Path("protein.a3m").read_text(encoding="utf-8")
12}]
13request_path.write_text(json.dumps(request, indent=2), encoding="utf-8")
14

El nombre protein.a3m conecta la referencia molecular con el adjunto que resolverá QDivZero. Mantén esa correspondencia y utiliza extensiones en minúsculas para que el archivo se identifique correctamente. La integración admite hasta 32 adjuntos de texto UTF-8 con un tamaño conjunto máximo de 8 MiB. Si el sistema contiene varias proteínas, prepara todos los alineamientos necesarios con un criterio común, porque no se pueden mezclar MSA adjuntos y automáticos en una misma solicitud.

#Configurar el presupuesto de predicción

Después de fijar moléculas y alineamientos, decide qué necesitas observar en el resultado. Para comprobar que una solicitud se procesa puedes empezar con una configuración reducida. Para estudiar si la pose o la orientación relativa de las cadenas cambia entre propuestas, necesitarás comparar varias muestras. Boltz permite ajustar por separado el muestreo estructural y el de afinidad, así que conviene relacionar cada ajuste con esa pregunta antes de aumentar el cómputo.

Muestreo de estructura

Si quieres explorar varias propuestas del mismo sistema, aumenta diffusion_samples, que controla cuántas estructuras se generan. Al compararlas podrás examinar si mantienen la pose del ligando y la posición relativa de las cadenas. Ese acuerdo aporta contexto para la revisión, aunque no demuestra que una pose sea experimentalmente correcta.

Para ajustar el trabajo realizado dentro de cada predicción, utiliza sampling_steps y recycling_steps. El primero controla los pasos de difusión y el segundo los ciclos de refinamiento de las representaciones internas del modelo. Aumentarlos añade cómputo y puede cambiar el resultado, por lo que debes evaluar su efecto en el sistema que estudias. Pasar de 50 a 200 pasos multiplica por cuatro las iteraciones de difusión, pero no necesariamente el tiempo total, que incluye también preparación, carga del modelo, MSA y afinidad.

Muestreo de afinidad

Si tu objetivo incluye comparar estimaciones de unión, revisa también sampling_steps_affinity y diffusion_samples_affinity. Estos parámetros controlan un muestreo independiente, por lo que reducir los pasos estructurales no reduce automáticamente el cálculo de afinidad. Por esa razón, el ejemplo combina 50 pasos de estructura con 200 pasos y 5 muestras de afinidad.

Durante esa fase, Boltz 2.2.1 utiliza 5 ciclos de refinamiento y un paralelismo de 1. QDivZero no expone una opción para cambiar ese número de ciclos. Las muestras de afinidad intervienen en su propio cálculo y no representan estructuras adicionales descargables dentro del conjunto de predicciones estructurales.

La tabla permite comprobar los valores por defecto de la API y sus límites antes de enviar el documento. Todos los controles numéricos anteriores requieren enteros. Los valores por defecto se aplican al omitir una opción, mientras que el formulario de Developers comienza con 50 pasos estructurales, de modo que conviene revisar la solicitud completa si alternas entre formulario y API.

Perfiles de Developers y opciones adicionales

Para probar el flujo sin introducir cada parámetro manualmente, puedes elegir Quick, que selecciona 50 pasos estructurales, 3 ciclos de refinamiento y 1 muestra, conservando el modo MSA elegido para cada proteína. Si quieres probar 200 pasos estructurales, utiliza Research, que mantiene los 3 ciclos y la muestra única. Cuando no hay alineamientos adjuntos, Research cambia los MSA explícitamente vacíos a automáticos. Si hay adjuntos, los conserva y deja vacíos los restantes para evitar una mezcla incompatible. En ese caso, aporta los alineamientos que falten antes de realizar un estudio que dependa de ellos.

Elige el perfil por los cambios concretos que necesitas y revisa el documento resultante. Ninguno modifica por sí mismo el presupuesto de afinidad, y su nombre no certifica la calidad científica de la predicción. Si quieres comparar varias poses, deberás ajustar además el número de muestras estructurales.

Cuando la memoria limita el cálculo, max_msa_seqs permite reducir cuántas secuencias del alineamiento utiliza el modelo, a costa de información evolutiva. Si trabajas con varias proteínas y MSA automático, puedes configurar su emparejamiento mediante msa_pairing_strategy, cuyo valor por defecto es greedy y cuya alternativa es complete. Registra estas elecciones para mantenerlas constantes entre los compuestos de la comparación.

Si necesitas evaluar una guía adicional para favorecer poses físicamente plausibles, puedes activar use_potentials durante el muestreo estructural. La opción está desactivada por defecto, añade cómputo y Boltz la desactiva durante la fase de afinidad. Para explorar una corrección de la estimación de afinidad por peso molecular, utiliza affinity_mw_correction, también desactivada por defecto. Evalúa su efecto con controles de tu proyecto y aplica el mismo criterio a todos los compuestos que compares.

Para documentar el componente aleatorio del experimento, fija seed con un entero entre 0 y 4294967295. Si lo omites, el entorno de ejecución genera una semilla y la guarda en los metadatos. Conservarla ayuda a describir el cálculo, pero repetirlo también requiere registrar pesos, versiones, moléculas y MSA, como veremos al archivar los resultados.

#Incorporar estructuras de referencia y restricciones

Si ya dispones de evidencia estructural, puedes aportarla para orientar la predicción hacia la hipótesis que quieres estudiar. Una plantilla permite utilizar coordenadas de referencia de una cadena proteica. En Structure templates, selecciona un archivo CIF, mmCIF o PDB adjunto y revisa cómo se relacionan sus cadenas con las de tu solicitud antes de utilizarlo.

Esa correspondencia se expresa con chain_id para la cadena que predices y template_id para su equivalente en la plantilla. Por ejemplo, la proteína A del documento puede corresponder a la cadena X de un CIF. Comprueba secuencia y numeración, especialmente en dominios o constructos recortados, para que la referencia aporte información sobre la cadena adecuada. Si utilizas PDB, revisa también sus convenciones de subcadenas en el formato nativo de plantillas.

Cuando quieras guiar la predicción hacia la plantilla, activa force e indica en threshold la desviación permitida en ångströms. Al hacerlo introduces una hipótesis estructural más fuerte, por lo que debes registrar por qué la referencia es pertinente y qué tolerancia has elegido. Después no debes utilizar el cumplimiento de esa misma condición como una validación independiente de la predicción.

Si tu información se refiere a contactos o a un sitio de unión, puedes describirla en Constraints. Para aportar un enlace covalente, bond referencia los átomos que participan. Para relacionar dos residuos o átomos, utiliza contact. Si quieres señalar elementos de un sitio de unión para una cadena, pocket los relaciona con la cadena indicada por binder. En todos estos casos, convierte primero la numeración experimental a posiciones que comiencen en 1 dentro de la secuencia enviada.

Las restricciones contact y pocket permiten expresar la distancia mediante max_distance, con valores de 4 a 20 ångströms y 6 por defecto. Su campo force activa la guía para esa condición. Los enlaces covalentes nativos requieren nombres de átomos válidos y se admiten para residuos canónicos y ligandos CCD. Elige cada restricción a partir de una evidencia o hipótesis identificable y consérvala en el protocolo para interpretar qué información ha condicionado la geometría final.

#Practicar en Developers

Con esas decisiones claras, puedes construir la solicitud en Developers seleccionando la tarea Biomolecular y tu servicio. La pestaña Form permite definir las moléculas, aportar alineamientos y ajustar el cálculo. Cuando hayas terminado, utiliza Advanced JSON para comprobar que el documento conserva el sistema y los parámetros que pretendías enviar. Después, View code genera los ejemplos de integración correspondientes, de modo que puedas pasar de la configuración visual a un cliente de la API.

La demo siguiente permite practicar ese recorrido con una proteína y un ligando SMILES. Cambia el modo MSA, compara perfiles y revisa cómo se modifica la solicitud antes de iniciar el despliegue de prueba y enviar el trabajo. Podrás seguir los estados simulados de cola y ejecución, y utilizar View code para descargar request.json y consultar su comando de envío.

Al terminar aparece un visor que te permite familiarizarte con la revisión de una estructura. Gira el complejo, alterna entre cintas y enlaces, acércate al ligando y descarga las coordenadas en mmCIF o PDB. También puedes utilizar Abrir tu CIF o PDB para examinar archivos de una ejecución real de Boltz. El visor procesa sus coordenadas en el navegador sin enviarlas a un servidor y no calcula nuevas estructuras, confianza ni afinidad. Tanto el visor como la referencia de ejemplo se sirven desde esta web, para que no dependan de otra página.

La referencia es el complejo experimental de estreptavidina con biotina PDB 1STP, resuelto por difracción de rayos X a 2,6 Å. El formulario utiliza sus 121 residuos proteicos observados y el ligando biotina para que puedas reconocer las moléculas al explorar el visor. Este muestra la unidad asimétrica depositada, que es distinta del ensamblaje biológico tetramérico. Los identificadores A y B del documento son etiquetas de entrada propias, mientras que el archivo conserva los identificadores del depósito, que pueden diferir entre las etiquetas nativas del mmCIF y las de autor. Esa correspondencia molecular no convierte la referencia en una predicción de Boltz, ni sus factores B en valores pLDDT.

La demo simula los estados y muestra una referencia fija. Si cambias las moléculas o solicitas varias muestras, las coordenadas de ejemplo se mantienen. Para obtener tus propias estructuras y sus métricas debes enviar el trabajo a tu despliegue real. La demo tampoco comprueba la química ni la conectividad del servicio MSA.

Cuando necesites varias entidades, ligandos CCD, adjuntos, plantillas o restricciones, prepara el documento en la plataforma. Su formulario admite esas capacidades, mientras que el editor de la demo las rechaza porque no puede representarlas de forma completa.

#Enviar el trabajo por la API

Para integrar el cálculo en tu propio flujo de investigación, envía request.json a POST /v1/biomolecular/jobs con una clave API de cuenta que tenga acceso al servicio. La predicción se ejecuta de forma asíncrona, porque antes de producir las estructuras el trabajo puede necesitar preparación y generación de MSA. Por eso la respuesta inicial te proporciona un identificador con el que seguir la ejecución y recuperar después los resultados.

Antes del envío, comprueba que QDIV0_API_URL contiene la URL base de tu integración sin terminar en /v1, ya que el ejemplo añade ese segmento, y que QDIV0_API_KEY contiene tu clave. Genera además una clave de idempotencia para esta solicitud. Conservarla te permitirá reintentar el mismo envío si se pierde la respuesta y recuperar el trabajo original.

1export QDIV0_IDEMPOTENCY_KEY="$(python -c 'import uuid; print(uuid.uuid4())')"
2
3curl --fail-with-body --silent --show-error \
4  "$QDIV0_API_URL/v1/biomolecular/jobs" \
5  -H "Authorization: Bearer $QDIV0_API_KEY" \
6  -H 'Content-Type: application/json' \
7  -H "Idempotency-Key: $QDIV0_IDEMPOTENCY_KEY" \
8  --data-binary @request.json \
9  --output job.json \
10  --write-out 'HTTP %{http_code}\n'
11

Si la API admite la solicitud, el comando guarda en job.json una respuesta HTTP 202 cuyo campo id contiene el UUID del trabajo. A partir de ese momento utiliza el UUID para consultar su evolución. La admisión confirma que puedes seguir el trabajo, pero todavía debes esperar a que termine para descargar sus salidas.

Si no recibes la respuesta del envío, repite únicamente el comando cURL con el mismo archivo y la misma clave, sin regenerar QDIV0_IDEMPOTENCY_KEY. La misma solicitud normalizada y la misma clave recuperan el trabajo original. Si cambias el cuerpo manteniendo la clave, la API devuelve HTTP 409. Para probar otro compuesto u otra configuración como un experimento nuevo, utiliza una clave nueva y conserva su relación con esa solicitud.

Una vez conocido el UUID, consulta GET /v1/biomolecular/jobs/{job_id}. La respuesta permite distinguir si debes seguir esperando o revisar un resultado terminal, y contiene fechas y, cuando están disponibles, resúmenes de confianza, afinidad, metadatos y artifacts, la lista de archivos descargables.

Si necesitas interrumpir el trabajo, envía una petición a POST /v1/biomolecular/jobs/{job_id}/cancel y vuelve a consultar el estado, porque detener el proceso puede requerir tiempo. Para recuperar una salida disponible, utiliza GET /v1/biomolecular/jobs/{job_id}/artifacts/{artifact_id} con los identificadores de artifacts. El siguiente cliente automatiza la espera y estas descargas para que puedas incorporarlas a una campaña.

#Recuperar las salidas desde Python

Al comparar varios sistemas, resulta útil conservar todos los archivos de cada ejecución con su identificador. El cliente siguiente lee el UUID de job.json, consulta el estado cada dos segundos y descarga los artefactos cuando el trabajo termina correctamente. Utiliza únicamente la biblioteca estándar de Python, por lo que puedes guardarlo como collect.py y ejecutarlo con python collect.py después de recibir una admisión HTTP 202.

El cliente continúa el trabajo que ya has creado. Si una conexión falla, puedes volver a ejecutarlo para consultar ese mismo UUID y recuperar sus archivos sin enviar otra predicción.

1import json
2import os
3import shutil
4import time
5from pathlib import Path
6from urllib.request import Request, urlopen
7
8base_url = os.environ["QDIV0_API_URL"].rstrip("/")
9api_key = os.environ["QDIV0_API_KEY"]
10admission = json.loads(Path("job.json").read_text(encoding="utf-8"))
11job_id = admission["id"]
12output = Path("results") / job_id
13output.mkdir(parents=True, exist_ok=True)
14
15def get(path):
16    request = Request(
17        base_url + path,
18        headers={"Authorization": f"Bearer {api_key}"}
19    )
20    return urlopen(request, timeout=60)
21
22while True:
23    with get(f"/v1/biomolecular/jobs/{job_id}") as response:
24        job = json.load(response)
25    print(job["status"], flush=True)
26    if job["status"] in {"succeeded", "failed", "cancelled"}:
27        break
28    time.sleep(2)
29
30(output / "job.json").write_text(
31    json.dumps(job, indent=2), encoding="utf-8"
32)
33if job["status"] != "succeeded":
34    raise SystemExit(job.get("error") or job["status"])
35
36for artifact in job["artifacts"]:
37    filename = Path(artifact["filename"]).name
38    destination = output / f"{artifact['id']}_{filename}"
39    path = f"/v1/biomolecular/jobs/{job_id}/artifacts/{artifact['id']}"
40    temporary = destination.with_suffix(destination.suffix + ".part")
41    with get(path) as response, temporary.open("wb") as file:
42        shutil.copyfileobj(response, file)
43    temporary.replace(destination)
44    print(destination)
45

Las descargas se agrupan en una carpeta con el UUID del trabajo, de modo que puedas revisar una ejecución sin mezclarla con otra. Cada nombre lleva el identificador de su artefacto para evitar sobrescrituras entre archivos con nombres repetidos. Además, las transferencias utilizan archivos temporales que solo se renombran al completarse, lo que permite distinguir una descarga interrumpida de un resultado disponible. La respuesta final se conserva en results/<job_id>/job.json para relacionar cada archivo con su nombre original y su identificador.

#Evaluar las estructuras y la afinidad

Con los archivos recuperados, vuelve a la pregunta que motivó el experimento. Para comparar dos análogos, necesitas revisar si las geometrías propuestas son pertinentes y después elegir la estimación de afinidad adecuada. Las métricas de confianza te ayudan a examinar la primera parte, pero no sustituyen la revisión de la pose ni demuestran actividad experimental.

Revisa primero las coordenadas y las interfaces

Abre el mmCIF de cada ejecución en un visor como PyMOL o UCSF ChimeraX y comprueba que aparecen las cadenas y el ligando esperados. Si tu herramienta requiere PDB, puedes solicitarlo estableciendo options.output_format en pdb antes del cálculo. La inspección debe centrarse en la región que responde a tu pregunta, porque una proteína bien definida puede coexistir con una interfaz incierta.

Al estudiar el ligando, examina su pose, los contactos con el sitio de unión, las distancias y los posibles choques estéricos. Si solicitaste varias muestras, compara dónde se sitúa y cómo se orientan las cadenas entre propuestas. Esa comparación te ayudará a detectar qué aspectos de la geometría requieren más revisión antes de utilizar la afinidad para ordenar compuestos.

Interpreta los indicadores de confianza

Para situar esas dudas, relaciona las métricas con la parte de la estructura que estás inspeccionando. La confianza local se resume en complex_plddt, la organización global en ptm y las interfaces en iptm. El JSON también puede aportar indicadores por cadena y por pareja de cadenas, útiles para examinar una interfaz concreta junto con su geometría. Los valores agregados de estas familias están normalizados entre 0 y 1.

Cuando hay varias propuestas, confidence_score permite ordenarlas mediante 0.8 × complex_plddt + 0.2 × iptm, sustituyendo iptm por ptm si existe una sola cadena. Utiliza ese orden para orientar la inspección de estructuras, sin trasladarlo a un orden de actividad de los compuestos. Para revisar el error de distancia predicho, consulta complex_pde y complex_ipde, expresados en ångströms. En estos campos un valor menor indica mayor confianza en las distancias, por lo que debes interpretarlos de forma diferente a las métricas normalizadas en las que valores mayores son favorables.

Utiliza la salida de afinidad adecuada para tu estudio

Si estás seleccionando candidatos de un cribado inicial, utiliza affinity_probability_binary para examinar la probabilidad predicha de unión a la diana. Esta salida está orientada a distinguir candidatos de controles que no se unen y puede ayudarte a priorizar ensayos. Sin embargo, un valor de 0,9 no demuestra una probabilidad experimental de éxito del 90 % en tu proyecto.

Si ya comparas compuestos activos de una serie, como los dos análogos del ejemplo de trabajo, utiliza affinity_pred_value. Esta salida representa la estimación en la escala y = log10(IC50 [µM]), que puedes convertir a concentración mediante IC50 [µM] = 10^y. La conversión facilita leer la magnitud de las diferencias, como muestra la tabla.

Por ejemplo, pasar de -1 a -2 corresponde a una concentración diez veces menor en esa escala. Esa relación permite comparar estimaciones del modelo, pero no proporciona una medición experimental de IC50, una constante de disociación Kd ni una energía libre de unión. IC50 depende de las condiciones del ensayo, de modo que debes conservar la distinción entre la escala numérica y la actividad medida al decidir qué compuesto validar.

Al automatizar esta comparación, revisa también qué salida estás leyendo. Los sufijos 1 y 2 corresponden a los modelos del ensemble de afinidad, la combinación utilizada para obtener las estimaciones finales. No identifican dos ligandos ni el número de muestras estructurales. La definición nativa de las salidas permite documentar esa correspondencia en tu pipeline.

Evalúa el rendimiento con controles de tu proyecto

Para decidir si la priorización es útil en tu diana, incluye compuestos con actividad conocida y controles apropiados. Comprueba cómo los ordena el modelo y conserva los casos en los que la geometría o la afinidad discrepan de la evidencia experimental. Así podrás valorar el método en tu sistema antes de aplicarlo a moléculas nuevas. La selección final requiere ensayos de actividad y, según el objetivo, estudios de selectividad, toxicidad y farmacocinética.

Los resultados publicados proporcionan contexto para esa evaluación. El trabajo de Boltz-2 reporta una correlación de Pearson media por diana de 0,62 en el subconjunto OpenFE del benchmark FEP+, frente a 0,63 para OpenFE. Esa cifra describe la asociación entre predicciones y valores experimentales del conjunto, y no un porcentaje de predicciones correctas. La ventaja de coste computacional superior a 1000 veces frente a las simulaciones de referencia también corresponde a las condiciones descritas en los resultados originales de evaluación, por lo que no determina por sí sola el rendimiento de tu campaña.

#Resolver fallos y organizar campañas

Una vez revisado el flujo con un sistema conocido, puedes preparar una biblioteca de ligandos utilizando un trabajo por sistema y el mismo protocolo. Conserva la relación entre cada compuesto, su solicitud y el UUID devuelto, porque será necesaria tanto para comparar resultados como para localizar un fallo sin confundir ejecuciones. Si un trabajo no termina correctamente, revisa su diagnóstico antes de cambiar parámetros o repetirlo. La tabla recoge las comprobaciones que corresponden a los problemas más habituales.

Al planificar los envíos, QDivZero admite hasta ocho trabajos no terminales por cuenta y ejecuta las predicciones de cada instancia de forma serial. Enviar más solicitudes simultáneamente no aumenta por sí mismo su capacidad, así que utiliza los estados para seguir los trabajos pendientes y los que ya han terminado. Los trabajos en cola caducan después de seis horas y, una vez enviados al entorno de ejecución, tienen un límite por defecto de una hora que el operador puede configurar. Las fechas devueltas permiten seguir la campaña, pero el tiempo transcurrido no establece un porcentaje de avance de la predicción.

#Conservar un experimento reproducible

Para poder explicar después por qué dos compuestos obtuvieron resultados diferentes, archiva lo que has enviado y lo que se ha ejecutado. Conserva la solicitud, sus adjuntos originales, la respuesta final y todos los artefactos, junto con el manifest.json que incluye un trabajo exitoso. Sus metadatos recogen las opciones efectivas, la semilla, las versiones del entorno, GPU y CUDA, la revisión de checkpoints y los hashes de entrada. Estas huellas digitales permiten detectar cambios de contenido en los archivos o en la solicitud al comparar ejecuciones.

Organiza el archivo por UUID y añade el identificador de tu experimento y de su compuesto. De ese modo podrás recuperar la composición molecular, el protocolo y las salidas que respaldan una conclusión. Descarga los resultados durante los siete días posteriores a la finalización, que es el periodo de conservación de la integración incluso si detienes la instancia.

Si has utilizado MSA automático, registra el servicio y la fecha de generación, porque su contenido puede cambiar con el proveedor o sus bases de datos. La integración conserva información de procedencia, pero no exporta ese alineamiento. Cuando necesites repetir una comparación con exactamente la misma entrada evolutiva, utiliza MSA precomputados que puedas archivar como adjuntos.

La semilla fija una parte del proceso estocástico, pero no controla cambios de hardware, dependencias, pesos o bases de datos del MSA. Por eso la reproducibilidad requiere conservar esos elementos y definir qué diferencias considerarás aceptables al repetir la predicción. Con ese registro, la comparación vuelve a estar vinculada a una pregunta científica y a un protocolo que puedes revisar.

#Preguntas frecuentes

#Referencias

1. Boltz-2, publicación científica original
2. Presentación oficial y licencia del modelo
3. Documentación de predicción de Boltz 2.2.1
4. Parser nativo de entradas moleculares
5. Implementación del comando de predicción
6. Repositorio de Boltz y licencia MIT
7. Modelo Boltz-2 en Hugging Face