Public interfaces

runMC(param::Parameter)
runMC(params::AbstractArray{Parameter}
      ;
      parallel::Bool=false,
      autoID::Bool=true)

Runs Monte Carlo simulation(s) and returns calculated observables.

Restart

If a checkpoint file named "$(param["Checkpoint Filename Prefix"])_$(param["ID"]).dat" exists and param["Checkpoint Interval"] > 0.0, runMC loads this file and restarts the pending simulation. NOTE: Restart will fail if the version or the system image of julia change (see the doc of Serialization.serialize ).

Keyward arguments

• autoID: If true, "ID"s will be set (overwritten) as params[i]["ID"] = i. Because a child seed is derived from ("Seed", "ID"), this is what makes a set of simulations sharing one "Seed" use distinct random number streams.
• parallel: If true, runs simulations in parallel (uses pmap instead of map).

Required keys in param

• "Model"
• "Lattice"
• "Update Method"

Optional keys in param

• "MCS": The number of Monte Carlo steps after thermalization
  • Default: 8192
• "Thermalization": The number of Monte Carlo steps for thermalization
  • Default: MCS>>3
• "Binning Size": The size of binning
  • Default: 0
• "Number of Bins": The number of bins
  • Default: 0
  • If both "Binning Size" and "Number of Bins" are not given, "Binning Size" is set to floor(sqrt(MCS)).
• "Seed": The initial seed of the random number generator.
  • Default: determined randomly (the generator is seeded from system entropy)
  • When "ID" is also given, a child seed is derived from the pair ("Seed", "ID"), so simulations sharing one seed still use distinct random number streams. The derivation is arithmetic and reproduces across julia versions; it requires "Seed" to be an integer.
• "RNG": The type (not an instance) of the random number generator.
  • Default: Random.Xoshiro
  • Only the constructor the other keys call for is needed: T(seed) when "Seed" is given, T() when it is not. Random.RandomDevice and Random.TaskLocalRNG provide only the latter, so they work only without "Seed".
  • Random.MersenneTwister selects the generator used before v1.3.
• "Checkpoint Filename Prefix": See the "Restart" section.
  • Default: "cp"
• "ID": Job ID. Used both for the checkpoint filename (see the "Restart" section) and, together with "Seed", for deriving a per-job random number stream.
  • Default: 0. Note that no child seed is derived when the key itself is absent, so a single runMC(param) without "ID" depends on "Seed" alone.
• "Checkpoint Interval": Time interval between writing checkpoint file in seconds.
  • Default: 0.0, this means that NO checkpoint file will be loaded and saved.
• "Snapshot Interval": Number of measurement MCS between snapshot writes. This is measured in MCS, not seconds. A value of 0 disables snapshots.
  • Default: 0
  • When restarting with snapshots enabled before and after the checkpoint, changing this value or "Thermalization" is rejected to preserve the snapshot schedule, as is shrinking "MCS" below the progress the checkpoint holds. Parameters driving the chain itself ("Update Method", "T", "J", ...) are not checked: restarting with a different temperature is allowed and produces snapshots that do not correspond to a single simulation.
• "Snapshot Filename Prefix": Prefix for snapshot files. The filename is "<prefix>_<ID>.txt".
  • Default: "snapshot"

dim(lat::Lattice)
dim(model::Model)

Returns the dimension of lattice.

size(lat::Lattice, [dim::Integer])
size(model::Model, [dim::Integer])

Returns the size of lattice.

sites(lat::Lattice, [sitetype::Integer])
sites(model::Model, [sitetype::Integer])

Returns an iterator over sites with sitetype (if omitted, over all sites)

bonds(lat::Lattice, [bondtype::Integer])
bonds(model::Model, [bondtype::Integer])

Returns an iterator over bonds with bondtype (if omitted, over all bonds)

numsites(lat::Lattice)
numsites(model::Model)

Returns the number of all sites.

numsites(lat::Lattice, sitetype::Integer)
numsites(model::Model, sitetype::Integer)

Returns the number of sitetype sites.

numbonds(lat::Lattice)
numbonds(model::Model)

Returns the number of all bonds.

numbonds(lat::Lattice, bondtype::Integer)
numbonds(model::Model, bondtype::Integer)

Returns the number of bondtype bonds.

neighbors(site::Site)
neighbors(lat::Lattice, site::Integer)
neighbors(model::Model, site::Integer)

Returns the index pairs of neighbor sites and bonds of site.

neighborsites(site::Site)
neighborsites(lat::Lattice, site::Integer)
neighborsites(model::Model, site::Integer)

Returns the indecies of neighbor sites of site.

neighborbonds(site::Site)
neighborbonds(lat::Lattice, site::Integer)
neighborbonds(model::Model, site::Integer)

Returns the indecies of neighbor bonds of site.

source(bond::Bond)
source(lat::Lattice, bond::Integer)
source(model::Model, bond::Integer)

Returns the source site index of bond.

target(bond::Bond)
target(lat::Lattice, bond::Integer)
target(model::Model, bond::Integer)

Returns the target site of bond.

sitetype(site::Site)
sitetype(lat::Lattice, site::Integer)
sitetype(model::Model, site::Integer)

Returns the type of site

bondtype(bond::Bond)
bondtype(lat::Lattice, bond::Integer)
bondtype(model::Model, bond::Integer)

Returns the type of bond.

sitecoordinate(site::Site)
sitecoordinate(lat::Lattice, site::Integer)
sitecoordinate(model::Model, site::Integer)

Returns the coordinate of the site in the Cartesian system

bonddirection(bond::Bond)
bonddirection(lat::Lattice, bond::Integer)
bonddirection(model::Model, bond::Integer)

Returns the unnormalized direction of the bond as vector in the Cartesian system

cellcoordinate(site::Site)
cellcoordinate(lat::Lattice, site::Integer)
cellcoordinate(model::Model, site::Integer)

Returns the coordinate of the cell including site in the Lattice system

Ising model with energy $E = -\sum_{ij} J_{ij} \sigma_i \sigma_j$, where $\sigma_i$ takes value of 1 (up spin) or -1 (down spin).

Q state Potts model with energy $E = -\sum_{i,j} \delta_{\sigma_i, \sigma_j}$, where $\sigma_i$ takes an integer value from $1$ to $Q$ and $\delta$ is a Kronecker's delta. Order parameter (total magnetization) is defined as \begin{equation} M = \frac{Q-1}{Q}N1 - \frac{1}{Q}(N-N1), \end{equation} where $N$ is the number of sites and $N_1$ is the number of $\sigma=1$ spins.

Q state clock model with energy $E = -\sum_{ij} J_{ij} \cos(\theta_i - \theta_j)$, where $\theta_i = 2\pi \sigma_i/Q$ and $\sigma_i$ takes an integer value from $1$ to $Q$.

XY model with energy $E = -\sum_{ij} J_{ij} \cos(\theta_i - \theta_j)$, where $\theta_i = 2\pi \sigma_i$ and $\sigma_i \in [0, 1)$.

AshkinTeller model with energy $E = -\sum_{ij} J^\sigma_{ij} \sigma_i \sigma_j + J^\tau_{ij} \tau_i \tau_j + K_{ij} \sigma_i \sigma_j \tau_i \tau_j$, where $\sigma_i$ and $\tau_i$ takes value of 1 (up spin) or -1 (down spin).

Spin-$S$ XXZ model represented as the following Hamiltonian,

$\mathcal{H} = \sum_{i,j} \left[ J_{ij}^z S_i^z S_j^z + \frac{J_{ij}^{xy}}{2} (S_i^+ S_j^- + S_i^-S_j^+) \right] - \sum_i \Gamma_i S_i^x,$

where $S^x, S^y, S^z$ are $x, y$ and $z$ component of spin operator with length $S$, and $S^\pm \equiv S^x \pm iS^y$ are ladder operator. A state is represented by a product state (spins at $\tau=0$) of local $S^z$ diagonal basis and an operator string (perturbations). A local spin with length $S$ is represented by a symmetrical summation of $2S$ sub spins with length $1/2$.

local_update!(model, param)

Updates spin configuration by local spin flip and Metropolice algorithm

SW_update!(model, param::Parameter)

Updates spin configuration by Swendsen-Wang algorithm

Wolff_update!(model, param::Parameter)

Updates spin configuration by Wolff algorithm

loop_update!(model, param::Parameter)

Updates spin configuration by loop algorithm

loop_update!(model, param::Parameter)
loop_update!(model, T::Real,
             Jz::AbstractArray,
             Jxy::AbstractArray,
             Gamma:AbstractArray)

Updates spin configuration by loop algorithm under the temperature T = param["T"] and coupling constants Jz, Jxy and transverse field Gamma

simple_estimator(model::Ising, T::Real, Js::AbstractArray)

Returns the following observables as Dict{String, Any}

Observables

• "Energy"
  • energy density
• "Energy^2"
  • square of energy density
• "Magnetization"
  • magnetization density
• "|Magnetization|"
  • absolute value of magnetization density
• "Magnetization^2"
  • square of magnetization density
• "Magnetization^4"
  • quadruple of magnetization density

simple_estimator(model::Clock, T::Real, Js::AbstractArray)
simple_estimator(model::XY, T::Real, Js::AbstractArray)

Returns the following observables as Dict{String, Any}

Observables

• "Energy"
  • Energy per spin (site)
• "Energy^2"
• "|Magnetization|"
  • Absolute value of total magnetization per spin (order paremeter)
• "|Magnetization|^2"
• "|Magnetization|^4"
• "Magnetization x"
  • x component of total magnetization per spin (order paremeter)
• "|Magnetization x|"
• "Magnetization x^2"
• "Magnetization x^4"
• "Magnetization y"
  • y component of total magnetization per spin (order paremeter)
• "|Magnetization y|"
• "Magnetization y^2"
• "Magnetization y^4"
• "Helicity Modulus x"
• "Helicity Modulus y"

simple_estimator(model::AshkinTeller, T::Real, Jsigma, Jtau, K)

Returns the following observables as Dict{String, Any}

Observables

• "Energy"
  • energy density
• "Energy^2"
  • square of energy density
• "|Magnetization|"
  • absolute value of magnetization density, $|m| = \sqrt{ (\sum_i \sigma_i )^2 + (\sum_i \tau_i)^2 } / N$
• "|Magnetization|^2"
  • square of magnetization density
• "|Magnetization|^4"
  • quadruple of magnetization density
• "Magnetization sigma"
  • magnetization density (sigma spin)
• "|Magnetization sigma|"
• "Magnetization sigma^2"
• "Magnetization sigma^4"
• "Magnetization tau"
  • magnetization density (tau spin)
• "|Magnetization tau|"
• "Magnetization tau^2"
• "Magnetization tau^4"

improved_estimator(model::Ising, T::Real, Js::AbstractArray, sw::SWInfo)

Returns the following observables as Dict{String, Any} using cluster information sw

Observables

• "Energy"
  • energy density
• "Energy^2"
  • square of energy density
• "Magnetization"
  • magnetization density
• "|Magnetization|"
  • absolute value of magnetization density
• "Magnetization^2"
  • square of magnetization density
• "Magnetization^4"
  • quadruple of magnetization density
• "Clustersize^2"
  • $\sum_c r_c^2$, where $r_c$ is the size density of $c$-th cluster
• "Clustersize^4"
  • $\sum_c r_c^4$
• "Clustersize^2 Clustersize^2"
  • $\sum_{c\ne c'} r_c^2 r_{c'}^2$

improved_estimator(model::Potts, T::Real, Js::AbstractArray, sw::SWInfo)

Returns the following observables as Dict{String, Any} using cluster information sw

Observables

• "Energy"
  • energy density
• "Energy^2"
  • square of energy density
• "Magnetization"
  • magnetization density
• "|Magnetization|"
  • absolute value of magnetization density
• "|Magnetization|^2"
  • square of magnetization density
• "|Magnetization|^4"
  • quadruple of magnetization density
• "Clustersize^2"
  • $\sum_c r_c^2$, where $r_c$ is the size density of $c$-th cluster
• "Clustersize^4"
  • $\sum_c r_c^4$
• "Clustersize^2 Clustersize^2"
  • $\sum_{c\ne c'} r_c^2 r_{c'}^2$

improved_estimator(model::QuantumXXZ, T::Real, Js::AbstractArray, uf::UnionFind)

Returns the following observables as Dict{String, Any} using loop information uf

Observables

• "Sign"
  • Sign of the weight function
• "Sign * Energy"
  • Energy per spin (site)
• "Sign * Energy^2"
• "Sign * Magnetization"
  • Total magnetization (Sz) per spin (site)
• "Sign * |Magnetization|"
• "Sign * Magnetization^2"
• "Sign * Magnetization^4"

MCObservable

abstract type representing observable in Monte Carlo calculation.

ScalarObservable <: MCObservable

abstract type representing scalar-type observable in Monte Carlo calculation.

VectorObservable <: MCObservable

abstract type representing vector-type observable in Monte Carlo calculation.

MCObservableSet{Obs}

Alias of `Dict{String, Obs}` where `Obs` is a subtype of `MCObservable`.

makeMCObservable!(oset::MCObservableSet{Obs}, name::String)

Create an observable with the name `name` in the observable set `oset`.

SimpleObservable

A simple observable which stores all the data in memory.

SimpleVectorObservable

A simple observable which stores all the data in memory.

SimpleObservableSet

Alias of `MCObservableSet{SimpleObservable}`.

SimpleObservableSet

Alias of `MCObservableSet{SimpleVectorObservable}`.

binning(obs::SimpleObservable; binsize::Int = 0, numbins::Int = 0)
binning(obs::SimpleVectorObservable; binsize::Int = 0, numbins::Int = 0)

Binning the observable `obs`.
Either `binsize` or `numbins` can be given. If both are given, `ArgumentError` is thrown.
If both are not given, `binsize` is set to `floor(sqrt(count(obs)))`.

Jackknife <: ScalarObservable

Jackknife resampling observable.

JackknifeVector <: VectorObservable

Jackknife resampling observable for vector-type observable.

JackknifeSet

Alias of `MCObservableSet{Jackknife}`.

JackknifeVectorSet

Alias of `MCObservableSet{JackknifeVector}`.

jackknife(obs::ScalarObservable)

Construct a Jackknife observable from a scalar observable

jackknife(obsset::MCObservableSet)

Construct a JackknifeSet from a MCObservableSet

jackknife(obs::VectorObservable)

Construct a JackknifeVector observable from a vector observable

extrapolate_tau(b::BinningObservable, point::Int=5)
extrapolate_tau(b::BinningVectorObservable, point::Int=5)

Extrapolates the autocorrelation time to the infinite bin size limit.

tau is evaluated on the last point binning levels and fitted against the inverse bin size by unweighted least squares; the intercept is the estimate. Returns (value, error) for a scalar observable and (values, errors) for a vector one, where the error is a 1-sigma standard error on the intercept.

Throws ArgumentError if fewer than three binning levels are used for the fit (i.e. min(point, maxlevel(b)) < 3), or if a level holds fewer than two bins and its statistic is therefore not finite.

extrapolate_stderror(b::BinningObservable, point::Int=5)
extrapolate_stderror(b::BinningVectorObservable, point::Int=5)

Extrapolates the standard error to the infinite bin size limit.

Behaves like extrapolate_tau but extrapolates stderror instead of tau. The second element of the return value is a 1-sigma standard error on the extrapolated value, not the extrapolated value's own confidence interval.

snapshot(model::Model)

Return a vector containing the model's current spin configuration. The returned vector does not share memory with the model.

The generic implementation requires model.spins to be an AbstractMatrix{<:Number}. It follows Julia's column-major order. In particular, Ashkin-Teller spins are ordered as σ₁ τ₁ σ₂ τ₂ …; the other classical models have one value per site. For the XY model, each value is the internal σ ∈ [0, 1) representation, with the physical angle given by θ = 2πσ.

save_snapshot(io::IO, model::Model; sep=" ")
save_snapshot(filename::AbstractString, model::Model; sep=" ", append=false)

Write the model's current spin configuration as one line of separator-delimited text. The filename form truncates an existing file unless append=true.

load_snapshots(source; sep=nothing)
load_snapshots(T::Type{<:Number}, source; sep=nothing)

Load separator-delimited snapshot configurations from an IO or filename. Each data line becomes one column of the returned snapshot_length × nconfigs matrix. Lines whose first non-whitespace character is # and lines that split into no tokens are ignored. The default element type is Float64.

gen_snapshot! was removed in v1.3; use the snapshot APIs instead.

gensave_snapshot! was removed in v1.3; use the snapshot APIs instead.

loadsnapshot was removed in v1.3; use `loadsnapshots` instead.

Input parameter of simulation

convert_parameter(model, param)

Generates arguments of updater and estimator.

Example

julia> model = Ising(chain_lattice(4));

julia> p = convert_parameter(model, Parameter("J"=>1.0))
(1.0, [1.0, 1.0]) # T and Js

julia> p = convert_parameter(model, Parameter("J"=>[1.5, 0.5]))
(1.0, [1.5, 0.5]) # J can take a vector whose size is `numbondtypes(model)`

julia> model.spins
4-element Array{Int64,1}:
  1
  1
  1
 -1

julia> local_update!(model, p...);

julia> model.spins
4-element Array{Int64,1}:
  1
  1
 -1
 -1

convert_parameter(model::Ising, param::Parameter)

Keynames:

• "T": a scalar (default: 1.0).
• "J": a vector with numbondtypes(model) elements (default: 1.0).

convert_parameter(model::Potts, param::Parameter)

Keynames:

• "T": a scalar (default: 1.0).
• "J": a vector with numbondtypes(model) elements (default: 1.0).

convert_parameter(model::Clock, param::Parameter)

Keynames:

• "T": a scalar (default: 1.0).
• "J": a vector with numbondtypes(model) elements (default: 1.0).

convert_parameter(model::XY, param::Parameter)

Keynames:

• "T": a scalar (default: 1.0).
• "J": a vector with numbondtypes(model) elements (default: 1.0).

convert_parameter(model::AshkinTeller, param::Parameter)

Keynames:

• "T": a scalar (default: 1.0).
• "Jsigma": a vector with numbondtypes(model) elements (default: 1.0).
• "Jtau": a vector with numbondtypes(model) elements (default: 1.0).
• "K": a vector with numbondtypes(model) elements (default: 0.0).

convert_parameter(model::QuantumXXZ, param::Parameter)

Keynames:

• "T": a scalar (default: 1.0).
• "Jz": a vector with numbondtypes(model) elements (default: 1.0).
• "Jxy": a vector with numbondtypes(model) elements (default: 1.0).
• "Gamma": a vector with numsitetypes(model) elements (default: 0.0).