Flujos de trabajo de simulación reproducibles en química e investigación de materiales: qué equipos deben documentar

La reproducibilidad en química y simulación de materiales no es solo una cuestión de almacenar un script, cargar un conjunto de datos o mantener una carpeta de archivos de entrada. Un flujo de trabajo es reproducible cuando otro investigador puede entender cómo una pregunta científica se convirtió en un modelo, cómo ese modelo se convirtió en una ejecución ejecutable, cómo la ejecución produjo resultados y cómo esas salidas se convirtieron en un resultado informado.

Esa cadena es fácil de romper. Una dependencia modificada, una configuración de solucionador indocumentada, un archivo de salida renombrado o una figura generada a partir de una hoja de cálculo editada pueden hacer que una simulación valiosa sea difícil de inspeccionar más adelante. El problema no siempre es mala ciencia. A menudo, falta el contexto.

Para los equipos de investigación de química y materiales computacionales, la documentación tiene que preservar más que la respuesta final. Tiene que preservar el razonamiento, la configuración, el estado de ejecución y la ruta de interpretación que hizo posible la respuesta.

Qué significa realmente un flujo de trabajo de simulación reproducible

Un flujo de trabajo de simulación reproducible es la ruta documentada desde la intención científica hasta el resultado interpretable. Incluye el modelo, las entradas, el estado del software, el entorno de ejecución, los datos generados, los pasos de procesamiento posterior y el razonamiento utilizado para conectar las salidas a una reclamación.

En un contexto de química o materiales, esto puede involucrar estructuras moleculares, modelos de campo de fase, supuestos de reacción, potenciales interatómicos, condiciones de contorno, opciones de malla, criterios de convergencia, parámetros termodinámicos o configuraciones de solucionador numérico. En la práctica, los elementos exactos varían según el método. El principio no.

Un flujo de trabajo reproducible debería permitir que un futuro lector responda cuatro preguntas:

• ¿Qué estaba tratando de probar o demostrar la simulación?
• ¿Qué suposiciones y parámetros dieron forma al resultado?
• ¿Qué estado computacional exacto produjo la producción?
• ¿Cómo se transformaron los productos en la interpretación reportada?

Sin esas respuestas, un resultado puede seguir siendo interesante, pero es más difícil confiar, comparar, extender o depurar.

La cadena de documentación de reclamación para ejecutar

La forma más útil de documentar el trabajo de simulación es comenzar con el reclamo que admite el flujo de trabajo y rastrear hacia atrás hasta la ejecución que lo produjo. Esto evita una falla de documentación común: preservar fragmentos técnicos sin mostrar cómo se conectan.

La cadena de reclamación de ejecución tiene cinco capas.

1. La capa de reclamación

Esta capa registra la conclusión, figura, tendencia, comparación o propiedad que el flujo de trabajo pretende soportar. Debe indicar qué se utiliza el resultado de la simulación para argumentar, no sólo qué archivo se generó.

Por ejemplo, un flujo de trabajo podría respaldar una afirmación sobre el comportamiento de difusión, la estabilidad de fase, la energía de formación de defectos, los efectos solventes, la evolución de la morfología o el rendimiento relativo de dos configuraciones de modelo. La documentación debe hacer visible ese propósito.

2. La capa modelo

Esta capa explica la representación científica y matemática detrás de la carrera. Incluye suposiciones, ecuaciones de gobierno, aproximaciones, límites del modelo, parámetros seleccionados y simplificaciones conocidas.

El objetivo no es escribir un libro de texto dentro de cada carpeta de proyecto. El objetivo es dejar suficiente contexto para que otro miembro del equipo pueda ver por qué se eligió este modelo y dónde comienzan sus límites.

3. La capa de ejecución

Esta capa captura el estado computacional de la ejecución: versiones de software, confirmaciones, dependencias, archivos de entorno, configuración de trabajos, contexto de hardware, semillas aleatorias y registros de tiempo de ejecución.

Los detalles de ejecución a menudo se tratan como ruido administrativo hasta que algo cambia. Luego se convierten en la única forma de explicar por qué una repetición difiere de la original.

4. La capa de datos

Esta capa conserva las salidas sin procesar, las salidas derivadas, los metadatos, las convenciones de nomenclatura, las unidades, las transformaciones y las relaciones de archivo. Debe quedar claro qué archivos son productos de simulación directa y cuáles se crearon mediante análisis o filtrado.

5. La capa de interpretación

Esta capa conecta las salidas con la interpretación científica final. Incluye scripts de análisis, código de trazado, ejecuciones excluidas, ejecuciones fallidas, decisiones manuales, notas de problemas y pasos de generación de figuras.

Aquí es donde muchos flujos de trabajo pierden reproducibilidad. La simulación puede ser recargable, pero la cifra o conclusión informada puede no ser rastreable.

Qué documentar antes de la ejecución

La documentación previa a la ejecución debe explicar por qué existe la simulación y qué condiciones definen un resultado significativo. Esto es especialmente importante cuando se revisará un flujo de trabajo después de un borrador en papel, un cambio de código, un comentario de revisión por pares o un traspaso al equipo.

Como mínimo, los equipos deben documentar la pregunta de investigación, el sistema químico o de materiales, el enfoque de modelado, los supuestos hechos y los criterios utilizados para juzgar si la ejecución tuvo éxito.

Para la investigación de química y materiales, eso a menudo significa registrar:

• Composición del sistema, estructura, geometría o descripción de fase;
• supuestos de modelo y simplificaciones conocidas;
• condiciones iniciales y de contorno;
• unidades y fuentes de parámetros;
• Solver, discretización, malla o configuraciones de convergencia;
• criterios de aceptación para un resultado estable o utilizable;
• productos esperados y cómo se interpretarán.

Esta información no necesita ser larga. Un archivo Léame conciso, una nota de ejecución estructurada o una plantilla de proyecto pueden ser suficientes si captura las decisiones que de otro modo serían fáciles de olvidar.

Qué capturar durante la ejecución

La documentación en tiempo de ejecución es la parte de la reproducibilidad que a menudo se siente rutinaria hasta que falta. Una simulación puede producir una salida de aspecto válido mientras se ocultan advertencias, cambios de dependencia, interrupciones del programador, rutas de entrada alteradas o comportamiento de reserva silencioso.

El registro de ejecución debe incluir el estado de software exacto utilizado para la ejecución. Eso significa números de versión, confirmaciones de repositorio cuando sea relevante, archivos de dependencia, archivos de configuración, argumentos de línea de comandos y detalles del entorno. Para los sistemas HPC o compartidos, la configuración del programador y la asignación de recursos también pueden importar.

Cuando aparecen resultados inesperados, estos registros pasan a formar parte del proceso de diagnóstico. Los equipos que tratan reproducibilidad como una ayuda práctica de depuración generalmente están mejor posicionados para identificar si un cambio provino del modelo, los datos, el software o el entorno de ejecución.

Los registros no deben descartarse demasiado rápido. Las advertencias, los mensajes de convergencia, el diagnóstico del solucionador, los errores en tiempo de ejecución y el comportamiento de reinicio pueden explicar por qué se debe confiar, repetir o excluir un resultado.

Qué conservar después de la carrera

La documentación posterior a la ejecución debería hacer visible la vía de salida. Un flujo de trabajo reproducible no termina cuando finaliza la simulación. Termina cuando el equipo puede mostrar cómo las salidas sin procesar se convirtieron en datos, cifras, tablas o reclamos derivados.

Conserve las salidas sin procesar por separado de las salidas procesadas. Mantenga los scripts de análisis cerca de los datos que transforman. Registre unidades, filtros, opciones de suavizado, umbrales y casos excluidos. Si aparece una figura en un informe o manuscrito, el flujo de trabajo debe mostrar qué ejecución, secuencia de comandos y conjunto de datos lo produjo.

Las carreras fallidas también merecen un récord. Una simulación fallida puede explicar por qué cambiaron los parámetros, por qué se redujo un modelo o por qué se volvió a ejecutar un resultado. Cuando las anomalías o las repeticiones afectan la interpretación, ayuda a preservar la conexión entre la salida y la decisión del equipo que siguió, incluyendo conexión de resultados de simulación al historial de problemas detrás de ellos.

Prueba útil: Si no se puede regenerar una figura a partir de entradas, scripts y salidas documentados, el flujo de trabajo no está completamente documentado incluso si se guarda la imagen final.

Un mapa de documentación práctica

Los administradores de flujos de trabajo, los cuadernos, los scripts y los trabajos de HPC necesitan registros diferentes

No todos los equipos de investigación necesitan el mismo sistema de documentación. Un pequeño cuaderno exploratorio, un barrido de parámetros con script, un flujo de trabajo en contenedores y una canalización de HPC de varias etapas tienen diferentes riesgos de reproducibilidad.

Para los portátiles, el principal riesgo es el estado oculto. Las celdas se pueden ejecutar fuera de orden, las variables intermedias pueden permanecer en la memoria y las cifras pueden depender de los pasos manuales. La documentación debe aclarar el orden de ejecución, los datos de entrada, las versiones de paquetes y el estado de script o cuaderno final utilizado para los resultados informados.

Para los scripts ad hoc, el riesgo es un contexto disperso. Un comando puede depender de rutas locales, valores predeterminados no documentados o archivos fuera del control de versiones. Los equipos deben capturar ejemplos de comandos, archivos de configuración, estructura de directorios esperada y ubicaciones de salida.

Para los administradores de flujos de trabajo, el riesgo es asumir que la automatización equivale a la comprensión. La procedencia automatizada es valiosa, pero aún se necesita documentación legible por humanos para explicar por qué se configuró un flujo de trabajo de cierta manera.

Para las carreras de HPC, el riesgo es la deriva ambiental. La configuración de colas, los módulos, los tipos de nodos, las opciones de paralelización, el almacenamiento temporal y el comportamiento de reinicio pueden influir en si una ejecución es realmente reproducible en otro sistema.

Puntos débiles comunes que rompen la reproducibilidad

La mayoría de las fallas de reproducibilidad no son dramáticas. Son pequeños huecos que se agravan con el tiempo.

• Unidades faltantes: Se guarda un valor de parámetro, pero su unidad no.
• Origen del parámetro poco claro: Aparece un valor en un archivo de configuración sin explicación de si proviene de la literatura, la calibración o la conveniencia.
• Dependencias modificadas: Todavía se ejecuta un script, pero una actualización de la biblioteca cambia el comportamiento.
• Ediciones manuales de archivos: Se utiliza un conjunto de datos corregido, pero la corrección no está documentada.
• Figuras separadas: Sobrevive una trama, pero los datos y el guión que lo crearon no están claros.
• Ejecuciones fallidas invisibles: Solo quedan salidas exitosas, ocultando la ruta que condujo a las opciones de parámetros finales.
• Configuración del solucionador no documentado: Un resultado depende de las tolerancias, de la resolución de la malla o de los criterios de convergencia que no se registran.

Estos puntos débiles importan porque hacen que la interpretación posterior sea frágil. Un futuro investigador puede volver a ejecutar el flujo de trabajo y obtener una respuesta diferente sin saber si la diferencia es científica, numérica, ambiental o de procedimiento.

Documentación mínima viable para equipos de investigación

Un equipo no necesita una infraestructura perfecta antes de que pueda documentar de manera reproducible. Un registro mínimo viable suele ser suficiente para evitar las peores pérdidas de contexto.

Para muchos proyectos de simulación de química y materiales, la siguiente estructura es un punto de partida realista:

• un Léame que explica la pregunta científica y el diseño del flujo de trabajo;
• una nota de modelo que enumera supuestos, parámetros, unidades y criterios de aceptación;
• un archivo de entorno o un registro de dependencia;
• un directorio de archivos de entrada versionados;
• un comando de ejecución guardado o una configuración de flujo de trabajo;
• registros y advertencias de tiempo de ejecución;
• un manifiesto de salida que distingue archivos RAW y procesados;
• scripts de análisis utilizados para generar tablas y figuras;
• un mapa de figuras que conectaba imágenes informadas a datos y scripts;
• Un breve registro de desviación para ejecuciones fallidas, exclusiones y repeticiones.

El punto no es crear papeleo por sí mismo. El punto es hacer que el flujo de trabajo sea comprensible en el momento en que la memoria ya no sea confiable.

La reproducibilidad es la memoria del equipo

Los flujos de trabajo de simulación a menudo sobreviven a la persona que los construyó por primera vez. Un investigador graduado se va, una dependencia cambia, un revisor pide una aclaración, un colaborador cuestiona una figura o un equipo decide extender un modelo antiguo a un nuevo sistema químico.

En esos momentos, la documentación se convierte en la memoria del equipo. Explica no solo qué se ejecutó, sino por qué se ejecutó de esa manera, qué cambió a lo largo del camino y cómo se debe interpretar el resultado final.

Los flujos de trabajo reproducibles más fuertes no simplemente archivan artefactos computacionales. Conservan la relación entre la reivindicación científica, el modelo, el estado ejecutable, los datos y la interpretación. Esa relación es lo que permite que los equipos de investigación de química y materiales confíen en un resultado después de que el contexto original se haya desvanecido.