ccervantess/livecroco

By ccervantess

•Updated about 1 month ago

CROCO 2.1.2 + TOOLS + PYTOOLS in an Apptainer SIF for reproducible HPC ocean-modeling workflows.

Artifact

Data science

Overview Tags

ccervantess/livecroco repository overview

⁠LiveCROCO 2.1.2 — Apptainer/Singularity

Contenedor reproducible para ejecutar CROCO 2.1.2, CROCO TOOLS 2.1.0 y CROCO PYTOOLS 2.0.1 en servidores GNU/Linux y clústeres HPC con Apptainer/Singularity.

El contenedor incluye el software y sus dependencias. Los proyectos y datasets se mantienen fuera del .sif y se montan con --bind, lo que facilita mover el mismo contenedor entre servidores.

⁠Componentes incluidos

Componente	Versión validada
CROCO	2.1.2
CROCO TOOLS	2.1.0
CROCO PYTOOLS	2.0.1
Python	3.11
Open MPI	4.1.6
NetCDF-C	4.9.2
NetCDF-Fortran	4.5.4
pyinterp	2024.6.0

También se incluyen utilidades de Python científico como netCDF4, xarray, numpy, scipy, cartopy, pyproj y GDAL.

⁠Convención de rutas

El contenedor utiliza dos rutas internas principales:

/work  = proyecto CROCO
/data  = datasets externos

Por ejemplo:

apptainer exec \
  --bind "$PROJECT:/work" \
  --bind "$CROCO_DATA:/data/DATASETS_CROCOTOOLS:ro" \
  "$SIF" \
  COMANDO

El .sif permanece inmutable y los datos permanecen en el sistema anfitrión.

⁠Descargar el contenedor

El SIF se distribuye como un artefacto OCI/ORAS y debe descargarse con Apptainer.

apptainer pull \
  livecroco-2.1.2.sif \
  oras://docker.io/ccervantess/livecroco:2.1.2-sif

Importante: este artefacto es un archivo Apptainer .sif almacenado en un registro OCI. No debe asumirse que es una imagen Docker convencional para ejecutar con docker run.

⁠Prueba rápida sin descargar datasets ni crear cuentas externas

Esta es la forma más sencilla de demostrar que el SIF funciona.

No requiere:

cuenta de Copernicus Climate Data Store;
cuenta de Copernicus Marine;
credenciales;
ERA5;
Mercator;
datasets adicionales.

Definir:

export SIF=/ruta/al/livecroco-2.1.2.sif

⁠1. Verificar CROCO PYTOOLS

apptainer exec "$SIF" croco-make-grid --help

Una instalación correcta muestra algo equivalente a:

usage: make_grid.py [-h] [filePath]

Generate CROCO grid NetCDF from a config file.

⁠2. Verificar el entorno Python

apptainer exec "$SIF" \
  /opt/micromamba/envs/croco_pyenv/bin/python - <<'PY'
import pyinterp
import netCDF4
import xarray
import numpy
import scipy

print("pyinterp :", pyinterp.__version__)
print("netCDF4  :", netCDF4.__version__)
print("xarray   :", xarray.__version__)
print("numpy    :", numpy.__version__)
print("scipy    :", scipy.__version__)
print("LiveCROCO Python environment OK")
PY

En la imagen validada se obtuvo:

pyinterp : 2024.6.0
netCDF4  : 1.7.4
xarray   : 2026.9.0
numpy    : 2.4.6
scipy    : 1.17.1
LiveCROCO Python environment OK

⁠3. Verificar software compilado

apptainer exec "$SIF" bash -lc '
  echo "CROCO:"
  test -d /opt/livecroco/croco-v2.1.2 && echo "  CROCO 2.1.2 OK"

  echo "CROCO TOOLS:"
  test -d /opt/livecroco/croco_tools-v2.1.0 && echo "  CROCO TOOLS 2.1.0 OK"

  echo "CROCO PYTOOLS:"
  test -d /opt/livecroco/croco_pytools-v2.0.1 && echo "  CROCO PYTOOLS 2.0.1 OK"

  echo "Fortran extension:"
  ls /opt/livecroco/croco_pytools-v2.0.1/prepro/Modules/toolsf*.so
'

Esta prueba es suficiente para un smoke test del contenedor y no depende de servicios externos.

⁠Prueba funcional sin cuentas externas: ejemplo BENGUELA

Para una prueba más completa puede utilizarse el ejemplo BENGUELA.

Esta prueba genera:

croco_grd.nc
croco_ini_*.nc
croco_bry_*.nc

y utiliza únicamente archivos públicos alojados por CROCO/IFREMER. No requiere crear cuentas en CDS ni en Copernicus Marine.

⁠1. Definir rutas

export SIF=/ruta/al/livecroco-2.1.2.sif
export PROJECT=/ruta/al/proyecto
export CROCO_DATA=/ruta/a/DATASETS_CROCOTOOLS

Ejemplo:

export SIF=$HOME/apptainers/croco/livecroco-2.1.2.sif
export PROJECT=$HOME/benguela
export CROCO_DATA=$HOME/data/DATASETS_CROCOTOOLS

Crear el proyecto:

mkdir -p "$PROJECT/config" "$PROJECT/data"
cd "$PROJECT"

⁠2. Descargar `DATASETS_CROCOTOOLS`

wget \
  https://data-croco.ifremer.fr/DATASETS/DATASETS_CROCOTOOLS.tar.gz

Descomprimir:

tar -xzf DATASETS_CROCOTOOLS.tar.gz

Este paquete contiene, entre otros, datos de topografía ETOPO y líneas de costa GSHHS.

DATASETS_CROCOTOOLS.tar.gz no contiene el archivo Mercator usado para las condiciones iniciales y de borde.

⁠3. Crear la configuración CROCO

apptainer exec \
  --bind "$PROJECT:/work" \
  "$SIF" \
  create_croco_config

Responder:

cuando aparezca:

Do you want to proceed ? [Y/n]

Se creará:

Run/

⁠4. Compilar CROCO

apptainer exec \
  --bind "$PROJECT:/work" \
  "$SIF" \
  croco-build

Comprobar:

ls -lh "$PROJECT/Run/croco"

⁠5. Copiar los archivos del ejemplo BENGUELA

apptainer exec \
  --bind "$PROJECT:/work" \
  "$SIF" \
  bash -lc '
    cp \
      /opt/livecroco/croco_pytools-v2.0.1/prepro/Examples/benguela_multifiles/*.ini \
      /work/config/
  '

Comprobar:

ls "$PROJECT/config"

Deben aparecer, entre otros:

grid.ini
ibc.ini
download_era5.ini
download_mercator.ini
rivers.ini
tides.ini

⁠6. Preparar `grid.ini`

sed -i \
  's#croco_files_dir = ../results/CROCO_FILES#croco_files_dir = /work/Run/CROCO_FILES#' \
  "$PROJECT/config/grid.ini"

sed -i \
  's#topo_file = ../data/DATASETS_CROCOTOOLS/Topo/etopo2.nc#topo_file = /data/DATASETS_CROCOTOOLS/Topo/etopo2.nc#' \
  "$PROJECT/config/grid.ini"

sed -i \
  's#shp_file = ../data/DATASETS_CROCOTOOLS/gshhs/GSHHS_shp/i/GSHHS_i_L1.shp#shp_file = /data/DATASETS_CROCOTOOLS/gshhs/GSHHS_shp/i/GSHHS_i_L1.shp#' \
  "$PROJECT/config/grid.ini"

Comprobar:

grep -E \
  'croco_files_dir|topo_file|shp_file' \
  "$PROJECT/config/grid.ini"

Debe mostrar:

croco_files_dir = /work/Run/CROCO_FILES
topo_file = /data/DATASETS_CROCOTOOLS/Topo/etopo2.nc
shp_file = /data/DATASETS_CROCOTOOLS/gshhs/GSHHS_shp/i/GSHHS_i_L1.shp

⁠7. Generar la malla

apptainer exec \
  --bind "$PROJECT:/work" \
  --bind "$CROCO_DATA:/data/DATASETS_CROCOTOOLS:ro" \
  "$SIF" \
  croco-make-grid \
  /work/config/grid.ini

Comprobar:

ls -lh "$PROJECT/Run/CROCO_FILES/croco_grd.nc"

⁠Datos oceánicos Mercator

El ejemplo necesita datos oceánicos para crear las condiciones iniciales y de borde.

Para esta prueba puede utilizarse un dataset preprocesado y público de CROCO, sin registro.

⁠8. Descargar Mercator

cd "$PROJECT/data"

wget \
  https://data-croco.ifremer.fr/CONFIGS_EXAMPLES/DATASETS_GLOB_INTER/CROCO/MERCATOR_GLOB_201301.tar.gz

tar -xzf MERCATOR_GLOB_201301.tar.gz

En la descarga validada se obtuvo:

MERCATOR_GLOB_2013/mercator_Y2013M1.cdf

La prueba realizada con este archivo no requiere descargar enero, febrero y marzo por separado.

Definir:

export MERCATOR_DATA="$PROJECT/data/MERCATOR_GLOB_2013"

Como el archivo de configuración del ejemplo busca el mes con dos dígitos:

mercator_Y2013M01.cdf

crear un enlace simbólico:

cd "$MERCATOR_DATA"

ln -sf \
  mercator_Y2013M1.cdf \
  mercator_Y2013M01.cdf

Comprobar:

ls -lh mercator_Y2013M*.cdf

⁠9. Preparar `ibc.ini`

cd "$PROJECT"

sed -i \
  's#croco_files_dir = ../results/CROCO_FILES#croco_files_dir = /work/Run/CROCO_FILES#' \
  "$PROJECT/config/ibc.ini"

sed -i \
  's#ibc_dir = ../data/DATA_IBC/MERCATOR_GLOB_2013/#ibc_dir = /mercator/#' \
  "$PROJECT/config/ibc.ini"

Comprobar:

grep -E \
  'croco_files_dir|ibc_reader|ibc_dir|ibc_prefix|ibc_extension|ini_filedate' \
  "$PROJECT/config/ibc.ini"

Valores esperados:

croco_files_dir = /work/Run/CROCO_FILES
ibc_reader = mercator_croco
ibc_dir = /mercator/
ibc_prefix = mercator
ibc_extension = .cdf
ini_filedate = Y2013M01

⁠10. Crear condiciones iniciales

apptainer exec \
  --bind "$PROJECT:/work" \
  --bind "$MERCATOR_DATA:/mercator:ro" \
  "$SIF" \
  croco-make-ini \
  /work/config/ibc.ini

Comprobar:

ls -lh "$PROJECT/Run/CROCO_FILES"/croco_ini_*.nc

En la prueba validada se generó:

croco_ini_mercator_croco_Y2013M01.nc

⁠11. Crear condiciones de borde

apptainer exec \
  --bind "$PROJECT:/work" \
  --bind "$MERCATOR_DATA:/mercator:ro" \
  "$SIF" \
  croco-make-bry \
  /work/config/ibc.ini

Comprobar:

ls -lh "$PROJECT/Run/CROCO_FILES"/croco_bry_*.nc

En la prueba validada se generó:

croco_bry_mercator_croco_Y2013M01.nc

⁠Verificación final de la prueba BENGUELA

echo "===== LiveCROCO validation ====="

test -x "$PROJECT/Run/croco" \
  && echo "CROCO executable: OK" \
  || echo "CROCO executable: FAIL"

test -f "$PROJECT/Run/CROCO_FILES/croco_grd.nc" \
  && echo "Grid generation: OK" \
  || echo "Grid generation: FAIL"

ls "$PROJECT/Run/CROCO_FILES"/croco_ini_*.nc >/dev/null 2>&1 \
  && echo "Initial conditions: OK" \
  || echo "Initial conditions: FAIL"

ls "$PROJECT/Run/CROCO_FILES"/croco_bry_*.nc >/dev/null 2>&1 \
  && echo "Boundary conditions: OK" \
  || echo "Boundary conditions: FAIL"

Una ejecución correcta debe producir:

===== LiveCROCO validation =====
CROCO executable: OK
Grid generation: OK
Initial conditions: OK
Boundary conditions: OK

Con esto se considera validado el flujo principal de preprocesamiento del contenedor.

⁠¿Es necesario ERA5 para comprobar el SIF?

No.

ERA5 se utiliza como forcing atmosférico para realizar simulaciones regionales completas, pero no es necesario para demostrar que:

CROCO compila;
CROCO PYTOOLS funciona;
NetCDF funciona;
Python y Fortran funcionan juntos;
se puede construir una malla;
se pueden interpolar datos oceánicos;
se pueden producir condiciones iniciales;
se pueden producir condiciones de borde.

El contenedor incluye:

croco-download-era5

pero su uso requiere una cuenta y credenciales del Copernicus Climate Data Store (CDS).

Por esta razón, ERA5 se considera una prueba opcional y no forma parte de la prueba funcional mínima del SIF.

⁠¿Es necesario Copernicus Marine?

No para este ejemplo.

CROCO PYTOOLS puede descargar datos actuales de Copernicus Marine mediante sus herramientas de Mercator/GLORYS, pero esa opción requiere cuenta y autenticación.

Para validar el contenedor se recomienda utilizar el archivo público:

MERCATOR_GLOB_201301.tar.gz

alojado directamente por CROCO/IFREMER.

⁠Ejecución completa de CROCO

La prueba descrita anteriormente valida el contenedor y el flujo de preprocesamiento.

Una simulación oceanográfica completa requiere además preparar correctamente el forcing atmosférico y revisar los parámetros de croco.in.

Cuando todos los archivos requeridos estén disponibles, puede ejecutarse:

apptainer exec \
  --bind "$PROJECT:/work" \
  "$SIF" \
  croco-run

Una simulación completa correcta debe finalizar con:

MAIN: DONE

Esta etapa no es necesaria para el smoke test ni para la validación básica del SIF.

⁠Estructura típica de un proyecto

proyecto/
├── config/
│   ├── grid.ini
│   ├── ibc.ini
│   ├── download_era5.ini
│   └── ...
│
├── data/
│   └── MERCATOR_GLOB_2013/
│       ├── mercator_Y2013M1.cdf
│       └── mercator_Y2013M01.cdf -> mercator_Y2013M1.cdf
│
└── Run/
    ├── croco
    ├── croco.in
    └── CROCO_FILES/
        ├── croco_grd.nc
        ├── croco_ini_mercator_croco_Y2013M01.nc
        └── croco_bry_mercator_croco_Y2013M01.nc

⁠Flujo recomendado

Para comprobar únicamente el contenedor:

Descargar SIF
      ↓
croco-make-grid --help
      ↓
verificar entorno Python
      ↓
verificar versiones
      ↓
SIF OK

Para una prueba funcional más completa sin cuentas externas:

Descargar SIF
      ↓
Descargar DATASETS_CROCOTOOLS
      ↓
create_croco_config
      ↓
croco-build
      ↓
croco-make-grid
      ↓
Descargar MERCATOR_GLOB_201301
      ↓
croco-make-ini
      ↓
croco-make-bry
      ↓
Validación funcional OK

ERA5 y la simulación completa quedan como pasos opcionales.

⁠Docker Hub / ORAS

Repositorio:

ccervantess/livecroco

Tag:

2.1.2-sif

Descarga mediante Apptainer:

apptainer pull \
  livecroco-2.1.2.sif \
  oras://docker.io/ccervantess/livecroco:2.1.2-sif

⁠Estado de validación

La imagen fue probada con éxito para:

CROCO build                    OK
CROCO PYTOOLS CLI              OK
Python scientific environment  OK
NetCDF / NetCDF-Fortran        OK
Fortran extension toolsf       OK
BENGUELA grid generation       OK
Mercator initial conditions    OK
Mercator boundary conditions   OK

ERA5 y una simulación completa con forcing atmosférico no se consideran necesarias para esta validación básica.

Tag summary

Recent tags

Content type

Unrecognized

Digest

sha256:11b2d4804…

Size

1.8 GB

Last updated

about 1 month ago

docker pull ccervantess/livecroco:2.1.2-sif