Do I need this?
You probably only want to use this if you are very new to preCICE and want to learn, for example during our preCICE Workshops or other conferences where we may be present with a training session.
After trying this out for a few days, you probably want to just delete it and install only the components you need directly on your target system.
What is this?
After installing this on any operating system, you will be able to start a virtual machine with Linux and a lightweight graphical interface. You can do anything you like in there, without breaking anything. This will download a very large file (~4GB), will occupy significant storage space (~10GB), and will reserve 2GB of main memory while running, but you can easily delete it when you don’t need it anymore.
See what is included in detail.
How to use this?
You can use this on any mainstream operating system (Windows/macOS/Linux), but it is necessary that your CPU supports virtualization (most systems nowadays do) and that this is enabled in your BIOS/UEFI settings. Note once more that this will consume a significant amount of storage and main memory space.
- Install Vagrant and VirtualBox (6.0 or later).
- Start your terminal / command prompt and go to an empty directory.
vagrant init precice/precice-vmto prepare the directory.
vagrant upto download the box (~4GB) and start the system.
- A window should eventually pop-up (or look for it in VirtualBox). The login password in
After logging in, start a terminal (e.g. terminator) from the applications menu.
On the Desktop (
cd ~/Desktop/) you can find the basic solverdummy examples, as well as the tutorials.
Most adapters are already built and available in the home directory.
In case of deal.II, you first need to copy the adapter from
~/dealii-adapter/ (built in 2D mode) wherever you need it.
We are working on different aspects needed to make this experience better.
You can turn off the system normally from the GUI and start it again with
What else may I want to do?
Sharing files and clipboard
Vagrant gives access to the same directory where you downloaded the box into.
If you add any files there from your host system, you will be able to see them in
~/Desktop/shared or in
You can enable copy-pasting text by clicking in the VirtualBox menu bar at
Devices > Shared Clipboard > Bidirectional. The VirtualBox Guest Additions
that enable this are already installed.
Even though you can directly start the VM again by clicking on it in VirtualBox, it is important
that you start it with
vagrant up to set up these features.
Changing the keyboard layout
The default keyboard layout is US English (QWERTY).
Change this clicking on the
Keyboard link on the Desktop,
removing the already added en-us layout, and adding yours.
Installing additional software
You can install additional software using
sudo apt install <package>,
without any password.
In terms of editors, gedit, vim, and nano are already installed.
If you need a more advanced editor with a GUI, you can
install VSCode by running
If you double-click on it, it will run silently. Wait for a bit
and you will then find it under a new category
in the applications menu.
Updating the system
preCICE, the tutorials, and all adapters are installed from their
Git repositories in the home directory, using their main/master branches.
You can do a
git pull at any time to get the latest state
of each package.
You can also update the complete box, but this will delete the previous one and you will lose any changes.
To go back to the state before trying this, run
vagrant box remove precice/precice-vm,
and uninstall Vagrant and VirtualBox.