Modify 4-Parameters_customize.md

build/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 1b6f940f8d9e59c2bc24c23404cb4d10
+config: b5f240d1de9c371a4bcfd8495307cfd4
 tags: 645f666f9bcd5a90fca523b33c5a78b7

build/html/_sources/4-Parameters_customize.md.txt

@@ -2,6 +2,40 @@
 
 ## Customize annealing schedule
 
+In this page, let us show you how to set the parameters for annealing. 
+
+### SASampler
+
+`SASampler` has arguments as follows.
+
+#### beta_min (float)
+
+The minimum value of inverse temperature. Default to None. This corresponds to the starting temperature for annealing.  
+If you do not specify anything, OpenJij will set the appropriate temperature automatically.
+
+#### beta_max (float)
+
+The maximum value of inverse temperature. Default to None. This corresponds to the ending temperature for annealing.  
+If you do not specify anything, OpenJij will set the appropriate temperature automatically.
+
+#### num_reads (int)
+
+The number of iteration of annealing. Default to 1. If num_reads is specified, response has numerical results for the number of num_reads.
+
+#### num_sweeps (int)
+
+The number of Monte-Carlo steps (hereafter we called MCsteps) during annealing. Default to 1000.
+
+> -note- MCsteps means the number of times to flip all the spins in the system. e.g., the case of N spin system, during 1 MCstep, you will have to flip these spins N times.
+
+#### schedule (list)
+
+You can set the annealing schedule as you like. Default to None. If you want to calculate "alpha" MCsteps for a given inverse temperature "beta", you can set it as [beta, alpha].
+
+
+### Sample script 1
+
+The following is an example of annealing with parameters `beta_min=0.1, beta_max=100, num_reads=1000, num_sweeps=100`. 
 
 ```python
 import openjij as oj
@@ -12,14 +46,124 @@ for i in range(n-1):
     for j in range(i+1, n):
         J[i, j] = -1
 
-# customized annealing schedule
-# list of [beta, monte carlo steps in beta]
-schedule = [
-    [10, 3],
-    [ 5, 5],
-    [0.5, 10]
-]
+# set parameters 
+bmin = 0.1
+bmax = 100
+nreads = 1000
+nsweeps = 100
+
+sampler = SASampler()
+response = sampler.sample_ising(h, J, beta_min=bmin, beta_max=bmax, num_reads=nreads, num_sweeps=nsweeps)
+```
+
+### Sample script 2
+
+Here, let me show you an example how to specify an annealing schedule for user. The following figure shows an image of annealing schedule.
+
+![An example of SA schedule](/images/4/schedule.png)
+
+At first, calculate 3 MCsteps with `beta=0.5`. Next, compute 5 MCsteps with `beta=5`. Finally, execute 6 MCsteps with `beta=10`.
+
+A example of script that does this is following.
+
+```python
+schedule = [[0.5, 3], [5, 5], [10, 6]]
 
 sampler = SASampler()
 response = sampler.sample_ising(h, J, schedule=schedule)
-```
+```
+
+### SQASampler
+
+SQASampler considers the total Hamiltonian with the following quantum terms when the Hamiltonian of the problem you want to solve is $\hat{H}_p$, 
+
+$
+\hat{H} = s\hat{H}_p + (1-s) \Gamma \sum_{i} \hat{\sigma}^x_i
+$
+
+and annealing is performed under the following statistical distribution, 
+
+$
+P(\hat{H}) \propto e^{-\beta \hat{H}}
+$
+
+`SQASampler` has arguments as follows.
+
+#### beta (float)
+
+The inverse temperature. Default to 5.0.
+
+#### Gamma (float)
+
+The magnitude of the quantum term. Default to 1.0.
+
+#### trotter (int)
+
+The system Trotter decomposition number. Default to 4.
+
+#### num_sweeps (int)
+
+The number of MCsteps required between changing the annealing schedule parameter `s` from 0 to 1. Default to 1000.
+
+#### num_reads (int)
+
+The number of annealing iteration. Default to 1.
+
+#### shcedule (list)
+
+Set an annealing shcedule as you like. Default to None. For a given inverse temperature if you want to compute "alpha" MCsteps with the annealing schedule parameter "s", you can set it as [s, alpha].   
+If you want to specify the inverse temperature "beta" and compute "alpha" MCsteps with the annealing schedule parameter "s", you can specify it as [s, beta, alpha].
+
+### Sample script 1
+
+The following example shows an annealing computation with `beta=10, gamma=5, trotter=16, num_reads=1000, num_sweeps=100`
+
+```python
+import openjij as oj
+
+n = 10
+h, J = {}, {}
+for i in range(n-1):
+    for j in range(i+1, n):
+        J[i, j] = -1
+
+# set parameters 
+beta = 10
+gamma = 5
+trotter = 16
+nreads = 1000
+nsweeps = 100
+
+sampler = SQASampler()
+response = sampler.sample_ising(h, J, beta=beta, gamma=gamma, trotter=trotter, num_reads=nreads, num_sweeps=nsweeps)
+```
+
+### Sample script 2
+
+Here we introduce an example of a user-specified annealing schedule. The following figure shows an image of annealing schedule.
+
+![An example of SQA schedule with constant beta](/images/4/schedule_sqa.png)
+
+First, 5 MCsteps with `s=0.0`. Next, 10 MCsteps with `s=0.5`. Finally, 5 MCsteps with `s=1`.
+
+```python
+schedule = [[0, 5], [0.5, 10], [1, 5]]
+
+sampler = SQASampler()
+response = sampler.sample_ising(h, J, schedule=schedule)
+```
+
+### Sample script 3
+
+In this section, we show you an example of a user-defined annealing shcedule in more detail.
+
+![An example of SQA schedule including beta](/images/4/schedule_sqa_2.png)
+
+First, 5 MCsteps with `s=0.0, beta=0.5`. Next, 10 MCsteps with `s=0.5, beta=1.0`. Finally, 5 MCsteps with `s=1, beta=10`.
+
+```python
+schedule = [[0, 0.5, 5], [0.5, 1.0, 10], [1, 10, 5]]
+
+sampler = SQASampler()
+response = sampler.sample_ising(h, J, schedule=schedule)
+```

build/html/_sources/7-hogehoge.md.txt

@@ -0,0 +1,34 @@
+# Higher order model
+
+If you want to handle higher order model as follows:
+
+ ```math
+ H = \sum_{i}h_i\sigma_i + \sum_{i < j} J_{ij} \sigma_i \sigma_j + \sum_{i, j, k} K_{i,j,k} \sigma_i\sigma_j \sigma_k \cdots
+ ```
+
+use ``.sample_hubo``
+
+> HUBO: Higher order unconstraint binary optimization
+
+## Sample code
+```python
+import openjij as oj
+
+# Only SASampler can handle HUBO.
+sampler = oj.SASampler()
+
+# make HUBO
+h = {0: -1}
+J = {(0, 1): -1}
+K = {(0, 1, 2): 1}
+
+response = sampler.sample_hubo([h, J, K], var_type="SPIN")
+response.states[0]
+> [1, 1, -1]
+```
+
+## Note
+
+``.sample_hubo``
+- The first argument (``interactions``) must be in ascending order.
+- Need ``var_type``

source/4-Parameters_customize.md

@@ -2,6 +2,40 @@
 
 ## Customize annealing schedule
 
+In this page, let us show you how to set the parameters for annealing. 
+
+### SASampler
+
+`SASampler` has arguments as follows.
+
+#### beta_min (float)
+
+The minimum value of inverse temperature. Default to None. This corresponds to the starting temperature for annealing.  
+If you do not specify anything, OpenJij will set the appropriate temperature automatically.
+
+#### beta_max (float)
+
+The maximum value of inverse temperature. Default to None. This corresponds to the ending temperature for annealing.  
+If you do not specify anything, OpenJij will set the appropriate temperature automatically.
+
+#### num_reads (int)
+
+The number of iteration of annealing. Default to 1. If num_reads is specified, response has numerical results for the number of num_reads.
+
+#### num_sweeps (int)
+
+The number of Monte-Carlo steps (hereafter we called MCsteps) during annealing. Default to 1000.
+
+> -note- MCsteps means the number of times to flip all the spins in the system. e.g., the case of N spin system, during 1 MCstep, you will have to flip these spins N times.
+
+#### schedule (list)
+
+You can set the annealing schedule as you like. Default to None. If you want to calculate "alpha" MCsteps for a given inverse temperature "beta", you can set it as [beta, alpha].
+
+
+### Sample script 1
+
+The following is an example of annealing with parameters `beta_min=0.1, beta_max=100, num_reads=1000, num_sweeps=100`. 
 
 ```python
 import openjij as oj
@@ -12,14 +46,124 @@ for i in range(n-1):
     for j in range(i+1, n):
         J[i, j] = -1
 
-# customized annealing schedule
-# list of [beta, monte carlo steps in beta]
-schedule = [
-    [10, 3],
-    [ 5, 5],
-    [0.5, 10]
-]
+# set parameters 
+bmin = 0.1
+bmax = 100
+nreads = 1000
+nsweeps = 100
+
+sampler = SASampler()
+response = sampler.sample_ising(h, J, beta_min=bmin, beta_max=bmax, num_reads=nreads, num_sweeps=nsweeps)
+```
+
+### Sample script 2
+
+Here, let me show you an example how to specify an annealing schedule for user. The following figure shows an image of annealing schedule.
+
+![An example of SA schedule](/images/4/schedule.png)
+
+At first, calculate 3 MCsteps with `beta=0.5`. Next, compute 5 MCsteps with `beta=5`. Finally, execute 6 MCsteps with `beta=10`.
+
+A example of script that does this is following.
+
+```python
+schedule = [[0.5, 3], [5, 5], [10, 6]]
 
 sampler = SASampler()
 response = sampler.sample_ising(h, J, schedule=schedule)
-```
+```
+
+### SQASampler
+
+SQASampler considers the total Hamiltonian with the following quantum terms when the Hamiltonian of the problem you want to solve is $\hat{H}_p$, 
+
+$
+\hat{H} = s\hat{H}_p + (1-s) \Gamma \sum_{i} \hat{\sigma}^x_i
+$
+
+and annealing is performed under the following statistical distribution, 
+
+$
+P(\hat{H}) \propto e^{-\beta \hat{H}}
+$
+
+`SQASampler` has arguments as follows.
+
+#### beta (float)
+
+The inverse temperature. Default to 5.0.
+
+#### Gamma (float)
+
+The magnitude of the quantum term. Default to 1.0.
+
+#### trotter (int)
+
+The system Trotter decomposition number. Default to 4.
+
+#### num_sweeps (int)
+
+The number of MCsteps required between changing the annealing schedule parameter `s` from 0 to 1. Default to 1000.
+
+#### num_reads (int)
+
+The number of annealing iteration. Default to 1.
+
+#### shcedule (list)
+
+Set an annealing shcedule as you like. Default to None. For a given inverse temperature if you want to compute "alpha" MCsteps with the annealing schedule parameter "s", you can set it as [s, alpha].   
+If you want to specify the inverse temperature "beta" and compute "alpha" MCsteps with the annealing schedule parameter "s", you can specify it as [s, beta, alpha].
+
+### Sample script 1
+
+The following example shows an annealing computation with `beta=10, gamma=5, trotter=16, num_reads=1000, num_sweeps=100`
+
+```python
+import openjij as oj
+
+n = 10
+h, J = {}, {}
+for i in range(n-1):
+    for j in range(i+1, n):
+        J[i, j] = -1
+
+# set parameters 
+beta = 10
+gamma = 5
+trotter = 16
+nreads = 1000
+nsweeps = 100
+
+sampler = SQASampler()
+response = sampler.sample_ising(h, J, beta=beta, gamma=gamma, trotter=trotter, num_reads=nreads, num_sweeps=nsweeps)
+```
+
+### Sample script 2
+
+Here we introduce an example of a user-specified annealing schedule. The following figure shows an image of annealing schedule.
+
+![An example of SQA schedule with constant beta](/images/4/schedule_sqa.png)
+
+First, 5 MCsteps with `s=0.0`. Next, 10 MCsteps with `s=0.5`. Finally, 5 MCsteps with `s=1`.
+
+```python
+schedule = [[0, 5], [0.5, 10], [1, 5]]
+
+sampler = SQASampler()
+response = sampler.sample_ising(h, J, schedule=schedule)
+```
+
+### Sample script 3
+
+In this section, we show you an example of a user-defined annealing shcedule in more detail.
+
+![An example of SQA schedule including beta](/images/4/schedule_sqa_2.png)
+
+First, 5 MCsteps with `s=0.0, beta=0.5`. Next, 10 MCsteps with `s=0.5, beta=1.0`. Finally, 5 MCsteps with `s=1, beta=10`.
+
+```python
+schedule = [[0, 0.5, 5], [0.5, 1.0, 10], [1, 10, 5]]
+
+sampler = SQASampler()
+response = sampler.sample_ising(h, J, schedule=schedule)
+```