Analyze the results
======================

Once you've run OpenFTS you'll probably want to do something with your results. Here we'll assume that you've used run the same input file as described in :ref:`OpenFTS as a python module`. If you'd like to change the names of the output files, see :ref:`Output`.

Instantaneous species densities
--------------------------------

One of the primary outputs of a OpenFTS simulation is the density field generated by each species in the simulation. By default, this information is written to a file named `density.dat`. This file is known as a *field file*. The preferred way to interact and manipulate these types of files is with a python module called `fieldkit`. `fieldkit` provides a wide range of functionality for reading, writing, analyzing and vizualizing field files. For using these features see the `fieldkit` documentation (TODO: add link!).

In short, convert to a VTK and then visualize with `paraview`::

    <path>/OpenFTS/extern/fieldkit/tools/fk_convert_to_vtk.py density.dat
    paraview density.vtk


This file is written (and overwritten) at every output step during a run. If you would like to save the densities at each output step separately, you can set `save_history=True` as specified in :ref:`Output`.

.. note::

  If you would like the density of each molecule instead of the density of each species you can use the `DensityMolecule` operator. (TODO: link to this documentation)
 

Instantaneous field configurations
------------------------------------

The degree of freedom in OpenFTS simulations are the auxilary fields :math:`w_\pm(\pmb{r})`.These are written to `fields.dat`. This is also a *field file* which can be read/manipulated using `fieldkit`. The ordering depends on the `model` being simulated.

This file is written (and overwritten) by every output step. If you would like to save the fields at each output step separately, you can set `save_history=True` as specified in :ref:`Output`.


Scalar operator files
------------------------

Any scalar operators that are specified in the input file are written to `operators.dat`. The format of this file is as follows (if the `Hamiltonian` and `CellStress` operators have been enabled): ::

  # step stress[0] h[0][0] H.real H.imag 
  1 -0.04695940 4.26311000 0.14389384 0.00000000 
  100 -0.01445410 4.18341314 50.34940822 0.00000000 
  200 -0.00511614 4.18975459 54.07533994 0.00000000
  ...

Each row of the file corresponds to a different timestep and each column corresponds to a separate operator. In this example `stress[0]` and `h[0][0]` give the stress and the cell tensor, while `H.real` and `H.imag` give the real and imaginary components of the Hamiltonian.

There are numerous ways that `operators.dat` can be analyzed and plotted by other programs. If you are going to use Python for your analysis, `operators.dat` can be easily read usingthe `openfts` Python module.  ::

    import openfts
    fts = fts = openfts.OpenFTS()
    ... initialize and run fts object ... 
    
    # now load operators
    ops = openfts.get_scalar_operators(fts,mode='timeseries') # fts object given as argument
    ops = openfts.get_scalar_operators('operators.dat',mode='timeseries') # filename as argument
    ... analyze/plot the returned ops dictionary ...

Additional usage of the `openfts.get_scalar_operators` function is documented in :ref:`Python Module API`.

Field operator files
------------------------

Certain operators like `DensityMolecule` or `DensitySpecies` return their values as a *field file*. These operators write their results to files named `opFIELDNAME.dat` where `FIELDNAME` is replaced by the specific name of that operator (e.g. a `opDensityMolecule.dat` file is written if the `DensityMolecule` operator is enabled. These files can be read using `fieldkit` (TODO: add link!).

These files are written (and overwritten) every output step. To save these operators at every output step, set `save_history=True`.


Field errors
---------------

Another useful output from a simulation if you are running SCFT is how close the current fields have converged to a saddle point. This is quantified by field errors for spefified model (e.g. :math:`|\frac{\delta H}{\delta \mu_+}|_{L1}`, :math:`|\frac{\delta H}{\delta \mu_-}|_{L1}`). 
These errors are written to `errors.dat`.

Run Status
-----------

One additional file that is output (which cannot be currently customized) is **STATUS**, the status of the current driver->run() command. Possible values are:

    * 0 - the simulation is still running
    * 1 - the forces in the simulation look fishy, may have diverged
    * 2 - the SCFT converged correctly to the specified tolerance
    * 3 - the run command reached the maximum number of specified steps