# 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`

— Function`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!`

).

`RRRMC.Interface.delta_energy`

— Function`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!`

.

`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:

- when a move is accepted, in
`standardMC`

,`rrrMC`

,`bklMC`

and`wtmMC`

. - 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`

— Function`getN(X::AbstractGraph)`

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

.

`RRRMC.Interface.neighbors`

— Function`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

`RRRMC.Interface.allΔE`

— Function```
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.

## Functions used by `DoubleGraph`

models

`RRRMC.Interface.inner_graph`

— Function`inner_graph(X::DoubleGraph)`

Returns the internal graph used by the given `DoubleGraph`

. The default implementation simply returns `X.X0`

.

`RRRMC.Interface.delta_energy_residual`

— Function`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.

`RRRMC.Interface.update_cache_residual!`

— Function`update_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`

— Function`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).

`RRRMC.QT.transverse_mag`

— Function`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

`RRRMC.RE.REenergies`

— Function`REenergies(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`

— Function`LEenergies(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`

— Function`TLEenergies(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`

— Function`cenergy(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`

— Function`distances(X::DoubleGraph)`

Returns the matrix of the Hamming distances between replicas, in graphs with replicas: `GraphQuant`

, `GraphLocalEntropy`

, `GraphTopologicalLocalEntropy`

or `GraphRobustEnsemble`

.