.. Watlab documentation file, created by
   Pierre-Yves Gousenbourger on Wed Aug 2, 2023.

.. _run-watlab:

Watlab for dummies
==================

Watlab works as a Python API, which means that you need to know how to run a Python script, use a Python interpreter and load a Python library. See also the links proposed in the :ref:`previous chapter <setup>` for some useful tutorials.

To run your watlab simulation, you will need three things:

* A mesh constructed with GMSH (see our :ref:`tutorial <create-mesh>` or :download:`download it <../storage/tutorial-mesh.msh>`);
* A proper model;
* Some initial and boundary conditions.

This page will guide you through the two last (but most important!) steps with Watlab.


Set up the Watlab model
-----------------------

Starting using watlab and initializing the model is very easy. You would need to do three steps : 

1. Load the adapted model module from watlab (here, it is hydroflow)
2. Load the mesh
3. Build the model based on that mesh.

Here we provide a first example based on the hydrodynamic module of Watlab : Hydroflow. 

.. code-block:: python

   # Load the module
   from watlab import hydroflow

   # Load the mesh
   mesh = hydroflow.Mesh('path/to/tutorial-mesh.msh')

   # Impose a meshchecking for this simulation (only if needed, default = False)
   mesh.meshchecking = True

   # Create the model
   model = hydroflow.HydroflowModel(mesh)


That's it, your model is set up !


Parameterize the model
----------------------

The model comes with numerous functions and parameters that allow to set up your simulation: initial conditions, boundary conditions, running parameters, etc.

- The syntax to modify a parameter is always ``model.parameter = value``;
- The syntax to add an initial condition is ``model.set_condition(regions, values)`` where ``regions`` is a (list of) name of region from the mesh, and ``values`` is a (list of) values corresponding to the condition;
- The syntax do add boundary conditoons is ``model.set_condition(regions, values)`` where ``bounadry`` is a (list of) name of boundary from the mesh, and ``values`` is a (list of) values corresponding to the condition; 


In the following example, the name of the simulation is modified, and the initial water level is fixed in the "Filled area" of the mesh.

.. code-block:: python

   model.name = "my simulation name"
   model.set_initial_water_level("Filled area", 0.15)
   model.set_wall_boundaries(["Boundaries down", "Boundaries up", "Boundaries right", "Boundaries left"])

The list of parameters and conditions is given in the :ref:`documentation <model-module>` with an exhaustive explanation of the entry parameters.


To get the conditions, just call ``model.get_initial_conditions()`` or ``model.get_boundary_conditons()``.


Launch the simulation
---------------------

Finally, to run the code, you will need to export the data files, then solve the model :

.. code-block:: python

   model.export_data()
   model.solve()


This last line runs the simulator file. If this latter does not exist, the C++ (calculation code) will be compiled and run. If it exists, the simulation will start directly. 


Post-process the results
========================

Section in construction.