.. _getting_started_1:

**********************************
Getting Started 1: Example Project
**********************************

This section provides a brief demonstration of executing a fully prepared 
DTOcean simulation. The zip file containing the example files used for this
exercise can be  downloaded from `Github 
<https://github.com/DTOcean/dtocean/releases>`__. Unzip the archive to your
preferred location.

Open the Project
================

The first step is to open the "RM3_10_example.dto" file. Start DTOcean and
use the "Open" button from the main toolbar to open the file, as shown in
:numref:`fig_open`.

.. _fig_open:
.. figure:: /images/open_action.png

   Left-click the "Open" button

Locate and select the file using the file dialogue and click the "Open" button. 
The "pipeline" dock should now populate with variables, all of which except one 
will have green (satisfied) or blue (optional) indicators as seen in 
:numref:`fig_example_pipeline`. 

.. _fig_example_pipeline:
.. figure:: /images/example_pipeline.png

   The "Pipeline" dock showing the status of variables

Add Wave Device Model Data
==========================

The only variable not satisfied in the example is the "Wave Data Directory". 
This variable provides the path to the wave device model data generated by the 
"WEC Simulator" pre-processing tool. The output folder for the RM3 device is 
included alongside the example ".dto" file, so we simply need to set the path 
to its location. 

Firstly, select the "Wave Data Directory" variable in the 
"Modules->Hydrodynamics" branch of the "Configuration" section of the pipeline, 
as shown in :numref:`fig_wave_data_directory`. The main window will now contain 
a text field for entering the path, as seen in :numref:`fig_select_directory`. 
If the text field is not visible then ensure that the "data context" is 
selected in the main toolbar, as in :numref:`fig_data_context`. 

.. _fig_wave_data_directory:
.. figure:: /images/wave_data_directory.png

   Left-click the "Wave Data Directory" variable

.. _fig_select_directory:
.. figure:: /images/select_directory.png

   Text field for entering the folder path

.. _fig_data_context:
.. figure:: /images/data_context.png

   The "data context" is used for entering input data and viewing results

Click the "..." button, seen in :numref:`fig_select_directory`, to open a file
dialogue and select the "**RM3 Model Data**" folder contained in the example
archive. Finally, you must click the "OK" button at the bottom of the window,
shown in :numref:`fig_ok_button`, to add the chosen path to the variable. The
variable's indicator will now change to a green circle.

.. _fig_ok_button:
.. figure:: /images/ok_button.png

   The "OK" button must be clicked to add data to a variable

Add an Execution Strategy
=========================

DTOcean divides the design of an OEC array into distinct stages which are 
computed by "modules". Modules can be run individually or using an "execution
strategy" which allows more advanced usage, such as conducting sensitivity
studies. The most basic execution strategy runs all of the modules in a
simulation in a single action and we will now select this strategy. To begin,
click the "Select Strategy" button in the main toolbar, as shown in 
:numref:`fig_select_strategy_button`.

.. _fig_select_strategy_button:
.. figure:: /images/select_strategy_button.png

   Left-click the "Select Strategy" button

The "Strategy Manager" dialogue will now open, which is used to select and
configure execution strategies. As shown in :numref:`fig_basic_strategy`, select
"Basic" from the "Available strategies" list and then click "Apply" as shown in
:numref:`fig_apply_button`. 

.. _fig_basic_strategy:
.. figure:: /images/basic_strategy.png

   Select the "Basic" strategy from the list of available strategies

.. _fig_apply_button:
.. figure:: /images/apply_button.png

   Left-click the "Apply" button

The current execution strategy should now be displayed at the top of the 
strategy manager, as seen in :numref:`fig_selected_strategy`. The Basic 
strategy requires no configuration, so click the "Close" button to leave the 
dialogue. 

.. _fig_selected_strategy:
.. figure:: /images/selected_strategy.png

   The current execution strategy is displayed at the top of the dialogue

.. _exectute_simulation:

Execute the Simulation
======================

The simulation is now ready to be executed. As an execution strategy has been
applied we need to click the "Run Strategy" button from the main toolbar, as
seen in :numref:`fig_run_strategy_button`.

.. _fig_run_strategy_button:
.. figure:: /images/run_strategy_button.png

   Left-click the "Run Strategy" button

A dialogue now opens which informs us if any required variables have not yet 
been set. At this stage, all required variables should be satisfied, so the 
dialogue will return "PASSED", as seen in 
:numref:`fig_data_requirements_passed`.

.. _fig_data_requirements_passed:
.. figure:: /images/data_requirements_passed.png 

   All required variables have been satisfied

Clicking "OK" in the dialogue will start the execution of the simulation. If you
want to go back, for any reason, click "Cancel". Once the simulation has
started the user interface will not be accessible until the strategy has
completed or failed. An indicator shows that the simulation is still computing,
as shown in :numref:`fig_progress_bar`. The "System" dock, at the bottom the
user-interface, will show any logging information sent from the modules. The
simulation will require about 30 minutes to complete.

.. _fig_progress_bar:
.. figure:: /images/progress_bar.png

   The progress bar is shown while the strategy is being executed

Inspect the Results
===================

Once the simulation has been executed (and no errors have been encountered) the
pipeline dock will close the configuration branches and populate the results
branches. To examine the LCOE for the array, click the "Most Likely Levelised
Cost of Energy" variable in the "Assessment->Economics" branch of the "Results"
section of the pipeline, as shown in :numref:`fig_most_likely_lcoe` (you will
need to scroll down to find it).

.. _fig_most_likely_lcoe:
.. figure:: /images/most_likely_lcoe.png

   Left-click the "Most Likely Levelised Cost of Energy" variable

Assuming that the data context is selected, the value will appear in the main
window. It should be around 1.13 Euro\\kWh, although it can vary slightly due
to the statistical method used for its calculation.

DTOcean provides a number of default (based on data type) and customised plots 
for visualising inputs and results. As an example, let's look at the cable layout 
designed by the electrical sub-sytems module. First, find the "Cable Route 
Data" variable in the "Modules->Electrical Sub-Sytems" branch of the results 
section of the pipeline, as shown in :numref:`fig_cable_route_data`. 

.. _fig_cable_route_data:
.. figure:: /images/cable_route_data.png

   Left-click the "Cable Route Data" variable

The main section of the interface will now show the table of raw data which 
describes the cable routes. To view the plot, the interface must be switched to 
the "plots context" by clicking the button in the main toolbar, as shown in 
:numref:`fig_plots_context`.

.. _fig_plots_context:
.. figure:: /images/plots_context.png

   The "plots context" is used for viewing plots

The main window should now show the custom plot of the electrical cable layout, 
as seen in :numref:`fig_cable_route_plot`, which also shows other array 
features such as the devices and lease area. You may need to maximise the 
DTOcean window, or close the System dock to see the plot clearly. 

.. _fig_cable_route_plot:
.. figure:: /images/cable_route_plot.png

   Plot of the electrical cable routes and related array features

.. _assessment_scope:

Change the Assessment Scope
===========================

DTOcean applies "assessments" to the results of each design module, which 
calculates metrics such as the levelised cost of energy (LCOE). The assessments 
are calculated over two scopes, "global" and "module". The global scope carries 
out the assessment for all results produced so far in the simulation, whilst 
the module scope only uses the results generated by the last executed module 
[#f1]_. The difference can be illustrated by observing the "CAPEX (Excluding 
Externalities)" variable. This is found in the "Assessment->Economics" branch 
of the "Results" section of the pipeline, as shown in 
:numref:`fig_capex_excluding_ext`. 

.. _fig_capex_excluding_ext:
.. figure:: /images/capex_excluding_ext.png

   Left-click the "CAPEX (Excluding Externalities)" variable

Switching back to the data context, a value of about 30 million Euro should be 
visible in the main window. Now use the radio button at the top of the 
pipeline, shown in :numref:`fig_module_scope`, to switch to the module 
assessment scope. Because the last executed module was Operations and 
Maintenance, and the contribution to the CAPEX from maintenance is zero, the 
CAPEX (Excluding Externalities) variable will now also be zero. 

.. _fig_module_scope:
.. figure:: /images/module_scope.png

   Use the radio button to switch to the "Module" assessment scope

View Results Evolution
======================

Visualising how results evolved over the course of a simulation is another 
useful feature of DTOcean. We can "inspect" the state of all variables 
following the execution of any module. First, switch back to the global scope, 
as shown in :numref:`fig_global_scope`. Now, right click on one of the 
"Modules->Mooring and Foundations" branches, in the Configuration or Results 
section, to bring up the context menu and click the "Inspect" command, as shown 
in :numref:`fig_pipeline_context_inspect`. The Inspect command operates the same
way for a branch in the Configuration or Results section of the pipeline.

.. _fig_global_scope:
.. figure:: /images/global_scope.png

   Use the radio button to switch to the "Global" assessment scope

.. _fig_pipeline_context_inspect:
.. figure:: /images/pipeline_context_inspect.png

   Right-click the "Mooring and Foundations" branch and choose "Inspect" from
   the context menu

The variables are now displaying their state following execution of the Mooring 
and Foundations module. Selecting the "CAPEX (Excluding Externalities)" 
variable again, the value shown should be about 28 million Euro. As expected, 
this is less than the final CAPEX, as the value does not include the cost of 
installation. 

Before moving onto the next section, select "Inspect" on the "Operations and
Maintenance" module, to show the results in their final state once more.

Clone and Re-Execute
====================

DTOcean contains advanced memory management features that make it easy to 
clone, alter, re-execute and compare simulations. Execution strategies may
also create clones of simulations. To demonstrate this functionality, we
will clone the default simulation, modify the preferred foundation type 
of the devices, and then re-execute.

To begin, switch to the "Simulations" dock, by clicking the tab in the top
left corner of the interface, as shown in :numref:`fig_simulations_tab`. The
simulations dock should now be shown, containing the "Default" simulation.
Create a clone of this simulation by right-clicking and selecting "Clone" from
the menu, as shown in :numref:`fig_clone_simulation`.

.. _fig_simulations_tab:
.. figure:: /images/simulations_tab.png

   Left-click the "Simulations" tab

.. _fig_clone_simulation:
.. figure:: /images/clone_simulation.png

   Right-click the "Default" simulation and select "Clone"

A second simulation will appear in the list of simulations. You can rename 
simulations at any time by double-clicking on the simulation and entering the 
new name. Note, simulations can not currently be deleted or re-ordered. Return 
to the pipeline dock (by left-clicking the "Pipeline" tab). We are going to 
move the state of our new simulation back to prior to execution of the mooring 
and foundation module. To do this, right-click on the "Modules->Mooring and 
Foundations" branch in the "Configuration" section of the pipeline and select 
"Reset", as shown in :numref:`fig_pipeline_context_reset`. Always take care 
when using the "Reset" command as all results from the chosen module onwards 
will be deleted. 

.. _fig_pipeline_context_reset:
.. figure:: /images/pipeline_context_reset.png

   Right-click the "Mooring and Foundations" branch and choose "Reset" from
   the context menu

Expand the Mooring and Foundations branch and find the "Preferred Foundations 
Type" variable. Ensuring that the data context is active, use the drop-down box 
in the main window to select "Gravity" and then click the "OK" button. The 
current value shown should now update to "Gravity", as shown in 
:numref:`fig_preferred_foundation_type`. 

.. _fig_preferred_foundation_type:
.. figure:: /images/preferred_foundation_type.png

   Set the "Preferred Foundations Type" variable to "Gravity"

The cloned simulation is now ready to be executed, so click the "Run Strategy" 
button again (as shown in :numref:`fig_run_strategy_button`) and the simulation 
will create new results from the mooring and foundations module onwards. 

Compare Results
===============

By using the simulation and pipeline docks in unison, it's easy to compare 
results from different simulations. Once the cloned simulation is completed, 
select the Simulations dock and then drag it to a position above the Pipeline 
dock, as shown in :numref:`fig_redock_simulations`, so that both docks can be 
seen together. 

.. _fig_redock_simulations:
.. figure:: /images/redock_simulations.png

   Drag the Simulation dock to a position above the Pipeline dock

Now, in the pipeline, find the "CAPEX (Excluding Externalities)" output 
variable again and select it, ensuring that the data context is active (see 
:numref:`fig_data_context`. Using the simulation dock, click on each simulation 
in turn and watch the value in the main window update. The same functionality 
can be used for all other variables and plots and for any number of 
simulations. 

Further insight can be gained by using the "comparisons context", which can
be activated by clicking the "Comparisons" button in the toolbar, as shown in
:numref:`fig_comparisons_context`.

.. _fig_comparisons_context:
.. figure:: /images/comparisons_context.png

   The "comparisons context" is used for comparing simulations

In the "Module Comparison" window, ensure that the "Mode" is set the "Plot" and 
then start typing "CAPEX (Excluding Externalities)" into the "Variable" field. 
Select the variable from the list that will appear below the search box. The 
correct setup is shown in :numref:`fig_module_comparison`. When ready click the 
"OK" button and a plot will appear showing the recorded CAPEX following each 
module for the two different simulations. 

.. _fig_module_comparison:
.. figure:: /images/module_comparison.png

   The "Module Comparison" window, ready to plot for the "CAPEX (Excluding
   Externalities)" variable

The differences between the simulations are even clearer when comparing using 
the Module assessment scope (the :ref:`assessment_scope` section describes how 
to change the scope). Drawing the comparison plot again, with the module scope 
selected, produces a plot similar to :numref:`fig_module_comparison_plot`. 
Here, it can be seen that not only does the CAPEX increase following the 
Mooring and Foundations module, but also the cost of installation is greater. 

.. _fig_module_comparison_plot:
.. figure:: /images/module_comparison_plot.png

   Module comparison plot using the "Module" assessment scope

Finishing Up
============

DTOcean projects can be easily saved to file. To avoid overwriting the
tutorial file, chose "Save As..." from the "File" menu, as shown in
:numref:`fig_save_as`. Use the file dialogue to save the project to a path
of your choosing.

.. _fig_save_as:
.. figure:: /images/save_as.png

   Left click "Save As..." to save the project to a new file

.. rubric:: Footnotes

.. [#f1] The module scope will use all variables which are not an output of
         another module, including, for instance, imported data.