big library overhual, fixed all examples, added documentation with sphinx

10 files changed, 575 insertions, 0 deletions

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..298ea9e
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
diff --git a/doc/compile.rst b/doc/compile.rst
new file mode 100644
index 0000000..2a3b4a2
--- /dev/null
+++ b/doc/compile.rst
@@ -0,0 +1,51 @@
+
+.. _compile:
+
+***************
+Compile Options
+***************
+
+There are several features that are not active by default, but can be used by defining a compiler flag. These will modify the constructor of :cpp:class:`system`. These can be used in concert when applicable. Note that at the moment, there is no :ref:`finite_states` support for systems with bond or site dependence.
+
+Building Without A Field
+========================
+
+.. c:macro:: WOLFF_NO_FIELD
+
+When this flag is defined Wolff will not use a field. When a field isn't necessary, this will improve performance: no ghost site will be initialize and no time will be wasted checking the energy change with respect to a uncoupled ghost site. 
+
+When defined, the constructor for :cpp:class:`system` becomes
+
+.. cpp:namespace:: cflags
+
+.. cpp:function:: system(graph, double, std::function <double(const X_t&, const X_t&)>)
+
+The resulting :cpp:class:`system` object does not have member objects :cpp:member:`B` or :cpp:member:`s0`, and :cpp:member:`system::G` does not have a ghost site initialized.
+
+Building With Bond Dependence
+=============================
+
+.. c:macro:: WOLFF_BOND_DEPENDENCE
+
+When this flag is defined Wolff will ask for the indices of the spins on each side a bond, allowing the implementation of random bonds or anisotropic interactions.
+
+When defined, the bond coupling must be a function of the form
+
+.. cpp:function:: double Z(v_t, const X_t&, v_t, const X_t&)
+
+where the first argument is the index of the first spin and the third argument is the index of the second spin. A function of this type is passed to :cpp:class:`system` in place of the original bond coupling.
+
+
+Building With Site Dependence
+=============================
+
+.. c:macro:: WOLFF_SITE_DEPENDENCE
+
+When this flag is defined Wolff will ask for the indices of the spin when measuring the external field, allowing the implementation of random fields or to emulate boundaries.
+
+When defined, the field coupling must be a function of the form
+
+.. cpp:function:: double B(v_t, const X_t&)
+
+where the first argument is the index of the spin. A function of this type is passed to :cpp:class:`system` in place of the original field coupling.
+
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..112d4b7
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,177 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'wolff'
+copyright = '2018, Jaron Kent-Dobias'
+author = 'Jaron Kent-Dobias'
+
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = ''
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.mathjax',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'wolffdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'wolff.tex', 'wolff Documentation',
+     'Jaron Kent-Dobias', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'wolff', 'wolff Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'wolff', 'wolff Documentation',
+     author, 'wolff', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+
+# -- Extension configuration -------------------------------------------------
\ No newline at end of file
diff --git a/doc/finite_states.rst b/doc/finite_states.rst
new file mode 100644
index 0000000..5d1fce8
--- /dev/null
+++ b/doc/finite_states.rst
@@ -0,0 +1,24 @@
+
+.. _finite_states:
+
+*************
+Finite States
+*************
+
+One of the slower steps in running the algorithm is taking the exponent involved in computing the bond activation probabilities for each prospective bond. When the spins in your system have a finite number of possible states, the algorithm can be sped up considerably by precomputing the bond activation probabilities for every possible combination pair spins. Once the appropriate things have been defined for your model, the header :file:`wolff/finite_states.hpp` can be invoked to automate this process. The provided model headers :file:`wolff/models/ising.hpp` and :file:`wolff/models/potts.hpp` demonstrate the expected usage.
+
+Required Definitions
+====================
+
+.. c:macro:: WOLFF_FINITE_STATES_N
+
+This macro must be defined and given a value equal to the number of states your model can take.
+
+.. cpp:var:: const X_t finite_states_possible[WOLFF_FINITE_STATES_N]
+
+You must supply a constant array which lists each of the possible states of your individual spins. 
+
+.. cpp:function:: q_t finite_states_enum(const X_t&)
+
+You must define a function which takes each state and returns its index in :cpp:var:`finite_states_possible`.
+
diff --git a/doc/graph.rst b/doc/graph.rst
new file mode 100644
index 0000000..e44a14f
--- /dev/null
+++ b/doc/graph.rst
@@ -0,0 +1,47 @@
+
+******
+Graphs
+******
+
+This class is defined in the header :file:`wolff/graph.hpp`.
+
+.. cpp:class:: graph
+
+   Lattices are described by objects of class :cpp:class:`graph`, a minimal implementation of graphs.
+
+.. cpp:member:: D_t graph::D
+
+   The dimension of the graph. This property is unused by the core library.
+
+.. cpp:member:: L_t graph::L
+
+   The linear size of the graph. This property is unused by the core library.
+
+.. cpp:member:: v_t graph::ne
+
+   The number of edges in the graph. This property is unused by the core library.
+
+.. cpp:member:: v_t graph::nv
+
+   The number of vertices in the graph.
+
+.. cpp:member:: std::vector<std::vector<v_t>> graph::adjacency
+
+   The adjacency list for the graph. The :math:`i\text{th}` element of :cpp:member:`adjacency` is a standard library vector containing the indices of all vertices adjacent to vertex :math:`i`.
+
+.. cpp:member:: std::vector<std::vector<double>> graph::coordinate
+
+   The coordinates of the graph vertices. The :math:`i\text{th}` element of :cpp:var:`coordinate` is a standard library vector of length :cpp:var:`D` containing the spatial coordinates of vertex :math:`i`. This property is unused by the core library.
+
+.. cpp:function:: graph::graph()
+
+   The default constructor. Initializes an empty graph, i.e., :cpp:var:`D`, :cpp:var:`L`, :cpp:var:`ne`, and :cpp:var:`nv` are all zero and :cpp:var:`adjacency` and :cpp:var:`coordinate` are uninitialized.
+
+.. cpp:function:: graph::graph(D_t D, L_t L)
+
+   Calling the constructor with :cpp:var:`D` and :cpp:var:`L` will initialize the graph of a :cpp:var:`D`-dimensional hypercubic lattice with :cpp:var:`L` vertices per side. This is the only nontrivial graph constructor supplied by the core library.
+
+.. cpp:function:: void graph::add_ghost()
+
+   Calling this function on a graph object will add a ghost site to the graph. Explicitly, a new vertex is added that is adjacent to every other vertex in the graph. This vertex will have the last index, which is equal to number of vertices in the original graph.
+
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..4e58e46
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,15 @@
+
+Wolff Libraries
++++++++++++++++
+
+.. toctree ::
+   :maxdepth: 2
+   
+   models
+   system
+   measurement
+   graph
+   types
+   finite_states
+   compile
+
diff --git a/doc/measurement.rst b/doc/measurement.rst
new file mode 100644
index 0000000..e71010d
--- /dev/null
+++ b/doc/measurement.rst
@@ -0,0 +1,84 @@
+
+************
+Measurements
+************
+
+One of the most complicated parts of using this library is setting up measurements to take during a run, but once understood they provide a powerful way to quickly measure arbitrary properties. The class is defined in the header :file:`wolff/measurement.hpp`.
+
+.. cpp:class:: template\<class R_t, class X_t> measurement
+
+   This class defines several virtual member functions. To use the library, you must supply your own measurement class that inherits this one and defines those functions, which may be trivial.
+
+   Each member function defines a hook that is run at a specific time during execution. These hooks can be used to modify member objects of your inheritor measurement class, and thereby extract information from the simulation.
+
+.. cpp:function:: template<void measurement::pre_cluster(N_t n, N_t N, const system<R_t, X_t>& S, v_t i0, const R_t& r)
+
+   This hook is run prior to cluster formation. The arguments supplied are:
+
+   =========================== ===
+   :cpp:var:`n`                the number of clusters already flipped
+   :cpp:var:`N`                the total number of clusters to flip
+   :cpp:var:`S`                the current system state
+   :cpp:var:`i0`               the index of the seed vertex for the cluster
+   :cpp:var:`r`                the transformation by which the cluster will be flipped
+   =========================== ===
+
+.. cpp:function:: void measurement::plain_bond_visited(const system<R_t, X_t>& S, v_t i1, const X_t& s1_new, v_t i2, double dE)
+
+   This hook is run when an ordinary edge is visited during cluster formation, whether it is activated or not. The arguments supplied are:
+
+   ================================= ===
+   :code:`const system<R_t, X_t>& S` the current system state
+   :code:`v_t i1`                    the index of the vertex soon to be flipped
+   :code:`const X_t& s1_new`         the state vertex :cpp:var:`i1` will be flipped to
+   :code:`v_t i2`                    the other vertex sharing the edge
+   :code:`double dE`                 the change in energy that will result when the spin at site :cpp:var:`i1` is flipped
+   ================================= ===
+
+.. cpp:function:: void measurement::plain_site_transformed(const system<R_t, X_t>& S, v_t i, const X_t& si_new)
+
+   This hook is run when an ordinary site is about to be flipped. The arguments supplied are:
+
+   ================================= ===
+   :code:`const system<R_t, X_t>& S` the current system state
+   :code:`v_t i`                     the index of the vertex soon to be flipped
+   :code:`const X_t& si_new`         the state vertex :cpp:var:`i` will be flipped to
+   ================================= ===
+
+|
+
+.. cpp:function:: void measurement::ghost_bond_visited(const system<R_t, X_t>& S, v_t i, const X_t& s0si_old, const X_t& s0si_new, double dE)
+
+   This hook is run when an edge containing the ghost site is visited during cluster formation, whether activated or not. The arguments supplied are:
+
+   ================================= ===
+   :code:`const system<R_t, X_t>& S` the current system state
+   :code:`v_t i`                     the index of the non-ghost site in this edge
+   :code:`const X_t& s0si_old`       the state that the spin on the non-ghost site has before the transformation is applied, rotated by the inverse action of the ghost site
+   :code:`const X_t& s0si_new`       the state that the spin on the non-ghost site will have after the transformation is applied, rotated by the inverse action of the ghost site
+   :code:`double dE`                 the change in energy that will result when one site is transformed
+   ================================= ===
+
+|
+
+.. cpp:function:: void measurement::ghost_site_transformed(const system<R_t, X_t>& S, const R_t& R_new)
+
+   This hook is run when the ghost site is about to be flipped. The arguments supplied are:
+
+   ================================= ===
+   :code:`const system<R_t, X_t>& S` the current system state
+   :code:`const R_t& R_new`          the state the ghost site will be flipped to
+   ================================= ===
+
+|
+
+.. cpp:function:: void measurement::post_cluster(N_t n, N_t N, const system<R_t, X_t>& S) 
+
+   This hook is run after a cluster has been flipped. The arguments supplied are:
+
+   ================================= ===
+   :code:`N_t n`                     the number of clusters already flipped
+   :code:`N_t N`                     the total number of clusters to flip
+   :code:`const system<R_t, X_t>& S` the current system state
+   ================================= ===
+
diff --git a/doc/models.rst b/doc/models.rst
new file mode 100644
index 0000000..aa80ee6
--- /dev/null
+++ b/doc/models.rst
@@ -0,0 +1,61 @@
+
+****************
+Defining a Model
+****************
+
+To define your own model, you need a class for spin states, a class for spin transformations, a bond and site coupling, and a generator of transformations.
+
+Spin States
+===========
+
+.. cpp:class:: X_t
+
+   The spin type, which we have been denoting with :cpp:class:`X_t`, only needs to have a default constructor. If your spins can take only finitely many values, consider following the instructions in :ref:`finite_states` to significantly speed the algorithm.
+
+Transformations
+===============
+
+.. cpp:class:: R_t
+
+   The transformation type must have a default constructor, and the following member functions:
+
+   .. cpp:function:: X_t act(const X_t&)
+
+      The action of the transformation on a spin, returning the transformed spin.
+
+   .. cpp:function:: R_t act(const R_t&)
+
+      The action of the transformation on another transformation, returning the transformed transformation.
+
+   .. cpp:function:: X_t act_inverse(const X_t&)
+
+      The action of the inverse transformation on a spin, returning the transformed spin.
+
+   .. cpp:function:: R_t act_inverse(const R_t&)
+
+      The action of the inverse transformation on another transformation, returning the transformed transformation.
+
+Couplings
+=========
+
+When a :cpp:class:`system` object is initialized it needs to be given a bond and field coupling, to resemble the Hamiltonian
+
+.. math::
+         \mathcal H = -\sum_{\langle ij\rangle}Z(s_i,s_j)-\sum_iB(s_i)
+
+Note that building with certain compile flags will change the form that these coupling functions must take, as outlined in :ref:`compile`.
+
+Bond Coupling
+-------------
+
+.. cpp:function:: double Z(const X_t&, const X_t&)
+
+   A function that takes two spins and outputs the coupling between them. For traditional spin models, this is typically something like a dot product.
+
+Field Coupling
+--------------
+
+.. cpp:function:: double B(const X_t&)
+
+   A function that takes one spin and outputs the coupling between it and an external field.
+
diff --git a/doc/system.rst b/doc/system.rst
new file mode 100644
index 0000000..1751e2b
--- /dev/null
+++ b/doc/system.rst
@@ -0,0 +1,61 @@
+
+*************************************
+Constructing a System & Running Wolff
+*************************************
+
+The core of the library lies in the :cpp:class:`system` class and its member functions. Here, the state of your model is stored and cluster flip Monte Carlo can be carried out in various ways.
+
+Note that the member objects and functions described here will change when compiled with certain compiler flags active, as described in :ref:`compile`.
+
+.. cpp:class:: template\<class R_t, class X_t> system
+
+Member Objects
+==============
+
+.. cpp:member:: v_t system::nv
+
+   Stores the number of ordinary sites in the model.
+
+.. cpp:member:: v_t system::ne
+
+   Stores the number of ordinary bonds in the model.
+
+.. cpp:member:: graph system::G
+
+   Stores the graph describing the lattice, including the ghost site.
+
+.. cpp:member:: double system::T
+
+   Stores the temperature of the model.
+
+.. cpp:member:: std::vector<X_t> system::s
+
+   The :math:`i\text{th}` component stores the spin state of site :math:`i`.
+
+.. cpp:member:: R_t system::s0
+
+   Stores the state of the ghost site.
+
+.. cpp:member:: std::function <double(const X_t&, const X_t&)> system::Z
+
+   The function that returns the coupling between neighboring sites.
+
+.. cpp:member:: std::function <double(const X_t&)> system::B
+
+   The function that returns the coupling to the field.
+
+Member Functions
+================
+
+.. cpp:function:: system::system(graph G, double T, std::function <double(const X_t&, const X_t&)> Z, std::function <double(const X_t&)> B)
+
+   The constructor for systems. The arguments given are a graph :cpp:any:`G` *without* the ghost spin added, the temperature :cpp:any:`T`, and the coupling functions :cpp:any:`Z` and :cpp:any:`B`. The states of the spins and ghost site are initialized using the default constructors for :cpp:type:`X_t` and :cpp:type:`R_t`, respectively. :cpp:any:`nv` and :cpp:any:`ne` are taken directly from :cpp:any:`G`, after which the ghost site is added to :cpp:any:`G`.
+
+.. cpp:function:: system::flip_cluster(v_t i0, const R_t& r, std::mt19937& rng, measurement<R_t, X_t>& A)
+
+   Performs one Wolff cluster flip to the system. The cluster is seeded at vertex :cpp:any:`i0` and the spins added are transformed by :cpp:any:`r`. A random number generator :cpp:any:`rng` provides required random numbers during, and the relevant measurement hooks defined in the inherited class of :cpp:any:`A` are run during the cluster formation.
+
+.. cpp:function:: system::run_wolff(N_t N, std::function <R_t(std::mt19937&, const system<R_t, X_t>&, v_t)> r_gen, measurement<R_t, X_t>& A, std::mt19937& rng)
+
+   Performs :cpp:any:`N` Wolff cluster flips to the system. One must provide a function :cpp:func:`r_gen` that takes a random number generator, the system state, and the index of the seed site and returns a transformation for each flip. Also required are an object from a class which inherits :cpp:class:`measurement` to run measurements, and a random number generator :cpp:any:`rng`.
+
diff --git a/doc/types.rst b/doc/types.rst
new file mode 100644
index 0000000..b729ac3
--- /dev/null
+++ b/doc/types.rst
@@ -0,0 +1,36 @@
+
+************
+Custom Types
+************
+
+The Wolff library uses several custom types, defined to promote memory and cache effiency, promote shorter lines, and associate natural scope to certain parameters. They are all aliases for `standard C99 fixed width integer types`_. These are defined in the header file :file:`wolff/types.h`. Here is a list of the types and what they are used to hold:
+
+.. cpp:type:: uint_fast32_t v_t
+
+   Holds indicies for lattice vertices and edges.
+
+.. cpp:type:: uint_fast8_t q_t
+
+   Holds indicies for enumerating states, as in :math:`q`-state Potts.
+
+.. cpp:type:: uint_fast8_t D_t
+
+   Holds the dimension of space.
+
+.. cpp:type:: uint_fast16_t L_t
+
+   Holds the linear extent of the lattice.
+
+.. cpp:type:: uint_fast64_t N_t
+
+   Holds a count of Monte Carlo steps.
+
+Other Definitions
+=================
+
+All types are unsigned integers of a minimum size appropriate for most realistic purposes, with the :c:type:`fast` directives meaning that your compiler may choose a larger type for efficiency's sake.
+
+For each type :c:type:`x_t`, the macro :c:macro:`MAX_x` supplies the maximum value the type may hold, the macro :c:macro:`PRIx` supplies the format constants for use with the :c:func:`fprintf` family of functions, and the macro :c:macro:`SCNx` supplies the format constants for use with the :c:func:`fscanf` family of functions.
+
+.. _standard C99 fixed width integer types: https://en.cppreference.com/w/c/types/integer
+