Using the MAPL tutorials - GEOS-ESM/MAPL GitHub Wiki
Introduction
The overall instructions for the MAPL tutorials can be found in this README.
It will detail how to run the tutorials. Note each tutorial case has its own readme in the corresponding tutorial directory. For example the README for the first tutorial is here
Running on your Local Machine or NASA Computing Center
If you can and have built MAPL either on a NASA computer resource like NCCS or NAS, or have built MAPL on your local Linux or MacOS machine, you can just play with and run the tutorials that resource. There is no need bother with the rest of this page on running in a container. That is for people who can not build MAPL themselves. Just go to the README.md and start there.
Containers
The MAPL Tutorials can also be run in our containers as well. When MAPL is released, two containers are built, one using GCC compilers and Open MPI and one using Intel compilers and Intel MPI. The containers can be found at both Docker Hub and on GCHR.
In the examples below we will be using the 2.31.0 Intel container from Docker Hub. On Docker Hub, for example, the 2.31.0 Intel container is tagged as:
gmao/mapl:2.31.0-intel
while the GHCR version is:
ghcr.io/geos-esm/mapl:2.31.0-intel
These are equivalent, so all commands below using the Docker Hub container can be run with the GHCR image as well.
Moreover, the gcc container just has -gcc at the end rather than -intel:
gmao/mapl:2.31.0-gcc
Pulling the Container
To pull the container, run:
docker pull gmao/mapl:2.31.0-intel
Using the run tutorial case script
First will will show how to run the run_tutorial_case.sh script. This can be done two ways, directly from the container and within
Directly via docker run
The direct method is to docker run the script directly. Note that you will see some errors at the start because the script currently assumes a user is running not via container, but on a system that uses our g5_modules script to control module files. But the command does still run:
$ docker run --rm -it gmao/mapl:2.31.0-intel /MAPL/install/bin/run_tutorial_case.sh /MAPL/install/ hello_world
basedir: Undefined variable.
/MAPL/install//bin/g5_modules.sh: line 27: /init/bash: No such file or directory
/MAPL/install//bin/g5_modules.sh: line 28: module: command not found
usemods: Undefined variable.
mods: Undefined variable.
MAPL: No configure file specified for logging layer. Using defaults.
Starting pFIO input server on Clients
Starting pFIO output server on Clients
...
----hello_world 1 0.000 0.46 0.000 0.46
----HIST 1 0.000 0.20 0.000 0.20
----EXTDATA 1 0.000 0.23 0.000 0.23
Running inside the container
You can also run inside the container if you wish by getting a bash shell:
$ docker run --rm -it gmao/mapl:2.31.0-intel bash
Once inside, you can just run:
# /MAPL/install/bin/run_tutorial_case.sh /MAPL/install/ hello_world
basedir: Undefined variable.
/MAPL/install//bin/g5_modules.sh: line 27: /init/bash: No such file or directory
/MAPL/install//bin/g5_modules.sh: line 28: module: command not found
usemods: Undefined variable.
mods: Undefined variable.
MAPL: No configure file specified for logging layer. Using defaults.
Starting pFIO input server on Clients
Starting pFIO output server on Clients
MAPL: Running with MOAB library for ESMF Mesh: F
SHMEM: NumCores per Node = 1
SHMEM: NumNodes in use = 1
...
Running specific examples manually
To run an example directly and not via run_tutorial_case.sh. For now we'll use hello_world as the example.
Directly via docker run
For the case of hello_world, we need to provide a working directory because when you run a case manually, you must do it inside it's install path. For hello_world in the container this is /MAPL/install/etc/mapl_tutorials/hello_world/.
For docker run you use the -w or --workdir option which tells it to run the command in this directory.
$ docker run --rm -it -w /MAPL/install/etc/mapl_tutorials/hello_world/ gmao/mapl:2.31.0-intel mpirun -np 1 /MAPL/install/bin/Example_Driver.x --root_dso /MAPL/install/lib/libMAPL.hello_world_gridcomp.so
MAPL: No configure file specified for logging layer. Using defaults.
Starting pFIO input server on Clients
Starting pFIO output server on Clients
MAPL: Running with MOAB library for ESMF Mesh: F
SHMEM: NumCores per Node = 1
...
----HIST 48 0.001 2.18 0.001 2.18
--Finalize 1 0.001 2.15 0.001 1.70
----hello_world 1 0.000 0.20 0.000 0.20
----HIST 1 0.000 0.11 0.000 0.11
----EXTDATA 1 0.000 0.13 0.000 0.13
Running inside the container
Like above, we get a shell, but now we have to cd to the case directory:
$ docker run --rm -it gmao/mapl:2.31.0-intel bash
# cd /MAPL/install/etc/mapl_tutorials/hello_world/
Now you can run the example directly:
# mpirun -np 1 /MAPL/install/bin/Example_Driver.x --root_dso /MAPL/install/lib/libMAPL.hello_world_gridcomp.so
MAPL: No configure file specified for logging layer. Using defaults.
Starting pFIO input server on Clients
Starting pFIO output server on Clients
MAPL: Running with MOAB library for ESMF Mesh: F
SHMEM: NumCores per Node = 1
SHMEM: NumNodes in use = 1
SHMEM: Total PEs = 1
...
----hello_world 1 0.000 0.47 0.000 0.47
----HIST 1 0.000 0.19 0.000 0.19
----EXTDATA 1 0.000 0.34 0.000 0.34
Changes for GCC Containers
When using the GCC containers, you must make a changes to run the examples. The issue is that Open MPI, by default, does NOT allow one to run as root, and when you run with Docker, you are the root user. If you try to run you'll see:
$ docker run --rm -it gmao/mapl:2.31.0-gcc /MAPL/install/bin/run_tutorial_case.sh /MAPL/install/ hello_world
basedir: Undefined variable.
/MAPL/install//bin/g5_modules.sh: line 27: /init/bash: No such file or directory
/MAPL/install//bin/g5_modules.sh: line 28: module: command not found
usemods: Undefined variable.
mods: Undefined variable.
--------------------------------------------------------------------------
mpirun has detected an attempt to run as root.
Running as root is *strongly* discouraged as any mistake (e.g., in
defining TMPDIR) or bug can result in catastrophic damage to the OS
file system, leaving your system in an unusable state.
We strongly suggest that you run mpirun as a non-root user.
You can override this protection by adding the --allow-run-as-root option
to the cmd line or by setting two environment variables in the following way:
the variable OMPI_ALLOW_RUN_AS_ROOT=1 to indicate the desire to override this
protection, and OMPI_ALLOW_RUN_AS_ROOT_CONFIRM=1 to confirm the choice and
add one more layer of certainty that you want to do so.
We reiterate our advice against doing so - please proceed at your own risk.
--------------------------------------------------------------------------
So, we need to do one of two things. If you are running directly with docker run you need to pass the environment variables detailed in the message (since you can't directly change the mpirun command). To do this add them with -e env-var:
mathomp4@ip-172-31-58-186:~$ docker run --rm -it -e OMPI_ALLOW_RUN_AS_ROOT=1 -e OMPI_ALLOW_RUN_AS_ROOT_CONFIRM=1 gmao/mapl:2.31.0-gcc /MAPL/install/bin/run_tutorial_case.sh /MAPL/install/ hello_world
basedir: Undefined variable.
/MAPL/install//bin/g5_modules.sh: line 27: /init/bash: No such file or directory
/MAPL/install//bin/g5_modules.sh: line 28: module: command not found
usemods: Undefined variable.
mods: Undefined variable.
MAPL: No configure file specified for logging layer. Using defaults.
Starting pFIO input server on Clients
If you are running by hand, you'll need to add the --allow-run-as-root option:
# mpirun --allow-run-as-root -np 1 /MAPL/install/bin/Example_Driver.x --root_dso /MAPL/install/lib/libMAPL.hello_world_gridcomp.so
MAPL: No configure file specified for logging layer. Using defaults.
Starting pFIO input server on Clients
Starting pFIO output server on Clients
MAPL: Running with MOAB library for ESMF Mesh: F
...