.. _python:

Python scripts and modules
===================================

Python scripts and modules are provided to quickly access the numerical data of a ComFLOW simulation (in Numpy format).
The ComFLOW Python library furthermore provides Python plug-ins for post-processing in Paraview (see :numref:`Chapter %s <paraview>`)


.. _python/prerequisites:

Prerequisites
----------------


The ComFLOW Python scripts and modules are designed for Python 3. It is therefore recommended to install
a recent 3.x version of Python. Although largely compatible with Python 2, it is not guaranteed that all functionality is available.

In order to run the ComFLOW Python script and/or to import the ComFLOW Python modules it is required to
add the ``python`` subfolder to the Python search path.
On Linux this can be done as follows (for persistent installation it is recommended
to include these line in your startup script, typically ``~/.bashrc``):

    .. code-block:: bash

       export PYTHONPATH="/path_to_comflow/python:$PYTHONPATH"

and on Windows as follows:

    .. code-block:: batch

       setx PYTHONPATH "c:\path_to_comflow\python;%PYTHONPATH%"


ComFLOW Python classes
--------------------------

The ComFLOW Python module can be accessed by means of the following import statement (assuming ``PYTHONPATH`` is already correctly set):

.. code-block:: python

    import comflow


comflow.TabularData
....................

This class can be used to load data from ASCII and binary output files.
The class provides the member function ``plot`` and the ``[]`` operator which can be used to
plot or evaluate custom expressions involving the stored time traces, e.g. ``Pressure/1000.``.
This can be useful to scale the data or to apply a time shift.

As an illustration consider the following example in which a monitor point is plotted and the pressure
is expressed in kPa:

.. code-block:: python

    import comflow

    # produce a simple Matplotlib plot
    td = comflow.TabularData("./mntrp0001.bin")
    td.plot([("Time","Pressure/1000.","Pressure [kPa]")])

    # access Numpy arrays
    t = td["Time"]
    p = td["Pressure"]

    # ...

In the following example the surface elevation is plotted as stored in the output file ``relwh0001.bin``:

.. code-block:: python

    import comflow

    # produce a simple Matplotlib plot for a relative water height probe starting at z=ZStart
    td = comflow.TabularData("./relwh0001.bin")
    td.plot([("Time","ZStart + WettedLength","Relative water height [m]")])

    # access Numpy arrays
    t = td["Time"]
    wh = td["ZStart + WettedLength"]

    # ...

*More details and examples will follow shortly.*

comflow.Simulation
..................

This class can be used to quickly access properties of a ComFLOW simulation.

*Details and examples will follow shortly.*


comflow.MonitorSurface
....................

This class can be used to read and plot data from a monitor surface output file (``surface*.bin``).

*Details and examples will follow shortly.*