.. _gui: Graphical User Interface ======================== Introduction ------------ DTOcean provides a Graphical User Interface (GUI). This chapter presents the visual components of the GUI and its main functionalities. A technical description (i.e. the technologies and architecture) of the GUI can be found in the Technical Manual. Key Concepts ------------ This section summarises the key concepts that need to be understood whilst using DTOcean. * **Project**: A project is the overarching container for a design session using the DTOcean software. Projects contain one or many Simulations and can be saved and reloaded. * **Simulation**: A simulation refers to a single calculation of LCOE for a given set of computational modules. Simulations and the thematic assessments of their results are configurable by the user. * **Module**: Computational module are the main functional engines of the DTOcean software, manipulating existing and creating new data for a particular purpose (such as solving the layout and power output of the array of OECs). * **Assessment**: Assessments are used to provide key metrics to compare different farm design simulations. Thematic algorithms provide the assessments. * **Learning Strategies**: Learning strategies are used to calculate the value of LCOE for a complete computationally defined farm. Various levels of learning strategies can be used from the most basic to more complex strategies for finding solutions closer to the optimum. * **Data**: Data refers to variables that are required as inputs to the computational modules and thematic algorithms, and the results obtained from them. * **Database**: The database is a persistent store of data that can be used to support the needs of the design process. It contains both long standing reference data and project specific data, although this data is prepared prior to creating a project. * **Levels**: A “level” refers to the state of the data after execution of a particular module. The software can recall any level in any simulation and compare between them. * **Pipeline**: The pipeline provides a structured methodology for preparing simulations, visualising the order of execution and examining results. * **Tools**: Tools are small functions that can be used to manipulate or create new data to aid the operation of the software. Unlike the computational modules, however, they do not have any design purpose and work (mostly) on one, rather than many, variables. Layout ------ .. _fig-main-layout: .. figure:: /images/user/main_layout.png Main layout The main feature of these existing layouts are a large visualisation area (normally to the right), which is often interactive, and a tree like structure to the left where simulations, maps, charts, visualisations, etc. are configured and prepared. The DTOcean software shares these two main components. The chosen layout for the DTOcean software is shown in :numref:`fig-main-layout`. At the top of the layout there are the menus and icon bar. Below these, on the left hand side of the screen, lies a dock window with two tabs; one relates to a particular simulation (pipeline dock), and the other lists all the simulations within a project. As more simulations are added to a project (automatically by a strategy or manually by the user), they will will be added in the simulation tab on the left. The dock area labelled as the “Pipeline” (and this name is used to identify this area in some actions) is used to control simulations by interacting with computational modules, thematic assessments and data. Here, the entry/visualisation window is labelled as “Data Entry/Visualisation. Below the Data Visualisation area is an area named the “System Dock”. As the name implies, the primary purpose of this area is to show the logging information being generated by the core, computational modules and thematic algorithms. Menus ----- The DTOcean software has a number of standard menus that serve various purposes. In the subsections below, each menu is considered in turn and its associated functions are described. File Menu ^^^^^^^^^ The file menu is for working with projects, the overall container for a session within DTOcean. It contains the following actions: * **New**: create a new project from scratch * **Open / Open recent**: open an existing project file or a file that was recently open * **Save / Save as**: save the open project file or save it to a particular file name * **Properties**: set some meta data information about the project * **Close**: close the current project (if open) * **Exit**: shut down DTOcean Simulation Menu ^^^^^^^^^^^^^^^ This simulation menu is used for undertaking actions relating to carrying out simulations, in particular selecting modules, thematic assessments and learning strategies. The actions in the menu are as follows: * **Add Modules**: select which computational modules are required for the simulation * **Add Assessment**: select which thematic algorithms are required for the simulation * **Add Strategy**: select a strategy to run simulations * **Run Current Module**: execute the current module * **Run Themes**: execute all the thematic assessments * **Run Strategy**: execute the selected strategy Data Menu ^^^^^^^^^ The data menu provides actions related to acquiring, storing, reporting and manipulating data. Through this menu a DTOcean database can be connected and configured. The actions available through the data menu are as follows: * **Select Database**: select the database for filtering the data of the scenarios * **Initiate Pipeline**: start the pipeline area and collect top level information from the selected database * **Initiate Bathymetry**: filters the bathymetry out of the database * **Initiate Dataflow**: given the provided top level data, collect site and technology related data from the database. The user may also choose to consider a non-stored site and technology Note that the database actions, Edit, Clone and Delete are extensions of the baseline functionality and would be provided as part of the database development. View Menu ^^^^^^^^^ The view menu allows access to a small group of actions related solely to visualisation within the GUI. The available actions are: * **Show Simulations**: show the list of the simulations which have been run in the simulation dock. * **Show System Log**: toggle on and off the system dock window * **Data**: show Data in the Data Visualisation Window * **Plots**: show Plots f available in the Data Visualisation Window * **Show Comparison**: show comparisons through different simulations The actions relating to image manipulation and storage are extensions to the baseline functionality. Help Menu ^^^^^^^^^ The help menu will provide access to various sections of the manuals, details about the software version, and how to get support. Contextual Menus ^^^^^^^^^^^^^^^^ Within the “Pipeline” tree various contextual menus will be made available (when right clicking on a branch or variable) to allow some of the menu functions described above to be used directly. Icon Bar ^^^^^^^^ The icon bar provides short cuts for various menu options in Section 4.4. :numref:`tab-icons` provides a description for each icon in the icon bar. .. _tab-icons: .. figure:: /images/user/icons.png Description of the icons in the icon bar. Pipeline Widget and Status Indicators ------------------------------------- .. _fig-pipeline: .. figure:: /images/user/pipeline.png The “pipeline” tree widget The “pipeline” concept uses the familiar tree structure seen in a number of scientific computational packages. Generally, this tree structure, to the left hand side of the screen, allows detailed investigation into the components of the system being investigated. :numref:`fig-pipeline` shows the default layout of the pipeline, once it’s been initiated (after connecting to a DTOcean database). There are two default sections, describedas follows: * Configuration - This is the area that is used to set up a Simulation, choose a site and technology, prepare the inputs for the modules and themes and provide information for any learning strategies * Results This area contains results carried out by each module as well as by the thematic algorithms Displayed within the branches of the tree (such as a branch for the Hydrodynamics module) are individual items of data that can be manipulated and visualised. These variables also have indicators of various colours to describe the status of the data it contains. The indicators for input variables can be seen in :numref:`fig-color-status`. For inputs, the meanings of these indicators for the variables are as follows: * **Green circle**: The data for the variable has been entered * **Red square**: The data for the variable is required and has not been entered * **Blue diamond**: The data for the variable is optional and has not been entered * **Grey cross**: The data will be supplied by the outputs of another module For outputs, the meanings change: * **Green light**: The data for the variable is available * **Grey cross**: The data has been overwritten by another module .. _fig-color-status: .. figure:: /images/user/color_status.png Coloured status indicators within the pipeline widget Data Entry and Visualisation Widgets ------------------------------------ .. _fig-data-entry: .. figure:: /images/user/data_entry.png Example data entry widget for selecting from a list of strings The central Data Window can be used to both enter data and visualise basic result values, such as strings, integers and floating point numbers. :numref:`fig-data-entry` provides an example of a widget for collecting a string from a predefined list (nominally set in the data definition specification files, but also potentially being supplied by the database). In general, these widgets contain a contextual data entry part (in this case a drop down list), based on the structure definition given in the data definition specification (DDS). Different widgets are matched to the different types of data that are required. Below this data entry section are a standard set of buttons, with actions as follows: * **OK**: this action adds the data entered through the widget into the software * **Cancel**: this action removes the stored data from the software .. _fig-chart: .. figure:: /images/user/chart.png A chart in the Data Visualisation window Both input and output data may have charts which can be visualised with the Data Visualisation area as demonstrated in :numref:`fig-chart`. Again, these charts are generated given the context of the data structure defined in the DDS. The plots can be saved. The Data Entry area can also be used to show outputs as seen in :numref:`fig-data-output`. Again, the format of these outputs is contextually based on the data structure being displayed. .. _fig-data-output: .. figure:: /images/user/data_output.png Data output widget matching the chart in the previous figure. System Dock and other Dialogues ------------------------------- This area of the GUI allows the user to observe the actions of the underlying system. The logging window will automatically collect the logging information being produced by the core, modules and thematic assessments and display it to the user as seen in :numref:`fig-dock`. .. _fig-dock: .. figure:: /images/user/dock.png The Logging and Terminal tabs of the System Widget .. _fig-dialog: .. figure:: /images/user/dialog.png A selection of pop-up dialogues with various functions The software also utilises a number of pop up dialogues which are used for specialised functions. Some examples of this are the selection of modules, themes and strategies using a shuttle dialogue, or progress bars to indicate progress of data download or module execution. Some examples of these dialogues can be seen in :numref:`fig-dialog`. Project Scenario ---------------- Summary ^^^^^^^ The following scenario considers using the DTOcean software to investigate an array deployment scenario. The aim is to prepare and execute a simulation, examine the results, and then make a modified simulation to evaluate the impact of design changes. Each of the following subsections represents a logical step in this process, starting from opening the software for the first time. Opening DTOcean ^^^^^^^^^^^^^^^ The user opens the DTOcean GUI and is presented with the menus and shortcut icons only. Most of these will be inactive until a new project is opened. The user can select “New Project” from the “File” menu as seen in :numref:`fig-new` which will lead to the layout skeleton appearing. .. _fig-new: .. figure:: /images/user/new.png Creation of a new project Modification of the Database ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Additional actions may be available for the open project from the database menu such as these functions: * Cloning the master database to create “personal” copies. * Editing database entries The user may choose to undertake these actions before activating their chosen database for their project. Note, the provision of these functions is provided as part of the DTOcean database development, and are considered extensions of the baseline functionality. Activating the Pipeline ^^^^^^^^^^^^^^^^^^^^^^^ Activating the pipeline is an option available within of the Database menu. Essentially, this means choosing which database should be used to provide the scenario data. This is assumed to be a choice between the original master database and any clones that have been made by the user, as seen in :numref:`fig-ini-pipeline`. Once the pipeline is activated, new information will appear within the pipeline browser, under the scenario category. Entering Scenario Selections ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order for the database to fulfil the requirements of the scenario, the user must enter certain data. The particular data that must be provided is now displayed under the Scenario main category as seen in :numref:`fig-scenario-inputs`. It will be indicated if certain data has not been provided yet (using a red icon). Some of the inputs may also require to be made unavailable (grey) until other information has been entered. For instance, defining the deployment area does not make sense until the site has been selected. Once the user selects one of the required inputs, the data entry section below the pipeline activates and shows certain fields that can be modified in order to fulfil the data requirements. For instance, for site selection there may be a selection of possible sites, displayed in a drop down menu. The user then selects a site, and presses an “Apply” button. At this point, it might be possible to provide a visual output of the site selection in the data visualisation area of the screen. Selection of the site activates further options such as selecting the deployment area for which the user will set the range of coordinates. Thus, the user continues entering data in a similar manner until all of the parameters specifying the scenario have been entered. .. image:: /images/user/ini_pipeline.png .. _fig-ini-pipeline: .. figure:: /images/user/ini_pipeline2.png Initiating the pipeline .. _fig-scenario-inputs: .. figure:: /images/user/scenario_inputs.png Scenario inputs Selection of Modules and Assessment Criteria ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Following the scenario specification, the user selects which modules and assessment criteria they wish to include in the simulation. It is important to carry out this selection at this stage as it will govern the data requirements for the overall simulation. The user can select the modules and assessment criteria either from the “Simulation” menu or from the contextual menus available from the “Modules” and “Assessment” pipeline categories, as shown in :numref:`fig-add-module`. When choosing to add modules from the Simulation menu, a “transfer box” will open, where the user can move the modules from the inactive side to the active, as seen in :numref:`fig-transfer`. Note that there is no option to reorder the modules, as the order of execution of multiple modules will be controlled automatically within DTOcean. A similar widget is used for the thematic assessment functions. .. _fig-add-module: .. figure:: /images/user/add_module.png Adding modules from the Simulation menu .. _fig-transfer: .. figure:: /images/user/transfer.png Adding modules in “transfer box” Initiating the Dataflow ^^^^^^^^^^^^^^^^^^^^^^^ Once the required modules and assessment functions have been chosen, the user is required to select “Initiate Dataflow”, either from the simulation menu or using an icon, as seen in :numref:`fig-ini-dataflow`. Two actions are initiated by this: firstly, the system will calculate the data requirements given the modules and assessment functions that have been chosen. Once this “dataflow” has been calculated, the system will then collect data from the database which satisfies the input requirements. The progress of these actions can be shown to the user utilising a pop up widget should they require significant amounts of time. .. _fig-ini-dataflow: .. figure:: /images/user/ini_dataflow.png Initiate dataflow menu Finalising Data and Configuring Modules ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once the dataflow has been initialised, the modules and assessment functions will become active in the pipeline. The user can then perform various actions, such as configure certain options for each module or function, or inspect and set values for data. An example of this process is shown in :numref:`fig-scenario-conf`. The indicators of completion will be given in the pipeline once all necessary data to fulfil the criteria of the module inputs has been supplied. .. _fig-scenario-conf: .. figure:: /images/user/scenario_conf.png Scenario configuration The user can supply information in various ways (e.g. manual input or files). The user can also choose to override inputs from the database at this stage. These new values will be stored within the simulation for the time of the session (or longer should the user choose to save the project). Note that the database values are not updated. Preparing the Strategy ^^^^^^^^^^^^^^^^^^^^^^ Having fulfilled all of the criteria of the module, the user can now select a strategy to run simulations. The most basic strategy is to execute all the modules sequentially. For more complex strategies, the user will need to control some parameters for which to attempt improve the LCOE. This is for a single parameter from the inputs with some ranges to test (i.e. a single variable sensitivity study), or a more complicated strategy possibly with some combinations of parameters as described in the requirements for the sequencing and optimisation component. Running a Simulation with a Basic Strategy ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once all of the required inputs have been satisfied the user will select “Run Strategy” from the Simulation menu or from the icons. Initially, it will be checked if the user has fulfilled the input requirements and if not, those that are still required will be displayed. If the data requirements have been satisfied then the user will be informed that the simulation has started and they will be able to track the progress of the simulation in the logging menu. Should the simulation fail for some reason (e.g. a crash or exceed accuracy targets), the user will be informed by a dialogue with the possibility to examine the cause of the failure in the logging window. Similarly, when the simulation is complete, the user is informed with a dialogue box. Visualising Results ^^^^^^^^^^^^^^^^^^^ The results of the simulations are displayed in the pipeline using two sections as shown in :numref:`fig-module-output`. The “Results” section displays the aggregated global values of the assessment criteria (the results from all modules amalgamated into single metrics or charts). Additionally, the current value of all the variables related to the executed modules up to and including the last executed module can be seen. When an output variable is selected in the pipeline, an appropriate display will be shown in the data visualisation window. .. _fig-strategy-user: .. figure:: /images/user/strategy.png Using a strategy to attempt to run a simulation which required additional data .. _fig-module-output: .. figure:: /images/user/module_output.png Outputs from a module Changing the Active Module ^^^^^^^^^^^^^^^^^^^^^^^^^^ Following completion of a full simulation, obtaining a first attempt at an LCOE estimate, the user of the GUI may wish to go back to a previous state of the data and examine the system at that level of the computation. There are two methods for the user to change the active module. Both of them can be active while right-clicking on the module the user wants to go back to: * Reset: it moves the system back to that module, but the user cannot move forward (i.e.e the forward results will be lost) * Inspect: moves the results back to that module, but the forward results are not lost and the user can move the other modules if run. Simulation Cloning and Execution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Rather than destroy the outcome of the first simulation by changing the inputs to the next module the user can decide to clone the simulation. This creates an exact copy of the active simulation at the level that the user has selected. Thus, if the user creates a clone at the completion of a full simulation, then the clone contains all the results of that simulation. Otherwise, as is most likely, the clone contains the data up to the level selected by the user prior to the cloning process. Once the simulation is cloned, data can be changed in the clone and the simulation restarted in a similar manner to the original simulation. The most basic strategy will be able to restart the simulation at an intermediate stage and then complete it.