Visualizing field files
=======================

OpenFTS field files can be visualized a few different ways by using the 
``fieldkit`` library located `here <https://github.com/LequieuLab/fieldkit>`_.
In this tutorial, we will visualize density field files using each method 
available. To begin enter a directory containing OpenFTS and your field file, 
which in this tutorial will be named ``density.dat`` and correspond to a gyroid
phase.

With matplotlib.pyplot
----------------------

This is the best method for quickly visualizing field files. To do so, we run
the following in python:

.. code-block:: python

   import fieldkit as fk
   density_fields = fk.read_from_file('density.dat')
   fk.plot(fields=density_fields, show=True)

.. image:: matplotlib.png
   :alt: matplotlib.pyplot example

For common operations like these, ``fieldkit`` has standalone scripts that can
be executed from the command line to accomplish the same task.

.. code-block:: bash

   $ OpenFTS/extern/fieldkit/tools/fk_plot.py density.dat

With visual molecular dynamics (VMD)
------------------------------------

For more control over your visualizations you can use
`VMD <https://www.ks.uiuc.edu/Research/vmd/>`_. We first use ``fieldkit`` to 
convert the field file to the 
`cube <https://paulbourke.net/dataformats/cube/>`_ file format.

.. code-block:: python

   import fieldkit as fk
   density_fields = fk.read_from_file('density.dat')
   fk.write_to_cube_files(prefix='density', fields=density_fields)

Alternatively we can run the following from the command line:

.. code-block:: bash

   $ OpenFTS/extern/fieldkit/tools/fk_convert_to_cube.py density.dat

This generates a cube file per field in the field file. Let's now visualize 
the first field.

.. code-block:: bash

   $ vmd density_field0.cube

``fieldkit`` labels each voxel as an atom in the cube file in addition to 
converting the field data to volumetric data. We can therefore either 
visualize the voxels themselves:

.. code-block:: bash

   vmd > mol rep Points 20
   vmd > mol color Charge
   vmd > mol addrep 0

.. image:: vmd1.png
   :alt: VMD example 1

Or visualize the volumetric data by computing isosurfaces, where here we set 
the isovalue to 0.75.

.. code-block:: bash

   vmd > mol rep Isosurface 0.75 0 3 1 1 1
   vmd > mol color ColorID 16
   vmd > mol addrep 0

.. image:: vmd2.png
   :alt: VMD example 2

With paraview
-------------

For the greatest control over your visualizations you can use
`paraview <https://www.paraview.org/>`_. First we use ``fieldkit`` to convert
the field file to a VTK file.

.. code-block:: python

   import fieldkit as fk
   density_fields = fk.read_from_file('density.dat')
   fk.write_to_VTK(filename='density.vtk', fields=density_fields)

We can also alternatively do so from the command line.

.. code-block:: bash

   $ OpenFTS/extern/fieldkit/tools/fk_convert_to_vtk.py density.dat

This generates ``density.vtk`` which we can visualize with paraview.

.. code-block:: bash

   $ paraview density.vtk

Like VMD, paraview can also compute isosurfaces as well as other sophisticated
visualizations. To compute the same isosurface as we did in VMD, first we must
apply the ``density.vtk`` file.

.. image:: paraview1.png
   :alt: paraview example 1

Next we have to configure the isosurface and make the axes visible.

.. image:: paraview2.png
   :alt: paraview example 2

And now we have a visualization of the gyroid phase. Something to keep in mind:
as your total number of plane waves increase for your ``fts`` object, 
interacting with the visualization can become slow. For high numbers of plane
waves, we find that paraview gives the best performance.

.. image:: paraview3.png
   :alt: paraview example 3