ROCKE-3D Docker Image

Docker/Podman image to install and run a containerised ROCKE-3D on Fedora.

Useful links

• ROCKE-3D Model Description (doi:10.3847/1538-4365/aa7a06)
• ROCKE-3D Webpage
• ROCKE-3D Compilers & libraries
• ROCKE-3D Installation
• ROCKE-3D Tutorial Videos
• ROCKE-3D Publication Supplements (inc rundecks)
• Docker build help
• Docker run help

Installation & running via published image

• Install service & check it's running:

Service	Instructions
Apptainer	Apptainer installation
Docker	Install Docker desktop
Podman	Podman installation

• Download published image:

Service	Instructions
Apptainer	apptainer pull rocke3d.sif docker://woodwardsh/rocke3d:latest
Docker	docker pull woodwardsh/rocke3d:latest
Podman	podman pull woodwardsh/rocke3d:latest

• Navigate to chosen directory for storing model input and output using cd
• Ensure model input/output folders have been created:

mkdir -p exec huge_space prod_decks prod_input_files prod_runs

• Run/start container, noting:
  • the mounting of local current working directory (${PWD}) to container path /home/app/ModelE_Support for shared storage of model input/output
  • apptainer (see apptainer cli docs):
    • --compat: improves compatability with Docker source images
    • --unsquash -w: allow permanent file writing to container
    • cd /home/app: to navigate to home directory in container (instead of outside user's home directory which is default)
    • export HOME=/home/app: to manually update $HOME
    • export LC_CTYPE=C; export LANG=C: fix perl locale errors (may not be needed for apptainer exec or apptainer shell commands)
  • docker & podman:
    • -itd: interactive & TTY (starts shell inside container) & detached
  • podman:
    • --security-opt label=disable: fixes permissions on mounted volumes (see podman run)

Service	Instructions
Apptainer	apptainer instance start --bind ${PWD}:/home/app/ModelE_Support --compat --no-mount bind-paths --no-home --unsquash -w rocke3d.sif apptainer shell instance://rocke3d cd /home/app; export HOME=/home/app; export LC_CTYPE=C; export LANG=C
Docker	docker run -itd --volume=${PWD}:/home/app/ModelE_Support woodwardsh/rocke3d:latest
Podman	podman run -itd -v ${PWD}/ModelE_Support:/home/app/ModelE_Support --security-opt label=disable woodwardsh/rocke3d:latest

Installation & running via locally built image

• Clone repo & navigate inside:

git clone [email protected]:hannahwoodward/docker-rocke3d.git && cd docker-rocke3d

Docker

• Build image from Dockerfile (~15 min):

docker build -t rocke3d .

• Or, if debugging:

docker build -t rocke3d . --progress=plain --no-cache

• Navigate to chosen directory for storing model input and output using cd
• Ensure model input/output folders have been created:

mkdir -p exec huge_space prod_decks prod_input_files prod_runs

• Run locally built container:

docker run -itd -v ${PWD}/ModelE_Support:/home/app/ModelE_Support rocke3d

Podman

• Build with similar command, replacing docker with podman:

podman build -t rocke3d .

• Navigate to chosen directory for storing model input and output using cd
• Ensure model input/output folders have been created:

mkdir -p exec huge_space prod_decks prod_input_files prod_runs

• Start container from image, with additional options to fix permissions on mounted volumes (see podman run):

podman run -itd -v ${PWD}/ModelE_Support:/home/app/ModelE_Support --security-opt label=disable rocke3d

Testing

• Start container
• Run sh test-earth.sh (output written to ModelE_Support/huge_space/E1oM20_Test)
• Run sh test-planet.sh (uses SOCRATES; output written to ModelE_Support/huge_space/P1SoM40_Test)

Diagnostics & Post-processing

• ROCKE-3D Diagnostics info
• The following directories have been added to $PATH, which contain scripts to generate readable netcdf model outputs. Use both in model output directories (i.e. ModelE_Support/huge_space/<simulation_name>:
  • $HOME/$MODELDIR/model/mk_diags:
    • scaleacc for interim/accumulative source files (e.g. PARTIAL.acc$RUN_ID.nc aij)
    • sumfiles to combine multiple acc files across different time periods
    • Documention can be found in $MODELDIR/model/mk_diags/conventions.txt
  • $HOME/bin:
    • scaleaccm the multifile equivalent of scaleacc, usage e.g. scaleaccm "ANN*.acc*.nc" aij

Publishing image

docker login && docker tag rocke3d woodwardsh/rocke3d && docker push woodwardsh/rocke3d

Model info

• Create a rundeck P2{G,S}{A,x,N}{p,q,o}{F,M}40
  • GISS/SOCRATES radiation
  • Atmosphere of PI Earth Ocean {p,q,o}
  • M40 4degx5deg with 40 layers in atmosphere, 13 layers in ocean
• Rundeck start/stop times:
  • YEAR is just an index, MONTH always 1 to 12, HOUR always 0 to 23
    • Calendar system used divides days into 24 model "hours" and years into 12 "months", so with varying orbital/rotation periods will therefore not generally be 3600s or 720hrs, respectively
  • ISTART=2 way to tell the model that initial conditions will be provided (AIC atmosphere, ground GIC, and if relevant ocean OIC)
  • IRANDI=X random number generation seed/adding numerical noise, used for cloud generation
  • master_yr=1850 tells model to use Earth greenhouse gas concentrations
  • master_yr=0 runs a transient simulation
• For non-Earth continental configurations:
  • Ensure land mass added at south pole to prevent grid singularity issues
  • Update OCNDYN.f#L5812: J1O=1 (or whatever latitude south pole landmass ends at, default J1O=4, default in image J1O=1)