Add devdocs + some cleanup

docs/make.jl

@@ -44,6 +44,12 @@ makedocs(
             "General exports" => [
                 "General" => "legacy/methods/general.md"
             ],
+        ],
+        "DQMC Dev Docs" => [
+            "devdocs/model_field.md",
+            "devdocs/dqmc_stacks.md",
+            "devdocs/measurements.md",
+            "devdocs/linalg.md"
         ]
     ],
     # assets = ["assets/custom.css", "assets/custom.js"]

docs/src/DQMC/Introduction.md

@@ -8,7 +8,7 @@ The minimal working example for a DQMC simulation is the following.
 using MonteCarlo
 
 dqmc = DQMC(HubbardModel(), beta = 1.0)
-run(dqmc)
+run!(dqmc)
 ```
 
 This will set up and run a DQMC simulation at inverse temperature $\beta = 1.0$ using an attractive Hubbard model with a two by two square lattice. Of course this example is not very useful. In practice you will want to modify lots of parameters and components of the simulation. We give a brief overview of the different components here. You can also check the examples section for some more involved and realistic examples.

docs/src/DQMC/fields.md

@@ -42,7 +42,7 @@ One method of solving this integral is Gauß-Hermite quadrature. With four weigh
 
 where $\gamma$ and $\eta$ give the weights and nodes for a given $x$. For the density-channel version $V_\uparrow = V_\downarrow = \sqrt{U}$ and $C = 0.5 \sqrt{U}$, for the spin channel $V_\uparrow = - V\downarrow = \sqrt{U}$ and $C = 0$. These two cases are implemented as `DensityGHQField` and `MagneticGHQField`. Just like with the Hirsch field these two methods can create real or complex interaction matrices depending on the sign $U$ and the Density case makes use of symmetry.
 
-See [ALF](https://git.physik.uni-wuerzburg.de/ALF/ALF) Documentation (Auxiliary Field Quantum Monte Carlo section) and https://arxiv.org/pdf/2009.04491.pdf
+See [ALF](https://git.physik.uni-wuerzburg.de/ALF/ALF) Documentation (Auxiliary Field Quantum Monte Carlo section) and the related [paper](https://arxiv.org/pdf/2009.04491.pdf).
 
 ## Performance & Accuracy
 

docs/src/DQMC/lattice.md

@@ -63,7 +63,7 @@ Note that bonds also have an integer label which can be used to differentiate th
 
 Lattice Iterators are to some degree a backend component. They specify a way to iterate through the lattice, and are mainly used for DQMC measurements which frequently require specific pairings of sites. The iterators fall into three categories:
 
-### DirectLatticeIterator`
+### DirectLatticeIterator
 
 First we have `DirectLatticeIterator`. These iterators return just site indices, e.g. `(source_index, target_index)`. The concrete implementations include:
 

docs/src/DQMC/model.md

@@ -19,36 +19,4 @@ You can create a Hubbard model with `HubbardModel()`. Optional keyword arguments
 - `L::Integer = 2` is the linear system size of the default lattice (Chain/Square/Cubic)
 - `t::Float64 = 1.0` is the hopping strength.
 - `mu::Float64 = 0.0` is the chemical potential. (Must be 0 if U is negative.)
-- `U::Float64 = 1.0` is the interaction strength.
-
-## Creating your own Model
-
-To create your own model you will need to inherit from the abstract type `Model`. There is a set of mandatory and optional methods you must/can implement:
-
-#### Mandatory Methods
-
-A custom model needs to implement these methods to function
-
-- `lattice(model)` needs to return a MonteCarlo compatible lattice
-- `nflavors(model)` needs to return the number of unique fermion flavors of the hopping matrix. For example, in a two spin model this would return 2 if the hopping matrix is different between spin up and down, or 1 if one sector is a copy of the other. Internally this is used together with `nflavors(field)` to optimize spin/flavor symmetric systems.
-- `hopping_matrix(model)` needs to generate the hopping matrix, which includes all quadratic terms. (I.e. also the chemical potential.) The hopping matrix should only include as many flavors as necessary. If the hopping matrix contains two copies of the same matrix, one for spin up and one for spin down for example, then it should only return one of these. Expanding it to an appropriate size is handled internally.
-
-#### (Semi-) Optional Methods
-
-These methods aren't strictly necessary to implement, but may boost performance when implemented. It is recommended to provide these if the defaults do not apply.
-
-
-- `_save(file::FileLike, entryname, model)` should write model information to the given file. It should also save the lattice via `_save(file, entryname, lattice)` and save a unique `tag`. If this is not implemented JLD2 will be asked to save the type as is, which makes it hard to load data when the model type is edited.
-- `_load(data, ::Val{Symbol(tag)})` loads a model from `data`, which typically is a JLDFile. Note that saved tag is used to dispatch to the correct method.
-- `intE_kernel(mc, model, idxs, G, ::Val{flv})` should be implemented to enable measurements of the energy from the interactive term as well as the total energy. 
-- `choose_field(model)` returns the default field type for a given model. If this is not implemented a field must be passed to `DQMC`.
-
-#### Optional Methods
-
-- `hopping_eltype(model) = eltype(hopping_matrix(model))` returns the element type of the hopping matrix.
-- `hopping_matrix_type(field, model) = typeof(pad_to_nflavors(field, model, hopping_matrix(model)))` return the matrix type of the hopping matrix.
-- `greens_eltype(field, model) = generalized_eltype(interaction_eltype(field), hopping_eltype(model))` returns the element type of the greens function. This must be compatible with element types of the hopping matrix and the interaction matrix.
-- `greens_matrix_type(field, model) = Matrix{greens_eltype(field, model)}` returns the full type of the greens function. This must be compatible with both the type of the hopping matrix and the interaction matrix.
-* `parameters(m::Model)` should collect the parameters from the model and lattice in a NamedTuple.
-
-Also note that you may need to update the measurement kernels. More information about that on the measurement page.
+- `U::Float64 = 1.0` is the interaction strength.

docs/src/devdocs/FileIO.md

@@ -0,0 +1,20 @@
+# FileIO
+
+MonteCarlo.jl uses JLD2 for FileIO. While it is possible to save structs directly with JLD2, it becomes difficult to load when the struct has changed. Therefore MonteCarlo.jl implements a custom `_save` and `_load` function for most structs. In general these functions are implemented as
+
+```julia
+function _save(file::FileLike, key::String, object)
+    write(file, "$key/VERSION", some_int)
+    write(file, "$key/tag", "some identifiying name")
+    # write data ...
+end
+
+function _load(data::FileData, ::Val{:some_tag})
+    # maybe check data["VERSION"]
+    # load file from data
+end
+```
+
+where `FileData` is a wrapper around `Dict{String, Any}`, which allows accessing the dictionary returned by `JLD2.load` as if it were a nested dictionary. I.e. rather than `data["key1/key2/key3"]` you can use `data["key1"]["key2"]["key3"]` with it, which aligns better to the way data is saved and loaded. `FileLike` is a `Union{JLD2.JLDFile, JLD2.Group, FileData}`. The "tag" saved in each `_save` function is used to identify what is saved, and it later used for dispatch in `_load`.
+
+The entrypoint for saving is the `save` function "src/FileIO.jl". The function includes functionality to rename a file to avoid overwriting an existing and includes compression. It also writes some GIT information which is printed in `load` if the load fails.