root/trunk/matml/src/ternary/ternary.tex.in

\documentclass{article}
\usepackage{fullpage,lmodern,cxref,url}
\usepackage[T1]{fontenc}
\begin{document}
\title{{\tt Ternary}: Ternary Thermodynamics Visualization}
\author{Adam C. Powell, IV}
\date{Version @VERSION@ released @RELEASE_DATE@}
\maketitle

\begin{abstract}
  {\tt Ternary} is a little code written by Adam Powell back in 2003 to
  visualize ternary free energy functions.  In 2008-2009 he updated it to
  calculate phase diagram isotherms.  Soon it will do a lot more.
\end{abstract}

\tableofcontents
\newpage

\section{Introduction}

In 2003, Adam Powell wrote the core of this little program to visualize the
free energy function of a polymer-solvent-nonsolvent system as used by one of
his grad students.  In 2008-2009, he expanded it considerably:
\begin{itemize}
\item Removed it from the {\tt RheoPlast} package and made it a stand-alone
  program, with considerably expanded documentation.
\item Craig Carter used a convex hull construct to find and illustrate the
  lowest-energy manifold of a binary free energy function or set of
  functions.\footnote{Though others have noted the relationship between the
    convex hull and the minimum enengy surface before ({\em e.g.}
    \cite{Var1990,Aic2001,Aic2003,Zho2004}), Carter's Mathematica scripts are
    the inspiration for this work.}  Based on that concept, ternary uses {\tt
    qhull} \cite{BDH1997} to calculate that hull, and visualizes the edges of the resulting
  triangles---which will clearly show the one- and two-phase regions, complete
  with two-phase tie lines.
\item Added visualization and convex hull calculation for multiple phases with
  separate free energy functions, {\em e.g.} solid and liquid.
\item Made binodal calculation much more accurate by a Newton refining
  procedure at the edges.
\item Added spinodal region boundary calculation.
\item Added a graphical interface for setting the free energy parameters.
\end{itemize}

{\tt Ternary} is nearly complete, with the one un-implemented feature being to
build and neatly visualize how free energy functions create a full
temperature-composition ternary phase diagram.

\section{Compiling {\tt Ternary}}

To compile {\tt Ternary}, you need the qhull library and geomview program, as
well as a C compiler.  On Debian and Ubuntu, installing the {\tt
  build-essential}, {\tt liblapack-dev}, {\tt libqhull-dev} and {\tt geomview}
packages satisfy this.  If you want to build the documentation as well, you
will also need {\tt cxref} along with \LaTeX (in the {\tt texlive-latex-base}
package) for the PDF, and either {\tt hevea} or {\tt latex2html} for HTML
documentation.

Next, unpack the {\tt .tar.gz} source archive by typing (at the command line):
\begin{quote}
  \tt tar xzf Ternary-[version].tar.gz
\end{quote}
Configure and compile it using:
\begin{quote}
  \tt ./configure\\
  make
\end{quote}
Then you can run the {\tt ternary} and {\tt square} binary executables.  Modify
them by changing the parameters at the top of {\tt ternary.c} and {\tt
  square.c} and re-compiling it using {\tt make} again.

\section{How it works}

The files {\tt ternary.c} and {\tt square.c} (documentation in appendices
\ref{file_ternary.c} and \ref{file_square.c}) contain sample front-ends to the
free energy and phase diagram libraries.  They do the following:
\begin{itemize}
\item Call functions in {\tt book.c} (appendix \ref{file_book.c}) to create a
  triangular or square array of points and set of triangles connecting them.
\item Calculate the free energy function on the triangle vertices using
  {\tt free\_energies()} in {\tt freenergy.c} (appendix
  \ref{file_freenergy.c}).  Note that {\tt freenergy.c} is the sole source file
  for {\tt libfreenergy}; {\tt book.c} and the others below comprise {\tt
    libgibbs}.
\item Display the free energy using the functions in {\tt geomview.c}
  (appendix \ref{file_geomview.c}), which forks and controls a Geomview
  process.
\item Calculate the spinodal of this free energy function using {\tt
    calc\_spinodal} in {\tt spinodal.c} (appendix \ref{file_spinodal.c}), and
  displays it on the free energy function.
\item Use Qhull calls in {\tt qhull.c} (appendix \ref{file_qhull.c}) to
  calculate the convex hull of the free energy function.
\item Refine the multi-phase triangles using Newton iteration ({\tt
    hullRefine} in {\tt qhull.c}) to find the lowest-energy point starting at
  each corner, smoothing the phase boundaries considerably.
\item Add the two-phase region facet outlines to the Geomview display.
\end{itemize}

For more than one free energy function (as implemented in {\tt ternary} and
{\tt square}), it creates a double-size (or more) array with multiple sets of
points, and multiple sets of triangle indices connecting them.  The rest of
this procedure is pretty much the same.

The {\tt Ternary} GUI does all of these things as well each time the user
changes the free energy function parameters or otherwise updates the display.

\section{Bugs}

There are several bugs in the Ternary algorithms, an incomplete implementation,
and a problem in the GUI, as follows:

\begin{itemize}
\item Finding some phases depends on the initial discretization of the space.
  For example, if there is a small miscibitily gap which none of the initial
  points happens to be in, it will not show up in the phase diagram isotherm.

\item The refining algorithm does not work well near a critical point.

\item The edge-values test often produces two critical points and a three-phase
  region where there should be just one critical point.

\item Version 0.5.0 is releasing with an incomplete implementation of {\tt
    hullRefine} which is fine for interior points, but does not attempt to
  refine points on the edges, i.e. pseudobinaries.

\item The function {\tt hullReturnPhaseBoundaries} returns more phases than
  appropriate in some cases, with some of them empty.

\item The {\tt Ternary} GUI is incomplete: it is missing the polynomial and
  Gaussian free energy terms, and cannot add or remove phases.
\end{itemize}

\section{Future Goals}

The 1.0 release should have the following features:
\begin{itemize}
\item Fixes for as many of the above bugs as possible.
\item An XML format for the free energy parameters, and ability to load and
  save in this format in {\tt libfreenergy}.
\item Some ability to import and export ThermoCalc\textregistered database
  files.
\item Ability to click the isotherm view lower convex hull triangles to return
  the triangle number and its corners.
\item Function for determining the phases and their fractions for a given
  composition in the lower convex hull isotherm.
\item Assembly of the ternary full phase diagram isotherm traces in a separate
  view.
\item Stitch together ternary isotherm traces to create smooth faces.
\item Change {\tt libfreenergy} and {\tt libgibbs} from $C2,C3$ composition
  representation to an array, creating a multi-component API which will
  support such calculations when the back-end is ready.
\end{itemize}

Other wishlist items include:
\begin{itemize}
\item ``Line compounds'' which consist of a single point, this is already
  possible to do manually but is not in the GUI or either front end.
\item Phases which do not cover the whole ternary space, also possible to do
  manually but it would be nice to have some support in {\tt book.c}.
\end{itemize}

\section{Copyright}

{\tt Ternary} Thermodynamics Visualization

\noindent Copyright \copyright 2003, 2006, 2008, 2009 Adam C. Powell, IV

This code is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 3 of the License, or (at your option) any later
version.

This code is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this code; if not, write to the Free Software Foundation, Inc., 51 Franklin
Street, Fifth Floor Boston, MA 02110-1301 USA

You may contact the author by email at {\tt apowell@opennovation.com}.

\section{Version History}

This is a condensed summary of new user-visible features in {\tt Ternary}.  A
more detailed description of new features in each release is in the {\tt
  ChangeLog} file.

\subsection{{\tt Ternary} 0.1.0}

First standalone release of ternary (extracted from {\tt RheoPlast}), which
plots a ternary free energy function.  New to this release is the use of the
Geomview {\tt COFF} format, which creates a much smoother pseudocolor plot.

\subsection{{\tt Ternary} 0.2.0}

This release links with the {\tt qhull} library to calculate the convex hull of
the energy function, and displays 2- and 3-phase regions in addition to the
free energy function.

\subsection{{\tt Ternary} 0.3.0}

This version introduced multiple free energy functions which intersect to
produce complex multi-phase regions on the convex hull.  Internally, much of
the code in {\tt main()} moved out to a new file {\tt book.c}, which will make
it a lot easier to wrap these functions using SIDL or SWIG.

\subsection{{\tt Ternary} 0.4.0}

The new Newton refining code in {\tt qhull.c}, which uses new free energy
derivative functions in {\tt freenergy.c}, gives {\tt Ternary} the ability to
accurately predict binodal boundaries.  Another new function in {\tt
  spinodal.c} calculates the shape of the spinodal curve.

All functions can now accommodate ``rectangle'' ternary spaces, though it's not
clear what a spinodal means in this context.  The {\tt square} front-end
demonstrates this functionality.

Finally, a major reorganization splits the bulk of the code into two libraries,
with front-end codes {\tt ternary} and {\tt square} calling into them.  The
library {\tt libfreenergy} calculates free energies and derivatives, and can be
re-used in phase field codes.  The library {\tt libgibbs} calculates phase
diagrams.  The APIs are relatively immature and bound to change.

\subsection{{\tt Ternary} 0.5.0}

The {\tt Ternary} GUI has landed, but is not yet complete.

This version fixed major bugs in, and improved the accuracy of, the spinodal
calculation.

There are also new arbitrary polynomial terms in the free energy functions.
And there is a new {\tt adjust\_gaussians} function to aid in the use of
Gaussians for a single-function free energy surface with known free energies of
certain phases.

\bibliographystyle{unsrturl}
\bibliography{ternary}
\newpage

\appendix

% Begin-Of-Source-Files

% End-Of-Source-Files
\end{document}