IBSIMU simulation package in a Docker container
Easiest way of running IBSIMU on Windows
IBSIMU is a very capable simulation tool for 2D and 3D particle tracing in electric and magnetic fields taking into account the field created by the charged particles themselves. I already covered how to run IBSIMU on a modern Ubuntu release and how to bootstrap an AWS instance for that*.
This time I want to expand on number of ways one can launch IBSIMU by making a Docker container.
From previous exercises we know how to set up IBSIMU on Ubuntu 20.04. This time we start from the basic image of Ubuntu 20.04 and we will build it so that we can run it with an X11 display forwarded to a host machine (a windows machine in my case). In order to create a docker image we will create a docker file. Beginning of our dockerfile is the following:
The first line defines our base image. The second specifies a non-interactive environment so that installed packages will not hold installation indefinitely unless we give them our timezone information (or other equally important). SHELL command allows us to switch the default shell and have access to bash commands.
Two ARG statements define a default user we will create ARG username=ubuntu
and ARG password=ubuntu
. Tough our environment is a sandbox, we will limit the use of root and will use our non-root user instead.
RUN statement contains a long chain of bash commands we want to execute to create our image.
We start with apt-get update as there is an empty package index in the default Ubuntu 20.04 image. Then we proceed by installing dependencies we need for IBSIMU and a few utilities such as sudo and curl.
Then we add our user with a name taken from ARG statement in the beginning. At first our user created without a password, and then we change it from nothing to a password (from the second ARG statement). I have it done this way to avoid being interactively asked to set a password (if you know a more straightforward way — tell me). Then I give my user sudo privileges and switch to continue as the non-root user in their home directory.
I download IBSIMU source code (a particular build I found reliable), extract it from an archive, and perform compilation, checks and installation.
Finally I copy folder with some further information from my local folder where I have the docker file with COPY --chown=$username ./home/$username
In one of the folders I have settings to run my cases and interact with the host X11 server. The other folder is meant to load some test cases. I have COPY
statement with--chown
option, otherwise copied folder will be own by root, as dockerfile commands are executed as root.
In the settings folder I have the following shell script
It will export several environmental variables into .bashrc file. In order to enable X11 graphics from IBSIMU on your windows host machine you will need the following: open command prompt and by using ipconfig
find out your machine IPv4 IP address (likely 192.168.x.x). You would also need an X11 server to show graphical window. I can recommend VcXsrv (). When launching the server you will need to disable access filtering to allow the server to accept request from Docker image.
With these preparations complete I can create my docker image with
docker build --no-cache . -t ibsimu_stack
Building this image takes about 8 minutes on my desktop, largely due to IBSIMU compilation. But in general you only need to do it only once. When the image is build we can start it as command line interactive (--it
) as our non-root user (-- user ubuntu
) using the following command:
docker run -it --user ubuntu ibsimu_stack
once we are there cd ~/ibsimu/ibsimu_config
and run ./ibsimu_config.sh
~ followed by source ~/.bashrc
/ in order to export and reload environmental variables.
Now we can run a test case if we go to ~/ibsimu/ibsimu_tests/einzel_lens
and run in there make
followed by ./einzel
. In a matter of tens of seconds you should see the result of the run. Now everything is set up. This looks to me as the easiest way to have IBSIMU ready for use on Windows.
I am quite impressed by IBSIMU capabilities and surprised by relatively low adoption in the community. I partly attribute it to quite high entrance threshold, and hope to help lowering the barrier for wider public.
Just to illustrate IBSIMU’s capabilities. The world most famous accelerator is Large Hadron Collider (LHC) in Geneva. At the very beginning of LHC complex is a linear accelerator Linac4. Linac4 is fed by a source of negative hydrogen ions H-. This is literally beginning of LHC. You can see (hallelujah — Open Access under creative common license) how IBSIMU helped to optimize the low energy injection from the source to Linac4 (btw we were officemates with the first author for several years). This is the ion source powering the biggest and best known accelerator in the world history.
I think if people can have easier access to such a powerful modelling package, they will fully appreciate what it can give to them. Hope it helps to get more people using IBSIMU.
All files and scripts of this articles can be found on github.