# Setting up an environment

We use a [this Docker software container](https://hub.docker.com/layers/deeplearnphysics/larcv2/ub20.04-cuda11.1-cudnn8-pytorch1.9.0-larndsim/images/sha256-531e5a9c7ec30b2d64e9a7173859b8658ba85ead929523b24ec4f9430c7af5d6?context=explore)! To run this container...

* If you work on a linux system, we recommend [Singularity](https://singularity.hpcng.org/)
* If you work on OSX/Windows, we recommend [Docker](https://www.docker.com/)
* If you wanna learn just a little extra for better usability, we highly recommend [Podman](https://podman.io/)!

## Supported GPUS
* Turing (RTX 2000) architectures
* Volta architectures (e.g. V100)
* Ampere architectures (e.g. RTX3000 series, A100)

## Currently unspported GPUs
* Kepler architecture (e.g. K40/K80)
* Pascal architecture (e.g. GTX 1000 series, P100, Titan Xp)

## Singularity
First, if you haven't, you can pull and convert the docker image as follows:

singularity pull docker://deeplearnphysics/larcv2:ub20.04-cuda11.1-cudnn8-pytorch1.9.0-larndsim

... then you should see a file named `larcv2_ub20.04-cuda11.1-cudnn8-pytorch1.9.0-larndsim.sif`. Thats your image file!

To run a singularity container, try:

singularity exec --nv larcv2_ub20.04-cuda11.1-cudnn8-pytorch1.9.0-larndsim bash

Using Singularity, it's almost like you log (ssh) into another machine. You might wonder: "wait, what happened to my file system?? do I have to copy data files into a container?" You don't have to! First of all, your very own home area is mounted. Try `cd $HOME`. You can also mount more directories from your machine into a container using`--bind` option.

## Docker
In case of a docker, you will be essentially running a container as a root user. So you want to be careful about file permissions: you have rights to do anything within a container as a super user, but files you created in the mounted space from your host machine will remain as root-owned files :(

As a result, a common issue happens when you log out and try to remove files by `sudo rm` as you might accidentally remove files you did not mean to. That would be a disaster.

To avoid this, let's first create a directory dedicated for working inside the container. After done working in a container, we can just remove the work directory.

cd $HOME
mkdir workshop_area

Now let's run docker. This isn't the best-practice flags to run a docker, but hopefully least hassle for the workshop.

docker run -it --rm --net=host --mount type=bind,source=$HOME/workshop_area,target=/workshop_area --entrypoint=bash deeplearnphysics/larcv2:ub20.04-cuda11.1-cudnn8-pytorch1.9.0-larndsim

cd /workshop_area

Now you can work in this area. For instance, to start a jupyter session:

jupyter lab --allow-root