Xlab / Quick Start /

In order to be cross-platform, XLab has been dockerized. The following instructions are tailored to Linux systems (Debian in particular) but the spirit is the same for other operating systems.
WINDOWS USERS: please backup your data before installing docker.

Install Docker



1. Install the docker engine on your system. As an example, if you are on Debian:
   $ sudo apt-get update
$ sudo apt-get install \
   ca-certificates \
   curl \
   gnupg \
   lsb-release
$ sudo mkdir -p /etc/apt/keyrings
$ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
$ echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
   $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
$ sudo apt-get update
$ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

2. Run a test container:
   $ sudo docker run --rm hello-world
3. Add sudo privileges to docker:
   $ sudo groupadd docker
$ sudo usermod -aG docker $USER
Log out and log back. Verify that you can run docker without sudo:
   $ docker run --rm hello-world




Load an xlab image



1. Download an xlab image.
2. Load the image on your system: inside your download directory,
   $ docker load < xlab-docker-123456.tar.gz
   This can take a few minutes.





Run an xlab container



1. Test that you can run an xlab container:
   $ docker run -it --rm xlab
   You should now be given a new prompt. It is bash running inside the container.
2. Look around:
   # ls
3. Exit the container:
   # exit




Compute an example



1. Open acces to X:
   $ xhost +local:
   WARNING: you should undo that once you're done with XLab.
2. Run an xlab container:
   $ docker run -it --rm --volume=/tmp/.X11-unix:/tmp/.X11-unix --device=/dev/dri/card0:/dev/dri/card0 --env "DISPLAY=$DISPLAY" --network="host" xlab
3. Inside the container, compute an example:
   # xlab --compute --gui=gtk xlab/experiments/minimal/catenoid.xlab
4. Have fun. You cannot break the container.
5. Close the XLab windows.
6. Exit the container:
   # exit
7. Close access to X:
   $ xhost -local:




Share directories



1. Make an xlab directory and go to it:
   $ mkdir xlab
$ cd xlab/
2. We want to take a picture of a surface using XLab and bring it back home, outside the container. So make a directory for sharing files between the host and the container:
   $ mkdir shared
3. Open acces to X:
   $ xhost +local:
   WARNING: you should undo that once you're done with XLab.
4. Run an xlab container with the shared directory mounted:
   $ docker run -it --rm \
--volume=/tmp/.X11-unix:/tmp/.X11-unix \
--device=/dev/dri/card0:/dev/dri/card0 \
--env "DISPLAY=$DISPLAY" \
--network="host" \
--volume=[absolute-path-to-shared]:/shared xlab
5. Compute an example (see the corresponding section above).
6. Find your favorite point of view with the mouse in the XLab | Viewer window. You can use the Space key to center the view and the "o" key to go back to the default view. Fullscreen with "f", switch viewers with "r".
7. In the XLab window, right click on the node called "ViewerR3" and select "Open". Maximize your window if necessary.
8. Click on the "Scene" node. Expand the left-hand panel if necessary to select "Controls". Then click on the button right beside "Screenshot".
9. Write
   /shared/my-picture.png
and press Enter.
10. Close the XLab windows and exit the container:
    # exit
11. Close access to X:
    $ xhost -local:
12. Open shared/my-picture.png. You brought your picture home!





Save and read your data



1. Open access to X and run an XLab container with a mounted shared/ directory.
2. Compute the Enneper example:
   # xlab --compute --gui=gtk xlab/experiments/minimal/enneper.xlab
3. Let's modify this surface. Select the node "ComplexVectorFunction1", access Controls on the left panel and change the Text from {z,1} to{z^3,1}. Press Enter. Most of the nodes should turn red.
4. Right click on the SurfaceWriter node and select Compute. Look at the surface: we need a finer domain.
5. Select the SimpleTriGrid node and change the CountMultiplier from 1 to 5. Press Enter, some nodes should turn red. Right click on the SurfaceWriter node and select Compute. Look at the surface: it's much better.
6. If you exit the container now, you will lose the work you've just done. So right click in the background of the node panel and select Write. Put your work in the shared directory:
   /shared/my-surface.xlab
7. Exit the container, close access to X, and take a look at the file shared/my-surface.xlab.
8. To read your data, open access to X, run an XLab container and compute your example:
   xlab --compute --gui=gtk shared/my-surface.xlab
9. You can now read the contents of the examples section.