Merge branch 'develop' into feature/save-state

.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
 

Project.toml

@@ -1,7 +1,7 @@
 name = "Rimu"
 uuid = "c53c40cc-bd84-11e9-2cf4-a9fde2b9386e"
 authors = ["Joachim Brand <[email protected]>"]
-version = "0.13.0"
+version = "0.14.0"
 
 [deps]
 Arrow = "69666777-d1a9-59fb-9406-91d4454c9d45"
@@ -39,6 +39,7 @@ StrLiterals = "68059f60-971f-57ff-a2d0-18e7de9ccc84"
 TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
 Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
 TerminalLoggers = "5d786b92-1e48-4d6f-9151-6b4477ca9bed"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 TupleTools = "9d95972d-f1c8-5527-a6e0-b4b365fa01f6"
 VectorInterface = "409d34a3-91d5-4945-b6ec-7529ddf182d8"
 
@@ -87,14 +88,13 @@ 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]
 Arpack = "7d9fca2a-8960-54d3-9f78-7d1dccf2cb97"
 IterativeSolvers = "42fd0dbc-a981-5370-80f2-aaf504508153"
 KrylovKit = "0b1a1467-8014-51b9-945f-bf0ae24f4b77"
-Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
 test = ["Test"]

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

@@ -63,16 +63,6 @@ const SUITE = @benchmarkset "Rimu" begin
             lomc!(ham, dv; s_strat, post_step, dτ=1e-4, laststep=8000)
         end seconds=150
 
-        @case "(4+1, 11) 2C Mom space with G2Correlators" 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(target_walkers=10_000)
-            replica_strategy = AllOverlaps(2; operator = ntuple(i -> G2Correlator(i - 1), 7))
-
-            lomc!(ham, dv; s_strat, replica_strategy, laststep=2000)
-        end seconds=150
-
         @case "(50, 50) Real space" begin
             addr = near_uniform(BoseFS{50,50})
             ham = HubbardReal1D(addr, u=6.0)

docs/make.jl

@@ -43,7 +43,7 @@ for fn in EXAMPLES_FILES
 end
 
 makedocs(;
-    modules=[Rimu,Rimu.RimuIO],
+    modules=[Rimu,Rimu.RimuIO,Rimu.InterfaceTests],
     format=Documenter.HTML(
         prettyurls = false,
         size_threshold=700_000, # 700 kB
@@ -55,18 +55,17 @@ makedocs(;
         "User documentation" => [
             "Exact Diagonalization" => "exactdiagonalization.md",
             "Projector Monte Carlo" => "projectormontecarlo.md",
+            "Hamiltonians" => "hamiltonians.md",
             "StatsTools" => "statstools.md",
             "Using MPI" => "mpi.md",
+            "Custom Hamiltonians" => "custom_hamiltonians.md",
         ],
         "Developer documentation" => [
             "Interfaces" => "interfaces.md",
-            "Hamiltonians" => "hamiltonians.md",
             "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",
             "Code testing" => "testing.md",
         ],
@@ -80,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/custom_hamiltonians.md

@@ -0,0 +1,110 @@
+# Advanced operator usage and custom Hamiltonians
+
+`Rimu` can be used to work with custom Hamiltonians and observables that are user-defined and
+ not part of the `Rimu.jl` package. To make this possible and reliable, `Rimu` exposes a number 
+ of interfaces and provides helper functions to test compliance with the interfaces through the 
+ submodule [`Rimu.InterfaceTests`](@ref), see [Interface tests](@ref). This section covers the
+ relevant interfaces, the interface functions as well as potentially useful helper functions.
+
+ In order to define custom Hamiltonians or observables it is useful to know how the operator 
+ type hierarchy works in `Rimu`. For an example of how to implement custom Hamiltonians that 
+ are not part of the `Rimu.jl` package, see 
+ [`RimuLegacyHamiltonians.jl`](https://github.com/RimuQMC/RimuLegacyHamiltonians.jl).
+
+## Operator type hierarchy
+
+`Rimu` offers a hierarchy of abstract types that define interfaces with different requirements
+for operators:
+```julia
+AbstractHamiltonian <: AbstractOperator <: AbstractObservable
+```
+The different abstract types have different requirements and are meant to be used for different purposes. 
+- [`AbstractHamiltonian`](@ref)s are fully featured models that define a Hilbert space and a linear operator over a scalar field. They can be passed as a Hamiltonian into [`ProjectorMonteCarloProblem`](@ref) or [`ExactDiagonalizationProblem`](@ref).
+- [`AbstractOperator`](@ref) and [`AbstractObservable`](@ref) are supertypes of [`AbstractHamiltonian`](@ref) with less stringent conditions. They are useful for defining observables that can be used in a three-way `dot` product, or passed as observables into a [`ReplicaStrategy`](@ref) that can be inserted with the keyword `replica_strategy` into a [`ProjectorMonteCarloProblem`](@ref).
+
+## Hamiltonians interface
+
+Behind the implementation of a particular model is a more abstract interface for defining
+Hamiltonians. If you want to define a new model you should make use of this interface. A new 
+model Hamiltonian should subtype to `AbstractHamiltonian` and implement the relevant methods.
+
+```@docs
+AbstractHamiltonian
+offdiagonals
+diagonal_element
+starting_address
+```
+
+The following functions may be implemented instead of [`offdiagonals`](@ref).
+
+```@docs
+num_offdiagonals
+get_offdiagonal
+```
+
+The following functions come with default implementations, but may be customized.
+
+```@docs
+random_offdiagonal
+Hamiltonians.LOStructure
+dimension
+has_adjoint
+allows_address_type
+Base.eltype
+VectorInterface.scalartype
+mul!
+```
+
+This interface relies on unexported functionality, including
+```@docs
+Hamiltonians.adjoint
+Hamiltonians.dot
+Hamiltonians.AbstractOffdiagonals
+Hamiltonians.Offdiagonals
+Hamiltonians.check_address_type
+Hamiltonians.number_conserving_dimension
+Hamiltonians.number_conserving_bose_dimension
+Hamiltonians.number_conserving_fermi_dimension
+```
+
+## Operator and observable interface 
+
+```@docs
+AbstractObservable
+AbstractOperator
+```
+
+## Interface tests
+Helper functions that can be used for testing the various interfaces are provided in the 
+(unexported) submodule `Rimu.InterfaceTests`. 
+
+```@docs
+Rimu.InterfaceTests
+```
+
+### Testing functions
+```@docs
+Rimu.InterfaceTests.test_hamiltonian_interface
+Rimu.InterfaceTests.test_hamiltonian_structure
+Rimu.InterfaceTests.test_observable_interface
+Rimu.InterfaceTests.test_operator_interface
+```
+
+## Utilities for harmonic oscillator models
+Useful utilities for harmonic oscillator in Cartesian basis, see [`HOCartesianContactInteractions`](@ref)
+and [`HOCartesianEnergyConservedPerDim`](@ref).
+```@docs
+get_all_blocks
+fock_to_cart
+```
+Underlying integrals for the interaction matrix elements are implemented in the following unexported functions
+```@docs
+Hamiltonians.four_oscillator_integral_general
+Hamiltonians.ho_delta_potential
+Hamiltonians.log_abs_oscillator_zero
+```
+
+## Index
+```@index
+Pages   = ["custom_hamiltonians.md"]
+```

docs/src/dictvectors.md

@@ -23,6 +23,8 @@ localpart
 apply_operator!
 sort_into_targets!
 working_memory
+mapreduce
+sum_mutating!
 ```
 
 ## Supported operations

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
-```
+```