Interface tests - remove two component models (#299)

# Remove legacy two-component address type and models

This PR removes the address type `BoseFS2C`, which has been superseded
by `CompositeFS` and model Hamiltonians that depend on it. A new package
[`RimuLegacyHamiltonians.jl`](https://github.com/RimuQMC/RimuLegacyHamiltonians.jl)
has been created to house this functionality.

## Breaking changes
- remove `BoseFS2C`, `BoseHubbardMom1D2C`, `BoseHubbardReal1D2C`

## New features
- new module `Rimu.InterfaceTests` with functions 
- `test_observable_interface`
- `test_operator_interface`
- `test_hamiltonian_interface`
- `test_hamiltonian_structure`

## Documentation changes
- The previous page on the `Hamiltonians` module in the "Developer
Documentation" has been split into "Hamiltonians" and "Custom
Hamiltonians" and moved into the "User Documentation"
- various minor changes to the documentation and docstrings, including
additional links.

---------

Co-authored-by: mtsch <matijacufar@gmail.com>

Project.toml

@@ -1,7 +1,7 @@
 name = "Rimu"
 uuid = "c53c40cc-bd84-11e9-2cf4-a9fde2b9386e"
 authors = ["Joachim Brand <j.brand@massey.ac.nz>"]
-version = "0.13.2-dev"
+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"
 
@@ -94,7 +95,6 @@ julia = "1.9"
 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"]

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,17 +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",
             "I/O" => "rimuio.md",
-            "Random numbers" => "randomnumbers.md",
             "Documentation generation" => "documentation.md",
             "Code testing" => "testing.md",
         ],

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/hamiltonians.md

@@ -11,44 +11,39 @@ The Hamiltonians can be used for projector quantum Monte Carlo with [`ProjectorM
 Hamiltonians
 ```
 
-
-## Model Hamiltonians
-
 Here is a list of fully implemented model Hamiltonians. There are several variants
 of the Hubbard model in real and momentum space, as well as some other models.
 
-### Real space Hubbard models
+## Real space Hubbard models
 ```@docs
 HubbardReal1D
-BoseHubbardReal1D2C
 HubbardReal1DEP
 HubbardRealSpace
 ExtendedHubbardReal1D
 ```
 
-### Momentum space Hubbard models
+## Momentum space Hubbard models
 ```@docs
 HubbardMom1D
-BoseHubbardMom1D2C
 HubbardMom1DEP
 ExtendedHubbardMom1D
 ```
 
-### Harmonic oscillator models
+## Harmonic oscillator models
 ```@docs
 HOCartesianContactInteractions
 HOCartesianEnergyConservedPerDim
 HOCartesianCentralImpurity
 ```
 
-### Other
+## Other model Hamiltonians
 ```@docs
 MatrixHamiltonian
 Transcorrelated1D
 FroehlichPolaron
 ```
 
-### Convenience functions
+## Convenience functions
 ```@docs
 rayleigh_quotient
 momentum
@@ -81,8 +76,6 @@ AbstractHamiltonian{T} <: AbstractOperator{T} <: AbstractObservable{T}
 ```
 
 ```@docs
-AbstractObservable
-AbstractOperator
 ParticleNumberOperator
 G2RealCorrelator
 G2RealSpace
@@ -97,55 +90,10 @@ Momentum
 AxialAngularMomentumHO
 ```
 
-## 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. The
-most general form of a 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
-```
-
 ## Geometry
 
-Lattices in higher dimensions are defined here for [`HubbardRealSpace`](@ref) and [`G2RealSpace`](@ref).
+Lattices in higher dimensions are defined here and can be passed with the keyword argument
+`geometry` to [`HubbardRealSpace`](@ref) and [`G2RealSpace`](@ref).
 
 ```@docs
 CubicGrid
@@ -157,20 +105,6 @@ HardwallBoundaries
 LadderBoundaries
 ```
 
-## Harmonic Oscillator
-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   = ["hamiltonians.md"]

docs/src/projectormontecarlo.md

@@ -7,9 +7,9 @@ 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. 
+To run a projector Monte Carlo simulation you set up a problem with [`ProjectorMonteCarloProblem`](@ref)
+and solve it with [`solve`](@ref). Alternatively you can [`init`](@ref) it with to obtain a [`PMCSimulation`](@ref Rimu.PMCSimulation) struct, [`step!`](@ref) 
+through time steps, and [`solve!`](@ref) it to completion. 
 
 ```@docs; canonical=false
 ProjectorMonteCarloProblem
@@ -22,16 +22,16 @@ 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`
+## `PMCSimulation` and report as a `DataFrame`
 
 ```@docs; canonical=false
 Rimu.PMCSimulation
 ```
 
-The `DataFrame` returned from `DataFrame(::PMCSimulation)` contains the time series data from 
+The [`DataFrame`](https://dataframes.juliadata.org/stable/) 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 
+[`ProjectorMonteCarloProblem`](@ref) 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

docs/src/testing.md

@@ -1,6 +1,6 @@
 # Code testing
 
-The script `runtest.jl` in the `test/` folder contains tests of the code. To run the test simply run the script from the Julia REPL or run
+The script `runtest.jl` in the `test/` folder contains tests of the code in `Rimu`. To run the test simply run the script from the Julia REPL or run
 ```
 Rimu$ julia test/runtest.jl
 ```
@@ -12,3 +12,7 @@ More tests should be added over time to test core functionality of the code. To
 
 GitHub Actions are set up to run the test script automatically on the GitHub cloud server every time a new commit to the master branch is pushed to the server. The setup for this to happen is configured in the file
 `actions.yml` in the `Rimu/.github/workflows` folder.
+
+## Testing of custom types for use with `Rimu`
+
+The module `Rimu.InterfaceTests` contains a number of functions to test the interfaces of the [`AbstractHamiltonian`](@ref) type hierarchy. See [Interface tests](@ref) in the section [Advanced operator usage and custom Hamiltonians](@ref).