Breaking changes before v1.0 release (#268)

* rename df.steps to df.step

* rename :dτ to :time_step in report/DataFrame

* rename update_dτ to update_time_step

* rename :targetwalkers to :target_walkers

* update G2-example.jl

* fix benchmarks

* skip reporting time step if constant

* fix skip reporting time step

* doc page on Projector Monte Carlo

* removing lomc! references from docstrings

* Apply suggestions from code review

Co-authored-by: mtsch <[email protected]>

* Apply suggestions from code review

Co-authored-by: christofbradly <[email protected]>

* deprecate instead of remove `targetwalkers`

---------

Co-authored-by: Joachim Brand <[email protected]>
Co-authored-by: mtsch <[email protected]>
Co-authored-by: christofbradly <[email protected]>

benchmark/benchmarks.jl

@@ -58,7 +58,7 @@ const SUITE = @benchmarkset "Rimu" begin
             ham = HubbardMom1D(addr, u=1.0)
             dv = PDVec(addr => 1.0; style=IsDynamicSemistochastic(), initiator=true)
             post_step = ProjectedEnergy(ham, dv)
-            s_strat = DoubleLogUpdate(targetwalkers=40_000)
+            s_strat = DoubleLogUpdate(target_walkers=40_000)
 
             lomc!(ham, dv; s_strat, post_step, dτ=1e-4, laststep=8000)
         end seconds=150
@@ -67,7 +67,7 @@ const SUITE = @benchmarkset "Rimu" begin
             addr = BoseFS2C(ntuple(i -> ifelse(i == 5, 4, 0), 11), ntuple(==(5), 11))
             ham = BoseHubbardMom1D2C(addr, v=0.1)
             dv = PDVec(addr => 1.0f0; style=IsDynamicSemistochastic{Float32}())
-            s_strat = DoubleLogUpdate(targetwalkers=10_000)
+            s_strat = DoubleLogUpdate(target_walkers=10_000)
             replica_strategy = AllOverlaps(2; operator = ntuple(i -> G2Correlator(i - 1), 7))
 
             lomc!(ham, dv; s_strat, replica_strategy, laststep=2000)
@@ -77,7 +77,7 @@ const SUITE = @benchmarkset "Rimu" begin
             addr = near_uniform(BoseFS{50,50})
             ham = HubbardReal1D(addr, u=6.0)
             dv = PDVec(addr => 1.0; style=IsDynamicSemistochastic())
-            s_strat = DoubleLogUpdate(targetwalkers=50_000)
+            s_strat = DoubleLogUpdate(target_walkers=50_000)
 
             lomc!(ham, dv; s_strat, dτ=1e-4, laststep=1000)
         end seconds=150

docs/make.jl

@@ -54,6 +54,7 @@ makedocs(;
         "Examples" => EXAMPLES_PAIRS[sortperm(EXAMPLES_NUMS)],
         "User documentation" => [
             "Exact Diagonalization" => "exactdiagonalization.md",
+            "Projector Monte Carlo" => "projectormontecarlo.md",
             "StatsTools" => "statstools.md",
             "Using MPI" => "mpi.md",
         ],

docs/src/projectormontecarlo.md

@@ -0,0 +1,45 @@
+# Projector Monte Carlo / FCIQMC
+
+The purpose of Projector Monte Carlo is to stochastically sample the ground state, i.e. the 
+eigenvector corresponding to the lowest eigenvalue of a quantum Hamiltonian, or more generally, 
+a very large matrix. Rimu implements a flavor of Projector Monte Carlo called 
+Full Configuration Interaction Quantum Monte Carlo (FCIQMC).
+
+## `ProjectorMonteCarloProblem`
+
+To run a projector Monte Carlo simulation you set up a problem with `ProjectorMonteCarloProblem`
+and solve it with `solve`. Alternatively you can initialize a `PMCSimulation` struct, `step!` 
+through time steps, and `solve!` it to completion. 
+
+```@docs; canonical=false
+ProjectorMonteCarloProblem
+init
+solve
+solve!
+step!
+```
+
+After `solve` or `solve!` have been called the returned `PMCSimulation` contains the results of 
+the projector Monte Carlo calculation.
+
+### `PMCSimulation` and report as a `DataFrame`
+
+```@docs; canonical=false
+Rimu.PMCSimulation
+```
+
+The `DataFrame` returned from `DataFrame(::PMCSimulation)` contains the time series data from 
+the projector Monte Carlo simulation that is of primary interest for analysis. Depending on the 
+`reporting_strategy` and other options passed as keyword arguments to 
+`ProjectorMonteCarloProblem` it can have different numbers of rows and columns. The rows 
+correspond to the reported time steps (Monte Carlo steps). There is at least one column with the name `:step`. Further columns are usually present with additional data reported from the simulation.
+
+For the default option `algorithm = FCIQMC(; shift_strategy, time_step_strategy)` with a single
+replica (`n_replicas = 1`) and single spectral state, the fields `:shift`, `:norm`, `:len` will 
+be present as well as others depending on the `style` argument and the `post_step_strategy`.
+
+If multiple replicas or spectral states are requested, then the relevant field names in the 
+`DataFrame` will have a suffix identifying the respective replica simulation, e.g. the `shift`s will be reported as `shift_1`, `shift_2`, ... 
+
+Many tools for analysing the time series data obtained from a 
+[`ProjectorMonteCarloProblem`](@ref) are contained in the [Module `StatsTools`](@ref).

scripts/BHM-example-mpi.jl

@@ -57,7 +57,7 @@ problem = ProjectorMonteCarloProblem(H;
     start_at=initial_vector,
     reporting_strategy,
     post_step_strategy=ProjectedEnergy(H, initial_vector),
-    targetwalkers=10_000,
+    target_walkers=10_000,
     time_step=1e-4,
     last_step=10_000
 );

scripts/BHM-example.jl

@@ -29,7 +29,7 @@ H = HubbardReal1D(initial_address; u = 6.0, t = 1.0)
 # use in this Monte Carlo run, which is equivalent to the average one-norm of the
 # coefficient vector. Higher values will result in better statistics, but require more
 # memory and computing power.
-targetwalkers = 1_000;
+target_walkers = 1_000;
 
 # FCIQMC takes a certain number of steps to equllibrate, after which the observables will
 # fluctuate around a mean value. In this example, we will devote 1000 steps to equilibration
@@ -76,7 +76,7 @@ problem = ProjectorMonteCarloProblem(
     start_at = initial_vector,
     last_step,
     time_step,
-    targetwalkers,
+    target_walkers,
     post_step_strategy
 );
 
@@ -91,11 +91,11 @@ df = DataFrame(simulation);
 
 # We can plot the norm of the coefficient vector as a function of the number of steps.
 hline(
-    [targetwalkers];
-    label="targetwalkers", xlabel="steps", ylabel="norm",
+    [target_walkers];
+    label="target_walkers", xlabel="step", ylabel="norm",
     color=2, linestyle=:dash, margin = 1Plots.cm
 )
-plot!(df.steps, df.norm, label="norm", color=1)
+plot!(df.step, df.norm, label="norm", color=1)
 
 # After an initial equilibriation period, the norm fluctuates around the target number of
 # walkers.
@@ -120,11 +120,11 @@ pe = projected_energy(df; skip=steps_equilibrate)
 v = val_and_errs(pe; p=0.95)
 
 # Let's visualise these estimators together with the time series of the shift.
-plot(df.steps, df.shift, ylabel="energy", xlabel="steps", label="shift", margin = 1Plots.cm)
+plot(df.step, df.shift, ylabel="energy", xlabel="step", label="shift", margin = 1Plots.cm)
 
-plot!(x->se.mean, df.steps[steps_equilibrate+1:end], ribbon=se.err, label="shift mean")
+plot!(x->se.mean, df.step[steps_equilibrate+1:end], ribbon=se.err, label="shift mean")
 plot!(
-    x -> v.val, df.steps[steps_equilibrate+1:end], ribbon=(v.val_l,v.val_u),
+    x -> v.val, df.step[steps_equilibrate+1:end], ribbon=(v.val_l,v.val_u),
     label="projected energy",
 )
 lens!([steps_equilibrate, last_step], [-5.1, -2.9]; inset=(1, bbox(0.2, 0.25, 0.6, 0.4)))
@@ -146,7 +146,7 @@ exact_energy = solve(edp).values[1]
 
 println(
     """
-    Energy from $steps_measure steps with $targetwalkers walkers:
+    Energy from $steps_measure steps with $target_walkers walkers:
     Shift: $(se.mean) ± $(se.err)
     Projected Energy: $(v.val) ± ($(v.val_l), $(v.val_u))
     Exact Energy: $exact_energy

scripts/G2-example.jl

@@ -53,20 +53,22 @@ replica_strategy = AllOverlaps(num_replicas; operator = G2list)
 # Other FCIQMC parameters and strategies can be set in the same way as before.
 steps_equilibrate = 1_000
 steps_measure = 5_000
-targetwalkers = 100;
-dτ = 0.001
+target_walkers = 100;
+time_step = 0.001
 
 Random.seed!(17); #hide
 
 # Now, we run FCIQMC. Note that passing an initial vector is optional - if we only pass the
 # style, a vector with the appropriate style is created automatically.
-df, state = lomc!(
-    H; style=IsDynamicSemistochastic(),
-    dτ,
-    laststep = steps_equilibrate + steps_measure,
-    targetwalkers,
+problem = ProjectorMonteCarloProblem(H;
+    style=IsDynamicSemistochastic(),
+    time_step,
+    last_step = steps_equilibrate + steps_measure,
+    target_walkers,
     replica_strategy,
-);
+)
+result = solve(problem)
+df = DataFrame(result);
 
 # The output `DataFrame` has FCIQMC statistics for each replica (e.g. shift, norm),
 println(filter(startswith("shift_"), names(df)))

src/DictVectors/initiatordvec.jl

@@ -1,7 +1,8 @@
 """
     InitiatorDVec{K,V} <: AbstractDVec{K,V}
 
-Dictionary-based vector-like data structure for use with [`lomc!`](@ref Main.lomc!) and
+Dictionary-based vector-like data structure for use with
+[`ProjectorMonteCarloProblem`](@ref Main.ProjectorMonteCarloProblem) and
 [`KrylovKit.jl`](https://github.com/Jutho/KrylovKit.jl). See [`AbstractDVec`](@ref).
 Functionally identical to [`DVec`](@ref), but contains [`InitiatorValue`](@ref)s internally
 in order to facilitate initiator methods. Initiator methods for controlling the Monte Carlo

src/DictVectors/projectors.jl

@@ -10,7 +10,7 @@ products. Implemented subtypes:
 - [`Norm2Projector`](@ref)
 - [`Norm1ProjectorPPop`](@ref)
 
-See also [`PostStepStrategy`](@ref Main.PostStepStrategy) for use of projectors in [`lomc!`](@ref Main.lomc!).
+See also [`PostStepStrategy`](@ref Main.PostStepStrategy) for use of projectors in [`ProjectorMonteCarloProblem`](@ref Main.ProjectorMonteCarloProblem).
 
 ## Interface
 
@@ -33,7 +33,7 @@ dot(UniformProjector(), LO, v) == sum(LO*v)
 ```
 
 See also [`PostStepStrategy`](@ref Main.PostStepStrategy), and [`AbstractProjector`](@ref) for use
-of projectors in [`lomc!`](@ref Main.lomc!).
+of projectors in [`ProjectorMonteCarloProblem`](@ref Main.ProjectorMonteCarloProblem).
 """
 struct UniformProjector <: AbstractProjector end
 
@@ -60,7 +60,7 @@ dot(NormProjector(),x)
 `NormProjector()` thus represents the vector `sign.(x)`.
 
 See also [`PostStepStrategy`](@ref Main.PostStepStrategy), and [`AbstractProjector`](@ref) for use
-of projectors in [`lomc!`](@ref Main.lomc!).
+of projectors in [`ProjectorMonteCarloProblem`](@ref Main.ProjectorMonteCarloProblem).
 """
 struct NormProjector <: AbstractProjector end
 
@@ -75,7 +75,7 @@ dot(NormProjector(),x)
 ```
 
 See also [`PostStepStrategy`](@ref Main.PostStepStrategy), and [`AbstractProjector`](@ref) for use
-of projectors in [`lomc!`](@ref Main.lomc!).
+of projectors in [`ProjectorMonteCarloProblem`](@ref Main.ProjectorMonteCarloProblem).
 """
 struct Norm2Projector <: AbstractProjector end
 
@@ -92,7 +92,7 @@ dot(Norm1ProjectorPPop(),x)
 ```
 
 See also [`PostStepStrategy`](@ref Main.PostStepStrategy), and [`AbstractProjector`](@ref) for use
-of projectors in [`lomc!`](@ref Main.lomc!).
+of projectors in [`ProjectorMonteCarloProblem`](@ref Main.ProjectorMonteCarloProblem).
 """
 struct Norm1ProjectorPPop <: AbstractProjector end
 
@@ -121,7 +121,7 @@ dot(PopsProjector(),x)
 ```
 
 See also [`PostStepStrategy`](@ref Main.PostStepStrategy), and [`AbstractProjector`](@ref) for use
-of projectors in [`lomc!`](@ref Main.lomc!).
+of projectors in [`ProjectorMonteCarloProblem`](@ref Main.ProjectorMonteCarloProblem).
 """
 struct PopsProjector <: AbstractProjector end
 

src/Hamiltonians/MatrixHamiltonian.jl

@@ -4,7 +4,7 @@
         starting_address::Int = starting_address(mat)
     ) <: AbstractHamiltonian{T}
 Wrap an abstract matrix `mat` as an [`AbstractHamiltonian`](@ref) object.
-Works with stochastic methods of [`lomc!()`](@ref) and [`DVec`](@ref).
+Works with stochastic methods of [`ProjectorMonteCarloProblem()`](@ref) and [`DVec`](@ref).
 Optionally, a valid index can be provided as the [`starting_address`](@ref).
 
 Specialised methods are implemented for sparse matrices of type `AbstractSparseMatrixCSC`.

src/Hamiltonians/correlation_functions.jl

@@ -392,7 +392,7 @@ Assumes a one-dimensional lattice with ``M`` sites and periodic boundary conditi
 
 # Usage
 Superfluid correlations can be extracted from a Monte Carlo calculation by wrapping `SuperfluidCorrelator` with
-[`AllOverlaps`](@ref) and passing into [`lomc!`](@ref) with the `replica` keyword argument. For an example with a
+[`AllOverlaps`](@ref) and passing into [`ProjectorMonteCarloProblem`](@ref) with the `replica` keyword argument. For an example with a
 similar use of [`G2RealCorrelator`](@ref) see
 [G2 Correlator Example](https://joachimbrand.github.io/Rimu.jl/previews/PR227/generated/G2-example.html).
 

src/Interfaces/Interfaces.jl

@@ -7,7 +7,9 @@ This module contains interfaces that can be used to extend and modify the algori
 Follow the links for the definitions of the interfaces!
 * [`AbstractHamiltonian`](@ref) for defining [`Hamiltonians`](@ref Main.Hamiltonians)
 * [`AbstractDVec`](@ref) for defining data structures for `Rimu` as in [`DictVectors`](@ref Main.DictVectors)
-* [`StochasticStyle`](@ref) for controlling the stochastic algorithms used by [`lomc!`](@ref Main.lomc!) as implemented in [`StochasticStyles`](@ref Main.StochasticStyles)
+* [`StochasticStyle`](@ref) for controlling the stochastic algorithms used by
+  [`ProjectorMonteCarloProblem`](@ref Main.ProjectorMonteCarloProblem) as implemented in
+  [`StochasticStyles`](@ref Main.StochasticStyles)
 
 # Additional exports
 

src/Interfaces/dictvectors.jl

@@ -5,7 +5,8 @@ Abstract data type for vector-like data structures with sparse storage. While co
 `AbstractDVec`s represent elements of a vector space over a scalar type `V`, they are
 indexed by an arbitrary type `K` (could be non-integers) similar to dictionaries. They
 support the interface from [VectorInterface.jl](https://github.com/Jutho/VectorInterface.jl)
-and are designed to work well for quantum Monte Carlo with [`lomc!`](@ref Main.lomc!) and
+and are designed to work well for quantum Monte Carlo with
+[`ProjectorMonteCarloProblem`](@ref Main.ProjectorMonteCarloProblem) and
 for matrix-free linear algebra with [KrylovKit](https://github.com/Jutho/KrylovKit.jl).
 
 Concrete implementations are available as [`PDVec`](@ref Main.DictVectors.PDVec),

src/Interfaces/hamiltonians.jl

@@ -5,7 +5,8 @@
     AbstractHamiltonian{T}
 
 Supertype that provides an interface for linear operators over a linear space with scalar
-type `T` that are suitable for FCIQMC (with [`lomc!`](@ref Main.lomc!)). Indexing is done
+type `T` that are suitable for FCIQMC (with
+[`ProjectorMonteCarloProblem`](@ref Main.ProjectorMonteCarloProblem)). Indexing is done
 with addresses (typically not integers) from an address space that may be large (and will
 not need to be completely generated).
 

src/Interfaces/stochasticstyles.jl

@@ -7,7 +7,8 @@ generalised vector `v` that determines how simulations are to proceed.
 # Usage
 
 Concrete `StochasticStyle`s can be used for the `style` keyword argument of
-[`lomc!`](@ref Main.lomc!), [`DVec`](@ref Main.DictVectors.DVec) and
+[`ProjectorMonteCarloProblem`](@ref Main.ProjectorMonteCarloProblem),
+[`DVec`](@ref Main.DictVectors.DVec) and
 [`PDVec`](@ref Main.DictVectors.PDVec). The following styles are available:
 
 * [`IsStochasticInteger`](@ref Main.StochasticStyles.IsStochasticInteger)
@@ -22,7 +23,7 @@ Concrete `StochasticStyle`s can be used for the `style` keyword argument of
 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!`](@ref Main.lomc!), a `StochasticStyle` must define the
+For it to work with [`ProjectorMonteCarloProblem`](@ref Main.ProjectorMonteCarloProblem), a `StochasticStyle` must define the
 following:
 
 * [`apply_column!(::StochasticStyle, w, H, address, value)`](@ref)
@@ -123,7 +124,8 @@ end
     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!`](@ref Main.lomc!).
+length. These will be reported as columns in the `DataFrame` returned by
+[`ProjectorMonteCarloProblem`](@ref Main.ProjectorMonteCarloProblem).
 """
 step_stats(v) = step_stats(StochasticStyle(v))
 

src/StatsTools/growth_witness.jl

@@ -32,7 +32,12 @@ function growth_witness(shift::AbstractArray, norm::AbstractArray, dt, b; kwargs
     return smoothen(g_raw, b)
 end
 """
-    growth_witness(df::DataFrame, [b]; shift=:shift, norm=:norm, dτ=df.dτ[end], skip=0)
+    growth_witness(df::DataFrame, [b];
+        shift=:shift,
+        norm=:norm,
+        time_step=determine_constant_time_step(df),
+        skip=0
+    )
     growth_witness(sim::PMCSimulation, [b]; kwargs...)
 
 Calculate the growth witness directly from the result (`DataFrame` or
@@ -43,14 +48,14 @@ Calculate the growth witness directly from the result (`DataFrame` or
 """
 function growth_witness(
     sim, b=Val(0);
-    shift=:shift, norm=:norm, dτ=nothing, kwargs...
+    shift=:shift, norm=:norm, time_step=nothing, kwargs...
 )
     df = DataFrame(sim)
-    dτ = determine_constant_time_step(df)
+    time_step = determine_constant_time_step(df)
 
     shift_vec = getproperty(df, Symbol(shift))
     norm_vec = getproperty(df, Symbol(norm))
-    return growth_witness(shift_vec, norm_vec, dτ, b; kwargs...)
+    return growth_witness(shift_vec, norm_vec, time_step, b; kwargs...)
 end
 
 """