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.energy
— Functionenergy(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!
).
RRRMC.Interface.delta_energy
— Functiondelta_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!
.
RRRMC.Interface.update_cache!
— Functionupdate_cache!(X::AbstractGraph, C::Config, move::Int)
A function which is called every time a spin is flipped. This may happen:
- when a move is accepted, in
standardMC
,rrrMC
,bklMC
andwtmMC
. - 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
.
RRRMC.Interface.getN
— FunctiongetN(X::AbstractGraph)
Returns the number of spins for a graph. The default implementation just returns X.N
.
RRRMC.Interface.neighbors
— Functionneighbors(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
RRRMC.Interface.allΔE
— FunctionallΔ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.
Functions used by DoubleGraph
models
RRRMC.Interface.inner_graph
— Functioninner_graph(X::DoubleGraph)
Returns the internal graph used by the given DoubleGraph
. The default implementation simply returns X.X0
.
RRRMC.Interface.delta_energy_residual
— Functiondelta_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.
RRRMC.Interface.update_cache_residual!
— Functionupdate_cache_residual!(X::DoubleGraph, C::Config, move::Int)
Called internally by the default update_cache!
when the argument is a DoubleGraph
. Can be useful to overload this if the residual part of the graph has an indipendent cache.
By default, it does nothing.
Functions specific to quantum models
RRRMC.QT.Qenergy
— FunctionQenergy(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).
RRRMC.QT.transverse_mag
— Functiontransverse_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
RRRMC.RE.REenergies
— FunctionREenergies(X::GraphRobustEnsemble)
Returns a Vector with the individual energy (as defined by the original model) of each replica in a GraphRobustEnsemble
graph.
Functions specific to local-entropy models
RRRMC.LE.LEenergies
— FunctionLEenergies(X::GraphLocalEntropy)
Returns a Vector with the individual energy (as defined by the original model) of each replica in a GraphLocalEntropy
graph.
RRRMC.TLE.TLEenergies
— FunctionTLEenergies(X::GraphTopologicalLocalEntropy)
Returns a Vector with the individual energy (as defined by the original model) of each replica in a GraphTopologicalLocalEntropy
graph.
RRRMC.Interface.cenergy
— Functioncenergy(X::DoubleGraph)
Returns the individual energy (as defined by the original model) of the reference configuration in a GraphLocalEntropy
graph or a GraphTopologicalLocalEntropy
graph.
RRRMC.Interface.distances
— Functiondistances(X::DoubleGraph)
Returns the matrix of the Hamming distances between replicas, in graphs with replicas: GraphQuant
, GraphLocalEntropy
, GraphTopologicalLocalEntropy
or GraphRobustEnsemble
.