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 <matijacufar@gmail.com>

* Apply suggestions from code review

Co-authored-by: christofbradly <christof.bradly@gmail.com>

* deprecate instead of remove `targetwalkers`

---------

Co-authored-by: Joachim Brand <joachim.brand@gmail.com>
Co-authored-by: mtsch <matijacufar@gmail.com>
Co-authored-by: christofbradly <christof.bradly@gmail.com>

Author: 3 people

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