UPLAY

Basic Information

Name of Program

uplay

Version-Date

April 2018

Description-Date

April 2018

Catchwords

numerical simulation
hydrodynamic
visualization
learning program

Short Description of Functionality

UPLAY is a GUI around UNTRIM2 and NCPLOT. With UPLAY the user is able to change grid depths graphically, to let compute the hydrodynamical effect of that grid depth change and to look at the results.

The change of grid depths will be done within the GUI. There are a (small) number of color classes each representing one depth value. Using UPLAY in standard manner there are 5 different color classes: "blue" representing 10 m below sea surface, "light blue" (-5m), "green" (-2m), "orange" (0m) and "red" representing 2 m above sea surface. The user activates one color class and clicks on grid elements to change the depth of that element to the color representing value.

To compute the hydrodynamic effect UPLAY does the following in the background after the user started a simulation by clicking the right button:

Writing current grid files (format utrsub_grid.dat and pltsub_grid.upi)
Provide input files for UNTRIM2 and execute an UNTRIM2 simulation
Provide input files for NCPLOT and create images containing the computational results (current velocity and water level) for one specific moment in time

The vector gaphics created by NCPLOT will be converted by UPLAY to the pixel format BMP and presented to the user.

Input-Files

UPLAY is started by default without any input files. In this case UPLAY gets his input files from this directory: $PROGHOME/shellscripts/uplay/sandbox/. However, the user can prepare his own folder with input files if he does not want to use the "sandbox model". In this case the user has to provide the following files in his own folder and has to hand over the name of the folder by using the option -userdir <name_userdir>:

input files for UPLAY:
- uplay.dat: input steering file for UPLAY. It controls in particular the layout of UPLAY
- grid files (format utrsub_grid.dat and pltsub_grid.upi): Position of grid edges and depth of subgrid edges and elements. Please note that in the current version of UPLAY every grid edge and element consists of only one subgrid edge and element.
input files for UNTRIM2:
- untrim2009.dat: input steering file for UNTRIM2. A coupling together with the K-Model or with Sedimorph or with the settling velocity package SV is not supported by UPLAY.
- utromp2009.dat: input steering file of the hydrodynamic package UTROMP_2009. The description of initial and boundary values has to be simple: boundary input files are not supported as well as initial files.
- eqs.dat: input steering file of the density package EQS
- vertical.dat: input steering file describing the vertical resolution
- run_untrim2009_user.sh: UNIX-shellscript to launch an UNTRIM2 simulation run
input files to create images of the computational results:
- nc2table.dat: input steering file for NC2TABLE. NC2TABLE has to write the computational results to an ASCII file to compute the actual range of values.
- run_nc2table_user.sh: UNIX-shellscript to launch an NC2TABLE run
- ncplot_velo.dat: input steering file for NCPLOT to create an image of the current velocities
- run_ncplot_velo_user.sh: UNIX-shellscript to launch an NCPLOT run to create an image of the current velocities at the end of the simulation. In this shellscript the conversion from vector to bitmap image is included. Note that this conversion has to be adjusted to the location and size of the printing.
- ncplot_wlev.dat: input steering file for NCPLOT to create an image of the waterlevels
- run_ncplot_wlev_user.sh: UNIX-shellscript to launch an NCPLOT run to create an image of the waterlevels at the end of the simulation. In this shellscript the conversion from vector to bitmap image is included. Note that this conversion has to be adjusted to the location and size of the printing.
- newcplot_wl.dat: input steering file for NEWCPLOT to create an image of the temporal development of the waterlevels. This image will not be shown by UPLAY, but can be useful to check whether the computaional results are a time independent solution.
- run_newcplot_wl_user.sh: UNIX-shellscript to launch a NEWCPLOT run to create an image of the temporal development of the waterlevels.

Output-Files

as in UNTRIM2 and NCPLOT

Methodology

For each model run, a subfolder is created in the working directory. In the subfolder of a model simulation all result files of UNTRIM2 and NCPLOT are kept. They are thus still available after generating and presenting with UPLAY. The naming for the subfolders is composed of a letter and 4 digits: At the start UPLAY searches for a letter that has not yet been used. Thus, in a folder simulations of up to 26 UPLAY sessions can be kept. Every simulation within a UPLAY session increases the four-digit counter by one. This allows up to 9999 simulations to be performed within a UPLAY session.

The program UPLAY can be called without a control file and without transfer parameters. In this case, a prepared "sandbox model" (a 2.5 km long and 500 m wide test channel with rectangular elements with a resolution of 500 m) is used. This is a 2D model for calculating hydrodynamics without the influence of density. Salt, heat, suspended particles and tracers are not included in the model. At the upstream edge, the inflow is controlled via a FLOW boundary with a constant value of 2000 m3 s-1. At the downstream edge, a water level boundary is implemented with constant value of +1 m. The simulation period is 1.5 hours with a time step of 90 seconds. The aim of the simulation is to calculate the resulting stationary solution. Therefore, the implicitness factor theta of UNTRIM2 is equal to 1. Various tests have shown that the chosen time period is long enough to have a stationary solution at the end of the period. NCPLOT generates images of the flow and the waterlevels for the last moment of time. These images are read in and displayed by UPLAY.

Transfer parameters

-h

UPLAY shows a help text instead of starting the program in a normal manner.

-userdir <name_userdir>

In standard case UPLAY gets his input files from this directory: $PROGHOME/shellscripts/uplay/sandbox/. However, the user can prepare his own folder with input files if he does not want to use the "sandbox model". In this case the user has to provide the input files in his own folder and has to hand over the name of the folder by using the option -userdir <name_userdir>

Note that in this case the user is responsible that the input files describe the right time index to create images. The "sandbox model" uses the 61st time index in den CF-netCDF result files. The same applies to the names of the result files. For this purpose, the placeholder <RUN> may be used in the input files. This placeholder is replaced by UPLAY with the currently valid run name (equal to the folder name).

If the user wants to use his own grid, then the grid may contain only one subelement per grid element and only one subedge per grid edge. It is also important that the depths of the grid elements and the depths of the predefined color classes match. There must not be a grid element with a depth that is not covered by the color classes. UPLAY treats depth values as equal if the difference is less than 1 mm.

Most likely the UNIX-shellscripts has to be adjusted due to the circumstance that the conversion of the vector graphics to a bitmap image the program needs to know the correct cutout values.

-adjusted_velocity_color_palette <yes no adjusted>

Adjust the color palette to the current range of velocity values? If the answer is "yes" or "adjusted", the adjustment takes place. If "no", UPLAY uses a standard range of values. Default ist "no".

-adjusted_waterlevel_color_palette <yes no adjusted>

Adjust the color palette to the current range of waterlevel values? If the answer is "yes" or "adjusted", the adjustment takes place. If "no", UPLAY uses a standard range of values. Default ist "adjusted".

-untrim2009_exe <name_und_pfad_zum_untrim2009_executable>

Executable file for program UNTRIM2. Without using this transfer parameter UPLAY uses a standard executable from within $PROGHOME.

-nc2table_exe <name_und_pfad_zum_nc2table_executable>

Executable file for program NC2TABLE. Without using this transfer parameter UPLAY uses a standard executable from within $PROGHOME.

-ncplot_exe <name_und_pfad_zum_ncplot_executable>

Executable file for program NCPLOT. Without using this transfer parameter UPLAY uses a standard executable from within $PROGHOME.

-newcplot_exe <name_und_pfad_zum_newcplot_executable>

Executable file for program NEWCPLOT. Without using this transfer parameter UPLAY uses a standard executable from within $PROGHOME.

Hints for programmers

UPLAY consists of three parts: First a Fortran-Program, which works as a front end to show the grid depths, to let the user change the grid depths an to show the images of the computational results. Second a collection of UNIX-shellscripts as a back end to control simulation an creation of images. The third part is a UNIX-shellscript as a starting program. This starting script will fullfill all the necessary conditions for a successful use of the front end.

The communication between front and back end is done through data files and UNIX environment variables.

The Fortran Program uses the following PROGHOME software packages:

h_grid for in- and output of grid files
dic-io to read the UPLAY steering file
base-library for basic functions (e.g. to read windows bitmap files (BMP))

In addition, the Fortran program absolutely needs the GKS (graphical kernel system) installation for basic drawing functions and a netCDF installation.

Limitations

A coupling of UNTRIM2 together with the K-Model or with Sedimorph or with the settling velocity package SV is not supported by UPLAY.
If UNTRIM2 has to solve the transport equation for salt, heat, suspended particles or tracers UPLAY does not support the creation of images of the computational results of salinity, temperature or concentration.

Program(s) to run before this Program

UTRPRE

Program(s) to run after this Program

DAVIT, NCAGGREGATE, NCANALYSE, NCAUTO, NCDELTA, NCPLOT, NC2TABLE, UNTRIM2007MONITOR

Additional Information

Language

Fortran90

Additional software

GKS (graphical kernel system)

Original Version

J. Jürges

Maintenance