From 995c81104f4439a02aecbd434afff52fc88f821e Mon Sep 17 00:00:00 2001 From: christofbradly Date: Thu, 1 Sep 2022 11:18:01 +1200 Subject: [PATCH] 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 1bffa525f4a3fd9c5f3f59435c3eb43269c71ea2. * doctest fix * Revert "doctest fix" This reverts commit d16e3f1d542a6568d97209d093848102d5e74890. * statstools refs * typo * hamiltonians refs * dvecs & styles refs * mpidata * examples loop * example links --- docs/make.jl | 16 +++--- docs/src/API.md | 3 +- docs/src/RMPI.md | 28 +++++++--- docs/src/addresses.md | 38 +++++-------- docs/src/consistentrng.md | 7 ++- docs/src/dictvectors.md | 5 ++ docs/src/hamiltonians.md | 56 +++++++++++++++---- docs/src/index.md | 2 +- docs/src/rimuio.md | 10 ++++ docs/src/statstools.md | 2 +- docs/src/stochasticstyles.md | 38 ++++++------- scripts/BHM-example-mpi.jl | 11 +++- scripts/BHM-example.jl | 7 ++- src/BitStringAddresses/fockaddress.jl | 2 +- src/DictVectors/abstractdvec.jl | 22 ++++---- src/DictVectors/dvec.jl | 2 +- src/DictVectors/initiators.jl | 4 +- src/Hamiltonians/Hamiltonians.jl | 32 +++++++---- src/Hamiltonians/HubbardReal1DEP.jl | 6 +- src/Hamiltonians/correlation_functions.jl | 18 ++---- src/Hamiltonians/offdiagonals.jl | 6 +- src/Hamiltonians/operations.jl | 2 +- src/Interfaces/Interfaces.jl | 9 ++- src/Interfaces/dictvectors.jl | 14 ++--- src/Interfaces/hamiltonians.jl | 34 +++++------ src/Interfaces/stochasticstyles.jl | 25 +++------ src/RMPI/helpers.jl | 2 +- src/RMPI/mpidata.jl | 2 +- src/RMPI/noexchange.jl | 2 +- src/RMPI/onesided.jl | 4 +- src/RimuIO.jl | 5 +- src/StatsTools/blocking.jl | 8 +-- src/StatsTools/convenience.jl | 17 ++++-- src/StatsTools/fidelity.jl | 2 +- src/StatsTools/growth_witness.jl | 4 +- src/StatsTools/reweighting.jl | 32 +++++------ .../variational_energy_estimator.jl | 4 +- src/StochasticStyles/StochasticStyles.jl | 5 +- src/StochasticStyles/styles.jl | 4 +- src/lomc.jl | 2 +- src/strategies_and_params/poststepstrategy.jl | 2 +- .../reportingstrategy.jl | 6 +- 42 files changed, 281 insertions(+), 219 deletions(-) create mode 100644 docs/src/rimuio.md diff --git a/docs/make.jl b/docs/make.jl index 1e3619f28..c2ed9d527 100644 --- 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,6 +34,7 @@ makedocs(; "Stochastic styles" => "stochasticstyles.md", "RMPI" => "RMPI.md", "Random Numbers" => "consistentrng.md", + "I/O" => "rimuio.md", "Documentation generation" => "documentation.md", "Code testing" => "testing.md", ], @@ -41,6 +42,7 @@ makedocs(; ], sitename="Rimu.jl", authors="Joachim Brand ", + checkdocs=:exports, doctest=false # Doctests are done while testing. ) diff --git a/docs/src/API.md b/docs/src/API.md index 1310a44bf..37ac91cd4 100644 --- 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 index 635ddbf1b..e7566560d 100644 --- 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"] +``` \ No newline at end of file diff --git a/docs/src/addresses.md b/docs/src/addresses.md index a9e3047ff..8791ec846 100644 --- 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 index a35d7ad09..cd19f463f 100644 --- 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"] +``` \ No newline at end of file diff --git a/docs/src/dictvectors.md b/docs/src/dictvectors.md index a540691b6..396368459 100644 --- 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"] +``` \ No newline at end of file diff --git a/docs/src/hamiltonians.md b/docs/src/hamiltonians.md index 98fdc2f5f..5dabd864d 100644 --- 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"] +``` \ No newline at end of file diff --git a/docs/src/index.md b/docs/src/index.md index 86209d0d6..262823787 100644 --- 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 new file mode 100644 index 000000000..37922db58 --- /dev/null +++ b/docs/src/rimuio.md @@ -0,0 +1,10 @@ +# Module `RimuIO` + +```@autodocs +Modules = [RimuIO] +``` + +## Index +```@index +Pages = ["rimuio.md"] +``` \ No newline at end of file diff --git a/docs/src/statstools.md b/docs/src/statstools.md index a3407b5d9..6b6757c77 100644 --- 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 index dd730e926..743e3fe6c 100644 --- 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"] +``` \ No newline at end of file diff --git a/scripts/BHM-example-mpi.jl b/scripts/BHM-example-mpi.jl index aa5e91be6..ce609c2cc 100644 --- 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. diff --git a/scripts/BHM-example.jl b/scripts/BHM-example.jl index 6be308fe7..4aa14c2fb 100644 --- a/scripts/BHM-example.jl +++ b/scripts/BHM-example.jl @@ -2,7 +2,12 @@ # This is an example calculation finding the ground state of # a 1D Bose-Hubbard chain with 6 particles in 6 lattice sites. -# The Julia run-able script is in [`scripts/BHM-example.jl`](../../scripts/BHM-example.jl). + +# A runnable script for this example is located +# [here](https://github.com/joachimbrand/Rimu.jl/blob/develop/scripts/BHM-example.jl). +# Run it with `julia BHM-example.jl`. + +# ## `BHM-example.jl` # Firstly, we load all needed modules. # `Rimu` for FCIQMC calculation; diff --git a/src/BitStringAddresses/fockaddress.jl b/src/BitStringAddresses/fockaddress.jl index 4bfe7e2ae..c2f04be48 100644 --- a/src/BitStringAddresses/fockaddress.jl +++ b/src/BitStringAddresses/fockaddress.jl @@ -235,7 +235,7 @@ julia> dot(mf, mb) julia> dot(mf, 1:20) 17 ``` -See also [`dot`](@ref), [`SingleComponentFockAddress`](@ref). +See also [`dot`](@ref Main.Hamiltonians.dot), [`SingleComponentFockAddress`](@ref). """ struct OccupiedModeMap{N,T} <: AbstractVector{T} indices::SVector{N,T} # N = min(N, M) diff --git a/src/DictVectors/abstractdvec.jl b/src/DictVectors/abstractdvec.jl index fd435e7fb..c7d929c3c 100644 --- a/src/DictVectors/abstractdvec.jl +++ b/src/DictVectors/abstractdvec.jl @@ -179,7 +179,7 @@ products. Implemented subtypes: - [`Norm2Projector`](@ref) - [`Norm1ProjectorPPop`](@ref) -See also [`PostStepStrategy`](@ref) for use of projectors in [`lomc!`](@ref). +See also [`PostStepStrategy`](@ref Main.PostStepStrategy) for use of projectors in [`lomc!`](@ref Main.lomc!). ## Interface @@ -197,8 +197,8 @@ UniformProjector()⋅v == sum(v) dot(UniformProjector(), LO, v) == sum(LO*v) ``` -See also [`PostStepStrategy`](@ref), and [`AbstractProjector`](@ref) for use -of projectors in [`lomc!`](@ref). +See also [`PostStepStrategy`](@ref Main.PostStepStrategy), and [`AbstractProjector`](@ref) for use +of projectors in [`lomc!`](@ref Main.lomc!). """ struct UniformProjector <: AbstractProjector end @@ -216,8 +216,8 @@ dot(NormProjector(),x) ``` `NormProjector()` thus represents the vector `sign.(x)`. -See also [`PostStepStrategy`](@ref), and [`AbstractProjector`](@ref) for use -of projectors in [`lomc!`](@ref). +See also [`PostStepStrategy`](@ref Main.PostStepStrategy), and [`AbstractProjector`](@ref) for use +of projectors in [`lomc!`](@ref Main.lomc!). """ struct NormProjector <: AbstractProjector end @@ -231,8 +231,8 @@ dot(NormProjector(),x) -> norm(x,2) # with type Float64 ``` -See also [`PostStepStrategy`](@ref), and [`AbstractProjector`](@ref) for use -of projectors in [`lomc!`](@ref). +See also [`PostStepStrategy`](@ref Main.PostStepStrategy), and [`AbstractProjector`](@ref) for use +of projectors in [`lomc!`](@ref Main.lomc!). """ struct Norm2Projector <: AbstractProjector end @@ -248,8 +248,8 @@ dot(Norm1ProjectorPPop(),x) -> norm(real.(x),1) + im*norm(imag.(x),1) ``` -See also [`PostStepStrategy`](@ref), and [`AbstractProjector`](@ref) for use -of projectors in [`lomc!`](@ref). +See also [`PostStepStrategy`](@ref Main.PostStepStrategy), and [`AbstractProjector`](@ref) for use +of projectors in [`lomc!`](@ref Main.lomc!). """ struct Norm1ProjectorPPop <: AbstractProjector end @@ -277,8 +277,8 @@ dot(PopsProjector(),x) -> real(x) ⋅ imag(x) ``` -See also [`PostStepStrategy`](@ref), and [`AbstractProjector`](@ref) for use -of projectors in [`lomc!`](@ref). +See also [`PostStepStrategy`](@ref Main.PostStepStrategy), and [`AbstractProjector`](@ref) for use +of projectors in [`lomc!`](@ref Main.lomc!). """ struct PopsProjector <: AbstractProjector end diff --git a/src/DictVectors/dvec.jl b/src/DictVectors/dvec.jl index 703e26dde..e9a188194 100644 --- a/src/DictVectors/dvec.jl +++ b/src/DictVectors/dvec.jl @@ -26,7 +26,7 @@ The default `style` is selected based on the `DVec`'s `valtype` (see [`default_style`](@ref)). If a style is given and the `valtype` does not match the `style`'s `eltype`, the values are converted to an appropriate type. -The capacity argument is optional and sets the initial size of the `DVec` via `sizehint!`. +The capacity argument is optional and sets the initial size of the `DVec` via `Base.sizehint!`. ## Examples diff --git a/src/DictVectors/initiators.jl b/src/DictVectors/initiators.jl index 3ff3ae74b..7f9c55e3b 100644 --- a/src/DictVectors/initiators.jl +++ b/src/DictVectors/initiators.jl @@ -125,7 +125,7 @@ end """ InitiatorDVec{K,V} <: AbstractDVec{K,V} -Dictionary-based vector-like data structure for use with [`lomc!`](@ref) and +Dictionary-based vector-like data structure for use with [`lomc!`](@ref Main.lomc!) 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. How the initiators are handled is controlled by @@ -154,7 +154,7 @@ the `initiator` keyword argument (see below). * `initiator = Initiator(1)`: A valid [`InitiatorRule`](@ref). See [`Initiator`](@ref). * `capacity`: Indicative size as `Int`. Optional. Sets the initial size of the - `InitiatorDVec` via [`sizehint!`](@ref). + `InitiatorDVec` via `Base.sizehint!`. """ struct InitiatorDVec{ diff --git a/src/Hamiltonians/Hamiltonians.jl b/src/Hamiltonians/Hamiltonians.jl index a10f33a29..338e71a96 100644 --- a/src/Hamiltonians/Hamiltonians.jl +++ b/src/Hamiltonians/Hamiltonians.jl @@ -4,26 +4,37 @@ This module defines Hamiltonian types and functions for working with Hamiltonians. -## Exported concrete Hamiltonian types include -- [`MatrixHamiltonian`](@ref) -- [`HubbardReal1D`](@ref) -- [`ExtendedHubbardReal1D`](@ref) +## [Exported concrete Hamiltonian types](#Model-Hamiltonians) + +Real space Hubbard models + - [`HubbardReal1D`](@ref) + - [`BoseHubbardReal1D2C`](@ref) + - [`HubbardReal1DEP`](@ref) + - [`HubbardRealSpace`](@ref) + - [`ExtendedHubbardReal1D`](@ref) + +Momentum space Hubbard models - [`HubbardMom1D`](@ref) -- [`Transcorrelated1D`](@ref) - [`BoseHubbardMom1D2C`](@ref) -- [`BoseHubbardReal1D2C`](@ref) +- [`HubbardMom1DEP`](@ref) + +Other +- [`MatrixHamiltonian`](@ref) +- [`Transcorrelated1D`](@ref) -## Wrappers +## [Wrappers](#Hamiltonian-wrappers) - [`GutzwillerSampling`](@ref) - [`GuidingVectorSampling`](@ref) - [`ParitySymmetry`](@ref) - [`TimeReversalSymmetry`](@ref) -## Other +## [Observables](#Observables) - [`G2MomCorrelator`](@ref) - [`G2RealCorrelator`](@ref) +- [`DensityMatrixDiagonal`](@ref) +- [`Momentum`](@ref) -## Interface for working with Hamiltonians +## [Interface for working with Hamiltonians](#Hamiltonians-interface) - [`AbstractHamiltonian`](@ref): defined in the module [`Interfaces`](@ref) """ module Hamiltonians @@ -41,7 +52,8 @@ using ..Interfaces import ..Interfaces: diagonal_element, num_offdiagonals, get_offdiagonal, starting_address, offdiagonals, random_offdiagonal, LOStructure -export AbstractHamiltonian, TwoComponentBosonicHamiltonian +export AbstractHamiltonian +# export TwoComponentHamiltonian export dimension, rayleigh_quotient, momentum export BasisSetRep diff --git a/src/Hamiltonians/HubbardReal1DEP.jl b/src/Hamiltonians/HubbardReal1DEP.jl index 39def2e4c..15da4f8ec 100644 --- a/src/Hamiltonians/HubbardReal1DEP.jl +++ b/src/Hamiltonians/HubbardReal1DEP.jl @@ -3,7 +3,8 @@ Circular shift contiguous indices `is` in interval `[M÷2, M÷2)` such that set starts with 0, where `M=length(is)`. -Inverse operation: [`shift_lattice_inv`](@ref). +Inverse operation: [`shift_lattice_inv`](@ref). Used in [`HubbardReal1DEP`](@ref) and +[`HubbardMom1DEP`](@ref) """ shift_lattice(is) = circshift(is, cld(length(is),2)) @@ -12,7 +13,8 @@ shift_lattice(is) = circshift(is, cld(length(is),2)) Circular shift indices starting with 0 into a contiguous set in interval `[M÷2, M÷2)`, where `M=length(js)`. -Inverse operation of [`shift_lattice`](@ref). +Inverse operation of [`shift_lattice`](@ref). Used in [`HubbardReal1DEP`](@ref) and +[`HubbardMom1DEP`](@ref) """ shift_lattice_inv(js) = circshift(js, fld(length(js),2)) diff --git a/src/Hamiltonians/correlation_functions.jl b/src/Hamiltonians/correlation_functions.jl index 1de6886a8..3962ca4d5 100644 --- a/src/Hamiltonians/correlation_functions.jl +++ b/src/Hamiltonians/correlation_functions.jl @@ -78,6 +78,12 @@ Correlation within a single component: ```math \\hat{G}^{(2)}(d) = \\frac{1}{M}\\sum_{spqr=1}^M e^{-id(p-q)2π/M} a^†_{s} a^†_{p} a_q a_r δ_{s+p,q+r} ``` + +The diagonal element, where `(p-q)=0`, is +```math +\\frac{1}{M}\\sum_{k,p=1}^M a^†_{k} b^†_{p} b_p a_k . +``` + # Arguments - `d::Integer`: the distance between two particles. - `c`: possible instructions: `:cross`: default instruction, computing correlation between particles across two components; @@ -144,18 +150,6 @@ function num_offdiagonals(g::G2MomCorrelator, add::BoseFS) return singlies*(singlies-1)*(m - 2) + doublies*(m - 1) end -""" - diagonal_element(g::G2MomCorrelator, add::BoseFS2C{NA,NB,M,AA,AB}) - -The diagonal element in [`G2MomCorrelator`](@ref), where `(p-q)=0`, hence -it becomes -```math -\\frac{1}{M}\\sum_{k,p=1}^M a^†_{k} b^†_{p} b_p a_k . -``` -# See also - -* [`G2MomCorrelator`](@ref) -""" diagonal_element(g::G2MomCorrelator{1}, add::BoseFS2C) = diagonal_element(g, add.bsa) diagonal_element(g::G2MomCorrelator{2}, add::BoseFS2C) = diagonal_element(g, add.bsb) diff --git a/src/Hamiltonians/offdiagonals.jl b/src/Hamiltonians/offdiagonals.jl index 9b7bd35da..42762d71c 100644 --- a/src/Hamiltonians/offdiagonals.jl +++ b/src/Hamiltonians/offdiagonals.jl @@ -5,15 +5,15 @@ """ AbstractOffdiagonals{A,T}<:AbstractVector{Tuple{A,T}} -Iterator over new address and matrix element for reachable off-diagonal matrix elements of a +Iterator over new address and matrix elements for reachable off-diagonal matrix elements of a linear operator. See [`Offdiagonals`](@ref) for a default implementation. # Methods to define -* [`offdiagonals(h, a)::AbstractOffdiagonals`](@ref): This function is used to construct the - correct type of offdiagonals for a given combination of hamiltonian `h` and fock address +* [`offdiagonals(h, a)::AbstractOffdiagonals`](@ref offdiagonals): This function is used to construct the + correct type of offdiagonals for a given combination of Hamiltonian `h` and Fock address `a`. * `Base.getindex(::AbstractOffdiagonals, i)`: should be equivalent to `get_offdiagonal(h, a, i)`. diff --git a/src/Hamiltonians/operations.jl b/src/Hamiltonians/operations.jl index b71eacc39..27321d7c1 100644 --- a/src/Hamiltonians/operations.jl +++ b/src/Hamiltonians/operations.jl @@ -93,7 +93,7 @@ LinearAlgebra.adjoint(op::AbstractHamiltonian) = adjoint(LOStructure(op), op) """ adjoint(::LOStructure, op::AbstractHamiltonian) -Represent the adjoint of an `AbstractHamiltonian`. Extend this method to define custom +Represent the adjoint of an [`AbstractHamiltonian`](@ref). Extend this method to define custom adjoints. """ function LinearAlgebra.adjoint(::S, op) where {S<:LOStructure} diff --git a/src/Interfaces/Interfaces.jl b/src/Interfaces/Interfaces.jl index b67acabb1..8faf869fc 100644 --- a/src/Interfaces/Interfaces.jl +++ b/src/Interfaces/Interfaces.jl @@ -5,12 +5,11 @@ This module contains interfaces that can be used to extend and modify the algori # Interfaces Follow the links for the definitions of the interfaces! -* [`AbstractHamiltonian`](@ref) for defining [`Hamiltonians`](@ref) -* [`AbstractDVec`](@ref) for defining data structures for `Rimu` as in [`DictVectors`](@ref) -* [`StochasticStyle`](@ref) for controlling the stochastic algorithms used by [`lomc!`](@ref) - as implemented in [`StochasticStyles`](@ref) +* [`AbstractHamiltonian`](@ref) for defining [`Hamiltonians`](@ref Main.Hamiltonians) +* [`AbstractDVec`](@ref) for defining data structures for `Rimu` as in [`DictVectors`](@ref Main.DictVectors) +* [`StochasticStyle`](@ref) for controlling the stochastic algorithms used by [`lomc!`](@ref Main.lomc!) as implemented in [`StochasticStyles`](@ref Main.StochasticStyles) -# Additonal exports +# Additional exports ## Interface functions for[`AbstractHamiltonian`](@ref)s: * [`diagonal_element`](@ref) diff --git a/src/Interfaces/dictvectors.jl b/src/Interfaces/dictvectors.jl index 87dfb3328..8d9485b73 100644 --- a/src/Interfaces/dictvectors.jl +++ b/src/Interfaces/dictvectors.jl @@ -3,11 +3,11 @@ Abstract type for data structures that behave similar to sparse vectors, but are indexed by an arbitrary type `V` (could be non-integers) similarly to dictionaries. `AbstractDVec`s -are designed to work well with [`lomc!`](@ref) and +are designed to work well with [`lomc!`](@ref Main.lomc!) and [KrylovKit](https://github.com/Jutho/KrylovKit.jl). -Concrete implementations are available as [`DVec`](@ref) -and [`InitiatorDVec`](@ref). +Concrete implementations are available as [`DVec`](@ref Main.DictVectors.DVec) +and [`InitiatorDVec`](@ref Main.DictVectors.InitiatorDVec). `AbstractDvec`s lie somewhere between `AbstractDict`s and sparse `AbstractVector`s, while being subtyped to neither. @@ -30,9 +30,9 @@ Implement what would be needed for the `AbstractDict` interface (`pairs`, `keys` * [`StochasticStyle`](@ref) * [`storage`](@ref) returns an `AbstractDict` storing the raw data with possibly different `valtype` than `V`. -* [`deposit`](@ref) +* [`deposit!`](@ref) -See also [`DictVectors`](@ref), [`Interfaces`](@ref). +See also [`DictVectors`](@ref Main.DictVectors), [`Interfaces`](@ref). """ abstract type AbstractDVec{K,V} end @@ -41,7 +41,7 @@ abstract type AbstractDVec{K,V} end Add `val` into `w` at address `add`, taking into account initiator rules if applicable. `parent` contains the `address => value` pair from which the pair `add => val` -was created. [`InitiatorDVec`](@ref) can intercept this and add its own functionality. +was created. [`InitiatorDVec`](@ref Main.DictVectors.InitiatorDVec) can intercept this and add its own functionality. """ function deposit!(w, add, val, _) w[add] += convert(valtype(w), val) @@ -71,6 +71,6 @@ StochasticStyle(::AbstractArray{T}) where {T} = default_style(T) Create a "frozen" version of `dv` which can no longer be modified or used in the conventional manner, but supports faster dot products. -If `dv` is an [`MPIData`](@ref), synchronize its contents among the ranks first. +If `dv` is an [`MPIData`](@ref Main.Rimu.RMPI.MPIData), synchronize its contents among the ranks first. """ freeze(v::AbstractVector) = copy(v) diff --git a/src/Interfaces/hamiltonians.jl b/src/Interfaces/hamiltonians.jl index 5953adb7d..86a790136 100644 --- a/src/Interfaces/hamiltonians.jl +++ b/src/Interfaces/hamiltonians.jl @@ -5,16 +5,16 @@ AbstractHamiltonian{T} Supertype that provides an interface for linear operators over a linear space with scalar -type `T` that are suitable for FCIQMC (with [`lomc!`](@ref)). Indexing is done with addresses (typically not -integers) from an address space that may be large (and will not need to be completely -generated). +type `T` that are suitable for FCIQMC (with [`lomc!`](@ref Main.lomc!)). Indexing is done +with addresses (typically not integers) from an address space that may be large (and will +not need to be completely generated). `AbstractHamiltonian` instances operate on vectors of type [`AbstractDVec`](@ref) from the -module `DictVectors` and work well with addresses of type [`AbstractFockAddress`](@ref) from -the module `BitStringAddresses`. The type works well with the external package +module `DictVectors` and work well with addresses of type [`AbstractFockAddress`](@ref Main.BitStringAddresses.AbstractFockAddress) +from the module `BitStringAddresses`. The type works well with the external package [KrylovKit.jl](https://github.com/Jutho/KrylovKit.jl). -For available implementations see [`Hamiltonians`](@ref). +For available implementations see [`Hamiltonians`](@ref Main.Hamiltonians). # Interface @@ -27,10 +27,10 @@ Methods that need to be implemented: Optional methods to implement: -* [`LOStructure(::Type{typeof(lo)})`](@ref): defaults to `AdjointUnknown` -* [`dimension(::Type{T}, ::AbstractHamiltonian)`](@ref): defaults to dimension of address +* [`LOStructure(::Type{typeof(lo)})`](@ref LOStructure): defaults to `AdjointUnknown` +* [`dimension(::Type{T}, ::AbstractHamiltonian)`](@ref Main.Hamiltonians.dimension): defaults to dimension of address space -* [`momentum(::AbstractHamiltonian)`](@ref): no default +* [`momentum(::AbstractHamiltonian)`](@ref Main.Hamiltonians.momentum): no default Provides: @@ -39,12 +39,12 @@ Provides: * `*(H, v)`: deterministic matrix-vector multiply (allocating) * `H(v)`: equivalent to `H * v`. * `mul!(w, H, v)`: mutating matrix-vector multiply. -* [`dot(x, H, v)`](@ref): compute `x⋅(H*v)` minimizing allocations. +* [`dot(x, H, v)`](@ref Main.Hamiltonians.dot): compute `x⋅(H*v)` minimizing allocations. * `H[address1, address2]`: indexing with `getindex()` - mostly for testing purposes (slow!) -* [`BasisSetRep`](@ref): construct a basis set repesentation -* [`sparse`](@ref), [`Matrix`](@ref): construct a (sparse) matrix representation +* [`BasisSetRep`](@ref Main.Hamiltonians.sparse): construct a basis set repesentation +* [`sparse`](@ref Main.Hamiltonians.sparse), [`Matrix`](@ref): construct a (sparse) matrix representation -See also [`Hamiltonians`](@ref), [`Interfaces`](@ref). +See also [`Hamiltonians`](@ref Main.Hamiltonians), [`Interfaces`](@ref). """ abstract type AbstractHamiltonian{T} end @@ -143,8 +143,8 @@ Return an iterator over reachable off-diagonal matrix elements of type # See also -* [`Offdiagonals`](@ref) -* [`AbstractOffdiagonals`](@ref) +* [`Offdiagonals`](@ref Main.Hamiltonians.Offdiagonals) +* [`AbstractOffdiagonals`](@ref Main.Hamiltonians.AbstractOffdiagonals) ```jldoctest julia> addr = BoseFS((3,2,1)); @@ -199,8 +199,8 @@ known this can speed up calculations. Implemented structures are: * `IsDiagonal`: The operator is diagonal. * `IsHermitian`: The operator is complex and Hermitian or real and symmetric. -* `AdjointKnown`: The operator is not Hermitian, but its [`adjoint`](@ref) is implemented. -* `AdjointUnknown`: [`adjoint`](@ref) for this operator is not implemented. +* `AdjointKnown`: The operator is not Hermitian, but its [`adjoint`](@ref Main.Hamiltonians.adjoint) is implemented. +* `AdjointUnknown`: [`adjoint`](@ref Main.Hamiltonians.adjoint) for this operator is not implemented. In order to define this trait for a new linear operator type, define a method for `LOStructure(::Type{<:MyNewLOType}) = …`. diff --git a/src/Interfaces/stochasticstyles.jl b/src/Interfaces/stochasticstyles.jl index aa7aa6600..b925ee1d1 100644 --- a/src/Interfaces/stochasticstyles.jl +++ b/src/Interfaces/stochasticstyles.jl @@ -3,28 +3,18 @@ Abstract type. When called as a function it returns the native style of the generalised vector `v` that determines how simulations are to proceed. - -# Implemented styles - -* [`IsStochasticInteger`](@ref) - integer walker FCIQMC -* [`IsDeterministic`](@ref) - perform deterministic variant of power method -* [`IsStochasticWithThreshold`](@ref) - floating point walker FCIQMC -* [`IsDynamicSemistochastic`](@ref) - floating point walker FCIQMC with smarter spawning and - vector compression -* [`IsStochastic2Pop`](@ref) -* [`IsExplosive`](@ref) - + # Usage Concrete `StochasticStyle`s can be used for the `style` keyword argument of -[`lomc!`](@ref) and [`DVec`](@ref). +[`lomc!`](@ref Main.lomc!) and [`DVec`](@ref Main.DictVectors.DVec). # Interface When defining a new `StochasticStyle`, subtype it as `MyStyle<:StochasticStyle{T}` where `T` is the concrete value type the style is designed to work with. -For it to work with [`lomc!`](@ref), a `StochasticStyle` must define the following: +For it to work with [`lomc!`](@ref Main.lomc!), a `StochasticStyle` must define the following: * [`fciqmc_col!(::StochasticStyle, w, H, address, value, shift, dτ)`](@ref) * [`step_stats(::StochasticStyle)`](@ref) @@ -33,7 +23,7 @@ and optionally * [`CompressionStrategy(::StochasticStyle)`](@ref) for vector compression after annihilations, * [`update_dvec!`](@ref) for arbitrary transformations after the spawning step. -See also [`StochasticStyles`](@ref), [`Interfaces`](@ref). +See also [`StochasticStyles`](@ref Main.StochasticStyles), [`Interfaces`](@ref). """ abstract type StochasticStyle{T} end @@ -64,9 +54,8 @@ default_style(::Type{T}) where T = StyleUnknown{T}() The `CompressionStrategy` controls how a vector is compressed after a step. -## Standard implementations (subtypes): +## Default implementation: * [`NoCompression`](@ref): no vector compression -* [`ThresholdCompression`](@ref): compress elements below a threshold ## Usage A subtype of `CompressionStrategy` can be passed as a keyword argument to the @@ -78,7 +67,7 @@ default is [`NoCompression`](@ref). When defining a new `CompressionStrategy`, subtype it as `MyCompressionStrategy <: CompressionStrategy` and define a method for -* [`compress!(s::MyCompressionStrategy, v)`](@ref) +* [`compress!(s::MyCompressionStrategy, v)`](@ref compress!) """ abstract type CompressionStrategy end @@ -125,7 +114,7 @@ end step_stats(::StochasticStyle) Return a tuple of names (`Symbol` or `String`) and a tuple of zeros of values of the same -length. These will be reported as columns in the `DataFrame` returned by [`lomc!`](@ref). +length. These will be reported as columns in the `DataFrame` returned by [`lomc!`](@ref Main.lomc!). """ step_stats(v, n) = step_stats(StochasticStyle(v), n) function step_stats(s::StochasticStyle, ::Val{N}) where N diff --git a/src/RMPI/helpers.jl b/src/RMPI/helpers.jl index 1d54a0831..73f0f2018 100644 --- a/src/RMPI/helpers.jl +++ b/src/RMPI/helpers.jl @@ -107,7 +107,7 @@ function Rimu.sort_into_targets!(dtarget::MPIData, w::AbstractDVec, stats) end """ - sync_cRandn(md::MPIData) + ConsistentRNG.sync_cRandn(md::MPIData) Generate one random number with [`cRandn()`](@ref) in a synchronous way such that all MPI ranks have the same random number. The argument is ignored unless it is of type `MPIData`, in which case a random diff --git a/src/RMPI/mpidata.jl b/src/RMPI/mpidata.jl index cc306c613..4bc9e27ab 100644 --- a/src/RMPI/mpidata.jl +++ b/src/RMPI/mpidata.jl @@ -9,7 +9,7 @@ does not support indexing, or iteration over `keys`, `values`, and `pairs`. Keyword arguments: * `setup = mpi_point_to_point` - controls the communication stratgy * [`mpi_one_sided`](@ref) uses one-sided communication with remote memory access (RMA), sets [`MPIOneSided`](@ref) strategy. - * [`mpi_point_to_point`](@ref) uses [`MPIPointTOPoint`](@ref) strategy. + * [`mpi_point_to_point`](@ref) uses [`MPIPointToPoint`](@ref) strategy. * [`mpi_all_to_all`](@ref) uses [`MPIAllToAll`](@ref) strategy. * [`mpi_no_exchange`](@ref) sets [`MPINoWalkerExchange`](@ref) strategy. Experimental. Use with caution! * `comm = mpi_comm()` diff --git a/src/RMPI/noexchange.jl b/src/RMPI/noexchange.jl index 2d94c5988..07cd1dc4b 100644 --- a/src/RMPI/noexchange.jl +++ b/src/RMPI/noexchange.jl @@ -14,7 +14,7 @@ end """ MPINoWalkerExchange(nprocs, my_rank, comm) -Strategy for for not exchanging walkers between ranks. Consequently there +Strategy for not exchanging walkers between ranks. Consequently there will be no cross-rank annihilations. """ struct MPINoWalkerExchange <: DistributeStrategy diff --git a/src/RMPI/onesided.jl b/src/RMPI/onesided.jl index 4ea4a7d21..1fc191de6 100644 --- a/src/RMPI/onesided.jl +++ b/src/RMPI/onesided.jl @@ -23,9 +23,9 @@ end MPIOneSided(nprocs, myrank, comm, ::Type{T}, capacity) Communication buffer for use with MPI one-sided communication (remote memory access). Up to -`capacity` elements of type `T` can be exchanged between MPI ranks via [`put`](@ref). It is +`capacity` elements of type `T` can be exchanged between MPI ranks via `put`. It is important that `isbitstype(T) == true`. Objects of type `MPIOneSided` have to be -freed manually with a (blocking) call to [`free()`](@ref). +freed manually with a (blocking) call to `free()`. """ mutable struct MPIOneSided{T} <: DistributeStrategy mpiid::Int # unique ID for MPI-distributed objects diff --git a/src/RimuIO.jl b/src/RimuIO.jl index f4d41b9c1..ed981c092 100644 --- a/src/RimuIO.jl +++ b/src/RimuIO.jl @@ -1,5 +1,5 @@ """ -Module to provide file inut and output functionality for `Rimu`. +Module to provide file input and output functionality for `Rimu`. Provides convenience functions: * [`RimuIO.save_df(filename, df::DataFrame)`](@ref) Save dataframe in Arrow format. @@ -42,8 +42,7 @@ Save `dvec` in [BSON](https://github.com/JuliaIO/BSON.jl) format. ## Notes * Only the [`localpart`](@ref) is saved. You may need to re-wrap the result in - [`MPIData`](@ref) if using MPI. - + [`MPIData`](@ref Main.Rimu.RMPI.MPIData) if using MPI. * When using this function with MPI, make sure to save the vectors from different ranks to different files, e.g. by saving as `RimuIO.save_dvec("filename-\$(mpi_rank()).bson", dvec)`. diff --git a/src/StatsTools/blocking.jl b/src/StatsTools/blocking.jl index 29ad8cbe9..797db2e37 100644 --- a/src/StatsTools/blocking.jl +++ b/src/StatsTools/blocking.jl @@ -4,7 +4,7 @@ """ BlockingResult(mean, err, err_err, p_cov, k, blocks) -Result of [`blocking_analysis()`](@ref). +Result of [`blocking_analysis`](@ref). ### Fields: - `mean`: sample mean @@ -16,7 +16,7 @@ Result of [`blocking_analysis()`](@ref). Has methods for [`NamedTuple`](@ref), [`val_and_errs`](@ref), [`val`](@ref), [`errs`](@ref), [`mean_and_se`](@ref), `Measurements.:±`, -`MonteCarloMeasurements.Particles`, and +[`MonteCarloMeasurements.Particles`](@ref), and `Statistics.cov` for `Complex` data. **Example:** @@ -76,7 +76,7 @@ end measurement(r::BlockingResult) Measurements.±(r::BlockingResult) Convert a `BlockingResult` into a `Measurement` for linear error propagation with -[`Measurements`](@ref). +[`Measurements`](https://github.com/JuliaPhysics/Measurements.jl). Limitation: Does not account for covariance in complex `BlockingResult`. Consider using [`MonteCarloMeasurements.Particles(r)`](@ref)! @@ -94,7 +94,7 @@ end MonteCarloMeasurements.Particles(r::BlockingResult; mc_samples = 2000) MonteCarloMeasurements.±(r::BlockingResult) Convert a `BlockingResult` into a `Particles` object for nonlinear error propagation with -[`MonteCarloMeasurements`](@ref). +[`MonteCarloMeasurements`](https://github.com/baggepinnen/MonteCarloMeasurements.jl). """ function MonteCarloMeasurements.Particles(r::BlockingResult{<:Real}; mc_samples=2000) return Particles(mc_samples, Normal(r.mean, r.err)) diff --git a/src/StatsTools/convenience.jl b/src/StatsTools/convenience.jl index cee2f0bc9..b98930e6f 100644 --- a/src/StatsTools/convenience.jl +++ b/src/StatsTools/convenience.jl @@ -2,8 +2,10 @@ """ to_measurement(p::MonteCarloMeasurements.Particles) -> ::Measurements.measurement -Convert an uncertain number from `MonteCarloMeasurements` to `Measurements` format using the median as the central -point. The new `±` boundaries will include the 68% quantile around the median. +Convert an uncertain number from [`MonteCarloMeasurements`](https://github.com/baggepinnen/MonteCarloMeasurements.jl) +to [`Measurements`](https://github.com/JuliaPhysics/Measurements.jl) format +using the median as the central point. The new `±` boundaries will include +the 68% quantile around the median. """ function to_measurement(p::MonteCarloMeasurements.Particles) q = pquantile(p, [0.16, 0.5, 0.84]) @@ -14,8 +16,9 @@ end """ val(x) Return the best estimate value for an uncertain `x`. Defaults to the `median` -for uncertain `x` represented by a (sampled) distribution. Supports `MonteCarloMeasurements` -and `Measurements`. +for uncertain `x` represented by a (sampled) distribution. Supports +[`MonteCarloMeasurements`](https://github.com/baggepinnen/MonteCarloMeasurements.jl) +and [`Measurements`](https://github.com/JuliaPhysics/Measurements.jl). See [`errs`](@ref), [`BlockingResult`](@ref), [`RatioBlockingResult`](@ref). """ @@ -31,8 +34,10 @@ import Measurements: Measurement, uncertainty, value Return the median and the lower and upper error bar for the uncertain value `x` as a `NamedTuple`. This is useful for plotting scripts. The interval `[val - val_l, val + val_u]` represents the confidence interval at level `n*σ`, -or at probability `p`. Setting `p` overrides `n`. Supports `MonteCarloMeasurements` -and `Measurements`. The names in the `NamedTuple` can be changed with `name`. +or at probability `p`. Setting `p` overrides `n`. Supports +[`MonteCarloMeasurements`](https://github.com/baggepinnen/MonteCarloMeasurements.jl) +and [`Measurements`](https://github.com/JuliaPhysics/Measurements.jl). The +names in the `NamedTuple` can be changed with `name`. **Example:** ```jldoctest diff --git a/src/StatsTools/fidelity.jl b/src/StatsTools/fidelity.jl index 9a35c3810..435a6d1c1 100644 --- a/src/StatsTools/fidelity.jl +++ b/src/StatsTools/fidelity.jl @@ -1,7 +1,7 @@ """ replica_fidelity(df::DataFrame; p_field = :hproj, skip = 0) Compute the fidelity of the average coefficient vector and the projector defined in -`p_field` from the result of replica [`lomc!()`](@ref) passed as argument `df`, +`p_field` from the result of replica [`lomc!`](@ref Main.lomc!) passed as argument `df`, using replicas `_1` and `_2`. Calls [`ratio_of_means()`](@ref) to perform a blocking analysis on a ratio of the means of separate time series and returns a diff --git a/src/StatsTools/growth_witness.jl b/src/StatsTools/growth_witness.jl index d04d3b600..62929444e 100644 --- a/src/StatsTools/growth_witness.jl +++ b/src/StatsTools/growth_witness.jl @@ -37,7 +37,7 @@ end """ growth_witness(df::DataFrame, [b]; shift=:shift, norm=:norm, dτ=df.dτ[end], skip=0) Calculate the growth witness directly from a `DataFrame` returned by -[`lomc!`](@ref). The keyword arguments `shift` and `norm` +[`lomc!`](@ref Main.lomc!). The keyword arguments `shift` and `norm` can be used to change the names of the relevant columns. """ function growth_witness( @@ -52,7 +52,7 @@ end """ smoothen(noisy::AbstractVector, b) Smoothen the array `noisy` by averaging over a sliding window of length `b` and -wrapping `noisy` periodically. The [`mean(noisy)`](@ref) is preserved. +wrapping `noisy` periodically. The `mean(noisy)` is preserved. """ function smoothen(noisy::AbstractVector, b::Integer) l = length(noisy) diff --git a/src/StatsTools/reweighting.jl b/src/StatsTools/reweighting.jl index 07dea485c..0ffe5f2cf 100644 --- a/src/StatsTools/reweighting.jl +++ b/src/StatsTools/reweighting.jl @@ -78,7 +78,7 @@ w_lin(shift, h, dτ; kwargs...) = w_lin(Vector(shift), h, dτ; kwargs...) kwargs... ) -> r::RatioBlockingResult Compute the growth estimator with reference energy `E_r` by the reweighting -technique described in [Umirgar *et al.* (1993)](http://dx.doi.org/10.1063/1.465195), +technique described in [Umrigar *et al.* (1993)](http://dx.doi.org/10.1063/1.465195), see Eq. (20). `shift` and `wn` are equal length vectors containing the shift and walker number time series, respectively. @@ -95,7 +95,7 @@ When `h` is greater than the autocorrelation time scale of the `shift`, then `E_gr` (returned as `r.ratio`) is an unbiased but approximate estimator for the ground state energy ``E_0`` with an error ``\\mathcal{O}(dτ^2)`` and potentially increased confidence intervals compared to the (biased) shift estimator. -Error propagation is done with [`MonteCarloMeasurements`](@ref). Progagation through the +Error propagation is done with [`MonteCarloMeasurements`](https://github.com/baggepinnen/MonteCarloMeasurements.jl). Progagation through the logarithm can be modified by setting `change_type` to [`to_measurement`](@ref) in order to avoid `NaN` results from negative outliers. @@ -103,7 +103,7 @@ If `success==true` the blocking analysis was successful in `k-1` steps, using `blocks` uncorrelated data points. The second method calculates the growth estimator directly from a `DataFrame` returned by -[`lomc!`](@ref). The keyword arguments `shift_name` and `norm_name` can be used to change the names +[`lomc!`](@ref Main.lomc!). The keyword arguments `shift_name` and `norm_name` can be used to change the names of the relevant columns. See also [`mixed_estimator()`](@ref) and [`RatioBlockingResult`](@ref). @@ -162,7 +162,7 @@ end """ growth_estimator_analysis(df::DataFrame; kwargs...) -> (;df_ge, correlation_estimate, se, se_l, se_u) -Compute the [`growth_estimator`](@ref) on a `DataFrame` `df` returned from [`lomc!`](@ref) +Compute the [`growth_estimator`](@ref) on a `DataFrame` `df` returned from [`lomc!`](@ref Main.lomc!) repeatedly over a range of reweighting depths. @@ -269,7 +269,7 @@ end kwargs... ) Compute the mixed estimator by the reweighting -technique described in [Umirgar *et al.* (1993)](http://dx.doi.org/10.1063/1.465195), +technique described in [Umrigar *et al.* (1993)](http://dx.doi.org/10.1063/1.465195), Eq. (19) ```math E_\\mathrm{mix} = \\frac{\\sum_n w_{h}^{(n)} (Ĥ'\\mathbf{v})⋅\\mathbf{c}^{(n)}} @@ -277,7 +277,7 @@ E_\\mathrm{mix} = \\frac{\\sum_n w_{h}^{(n)} (Ĥ'\\mathbf{v})⋅\\mathbf{c}^{( ``` where the time series `hproj ==` ``(Ĥ'\\mathbf{v})⋅\\mathbf{c}^{(n)}`` and `vproj ==` ``\\mathbf{v}⋅\\mathbf{c}^{(m)}`` have the same length as `shift` -(See [`ProjectedEnergy`](@ref) on how to set these up). +(See [`ProjectedEnergy`](@ref Main.ProjectedEnergy) on how to set these up). Reweighting is done over `h` time steps and `length(shift) - skip` time steps are used for the blocking analysis done with [`ratio_of_means()`](@ref). `dτ` is the time step and `weights` a function that @@ -288,11 +288,11 @@ When `h` is greater than the autocorrelation time scale of the `shift`, then `r.ratio` is an unbiased but approximate estimator for the ground state energy ``E_0`` with an error ``\\mathcal{O}(dτ^2)`` and potentially increased confidence intervals compared to the unweighted ratio. -Error propagation is done with [`MonteCarloMeasurements`](@ref). +Error propagation is done with [`MonteCarloMeasurements`](https://github.com/baggepinnen/MonteCarloMeasurements.jl). Results are returned as [`RatioBlockingResult`](@ref). The second method calculates the mixed energy estimator directly from a `DataFrame` -returned by [`lomc!`](@ref). The keyword arguments `hproj_name`, `vproj_name`, and +returned by [`lomc!`](@ref Main.lomc!). The keyword arguments `hproj_name`, `vproj_name`, and `shift_name` can be used to change the names of the relevant columns. See also [`growth_estimator()`](@ref). @@ -322,7 +322,7 @@ end """ mixed_estimator_analysis(df::DataFrame; kwargs...) -> (; df_me, correlation_estimate, se, se_l, se_u) -Compute the [`mixed_estimator`](@ref) on a `DataFrame` `df` returned from [`lomc!`](@ref) +Compute the [`mixed_estimator`](@ref) on a `DataFrame` `df` returned from [`lomc!`](@ref Main.lomc!) repeatedly over a range of reweighting depths. Returns a `NamedTuple` with the fields @@ -447,8 +447,8 @@ Argument `shift` is of type `Vector{Vector}`, with each element `Vector` holding the shift data for each individual replica. The second method computes the Rayleigh quotient directly from a `DataFrame` returned by -[`lomc!`](@ref). The keyword arguments `shift_name`, `op_name` and `vec_name` can be used to -change the names of the relevant columns, see [`AllOverlaps`](@ref) for default +[`lomc!`](@ref Main.lomc!). The keyword arguments `shift_name`, `op_name` and `vec_name` can be used to +change the names of the relevant columns, see [`AllOverlaps`](@ref Main.AllOverlaps) for default formatting. The operator overlap data can be scaled by a prefactor `Anorm`. A specific reweighting depth can be set with keyword argument `h`. The default is `h = 0` which calculates the Rayleigh quotient without reweighting. @@ -461,7 +461,7 @@ for the blocking analysis done with [`ratio_of_means()`](@ref). calulates the weights. See [`w_exp()`](@ref) and [`w_lin()`](@ref). Additional keyword arguments are passed on to [`ratio_of_means()`](@ref). -Error propagation is done with [`MonteCarloMeasurements`](@ref). +Error propagation is done with [`MonteCarloMeasurements`](https://github.com/baggepinnen/MonteCarloMeasurements.jl). Results are returned as [`RatioBlockingResult`](@ref). See also [`mixed_estimator`](@ref), [`growth_estimator()`](@ref). @@ -530,7 +530,7 @@ end """ rayleigh_replica_estimator_analysis(df::DataFrame; kwargs...) -> (; df_rre, df_se) -Compute the [`rayleigh_replica_estimator`](@ref) on a `DataFrame` `df` returned from [`lomc!`](@ref) +Compute the [`rayleigh_replica_estimator`](@ref) on a `DataFrame` `df` returned from [`lomc!`](@ref Main.lomc!) repeatedly over a range of reweighting depths. Returns a `NamedTuple` with the fields @@ -558,7 +558,7 @@ using StatsPlots @df df_rre plot!(:h, :val, ribbon = (:val_l, :val_u), label="E_mix") # Rayleigh quotient estimator as a function of reweighting depth xlabel!("h") ``` -See also: [`rayleigh_replica_estimator`](@ref), [`mixed_estimator_analysis`](@ref), [`AllOverlaps`](@ref). +See also: [`rayleigh_replica_estimator`](@ref), [`mixed_estimator_analysis`](@ref), [`AllOverlaps`](@ref Main.AllOverlaps). """ function rayleigh_replica_estimator_analysis( df::DataFrame; @@ -649,8 +649,8 @@ E_\\mathrm{p} = \\frac{\\sum_n \\mathbf{v}⋅Ĥ\\mathbf{c}^{(n)}} ``` where the time series `df.hproj ==` ``\\mathbf{v}⋅Ĥ\\mathbf{c}^{(n)}`` and `df.vproj ==` ``\\mathbf{v}⋅\\mathbf{c}^{(m)}`` are taken from `df`, skipping the first -`skip` entries (use `post_step = `[`ProjectedEnergy()`](@ref) to set these up in -[`lomc!()`](@ref)). +`skip` entries (use `post_step = `[`ProjectedEnergy()`](@ref Main.ProjectedEnergy) to set these up in +[`lomc!()`](@ref Main.lomc!)). `projected_energy` is equivalent to [`mixed_estimator`](@ref) with `h=0`. The keyword arguments `hproj` and `vproj` diff --git a/src/StatsTools/variational_energy_estimator.jl b/src/StatsTools/variational_energy_estimator.jl index 15334e21f..cf6c6c407 100644 --- a/src/StatsTools/variational_energy_estimator.jl +++ b/src/StatsTools/variational_energy_estimator.jl @@ -22,12 +22,12 @@ where the sum goes over distinct pairs out of the ``R`` replicas. See [arXiv:2103.07800](http://arxiv.org/abs/2103.07800). The `DataFrame` version can extract the relevant information from the result of -[`lomc!`](@ref). Set up [`lomc!`](@ref) with the keyword argument +[`lomc!`](@ref Main.lomc!). Set up [`lomc!`](@ref Main.lomc!) with the keyword argument `replica = AllOverlaps(R)` and `R ≥ 2`. If passing `shifts` and `overlaps`, the data has to be arranged in the correct order (as provided in the `DataFrame` version). -See [`AllOverlaps`](@ref). +See [`AllOverlaps`](@ref Main.AllOverlaps). """ function variational_energy_estimator(shifts, overlaps; kwargs...) num_replicas = length(shifts) diff --git a/src/StochasticStyles/StochasticStyles.jl b/src/StochasticStyles/StochasticStyles.jl index fef6a1154..a4102d375 100644 --- a/src/StochasticStyles/StochasticStyles.jl +++ b/src/StochasticStyles/StochasticStyles.jl @@ -1,16 +1,15 @@ """ This module provides concrete implementations of [`StochasticStyle`](@ref)s, which -specify the algorithm used by [`lomc!`](@ref) when +specify the algorithm used by [`lomc!`](@ref Main.lomc!) when performing stochastic matrix-vector multiplication. -# Stochastic styles: +# Implemented stochastic styles: * [`StochasticStyle`](@ref) * [`IsStochasticInteger`](@ref) * [`IsDeterministic`](@ref) * [`IsStochasticWithThreshold`](@ref) * [`IsDynamicSemistochastic`](@ref) -* [`IsExplosive`](@ref) * [`StyleUnknown`](@ref) The offdiagonal spawning is defined in `spawning.jl` and is controlled by setting a diff --git a/src/StochasticStyles/styles.jl b/src/StochasticStyles/styles.jl index a2b84478a..87a7cfeb9 100644 --- a/src/StochasticStyles/styles.jl +++ b/src/StochasticStyles/styles.jl @@ -33,7 +33,7 @@ Stochastic propagation with complex walker numbers representing two populations walkers. When using this style, make sure to set a complex target number walkers in the -[`ShiftStrategy`](@ref)! +[`ShiftStrategy`](@ref Main.ShiftStrategy)! This style is experimental. @@ -166,7 +166,7 @@ setting `compression` to [`NoCompression`](@ref). * `spawning = WithReplacement()`: [`SpawningStrategy`](@ref) to use for the non-exact spawns. See [`WithReplacement`](@ref) for behaviour and possible arguments. -* `compression = ThresholdCompression(proj_threshold)`: [`CompressionStartegy`](@ref) used +* `compression = ThresholdCompression(proj_threshold)`: [`CompressionStrategy`](@ref) used to compress the vector after a step. Overrides `proj_threshold`. See also [`StochasticStyle`](@ref). diff --git a/src/lomc.jl b/src/lomc.jl index f140be3f0..f9dd83c64 100644 --- a/src/lomc.jl +++ b/src/lomc.jl @@ -11,7 +11,7 @@ Can be advanced a step forward with [`advance!`](@ref). * `v`: vector. * `w`: working memory. * `pnorm`: previous walker number (see [`walkernumber`](@ref)). -* `params`: the [`FCIQMCRunStrategy`](@ref). +* `params`: the [`FciqmcRunStrategy`](@ref). * `id`: appended to reported columns. See also [`QMCState`](@ref), [`ReplicaStrategy`](@ref), [`replica_stats`](@ref), diff --git a/src/strategies_and_params/poststepstrategy.jl b/src/strategies_and_params/poststepstrategy.jl index f9554edbb..4f293ddef 100644 --- a/src/strategies_and_params/poststepstrategy.jl +++ b/src/strategies_and_params/poststepstrategy.jl @@ -186,7 +186,7 @@ end """ Timer <: PostStepStrategy -Record current time after every step. See [`Base.time`](@ref) for information on what time +Record current time after every step. See `Base.Libc.time` for information on what time is recorded. """ struct Timer <: PostStepStrategy end diff --git a/src/strategies_and_params/reportingstrategy.jl b/src/strategies_and_params/reportingstrategy.jl index aefa97f72..dbe05b026 100644 --- a/src/strategies_and_params/reportingstrategy.jl +++ b/src/strategies_and_params/reportingstrategy.jl @@ -129,7 +129,7 @@ end """ report_after_step(::ReportingStrategy, step, report, state) -This function is called at the very end of a step, after `reporting_interval`(@ref) steps. +This function is called at the very end of a step, after [`reporting_interval`](@ref) steps. For example, it can be used to print some information to `stdout`. """ function report_after_step(::ReportingStrategy, args...) @@ -168,7 +168,7 @@ end The default [`ReportingStrategy`](@ref). Report every `reporting_interval`th step to a `DataFrame` and write info message to `io` every `info_interval`th reported step (unless `writeinfo == false`). The flag `writeinfo` is useful for controlling info messages in MPI codes, e.g. by setting -`writeinfo =`[`is_mpi_root()`](@ref). +`writeinfo = `[`is_mpi_root()`](@ref Rimu.RMPI.is_mpi_root). """ @with_kw struct ReportDFAndInfo <: ReportingStrategy reporting_interval::Int = 1 @@ -201,7 +201,7 @@ jobs or large numbers of replicas, when the report can incur a significant memor * `chunk_size = 1000`: the size of each chunk that is written to the file. A `DataFrame` of this size is collected in memory and written to disk. When saving, an info message is also printed to `io`. -* `save_if =`[`is_mpi_root()`](@ref): if this value is true, save the report, otherwise +* `save_if = `[`is_mpi_root()`](@ref Rimu.RMPI.is_mpi_root): if this value is true, save the report, otherwise ignore it. * `return_df = false`: if this value is true, read the file and return the data frame at the end of computation. Otherwise, an empty `DataFrame` is returned.