Merge pull request #73 from ALPSim/docs/improve-mc-quickstart

docs: improve Classical Monte Carlo quickstart and fix math rendering

Author: egull

content/en/documentation/alpsize/alpsize00.md

@@ -46,23 +46,23 @@ Flow of packaging (missing picture)
 
 ### Packaging with Cmake
 
-00\_cmake
+00_cmake
 
     $ cmake .
     $ make 
     $ ./hello
 
 ### Implementation of the Wolff algorithm in C language
 
-01\_original-c
+01_original-c
 
     $ cmake .
     $ make 
     $ ./wolff
 
 ### Implementation of the Wolff algorithm in C++ language
 
-02\_basic-cpp
+02_basic-cpp
 
 - modify header file： \<math.h\> to \<cmath\>,etc..
 - std name space
@@ -75,7 +75,7 @@ Flow of packaging (missing picture)
 
 ### Using Standard Template Library
 
-03\_stl
+03_stl
 
 - std::vector<>:1D-array
 - std::stack<>:stack
@@ -88,7 +88,7 @@ Flow of packaging (missing picture)
 
 ### Using Boost C++ Library
 
-04\_boost
+04_boost
 
 - <boost/array.hpp>
     - fixed-length array
@@ -105,23 +105,23 @@ Flow of packaging (missing picture)
 
 ### Using ALPS/parameters
 
-05\_parameters
+05_parameters
 
     $ cmake .
     $ make
     $ ./wolff <wolff.ip
 
 ### Using ALPS/alea
 
-06\_alea
+06_alea
 
     $ cmake .
     $ make
     $ ./wolff wolff.ip
 
 ### Using ALPS/lattice
 
-07\_lattice
+07_lattice
 
     $ cmake .
     $ make
@@ -130,7 +130,7 @@ Flow of packaging (missing picture)
 
 ### Full ALPSize using ALPS/Parapack Scheduler
 
-08\_scheduler
+08_scheduler
 
 - encapsulated code: Worker class
 - Function, must be implemented by Worker Class
@@ -140,7 +140,7 @@ Flow of packaging (missing picture)
     - save&load member function
 - Worker registration to the scheduler running the macro of PARAPACK_REGISTER_WORKER
 - preparation of Parameters and ObservableSet by scheduler,and setting constructor、init_observables-function、run-function
-- Because lattice_mc_workerはlattice\_helper has inherited rng_helper、that can activate the function of lattice_helper,rng_helper.
+- Because lattice_mc_workerはlattice_helper has inherited rng_helper、that can activate the function of lattice_helper,rng_helper.
 
         $ cmake .
         $ make

content/en/documentation/codedev/code01.md

@@ -78,7 +78,7 @@ The `run` method manages the Monte Carlo updates defined in the step routine and
             # Flip s_k with probability exp(2 beta e)
             ...
 
-The Monte Carlo sweeps are done in the `step` method. In the Metropolis algorithm a spin is a randomly picked and flipped with probability $p\_{accept} = min(1,e^{-\beta \Delta E})$, $\Delta E$ being the energy difference of the initial and proposed configuration. This procedure is repeated $L^2$ times. The implementation of the Metropolis algorithm is left to you as an exercise. You can make use of the `randint` function defined below:
+The Monte Carlo sweeps are done in the `step` method. In the Metropolis algorithm a spin is a randomly picked and flipped with probability $p_{accept} = min(1,e^{-\beta \Delta E})$, $\Delta E$ being the energy difference of the initial and proposed configuration. This procedure is repeated $L^2$ times. The implementation of the Metropolis algorithm is left to you as an exercise. You can make use of the `randint` function defined below:
 
     def randint(self,max):
        return int(max*self.rng())

content/en/documentation/codedev/code02.md

@@ -10,7 +10,7 @@ This tutorial shows how to write a Monte Carlo simulation in C++ using the ALPS
 
 As a simple example, we will write a simulation of the classical 2D Ising model with local updates. The file `ising-skeleton.cpp` contains a skeleton code which already has all the infrastructure we will need: First it includes all needed headers, then it initializes a random number generator and three `alps::RealObservable` objects. Then it sets up a square lattice of Ising spins. It also provides a table of probabilities that can be used for Metropolis updates. The interface is the same as in the python script you implemented in the previous [tutorial](../../codedev/code01).
 
-Your job is again to complete the methods `step()` and `measure()`: `step()` should choose a random spin from the lattice and flip it with the Metropolis probability $p\_{accept} = min(1,e^{-\beta \Delta E})$ where $\Delta E$ is the energy change the spin flip would cause. `measure()` determines the energy and magnetization of a spin configuration and adds this sample to the observable objects.
+Your job is again to complete the methods `step()` and `measure()`: `step()` should choose a random spin from the lattice and flip it with the Metropolis probability $p_{accept} = min(1,e^{-\beta \Delta E})$ where $\Delta E$ is the energy change the spin flip would cause. `measure()` determines the energy and magnetization of a spin configuration and adds this sample to the observable objects.
 
 After replacing all ellipses with code, you can compile the simulation with this `Makefile`: Save the `Makefile` to the same directory as the `.cpp` file, edit the second line to point to your ALPS installation (if you haven't already set the environment variable ALPS_ROOT) and type `make`. This will produce an executable `ising`. Run it and you will see a scan over different values of $\beta = 1/k_B T$.
 

content/en/documentation/intro/runalps/usepython.md

@@ -166,7 +166,7 @@ The preparation, simulation, and evaluation tasks can also be split into subtask
 
 ## More examples
 
-More example usage of the various functions and more advanced applications can be found in the tutorials. Also, don't forget to look at the documentation of the various functions using the \_\_doc\_\_ member variable of the functions, as in:
+More example usage of the various functions and more advanced applications can be found in the tutorials. Also, don't forget to look at the documentation of the various functions using the __doc__ member variable of the functions, as in:
 
     print pyalps.plot.plot.__doc__
 

content/en/documentation/lib/alea/_index.md

@@ -15,8 +15,8 @@ Here is an overview of the functions available
 | `mean` | Timeseries | None | `AverageType` |
 | `variance` | Timeseries | None | `AverageType` | 
 | `error` | Timeseries | uncorrelated, binning | `AverageType` |
-| `autocorrelation` | Timeseries | \_distance, \_limit | `mctimeseries<AverageType>` | 
-| `exponential_autocorrelation_time` | Scalar MCTimeseries | \_from & \_to, \_max & \_min | `std::pair<AverageType, AverageType>` |
+| `autocorrelation` | Timeseries | _distance, _limit | `mctimeseries<AverageType>` | 
+| `exponential_autocorrelation_time` | Scalar MCTimeseries | _from & _to, _max & _min | `std::pair<AverageType, AverageType>` |
 | `integrated_autocorrelation_time` | Scalar MCTimeseries, `std::pair<AverageType, AverageType>` | None | `AverageType` |
 | `running_mean` | Timeseries | None | `mctimeseries<AverageType>` |
 | `reverse_running_mean` | Timeseries | None | `mctimeseries<AverageType>` |
@@ -27,8 +27,8 @@ The objects `mctimeseries<ValueType>` and `mctimeseries_view<ValueType>` are ess
 
 | **Function Name** | **Argument(s)** | **Options** | **Return Type** |
 | :---------------- | :-------------- | :---------- | :-------------- |
-| `cut_head` | Timeseries | \_distance, \_limit | `mctimeseries_view<ValueType>` |
-| `cut_tail` | Timeseries | \_distance, \_limit | `mctimeseries_view<ValueType>` |
+| `cut_head` | Timeseries | _distance, _limit | `mctimeseries_view<ValueType>` |
+| `cut_tail` | Timeseries | _distance, _limit | `mctimeseries_view<ValueType>` |
 
 
 ## Mean

content/en/documentation/methods/dmft/dmft.md

@@ -34,7 +34,7 @@ weight: 9
 | MAX_IT | maximum number of iteration in self-consistency loop (usually 10-20 will be enough) |
 | CONVERGED | criterium for stopping the self-consistency loop before reaching MAX_IT - if the maximum change in Green's function in Matsubara representation is less than CONVERGED, the loop will stop |
 | TOLERANCE | (only for hirschfyesim) as above |
-| RELAX_RATE | (by default 1; currently implemented only for selfconsistency loop with OMEGA_LOOP switched on) the new Green's function are in general computed as RELAX\_RATE \* $G\_{new}(i\omega_n)$ + (1-RELAX\_RATE) \* $G\_{old}(i\omega_n)$, which may help if oscillations occur |
+| RELAX_RATE | (by default 1; currently implemented only for selfconsistency loop with OMEGA_LOOP switched on) the new Green's function are in general computed as RELAX_RATE \* $G_{new}(i\omega_n)$ + (1-RELAX_RATE) \* $G_{old}(i\omega_n)$, which may help if oscillations occur |
 
 ### General parameters
 
@@ -147,7 +147,7 @@ weight: 9
 
 ### The output files for the hybridization expansion impurity solver: (text files) 
 
-- overlap: i-th row contains the $\langle n\_\downarrow n\_\uparrow\rangle$ in the i-th iteration 
+- overlap: i-th row contains the $\langle n_\downarrow n_\uparrow\rangle$ in the i-th iteration 
 - matrix_size:
 
 

content/en/documentation/methods/ed/fulldiag/implem.md

@@ -9,7 +9,7 @@ weight: 3
 
 The `fulldiag` package uses LAPACK library for a complete diagonalization of the Hamiltonian. Hence, it can be used for computing thermodynamic properties of any model that can be defined using the ALPS libraries. The main limitation is one of size, i.e., memory and CPU time may become unacceptable at sizes where other, more specialized applications still work well.
 
-Release 1.3 allows the computation of magnetic or charge properties properties for models with a coupling to a conserved quantity of the form $-hS\_z$ or $-\mu N$, i.e., a SITETERM $-h S_z(i)$ or $-\mu n(i)$. In fact, adaptation to other situations with a coupling to a conserved quantity should be relatively straightforward by changing a few lines in the source file fulldiag.h (this is just not supported at the moment, since it requires the modification of at least 5 strings by the user). If the conserved quantity is not present, two quantities less will be evaluated (see below).
+Release 1.3 allows the computation of magnetic or charge properties properties for models with a coupling to a conserved quantity of the form $-hS_z$ or $-\mu N$, i.e., a SITETERM $-h S_z(i)$ or $-\mu n(i)$. In fact, adaptation to other situations with a coupling to a conserved quantity should be relatively straightforward by changing a few lines in the source file fulldiag.h (this is just not supported at the moment, since it requires the modification of at least 5 strings by the user). If the conserved quantity is not present, two quantities less will be evaluated (see below).
 
 **Warning:** Incorrect results may be obtained if the supposed conserved quantity does actually not commute with the Hamiltonian. Incorrect results will also in general be obtained if the coefficients are not of the above form, and the magnetic field $h$ or chemical potential $\mu$ are changed by `fulldiag_evaluate`.
 

content/en/documentation/methods/ed/fulldiag/jacobi.md

@@ -21,7 +21,7 @@ $$
 
 where $D$ is a diagonal matrix containing the eigenvalues of $A$, and the columns of $P$ are the corresponding eigenvectors.
 
-The Jacobi method achieves this by applying a sequence of orthogonal transformations (rotations) to $A$. Each rotation targets a specific off-diagonal element $A\_{ij}$ and zeroes it out.
+The Jacobi method achieves this by applying a sequence of orthogonal transformations (rotations) to $A$. Each rotation targets a specific off-diagonal element $A_{ij}$ and zeroes it out.
 
 
 ## Rotation Matrix
@@ -40,18 +40,18 @@ R = \begin{pmatrix}
 \end{pmatrix}
 $$
 
-Here, $\cos \theta$ and $\sin \theta$ are placed at the intersections of the $i$-th and $j$-th rows and columns. The angle $\theta$ is chosen such that the off-diagonal element $A\_{ij}$ is zeroed out.
+Here, $\cos \theta$ and $\sin \theta$ are placed at the intersections of the $i$-th and $j$-th rows and columns. The angle $\theta$ is chosen such that the off-diagonal element $A_{ij}$ is zeroed out.
 
 
 ## Algorithm
 
 1. **Identify the Largest Off-Diagonal Element**:
-   - Find the largest off-diagonal element $A\_{ij}$ (in absolute value) in the matrix $A$.
+   - Find the largest off-diagonal element $A_{ij}$ (in absolute value) in the matrix $A$.
 
 2. **Compute the Rotation Angle $\theta$**:
    - The angle $\theta$ is chosen to satisfy:
      $$
-     \tan(2\theta) = \frac{2A\_{ij}}{A\_{ii} - A\_{jj}}
+     \tan(2\theta) = \frac{2A_{ij}}{A_{ii} - A_{jj}}
      $$
    - From this, compute $\cos \theta$ and $\sin \theta$.
 
@@ -63,7 +63,7 @@ Here, $\cos \theta$ and $\sin \theta$ are placed at the intersections of the $i$
      $$
      A^{\prime} = R^T A R
      $$
-   - This transformation zeroes out $A\_{ij}$ and $A\_{ji}$.
+   - This transformation zeroes out $A_{ij}$ and $A_{ji}$.
 
 5. **Accumulate the Transformations**:
    - Update the eigenvector matrix $P$ as:

content/en/documentation/methods/ed/fulldiag/qrfactor.md

@@ -44,13 +44,13 @@ The eigenvalues of $A$ are found on the diagonal of the final matrix $A_k$, and
 3. **Reconstruction**:
    - Reconstruct the matrix $A_{k+1}$ as:
      $$
-     A\_{k+1} = R_k Q_k
+     A_{k+1} = R_k Q_k
      $$
 
 4. **Accumulate Transformations**:
    - Update the eigenvector matrix $P$ as:
      $$
-     P\_{k+1} = P_k Q_k
+     P_{k+1} = P_k Q_k
      $$
    - Initialize $P_0 = I$ (identity matrix).
 

content/en/documentation/methods/ed/intro.md

@@ -11,23 +11,23 @@ Exact diagonalization (ED) is a numerical technique used to solve quantum many-b
 The Heisenberg model is defined by the Hamiltonian:
 
 $$
-\mathcal{H} = J \sum\_{\langle i,j \rangle} \mathbf{S}\_i \cdot \mathbf{S}\_j,
+\mathcal{H} = J \sum_{\langle i,j \rangle} \mathbf{S}_i \cdot \mathbf{S}_j,
 $$
 
-where $\mathbf{S}\_i$ is the spin-1/2 operator at site $i$, $J$ is the exchange interaction (ferromagnetic for $J \lt 0$ and antiferromagnetic for $J \gt 0$), and the sum runs over nearest-neighbor pairs $\langle i,j \rangle$. For simplicity, we consider a 1D chain with periodic boundary conditions.
+where $\mathbf{S}_i$ is the spin-1/2 operator at site $i$, $J$ is the exchange interaction (ferromagnetic for $J \lt 0$ and antiferromagnetic for $J \gt 0$), and the sum runs over nearest-neighbor pairs $\langle i,j \rangle$. For simplicity, we consider a 1D chain with periodic boundary conditions.
 
 ### Example: 4-Site 1D Heisenberg Chain
 
 Let’s study a 4-site 1D Heisenberg chain with periodic boundary conditions. The Hamiltonian for this system is:
 
 $$
-\mathcal{H} = J \left( \mathbf{S}\_1 \cdot \mathbf{S}\_2 + \mathbf{S}\_2 \cdot \mathbf{S}\_3 + \mathbf{S}\_3 \cdot \mathbf{S}\_4 + \mathbf{S}\_4 \cdot \mathbf{S}\_1 \right).
+\mathcal{H} = J \left( \mathbf{S}_1 \cdot \mathbf{S}_2 + \mathbf{S}_2 \cdot \mathbf{S}_3 + \mathbf{S}_3 \cdot \mathbf{S}_4 + \mathbf{S}_4 \cdot \mathbf{S}_1 \right).
 $$
 
-The spin-1/2 operators $\mathbf{S}\_i = (S_i^x, S_i^y, S_i^z)$ can be expressed in terms of Pauli matrices $\boldsymbol{\sigma}\_i$ as $\mathbf{S}\_i = \frac{1}{2} \boldsymbol{\sigma}\_i$. The dot product $\mathbf{S}\_i \cdot \mathbf{S}\_j$ can be written as:
+The spin-1/2 operators $\mathbf{S}_i = (S_i^x, S_i^y, S_i^z)$ can be expressed in terms of Pauli matrices $\boldsymbol{\sigma}_i$ as $\mathbf{S}_i = \frac{1}{2} \boldsymbol{\sigma}_i$. The dot product $\mathbf{S}_i \cdot \mathbf{S}_j$ can be written as:
 
 $$
-\mathbf{S}\_i \cdot \mathbf{S}\_j = S_i^x S_j^x + S_i^y S_j^y + S_i^z S_j^z.
+\mathbf{S}_i \cdot \mathbf{S}_j = S_i^x S_j^x + S_i^y S_j^y + S_i^z S_j^z.
 $$
 
 ### Basis States
@@ -36,15 +36,15 @@ For a 4-site system with spin-1/2 particles, the Hilbert space has $2^4 = 16$ ba
 
 The basis states are eigen states of $S_i^z$ operators. When it is applied to the $i$'th site, it gives
 $$
-S\_i^z|\uparrow\rangle = \frac{1}{2}|\uparrow\rangle,
+S_i^z|\uparrow\rangle = \frac{1}{2}|\uparrow\rangle,
 $$
 and
 $$
-S\_i^z|\downarrow\rangle = -\frac{1}{2}|\downarrow\rangle.
+S_i^z|\downarrow\rangle = -\frac{1}{2}|\downarrow\rangle.
 $$
 To see the result of applying Hamiltonian to the basis states, we need to express the off-diagonal operators, i.e., $S_i^x$ and $S_i^y$ in terms of raising $S^{\dagger}$ and lowering $S^{-}$ operators:
 $$
-S\_i^x=\frac{1}{2}(S_i^{\dagger}+S_i^{-}),
+S_i^x=\frac{1}{2}(S_i^{\dagger}+S_i^{-}),
 $$
 $$
 S_i^y=\frac{1}{2i}(S_i^{\dagger}-S_i^{-}),
@@ -59,21 +59,21 @@ $$
 where $S=1/2$ and $s=-1/2, 1/2$.
 With the above transformation, the Hamiltonian element becomes
 $$
-\mathbf{S}\_i \cdot \mathbf{S}\_j = \frac{1}{2}(S_i^{\dagger}S_j^{-}+S_i^{-}S_j^{\dagger})+S\_i^zS\_j^z.
+\mathbf{S}_i \cdot \mathbf{S}_j = \frac{1}{2}(S_i^{\dagger}S_j^{-}+S_i^{-}S_j^{\dagger})+S_i^zS_j^z.
 $$
 
 ### Hamiltonian Matrix
 
-To construct the Hamiltonian matrix, we evaluate the action of $\mathcal{H}$ on each basis state. For instance, consider the term $\mathbf{S}\_1 \cdot \mathbf{S}\_2$:
+To construct the Hamiltonian matrix, we evaluate the action of $\mathcal{H}$ on each basis state. For instance, consider the term $\mathbf{S}_1 \cdot \mathbf{S}_2$:
 
 $$
-\mathbf{S}\_1 \cdot \mathbf{S}\_2 = \frac{1}{2}(S_1^{\dagger}S_2^{-}+S_1^{-}S_2^{\dagger})+S\_1^zS\_2^z.
+\mathbf{S}_1 \cdot \mathbf{S}_2 = \frac{1}{2}(S_1^{\dagger}S_2^{-}+S_1^{-}S_2^{\dagger})+S_1^zS_2^z.
 $$
 
 This term flips spins at sites 1 and 2 if they are antiparallel and contributes a factor of $\frac{1}{4}$ if they are parallel. For example:
 
 $$
-\mathbf{S}\_1 \cdot \mathbf{S}\_2 | \uparrow \downarrow \uparrow \uparrow \rangle = \frac{1}{4} \left( | \downarrow \uparrow \uparrow \uparrow \rangle - | \uparrow \downarrow \uparrow \uparrow \rangle \right).
+\mathbf{S}_1 \cdot \mathbf{S}_2 | \uparrow \downarrow \uparrow \uparrow \rangle = \frac{1}{4} \left( | \downarrow \uparrow \uparrow \uparrow \rangle - | \uparrow \downarrow \uparrow \uparrow \rangle \right).
 $$
 
 Repeating this process for all terms in $\mathcal{H}$ and all basis states, we construct the $16 \times 16$ Hamiltonian matrix. For brevity, we do not write the full matrix here, but it can be systematically built using the above rules.