Feature/doc fix (#159)

* fix example links * Hamiltonians init * API links * RMPI links * module Hamiltonians * mpi link * addresses * G2mom doc * indexes * rimuIO * rmpi links * missing * stochastic module * doctest fix * Revert "doctest fix" This reverts commit 1bffa52. * doctest fix * Revert "doctest fix" This reverts commit d16e3f1. * statstools refs * typo * hamiltonians refs * dvecs & styles refs * mpidata * examples loop * example links
RimuQMC · Aug 31, 2022 · 995c811 · 995c811
1 parent a775349
commit 995c811
Show file tree

Hide file tree

Showing 42 changed files with 281 additions and 219 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -5,17 +5,17 @@ using Rimu.BitStringAddresses
 using Rimu.StatsTools
 using Literate
 
+EXAMPLES_INPUT = joinpath(@__DIR__, "../scripts")
 EXAMPLES_OUTPUT = joinpath(@__DIR__, "src/generated")
 
-Literate.markdown(
-    joinpath(@__DIR__, "../scripts/BHM-example.jl"), EXAMPLES_OUTPUT; documenter=true
-)
-Literate.markdown(
-    joinpath(@__DIR__, "../scripts/BHM-example-mpi.jl"), EXAMPLES_OUTPUT; documenter=true
-)
+for fn in filter(endswith(".jl"), readdir(EXAMPLES_INPUT))
+    Literate.markdown(
+        joinpath(EXAMPLES_INPUT, fn), EXAMPLES_OUTPUT; documenter=true
+    )
+end
 
 makedocs(;
-    modules=[Rimu,Rimu.ConsistentRNG],
+    modules=[Rimu,Rimu.ConsistentRNG,Rimu.RimuIO],
     format=Documenter.HTML(prettyurls = false),
     pages=[
         "Guide" => "index.md",
@@ -34,13 +34,15 @@ makedocs(;
             "Stochastic styles" => "stochasticstyles.md",
             "RMPI" => "RMPI.md",
             "Random Numbers" => "consistentrng.md",
+            "I/O" => "rimuio.md",
             "Documentation generation" => "documentation.md",
             "Code testing" => "testing.md",
         ],
         "API" => "API.md",
     ],
     sitename="Rimu.jl",
     authors="Joachim Brand <j.brand@massey.ac.nz>",
+    checkdocs=:exports,
     doctest=false # Doctests are done while testing.
 )
 

diff --git a/docs/src/API.md b/docs/src/API.md
@@ -14,10 +14,9 @@ See [Module `Interfaces`](@ref)
 
 See [Module `StochasticStyles`](@ref)
 
-
 ## Hamiltonians
 
-See [Module `Hamiltionians`](@ref)
+See [Module `Hamiltonians`](@ref)
 
 ## BitStringAddresses
 

diff --git a/docs/src/RMPI.md b/docs/src/RMPI.md
@@ -10,6 +10,7 @@ Rimu.RMPI
 Rimu.RMPI.MPIData
 ```
 
+### Setup functions
 The following distribute strategies are available. The functions are unexported.
 
 ```@docs
@@ -19,15 +20,24 @@ Rimu.RMPI.mpi_all_to_all
 Rimu.RMPI.mpi_no_exchange
 ```
 
+### Strategies
+```@docs
+Rimu.RMPI.MPIPointToPoint
+Rimu.RMPI.MPIOneSided
+Rimu.RMPI.MPIAllToAll
+Rimu.RMPI.MPINoWalkerExchange
+```
+
 ## MPI convenience functions
 
-```@docs
-Rimu.RMPI.mpi_rank
-Rimu.RMPI.is_mpi_root
-Rimu.RMPI.@mpi_root
-Rimu.RMPI.mpi_barrier
-Rimu.RMPI.mpi_comm
-Rimu.RMPI.mpi_root
-Rimu.RMPI.mpi_seed_CRNGs!
-Rimu.RMPI.mpi_allprintln
+```@autodocs
+Modules = [Rimu.RMPI]
+Pages = ["helpers.jl"]
+Private = true
+Public = true
 ```
+
+## Index
+```@index
+Pages   = ["RMPI.md"]
+```
diff --git a/docs/src/addresses.md b/docs/src/addresses.md
@@ -17,24 +17,10 @@ straightforward to implement efficient Hamiltonians.
 
 ### Fock address API
 
-```@docs
-AbstractFockAddress
-SingleComponentFockAddress
-BoseFS
-FermiFS
-BoseFS2C
-CompositeFS
-num_particles
-num_modes
-num_components
-onr
-near_uniform
-occupied_modes
-is_occupied
-num_occupied_modes
-find_occupied_mode
-find_mode
-excitation
+```@autodocs
+Modules = [BitStringAddresses]
+Pages = ["fockaddress.jl","bosefs.jl","fermifs.jl","multicomponent.jl"]
+Private = false
 ```
 
 ## BitStrings
@@ -45,11 +31,13 @@ space-efficient. The API for [`BitString`](@ref)s is as follows.
 
 ### BitString API
 
-```@docs
-BitString
-num_bits
-num_chunks
-chunk_type
-chunk_bits
-top_chunk_bits
+```@autodocs
+Modules = [BitStringAddresses]
+Pages = ["bitstring.jl"]
+Private = false
+```
+
+## Index
+```@index
+Pages   = ["addresses.md"]
 ```
diff --git a/docs/src/consistentrng.md b/docs/src/consistentrng.md
@@ -8,8 +8,13 @@ For the random number generator we are currently using
 'Xoroshiro128Plus' from 'RandomNumbers.jl'. For benchmarks and statistical test results see the
 [Documentation of `RandomNumbers.jl`](https://sunoru.github.io/RandomNumbers.jl/stable/man/benchmark/#Benchmark-1).
 
-## Module `ConsistentRNG.jl`
+## Module `ConsistentRNG`
 
 ```@autodocs
 Modules = [Rimu.ConsistentRNG]
 ```
+
+## Index
+```@index
+Pages   = ["consistentrng.md"]
+```
diff --git a/docs/src/dictvectors.md b/docs/src/dictvectors.md
@@ -60,3 +60,8 @@ Rimu.DictVectors.Initiator
 Rimu.DictVectors.SimpleInitiator
 Rimu.DictVectors.CoherentInitiator
 ```
+
+## Index
+```@index
+Pages   = ["dictvectors.md"]
+```
diff --git a/docs/src/hamiltonians.md b/docs/src/hamiltonians.md
@@ -19,7 +19,7 @@ hubb = HubbardReal1D(BoseFS((1,2,0,3)); u=1.0, t=1.0)
 ```
 
 The Hamiltonian `hubb` is now ready to be used for FCIQMC in [`lomc!`](@ref) 
-and for exact diagolisation with [`KrylovKit.jl`](https://github.com/Jutho/KrylovKit.jl) directly, or after 
+and for exact diagonalisation with [`KrylovKit.jl`](https://github.com/Jutho/KrylovKit.jl) directly, or after 
 transforming into a sparse matrix first with 
 ```julia-repl
 using SparseArrays
@@ -32,29 +32,49 @@ fh = Matrix(hubb)
 ```
 This functionality relies on 
 ```@docs
-BasisSetRep
+Hamiltonians.BasisSetRep
 sparse
 Matrix
 ```
 
 ## Model Hamiltonians
 
-Here is a list of fully implemented model Hamiltonians. So far there are two variants
-implemented of the one-dimensional Bose-Hubbard model real space as well as a momentum-space
-Hubbard chain.
+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
 ```@docs
 HubbardReal1D
+BoseHubbardReal1D2C
+HubbardReal1DEP
+HubbardRealSpace
 ExtendedHubbardReal1D
+```
+
+### Momentum space Hubbard models
+```@docs
 HubbardMom1D
-Transcorrelated1D
-BoseHubbardReal1D2C
 BoseHubbardMom1D2C
-HubbardRealSpace
+HubbardMom1DEP
+```
+
+### Other
+```@docs
 MatrixHamiltonian
+Transcorrelated1D
+```
+
+### Convenience functions
+```@docs
+rayleigh_quotient
+momentum
+hubbard_dispersion
+continuum_dispersion
+shift_lattice
+shift_lattice_inv
 ```
 
-## Hamiltonian Wrappers
+## Hamiltonian wrappers
 The following Hamiltonians are constructed from an existing 
 Hamiltonian instance and change its behaviour:
 ```@docs
@@ -71,13 +91,14 @@ them into [`AllOverlaps`](@ref).
 ```@docs
 G2MomCorrelator
 G2RealCorrelator
+DensityMatrixDiagonal
 Momentum
 ```
 
 ## 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
+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.
 
@@ -101,9 +122,19 @@ The following functions come with default implementations, but may be customized
 random_offdiagonal
 Hamiltonians.LOStructure
 dimension
+has_adjoint
+```
+
+This interface relies on unexported functionality, including
+```@docs
+Hamiltonians.adjoint
+Hamiltonians.dot
+Hamiltonians.AbstractOffdiagonals
+Hamiltonians.Offdiagonals
 ```
 
 ## Geometry
+Lattices in higher dimensions are defined here for [`HubbardRealSpace`](@ref).
 
 ```@docs
 LatticeGeometry
@@ -113,3 +144,8 @@ LadderBoundaries
 num_neighbours
 neighbour_site
 ```
+
+## Index
+```@index
+Pages   = ["hamiltonians.md"]
+```
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -111,7 +111,7 @@ seconds, a speedup factor of 2.6. This seems reasonable, given that extra work
 needs to be done for communicating between different processes.
 
 Using MPI parallelism with `Rimu` is easy. Enabling MPI for use in [`lomc!()`](@ref) 
-is done by wrapping the primary data structures as [`MPIData`](@ref). As a consequence, data will 
+is done by wrapping the primary data structures as [`MPIData`](@ref Main.Rimu.RMPI.MPIData). As a consequence, data will 
 be stored in a distributed fashion among the MPI ranks and only communicated between ranks when 
 necessary. The relevant functionality is provided by the module `Rimu.RMPI`.
 

diff --git a/docs/src/rimuio.md b/docs/src/rimuio.md
@@ -0,0 +1,10 @@
+# Module `RimuIO`
+
+```@autodocs
+Modules = [RimuIO]
+```
+
+## Index
+```@index
+Pages   = ["rimuio.md"]
+```
diff --git a/docs/src/statstools.md b/docs/src/statstools.md
@@ -28,7 +28,7 @@ unbiased estimators are implemented as [`mixed_estimator`](@ref),
 ```@autodocs
 Modules = [StatsTools]
 Pages = ["StatsTools.jl", "blocking.jl", "ratio_of_means.jl", "convenience.jl",
-  "variances.jl", "growth_witness.jl", "reweighting.jl", "fidelity.jl"
+  "variances.jl", "growth_witness.jl", "reweighting.jl", "fidelity.jl", "variational_energy_estimator.jl"
 ]
 Private = false
 ```

diff --git a/docs/src/stochasticstyles.md b/docs/src/stochasticstyles.md
@@ -1,31 +1,29 @@
 # Module `StochasticStyles`
 
-This module contains the implementations of [`StochasticStyle`](@ref)s, which control how the
-stochastic matrix-vector multiplication is performed.
-
 ```@docs
-StochasticStyle
+StochasticStyles
 ```
 
 ## Available `StochasticStyle`s
 
 ```@docs
 StyleUnknown
-IsStochasticInteger
-IsDeterministic
-IsStochasticWithThreshold
-IsDynamicSemistochastic
-Rimu.StochasticStyles.IsStochastic2Pop
-Rimu.StochasticStyles.IsExplosive
+```
+```@autodocs
+Modules = [StochasticStyles]
+Pages = ["styles.jl"]
 ```
 
 ## The `StochasticStyle` interface
 
 ```@docs
+StochasticStyle
 step_stats
 fciqmc_col!
 update_dvec!
 CompressionStrategy
+NoCompression
+StochasticStyles.ThresholdCompression
 compress!
 default_style
 ```
@@ -34,15 +32,13 @@ default_style
 
 The following functions and types are unexported, but are useful when defining new styles.
 
-```@docs
-Rimu.StochasticStyles.diagonal_step!
-Rimu.StochasticStyles.projected_deposit!
-Rimu.StochasticStyles.SpawningStrategy
-Rimu.StochasticStyles.Exact
-Rimu.StochasticStyles.SingleSpawn
-Rimu.StochasticStyles.WithReplacement
-Rimu.StochasticStyles.WithoutReplacement
-Rimu.StochasticStyles.Bernoulli
-Rimu.StochasticStyles.DynamicSemistochastic
-Rimu.StochasticStyles.spawn!
+```@autodocs
+Modules = [StochasticStyles]
+Pages = ["spawning.jl"]
+Order = [:function,:method,:type]
 ```
+
+## Index
+```@index
+Pages   = ["stochasticstyles.md"]
+```
diff --git a/scripts/BHM-example-mpi.jl b/scripts/BHM-example-mpi.jl
@@ -1,5 +1,12 @@
-# In this example, we will demonstrate using Rimu with MPI.  A runnable script is located at
-# [here](../../scripts/BHM-example-mpi.jl). Run it as `mpirun julia BHM-example.jl`.
+# # Example: Rimu with MPI
+
+# In this example, we will demonstrate using Rimu with MPI. 
+
+# A runnable script for this example is located 
+# [here](https://github.com/joachimbrand/Rimu.jl/blob/develop/scripts/BHM-example-mpi.jl). 
+# Run it with `mpirun julia BHM-example-mpi.jl`.
+
+# ## `BHM-example-mpi.jl`
 
 # We start by importing `Rimu` and `Rimu.RMPI`, which contains MPI-replated
 # functionality.