PyDiagram
=========

PyDiagram is a python package for generating a phase diagram from results output by polymer field-theoretic simulations. PyDiagram also provides functions for analysis of simulation results.

Quickstart
----------

1. Install
^^^^^^^^^^

::

    $ pip install pydiagram

**Required Packages**

* ``numpy``
* ``scipy``
* ``matplotlib``
* ``mpltex``
* ``attrdict``
* ``PyYAML``

*Important note*: PyYAML cannot be installed by pip or easy_install. Please install it by downloading its source code and use ``python setup.py install`` to install it, see details at `PyYAML Documentation <http://pyyaml.org/wiki/PyYAMLDocumentation#Installation>`_.

2. Use PyDiagram as An Executable
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To use the executable, ``pydiagram``, you need to provide a project configuration file. The configuration file is in YAML format. Three sample configuration files, ``config_polyorder.yml``, ``config_polyfts.yml``, and ``config_pydiagram.yml``, are shipped with PyDiagram package. You can copy one of them to your project root directory and make any necessary modifications to it.

Typical usage.

.. code:: bash

    pydiagram [-v] [-h] [-p] [-q] [-s] [-m]

* ``pydiagram -p``

This command processes the simulation data in the current directory. It will save ``diagram``, ``info_map``, and ``boundary`` objects as Python pickle files. The parser can be specified in the project configuration file using the ``solver`` option.

* ``pydiagram -q``

According to the plot mode specified in the project configuration file, this command will plot requested figures and save them as files.

* ``pydiagram -s``

This command will run pydiagram as a server.

* ``pydiagram -m``

This command will run pydiagram in manual mode, which will submit additional simulation jobs specified in the ``predictor.manual`` in the project configuration file.

3. Use PyDiagram as A Library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can customize your own processing, plotting and predicting scripts by utilizing PyDiagram functions. As described in the last section, your script will also depend on a project configuration file.

Typical usage.

.. code:: python

    import pydiagram
    import matplotlib.pyplot as plt

    # Generate diagram by specifying the folder where data locate.
    # This will require the output data files from supported solvers.
    # Here assume the project configuration file in the current directory.
    diagram = pydiagram.get_diagram()
    # Plot the raw diagram
    fig, ax = plt.subplots(1)
    pydiagram.plot_diagram(ax, diagram)

    # Or you can generate diagram from .dgm file
    # First load .dgm file to get info_map
    xaxis, yaxis, info_map = pydiagram.load_dgm('phase_data.dgm')
    diagram = pydiagram.get_diagram_from_info_map(info_map)

    # You can find phase boundary from digaram
    boundary = pydiagram.get_boundary(diagram, info_map)
    # And plot it as scatter points
    pydiagram.plot_boundary_point(ax, boundary)
    # Or plot it as line
    pydiagram.plot_boundary_line(ax, boundary)

    # PyDiagram also provides a plot function for plotting diagram points
    # and phase boundary together.
    pydiagram.plot_phase_diagram(diagram, boundary, settings, xaxis, yaxis)

    # To analyze the simulation results, PyDiagram also provides
    # a plotting function which will plot F vs. x or F vs. y,
    # a vs. x or a vs. y, and accuracy vs. x or accuracy vs. y.
    pydiagram(info_map, xaxis, yaxis, path, phases, val)

All above mentioned functions have more available options to fine tune the processing and plotting. For more details, please consult the source code or directly contact me via E-mail.

4. dgm File Format
^^^^^^^^^^^^^^^^^^

For non `Polyorder <http://ngpy.org/software/#polyorder>`_ or `PolyFTS <http://polybot.mrl.ucsb.edu/cfdc/polyfts>`_ users, to use PyDiagram you have to generate your own ``dgm`` file from your simulation results by following the ``dgm`` file format.

The format of the ``dgm`` file.

First line::

    [x-axis name] [y-axis name]

Other lines::

    [x] [y] [phase] [F] [a] [accuracy] [separation state]

* ``x-axis name``: the variable name of the x axis in the phase diagram.
* ``y-axis name``: the variable name of the y axis in the phase diagram.
* ``x`` and ``y``: the coordinates in the phase diagram.
* ``phase``: the name of the phase structure.
* ``F``: the Gibbs free energy of the corresponding phase structure.
* ``a``: the stretch-free cell size.
* ``accuracy``: the residual error for the corresponding simulation.
* ``separation state``: Does the simulation yield phase separated structures? 0 for no and 1 for yes.

The first five columns are mandatory while the last two are optional.
The optional values are assumed by their order.
For example, if only 6 columns are provided, then the 6th column is interpreted as ``accuracy``.

Example::

    f   xN
    0.1 12.5    HEX 3.953993    2.9543  8.7e-7  1
    0.1 12.6    LAM 3.970134    2.5877  1.7e-8  1

Links
-----

* `Yi-Xin Liu's academic homepage <http://ngpy.org/software/>`_
