Merge pull request #30 from xLPMG/develop

Develop

configs/tohoku.json

@@ -0,0 +1,11 @@
+{
+    "solver": "fwave",
+    "setup":"TOHOKU",
+    "outputFileName":"tohoku_solution",
+    "nx":1080,
+    "ny":600,
+    "endTime":15000,
+    "writingFrequency":100,
+    "stationFrequency":0,
+    "timeStepScaling":0.6
+}

configs/tohoku1000.json

@@ -5,5 +5,6 @@
     "nx":2700,
     "ny":1500,
     "endTime":15000,
-    "writingFrequency":100
+    "writingFrequency":100,
+    "stationFrequency":0
 }

configs/tohoku5000.json

@@ -5,5 +5,7 @@
     "nx":540,
     "ny":300,
     "endTime":15000,
-    "writingFrequency":80
+    "writingFrequency":80,
+    "stationFrequency":0,
+    "timeStepScaling":0.6
 }

docs/source/files/assignments/project.rst

@@ -2,7 +2,7 @@
 10. Project Phase
 ###################
 
-In the project phase we decided to implement a user-friendly Gui. The aim was to make the usage of our Tsunami solver
+In the project phase we decided to implement a user-friendly graphical user interface. The aim was to make the usage of our Tsunami solver
 as easy and interactive as possible. 
 
 All authors contributed in equal parts.
@@ -32,7 +32,7 @@ All it takes is to send the correct commands to the server by sticking to the AP
 GUI (Client-side)
 *********************
 
-The GUI is designed to be as intuitively usable as possible. We divided the functionality into 5 sections, which are represented by the main tabs.
+We divided all functionality into 5 sections, which are represented by the main tabs.
 
 ..  image:: ../../_static/assets/task-10-Gui_help.png
 
@@ -74,7 +74,6 @@ The system info vizualization shows usaga of the RAM during computation.
 
 In the last window, data files can be selected and then sent to the server. Receiving from the server is possible as well.
 
-
 *********************
 Server-side
 *********************

docs/source/files/categories/gui_documentation.rst

@@ -0,0 +1,210 @@
+.. _gui-doc:
+
+============================
+The Graphical User Interface
+============================
+
+Run the GUI by executing the following command in the terminal:
+
+.. code-block:: bash
+
+   ./build/gui
+
+Next, you will be greeted by the main window, which is divided into multiple tabs:
+
+*********
+Help
+*********
+
+.. figure:: /_static/assets/guidoc/tab_help.png
+   :alt: The help tab of the GUI
+   :align: center
+
+|
+This tab currently only contains a link to the documentation.
+However we plan to add more information here in the future.
+
+*************
+Connectivity
+*************
+
+.. figure:: /_static/assets/guidoc/tab_connectivity.png
+   :alt: The connectivity tab of the GUI
+   :align: center
+
+|
+This tab is used to connect to the server, which is the device that actually runs the simulation.
+This can be a remote machine or the local machine. After starting the server application from the command line, you can connect to it using this tab.
+Simply enter the IP address and port of the target device and the GUI will try to connect to it.
+
+You also the option to change the buffer sizes, however the default values should be sufficient for most use cases.
+Explanations on what these values do can be found within the GUI itself.
+
+************************
+Simulation controls
+************************
+
+.. figure:: /_static/assets/guidoc/tab_controls.png
+   :alt: The simulation controls tab of the GUI
+   :align: center
+
+|
+This is where you control the simulation. The main actions here are Run, Reset and Kill. Information on Run and Reset are also found within the GUI.
+You may also pause and continue the simulation.
+
+Below those buttons, you can find the current simulation status.
+The first value tells you what the simulator is doing right now, which can be either ``CALCULATING``, ``PREPARING`, ``RESETTING`` or ``IDLE``.
+If it is currently ``CALCULATING``, a progress bar will show you how far the simulation has progressed. 
+If you prefer numbers instead of percentages, you can get this info right below in terms of time steps.
+The last two values are how long the computation of one time step takes on average (based on all computed time steps so far) and using this value an estimation of how much time is left.
+
+You can also change the update settings, which are the polling interval to the server to gather information and a checkbox if that communication should be logged.
+
+Lastly, there is the ``Cleanup`` section. As of now, it only provides you with a button to delete checkpoint data, 
+but if we encounter any other things the user should be able to delete, we will add them here. 
+
+************************
+Windows
+************************
+
+The windows tab is used to open and close the different windows of the GUI. We will go through them in the following sections.
+
+Configuration windows
+=====================
+
+.. figure:: /_static/assets/guidoc/tab_windows_conf.png
+   :alt: Configuration windows inside the windows tab of the GUI
+   :align: center
+
+|
+Here you can find windows to configure the simulation parameters, the stations and the compiler/runtime options.
+
+Simulation parameters editor
+----------------------------
+
+.. figure:: /_static/assets/guidoc/simulation_parameters.png
+   :alt: Simulation parameter editor
+   :align: center
+
+|
+At the top of the window, you find a text input and a ``Load config`` button. 
+Simply input the path to a configuration file (which is located on the same machine the server application is running on) and press the button to load the configuration into the simulator.
+You can now run the simulation with the new parameters.
+
+Below that, you find the actual configuration editor. Here you can choose a setup and input all parameters manually.
+At the bottom you find more options for File I/O, boundary conditions and time step scaling.
+
+For more info on all parameters, please refer to :ref:`the usage manual. <config-files>`
+
+Stations manager
+-----------------
+
+.. figure:: /_static/assets/guidoc/station_manager.png
+   :alt: Stations manager
+   :align: center
+
+Here you can create stations locally and send them to the server.
+This means that any station you add to the list in the GUI will be added to the stations that are already present on the server.
+The second button allows you to delete all stations from the server.
+You can not remove single stations from the server or override stations with the same name.
+
+Compiler/runtime options editor
+---------------------------------
+
+.. figure:: /_static/assets/guidoc/compiler.png
+   :alt: Compiler options editor
+   :align: center
+
+|
+This window lets you recompile the server application with different compiler and runtime options.
+You may also select a runner to execute the server application with the new options.
+
+Each options is documented within the GUI itself. Please only use this window if you know what you are doing.
+
+Observation windows
+===================
+
+.. figure:: /_static/assets/guidoc/tab_windows_obs.png
+   :alt: Observation tool windows inside the windows tab of the GUI
+   :align: center
+
+|
+Oberservation windows are used to give the user a better understanding of what is going on by visualizing certain data.
+
+Heights visualizer
+------------------
+
+The heights visualizer is used to visualize the water level and bathymetry of the simulator. 
+The data is grabbed directly from the Simulator mid-computation and sent to the GUI for visualization.
+It will give you direct insight on how far the simulation has progressed and what the current state of the simulation is.
+
+You may view the water level
+
+.. figure:: /_static/assets/guidoc/data_viewer_height.png
+   :alt: Water level visualization
+   :align: center
+
+|
+or the bathymetry
+
+.. figure:: /_static/assets/guidoc/data_viewer_bathymetry.png
+   :alt: Bathymetry visualization
+   :align: center
+
+|
+by selecting the respective data in the top left corner of the graph. 
+You may also change the color scale at the top by entering the minimum and maximum values. Hover over the scales on the left and bottom and scroll to scale the graph. Or simply click the scale to automatically resize it.
+
+.. note:: If your simulation has a large amount of cells, the data size will therefore be large as well. Expect that the GUI will freeze while the data is being sent/received. 
+   We are working on a solution to this problem to handle the data asynchronously.
+
+Station data visualizer
+-----------------------
+
+.. figure:: /_static/assets/guidoc/station_viewer.png
+   :alt: Station data visualizer
+   :align: center
+
+|
+Use the button at the top to select a station data ``.csv`` file from the file system.
+
+The top graph will display water and bathymetry height, and the bottom graph the momentum of the water.
+Hover over the scales on the left and bottom and scroll to scale the graph. Or simply click the scale to automatically resize it.
+
+You may also click on the legend to hide/show the respective data.
+
+Client log
+----------
+
+.. figure:: /_static/assets/guidoc/log.png
+   :alt: Station data visualizer
+   :align: center
+
+|
+The client log provided you with info on data transmission of the client application and the server.
+
+System info
+-----------
+
+.. figure:: /_static/assets/guidoc/systeminfo.png
+   :alt: Station data visualizer
+   :align: center
+
+|
+The first line shows the RAM usage. Below that, you can see the overall CPU usage of the server application.
+On Linux, you may view the indivual core usage as well.
+
+Lastly, the update frequency determines how often the data is gathered from the server. Specify it in seconds.
+
+************************
+File Transfer
+************************
+
+.. figure:: /_static/assets/guidoc/tab_transfer.png
+   :alt: The file transfer tab of the GUI
+   :align: center
+
+|
+In case you are not familiar with ``sftp`` or similar file transfer tools, you may use our naive implementation.
+Simply enter the file paths of where the file is (when sending) or should be (when receiving) located on your local machine.
+Do the same for the server paths and press the respective button to start the transfer. The log will show you the progress.

docs/source/files/categories/usage.rst

@@ -7,7 +7,7 @@ Navigate to the local git repository. If the name wasnt explicitly changed, this
 If you have yet to set up and build the git repository locally, check out the :ref:`setup` page first.
 
 
-Running with GUI
+Running with the GUI
 ----------------------
 
 .. note:: 
@@ -26,24 +26,15 @@ inside the ``tsunami_lab`` folder. To start the server, run
     ./build/tsunami_lab server <PORT>
 
 also from inside the ``tsunami_lab`` folder. The ``<PORT>`` parameter specifies which port will be used for the remote connection.
+If no port is specified, ``8080`` will be used.
 
 The two applications may run on different machines, but you have to make sure that the server can be reached over TCP using
 the machines ip address and the specified port.
 
-Basic GUI Usage
------------------
+For instructions on how to use the GUI, check out :ref:`this page <gui-doc>`.
 
-After starting a server, you can connect to it using the ``Connectivity`` tab of the main window:
-
-.. image:: ../../_static/assets/gui_connect.png
-
-Simply enter the server data and click ``Connect``.
-
-.. warning::
-  Since as of now the GUI is constantly being worked on, the usage guide will end here. We will complete it once the GUI has reached a stable phase.
-
-Running without GUI
-----------------------
+Running without the GUI
+-------------------------
 
 Make sure you are inside the ``tsunami_lab`` folder.
 To run the simulator, execute
@@ -63,6 +54,8 @@ executing the command from. For example
 in case ``yourconfig.json`` is also located inside the ``tsunami_lab`` folder. If it were inside the ``resources`` folder,
 you would need to specify the relative path like ``resources/yourconfig.json``
 
+.. _config-files:
+
 Configuration files
 ---------------------
 

docs/source/index.rst

@@ -9,6 +9,7 @@ Table of Contents
    files/categories/introduction
    files/categories/setup
    files/categories/usage
+   files/categories/gui_documentation
 
 .. toctree::
    :caption: Documentation

src/Simulator.cpp

@@ -134,7 +134,7 @@ void tsunami_lab::Simulator::loadConfiguration()
   m_checkpointFrequency = m_configData.value("checkpointFrequency", -1);
 
   // read station data
-  m_stationFrequency = m_configData.value("stationFrequency", 1);
+  m_stationFrequency = m_configData.value("stationFrequency", 0);
   if (m_useFileIO)
   {
     std::string l_outputMethod = m_configData.value("outputMethod", "netcdf");
@@ -543,7 +543,11 @@ void tsunami_lab::Simulator::deriveTimeStep()
     // set count in case we load from a checkpoint file
     if (m_simTime > 0)
     {
+      if(m_stationFrequency > 0){
       m_captureCount = std::floor(m_simTime / m_stationFrequency);
+      }else{
+        m_captureCount = 0;
+      }
     }
   }
 }
@@ -795,7 +799,7 @@ void tsunami_lab::Simulator::runCalculation()
         }
       }
       // write stations
-      if (m_simTime >= m_stationFrequency * m_captureCount)
+      if (m_stationFrequency > 0 && m_simTime >= m_stationFrequency * m_captureCount)
       {
         std::cout << "  capturing station data" << std::endl;
         for (tsunami_lab::io::Station *l_s : m_stations)

src/ui/GUI.cpp

@@ -539,17 +539,17 @@ int tsunami_lab::ui::GUI::launch()
                     {
                         if (ImGui::BeginTabItem("Configuration"))
                         {
-                            ImGui::Checkbox("Edit simulation parameters", &showSimulationParameterWindow);
-                            ImGui::Checkbox("Manage stations", &showStationsWindow);
-                            ImGui::Checkbox("Edit compiler/runtime options", &showCompilerOptionsWindow);
+                            ImGui::Checkbox("Simulation parameter editor", &showSimulationParameterWindow);
+                            ImGui::Checkbox("Stations manager", &showStationsWindow);
+                            ImGui::Checkbox("Compiler/runtime options editor", &showCompilerOptionsWindow);
                             ImGui::EndTabItem();
                         }
                         if (ImGui::BeginTabItem("Observation tools"))
                         {
-                            ImGui::Checkbox("Show station data visualizer", &showStationDataVisualizer);
-                            ImGui::Checkbox("Show data visualizer", &showDataVisualizer);
-                            ImGui::Checkbox("Show client log", &showClientLog);
-                            ImGui::Checkbox("Show system info", &showSystemInfoWindow);
+                            ImGui::Checkbox("Heights visualizer", &showDataVisualizer);
+                            ImGui::Checkbox("Station data visualizer", &showStationDataVisualizer);
+                            ImGui::Checkbox("Client log", &showClientLog);
+                            ImGui::Checkbox("System info", &showSystemInfoWindow);
                             ImGui::EndTabItem();
                         }
                         ImGui::EndTabBar();
@@ -645,6 +645,7 @@ int tsunami_lab::ui::GUI::launch()
             ImGui::ColorEdit3("Background color", (float *)&clear_color);
 
             ImGui::Text("Application average %.3f ms/frame (%.1f FPS)", 1000.0f / io.Framerate, io.Framerate);
+            ImGui::Text("You are currently using version %s", VERSION);
             ImGui::Text("made by Luca-Philipp Grumbach and Richard Hofmann");
             ImGui::End();
         }

src/ui/GUI.h

@@ -27,6 +27,8 @@ namespace tsunami_lab
 class tsunami_lab::ui::GUI
 {
 private:
+  //! Version of the GUI
+  const char *VERSION = "1.0.2";
   //! Width of the window
   const unsigned int WINDOW_WIDTH = 1500;
   //! Height of the window