Regional Climate Mode Evaluation SystemRCMES
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.
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.
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"
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.
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.
Most likely your folder list will be empty.
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.
Once the RCMES VM is started you will be prompted to log in. You should do so by using the following credentials
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.
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.
The remainder of this document explains how to run an example provided as part of the RCMES VM.
cd RCMES
ls -l
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.
cd RCMES/test
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!
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.
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.
You should now be able to access the result from your host machine.
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.
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.