The darwinView User's Guide Marissa Weichman Chris Hill Background Darwin project is exploring marine biogeochemistry by populating oceanic configurations of the M.I.T General Circulation Model (MITgcm) with "virtual" biologeochemical species that can interact and evolve. Different species are characterized by their combinations of different physiology ranges, over which a species can flourish. For example, some species may be very sensitive to ocean temperature or nutrient concentrations while other species may thrive over a wide temperature range but require high levels of solar radiation to flourish. By seeding an ocean circulation model with ensembles of different species, with probability distributions guided by biological measurement, we can use this approach to develop an understanding of the actual and potential biodiversity in the marine ecosystem. The darwinView project At a practical level the modeling in Darwin yields three-dimensional, time evolving maps of species distributions that are studied to help us understand the marine ecosystem. The distributions are embedded in three-dimensional, time evolving maps of nutrient, and physical field distributions. The result is a high-dimensional "space" of output which we wish to explore and from which we want to extract understanding. The goal of darwinView is to develop some quick-look, interactive, visualization tools that can allow researchers to rapidly explore Darwin project outputs from MITgcm. Detailed studies of simulation outputs employ analytical packages like Matlab and Ferret. The idea of a quick look tool is not to try and replicate the functionality of these systems, but to make a tool for visually quickly scanning outputs to identify interesting behaviors. What is darwinView 1 - a program to display multiple panels of Darwin project outputs from MITgcm at once. 2 - allows moving through data in space (up-down, east-west, north-south depending on view) and time over a many fields at once. 3 - movement through data can be manual or automatic (scripted or autoplay). 4 - can display to a single screen or to a walled display. 5 - displayed fields are annotated with scale, coordinates, key etc. 6 - some limited controls on display are available. o user-set color scale o log scale o global scale over all fields o local scale for each species, depth and time 7 - can read data from both binary (big or little endian) and NetCDF files How to Use darwinView * Before You Compile the Program: - Make sure you have all the components necessary to run the program: o darwin.bash - bash script that handles data files o darwin.c - the main OpenGL program o netcdf.c - the program that handles NetCDF files o jet.h - a table of color values - Make sure the following are installed on your computer: o Bash Unix shell o gcc C compiler o C programming libraries o OpenGL libraries o NetCDF libraries, if you intend to read from NetCDF files - Make sure your data is organized correctly: o Binary data should be organized in a directory whose only contents are subdirectories representing different time steps. Each subdirectory should contain one binary file for each variable (species concentration, compound concentration or otherwise). Each binary file should contain data for all three dimensions (x, y and z) for its timestep. In addition, the user must prepare a file containing a list of the variables that will be displayed. The variable names should be on one line, separated by spaces. The user will be prompted for the name of this file. o NetCDF files should all be placed in one directory. Make sure all the tiles for the desired timesteps are present. In addition, the user must prepare three files: one containing a list of variables that will be displayed, one containing a list of tiles that make up each plot, and one containing a list of the desired time steps. In each file, the variable names should be on one line, separated by spaces. The user will be prompted for the names of these three files. Finally, the program handles NetCDF files by converting them to binary. Therefore, a directory must be created for the program to write to. The user will be prompted for the name of this directory. o The darwinView program has the option of scaling the z-axis, so depth levels aren't equally spaced. If you plan to use this feature, a file must be prepared containing a list of the depths of each layer. The list should begin with the layer closest to the surface and progress down the water column, one depth per line. The number of lines should be equal to the z-dimension (number of depth layers). The user will be prompted for the name of this file when the scaled z-axis feature is enabled. * Compiling the Program: - The darwinView program is called through a bash script which prompts for information the program needs to run. Type "bash darwin.bash" to run the script. o First, the script prompts for the format of the data. If you are using binary files, type "binary" then type enter. If you are using NetCDF files, type "netcdf", then enter. o The script then asks if the user would like to use the default settings. If you have run the program before and none of your settings have changed, type "y" for yes, then hit enter. If you have not run the program before, or would like to change your settings, type "n" for no, then hit enter. o If you typed "n", the program should begin running, and you can skip to the section "running the program". If you typed "y", it will prompt for more information. o Next, the program asks for the dimensions of the data, meaning the x, y and z values of the data. These are entered in the format "x y z". For example, a set of data might cover 360 longitude steps, 160 latitude steps and 20 depth steps. The user would therefore enter "360 160 20". o Next, the user is prompted for the dimensions of the data sets. darwinView is designed to graph several different sets of data simultaneously. For example, if a user were graphing concentrations of four species of phytoplankton, and wanted them arranged in a square, he would enter "2x2". For a horizontal line, he would enter "4x1", and for a vertical line he would enter "1x4". o If you are using the program to read from binary files, you are then prompted for the directory containing the data to be read from. This directory should contain a subdirectory for each timestep, as described in the section "Before You Compile the Program." Finally, you are prompted for the name of the file containing the list of variable names as described in the section "Before You Compile the Program." The program should now begin running, and you can skip to the section "Running the Program." (Note: all of the input asked for up until this point is saved in the file .darwinview/binconfig. If your settings have not changed by the next time you run the program, you can simply select "use default settings" to skip retyping the information.) o If you are using the program to read from NetCDF files, you are then prompted for the directory containing the data to be read from. This directory should contain all the tiles for the necessary timesteps, as described in the section "Before You Compile the Program." o Next, you are prompted for the directory to write to. This directory should be empty. o Finally, you are prompted for the names of the three files: one containing a list of desired variable names, one containing a list of tile names, and one containing a list of time steps (as described in the section "Before You Compile the Program). The program should now begin running. (Note: all of the input asked for up until this point is saved in the files .darwinview/netcdf and .darwinview/ncconfig. If your settings have not changed by the next time you run the program, you can simply select "use default settings" to skip retyping the information.) * Running the Program - When the program window first comes up, you should see the x-y plane of each data set. The default color scale is set to local. At the top of each graph, the name of the file being read from, the depth level being viewed and the time step being viewed are labeled. -The right mouse button brings up a menu with the following options: - Local color scale - switch to the local color scale, where the maximum and minimum values are specific for each variable, time and level. Default when the program begins running. - Global color scale - switch to the global color scale, where the maximum and minimum are calculated based on the entire data set (all variables, times and levels). - User-set color scale - switch to the user-set color scale, where the user is prompted for the maximum and minimum. All variables are then scaled according to these values. - Log scale - toggles the log scale on/off. The log scale can be used in conjunction with any of the color scale options listed above. - Allow negatives - toggles the allowance of negatives on/off. When the program begins running, off is the default. In off mode, all negative values are set to the lowest positive value. - Switch endian - toggles between big and little endian. Default is big endian. -There are also a number of key commands: - left arrow key - move all plots forward one time step. If the animate feature is set, pushing this key cycles forwards through the time steps. - right arrow key - move all plots back one time step. If the animate feature is set, pushing this key cycles backwards through the time steps. - down arrow key - in the xy view, move down one depth level. In the xz view, move down one North-South slice. In the yz slice, move right one East-West slice. If the animate feature is set, pushing this key cycles downwards through the depth levels in the xy view, down the North-South slices in the xz view, and right across the East-West slices in the yz view. - up arrow key - in the xy view, move up one depth level. In the xz view, move up one North-South slice. In the yz view, move left one East-West slice. If the animate feature is set, pushing this key cycles upwards through the depth levels in the xy view, up the North- South slices in the xz view, and left across the East-West slices in the yz view. - r - reset the view (return to the xy plane at the first time and level) - a - toggle the animate feature on/off - x - toggle between xy and xz view, which plots how a certain North-South slice changes over depth. - y - toggle between xy and yz view, which plots how a certain East-West slice changes over depth. - z - toggles scaling of the z-axis when the program is in the xz or yz view. The user will be prompted for the name of the file containing containing the depth information the first time "z" is pressed (as described in the section "Before you Compile the Program"). - q - quit the program