Merge branch 'develop' into feature/retire-BoseHubbardMom1D2C

.github/workflows/actions.yml

@@ -9,8 +9,10 @@ jobs:
     strategy:
       matrix:
         julia-version: ['1', 'nightly', '1.9']
-        julia-arch: [x64]
         os: [ubuntu-latest]
+        include:
+          - julia-version: '1'
+            os: macos-latest
       fail-fast: false
     steps:
       - name: "Checkout"
@@ -19,7 +21,6 @@ jobs:
         uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.julia-version }}
-          arch: ${{ matrix.julia-arch }}
       - name: "Load cache"
         uses: julia-actions/cache@v2
       - name: "Build"
@@ -39,7 +40,8 @@ jobs:
           # with Pkg.develop(path="."). using Rimu, KrylovKit, StaticArrays at the end
           # ensures everything is precompiled before the MPI job starts.
           julia --color=yes --project=test -e "using Pkg; Pkg.instantiate(); Pkg.develop(path=\".\"); Pkg.add(\"MPI\"); Pkg.build(); using MPI; MPI.install_mpiexecjl(); using Rimu, KrylovKit, StaticArrays"
-          export PATH=$PATH:/home/runner/.julia/bin
+          export PATH=$PATH:/home/runner/.julia/bin # for linux
+          export PATH=$PATH:/Users/runner/.julia/bin # for macos
 
           mpiexecjl -n 2 julia --code-coverage=user --depwarn=yes --project=test test/mpi_runtests.jl
 

.github/workflows/docs.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - develop
+    tags: '*'
   pull_request:
     branches:
       - '*'

Project.toml

@@ -1,7 +1,7 @@
 name = "Rimu"
 uuid = "c53c40cc-bd84-11e9-2cf4-a9fde2b9386e"
 authors = ["Joachim Brand <j.brand@massey.ac.nz>"]
-version = "0.12.0"
+version = "0.13.2-dev"
 
 [deps]
 Arrow = "69666777-d1a9-59fb-9406-91d4454c9d45"
@@ -87,7 +87,7 @@ TOML = "1"
 Tables = "1.9"
 TerminalLoggers = "0.1.4"
 TupleTools = "1"
-VectorInterface = "0.2, 0.3, 0.4"
+VectorInterface = "0.2, 0.3, 0.4, 0.5"
 julia = "1.9"
 
 [extras]

README.md

@@ -1,8 +1,8 @@
 # Rimu
 
-[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://joachimbrand.github.io/Rimu.jl/)
-[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://joachimbrand.github.io/Rimu.jl/dev/)
-[![Coverage Status](https://coveralls.io/repos/github/joachimbrand/Rimu.jl/badge.svg)](https://coveralls.io/github/joachimbrand/Rimu.jl)
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://RimuQMC.github.io/Rimu.jl/)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://RimuQMC.github.io/Rimu.jl/dev/)
+[![Coverage Status](https://coveralls.io/repos/github/RimuQMC/Rimu.jl/badge.svg)](https://coveralls.io/github/RimuQMC/Rimu.jl)
 
 *Random Integrators for many-body quantum systems*
 
@@ -70,4 +70,4 @@ Papers discussing results obtained with `Rimu`:
 - "Polaron-Depleton Transition in the Yrast Excitations of a One-Dimensional Bose Gas with a Mobile Impurity", M. Yang, M. Čufar, E. Pahl, J. Brand, [*Condens. Matter* **7**, 15 (2022)](https://www.mdpi.com/2410-3896/7/1/15).
 - "Magnetic impurity in a one-dimensional few-fermion system", L. Rammelmüller, D. Huber, M. Čufar, J. Brand, A. Volosniev, [arXiv:2204.01606](http://arxiv.org/abs/2204.01606) (2022).
 
-For more information, consult the [documentation](https://joachimbrand.github.io/Rimu.jl/dev/).
+For more information, consult the [documentation](https://RimuQMC.github.io/Rimu.jl/dev/).

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",
         ],
@@ -63,7 +64,6 @@ makedocs(;
             "Dict vectors" => "dictvectors.md",
             "BitString addresses" => "addresses.md",
             "Stochastic styles" => "stochasticstyles.md",
-            "RMPI" => "RMPI.md",
             "I/O" => "rimuio.md",
             "Random numbers" => "randomnumbers.md",
             "Documentation generation" => "documentation.md",
@@ -79,7 +79,7 @@ makedocs(;
 )
 
 deploydocs(
-    repo = "github.com/joachimbrand/Rimu.jl.git",
+    repo = "github.com/RimuQMC/Rimu.jl.git",
     push_preview = true,
 )
 

docs/src/API.md

@@ -34,10 +34,6 @@ See [Module `DictVectors`](@ref)
 
 See [Module `StatsTools`](@ref)
 
-## RMPI
-
-See [Module `RMPI`](@ref)
-
 # Index
 
 ```@index

docs/src/dictvectors.md

@@ -42,6 +42,7 @@ In addition, Rimu defines the following function.
 
 ```@docs
 walkernumber
+walkernumber_and_length
 dot_from_right
 ```
 

docs/src/documentation.md

@@ -27,25 +27,25 @@ deployed automatically with GitHub Actions. This needs to be set up with an appr
 script in the file `.github/workflows/docs.yml`, where triggers for this to happen can be
 defined. In the current set up, a new documentation web site is generated and deployed
 whenever someone pushes to the develop branch on the GitHub server. The updated
-documentation can then be accessed [here](https://joachimbrand.github.io/Rimu.jl/dev/).
+documentation can then be accessed [here](https://RimuQMC.github.io/Rimu.jl/dev/).
 
-Previews for pull-requests can be accessed by replacing 101 in the following link with the PR number: [https://joachimbrand.github.io/Rimu.jl/previews/PR101/](https://joachimbrand.github.io/Rimu.jl/previews/PR101/)
+Previews for pull-requests can be accessed by replacing 101 in the following link with the PR number: [https://RimuQMC.github.io/Rimu.jl/previews/PR101/](https://RimuQMC.github.io/Rimu.jl/previews/PR101/)
 
 ### Example scripts
 
-Examples should be added to the `scripts` folder, in the form of `.jl` files suitable for 
-parsing by [`Literate`](https://github.com/fredrikekre/Literate.jl). The process of generating 
-documentation is automated in the `docs/make.jl` file and assumes that the following line is 
+Examples should be added to the `scripts` folder, in the form of `.jl` files suitable for
+parsing by [`Literate`](https://github.com/fredrikekre/Literate.jl). The process of generating
+documentation is automated in the `docs/make.jl` file and assumes that the following line is
 at (or near) the top of the script:
 ```
 # # Example N: Title
 ```
 where the number `N` and `Title` will be extracted automatically.
 
 Tests for the results and output of specific scripts should be added at the end of each example. The code to run the test should be hidden from the final generated document by
-appending "#hide" to each line of testing code. For example, 
+appending "#hide" to each line of testing code. For example,
 ```
 using Test                          #hide
 @test isfile("result.out")          #hide
 @test result == expected_result     #hide
-```
+```

docs/src/hamiltonians.md

@@ -29,6 +29,7 @@ ExtendedHubbardReal1D
 ```@docs
 HubbardMom1D
 HubbardMom1DEP
+ExtendedHubbardMom1D
 ```
 
 ### Harmonic oscillator models
@@ -67,17 +68,28 @@ Stoquastic
 ```
 
 ## Observables
-Observables are [`AbstractHamiltonian`](@ref)s that represent a physical
-observable. Their ground state expectation values can be sampled by passing
-them into [`AllOverlaps`](@ref).
+`Rimu.jl` offers two other supertypes for operators that are less 
+restrictive than [`AbstractHamiltonian`](@ref). 
+[`AbstractObservable`](@ref) and [`AbstractOperator`](@ref)s both
+can represent a physical observable. Their expectation values can be sampled during a [`ProjectorMonteCarloProblem`](@ref) simulation by 
+passing them into a suitable [`ReplicaStrategy`](@ref), e.g. 
+[`AllOverlaps`](@ref). Some observables are also [`AbstractHamiltonian`](@ref)s. The full type hierarchy is
+```julia
+AbstractHamiltonian{T} <: AbstractOperator{T} <: AbstractObservable{T}
+```
+
 ```@docs
+AbstractObservable
+AbstractOperator
 ParticleNumberOperator
 G2RealCorrelator
 G2RealSpace
 G2MomCorrelator
 SuperfluidCorrelator
 StringCorrelator
 DensityMatrixDiagonal
+SingleParticleExcitation
+TwoParticleExcitation
 Momentum
 AxialAngularMomentumHO
 ```
@@ -110,7 +122,10 @@ random_offdiagonal
 Hamiltonians.LOStructure
 dimension
 has_adjoint
-allowed_address_type
+allows_address_type
+Base.eltype
+VectorInterface.scalartype
+mul!
 ```
 
 This interface relies on unexported functionality, including

docs/src/index.md

@@ -113,8 +113,7 @@ needs to be done for communicating between different processes.
 Using MPI parallelism with `Rimu` is easy. Enabling MPI enabled automatically if
 [`PDVec`](@ref) is used to store a vector. In that case, data will be stored in a
 distributed fashion among the MPI ranks and only communicated between ranks when
-necessary. Additional MPI-related functionality is provided by the module [`RMPI`](@ref
-Rimu.RMPI).
+necessary.
 
 ## Compatibility
 

docs/src/mpi.md

@@ -5,9 +5,6 @@ MPI should be fairly straightforward. Generally, [`PDVec`](@ref Main.DictVectors
 work with MPI automatically, as long as MPI is set up correctly and a few common pitfalls
 are avoided.
 
-Rimu includes an unexported module [`RMPI`](@ref Main.Rimu.RMPI), which must be imported to access
-additional MPI-related functionality.
-
 ## Configuring MPI
 
 When running on a cluster, ensure that MPI.jl is using the system binary. See [the MPI.jl
@@ -16,7 +13,6 @@ documentation](https://juliaparallel.org/MPI.jl/latest/configuration/) for more
 It is always a good idea to start your script with a quick test that ensures the MPI is set up correctly. One way to do this is to open with
 
 ```julia
-using Rimu.RMPI
 mpi_allprintln("hello")
 ```
 
@@ -60,10 +56,9 @@ srun mpi=pmi2 julia --project -tauto script.jl
 ### Using `@mpi_root`
 
 Take care to not use reducing functions (such as `length`, `sum`, `norm`, ...) inside
-[`@mpi_root`](@ref Main.Rimu.RMPI.@mpi_root) blocks. Doing so will only initiate the
-distributed reduction on one rank only, which will cause the code to go out of sync and
-freeze. As an example, to report the current length of a vector, calculate the length before
-the [`@mpi_root`](@ref Main.Rimu.RMPI.@mpi_root) block:
+[`@mpi_root`](@ref) blocks. Doing so will only initiate the distributed reduction on one
+rank only, which will cause the code to go out of sync and freeze. As an example, to report
+the current length of a vector, calculate the length before the [`@mpi_root`](@ref) block:
 
 ```julia
 len = length(pdvec)

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

docs/src/randomnumbers.md

@@ -9,4 +9,4 @@ If you want FCIQMC runs to be reproducible, make sure to seed the RNG with
 [Random.seed!](https://docs.julialang.org/en/v1/stdlib/Random/#Random.seed!).
 
 MPI-distributed runs can also be made reproducible by seeding the RNG with
-[`Rimu.RMPI.mpi_seed!`](@ref).
+[`mpi_seed!`](@ref).