.. _pfb:

PFB
====

.. _pfb_intro:

Introduction
-------------

ParFlow Binary (PFB) files are an integral part of ParFlow, and we need an easy way to handle them. 
Fortunately, we have a several functions within ``pftools`` that help us with this.  The ``parflow.tools.io`` 
module allows the user to work with numpy arrays, which are easy to visualize and manipulate 
in Python. We'll walk through some examples working with PFB files in Python to see just how powerful 
this is.

.. _pfb_dist:

Distributing
-------------

Let's say you have mastered the conversion of a TCL script to Python, and you have a few PFB 
files that you need to distribute to convert your workflow to Python. Here, you can use the 
``dist()`` method on your ``Run`` object that you created, as mentioned in the first tutorial:

.. code-block:: python3

    LWvdz.dist('lw.1km.slope_x.10x.pfb', 'P'=2, 'Q'=2)

This will distribute the PFB file with the distribution assigned to the ``Process.Topology`` 
keys on the ``Run`` object (``LWvdz`` in this example). However, this can be overwritten for 
a particular file, as shown above.

.. _pfb_create:

Creating PFB from Python
-------------------------

Let's copy another test Python script into our tutorial directory:

.. code-block::

    mkdir -p ~/path/pftools_tutorial/pfb_test
    cd ~/path/pftools_tutorial/pfb_test
    cp $PARFLOW_SOURCE/test/python/richards_FBx.py .

This test is a use case where an internal flow boundary is defined as a numpy array, written 
to a PFB file, and distributed for use in the run. You will notice the following 
modules at the top of the file are imported:

.. code-block::

    from parflow import Run
    from parflow.tools.fs import get_absolute_path
    from parflow.tools.io import write_pfb, read_pfb
    import numpy as np

We have already covered the first two in prior tutorials. The third line imports the ``read_pfb`` and
``write_pfb`` functions from the ``parflow.tools.io`` module, and the fourth line imports the ``numpy`` module. 
We convert a numpy array to a PFB file with the ``write_pfb()`` function:

.. code-block:: python3

    # Create numpy array
    FBx_data = np.ones((20, 20, 20))

    # Reduction of 1E-3
    FBx_data[:, :, 9] = 0.001

    # Write flow boundary file as PFB with write_pfb() function
    write_pfb(get_absolute_path('Flow_Barrier_X.pfb'), FBx_data)


This creates a 3D numpy array that covers the entire domain and changes the values in the array 
where X = 10 to 0.001. Note that the numpy array translation to a PFB file reads the dimensions 
as (Z, Y, X). ``write_pfb(get_absolute_path('Flow_Barrier_X.pfb'), FBx_data)`` writes the data 
from the ``FBx_data`` numpy array to a file called ``'Flow_Barrier_X.pfb'``, which will be located in 
the current working directory, and distributes it.

----

Now, try running the file. It should execute successfully. Check out the files you now have in 
your directory - among the other output files is the *'Flow_Barrier_X.pfb'* that you created! 
If you have a PFB reader tool (such as ParaView), you can see what the file looks like: a 
20 x 20 x 20 unit cube with a low-conductivity slice through the middle. Nice!

.. _pfb_load:

Loading PFB from Python
------------------------

Now that we understand how to write a PFB file, how about reading one? This can be useful to do 
inside a Python script so you can visualize or manipulate existing data. Visualizing output data 
within the same script as a run can be very helpful!

----

Let's say you want to visualize some of your output data from the model you just ran, ``richards_FBx.py``. 
In the script, add the following lines to the bottom:

.. code-block:: python3

    FBx_press_out_data = read_pfb(get_absolute_path('richards_FBx.out.press.00010.pfb'))

    print(f'Dimensions of output file: {FBx_press_out_data.shape}')
    print(FBx_press_out_data)

The first line reads the PFB file of the output pressure field at time step = 10 and converts the data to a 
numpy array. The ``print`` statements print the dimensions of the array and the data from the file. Save and 
run this script again to see the printed output. If you're savvy with ``matplotlib`` or other visualization 
packages in Python, feel free to visualize to your heart's content!