From 33dc795e1c386463b26d3ed1f3e5110d9faca9eb Mon Sep 17 00:00:00 2001
From: Jaron Kent-Dobias <jaron@kent-dobias.com>
Date: Sat, 20 Oct 2018 14:44:11 -0400
Subject: added references to the c++ library, and fixed a figure label

---
 monte-carlo.tex | 149 +++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 105 insertions(+), 44 deletions(-)

(limited to 'monte-carlo.tex')

diff --git a/monte-carlo.tex b/monte-carlo.tex
index 584dba9..3d6ed8e 100644
--- a/monte-carlo.tex
+++ b/monte-carlo.tex
@@ -4,7 +4,8 @@
 
 \documentclass[aps,pre,reprint]{revtex4-1}
 
-\usepackage{amsmath,amssymb,latexsym,mathtools}
+\usepackage{amsmath,amssymb,latexsym,mathtools,algorithm,listings}
+
 
 % uncomment to label only equations that are referenced in the text
 %\mathtoolsset{showonlyrefs=true}
@@ -42,6 +43,9 @@
   \frac{\partial\tmp#2}{\partial#3\tmp}
 }
 
+% C++, but pretty
+\def\CXX{C\texttt{++}}
+
 \begin{document}
 
 \title{Cluster representations and the Wolff algorithm in arbitrary external fields}
@@ -63,7 +67,8 @@
   that this extension preserves the scaling of accelerated dynamics in the
   absence of a field for Ising, Potts, and $\mathrm O(n)$ models and
   demonstrate the method's use in modelling the presence of novel nonlinear
-  fields.
+  fields. We also provide a \CXX\ library for the method's convenient
+  implementation for arbitrary models. 
 \end{abstract}
 
 \maketitle
@@ -116,6 +121,12 @@ a `ghost' site coupled to all other sites that takes its values from the
 collection of spin symmetry transformations of the base model rather than
 resemble the base spins themselves.
 
+We provide an open-source implementation of this method in the form of a \CXX\
+library, available at \url{https://git.kent-dobias.com/wolff/}
+\cite{kent-dobias_wolff_2018}. Use of this library will be described briefly
+within, but extensive documentation is also available at
+\url{https://doc.kent-dobias.com/wolff/}.
+
 \section{Clusters Without a Field}
 
 We will pose the problem in a general way, but several specific examples can
@@ -174,10 +185,21 @@ redner_graphical_1998}.
     their external fields are also given. Other fields are possible, of course:
     for instance, some are interested in modulated fields $H\cos(2\pi k\theta(s))$ for
     integer $k$ and $\theta(s)$ giving the angle of $s$ to some axis applied
-    to the $\mathrm O(2)$ model \cite{jose_renormalization_1977}.}
+    to the $\mathrm O(2)$ model \cite{jose_renormalization_1977}. All models
+    listed here have example implementations in the provided \CXX\ library
+    \cite{kent-dobias_2018_wolff}.
+  }
   \label{table:models}
 \end{table*}
 
+Implementation of a model in the provided library is as simple as defining a
+class that represents an element of the state space $X$, with default
+constructor (and destructor, if necessary), and a class that represents an
+element of the group $R$, with default constructor and member functions that
+define the action and inverse action of the class on both states and group
+elements. Specific details may be found at
+\url{https://doc.kent-dobias.com/wolff/models.html}.
+
 The goal of statistical mechanics is to compute expectation values of
 observables $A:X^N\to\R$. Assuming the ergodic hypothesis holds (for systems
 with broken-symmetry states, it does not), the expected value $\avg A$ of an
@@ -203,35 +225,48 @@ and obey detailed balance (the ratio of probabilities that $\set{s'}$ follows
 $\set s$ and vice versa is equal to the ratio of weights for $\set s$ and
 $\set{s'}$ in the ensemble).
 
+Measurements of observables during Monte Carlo in the provided library are
+made by the use of hooks, which are member functions of a measurement class
+that are run at designated points during the algorithm's execution and are
+provided arbitrary information about the internal state of all relevant objects.
+A detailed description of these hooks can be found at
+\url{https://doc.kent-dobias.com/wolff/measurement.html}.
+
 While any of several related cluster algorithms can be described for this
 system, we will focus on the Wolff algorithm \cite{wolff_collective_1989}. In
 the absence of an external field, e.g., $B(s)=0$, the Wolff algorithm proceeds
-in the following way.
-\begin{enumerate}
-  \item Pick a random site $m_0$ and add it to the stack.
-
-  \item Select a transformation $r\in R_2$ distributed by $f(r\mid m_0,\set s)$.
-    Often $f$ is taken as uniform on $R_2$, but it is sufficient for preserving
-    detailed balance that $f$ be any function of the seed site $m_0$ and
-    $Z(s,r\cdot s)$ for all $s\in\set s$. The flexibility offered by the
-    choice of distribution will be useful in situations where the set of spin
-    states is infinite.
-  \item While the stack isn't empty,
-    \begin{enumerate}
-      \item pop site $m$ from the stack.
-      \item If site $m$ isn't marked, 
-        \begin{enumerate}
-          \item mark the site.
-          \item For every $j$ such that $\{m,j\}\in E$, add site $j$ to the
-            stack with probability
-            \[
-              p_r(s_m,s_j)=\min\{0,1-e^{\beta(\J(r\cdot s_m,s_j)-\J(s_m,s_j))}\}.
-              \label{eq:bond_probability}
-            \]
-          \item Take $s_m\mapsto r\cdot s_m$.
+in the following way.\\
+
+\begin{algorithm}[H]
+  \begin{enumerate}
+    \item Pick a random site $m_0$ and add it to the stack.
+
+    \item Select a transformation $r\in R_2$ distributed by $f(r\mid m_0,\set s)$.
+      Often $f$ is taken as uniform on $R_2$, but it is sufficient for preserving
+      detailed balance that $f$ be any function of the seed site $m_0$ and
+      $Z(s,r\cdot s)$ for all $s\in\set s$. The flexibility offered by the
+      choice of distribution will be useful in situations where the set of spin
+      states is infinite.
+    \item While the stack isn't empty,
+      \begin{enumerate}
+        \item pop site $m$ from the stack.
+        \item If site $m$ isn't marked, 
+          \begin{enumerate}
+            \item mark the site.
+            \item For every $j$ such that $\{m,j\}\in E$, add site $j$ to the
+              stack with probability
+              \[
+                p_r(s_m,s_j)=\min\{0,1-e^{\beta(\J(r\cdot s_m,s_j)-\J(s_m,s_j))}\}.
+                \label{eq:bond_probability}
+              \]
+            \item Take $s_m\mapsto r\cdot s_m$.
+        \end{enumerate}
       \end{enumerate}
-    \end{enumerate}
-\end{enumerate}
+  \end{enumerate}
+  \caption{Wolff}
+  \label{alg:wolff}
+\end{algorithm}
+
 When the stack is exhausted, a cluster of connected spins will have been
 transformed by the action of $r$. In order for this algorithm to be useful, it
 must satisfy ergodicity and detailed balance. Ergodicity is satisfied since we
@@ -266,6 +301,17 @@ of this dependence for a class of configuration spaces with continuous
 symmetry groups can be found in \cite{caracciolo_generalized_1991,
 caracciolo_wolff-type_1993}.
 
+This algorithm can be run on a system using the provided library. To construct
+a system, you must provide a graph representing the lattice, a temperature,
+the spin coupling function $Z$, and the field coupling function $B$. Once
+constructed, cluster flips as described in Alg.~\ref{alg:wolff} can be
+performed by directly providing seed sites $m_0$ and transformations $r$, or
+many in sequence by providing a function that generates random (appropriately
+distributed to preserve detailed balance) transformations $r$. The
+construction and use of Wolff systems is described at
+\url{https://doc.kent-dobias.com/wolff/system.html}.
+
+
 \section{Adding the field}
 
 This algorithm relies on the fact that the coupling $\J$ depends only on
@@ -379,12 +425,11 @@ are preserved, including correlators with the ghost site
 exists, we expect this representation to extend it to finite field, all other
 features of the algorithm held constant. For instance, the average cluster
 size in the Wolff algorithm is often said to be an estimator for the magnetic
-susceptibility in the Ising and Potts models (average sum over $x$-components
-in the cluster for the $\mathrm O(n)$), but really what it estimates is the
-averaged squared magnetization, which corresponds to the susceptibility when
-the average magnetization is zero. At finite field the latter thing is no
-longer true, but the correspondence between cluster size (sum of
-$x$-components) and the squared magnetization continues to hold (see
+susceptibility in the Ising, Potts, and $\mathrm O(n)$ models, but really what
+it estimates is the averaged squared magnetization, which corresponds to the
+susceptibility when the average magnetization is zero. At finite field the
+latter thing is no longer true, but the correspondence between cluster size
+and the squared magnetization continues to hold (see
 \eqref{eq:cluster-size-scaling} and Fig.~\ref{fig:cluster_scaling} below).
 
 \section{Examples}
@@ -407,8 +452,8 @@ of the Hamiltonian have been applied by several researchers
 \cite{alexandrowicz_swendsen-wang_1989, wang_clusters_1989,
 ray_metastability_1990}. The algorithm has been implemented by one of the
 authors in an existing interactive Ising simulator at
-\texttt{https://mattbierbaum.github.io/ising.js}
-\cite{bierbaum_ising.js_nodate}.
+\url{https://mattbierbaum.github.io/ising.js}
+\cite{bierbaum_ising.js_2016}.
 
 \subsection{The XY and other $\mathrm O(n)$ models}
 \label{sec:examples:on}
@@ -436,7 +481,8 @@ neighboring spins. Under these conditions, most choices of reflection plane
 will cause a change in energy so great that the whole system is always
 flipped, resulting in many correlated samples. To ameliorate this, one can
 draw reflections from a distribution that depends on how the seed spin is
-transformed. We implement this in the following way. Say that the state of the
+transformed, taking advantage of the freedom to choose the function $f$ in
+Alg.~\ref{alg:wolff}. We implement this in the following way. Say that the state of the
 seed of the cluster is $s$. Generate a vector $t$ taken uniformly from the
 space of unit vectors orthogonal to $s$. Let the plane of reflection be that
 whose normal is $n=s+\zeta t$, where $\zeta$ is drawn from a normal
@@ -723,11 +769,12 @@ problem before now.
 We have taken several disparate extensions of cluster methods to spin models
 in an external field and generalized them to work for any model of a broad
 class.  The resulting representation involves the introduction of not a ghost
-spin, but a ghost transformation. We provided evidence that algorithmic
-extensions deriving from this method are the natural way to extend cluster
-methods in the presence of a field, in the sense that they appear to reproduce
-the scaling of dynamic properties in a field that would be expected from
-renormalization group predictions.
+spin, but a ghost transformation. We provide a \CXX\ library with example
+implementations of all models described here \cite{kent-dobias_wolff_2018}. We
+provided evidence that algorithmic extensions deriving from this method are
+the natural way to extend cluster methods in the presence of a field, in the
+sense that they appear to reproduce the scaling of dynamic properties in a
+field that would be expected from renormalization group predictions.
 
 In addition to uniting several extensions of cluster methods under a single
 description, our approach allows the application of fields not possible under
@@ -738,13 +785,27 @@ perturbations on spin models can be tested numerically
 \cite{jose_renormalization_1977, blankschtein_fluctuation-induced_1982,
 bruce_coupled_1975, manuel_carmona_$n$-component_2000}.
 
-
 \begin{acknowledgments}
   This work was supported by NSF grant NSF DMR-1719490.
 \end{acknowledgments}
 
-\bibliography{monte-carlo}
+\appendix
 
+\section{Example Ising Implementation}
+
+Provided below is an example implementation of the Ising model using the
+provided \CXX\ library. The example is also included with the library source,
+along with several other more complicated ones \cite{kent-dobias_wolff_2018}.
+The routine defines an Ising class that acts as both spin and symmetry group
+and a measurement class that provides simple hooks for computing the average
+cluster size. The canonical Ising couplings are defined, a square lattice is
+initialized, the Wolff system is initialized, and the algorithm is run for a
+designated number of cluster flips.
+
+\lstset{language=C++, basicstyle=\footnotesize, frame=single}
+\lstinputlisting[breaklines]{ising_standalone.cpp}
+
+\bibliography{monte-carlo}
 
 \end{document}
 
-- 
cgit v1.2.3-70-g09d2

