# 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

RRRMC.Interface.energyFunction
energy(X::AbstractGraph, C::Config)

Returns the energy of graph X in the configuration C. This is always invoked at the beginning of standardMC, rrrMC, bklMC and wtmMC. Subsequently, delta_energy is used instead.

All graphs must implement this function.

It must also be used to initialize/reset the cache for a given graph, if any (see update_cache!).

source
RRRMC.Interface.delta_energyFunction
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!.

source
RRRMC.Interface.update_cache!Function
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.

source
RRRMC.Interface.getNFunction
getN(X::AbstractGraph)

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

source
RRRMC.Interface.neighborsFunction
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.

source

## Functions used by DiscrGraph models

RRRMC.Interface.allΔEFunction
allΔE{P<:DiscrGraph}(::Type{P})
allΔE(X::DiscrGraph)

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.

source

## Functions specific to quantum models

RRRMC.QT.QenergyFunction
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).

source
RRRMC.QT.transverse_magFunction
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.

source