Graphs interface

This page contains all the functions which are needed when implementing a graph type. See the built-in graphs for concrete examples (in particular, the SK, RRG and EA family of graphs have the most complete implementations). See also the documentation for the Config type.

Functions used by all graph types

delta_energy(X::AbstractGraph, C::Config, move::Int)

Returns the energy difference that would be associated to flipping the spin move.

A default fallback implementation based on energy is provided, to be used for debugging, but having an efficient implementation for each graph is critical for performance.

Note: when X is a DiscrGraph, the absolute value of the result must be contained in the tuple returned by allΔE – no approximations are allowed, and missing values will cause crashes (unless Julia is run with the --check-bounds=yes option, in which case they will cause errors).

Note: this function is always invoked before performing the flip, unlike in update_cache! and update_cache_residual!.

update_cache!(X::AbstractGraph, C::Config, move::Int)

A function which is called every time a spin is flipped. This may happen:

  1. when a move is accepted, in standardMC, rrrMC, bklMC and wtmMC.
  2. when a move is attempted to evaluate the effect on the neighbors, in rrrMC.

move is the spin index. By default, this function does nothing, but it may be overloaded by particular graph types.

When X is a DoubleGraph, there is a default implementation which first calls update_cache! on inner_graph(X), then calls update_cache_residual! on X.

Note: this function is always invoked after the flip has been performed, unlike in delta_energy and delta_energy_residual.


Returns the number of spins for a graph. The default implementation just returns X.N.

neighbors(X::AbstractGraph, i::Int)

Returns an iterable with all the neighbors of spin i. This is required by rrrMC, bklMC and wtmMC since those methods need to evaluate the effect of flipping a spin on its neighbors' local fields. It is not required by standardMC.

For performance reasons, it is best if the returned value is stack-allocated rather than heap-allocated, e.g. it is better to return an NTuple than a Vector.


Functions used by DiscrGraph models


Returns a tuple of all possible non-negative values that can be returned by delta_energy. This must be implemented by all DiscrGraph objects in order to use rrrMC or bklMC.

The second form above, called directly on the DiscrGraph object, takes precedence; however, for performance reasons, it is best if the result can be computed from the type of the graph alone (possibly using a generated function), i.e. it is best to implement the first definition above — the second one then falls back automatically to the first.


Functions used by DoubleGraph models

delta_energy_residual(X::DoubleGraph, C::Config, move::Int)

Returns the residual part of the energy difference produced if the spin move would be flipped, excluding the contribution from the internal SimpleGraph (see inner_graph).

See also delta_energy. There is a default fallback implementation, but it should be overloaded for efficiency.


Functions specific to quantum models

Qenergy(X::DoubleGraph, C::Config)

When using the Suzuki-Trotter transformation to simulate quantum systems in a transverse magnetic field with a replicated classical system, this function should be used to obtain the average value of the Hamiltonian observable (divided by the number of spins).

transverse_mag(X::DoubleGraph, C::Config, β::Float64)

When using the Suzuki-Trotter transformation to simulate quantum systems in a transverse magnetic field with a replicated classical system, this function should be used to obtain the average value of the transverse magnetization observable.


Functions specific to robust-ensemble models

Functions specific to local-entropy models