Envío de trabajos a la plataforma Grid UNAM

El subsistema de procesamiento de Grid UNAM está basado en el software HTCondor-CE, para el control y gestíon de colas de trabajo en una ambiente de mallas de computadoras y SLURM para el control de trabajos en un cluster específico. HTCondor-CE, llamado HTCondor "Computer Enterpoint (CE)", es una "ventana" por la cual sistemas remotos envían solicitudes para asignar de forma temporal recursos de procesamiento. Estas solicitdes son revisadas por el cluster de Grid UNAM en donde usted decide enviar el trabajo y se genera un trabajo piloto local. Si los recursos del piloto solicitados coinciden (procesadores, memoria RAM y autenticación de los usuarios) con las características del cluster, entonces se acepta y se ejecuta la aplicación.

Los comandos "gu" de procesamiento diseñados por Grid UNAM, son una sintésis de comandos HTCondor-CE en combinación con comandos SLURM que facilitan la manipulación de trabajos para los usuarios.

En este documenento, el proceso de envío de trabajos a la plataforma Grid UNAM está divida en las siguientes dos grandes secciones:

  1. Diseño de envío de la aplicación. Grid UNAM acepta una gran variead de aplicaciones, que llamaremos "app", como son las que se compilan con el software disponible en sus nodos de envío, las que se construyen en el momento de ejecución en cada nodo utilizando metalenguajes y las que se construyen utilizando el paradigma de "contenedores". Asimismo, cada app requiere de diferentes recuros de procesamiento y almacenamiento. Esto implica que no exista un esquema único para diseñar la aplicación. El diseño de ella está en el estado del arte. En este documento daremos ideas básicas para la explotación de Grid UNAM.

  2. Comandos gu de procesamiento. En esta sección se muestran los comandos para el envío de trabajos, la inspección de las colas de trabajo y la recuperación de resultados.

Requerimientos

  1. Tener acceso a un proyecto aprobado por la CTG.
  2. Tener sus credenciales, nombres de usuarios y palabas de acceso en:
    • El manejador de Identidad Digital. Vea los documentos Cuentas de Usuario RIU o Cuentas de Usuario Externo, según sea su caso.
    • El nodo de envío asigando. Vea el documento Cuentas en el nodo submit.
    • El node de almacenamiento S3 asignado. Vea el documento Almacenamiento S3
  3. Conocer como revisar el estado de la plataforma de procesamiento. Vea el documento Revisión de la plataforma.
  4. Conocer como manipluar el almacenamiento S3. Vea el documento Almacenamiento S3

Diseño del envío de la aplicación

Construcción de archívo de envío ".sub"

Los archivos de envío contienen directrices que corresponen a HTCondor-CE. En el siguiente recuadro, mostramos un protitipo que puede usar para enviar su app y explicaremos de forma breve cada una directrices usadas. En particular, hay directrices que son obligatorias y directrices opcionales. Usted, puede copiar el recuadro en su editor de texto y adaptalo a su app. Una descripción mas amplia la puede consultar en https://htcondor.com/htcondor-ce/v23/remote-job-submission/. También, es recomendable que el nombre de este archivo siempre lleve la extensión ".sub". 

# Required for remote HTCondor-CE submission (mandatory Grid UNAM)
universe = vanilla

# Necessary for S3 storage (mandatory Grid UNAM)
environment = "MC_HOST_gridunam=$ENV(MC_HOST_gridunam)"

######################################################
# App 
# If the flag is "optional", uncomment the next line
#####################################################

# Name of app (mandatory Grid UNAM)
executable = appName.sh

# App arguments (Optional)
#arguments = $(someArg)

# Output (strongly recommended by Grid UNAM)
output = appName.$(Cluster).$(Process).out

# Runtime errors  (strongly recommended by Grid UNAM)
error = appName.$(Cluster).$(Process).err

# Submit logs (strongly recommended by Grid UNAM)
log = appName.$(Cluster).$(Process).log

##########################################
# application resource request (optional)
##########################################

# N mumber of processing cores
#+xcount =  N

# Maximum  amount of memory M
#+maxMemory = M

#################################
# About transfer files
#################################

#Active transfer file (mandatory Grid UNAM)
ShouldTransferFiles = YES

# Time of transferring the output (mandatory Grid UNAM)
WhenToTransferOutput = ON_EXIT

# Input file names (optional)
#transfer_input_files = byLineArgs.txt, file3

#################################
# Submit app
#################################

# Run job (mandatory Grid UNAM)
queue 

# Run jobs as line number contains by-line-args.txt (optional)
#queue someArg from byLineArgs.txt

La descripción de las directrices es:

  • universe=vanilla: todos trabajos serán de este tipo para la versión actual de Grid UNAM.
  • environment: token para el acceso al almacenamiento S3. Este token es generado por el usuario en el nodo submit antes de enviar un trabajo que requiera almacenamiento S3.
  • executable: nombre del proceso maestro de envío de trabajos. Se recomienda ampliamente que sea un "script" de ejecución de "bash".
  • arguments: argumentos de la app en caso de requerirlos.
  • output, error y log: nombre de los archivos de salida (.out), error (.err) y estado del envío (.log) respecivamente.
  • +xcount, +manxMemory : Numero de núcleos de ejecución y memoría RAM que será solicitada al cluster, para ejecutar la app. El archivo de salida es el desplejado de la app en el momento de la ejecución. -ShouldTransferFiles: Activa la tranferencia de archivos.
  • WhenToTransferOutput: define el momento en el cual debe activarse. Se recomienda que sea al terminar la ejecución de la app.
  • transfer_input_files: nombre de los archivos adicionales que deben ser tranferidos a los nodos de trabajo de la app.
  • queue: directriz de envío y ejecución de la app.

Nota. En la dscripción de nombres de los archivos y variables evite colocar el guión medio "-", no es compatible con las directrices HTcondor-CE.

Construcción de la envoltura de la aplicación ".sh"

Grid UNAM tiene la habilidad de ejecutar programas que han sido compilados con los lenguajes de programación Fortran, C y C++. También, puede ejecutar una secuencia de instrucciones escrita en un metalenguje como Python o Julia. De la misma forma, puede ejecutar aplicaciones autocontenidas como son los Contenedores. Por otra parte, es una buena práctica recolectar información del estado de Grid UNAM, antes, en el momento de ejecución y al terminar la app. Es por ello, que se recomienda crear una secuencia de instrucciones basadas en directivas del sistema operativo Linux que realicen este proceso. A esa envoltura se le conoce como "script" y la extensíon ".sh" para conocer que es una secuencia de comando del sistema operativo.

En general, podemos recomendar las siguientes de secuencias de instrucciones antes de la ejecución de la app, que llamaremos "prólogo", y una secuencia de instrucciones al término de ella, que llamaremos "epílogo".

Entre el prólogo y el epílogo se encuentra todos los comandos y variables de ambiente necesarios para ejecutar la app. A esta sección la llamemos ambiente de ejecución. El ambiente de ejecución depende enteramente de las necesidas de la app y la habilidad del programador, por lo que solo se mencionarán algunas sugerencias.

La unión de estas 3 secciones definen al script de ejecución, en la sección anterior se identifica como appName.sh.

Nota. La appName.sh será ejecutada en uno o más nodos de trabajo!

Una buena práctica es recolectar información del estado del nodo de trabajo. El prototipo recolecta la información siguiente:

  • Las primeras 4 lineas dan información del comando original "Command:", la fecha de ejecución "RunDate:" y el nombre del nodo de ejecución "NodeName:" asignado automáticamente por Grid UNAM.
  • Las siguientes 3 líneas dan información de los nombres de los directorios almacenamientos auxiliares disponibles en cada nodo de trabajo. Estos son: "DefaultDir:" es el directorio en donde inicia la app, "HomeDir:" es el nombre del directorio del usuario en el contexto de SLURM y es generalmente una parición compartida, via red, en todo el cluster. El útlimo "GridWorkDir:" es un disco duro físico que está instalado en cada nodo del cluster y por lo tanto tiene mayor ancho de banda en operaciones de entrada y salida a disco.

    Grid UNAM recomienda ampliamente utilizar ${GRIDUNAM_WORKDIR} como el diectorio de trabajo. Cada nodo de trabajo de Grid UNAM garantiza 10 GB de almacenamiento por núcleo de procesamiento.

  • La utima acción es colocarse en ${GRIDUNAM_WORKDIR} para iniciar el trabajo. Para verificar, se almacena el nombre del directorio en "CurrentDir:"
#!/bin/bash

####################
## General Info
###################
echo "Command: $0 $@ "
theDateH=`date `
echo "RunDate: ${theDateH}"
theHost=`hostname`
echo "NodeName: ${theHost}"

echo "DefaultDir: `pwd` "
echo "HomeDir: ${HOME}"
echo "GridWorkDir: ${GRIDUNAM_WORKDIR}"

#################################
# Always work in GRIDUNAM_WORKDIR
##################################

cd ${GRIDUNAM_WORKDIR}

echo "CurrentDir: `pwd`"

echo " "

### End Prologue ##########

Ambiente de ejecución

A continuación se indican algunas sugerencias que debe contener un trabajo enviado a Grid UNAM.

  • Coloque los archivos de entrada y las librerias especiales que necesita su app en el almacenamiento S3 de su proyecto.
  • En el caso de un contenedor, éste debe estar en el almacenamiento S3.
  • De ser posible empaquete toda la información con el comando tar y de preferencia comprimido.
  • Defina las variables de ambiente especiales que requiere su aplicación.

    Advertencia. Nunca redefina las variables de ambiente descritas en el epílogo. Ésto causará problemas en el momento de ejecución.

Finalmente transfiera los resultados de su app, los archivos de salida (.out) los de error (.err) y los de estado de envío (.log) al almacenamiento S3. Al finalizar, borre todos los archivos del ${GRIDUNAM_WORKDIR}. Un prototipo está en el siguiente recuadro. Ajuste los nombre a sus necesidades.

##########
# Epilog
##########

###################
#Transfer Results
###############

#mcli cp some-file gridunam/Bucket-Raiz/some-result-dir

##############
# The logs
##########

#mcli cp $HOME/../*.log gridunam/Bucket-Raiz/some-result-dir
#mcli cp $HOME/../*.out gridunam/Bucket-Raiz/some-result-dir
#mcli cp $HOME/../*.err gridunam/Bucket-Raiz/some-result-dir


##############
# Clear space#
##############

cd ${GRIDUNAM_WORKDIR}
rm -rf *

### End Epilog ###

Comandos gu de manipulación de trabajos

Preparación previa

  1. Acceso al nodo submit

[remote-host]$ ssh usuario-nodo-sbmit@nodo-submit
en donde nodo-sbmit=[ jamatu.astrosen.unam.mx | condor-grid.lamod.unam.mx | sbmit.grid.unam.mx | jupyter2.atmosfera.unam.mx ] y usuario-nodo-submit es el nombre la cuenta en el nodo de envío de su proyecto.
  1. Activar los comandos gu
[nodo-sbmit]$ module load gridunam
  1. Activar el "Token" de procesamiento
[nodo-submit]$ gu_activar_acceso_gridunam

Nota importante. El "Token" de procesamiento tiene 1 h de vigencia.

  1. Activar el "Token" de almacenamiento S3.
[nodo-sbmit]$ cd $HOME

[nodo-submit]$ source gridauth.sh Identificador-S3
Identificador-S3
Usuario: Cuenta-de-almacenamiento
Password: Palabra-de-acceso-almacenamiento

En donde Identificador-S3=[ dgtic | atenea | lamod ].

Nota importante. El "Token" de almacenamiento S3 tiene 3 días de vigencia.

  1. Revisar el estado de la plataforma antes de envíar un trabajo (opcional). 
[nodo-submit]$ gu_show_all_cpus_all_cluster

Nota importante. Es una buena práctica revisar el estado de la plataforma antes de enviar un trabajo.

Envío de trabajos

El comando para enviar un trabajo a cualquera de 4 cluster que componene Grid UNAM es el siguiente:

$ gu_enviar_jobs trabajo.sub ID-cluster

Existe un token y es vigente
Submitting job(s)..................
N job(s) submitted to cluster ID-Job.

en donde ID-cluster=[ \(lamod_ | _\)astrosen | \(icaycc_ | _\)dgtic ].

Este comando despliega el número de trabajos enviados N y el identificador de trabajo ID-Job.

Nota. Guarde en un lugar seguro el identificado de trabajo ID-Job se utilizará en todos los procesos siguientes.

Consulta de trabajos

El comando para consultar la cola de trabajo es el siguiente:

$ gu_consultar_jobs ID-cluster ID-Job
Existe un token y es vigente

-- Schedd: Cluster-Name : <Cluster-IP:9619?... @ 01/10/25 20:12:06
OWNER        BATCH_NAME    SUBMITTED   DONE   RUN    IDLE  TOTAL JOB_IDS
User-GridUNAM ID: ID-Job   mm/dd hh:ss  _      _      1      N   ID-Job

Si el trabajo es aceptado, se despliega el nombre del cluster en donde se envió el trabajo, Cluster-Nanme, así como su dirección Internet, Cluster-Ip. También, despliega el estado del trabajo [DONE | RUN | IDL], en estos campos aparecerá un "1" si la bandera de estado se activa, de lo controtrario se muestra "-". La información de este comango se describe en la Tabla 1.

Columna Descripción
OWNER Nombre del usuarios en el contexto de la plataforma Grid UNAM
BATCH_NAME Número de identificación de trabajo
SUBMITTED Fecha de envío mm/dd hh:mm
DONE El trabajo se realizó
RUN El trabajo se está ejecutando
IDL El trabajo está está en espera de ser ejecutado
TOTAL Numero de trabajos
JOB_IDS Identificador de cada trabajo en la cola de ejecución. El formato es ID-Jobs-N

Tabla 1: Descripción de la informacion de gu_consultar_jobs ID-cluster ID-Job.

Un trabajo tarda del orden de 2 min a 5 min en ser colocado en la cola de ejecución en alguna de las entidades. Al mismo tiempo se activa la bandera "IDL", el trabajo está en espera de que se le asignen recursos de procesamiento para ser ejecutado.

Cuando un trabajó terminó todas las banderas del estado de trabajo estarán apagadas, se muestra "-".

Nota: Si en trabajo no pasa al estado de ejecución, "RUN = 1" después de 10 min y hay recursos disponibles en la entidad en donde envió el trabajo, ver comando gu_show_all_cpus_all_cluster, entonces ejecute el siguiennte comando y el resultado enviélo a la mesa de ayuda soportegrid@unam.mx

$ gu_consultar_jobs ID-cluster ID-Job -idl

Extraer los resultados

En general, los trabajos enviado a la plataforma Grid UNAM generan 3 archivos: los archivos de salida que la app genera en la consola ".out", los archivos del estado de la cola ".log" y los archivos de error en la ejecución ".err". Extraer los resultado significa: - Copiar estos archivos de los nodos trabajo al nodo de envío. - Los archivos serán colocados exactamente en el subdirectorio desde se envió el trabajo en el nodo submit.

$ gu_descargar_archivos ID-cluster ID-Job
Existe un token y es vigente
Fetching data files...

Buenas prácticas: Se recomienda enviar los archivos ".out", ".log", ".err" al almacenamiento S3 que le fué asignado.