diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/compile.rst | 5 | ||||
| -rw-r--r-- | doc/finite_states.rst | 2 | ||||
| -rw-r--r-- | doc/graph.rst | 63 | ||||
| -rw-r--r-- | doc/index.rst | 1 | ||||
| -rw-r--r-- | doc/measurement.rst | 51 | ||||
| -rw-r--r-- | doc/models.rst | 2 | ||||
| -rw-r--r-- | doc/system.rst | 30 | ||||
| -rw-r--r-- | doc/types.rst | 36 |
8 files changed, 93 insertions, 97 deletions
diff --git a/doc/compile.rst b/doc/compile.rst index e4960a3..d335dff 100644 --- a/doc/compile.rst +++ b/doc/compile.rst @@ -23,7 +23,7 @@ Building With 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:any:`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. + When defined, the bond coupling must be a function of the form :cpp:any:`double Z(const G_t::halfedge&, const X_t&, const X_t&)`, where the first argument is the edge being considered. A function of this type is passed to :cpp:class:`system` in place of the original bond coupling. Building With Site Dependence @@ -33,5 +33,6 @@ Building With 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:any:`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. + When defined, the field coupling must be a function of the form :cpp:any:`double B(const G_t::vertex&, const X_t&)`, where the first argument is the vertex the spin is on. A function of this type is passed to :cpp:class:`system` in place of the original field coupling. + An example of a system of this type can be found in :file:`examples/ising_random_field.cpp`, which uses a non-trivial vertex property to communicate vertex dependence to the field coupling function. diff --git a/doc/finite_states.rst b/doc/finite_states.rst index c36881e..66e34d2 100644 --- a/doc/finite_states.rst +++ b/doc/finite_states.rst @@ -5,7 +5,7 @@ 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 pair of spins. Once the appropriate things have been defined for your model, the compile definition :c:macro:`WOLFF_USE_FINITE_STATES` can be set to automate this process. The provided model headers :file:`wolff/models/ising.hpp` and :file:`wolff/models/potts.hpp` demonstrate the expected usage. +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 pair of spins. Once the appropriate things have been defined for your model, the compile definition :c:macro:`WOLFF_USE_FINITE_STATES` can be set 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 ==================== diff --git a/doc/graph.rst b/doc/graph.rst index 8a96e50..dfe684c 100644 --- a/doc/graph.rst +++ b/doc/graph.rst @@ -1,50 +1,83 @@ .. default-domain:: cpp +.. _graphs: ****** Graphs ****** -This class is defined in the header :file:`wolff/graph.hpp`. +This class is defined in the header :file:`lib/wolff.hpp`. -.. class:: graph +.. class:: \template <class vertex_prop = std::tuple\<>, class edge_prop = std::tuple\<>> graph - Lattices are described by objects of class :class:`graph`, a minimal implementation of graphs. + Lattices are described by objects of class :class:`graph`, a minimal implementation of graphs. Can be called with `graph<>` if no properties need to be associated with vertices or edges. Otherwise, those properties can be supplied as classes. - .. member:: D_t graph::D + .. member:: unsigned graph::D The dimension of the graph. This property is unused by the core library. - .. member:: L_t graph::L + .. member:: unsigned graph::L The linear size of the graph. This property is unused by the core library. - .. member:: v_t graph::ne + .. member:: unsigned graph::ne The number of edges in the graph. This property is unused by the core library. - .. member:: v_t graph::nv + .. member:: unsigned graph::nv The number of vertices in the graph. - .. member:: std::vector<std::vector<v_t>> graph::adjacency + .. class:: graph::vertex - The adjacency list for the graph. The :math:`i\text{th}` element of :member:`adjacency` is a standard library vector containing the indices of all vertices adjacent to vertex :math:`i`. + This class describes the vertices on the graph. - .. member:: std::vector<std::vector<double>> graph::coordinate + .. member:: unsigned ind - The coordinates of the graph vertices. The :math:`i\text{th}` element of :var:`coordinate` is a standard library vector of length :var:`D` containing the spatial coordinates of vertex :math:`i`. This property is unused by the core library. + The index of the vertex, which is also its position in the list :var:`vertices`. + + .. member:: std::list<halfedge> edges + + The list of edges emanating from this vertex. + + .. member:: vertex_prop prop + + Template-defined class which stores optional properties of the vertex. + + .. class:: graph::halfedge + + This class describes the halfedges on the graph. + + .. member:: vertex& self + + A reference to the vertex this halfedge is emanating from. + + .. member:: vertex& neighbor + + A reference to the vertex this halfedge is going to. + + .. member:: edge_prop prop + + Template-defined class which stores optional properties of the edge. + + .. function:: halfedge(vertex &self, vertex &neighbor) + + Constructor which sets self and neighbor from supplied vertices. + + .. member:: std::vector<vertex> graph::vertices + + A list of all vertices in the graph. .. function:: graph::graph() - The default constructor. Initializes an empty graph, i.e., :var:`D`, :var:`L`, :var:`ne`, and :var:`nv` are all zero and :var:`adjacency` and :var:`coordinate` are uninitialized. + The default constructor. Initializes an empty graph, i.e., :var:`D`, :var:`L`, :var:`ne`, and :var:`nv` are all zero and :var:`vertices` is uninitialized. - .. function:: graph::graph(D_t D, L_t L) + .. function:: graph::graph(unsigned D, unsigned L) Initializes a graph of a :var:`D`-dimensional hypercubic lattice with :var:`L` vertices per side. This is the only nontrivial graph constructor supplied by the core library. The library will work with arbitrary graphs, and if a different lattice is needed consider calling the default constructor and populating the member objects youself before handing the graph to the :class:`system` constructor. - :param D_t D: The dimension of space. - :param L_t L: The number of vertices per edge of the hypercube. + :param unsigned D: The dimension of space. + :param unsigned L: The number of vertices per edge of the hypercube. .. function:: void graph::add_ghost() diff --git a/doc/index.rst b/doc/index.rst index 7b156d3..c379dd7 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -11,7 +11,6 @@ Wolff Library system measurement graph - types finite_states compile diff --git a/doc/measurement.rst b/doc/measurement.rst index 1b4381c..1ca41cc 100644 --- a/doc/measurement.rst +++ b/doc/measurement.rst @@ -5,64 +5,63 @@ 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`. +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:`lib/wolff.hpp`. -.. class:: template<R_t, X_t> measurement +.. class:: template<R_t, X_t, G_t = graph<>> 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. - .. function:: void measurement::pre_cluster(N_t n, N_t N, const system<R_t, X_t>& S, v_t i0, const R_t& r) + .. function:: void measurement::pre_cluster(unsigned n, unsigned N, const system<R_t, X_t, G_t>& S, const G_t::vertex& v, const R_t& r) This hook is run prior to cluster formation. - :param N_t n: The number of clusters already flipped. - :param N_t N: The total number of clusters to flip. - :param const system<R_t, X_t>& S: The current system state. - :param v_t i0: The index of the seed vertex for the cluster. + :param unsigned n: The number of clusters already flipped. + :param unsigned N: The total number of clusters to flip. + :param const system<R_t, X_t, G_t>& S: The current system state. + :param const G_t\:\:vertex& v: The seed vertex for the cluster. :param const R_t& r: The transformation by which the cluster will be flipped. - .. 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) + .. function:: void measurement::plain_bond_visited(const system<R_t, X_t, G_t>& S, const G_t::halfedge& e, const X_t& s1_new, double dE) This hook is run when an ordinary edge is visited during cluster formation, whether it is activated or not. - :param const system<R_t, X_t>& S: The current system state. - :param v_t i1: The index of the vertex soon to be flipped. - :param const X_t& s1_new: The state vertex :code:`i1` will be flipped to. - :param v_t i2: The other vertex sharing the edge. - :param double dE: The change in energy that will result when the spin at site :code:`i1` is flipped. + :param const system<R_t, X_t, G_t>& S: The current system state. + :param const G_t\:\:halfedge& e: The edge being considered, with e.self referencing the vertex soon to be flipped. + :param const X_t& s1_new: The state the vertex will be flipped to. + :param double dE: The change in energy that will result when the spin is flipped. - .. cpp:function:: void measurement::plain_site_transformed(const system<R_t, X_t>& S, v_t i, const X_t& si_new) + .. cpp:function:: void measurement::plain_site_transformed(const system<R_t, X_t, G_t>& S, const G_t::vertex& v, const X_t& si_new) This hook is run when an ordinary site is about to be flipped. - :param const system<R_t, X_t>& S: The current system state. - :param v_t i: The index of the vertex soon to be flipped. - :param const X_t& si_new: The state vertex :code:`i` will be flipped to. + :param const system<R_t, X_t, G_t>& S: The current system state. + :param const G_t\:\:vertex& v: The vertex soon to be flipped. + :param const X_t& si_new: The state that vertex 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) + .. cpp:function:: void measurement::ghost_bond_visited(const system<R_t, X_t, G_t>& S, const G_t::vertex& v, 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. - :param const system<R_t, X_t>& S: The current system state. - :param v_t i: The index of the non-ghost site in this edge. + :param const system<R_t, X_t, G_t>& S: The current system state. + :param const G_t\:\:vertex& v: The non-ghost site in this edge. :param 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. :param 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. :param 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) + .. cpp:function:: void measurement::ghost_site_transformed(const system<R_t, X_t, G_t>& S, const R_t& R_new) This hook is run when the ghost site is about to be flipped. - :param const system<R_t, X_t>& S: The current system state. + :param const system<R_t, X_t, G_t>& S: The current system state. :param 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) + .. cpp:function:: void measurement::post_cluster(unsigned n, unsigned N, const system<R_t, X_t, G_t>& S) This hook is run after a cluster has been flipped. - :param N_t n: The number of clusters already flipped. - :param N_t N: The total number of clusters to flip. - :param const system<R_t, X_t>& S: The current system state. + :param unsigned n: The number of clusters already flipped. + :param unsigned N: The total number of clusters to flip. + :param const system<R_t, X_t, G_t>& S: The current system state. diff --git a/doc/models.rst b/doc/models.rst index e376e2e..8ba7e51 100644 --- a/doc/models.rst +++ b/doc/models.rst @@ -3,7 +3,7 @@ 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. Many examples of models can be found in the headers contained in :file:`wolff/models/`. +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. Many examples of models can be found in the headers contained in :file:`lib/wolff_models/`. Spin States =========== diff --git a/doc/system.rst b/doc/system.rst index 928d85b..9cd4a90 100644 --- a/doc/system.rst +++ b/doc/system.rst @@ -5,25 +5,25 @@ Constructing a System & Running Wolff ************************************* -This class and associated member functions are defined in the header files :file:`wolff.hpp`, :file:`wolff/system.hpp`, and :file:`wolff/cluster.hpp`. +This class and associated member functions are defined in the header file :file:`lib/wolff.hpp`. -.. class:: template\<R_t, X_t> system +.. class:: template\<R_t, X_t, G_t = graph\<>> system The core of the library lies in the :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`. - .. member:: v_t system::nv + .. member:: unsigned system::nv Stores the number of ordinary sites in the model. - .. member:: v_t system::ne + .. member:: unsigned system::ne Stores the number of ordinary bonds in the model. - .. member:: graph system::G + .. member:: G_t system::G - Stores the graph describing the lattice, including the ghost site. + Stores the graph describing the lattice, including the ghost site. See :ref:`graphs` for details on this class. The template parameter has a default option corresponding to a graph type with no special vertex or edge properties. .. member:: double system::T @@ -45,33 +45,33 @@ This class and associated member functions are defined in the header files :file The function that returns the coupling to the field. - .. function:: system::system(graph G, double T, std::function <double(const X_t&, const X_t&)> Z, std::function <double(const X_t&)> B) + .. function:: system::system(G_t G, double T, std::function <double(const X_t&, const X_t&)> Z, std::function <double(const X_t&)> B) The constructor for systems. - :param graph G: A lattice graph *without* the ghost spin added. + :param G_t G: A lattice graph *without* the ghost spin added. :param double T: The temperature. :param std\:\:function<double(const X_t&, const X_t&)> Z: The bond coupling. :param std\:\:function<double(const X_t&)> B: The field coupling. The states of the spins and ghost site are initialized using the default constructors for :type:`X_t` and :type:`R_t`, respectively. :any:`nv` and :any:`ne` are taken directly from :any:`G`, after which the ghost site is added to :any:`G`. - .. function:: system::flip_cluster(v_t i0, const R_t& r, std::mt19937& rng, measurement<R_t, X_t>& A) + .. function:: system::flip_cluster(const G_t::vertex& v0, const R_t& r, std::mt19937& rng, measurement<R_t, X_t, G_t>& A) Performs one Wolff cluster flip to the system. - :param v_t i0: The index of the seed site. + :param const G_t\:\:vertex& v0: The vertex of the seed site. :param const R_t& r: The transformation by which the cluster is flipped. :param std\:\:mt19937& rng: A random number generator. - :param measurement<R_t, X_t>& A: Object whose class inherits :class:`measurement` and provides relevant measurement hooks. + :param measurement<R_t, X_t, G_t>& A: Object whose class inherits :class:`measurement` and provides relevant measurement hooks. - .. 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) + .. function:: system::run_wolff(unsigned N, std::function <R_t(std::mt19937&, const system<R_t, X_t, G_t>&, const G_t::vertex&)> r_gen, measurement<R_t, X_t, G_t>& A, std::mt19937& rng) Performs :any:`N` Wolff cluster flips to the system. - :param N_t N: Number of clusters to flip. - :param std\:\:function <R_t(std\:\:mt19937&, const system<R_t, X_t>&, v_t>)> r_gen: Generator of transformations for the cluster flips. - :param measurement<R_t, X_t>& A: Object whose class inherits :class:`measurement` and provides relevant measurement hooks. + :param unsigned N: Number of clusters to flip. + :param std\:\:function <R_t(std\:\:mt19937&, const system<R_t, X_t, G_t>&, const G_t\:\:vertex&>)> r_gen: Generator of transformations for the cluster flips. + :param measurement<R_t, X_t, G_t>& A: Object whose class inherits :class:`measurement` and provides relevant measurement hooks. :param std\:\:mt19937& rng: A random number generator. diff --git a/doc/types.rst b/doc/types.rst deleted file mode 100644 index b729ac3..0000000 --- a/doc/types.rst +++ /dev/null @@ -1,36 +0,0 @@ - -************ -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 - |