VirtualMachine

Note: As of version 0.3.4, this page is obsolete. Check out the file README_VirtualMachine in the root directory of WavePacket for the new and simpler workflow!

For documentation on the buildsystems prior to v7, see here (and descend recursively if you need really older build systems).

In simplistic terms, a virtual machine is a program that emulates a computer. On this virtual machine, you can then install another operating system (the guest). This document describes how to use a virtual machine to simplify the setup of a Wavepacket system. Everything needed to compile Wavepacket (or compile and run your programs that use the library) is done in the Linux guest system, then you can share data for easier manipulation with your "real" system (the host).

Note that the build systems are usually linked to certain versions of Wavepacket. Compilation with the appropriate build image should always work, no matter what. If you experience problems while following the instructions here, drop a note on the mailing list or per private mail, so that the issue is fixed (and your problem solved).

• Minimal instructions
• Optional steps
• Trouble shooting / Problems
• Details of the system
• Where to go from here

Minimal instructions

1. Download and install the VirtualBox emulation software from http://www.virtualbox.org
2. Download the image for the already prepared operating system from https://sourceforge.net/projects/cpp.wavepacket.p/files/Compilation%20images/. You need at least version 7 of the build system for the instructions on this page.
3. Start VirtualBox, select File / Import Appliance, and select the downloaded .ova image.
4. Start the created virtual machine

After booting the guest, you should see a command-line asking you to enter a username. We will stick with the command line for the rest of the minimal instructions. The login data is

User: wavepacket
Password: wavepacket1

1. We need to set the Debian mirror to download packages from. The default is the German mirror which will work, but may be slow outside of Germany. If you do not care, you might skip this step.
   * Enter "sudo nano /etc/apt/sources.list"
   * In the URLs with the form "ftp.de.*", replace "de" by the country code where you are in (e.g., "ftp.dk.debian.org" for Danish).
   * Save the changes ("Ctrl-x", "y", "Return")
2. Start the preparation of everything by typing "bash prepareAll.sh".
3. When asked for a password, enter the user password. When asked for any decision, whatever you pick should be fine.

The script "prepareAll.sh" now installs all required programs for compilations. It upgrades the system and installs all required packages, downloads and installs CMake, downloads and compiles the tensor library, on which Wavepacket relies, and finally downloads the WavePacket git repository. Altogether, you should expect around 400 MB of downloaded data and a few minutes of waiting.

1. Type "source .bashrc". The background is that prepareAll.sh added the downloaded CMake to the program path, but this only becomes valid after you open a new shell or reload this initialization file.
2. Enter the Wavepacket directory "cd src/wavepacket"
3. Check which version (or branch) you want to compile
   • "git tag" lists all available tags (one for each release)
   • "git branch -r" lists all available development branches
   • Pick a tag or branch and make it the current one "git checkout <tag_or_branch_name>"
4. Follow the normal instructions in the readme for compilation
   • "less README" lets you browse the readme; q exits the viewer
     • Note: for the installation, you get admin privileges with "sudo make install" and entering the password again.
   • "less README.Python" explains the setup process for Python

Optional steps

1. Installing the VirtualBox add-ons. These are required for sharing folders between guest and host or integrating the GUI seamlessly.
   • When you have started the guest system, go to the menu and select "Devices / Insert Guest Additions CD Image"
   • mount it "mount /media/cdrom"
   • run the installation script "sudo bash /media/cdrom/VBoxLinuxAdditions.run"
   • After typing your password, everything should be done automatically
   • Restart the system for the add-ons to become active
     • "sudo halt"
     • Turn off the VM (if it does not stop on its own)
     • start it again
2. Sharing a folder between guest and host system. This allows you to exchange data between the two.
   • Create a directory on your host that will hold the shared content
   • Tell VirtualBox about this shared folder
     • In the VirtualBox GUI, right-click on the virtual machine, select "Settings"
     • Select "Shared Folders", add the created directory as shared folder with some name, say "my_share"
     • the folder should be set to "permanent"
   • Tell the guest system about the shared folder
     • Create a new directory that later hosts the shared folder, say "sudo mkdir /mnt/shared".
     • You should now be able to mount the shared folder
       • "sudo mount -t vboxsf my_share /mnt/shared" should work without error
       • "ls /mnt/shared" should show you changes if you add/remove files from within the host system
       • unmount for now again with "sudo umount /mnt/shared"
     • Tell the operating system to mount the shared folder.
       • Type "sudo nano /etc/fstab"
       • Add the line "my_share /mnt/shared vboxsf uid=wavepacket 0 0" (using the example names)
       • Save the file with "Ctrl-X" and confirm with "Y" and "Return"
   • Mount the shared folder (automatically done on later reboots) "mount -a"
   • Now you can exchange files via the directory "/mnt/shared" in the guest system and your created directory in the host system.
3. Changing the keyboard layout
   • Run "sudo dpkg-reconfigure keyboard-configuration"
   • Pick the keyboard model and configuration that you want
   • Restart the service: "sudo service keyboard-setup restart"
4. Changing the password
   • Type "passwd" and follow the instructions
5. Power off the system
   • Close the VM window and select the option "Send shutdown signal".
   • You could also type "sudo halt", then turn the VM off (the "Power off" option when you close the VM).

Trouble shooting / Problems

• If your mouse is captured by the VM, pressing the system key (by default: Right Ctrl key) should release it.
• If you manage to screw up the boot process (e.g., mistype something when setting up the shared folder below), there is no simple way to recover. Reason: I locked the root (/admin) account, but if there are problems with the boot process, the system wants to boot into the root account. Such a problem can be fixed, but that requires some deeper Linux/Unix skills.
• I observed occasional black screens when rebooting. Probably something broken with the VM console display (?). If the screen is black when there should be a login screen, just type username and password blindly. After a successful login eveything is refreshed, and you see the console again.

Details of the system

The system installed on the guest is a 64 bit Debian stretch. By default, the virtual machine is set up with 1GB of RAM, one CPU and a 20 GB hard disk (written to a file)

Where to go from here

• If Linux and Command lines are completely new, study a basic tutorial. Chances are you will come across them again anyway in science contexts

  • For example https://ryanstutorials.net/linuxtutorial/
  • Or one of the various books on the subject Linux / Unix / Bash / Command line interface

• You can change the VirtualMachine resources.

  • Select "Machine / Settings" in the VirtualBox menu
  • Switch to the "System" display
  • Now you can assign more memory and CPUs to the virtual machine if you need them. There are also lots of other settings, but they are probably less relevant.

• You can install more packages if you want

  • Update the list of packages "apt update"
  • install new packages
    • Use "apt search <keyword>" to search for packages by keyword</keyword>
    • Use "apt show <packagename>" to get more detailed information</packagename>
    • Use "sudo apt install <packagename>" to install new packages
      (sudo gives you administrator permissions for the subsequent command)</packagename>
  • To get a window manager in the host
    • Install the "icewm" package (minimal window manager) or "kde-full" for a more Windows-like desktop
    • Install the "xinit" package to setup the graphical system
    • Type "startx" to start up the window manager
    • If this does not work, try to reboot "sudo reboot" and login again.
      (This should not be required in principle. Probably a packaging bug, but I did not follow up on this issue)
  • If you want to integrate the GUI into the host system seamlessly, you need to reinstall the VirtualBox guest utilities after you installed the graphical interfaces (I think).