Quelltext der Seite UPLAY

{{Programmkennblatt
|name_en=UPLAY
|name=uplay
|version=März 2020
|version_beschr=März 2020
|stichworte=
numerische Simulation<br />
Hydrodynamik<br />
Visualisierung<br />
Lernprogramm<br />

|kurzbeschreibung=
Das Programm UPLAY ist eine Schale um [[UNTRIM2]] und [[NCPLOT]]. Der Anwender kann mit UPLAY interaktiv die Tiefen der Gitterelemente verändern, die hydrodynamische Wirkung mit UNTRIM2 berechnen lassen und die Berechnungsergebnisse anschauen.

Die Änderungen der Tiefen im Gitter erfolgt grafisch unterstützt. Es gibt eine begrenzte Anzahl unterschiedlicher Farbklassen, wobei jede Farbklasse einer Tiefe zugeordnet ist. Im Standardfall sind es 5 Farbklassen von "Blau" entsprechend 10 m unterhalb NHN über "Hellblau" (NHN-5m), "Grün" (NHN-2m), "Orange" (NHN0m) bis "Rot" entsprechend 2 m über NHN. Der Anwender aktiviert eine dieser vordefinierten Farbklassen und klickt die Gitterelemente an, die er auf diese Tiefe bringen möchte. 

[[Bild:UPLAY1.png|thumb|250px|Bild 1: Oberfläche von UPLAY nach Änderung der Gittertiefen des "Sandkisten-Modells" durch den Anwender und Berechnung der resultierenden Strömungsgeschwindigkeiten.]]

Um die hydrodynamische Wirkung zu berechnen, macht UPLAY im Hintergrund folgendes, wenn der Anwender per Knopfdruck eine Simulation startet:
# Erzeugung der aktuellen Gitterdateien im Format [[UTRSUB_GRID.DAT|utrsub_grid.dat]] und [[PLTSUB_GRID.UPI|pltsub_grid.upi]]
# Bereitstellung der notwendigen Eingagsdateien für UNTRIM2 und Durchführung einer UNTRIM2-Simulation
# Bereitstellung der notwendigen Eingangsdateien für NCPLOT und Erzeugung der Bilder mit den Berechnungsergebnissen (Strömung und Wasserstand) für einen Berechnungs-Zeitpunkt


Die von NCPLOT erzeugten Vektor-Grafiken werden von UPLAY in ein Pixelformat ([https://de.wikipedia.org/wiki/Windows_Bitmap BMP]) konvertiert und dem Anwender präsentiert.

|eingabedateien=
Das Programm UPLAY wird standardmäßig ganz ohne Eingabe-Dateien gestartet. In diesem Fall bezieht UPLAY seine Eingabe-Dateien aus dem Ordner <tt>$PROGHOME/shellscripts/uplay/sandbox/</tt>. Der Anwender kann aber einen eigenen Ordner mit Eingabe-Dateien vorbereiten, wenn er nicht das "Sandkasten-Modell" nutzen möchte. Dann muss der Anwender die folgenden Dateien in seinem Eingangsordner bereitstellen und diesen Ordner mit der Option <tt>-userdir <name_userdir></tt> an das Programm UPLAY übergeben:
* Eingabe-Dateien für UPLAY:
** '''uplay.dat''': Eingabesteuerdatei für das Programm UPLAY. Es regelt insbesondere das Layout des Programms.
** '''Gitternetz''' (Format [[UTRSUB_GRID.DAT|utrsub_grid.dat]] und [[PLTSUB_GRID.UPI|pltsub_grid.upi]]): Lage der Gitterkanten und -elemente und Tiefe der Subkanten und Subelemente. Allerdings darf das Gitter in der aktuellen Version von UPLAY pro Gitterelement immer nur genau ein Subelement und pro Gitterkante eine Subkante enthalten.
* Eingabe-Dateien für das Simulationsprogramm [[UNTRIM2]]:
** '''[[UNTRIM2.DAT|untrim2009.dat]]''': Steuerdatei für [[UNTRIM2]]. Eine Kopplung mit dem K-Modell oder mit Sedimorph oder mit dem SV-Paket wird derzeit von UPLAY nicht unterstützt.
** '''utromp2009.dat''': Steuerdatei des hydrodynamischen Pakets UTROMP_2009. Die Beschreibung der Anfangs- und Randwerte muss einfach gehalten sein: Randwert-Dateien das Wasserstands oder eine ortsvariable Anfangsverteilung über eine IPDS-Datei werden von UPLAY derzeit nicht unterstützt.
** '''[[UNTRIM_EQS.DAT|eqs.dat]]''': Steuerdatei des Pakets EQS zur Berechnung der Dichte
** '''[[VERTICAL.DAT|vertical.dat]]''': Steuerdatei zur Definition der vertikalen Schichtung
** '''run_untrim2009_user.sh''': UNIX-Script zur Durchführung der [[UNTRIM2]]-Simulation

* Eingabe-Dateien für die Erzeugung der Ergebnis-Darstellungen:
** '''[[NC2TABLE.DAT|nc2table.dat]]''': Steuerdatei für das Programm [[NC2TABLE]]. [[NC2TABLE]] muss die Strömungs- und Wasserstands-Ergebnisse nach ASCII konvertieren, damit der konkrete Wertebereich der Ergebnisse bestimmt werden kann.
** '''run_nc2table_user.sh''': UNIX-Script zur Durchführung des [[NC2TABLE]]-Programms
** '''[[NCPLOT.DAT|ncplot_velo.dat]]''': Steuerdatei für das Programm [[NCPLOT]] zur Darstellung der flächenhaften Strömungsergebnisse
** '''run_ncplot_velo_user.sh''': UNIX-Script zur Durchführung des [[NCPLOT]]-Programms zur Erzeugung der Strömungsdarstellung. Hier ist auch die Konvertierung der NCPLOT-Vektor-Grafik zu einem Pixelbild enthalten. Die Konvertierung muss ggf. angepasst werden, um in Abhängigkeit von der Lage der Ergebnis-Darstellung auf dem Bild den korrekten Bildausschnitt zu konvertieren.
** '''[[NCPLOT.DAT|ncplot_wlev.dat]]''': Steuerdatei für das Programm [[NCPLOT]] zur Darstellung der flächenhaften Wasserstandsergebnisse
** '''run_ncplot_wlev_user.sh''': UNIX-Script zur Durchführung des [[NCPLOT]]-Programms zur Erzeugung der Wasserstandsdarstellung. Hier ist auch die Konvertierung der NCPLOT-Vektor-Grafik zu einem Pixelbild enthalten. Die Konvertierung muss ggf. angepasst werden, um in Abhängigkeit von der Lage der Ergebnis-Darstellung auf dem Bild den korrekten Bildausschnitt zu konvertieren.
** '''[[NCPLOT.DAT|ncplot_wlev_zg.dat]]''': Steuerdatei für das Programm [[NCPLOT]] zur Darstellung der zeitlichen Entwicklung der Wasserstände. Dieses Bild wird von UPLAY nicht dargestellt, kann aber im Einzelfall nützlich sein, z.B. um zu prüfen, ob die von [[UNTRIM2]] gefundene Lösung (näherungsweise) stationär ist.
** '''run_ncplot_wlev_zg_user.sh''': UNIX-Script zur Durchführung des [[NCPLOT]]-Programms zur Erzeugung der Darstellung der zeitlichen Entwicklung der Wasserstände.

|ausgabedateien=
* siehe [[UNTRIM2]] und [[NCPLOT]] 
 
|methode=
Für jeden durchgeführten Modelllauf wird im Arbeitsverzeichnis ein Unterordner angelegt. Im Unterordner einer Modellsimulation werden alle Ergebnisdateien von UNTRIM2 und NCPLOT aufbewahrt. Sie stehen somit auch nach der Erzeugung und Darstellung mit UPLAY weiter zur Verfügung. Die Namensgebung für die Unterordner setzt sich aus einem Buchstaben und 4 Ziffern zusammen: Bei einem Programm-Neustart von UPLAY wird ein Buchstabe gesucht, der bisher noch nicht verwendet worden ist. So können in einem Ordner die Simulationen von bis zu 26 UPLAY-Sessions aufbewahrt werden. Jede Simulation innerhalb einer UPLAY-Session lässt den vierstelligen Zähler um 1 erhöhen. So können 9999 Simulationen innerhalb einer UPLAY-Session durchgeführt werden.

Das Programm UPLAY kann ohne Steuerdatei und ohne Übergabe-Parameter aufgerufen werden. In diesem Fall wird ein vorbereitetes "Sandkisten-Modell" (ein 2,5 km langer und 500 m breiter Testkanal mit Rechteck-Elementen mit einer Auflösung von 500 m) verwendet. Dabei handelt es sich um ein 2D-Modell zur Berechnung der Hydrodynamik ohne den Einfluss der Dichte. Salz, Wärme, Schwebstoffe und Tracer sind im Modell nicht enthalten. Am oberstromseitigen Rand wird der Einstrom über einen FLOW-Rand mit konstant 2000 m3 s-1 gesteuert. Am unterstromseitigen Rand ist eine Wasserstands-Steuerung implementiert mit konstant +1m. Der Simulationszeitraum beträgt 1,5 Stunden mit einem Zeitschritt von 90 sec. Ziel der Simulation ist es, die resultierende stationäre Lösung zu berechnen. Deshalb ist der Implicitness-Faktor theta von [[UNTRIM2]] auch gleich 1. Verschiedene Tests haben gezeigt, dass der gewählte Zeitraum ausreichend lang ist, um am Ende des Zeitraums von einer stationären Lösung sprechen zu können. [[NCPLOT]] erzeugt ein Bild der Strömung und des Wasserstands für den letzten Ausgabezeitpunkt. Diese Bilder werden von UPLAY eingelesen und dargestellt.

'''Übergabe-Parameter'''

<tt>-h</tt>

Das Programm UPLAY zeigt nur einen Hilfetext. Das Programm wird nicht normal gestartet.

<tt>-userdir <name_userdir></tt>

Das Programm UPLAY bezieht seine Eingangsdateien standardmäßig aus dem Ordner $PROGHOME/shellscripts/uplay/sandbox. Der Anwender kann aber einen eigenen Ordner mit Eingangsdateien vorbereiten, wenn er nicht das "Sandkasten-Modell" nutzen möchte. Dazu muss der Anwender die folgenden Dateien in seinem Eingangsordner bereitstellen und diesen Ordner mit der Option -userdir <name_userdir> an das Programm UPLAY übergeben.
   
Wichtig ist, dass der Anwender in diesem Fall dafür verantwortlich ist, dass die Steuerdateien den "richtigen" Zeitpunkt zur Darstellung nutzen. Im "Sandkasten-Modell" ist dies der 61. und letzte Zeitpunkt in den netCDF-Ergebnis-Dateien von UNTRIM2. Das gleiche gilt für die Namen der Ergebnisdateien. Hierzu darf in den Steuerdateien der Platzhalter <RUN> verwendet werden. Dieser Platzhalter wird von UPLAY durch den aktuell gültigen Lauf-Namen (=Ordner-Name) ersetzt.

Falls der Anwender ein eigenes Gitternetz verwenden möchte, dann darf das Gitter pro Gitterelement immer nur genau ein Subelement und pro Gitterkante nur genau eine Subkante enthalten. Es ist auch darauf zu achten, dass die Tiefen der Gitterelemente und die Tiefen der vordefinierten Farbklassen zueinander passen, d.h. es darf kein Gitterelement existieren mit einer Tiefe, die nicht über die Farbklassen abgedeckt ist. UPLAY behandelt Tiefenwerte dann als gleich, wenn der Unterschied kleiner ist als 1 mm.

In den UNIX-Scripten muss ggf. die Konvertierung der Vektor-Grafik zu einem Pixelbild angepasst werden, um in Abhängigkeit von der Lage der Ergebnis-Darstellung auf dem Bild den korrekten Bildausschnitt zu konvertieren.

<tt>-adjusted_velocity_color_palette <yes no adjusted></tt>

Soll die Farbpalette für die Darstellung der Strömungsergebnisse an den konkreten Wertebereich der Modellergebnisse angepasst werden? Ist die Antwort="yes" oder "adjusted", dann wird eine auf den aktuellen Wertebereich angepasste Farbpalette verwendet. Ist die Antwort="no", dann wird eine Standardpalette verwendet. Default ist "no".
   
<tt>-adjusted_waterlevel_color_palette <yes no adjusted></tt>

Soll die Farbpalette für die Darstellung der Wasserstandsergebnisse an den konkreten Wertebereich der Modellergebnisse angepasst werden? Ist die Antwort="yes" oder "adjusted", dann wird eine auf den aktuellen Wertebereich angepasste Farbpalette verwendet. Ist die Antwort="no", dann wird eine Standardpalette verwendet. Default ist "adjusted".

<tt>-untrim2009_exe <name_und_pfad_zum_untrim2009_executable></tt>

Ausführbare Datei für das Programm [[UNTRIM2]]. Wird die Datei vom Anwender nicht angegeben, dann wird ein Standard-Executable aus $PROGHOME genutzt.

<tt>-nc2table_exe <name_und_pfad_zum_nc2table_executable></tt>

Ausführbare Datei für das Programm [[NC2TABLE]]. Wird die Datei vom Anwender nicht angegeben, dann wird ein Standard-Executable aus $PROGHOME genutzt.

<tt>-ncplot_exe <name_und_pfad_zum_ncplot_executable></tt>

Ausführbare Datei für das Programm [[NCPLOT]]. Wird die Datei vom Anwender nicht angegeben, dann wird ein Standard-Executable aus $PROGHOME genutzt.

'''Hinweise für Programmierer'''

Das Programm UPLAY besteht aus drei Komponenten. Erstens einem Fortran-Programm, welches als Front-End die Darstellung des Gitters, die Interaktion der Tiefenänderung durch den Anwender und die Darstellung der Modellergebnisse steuert. Zweitens einer UNIX-Shellscript-Suite als Back-End, welches eine hydrodynamische Simulation und die Erzeugung der Ergebnis-Bilder steuert. Der dritte Teil ist ein UNIX-Startscript für das Front-End, damit die notwendigen Bedingungen für eine erfolgreiche Nutzung des Fortran-Programms erfüllt sind. 

Die Kommunikation zwischen dem Fortran-Programm einerseits und den UNIX-Scripten erfolgt über Steuerdateien und UNIX-Umgebungsvariable.

Das Fortran-Programm nutzt verschiedene PROGHOME-Pakete:
* h_grid zum Lesen und Schreiben von Gitterdateien
* dic-io für das Lesen der Eingabesteuerdatei von UPLAY
* base-library für einige Grundfunktionen (z.B. zum Lesen und Schreiben von Windows-Bitmap-Files (BMP))

Darüber hinaus braucht das Fortran-Programm zwingend die GKS-Installation (GKS=Graphical Kernel System) für Basis-Funktionen zum Zeichnen und die netCDF-Installation.

'''Einschränkungen'''

* Eine Kopplung von [[UNTRIM2]] mit dem K-Modell, mit Sedimorph und mit dem Sinkgeschwindigkeitspaket SV wird von UPLAY (noch) nicht unterstützt.
* Bei einer Nutzung von [[UNTRIM2]] mit Salz-, Wärme-, Schwebstoff- oder Tracertransport unterstützt UPLAY die Darstellung der entsprechenden Salzgehalts-, Temperatur- oder Konzentrations-Ergebnisse (noch) nicht.

|preprozessor=
[[CREATE_SIMPLE_UNTRIM2_GRID]], [[UTRPRE]]
|postprozessor=
[[DAVIT]], [[NCAGGREGATE]], [[NCANALYSE]], [[NCAUTO]], [[NCDELTA]], [[NCPLOT]], [[NC2TABLE]], [[UNTRIM2007MONITOR]]
|programmiersprache=Fortran90
|zus_software= GKS (Graphical Kernel System)
|kontakt_original=[mailto:jens.juerges@baw.de J. Jürges]
|kontakt_pflege=[mailto:jens.juerges@baw.de J. Jürges]
|dokumentation= -
}}