precice/vm

Vagrant box with preCICE and examples preinstalled

Vagrant box for preCICE, with examples preinstalled

Vagrant files to prepare a Virtual Machine image for preCICE, mainly for demo and teaching purposes.

What does this do?

Vagrant pulls an Ubuntu 20.04 "base box" and asks e.g. VirtualBox to start a virtual machine. It then installs basic tools (such as a desktop environment), a preCICE release, several solvers and adapters, as well as example and tutorial files.

Ready-to-use boxes are available on Vagrant Cloud.

How to use this?

Note: If you only want to directly get a pre-built box, look at the documentation.

1. Get a Virtual Machine provider, such as VirtualBox
2. Get Vagrant
3. Go to the root folder of this repository and start with vagrant up.
4. Be patient. Vagrant will now setup your virtual machine. You don't have to do anything and your terminal will be very busy.
5. After the provisioning finishes, restart the machine with vagrant reload to get a full GUI

You can afterwards also see and manage the produced VM in VirtualBox.

A few things you may need:

• The username and password are vagrant/vagrant
• The keyboard layout is US English (QWERTY). You can change this in install-basics.sh or through the keyboard setting shortcut on ~/Desktop.
• Find scripts to install additional software on ~/Desktop/shared.

What else can I do?

• Suspend and resume the machine: vagrant suspend, vagrant resume
• Turn off or destroy the machine: vagrant halt, vagrant destroy
• Update the machine after you change the related scripts: vagrant provision
• SSH into the machine: vagrant ssh
• Package your already provisioned box (e.g. to reduce the starting time on another machine): vagrant package --base "preCICE-VM" --output preCICE.box
• Change the number of cores and the allocated memory: edit vb.cpus and vb.memory in the Vagrantfile.
• Share files between host and guest system: the guest system's /vagrant/ directory reflects the directory of the Vagrantfile.

What is included?

This box is based on the generic/ubuntu2004 bento/ubuntu-20.04 base box and installs:

• Xubuntu-core (Xfce desktop environment) and related tools
• VirtualBox guest additions
• Terminator (a nice split-window terminal emulator, find it in Applications > System)
• Git, CMake, ccmake
• Editors: nano, vim, gedit
• Diff viewer: meld
• preCICE latest from the master branch (built in release-with-debug-info mode)
• preCICE config visualizer with its GUI (master)
• preCICE Python bindings (PIP)
• preCICE Julia bindings (Pkg)
• preCICE Rust bindings (Cargo)
• preCICE FMI Runner (PIP)
• preCICE Micro Manager (PIP)
• OpenFOAM v2312 and the OpenFOAM-preCICE adapter (master)
• deal.II 9.3 from the official backports and the deal.II-preCICE adapter (master)
• CalculiX 2.20 from source and the CalculiX-preCICE adapter (master)
• FEniCS latest from the FEniCS PPA and the FEniCS-preCICE adapter (PIP)
• SU2 7.5.1 and the SU2-preCICE adapter (master)
• code_aster 14.6 and the code_aster-preCICE adapter (master)
• DUNE 2.9.1 and the experimental DUNE-preCICE adapter (main)
• DuMuX 3.8 and the DuMuX-preCICE adapter (v2.0.0)
• ASTE (master)
• Paraview from APT
• Gnuplot

It then adds to the /home/vagrant/:

• The preCICE examples (solverdummies), including a copy of the Python solverdummy.
• The preCICE tutorials from the precice/tutorials

The adapter repositories remain in /home/vagrant/. It also adds a few shortcuts on the Desktop (see post-install.sh). At the end, it cleans up all object files and the APT cache (see cleanup.sh).

Troubleshooting

This does not seem to work on my machine

Even though most hardware supports virtualization, your CPU may not or you may need to enable it in your BIOS/UEFI settings.

Provisioning fails during an APT update / install

The most common reason can be that one of the third-party APT repositories (such as the repository of OpenFOAM on SourceForge) do not respond. Usually running again (e.g. with vagrant up --provision) helps.

There is no GUI

In case you killed the session before provisioning finished, the setup of your VM might be incomplete. You might still be able to interact with the VM without the GUI. In that case, run vagrant up --provision.

Testing before publishing

We now have a GitHub action that can build the Vagrant box. This workflow only runs for pull requests that are marked as "ready for review" (i.e. not "draft"), as it takes significant time to complete (~1.5h). If you already submitted a normal PR but the workflow is not triggered, you can manually trigger it from the "Actions" tab.

The workflow uploads the resulting box as an artifact and it also prints its SHA256 checksum before that. Download the job artifact and unzip it. Then run add the box to Vagrant:

vagrant box add test-box precice-vagrant-box/preCICE.box 

You can then start a VM by going into an empty directory and executing:

vagrant init test-box
vagrant up

Afterwards, you probably want to destroy everything to save storage space:

vagrant destroy
vagrant box remove test-box

KVM support

If you require a more responsive experience, lower overhead, or exotic features such as GPU pass through, then the libvirt vagrant box is for you. This allows you to run the vagrant box via libvirt and QEMU as a Kernerl Virtual Machine (KVM).

Note The libvirt variant does not work with the bento/ubuntu-20.04 base image, but also the VirtualBox variant does not at the moment work with the generic/ubuntu2004 image. Change the base image in the beginning of the Vagrantfile if you need this feature. See #83 for details.

To use this box, first install the vagrant plugin vagrant-libvirt following the official installation instructions. Then you follow the normal usage instructions above, but you need to tell vagrant to use the libvirt box by passing one additional option:

vagrant up --provider=libvirt

vm's Issues

arm64 Compatibility

Tried installing the VM for a hands-on session on a MacBook with Apple M1 Pro processor.

Vagrant can be installed via brew and works fine.

VirtualBox is not compatible with arm architecture chips, and from what I saw it cannot work with Rosetta. ( https://forums.virtualbox.org/viewtopic.php?t=98742 ). I guess there is not much you can do in terms of fixing it, but maybe there is an alternative for arm systems.

Missing solids4foam

We need this for our new perpendicular-flap/solids4foam tutorial case.

Include config-visualizer

Make shellscripts runnable from the file manager

It would be nice to be able to run a solver directly from the file manager.

An option "Run script" would be useful.

Migrate to release with debug log

We currently build and install preCICE in Debug mode as we need the Debug log

An option to enable Debug log in release builds was introduced in precice/precice#1177 and will be released with 2.4.0.

ASTE not in PATH

Our aste tutorial does not start.

code_aster solver and adapter missing

This is something we simply have not yet added, there is no particular problem expected.

VirtualBox window does not pop up

To... nobody? Maybe there is a way to enforce this.

Cannot open browser when clicking on links in evince

When clicking on a link from Evince (started from inside the Xfce desktop), Evince fails to open the link, reporting a permission denied error when calling /usr/lib/x86_64-linux-gnu/xfce4/exo-2/exo-helper-2.

At the same time, when performing the same task via ssh (vagrant ssh -- -Y), then firefox opens normally.

With a first look, I could not resolve it.

The exact error (in a pop-up):

Failed to launch preferred application for category "WebBrowser".

Failed to execute child process "/usr/lib/x86_64-linux-gnu/xfce4/exo-2/exo-helper-2" (Permission denied).

Missing FMI runner

See https://precice.org/tooling-fmi-runner.html

Nutils for offline use

In #71, I removed Nutils as tutorials now install it on first run.
However, we still sometimes need to run Nutils in offline environments (e.g., a course during a conference, in a remote room, with strange Wi-Fi access, if at all).

Maybe having a default Nutils installation isn't a bad idea after all.

Update VTK version

https://github.com/precice/vm/blob/a37b13a50ade7658e63bd17bbe3230df085bba7f/provisioning/install-aste.sh#LL5C36-L5C36

for ASTE, try VTK 9 from PIP

Related to precice/aste#171

Outdated SU2 version

See https://precice.org/adapter-su2-get.html

Need to disable the screensaver / screen lock

It is just annoying in a VM.

Also disable power management and set blank screen time to "None".

FEniCS is not working

I tried running tutorials/HT/partitioned-heat/fenics-fenics and got an error:

$ python3 heat.py
...
ModuleNotFoundError: No module named 'fenics'

Make paths in provisioning scripts configurable and portable

Some provisioning scripts are useful independently of the VM (e.g., the install-dune.sh). We could make these more portable.

dune-fem no longer needed

vm/provisioning/install-dune.sh

Line 71 in a37b13a

# Install dune-fem from PIP

See precice/tutorials#470 (review)

Missing a diff tool (Meld)

Suggested in the feedback form of the preCICE Workshop 2023.

Not building elastic-tube-1d C++ solvers

We are building the solverdummies and the quickstart solvers, but not the elastic-tube-1d C++ solvers.

Building results into "Failed to restart snapd.mounts-pre.target"

Building on my laptop results very early into:

    default: Setting up snapd (2.61.3+20.04) ...
    default: Installing new version of config file /etc/apparmor.d/usr.lib.snapd.snap-confine.real ...
    default: snapd.failure.service is a disabled or a static unit not running, not starting it.
    default: snapd.snap-repair.service is a disabled or a static unit not running, not starting it.
    default: Failed to restart snapd.mounts-pre.target: Operation refused, unit snapd.mounts-pre.target may be requested by dependency only (it is configured to refuse manual start/stop).
    default: See system logs and 'systemctl status snapd.mounts-pre.target' for details.
    default: Setting up systemd-sysv (245.4-4ubuntu3.23) ...
    default: Setting up libnss-systemd:amd64 (245.4-4ubuntu3.23) ...
    default: Setting up libpam-systemd:amd64 (245.4-4ubuntu3.23) ...
    default: Processing triggers for install-info (6.7.0.dfsg.2-5) ...
    default: Processing triggers for mime-support (3.64ubuntu1) ...
    default: Processing triggers for initramfs-tools (0.136ubuntu6.7) ...
    default: update-initramfs: Generating /boot/initrd.img-5.4.0-169-generic
    default: Error 24 : Write error : cannot write compressed block
    default: E: mkinitramfs failure cpio 141 lz4 -9 -l 24
    default: update-initramfs: failed for /boot/initrd.img-5.4.0-169-generic with 1.
    default: dpkg: error processing package initramfs-tools (--configure):
    default:  installed initramfs-tools package post-installation script subprocess returned error exit status 1
    default: Processing triggers for libc-bin (2.31-0ubuntu9.14) ...
    default: Processing triggers for man-db (2.9.1-1) ...
    default: Processing triggers for plymouth-theme-ubuntu-text (0.9.4git20200323-0ubuntu6.2) ...
    default: update-initramfs: deferring update (trigger activated)
    default: Processing triggers for dbus (1.12.16-2ubuntu2.3) ...
    default: Errors were encountered while processing:
    default:  initramfs-tools
    default: E: Sub-process /usr/bin/dpkg returned an error code (1)
The SSH command responded with a non-zero exit status. Vagrant
assumes that this means the command failed. The output for this command
should be in the log above. Please read the output to determine what
went wrong.

On GitHub Actions, it seems to fail also very early (earlier) with a different issue.

Reducing the code_aster build time

Code_aster takes a significant part of the total build time at the moment, and it looks like it is building several tests. We can probably disable these (not sure how at the moment).

Add DUNE adapter

https://github.com/precice/dune-adapter

There is a case already in the tutorials.

Nutils version: special case for perpendicular-flap

Continuing the discussion from #56 #52, we need Nutils 6.3 only for the perpendicular-flap tutorial.

I am working on a solution for this based on virtual environments.

Not providing dune-fem

Our tutorial case flow-over-heated-plate/solid-dunefem does not start.

Clipboard not shared when starting with vagrant up

It looks like the "Shared Clipboard: bidirectional" setting does not work when starting the VM with vagrant up, but it does work when starting the VM from VirtualBox.

Maybe this is related to the guest additions.

Add offline mirror for pip

We could use devpi to create a local mirror and pull all packages required for the tutorials.

https://devpi.net/docs/devpi/devpi/latest/+d/quickstart-pypimirror.html

# $HOME/.pip/pip.conf
[global]
index-url = http://localhost:3141/root/pypi/+simple/

Missing Micro-Manager

See https://precice.org/tooling-micro-manager-installation.html

Names of precice-config-visualizer aliases

We currently provide precice-config-visualizer and the following aliases for convenience:

• config-visualizer (produces PNG)
• config-visualizer-pdf
• config-visualizer-svg

It would be more useful to have a PNG variant, as image viewers typically easier file navigation.

They would also be more discoverable if they were called similarly to the actual tool:

• precice-config-visualizer-png
• precice-config-visualizer-pdf
• precice-config-visualizer-svg

A GUI-based editor would be nice

We provide a script to install VSCode, but this is a bit of a nuclear option for some people.

We could install gedit already, it is not so large.

Vagrant up leads to blank screen

Since v202202.0.1, the first vagrant up leads to a blank screen in the desktop environment.
I suspect that the issue originated from #37.

When trying this locally (after importing the box), the same issue appeared, but I was able to work around it with a vagrant reload. However, when trying importing the image from Vagrant Cloud normally, the issue persisted.

I revoked that version from the Vagrant Cloud for now and I will also revert #37 if I don't manage to fix it very soon.

MBDyn adapter

We should also add the MBDyn adapter to the VM: https://github.com/precice/mbdyn-adapter

This way, we could also have an installation script to refer people to.

Cannot build the VM on GitHub runners anymore

Recently, it was very random on whether the build workflow would be able to start and provision the VM, resulting early on in the following error:

The guest machine entered an invalid state while waiting for it
to boot. Valid states are 'starting, running'. The machine is in the
'gurumeditation' state. Please verify everything is configured
properly and try again.

Locally, it builds perfectly fine.

I have already tried:

• Restarting the failing jobs multiple times.
• Deleting the cache (did not help, it just gets the boxes again)
• Changing the github runner from macos-12 to macos-13 or to ubuntu-latest. Both don't seem to have Vagrant installed.

Paraview is not in PATH

We currently have a link to Paraview on the Desktop, but we cannot easily start it from the terminal.

Automatic login

It is a bit redundant to have a login screen, since we anyway are using the default password. Let's configure automatic login.

Missing pandas

We need this for the post-processing script of our oscillator tutorial.
It is also a rather common Python dependency and not so large.

Permission errors in repositories

Because of my messy way of executing scripts in provisioning (there are reasons, mostly related to still learning how to provision in Vagrant), users cannot pull the repositories we have already cloned:

$ git pull
error: cannot open .git/FETCH_HEAD: Permission denied

The workaround is to run sudo chown -R vagrant ., but I should fix it from its root.

Options to enable/disable features

Currently, the vm contains everything we support by default, but this ends up being a very large image that take a lot of time to build.

Having options to enable/disable features would be useful, e.g., in the following cases:

• Debugging a specific feature of the vm / ecosystem.
• Needing a reference system just for preCICE itself
• Needing a vm with specific versions of some components, for reproducibility.

This is easy, I will work on it sometime in the next few weeks.

Missing groovyBC

We need it for the Turek-Hron FSI3 benchmark case: https://precice.org/tutorials-turek-hron-fsi3.html

Outdated Nutils version

We currently install Nutils 6.3: https://github.com/precice/vm/blob/main/provisioning/install-nutils.sh

Our latest tutorials are updated to Nutils 7. The channel-transport fluid case does not work with 6.

elastic-tube-3d plot-all-displacements.sh does not produce results

In the elastic-tube-3d tutorial, after running a few time windows of both fluid-openfoam + solid-calculix and fluid-openfoam + solid-fenics, the plot-all-displacements.s exits successfully (exit code 0, no messages), but nothing appears on screen.

gnuplot is installed and I am running in the GUI. @fsimonis observed the same behavior in #50 (comment). This already affected v2202 and maybe earlier versions.

The gnuplot script plot-displacement.sh for the perpendicular-flap seems to work.

I am not sure if this is originating from the tutorials or from the vm, but it is not new. Nothing relevant has changed, neither in the respective tutorial, nor in the vm since v2202.

Need to add Terminator to favorites

We have a nice split-window terminal emulator, yet it is not easily discoverable.

Missing Rust

See https://precice.org/installation-bindings-rust.html

Add some hint for high-resolution screens

Some systems (e.g., MacBook Pro) have high resolution displays, but the settings do not propagate to VirtualBox.

We should try to either set window scaling automatically, or maybe link to the right settings from the Desktop.

GitHub Actions: Switch to a linux runner

Since recently, Linux-based runners seem to support nested virtualization as well.
We are facing some strange issues at the moment building the VM on GitHub runners, and this might help.

Need to move tutorials and examples to the home directory, link from Desktop

We currently get the tutorials on the Desktop, which is inconvenient when using the terminal.
Let's better move them to ~ and link from the Desktop.

Missing DuMuX

See https://precice.org/adapter-dumux-get.html

Wrong version number in release notes of v202202.0.0

The first sentence in the release notes states

This is a scheduled release in the context of the preCICE distribution 2002.0.

I assume this should be 2202.0, i.e.

This is a scheduled release in the context of the preCICE distribution 2202.0.

such that it is consistent with your versioning scheme (yymm).(distribution revision).

Note that these erroneous release notes are also on VagrantCloud: https://app.vagrantup.com/precice/boxes/precice-vm/versions/202202.0.0

Add FEniCSx to the vm

FEniCSx was recently added as a participant to the partitioned-heat-conduction tutorial case: precice/tutorials#317. FEniCSx needs to be added to the vm for the tutorial case to work.

Firefox bookmarks and homepage

It would be nice to have precice.org as the homepage in Firefox, together with some common bookmarks.

The VM should also guide people on what they can actually try in it.

Missing deal.II solvers in PATH

The user currently needs to copy the (already built in 2D mode) deal.II adapter/slovers linearelasticity and nonlinearelasticity to the tutorials.

This is because we currently:

• distinguish between 2D and 3D solvers (and tutorial cases) --> related to the tutorials restructuring and deal.II adapter changes
• search for a local executable in the tutorials --> potentially related to the tutorials restructuring

I would wait for the restructuring to be completed before I implement this.