Updated documentation

docs/documentation/compilation/advanced_compilation.md

@@ -0,0 +1,54 @@
+---
+title: Advanced Compilation
+---
+
+
+- **Parallel compilation**
+    To speed up the compilation process, the build step can be performed in parallel using the `-j` flag
+
+    ```bash
+    cmake --build build -j
+    ```
+
+- **Listing compile options**
+
+    The available compilation options can be displayed using
+    ``` bash
+    cmake -L .
+    ```
+
+- **Choosing a certain compiler**
+
+    The compiler (e.g. `icpx`) can be specified using
+    ``` bash
+    cmake -S . -B build -D CMAKE_CXX_COMPILER=icpx
+    ```
+
+    !!! warning 
+
+        If the `xdiag` library is compiled with a certain compiler, it is
+        advisable to also compile the application codes with the same compiler.
+
+- **Setting the install path**
+
+    In the installation step, the install directory can be set in the following way
+    ```bash
+    cmake --install build --prefix /my/install/prefix
+    ```
+
+- **Disabling HDF5/OpenMP**
+
+    To disable support for [HDF5](https://www.hdfgroup.org/solutions/hdf5/)
+    or [OpenMP](https://www.openmp.org/) support, use
+    ```bash
+    cmake -S . -B build -D XDIAG_DISABLE_OPENMP=On -D XDIAG_DISABLE_HDF5=On
+    ```
+
+- **Building and running tests**
+
+    To compile and run the testing programs, use
+    ``` bash
+    cmake -S . -B build -D BUILD_TESTING=On
+    cmake --build build
+    build/tests/tests
+    ```

docs/documentation/compilation/building_documentation.md

@@ -0,0 +1,14 @@
+---
+title: Building Documentation
+---
+The source files for the documentation can be found in the directory `docs`. The documentation is built using [Material for MKDocs](https://squidfunk.github.io/mkdocs-material/). To work on it locally, it can be served using 
+
+```bash
+mkdocs serve
+```
+
+from the `xdiag` root source directory. A local build of the documentation can then be accessed in a webbrowser at the adress
+
+```
+127.0.0.1:8000
+```

docs/documentation/compilation/julia_wrapper.md

@@ -0,0 +1,20 @@
+---
+title: Building the Julia wrapper
+---
+
+In order to develop and extend the julia wrapper, one should work locally and build a local version of the `xdiag` Julia binaries. First, get the path to the `CxxWrap` package of julia. To do so, enter the Julia REPL,
+```bash
+julia
+```
+and print the corresponding path using
+```julia
+using CxxWrap
+CxxWrap.prefix_path()
+```
+This should print the `/path/to/libcxxwrap-julia-prefix`. This is then used to configure the cmake compilation.
+``` bash
+cmake -S . -B build -D XDIAG_JULIA_WRAPPER=On -D CMAKE_PREFIX_PATH=/path/to/libcxxwrap-julia-prefix
+cmake --build build
+cmake --install build
+```
+The julia wrapper library can then be found in the install dir as `libxdiagjl.so`, (or the corresponding library format on non-Linux systems).

docs/documentation/index.md

@@ -4,6 +4,14 @@ title: Overview
 
 # Documentation
 
+## Building
+| Name                                                   | Description                                                      |                          Language |
+|:-------------------------------------------------------|:-----------------------------------------------------------------|----------------------------------:|
+| [Compilation](compilation/advanced_compilation.md)     | advanced settings for compilation of the C++ library using CMake |                :simple-cplusplus: |
+| [Documentation](compilation/building_documentation.md) | how to build and work on the documentation locally               |                 :simple-markdown: |
+| [Julia Wrapper](compilation/julia_wrapper.md)          | how to build and develop the Julia wrapper locally               | :simple-cplusplus: :simple-julia: |
+|                                                        |                                                                  |                                   |
+
 ## Algorithms
 
 

docs/tutorials.md → docs/examples.md

@@ -1,5 +1,5 @@
 ---
-title: Tutorials
+title: Examples
 ---
 
 ## Introduction to Exact Diagonalization using XDiag

docs/user_guide.md

@@ -0,0 +1,26 @@
+---
+title: User guide
+---
+
+**A step-by-step guide to using XDiag**
+
+| **[Installation](user_guide/installation.md)**                      |                                      | Language           |
+|---------------------------------------------------------------------|--------------------------------------|--------------------|
+| [Julia installation](user_guide/installation.md#julia-installation) | How to install the XDiag in Julia    | :simple-julia:     |
+| [C++ compilation](user_guide/installation.md#c-compilation)         | How to compile the XDiag C++ library | :simple-cplusplus: |
+
+
+| **[First steps](user_guide/first_steps.md)**                             |                                                  | Language                          |
+|--------------------------------------------------------------------------|--------------------------------------------------|-----------------------------------|
+| [Writing code](user_guide/first_steps.md#application-code)               | How to write an application using XDiag          | :simple-cplusplus: :simple-julia: |
+| [Compilation](user_guide/first_steps.md#compiling-your-application-code) | How to compile an application using XDiag in C++ | :simple-cplusplus:                |
+| [Hilbert spaces](user_guide/first_steps.md)                              | How to define a Hilbert space                    | :simple-cplusplus: :simple-julia: |
+| [Operators](user_guide/first_steps.md)                                   | How to define an operator                        | :simple-cplusplus: :simple-julia: |
+| [Ground state](user_guide/first_steps.md)                                | How compute a ground state (energy)              | :simple-cplusplus: :simple-julia: |
+| [Measurements](user_guide/first_steps.md)                                | How to measure an observable on a state          | :simple-cplusplus: :simple-julia: |
+
+
+| **[Input/Output](user_guide/input_output.md)** |                                    | Language           |
+|------------------------------------------------|------------------------------------|--------------------|
+| [TOML](user_guide/input_output.md)             | How to read input from a TOML file | :simple-cplusplus: |
+

docs/user_guide/first_steps.md

@@ -0,0 +1,54 @@
+---
+title: First steps
+---
+
+## Application code
+
+Let us set up our first program using the `xdiag` library. 
+
+=== "Julia"
+
+	```julia 
+	--8<-- "examples/hello_world/main.jl"
+	```
+
+=== "C++"
+	```c++ 
+	--8<-- "examples/hello_world/main.cpp"
+	```
+
+The function `say_hello()` prints out a welcome message, which also contains information which exact XDiag version is used. In Julia this is all there is to it.
+
+For the C++ code we need to create two files to compile the program. The first is the actual `C++` code. What is maybe a bit unfamiliar is the `try / catch` block. XDiag implements a traceback mechanism for runtime errors, which is activated by this idiom. While not stricly necessary here, it is a good practice to make use of this.
+
+## Compiling your application code
+
+Now that the application program is written, we next need to set up the compilation instructions using [CMake](https://cmake.org/). To do so we create a second file called `CMakeLists.txt` in the same directory.
+
+```cmake
+--8<-- "examples/hello_world/CMakeLists.txt"
+```
+
+You should replace `"/path/to/xdiag/install"` with the appropriate directory where your XDiag library is installed after compilation. This exact `CMakeLists.txt` file can be used to compile any XDiag application.
+
+!!! info
+
+    For using the distributed XDiag library the last line of the above
+    `CMakeLists.txt` should be changed to
+
+    ```cmake
+    target_link_libraries(main PUBLIC xdiag::xdiag_distributed)
+    ```
+
+We then compile the application code,
+
+```bash
+cmake -S . -B build
+cmake --build build
+```
+
+and finally run our first `xdiag` application.
+
+```bash
+./build/main
+```

docs/user_guide/input_output.md

@@ -0,0 +1,8 @@
+---
+title: Input/Output
+---
+
+Julia features a variety of packages facilitating input and output of data. For C++, we provide convenient functionality for [TOML](https://toml.io/en/) and [HDF5](https://www.hdfgroup.org/solutions/hdf5/) files.
+
+## TOML
+For simulations is can often be useful to read input paramters from a file. The 

docs/user_guide/installation.md

@@ -0,0 +1,69 @@
+---
+title: Installation
+---
+
+## Julia installation
+
+Enter the package mode using `]` in the Julia REPL and type:
+```julia
+add XDiag
+```
+
+That's it!
+
+## C++ compilation
+
+Using XDiag with C++ is a two-step process. First the `xdiag` library needs
+to be compiled and installed. Therafter, application codes are compiled
+in a second step. The library can be compiled in two different versions:
+
+- **Normal** library: features parallelization using OpenMP only
+- **Distributed** library: features distributed-memory parallelization using MPI. 
+
+### Prerequisites
+
+* A C++ compiler that supports C++17 (`g++`, `clang`, or Intel's `icpx`)
+* [git](https://git-scm.com/) version control system
+* [CMake](https://cmake.org/) build system generator 
+* A linear algebra backend (BLAS/LAPACK, Intel MKL or Accelerate on OSX)
+* **optional** [HDF5](https://www.hdfgroup.org/solutions/hdf5/), [OpenMP](https://www.openmp.org/)
+* **optional** [MPI](https://en.wikipedia.org/wiki/Message_Passing_Interface) for the distributed library
+
+
+### Basic Compilation
+
+- **Download** the source code using [git](https://git-scm.com/)
+  ```bash
+  cd /path/to/where/xdiag/should/be
+  git clone https://github.com/awietek/xdiag.git
+  ```
+
+- **Compile the default library**
+  ``` bash
+  cd xdiag
+  cmake -S . -B build
+  cmake --build build
+  cmake --install build
+  ```
+  By default, the library is now installed in the subdirectory `install`.
+
+- **Compile the distributed library**
+
+    To use the distributed computing features of `xdiag`, the distributed
+    library has to be built which requires [MPI](https://en.wikipedia.org/wiki/Message_Passing_Interface).
+    ``` bash
+    cd xdiag
+    cmake -S . -B build -D XDIAG_DISTRIBUTED=On
+    cmake --build build
+    cmake --install build
+    ```
+
+    !!! info
+
+        It might be necessary to explicitly define MPI compiler, e.g. `mpicxx` like this
+        ```bash
+        cmake -S . -B build -D XDIAG_DISTRIBUTED=On -D CMAKE_CXX_COMPILER=mpicxx
+        ```
+
+
+Of course the compilation process can be modified to allow for further optimizations. We collect several common scenarios in the [Advanced Compilation](documentation/compilation/advanced_compilation.md) guide.

examples/usage_examples/main.cpp

@@ -6,6 +6,27 @@ using namespace xdiag;
 int main() try {
   // clang-format off
 
+
+{
+// --8<-- [start:FileTOML]
+auto input = FileTOML("input.toml");
+int N = input["N"].as<int>();
+int nup = input["nup"].as<int>();
+double J1 = input["J1"].as<double>();
+double J2 = input["J2"].as<double>();
+
+auto block = Spinhalf(N, nup);
+auto H = OpSum();
+for (int i=0; i<N; ++i){
+  H += J1 * Op("HB", {i, (i+1)%N});
+  H += J2 * Op("HB", {i, (i+2)%N});
+}
+
+double e0 = eigval0(H, block);
+XDIAG_SHOW(e0);
+// --8<-- [end:FileTOML]
+}
+
 {
 // --8<-- [start:Permutation]
 Permutation p1 = {0, 2, 1, 3};

mkdocs.yml

@@ -35,8 +35,7 @@ extra_css:
 
 nav:
   - Home: index.md
-  - Installation: installation.md
-  - Quick start: quickstart.md
-  - Tutorials: tutorials.md
+  - User Guide: user_guide.md
+  - Examples: examples.md
   - Documentation: documentation
   - Releases: releases