Running ParFlow on Windows using VirtualBox (also updated instructions for installing ParFlow in Ubuntu)

-->

The title of this post may be a little misleading. This is not actually an instruction to run ParFlow on Windows, but a quick and easy way for Windows users to have access to ParFlow on Ubuntu Linux using virtualization. Sun Microsystems’ VirtualBox is a free and open source virtualization package that allows additional operating systems to run inside another operating system as an application.

This post is divided into three parts. The first section will detail the steps for setting up VirtualBox in Windows. The second part provides instructions for installing and configuring Ubuntu Linux on the virtual machine. The third section is an updated set of instructions for building ParFlow on an Ubuntu system, applicable to both native and virtual Ubuntu installations.

I completed this installation using Microsoft Windows XP SP3 (32-bit), VirtualBox 3.1.4, and Ubuntu 9.10 (32-bit). If you are running a 64-bit version of Windows, you can run a 32-bit or 64-bit version of Ubuntu in your VirtualBox. 64-bit Ubuntu will not work unless you are running a 64-bit version of Windows. When in doubt, install the 32-bit version. These instructions detail the 32-bit installation, but I will make note where differences appear for 64-bit. Excluding download time, setting up a virtual Ubuntu machine takes a little more than an hour.

Installing VirtualBox and setting up your virtual machine

1. Download the following:
   • Sun VirtualBox – select the version for Windows hosts

http://www.virtualbox.org/wiki/Downloads

• Ubuntu – for a 64-bit version, Click “Alternative download options” and select “64-bit version” before starting your download. The file is around 700 MB.

http://www.ubuntu.com/getubuntu/download

2. Install VirtualBox. This is a standard Windows installation wizard. On Windows XP, you may see several “Logo Testing” failures, which you may ignore.

3. Start VirtualBox. You will be required to register the software. I did this three weeks ago, and they haven’t sent me any emails to date.

4. Click “New” in the upper left corner to start the wizard. You may name it anything you like. Select “Linux” in the Operating System dropdown, and select “Ubuntu” in the Version dropdown (or select Ubuntu (64-bit) for a 64-bit install)

5. Choose how much memory to allocate to Ubuntu. You may choose up to half of the total memory of your computer. 512 MB is the minimum recommended. I went with 1200 MB

6. Create a Virtual Hard Disk when prompted by the wizard, and check “Boot Hard Disk.”
   • You will be given the choice between dynamically expanding storage or fixed-size storage. The wizard provides a good explanation of each. I picked dynamically expanding.
   • Next, set the size (or maximum size for dynamically expanding) of your virtual hard disk. 10.00 GB will cover you for the operating system, ParFlow and support software, and it will leave room for a small amount of data. I went with 20.00 GB to make sure I have plenty of space for small runs. I would not recommend going under 10.00 GB.

7. After you finish the wizard, create a shared folder. This will allow you to transfer files between your Ubuntu virtual machine and your Windows machine.
   • In Windows Explorer, create a folder that you want to use as your shared folder.
   • In the VirtualBox window, select the virtual machine you just created, click Settings, then click Shared Folders
   • Click the icon to add a folder (looks like a folder with a green ‘plus’ sign), and enter the path (or click other and navigate) to the folder you just created. “Folder name” is not the name you gave it in Windows. It is the name that will identify it in Ubuntu later. I called it “shared_folder.” Don’t make it read only: that would make it pretty useless.
   • Click OK, click OK.

8. You’re almost ready to start installing Ubuntu. If you have ever installed Windows, this is painless in comparison. First, we must mount the Ubuntu iso file. The virtual machine will recognize this as a CD.
   • In the VirtualBox window, click File>Virtual Media Manager.
   • Click the CD/DVD Images tab, then click Add.
   • Find and select the Ubuntu image file you downloaded from ubuntu.com, and click OK.
   • Select your virtual machine again and click settings, then click Storage. Under Storage Tree, click the icon that looks a bit like a CD.
   • Under Attributes, select the Ubuntu image file from the CD/DVD Device dropdown list.
   • While you’re dealing with settings, click Display and check the box to “Enable 3D Acceleration.” This will eventually allow you to work in full screen.

Now you’re ready to configure and install Ubuntu on your virtual machine.

Installing and configuring Ubuntu on a Virtual Machine

1. In the VirtualBox window, select your virtual machine and click Start. This should start installing Ubuntu. Simply follow the on-screen prompts. When you get the part about partitioning, make sure the virtual hard disk you created earlier is selected. If you know what you’re doing, you can set up your partitions manually. If not, select “Erase and use entire disk.” Don’t worry; this won’t touch anything but the virtual hard disk you created earlier, which exists only as a single file on your Windows machine.

2. Installation may take 45 minutes to an hour, depending on how fast your computer is. When it’s done, you will be prompted to restart. Go ahead and restart. When it tells you to remove the CD from the drive, close the window.

3. Back in the VirtualBox window, select your virtual machine, click Settings, click storage. Select the CD icon under Storage Tree, then select “Empty” from the CD/DVD Device dropdown list under Attributes. Click OK.

4. Start the virtual machine again. When it has finished booting into Ubuntu, start setting up Ubuntu to access the shared folder you created in Windows.
   • Go to Devices>Install Guest Additions. Cancel the dialog box that appears (don’t worry if it doesn’t appear).
   • Open a terminal window (Applications>Accessories>Terminal) and enter the following commands:

sudo apt-get install dkms [you will be prompted for your password]

cd /media/cdrom

sudo ./VBoxLinuxAdditions-x86.run

(for a 64-bit installation, enter “sudo ./VBoxLinuxAdditions-amd64.run” instead)

sudo reboot

*If you can't get this to work correctly, try restarting the virtual machine, then try again. If it still won't work, see the comment at the bottom of this post.

• When Ubuntu finishes rebooting, open a terminal window again and create a directory for your Windows/Ubuntu shared folder. I created mine in the home directory and called it “send_to_XP.”

mkdir send_to_XP

• In step 7 of installing VirtualBox above, you named a folder for use in Ubuntu. I called mine “shared_folder.” Let’s see if it works. It should. When you input your directory in Ubuntu in the following command, it is best to use the full absolute path, to avoid putting it in the wrong place or overwriting something important (I tell you this because it happened to me).

sudo mount –t vboxsf shared_folder /home/john/send_to_XP

• If that worked, you now have access to a folder shared between Ubuntu and Windows. Try it out. Stick a file in the folder in Windows. Then open the directory in Ubuntu (Places>Home Folder) and see if the file is in the “send_to_XP” folder (or whatever you decided to call it).

5. You will have to run the above command every time you start Ubuntu in order to use your shared folder. Here’s a way to mount it automatically so you don’t have to run that command every time:
   • Open the “fstab” file in a text editor (vi and gedit are installed by default).

sudo gedit /etc/fstab

• Copy the following line to end of the “fstab” file, changing the directory names to the ones you used and "john" to your own username .

shared_folder /home/john/send_to_XP vboxsf defaults,uid=john,gid=john,fmask=111,dmask=022 0 0

6. You can skip this step and come back to it after you’ve installed ParFlow. It involves up to 2 hours of unattended downloading and updating.

By now, “[Update Manager]” should appear at the bottom of the Ubuntu window. Click it. Click “Check.” You’ll be prompted for your password. When the check finishes, click “Install Updates.” When it is finished, you will probably be prompted to restart. Go ahead and restart.

Installing Parflow in Ubuntu

The instructions in this section are applicable to building ParFlow on both native and virtual installations of Ubuntu. These instructions should be much easier and more effective than those in my previous post about installing ParFlow on Ubuntu.

1. Open a terminal window.

2. You will first need to download and install C, C++ and Fortran compilers and Tcl/Tk. The download list below also includes optional, but recommended text editors. Ubuntu ships with vim-lite, which sucks. At the very least, install the full version of vim. Downloading and installing these is very easy. All you have to do is enter the following commands:

sudo apt-get install gcc

sudo apt-get install g++

sudo apt-get install gdc

sudo apt-get install gfortran

sudo apt-get install tcl-dev

sudo apt-get install tk-dev

Optional

sudo apt-get install vim [highly recommended]

sudo apt-get install jedit [my favorite text editor – allows vertical selection]

3. Now, download software from the internet. OpenMPI is optional if you are using a machine with a single-core processor. Silo is optional if you do not intend to use the VisIt visualization package. VisIt is also optional, but recommended as it is a good visualization package that lends itself well to use with ParFlow.
   • ParFlow

http://inside.mines.edu/~rmaxwell/maxwell_software.shtml

• Hypre – A powerful solver package that greatly enhances the performance of ParFlow

https://computation.llnl.gov/casc/hypre/download/hypre-2.4.0b_reg.html

• Silo

https://wci.llnl.gov/codes/silo/silo-4.7.2/silo-4.7.2.tar.gz

• VisIt

https://wci.llnl.gov/codes/visit/executables.html

Choose a version for Ubuntu 8.04 (which will work for 9.10 also). Be sure to pick the correct 32-bit or 64-bit version.

• OpenMPI – if you intend to utilize a multi-core processor, you will need this in order to do so.

http://www.open-mpi.org/software/ompi/v1.4/downloads/openmpi-1.4.1.tar.bz2

4. Build a directory structure for your ParFlow installation. It really helps to keep this organized, I’ve found, and it’s easy to do. Make a directory in your home directory for ParFlow and its supporting software. I called mine “parflow.” Then place the downloads from step 3 into that directory. If you’re not already working in the terminal window, now you must. I’ll use my directory structure as the example here.
   • Move into the new parflow directory and unpack the downloaded *.tar.gz files. If you’re new to linux command line operations, the [tab] button auto-completes your typing on the command line. I’ll use that in the commands below.

cd [takes you to your home directory]

cd parflow

tar –xvf parflow[tab]

tar –xvf hypre[tab]

tar –xvf silo[tab]

tar –xvf visit[tab]

tar –xvf openmpi[tab]

• Each “tar” command creates a directory with version numbers at the end of the name (except visit). I renamed the parflow, hypre and silo directories to simply “parflow,” “hypre,” and “silo” for simplicity.

5. Set environmental variables. This makes the installation a breeze, when we get to it. You can do this on the command line, but it is better to set them in the .bash_aliases file. Then you only have to do it once.

Depending on your text editor of choice:

vi ~/.bash_aliases

jedit ~/.bash_aliases or

gedit ~/.bash_aliases

Add the following lines, adjusted for your own directory structure, of course.

export CC=gcc

export CXX=g++

export FC=gfortran

export F77=gfortran

export PARFLOW_DIR=/home/john/parflow/parflow

export SILO_DIR=/home/john/parflow/silo

export HYPRE_DIR=/home/john/parflow/hypre

export PATH=$PATH:/home/john/parflow/visit/bin

Now it’s time to start installing. But first, source your bash aliases

source ~/.bash_aliases

6. Install OpenMPI

cd openmpi[tab]

sudo ./configure

sudo make all

sudo make check

sudo make all install

cd ..

7. Install Silo

cd silo

./configure --prefix=$SILO_DIR --disable-silex

make all

make check

make all install

cd ..

8. Install Hypre

cd hypre/src

./configure --prefix=$HYPRE_DIR --with-MPI [if you’re not using MPI, use --without-MPI]

make all

make check

make all install

cd ../..

9. Install ParFlow and PFTools, run the test cases

cd parflow/pfsimulator

./configure --prefix=$PARFLOW_DIR --enable-timing --with-clm --with-silo=$SILO_DIR --with-hypre=$HYPRE_DIR --with-amps=mpi1 [if you’re not using MPI, leave the last flag off]

make install

cd ../pftools

./configure --prefix=$PARFLOW_DIR --with-silo=$SILO_DIR --with-amps=mpi1 [if you’re not using MPI, leave the last flag off]

make install

cd ../test

sudo ldconfig

make check