diff --git a/docs/documentation/compilation/advanced_compilation.md b/docs/documentation/compilation/advanced_compilation.md new file mode 100644 index 00000000..5d3a90ea --- /dev/null +++ b/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 + ``` diff --git a/docs/documentation/compilation/building_documentation.md b/docs/documentation/compilation/building_documentation.md new file mode 100644 index 00000000..09e5d805 --- /dev/null +++ b/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 +``` diff --git a/docs/documentation/compilation/julia_wrapper.md b/docs/documentation/compilation/julia_wrapper.md new file mode 100644 index 00000000..ec0d7417 --- /dev/null +++ b/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). diff --git a/docs/documentation/index.md b/docs/documentation/index.md index 0701cf73..8e2697de 100644 --- a/docs/documentation/index.md +++ b/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 diff --git a/docs/tutorials.md b/docs/examples.md similarity index 99% rename from docs/tutorials.md rename to docs/examples.md index 51e5eedc..e83ed8af 100644 --- a/docs/tutorials.md +++ b/docs/examples.md @@ -1,5 +1,5 @@ --- -title: Tutorials +title: Examples --- ## Introduction to Exact Diagonalization using XDiag diff --git a/docs/user_guide.md b/docs/user_guide.md new file mode 100644 index 00000000..894a85d2 --- /dev/null +++ b/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: | + diff --git a/docs/user_guide/first_steps.md b/docs/user_guide/first_steps.md new file mode 100644 index 00000000..1dbe4a15 --- /dev/null +++ b/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 +``` diff --git a/docs/user_guide/input_output.md b/docs/user_guide/input_output.md new file mode 100644 index 00000000..b2a97bce --- /dev/null +++ b/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 diff --git a/docs/user_guide/installation.md b/docs/user_guide/installation.md new file mode 100644 index 00000000..c876906c --- /dev/null +++ b/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. diff --git a/examples/usage_examples/main.cpp b/examples/usage_examples/main.cpp index e543f3b9..38c16f98 100644 --- a/examples/usage_examples/main.cpp +++ b/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 nup = input["nup"].as(); +double J1 = input["J1"].as(); +double J2 = input["J2"].as(); + +auto block = Spinhalf(N, nup); +auto H = OpSum(); +for (int i=0; i