Module StochasticStyles

This module provides concrete implementations of StochasticStyles, which specify the algorithm used by lomc! when performing stochastic matrix-vector multiplication.

Implemented stochastic styles:

• StochasticStyle: abstract type for stochastic styles
• IsStochasticInteger
• IsDeterministic
• IsStochasticWithThreshold
• IsDynamicSemistochastic
• StyleUnknown

The offdiagonal spawning is defined in spawning.jl and is controlled by setting a SpawningStrategy.

The vector compression strategies are defined in compression.jl and are controlled by setting a CompressionStrategy.

StyleUnknown{T}() <: StochasticStyle

Trait for value types not (currently) compatible with FCIQMC. This style makes it possible to construct dict vectors with unsupported valtypes.

See also StochasticStyle.

IsDeterministic{T=Float64}(compression=NoCompression()) <: StochasticStyle{T}

Propagate with deterministic vector matrix multiplications. Stochastic compression of the resultant vector (after annihilations) can be triggered by setting the optional compression argument to a relevant CompressionStrategy.

See also StochasticStyle.

IsDynamicSemistochastic{T=Float64}(; kwargs...) <: StochasticStyle{T}

QMC propagation with floating-point walker numbers and reduced noise. All possible spawns (offdiagonal elements in vector-matrix multiplication) are performed deterministically when number of walkers in a configuration is high, as controlled by the rel_spawning_threshold and abs_spawning_threshold keywords. Stochastic selection of spawns is controlled by the spawning keyword.

By default, a stochastic vector compression is applied after annihilations are completed. This behaviour can be changed to on-the-fly projection (as in IsStochasticInteger or IsStochasticWithThreshold) by setting late_compression=false, or modifying spawning and compression. See parameters below for a more detailed explanation.

Parameters:

• threshold = 1.0: Values below this number are stochastically projected to this value or zero. See also ThresholdCompression.

• late_compression = true: If this is set to true, stochastic vector compression is performed after all the spawns are performed. If it is set to false, values are stochastically projected as they are being spawned. late_compression=true is equivalent to setting compression=ThresholdCompression(threshold) and spawning=WithReplacement(). late_compression=false is equivalent to compression=NoCompression() and spawning=WithReplacement(threshold).

• rel_spawning_threshold = 1.0: If the walker number on a configuration times this threshold is greater than the number of offdiagonals, spawning is done deterministically. Should be set to 1 or more for best performance.

• abs_spawning_threshold = Inf: If the walker number on a configuration is greater than this value, spawning is done deterministically. Can be set to e.g. abs_spawning_threshold = 0.1 * target_walkers.

• spawning = WithReplacement(): SpawningStrategy to use for the non-exact spawns.

• compression = ThresholdCompression(threshold): CompressionStrategy used to compress the vector after a step. Overrides threshold.

See also StochasticStyle.

IsStochastic2Pop{T=Complex{Int}}() <: StochasticStyle{T}

Stochastic propagation with complex walker numbers representing two populations of integer walkers.

When using this style, make sure to set a complex number as target walkers in the ShiftStrategy!

This style is experimental.

See also StochasticStyle.

IsStochasticInteger{T=Int}() <: StochasticStyle{T}

FCIQMC algorithm with integer walkers as in Booth et al. (2009). During the vector matrix product each individual diagonal and spawning step is rounded stochastically to a nearby integer value.

See also StochasticStyle.

IsStochasticWithThreshold{T=Float64}(threshold=1.0) <: StochasticStyle{T}

Stochastic propagation with floating point walker numbers. During the vector matrix product each individual diagonal and spawning result is rounded stochastically if smaller than threshold (before annihilations). For a more customizable stochastic style, see IsDynamicSemistochastic.

See also StochasticStyle.

StochasticStyle(v)

Abstract type. When called as a function it returns the native style of the generalised vector v that determines how simulations are to proceed.

Usage

Concrete StochasticStyles can be used for the style keyword argument of lomc!, DVec and PDVec. The following styles are available:

• IsStochasticInteger
• IsDeterministic
• IsStochasticWithThreshold
• IsDynamicSemistochastic
• StyleUnknown

Extended Help

Interface

When defining a new StochasticStyle, subtype it as MyStyle<:StochasticStyle{T} where T is the concrete value type the style is designed to work with.

For it to work with lomc!, a StochasticStyle must define the following:

• apply_column!(::StochasticStyle, w, H, address, value)
• step_stats(::StochasticStyle)

and optionally

• CompressionStrategy(::StochasticStyle) for vector compression after annihilations,

See also StochasticStyles, Interfaces.

step_stats(::StochasticStyle)
step_stats(::CompressionStrategy)

Return a tuple of stat names (Symbol or String) and a tuple of zeros of the same length. These will be reported as columns in the DataFrame returned by lomc!.

apply_column!(v, op, addr, num, boost=1) -> stats::Tuple

Apply the product of column addr of the operator op and the scalar num to the vector v according to the StochasticStyle of v. By expectation value this should be equivalent to

v .+= op[:, add] .* num

This is used to perform the spawning step in FCIQMC and to implement operator-vector multiplications. Mutates v and reports spawning statistics.

The boost argument multiplicatively increases the number of spawns to be performed without affecting the expectation value of the procedure.

default_style(::Type)

Pick a StochasticStyle based on the value type. Returns StyleUnknown if no known default style is set.

CompressionStrategy

The CompressionStrategy controls how a vector is compressed after a step.

Default implementation:

• NoCompression: no vector compression

Usage

A subtype of CompressionStrategy can be passed as a keyword argument to the constructors for some StochasticStyles. Calling CompressionStrategy(s::StochasticStyle) returns a relevant subtype. The default is NoCompression.

Interface

When defining a new CompressionStrategy, subtype it as MyCompressionStrategy <: CompressionStrategy and define these methods:

• compress!(s::CompressionStrategy, v)
• compress!(s::CompressionStrategy, w, v)
• step_stats(s::CompressionStrategy)

NoCompression <: CompressionStrategy end

Default CompressionStrategy. Leaves the vector intact.

ThresholdCompression(threshold=1) <: CompressionStrategy

CompressionStrategy that compresses a vector by threshold projection. Every entry in the vector with a value below the threshold is either set to zero, or increased to the threshold. The probabilty of setting it to zero is equal to abs(value) / threshold.

compress!([::CompressionStrategy,] v) -> ::NTuple{N,::Symbol}, ::NTuple{N}
compress!([::CompressionStrategy,] w, v) -> ::NTuple{N,::Symbol}, ::NTuple{N}

Compress the vector v. The one-argument version compresses the vector in-place. The two-argument vector stores the result in w. The CompressionStrategy associated with the StochasticStyle of v is used to determine the type of compression.

Returns two tuples, containing the names and values of statistics that are to be reported.

diagonal_step!(w, op, add, val, threshold=0) -> (clones, deaths, zombies)

Perform diagonal step on a walker add => val. Optional argument threshold sets the projection threshold. If eltype(w) is an Integer, the val is rounded to the nearest integer stochastically.

projected_deposit!(w, add, val, parent, threshold=0)

Like deposit!, but performs threshold projection before spawning. If eltype(w) is an Integer, values are stochastically rounded.

Returns the value deposited.

spawn!(s::SpawningStrategy, w, op::AbstractHamiltonian, add, val, boost)
spawn!(s::SpawningStrategy, w, offdiags::AbstractOffdiagonals, add, val, boost)

Perform stochastic spawns to w from address add with val walkers. val * boost controls the number of spawns performed.

This function should be overloaded in the second form, with offdiags as an argument.

See SpawningStrategy.

Bernoulli(threshold=0.0) <: SpawningStrategy

Perform Bernoulli sampling. A spawn is attempted on each offdiagonal element with a probability that results in an expected number of spawns equal to the number of walkers on the spawning configuration. This is significantly less efficient than WithReplacement.

If the number of spawn attempts is greater than the number of offdiagonals, this functions like Exact, but is less efficient. For best performance, this strategy is to be used as a substrategy of DynamicSemistochastic.

Parameters

• threshold sets the projection threshold.

spawn! with this strategy returns the number of spawn attempts and the number of spawns.

DynamicSemistochastic(; strat, rel_threshold, abs_threshold) <: SpawningStrategy

SpawningStrategy that behaves like strat when the number of walkers is low, but performs exact steps when it is high. What "high" means is controlled by the two thresholds described below.

Parameters

• strat = WithReplacement(): a SpawningStrategy to use when the multiplication is not performed exactly. If the strat has a threshold different from zero, all spawns will be projected to that threshold.

• rel_threshold = 1.0: When deciding on whether to perform an exact spawn, this value is multiplied to the number of walkers. Should be set to 1 or more for best performance. This threshold is affected by the boost argument to spawn!.

• abs_threshold = Inf: When deciding on whether to perform an exact spawn, min(abs_threshold, num_offdiagonals) is used. This threshold is not affected by the boost argument to spawn!.

See e.g. WithoutReplacement for a description of the strat.threshold parameter.

spawn! with this strategy returns the numbers of exact and inexact spawns, the number of spawn attempts and the number of spawns.

Exact(threshold=0.0) <: SpawningStrategy

Perform an exact spawning step.

Parameters

• threshold sets the projection threshold. If set to zero, no projection is performed.

spawn! with this strategy returns the number of spawn attempts and the number of spawns.

SingleSpawn(threshold=0.0) <: SpawningStrategy

Perform a single spawn. Useful as a building block for other stochastic styles.

Parameters

• threshold sets the projection threshold. If set to zero, no projection is performed.

spawn! with this strategy returns the number of spawn attempts (always 1) and the number of spawns.

SpawningStrategy

A SpawningStrategy is used to control how spawns (multiplies with off-diagonal part of the column vector) are performed and can be passed to some of the StochasticStyles as keyword arguments.

The following concrete implementations are provided:

• Exact: Perform exact spawns. Used by IsDeterministic.

• WithReplacement: The default stochastic spawning strategy. Spawns are chosen with replacement.

• DynamicSemistochastic: Behave like Exact when the number of spawns performed is high, and like a different substrategy otherwise. Used by IsDynamicSemistochastic.

• SingleSpawn: Perform a single spawn only. Used as a building block for other strategies.

• WithoutReplacement: Similar to WithReplacement, but ensures each spawn is only performed once. Only to be used as a substrategy of DynamicSemistochastic.

• Bernoulli: Each spawn is attempted with a fixed probability. Only to be used as a substrategy of DynamicSemistochastic.

Interface

In order to implement a new SpawningStrategy, define a method for spawn!.

WithReplacement(threshold=0.0) <: SpawningStrategy

SpawningStrategy where spawn targets are sampled with replacement. This is the default spawning strategy for most of the StochasticStyles.

Parameters

• threshold sets the projection threshold. If set to zero, no projection is performed.

spawn! with this strategy returns the number of spawn attempts and the number of spawns.

WithoutReplacement(threshold=0.0) <: SpawningStrategy

SpawningStrategy where spawn targets are sampled without replacement. This strategy needs to allocate a temporary array during spawning, which makes it significantly less efficient than WithReplacement.

If the number of spawn attempts is greater than the number of offdiagonals, this functions like Exact, but is less efficient. For best performance, this strategy is to be used as a substrategy of DynamicSemistochastic.

Parameters

• threshold sets the projection threshold. If set to zero, no projection is performed.

spawn! with this strategy returns the number of spawn attempts and the number of spawns.