xenotech/palm-docker repository overview

⁠PALM-Docker

This is the containerized version of the Large Eddy Simulation solver PALM (version 6.0, rev.3678). As it comes with all dependencies, the rather complex installation process is avoided, lowering the entry barrier for new users. It is designed to run as an executable container on a single node.

⁠What is PALM?

PALM is an advanced and modern meteorological model system for atmospheric and oceanic boundary-layer flows. It has been developed as a turbulence-resolving large-eddy simulation (LES) model that is especially designed for performing on massively parallel computer architectures. Since PALM 5.0, the model is shipped along with several PALM-4U (PALM for urban applications, read: PALM for you) components that allow to employ the model for various urban applications ranging from the meso- to the microscale.

The PALM model system has been mainly developed and is maintained by the ​PALM group⁠ at the ​Institute of Meteorology and Climatology⁠ (IMUK) of Leibniz Universität Hannover, Germany. The model is based on the non-hydrostatic, filtered, incompressible Navier-Stokes equations in Boussinesq-approximated form (an anelastic approximation is available as an option for simulating deep convection). See the source code⁠ (login required) and submit bug tickets⁠ (only relating to the solver, not this Docker image).

The PALM model system is free software. It can be redistributed and/or modified under the terms of the GNU General Public License (v3).

⁠Disclaimer

This is an inofficial Docker image of PALM, not created or maintained by the original creators of PALM.

⁠How to use this image

⁠Running the image

The easiest way to use this image as an executable container, is to define a palm-docker() function in your .bashrc file.

If you want to bind mount local JOBS and tmp folders, define in your .bashrc:

palm-docker(){
	docker run --rm -it \
		-v $(pwd)/JOBS:/home/palm/palm/current_version/JOBS:rw \
		-v $(pwd)/tmp:/home/palm/palm/current_version/tmp:rw \
        --cap-add=SYS_PTRACE \
		--name palm-docker \
		xenotech/palm-docker:6.1 $*
}

Note, that you will have to call the palm-docker function from the directory just above your JOBS and tmp folders on your host as the function expects to find them in the current working directory $(pwd). If these folders do not exist on your host, Docker will create them for you (but with palm user as owner, see further below).

If you have already a volume palm-jobs with job definitions and also want to collect all temporary simulation data in a separate volume called palm-tmp, define:

palm-docker(){
	docker run --rm -it \
		-v palm-jobs:/home/palm/palm/current_version/JOBS:rw \
		-v palm-tmp:/home/palm/palm/current_version/tmp:rw \
        --cap-add=SYS_PTRACE \
		--name palm-docker \
		xenotech/palm-docker:6.1 $*
}

If the volumes do not exist during the first call to this function, Docker will create them for you (empty, of course). After the first start, the volumes persist and you can fill the palm-jobs volume with job definitions.

To run a PALM simulation, replace the usual palmrun by the newly created function, e.g.:

$ palm-docker -r <job_name> -a "d3#"

⁠Data persistence

To provide the configuration & input files and to persist the simulation results you can either bind mount⁠ folders from the host file system or bind volumes⁠, as explained just above. It is the recommended and easier way to use volumes, but the palm-jobs volume must be prefilled in advance with PALM jobs definitions. The biggest drawback of bind mounting local folders into the container, is the requirement that the user and group ids of the user palm inside the container must be the same as the owner of the JOBS and tmp folders on your host, otherwise PALM will not be able to write data into them.

⁠Bind mount local file content

TBD

⁠Use Docker volumes

TBD

⁠Final notes

⁠Versioning

This image uses the PALM tag number as the first digit, and increments the second digit with every image build.

⁠SYS_PTRACE

The bash function proposed to start the container as an executable contains the optional argument --cap-add=SYS_PTRACE. This prevents ugly warnings which would flood the log files as explained here⁠.