Interfaces

The type used to define models that can be simulated by StochasticSeriesExpansion.jl.

Models are expected to have a constructor

YourModel(parameters::AbstractDict{Symbol, <:Any})

that gets passed the Carlo.jl task parameters that can be used to describe all parameters of your model, such as the lattice or the coupling strengths.

Apart from this, methods for the following functions should be implemented:

• generate_sse_data
• get_opstring_estimators
• leg_count
• normalization_site_count

generate_sse_data(model::YourModel) -> SSEData

This function should translate the data saved in the model to construct the information needed by the abstract-loop SSE algorithm:

• a graph of bonds
• the bond Hamiltonians

From this information an SSEData instance can be constructed and returned.

get_opstring_estimators(model::YourModel) -> Vector{Type{<:AbstractOpstringEstimator}}

Returns an array of types of operator string estimators that are used to calculate most observables. Each of them should implement the Operator string estimator interface.

leg_count(model::Type{YourModel}) -> Integer

This function returns the maximum number of legs a bond operator can have in the model.

In the SSE algorithm, the Hamiltonian is decomposed into bond operators that (ideally) act on only a few sites. For example, the Heisenberg model consists of operators that act on two sites. In a diagrammatic picture, each site corresponds to one incoming and one outgoing leg. Therefore, the leg count in the Heisenberg model is four.

Operators with differing leg-counts are supported within the same model. In such cases, leg_count should return the maximum.

normalization_site_count(model::YourModel) -> Integer

The number of physical sites used for normalizing observables. It may differ from the SSE algorithmic site count sometimes, e.g. when the computational basis consists of multiple physical spins but we still want the energy to be measured per spin.

This interface allows defining observable estimators that act on each operator of the the SSE operator string. The measurement code will call the functions of this interface like the following. However, for efficiency reasons, multiple estimators are automatically fused into a single loop.

est = init(YourEstimator, model, state)
for op in operators
    if isidentity(op)
        continue
    end

    if !isdiagonal(op)
        # update state
    end

    if n < num_operators
        measure(est, op, state, sse_data)
    end
    n += 1
end

result(est, mccontext, T, sign)

However, in practice, StochasticSeriesExpansion will interlace different estimators into the same loop for efficiency.

A reference implementation is in the model-generic MagnetizationEstimator, which can be used for most magnetization-like observables.

init(::Type{YourOpstringEstimator},
     model::AbstractModel,
     state::AbstractVector{<:StateIndex}) -> YourOpstringEstimator

Constructs an opstring estimator based on a model and an initial state. The state is a vector of integers labelling the computational site basis states. The estimator needs to interpret them in terms of physical quantities.

measure(est, op::OperCode, state::AbstractVector{<:StateIndex}, sse_data::SSEData)

Perform the in-string measurement of estimator est on each operator op in the operator string. The state at the current position and the sse_data object are passed for additional reference.

result(est, ctx::Carlo.MCContext, T::AbstractFloat, sign::AbstractFloat)

Finalize the measurement by saving the results to the Carlo MCContext, e.g. by calling measure!(ctx, :Magnetization, est.mag). For more information, consult the Carlo documentation.

For some observables, knowing the temperature T is necessary. In the case of a signful simulation, sign != 1 should be taken into account.

register_evaluables(
    ::Type{<:YourOpstringEstimator},
    eval::AbstractEvaluator,
    params::AbstractDict
)

Operator string estimators est can define their own evaluables using this function, which passes a AbstractEvaluator and the task parameters. The state of the estimator is unavailable here since this runs in the postprocessing step.

MagnetizationEstimator{
    OrderingVector,
    StaggerUC,
    Model,
    Prefix} <: AbstractOpstringEstimator

Generic operator string estimator that can be used for all models that have

• a field lattice::Lattice
• implement magnetization_state.

optionally, magnetization_lattice_site_idx.

It computes the

• :Mag, magnetization $\langle m\rangle$
• :AbsMag, absolute magnetization $\langle |m|\rangle$
• :Mag2, squared magnetization $\langle m^2\rangle$
• :Mag4, quartic magnetization $\langle m^4\rangle$
• :MagChi, susceptibility $N \int_0^\beta d\tau \langle m(\tau) m\rangle$
• :BinderRatio, Binder ratio $\langle m^2\rangle^2/\langle m^4\rangle$

Here, $m = \frac{1}{N} \sum_i m_i$, the $m_i$ are given by magnetization_state and $N$ is returned by normalization_site_count.

Type parameters

• OrderingVector: Fourier component to compute in units of π. For example $(1,1)$ corresponds to $(π,π)$
• If StaggerUC is true, the sublattice sign of the unitcell is additionally taken into account.
• Model: model type to apply this estimator to.
• Prefix: (Symbol) this prefix is added to all observable names. Consider using magnetization_estimator_standard_prefix.

magnetization_state(model::AbstractModel, ::Val{Tag}, site_idx, state_idx) where {Tag}

Returns the magnetization at site site_idx for the state state_idx. Tag can be used to dispatch on different “kinds” of magnetization in models that have more than one relevant quantum number per site.

magnetization_lattice_site_idx(model::AbstractModel, sse_site_idx) -> Integer

In models where additional degrees of freedom exist, this function maps sse site indices to physical lattice site indices.

magnetization_estimator_standard_prefix(q::Tuple{Bool...}, stagger_uc::Bool)

Returns the conventional prefix for a magnetization estimator with ordering vector q and stagger_uc set.