Step 1 — Determine which type of computer you have

This matters particularly for Mac users.

• Mac with an M1, M2, M3 or M4 processor: your computer uses Apple Silicon / ARM64.
• Older Mac with an Intel processor: use the Intel version.
• Windows computer with an Intel or AMD processor: use the normal Windows hosts version.
• Linux computer with an Intel or AMD processor: use the appropriate Linux version.

Step 2 — Download VirtualBox

1. Go to the official VirtualBox download page.
2. Download the latest version of VirtualBox for your operating system.
3. Choose the download corresponding to your computer, for example Windows hosts, macOS / Intel hosts, macOS / Apple Silicon hosts, or the appropriate Linux package.

Step 3 — Install VirtualBox

1. Open the installer that you just downloaded.
2. Follow the installation wizard.
3. Unless you have a specific reason to do otherwise, accept the default options.
4. If Windows or macOS asks whether VirtualBox may make changes to your computer, approve the request.

Step 4 — Install the VirtualBox Extension Pack

For consistency with the course setup, also install the Oracle VirtualBox Extension Pack.

1. On the same VirtualBox download page, find the VirtualBox Extension Pack.
2. Download the Extension Pack corresponding to the latest VirtualBox version that you just installed.
3. Open the downloaded .vbox-extpack file.
4. VirtualBox will ask whether you want to install it. Choose Install.
5. Accept the licence when requested.

VirtualBox is now installed, but it does not yet contain our Linux computer. We therefore have to download Quantum Mobile.

1. Go to the official Quantum Mobile releases page.
2. Choose the latest Quantum Mobile release.
3. Open the release page and download the Desktop/VirtualBox image corresponding to your computer:

• Apple M1/M2/M3/M4: download ARM64.
• Windows with Intel or AMD processor: download AMD64.
• Intel Mac: download AMD64.
• Intel/AMD Linux computer: download AMD64.

The downloaded file is the virtual computer itself. It is normally an .ova file and is several gigabytes large, so the download can take some time.

1. Start VirtualBox.
2. Choose File → Import Appliance.
3. Browse to the Quantum Mobile .ova file that you downloaded.
4. Select that file and continue.
5. You will see a summary of the virtual machine settings. For the moment, leave the normal settings unchanged.
6. Click Finish or Import.

VirtualBox now extracts and installs the virtual machine. When the import is complete, Quantum Mobile will appear in the list of virtual machines in the left-hand side of the VirtualBox window.

Before starting the virtual machine for the first time, make two useful display checks.

1. In VirtualBox, click once on Quantum Mobile so that it is selected.
2. Do not start it yet.
3. Choose Settings → Display.
4. Check that 3D Acceleration is disabled. This should normally already be the default.

If text and icons are likely to be very small

This is especially common on high-resolution laptop screens and Retina displays.

1. Still under Settings → Display, find Scale Factor.
2. Start with 150%.
3. Click OK.

You can change this to 175% or 200% later if necessary.

1. In VirtualBox, select Quantum Mobile.
2. Click Start, or right-click Quantum Mobile and choose Start → Normal Start.
3. A new window will appear.
4. Wait until the Ubuntu desktop is visible. The first start can take a little longer than later starts.

You now have a Linux computer running inside your normal computer.

If you are asked for login credentials, use:

• username: max
• password: moritz

Quantum Mobile normally already contains cif2cell. We nevertheless check that it is available. If it is not present, it can easily be installed.

Open a terminal

1. Inside the Quantum Mobile window, find the Terminal application. Its icon is usually a dark/black window containing a prompt symbol such as > or _.
2. Click the Terminal icon.
3. A terminal window opens.
4. Click once inside the terminal window. This is important: your keyboard input must be directed to the terminal.

Now type the following command in the terminal window, and press Enter:

cif2cell -h

If cif2cell displays its help information, it is already installed and you are finished with this step.

If the terminal tells you that cif2cell cannot be found, click inside the terminal again and type:

pip install cif2cell

Press Enter and wait until the installation has completed. This installation needs to be done only once.

Quantum Mobile is deliberately isolated from your normal computer. This is good for safety, but we need a convenient way to move calculation files between the two systems.

We therefore create a shared folder. Files placed in this folder on your normal computer will also be visible inside Quantum Mobile, and vice versa.

Step 1 — Create the folder on your normal computer

1. Shut Quantum Mobile down completely if it is currently running.
2. On your normal Windows, macOS or Linux computer, create a new folder.
3. For example, call it shared.

It is best to use a simple folder name without spaces, accented characters or unusual symbols.

Put one small text file in this folder. We will use it to test the connection.

Step 2 — Tell VirtualBox to share this folder

1. Open VirtualBox, but do not start Quantum Mobile.
2. Select Quantum Mobile.
3. Choose Settings → Shared Folders.
4. Click the small Add Shared Folder button, usually represented by a folder with a + symbol.
5. For Folder Path, browse to the shared folder that you created on your normal computer.
6. For Folder Name, enter exactly:

host

Use lower-case letters.

7. Tick Auto-mount.
8. Leave the Mount Point field empty.
9. Click OK.
10. Click OK again to close the Quantum Mobile settings.

1. Start Quantum Mobile.
2. Open the Terminal.
3. Click inside the terminal window before typing.
4. Type the following command and press Enter:

cd /media/sf_host

Now type:

ls

You should see the name of the test file that you placed in the shared folder on your normal computer.

Now create a second test file from inside Quantum Mobile:

touch testfile.txt
ls

Look at the shared folder on your normal computer. A new empty file named testfile.txt should now be present there.

If this works, the shared folder has been configured correctly.

/media/sf_host

You will normally perform calculations somewhere inside your Quantum Mobile home directory rather than directly in the shared folder.

For example, create a calculation directory by typing these commands in the Terminal:

cd
mkdir -p work/mycalculation
cd work/mycalculation
pwd

The final command, pwd, prints the directory in which you are currently working. It should end in:

/home/max/work/mycalculation

Copy a file from your normal computer into the calculation directory

For example:

cp /media/sf_host/testfile.txt ./
ls

The file is now present in your calculation directory.

Copy a file back to your normal computer

Create a test output file:

touch myoutput.txt

Copy it to the shared folder:

cp myoutput.txt /media/sf_host/

If you now look inside the shared folder on your normal computer, you should see myoutput.txt.

If the text and icons inside Quantum Mobile are too small, first adjust VirtualBox rather than changing Ubuntu’s own screen resolution.

A. Adjust the VirtualBox scale factor

1. Shut Quantum Mobile down completely.
2. In VirtualBox, select Quantum Mobile.
3. Open Settings → Display.
4. Set Scale Factor to 150%.
5. Click OK.
6. Start Quantum Mobile again.

On a Retina or other high-resolution display, 150% is usually a good first choice. If everything is still too small, try 175% or 200%.

B. Enable automatic resizing

With Quantum Mobile running:

1. In the menu of the VirtualBox VM window, choose View → Auto-resize Guest Display.
2. Make sure that this option is enabled.
3. Drag the edge or corner of the Quantum Mobile window to make it larger or smaller.

Ubuntu should automatically adapt its desktop resolution to the size of the VirtualBox window.

C. Use full-screen mode if desired

Choose View → Full-screen Mode.

The keyboard shortcut is:

Host key + F

On a Mac, the default VirtualBox Host key is the left Command (⌘) key, so with the default settings the shortcut is:

left ⌘ + F

What is the Host key?

When you click inside the Quantum Mobile window, VirtualBox sends your keyboard input to the virtual computer. VirtualBox therefore reserves one special keyboard key, called the Host key.

The Host key has two main functions:

• Pressing the Host key releases keyboard and mouse control from the virtual machine back to your normal computer.
• The Host key is combined with other keys for VirtualBox commands, for example Host key + F for full-screen mode.

The currently configured Host key is normally shown in the status bar at the bottom of the VirtualBox VM window.

Typical defaults are:

• macOS: left Command (⌘)
• Windows/Linux: right Ctrl

Why can Alt cause problems?

If Alt has accidentally or deliberately been configured as the Host key, VirtualBox treats that key as its special control key. This can interfere with familiar combinations such as Alt+Tab.

In that case it is convenient to choose another key as the Host key.

Change the Host key

1. Open the main VirtualBox window.
2. Choose File → Preferences.
3. Choose Input.
4. If different groups of shortcuts are displayed, choose Virtual Machine.
5. Find Host Key Combination.
6. Click in the field to the right of Host Key Combination.
7. Press the keyboard key that you want to use as the new Host key.
8. Click OK.

Quantum Mobile may initially use a US English keyboard layout. If characters appear that do not correspond to the keys that you press, change the keyboard layout inside Ubuntu.

1. Inside Quantum Mobile, open Settings.
2. Go to Keyboard.
3. Find Input Sources.
4. Choose Add Input Source.
5. Select the language and keyboard layout that corresponds to your actual keyboard.

After adding it, select that keyboard layout from the input-language control in Ubuntu. If the change does not appear to take effect immediately, restart Quantum Mobile.

When you are finished, there are two different ways to leave the virtual machine.

Preferred method: shut Ubuntu down

Inside Quantum Mobile, use Ubuntu’s normal Shut Down / Power Off command. Wait until the Quantum Mobile window closes.

This is equivalent to shutting down a normal computer and is the safest method before changing VirtualBox settings.

Saved state

VirtualBox can also save the exact state of the virtual machine so that you can resume it later. This is similar to hibernation.

Virtualization error on an Intel/AMD Windows computer

If VirtualBox reports that hardware virtualization such as VT-x or AMD-V is disabled, virtualization may have to be enabled in the computer’s BIOS or UEFI settings.

The exact procedure depends on the manufacturer of the computer. Search for instructions for your exact computer model and the exact VirtualBox error message.

Nothing seems to happen when you start the VM

• Check that you downloaded the correct Quantum Mobile architecture.
• On an Apple M1/M2/M3/M4 Mac, make sure that you downloaded the ARM64 image.
• Check that you installed the latest available version of VirtualBox.
• Completely shut down any previous saved instance of the VM and try again.

The display does not resize automatically

First make sure that View → Auto-resize Guest Display is enabled. Quantum Mobile contains the VirtualBox Guest Additions needed for this functionality, but occasionally a VirtualBox/Guest Additions mismatch can cause display problems.

If resizing still does not work, restart both Quantum Mobile and VirtualBox before changing Ubuntu’s own resolution settings.

A shared folder does not appear

Check the following:

• the shared-folder name in VirtualBox is exactly host;
• Auto-mount is enabled;
• the mount-point field was left empty;
• Quantum Mobile was restarted after creating the shared folder;
• you are looking inside Quantum Mobile at /media/sf_host.
• 
  

Your installation is ready for the course if all of the following work:

• VirtualBox starts normally.
• Quantum Mobile starts and displays the Ubuntu desktop.
• You can open a Terminal inside Quantum Mobile.
• cif2cell -h works.
• Your shared folder is visible as /media/sf_host.
• You can copy a test file in both directions between Quantum Mobile and your normal computer.
• The Quantum Mobile display is large enough to read comfortably.
• You know which key is configured as your VirtualBox Host key.

Once these checks succeed, the virtual machine is ready to use for the Quantum ESPRESSO exercises in the course.