Skip to content

Latest commit

 

History

History
263 lines (223 loc) · 9.35 KB

docker_setup_windows.md

File metadata and controls

263 lines (223 loc) · 9.35 KB

curl https://cernbox.cern.ch/remote.php/dav/public-files/9T2zAjpvL2ee9jZ/baler.zip --output baler.zip tar -xf baler.zip cd baler docker run --mount type=bind,source=%cd%/projects/,target=/baler-root/projects --mount type=bind,source=%cd%/data/,target=/baler-root/data pekman/baler:latest --project=example_CFD --mode=train

Running with Docker on Windows#

Prerequisites

  • You must have Docker installed. See this guide

Download Data and Project Directory

First download tutorial data and project directories.

curl https://cernbox.cern.ch/remote.php/dav/public-files/9T2zAjpvL2ee9jZ/baler.zip --output baler.zip

Unzip the files

tar -xf baler.zip

Enter the root directory of baler

cd baler

This process has created the following directory tree:

.
├── data
│   ├── example_CFD
│   │   └── example_CFD.npz
│   └── example_CMS
│       └── example_CMS.npz
└── projects
    ├── example_CFD
    │   ├── compressed_output
    │   ├── decompressed_output
    │   ├── example_CFD_config.py
    │   ├── model
    │   ├── plotting
    │   └── training
    └── example_CMS
        ├── compressed_output
        ├── decompressed_output
        ├── example_CMS_analysis.py
        ├── example_CMS_config.py
        ├── example_CMS_preprocessing.py
        ├── model
        ├── plotting
        └── training

For the tutorial example, we want to compress the data called example_CFD.npz. The configuration file for this, including the compression ratio, number of training epochs, input data path etc is defined in projects/example_CFD/example_CFD_config.py. the output of the compressed file is projects/example_CFD/compressed_output/.

Running

Training

Here is the command to start training the network on the example_CFD data:

docker run \
-u ${UID}:${GID} \
--mount type=bind,source=${PWD}/projects/,target=/baler-root/projects \
--mount type=bind,source=${PWD}/data/,target=/baler-root/data \
pekman/baler:latest \
--project=example_CFD \
--mode=train

In this command, the "fixed" lines are:

  • docker run invokes docker and specifies the running of a container
  • -u ${UID}:${GID} tells the container to use your username to create files
  • --mount type=bind,source=${PWD}/projects/,target=/baler-root/projects mounts the local (host) directory ./projects to the container at /projects
  • --mount type=bind,source=${PWD}/data/,target=/baler-root/data mounts the local (host) directory ./data to the container at /data
  • pekman/baler:latest specifies the container to run

And the user defined lines are:

  • --project=example_CFD specifies the current "project", i.e. the directory for the config file and the output
  • --mode=train specifies the current running mode of Baler. We start by training the network on the data

Compress

To compress and decompress the data use --mode=compress

docker run \
-u ${UID}:${GID} \
--mount type=bind,source=${PWD}/projects/,target=/baler-root/projects \
--mount type=bind,source=${PWD}/data/,target=/baler-root/data \
pekman/baler:latest \
--project=example_CFD \
--mode=compress

Compress

To compress and decompress the data use --mode=decompress

docker run \
-u ${UID}:${GID} \
--mount type=bind,source=${PWD}/projects/,target=/baler-root/projects \
--mount type=bind,source=${PWD}/data/,target=/baler-root/data \
pekman/baler:latest \
--project=example_CFD \
--mode=decompress

Plotting

After that training, compression, and decompression you can plot the performance of the procedure by using --mode=plot. In this tutorial example, the performance plot is found in projects/exmaple_CFD/plotting/comparison.jpg To compress and decompress the data use --mode=decompress

docker run \
-u ${UID}:${GID} \
--mount type=bind,source=${PWD}/projects/,target=/baler-root/projects \
--mount type=bind,source=${PWD}/data/,target=/baler-root/data \
pekman/baler:latest \
--project=example_CFD \
--mode=plot

Running with GPU

Baler can be run with GPU acceleration, to allow the Docker image access to the system GPU you need to add --gpus all right after docker run in the run command:

docker run \
--gpus all \
-u ${UID}:${GID} \
--mount type=bind,source=${PWD}/projects/,target=/baler-root/projects \
--mount type=bind,source=${PWD}/data/,target=/baler-root/data \
pekman/baler:latest \
--project=example_CFD \
--mode=plot

Build Docker image

If you would prefer not to use the Docker image provided by us, you may build the image yourself. This is achieved with:

docker build --rm -t myBaler:latest .

This image may be run using by specifying the image myBaler:latest instead of our pekman/baler:latest in the above base command.

Developing using Docker image

Docker presents some obstacles to live development, if you wish changes to be made to a Docker container it must be rebuilt. This slows development and can be frustrating.

An alternative is to use Docker volumes (mounts between local and container file systems) to shadow the source files in the container.

An example command is given here:

docker run \
-u ${UID}:${GID} \
--mount type=bind,source=${PWD}/projects/,target=/baler-root/projects \
--mount type=bind,source=${PWD}/data/,target=/baler-root/data \
--mount type=bind,source=${PWD}/baler/modules,target=/baler-root/baler/modules \
--mount type=bind,source=${PWD}/baler/baler.py,target=/baler-root/baler/baler.py \
pekman/baler:latest \
--project=example_CFD \
--mode=train

Where:

  • --mount type=bind,source=${PWD}/baler/modules,target=/baler-root/baler/modules mounts the local source code directory shadowing the source files built into the container
  • --mount type=bind,source=${PWD}/baler/baler.py,target=/baler-root/baler/baler.py mounts the main baler source file shadowing that in the container

Please note, this mounting does not permanently change the behavior of the container, for this the container must be rebuilt.

Running with Apptainer (Singularity) on a cluster

Docker is not available on all platforms, particularly high-performance or shared environments prefer not to use Docker due to security concerns. In these environments, Apptainer (formerly Singularity) is generally preferred and available.

In order to run Baler on a managed platform may require additional options to work with the system wide Apptainer configuration and respect good practice such as writing to appropriate storage areas, preferably not in on a shared storage space.

Create and enter workspace directory:

mkdir workspace
cd workspace

Download and unzip the example datasets:

wget https://cernbox.cern.ch/remote.php/dav/public-files/9T2zAjpvL2ee9jZ/baler.zip
unzip baler.zip

By default, Apptainer/singularity will write to your home area, this is not desirable on most remote environments. To control this:

export APPTAINER_CACHEDIR=${PWD}
export SINGULARITY_CACHEDIR=${PWD}

To build an Apptainer sandbox, a container completely constrained within a specified local directory, the following command can be run:

apptainer build --sandbox baler-sandbox docker://pekman/baler:latest

Where:

  • apptainer build specifies the building of an Apptainer image
  • --sandbox baler-sandbox/ specifies the output directory for the sandboxed container
  • docker://ghcr.io/uomresearchit/baler:latest specifies that a the Baler Docker image should be targeted

Now that the sandbox has been created, we can run the container.

Training

apptainer run \
--no-home \
--no-mount bind-paths \
--pwd /baler-root \
--nv \
--bind ${PWD}/baler/projects/:/baler-root/projects \
--bind ${PWD}/baler/data:/baler-root/data \
baler-sandbox/ \
--project=example_CFD \
--mode=train

Where:

  • -no-home specifies to not mount the user's home directory (small, networked storage on Blackett)
  • --no-mount bind-paths specifies to not mount the directories specified in the global Apptainer config
  • --pwd /baler-root sets the working directory for the container runtime
  • --nv allows the use of Nvidia graphics cards

Compressing

apptainer run \
--no-home \
--no-mount bind-paths \
--pwd /baler-root \
--nv \
--bind ${PWD}/baler/projects/:/baler-root/projects \
--bind ${PWD}/baler/data:/baler-root/data \
baler-sandbox/ \
--project=example_CFD \
--mode=compress

Decompressing

apptainer run \
--no-home \
--no-mount bind-paths \
--pwd /baler-root \
--nv \
--bind ${PWD}/baler/projects/:/baler-root/projects \
--bind ${PWD}/baler/data:/baler-root/data \
baler-sandbox/ \
--project=example_CFD \
--mode=decompress

Plotting

apptainer run \
--no-home \
--no-mount bind-paths \
--pwd /baler-root \
--nv \
--bind ${PWD}/baler/projects/:/baler-root/projects \
--bind ${PWD}/baler/data:/baler-root/data \
baler-sandbox/ \
--project=example_CFD \
--mode=plot