Running the RCMES Virtual Machine

Quick Navigation

I.    Introduction
II.   Prerequisite Software
III.  Install
IV.  Configure VM
V.   Start VM and RCMES
VI.  Testing RCMES
VII. Using VM RCMES for Tutorials

I . Introduction

The following document describes how to use RCMES within a Virtual Machine (VM) - an emulation of a computer system - on your system. The RCMES VM provides the RCMES software installed within a Linux OS, with the appropriate file system and Python libraries and dependencies. Thus, through using the RCMES VM, the user will have the opportunity to interact with RCMES with minimal impact on their local system. This document will guide you (1) towards the prerequisite software component needed to be installed before you can run the RCMES VM; (2) provide details on installing and configuring the RCMES VM to work on your system; (3) discuss how to start the RCMES VM; and  (4) provide a tutorial on using RCMES. Once you have completed all components of this page, refer to the different Tutorials to learn how to use CLI and Configuration Files within the VM.

IMPORTANT: Bullet points denote ACTIONS that you need to take, you should expect to do something at every bullet point.

II. Prerequisite Software

  • Install VirtualBox for your computer operation system.  VirtualBox is a powerful x86 and AMD64/Intel64 virtualization free software product for enterprise as well as home use that supports Windows, Linux, Macintosh, and Solaris host operating systems.

III.  Installing the RCMES VM

Once VirtualBox is downloaded, you can download and install the RCMES VM to use within VirtualBox. Please note that the screenshots provided in this section of the tutorial are from a Virtual Box Macintosh host thus there may be some (slight) discrepancies in VirtualBox the graphical user interface based on your host system.

Step 1: Download the RCMES VM (.ova file)

Once you've installed VirtualBox as explained above, download the .ova image to your local machine so you can access it. This is a large file and will take some time to download. The file should be named as follows: "RCMES_[latest-release-date].ova"

Step 2: Import the VM Image

  • Once downloaded double click the RCMES VM (.ova file), this will prompt you with a screenshot similar to the following (note that the data of the latest ova file may be different).

 

  • Click Import, this will import the RCMES VM into your VirtualBox appliance.

 

Once the import was successful, you will see a screen similar to below. Note that you will be working with the latest version of VM that you just downloaded - if you have downloaded multiple VMs, then make sure the one you want to work with is highlighted before proceeding.

IV. Configure the RCMES VM

Before you start the RCMES VM you are required to set up an area on your virtual machine where files generated while running RCMES in the VM can be stored. This allows you to access files between your virtual machine and your host machine.  This is achieved creating a shared folder between the RCMES VM and your machine.

Step 1: Adding a Shared Folder

  • First select the Settings option (the yellow wheel) on the VirtualBox Manager, then click the Shared Folders tab.

Most likely your folder list will be empty.

  • Add a new shared folder by clicking the icon with a "+" on a folder. The following window will pop up.

  • Navigate to the desired folder and name it RCMES_shared
  • Leave the Read-only option unselected.
  • Confirm that the Auto-Mount option is selected, so that you do not have to manually mount the folder in the VM every time you start it up.

  • Click OK to add the folder.

  • Confirm your shared folder settings, then click OK to close the Settings window.

Please note that installation and configuration are only required the FIRST TIME. Subsequent access does not require you complete though this section again, though you may change settings (e.g. where to store information) as desired.

You are now ready to start the RCMES VM.

V. Starting the RCMES VM

Step 1: Starting the RCMES VM

  • Click on the ocw-vm_latest image on the left hand side of the VirtualBox Manager Interface making sure that you select the VM you want to be working with.
  • Start the RCMES VM by selecting the Start option (the Green Arrow).

Step 2: Log into the RCMES VM

Once the RCMES VM is started you will be prompted to log in. You should do so by using the following credentials

  • username: vagrant
  • password: vagrant

 

You may receive messages at the top of your VM that tell you that you have the Auto Capture Keyboard option and Mouse Pointer Integration turned on. This just means that you can use your keyboard and mouse between the VM and your Host machine automatically without having to change between the two. You can close the notes out by clicking the blue X.

Step 3: Welcome to the RCMES VM Desktop Area

Once you've logged in, you should see the following Desktop area and a similar Desktop layout in the screenshot below.

 

The Desktop area contains multiple folders, the Terminal application, an Update RCMES tool, and other links. The following can be found in each.

RCMES-Code contains the RCMES application, CLI Application, a data folder, and configuration files used in the tutorials.

CLI_result, CF_result, and statistical_downscaling folders are where your results from your tutorial can be found.

RCMES-shared is the folder you shared during the set-up of the VM. This is the connection between your host machine and your virtual machine.

RCMES_website is a link that will launch the RCMES website in Firefox.

Link to CORDEX-Africa_example.yaml will open the CORDEX Africa example configuration file that can also be found in ~/RCMES/configuration_files.

Link to NARCCAP_example.yaml will open the NARCCAP example configuration file that can also be found in ~/RCMES/configuration_files.

You can also use the icons on the left side of the VM to navigate to different functions. The VM is essentially a machine that will run RCMES with all of the aspects ready to go. The Dash Home icon (white circle) brings you to recently used Apps as well as gives you an option to search for an App. The Home Folder icon (orange folder) is similar to Finder or Windows Explorer and allows you to navigate directories, files, etc. 

 

​

VI. Testing RCMES

Step 1: Finding the RCMES Test Example

The remainder of this document explains how to run an example provided as part of the RCMES VM.

  • Open Terminal. 
  • Type the following command:
cd RCMES
  • Press Enter.
  • You will now see that you reside within the RCMES directory. You can list the files within this directory by typing the following command:
ls -l
  • Press Enter.

 

Step 2: Running a test example using RCMES

Now that your VM is installed and configured, we can run a test example to confirm that everything is installed properly.

  • Move to the test folder within Terminal.
cd RCMES/test

  • Type in the following command to run a test example.

python test.py

 

The results will be saved to your ~/RCMES/test folder. You can click the Folder icon on the left of the VM to enter the Home Folder and Navigate to the RCMES/test folder. You should see the cru_31_tmax_knmi_africa_bias_full.png. Double click it to view the result.

 

Congratulations, your VM is set up and ready to be used for RCMES!
 

Step 3: Moving your results to your shared folder

You may have noticed that after running the test example, your results were not in your shared folder that you set up before starting the VM. If you want to access the results figure from your host machine, you will need to copy the result from the location within the VM into the shared folder you set up earlier when you configured the VM.

  • Right click the cru_31_tmax_knmi_africa_bias_full.png icon in the Home Folder.
  • Select Copy

Now you will navigate to the shared folder that you set up when you configured the VM. The RCMES-shared folder is located on the Desktop. 

  • From your Desktop area, double click on the RCMES-shared folder to open it.
  • Right click on your shared folder and Select Paste to move your result into the shared folder.

You should now be able to access the result from your host machine. 

VII. Using the VM for RCMES Tutorials

Now that the VM is set up and running correctly, you can refer to the Tutorials pages for future guidance using the CLI and Configuration Files in RCMES. The tutorials will ask you to download data needed to complete the tutorials. You may need to follow these steps to ensure the data is located properly within the VM.

Step 1: Save the downloaded data to your host machine in your RCMES_shared folder.

  • When you are required to download data for RCMES, unzip the tarball and copy and save it to the folder named RCMES-shared within your host machine.

Step 2: Copy the data from the RCMES-shared folder located on the Desktop

  • Open you RCMES-shared folder located on the Desktop of the VM.
  • Right click the folder containing the current tutorial data, and select Copy. 
  • Navigate to the RCMES/data folder (Home - RCMES - Data)
  • Right click and Paste the folder. 

To power off the machine, click VirtualBox VM - Quit VirtualBox VM - Send the shutdown signal which has the same effect of pressing the power button on a real computer. Power off the machine is equivilent to pulling the power cord on a real computer without shutting it down properly and is not recommended. The system will have to reboot completely when restarted. 

If you go through multiple tutorials and download more data, save the data as indicated in the RCMES-shared folder on your host machine and it should mount automatically to the RCMES-shared folder located on the Desktop of your VM.

Back to Top