Docs: improved build and GUI docs.

Added images and brief descriptions to the GUI docs.
spirit-code · Jun 13, 2019 · bc2c2b9 · bc2c2b9
1 parent e51fd54
commit bc2c2b9
Show file tree

Hide file tree

Showing 4 changed files with 105 additions and 48 deletions.
diff --git a/docs/Build_Unix_OSX.md b/docs/Build_Unix_OSX.md
@@ -8,26 +8,21 @@ or the desktop user interface yourself.
 The **Spirit** framework is designed to run across different
 platforms and uses `CMake` for its build process, which will
 generate the appropriate build scripts for each platform.
-To list all available build options, call
-```
-cd build
-cmake -LH ..
-```
 
 System-wide installation is not actively supported.
 While you can call `make install` after building,
 you may not achieve the desired results.
 
 
 Core library
--------------------------
+--------------------------------------
 
-### Requirements
+**Requirements**
 
 - cmake >= 3.2
 - compiler with C++11 support, e.g. gcc >= 5.1
 
-### Build
+**Build**
 
 CMake is used to automatically generate makefiles.
 
@@ -39,20 +34,22 @@ $ cd spirit
 $ mkdir build
 $ cd build
 
-# Generate a solution file
+# Generate makefiles
 $ cmake ..
 
-# To manually specify the build type, call `cmake --build . --config Release`
-# Or (default build type is "Release") simply run
+# Build
 $ make
 ```
 
 Note that you can use the `-j` option of make to run the
 build in parallel.
 
+To manually specify the build type (default is 'Release'),
+call `cmake --build . --config Release` instead of `make`.
+
 
 Desktop GUI
--------------------------
+--------------------------------------
 
 By default, the desktop GUI will try to build. The corresponding
 CMake option is `SPIRIT_UI_CXX_USE_QT`.
@@ -67,7 +64,7 @@ remotely modern graphics card.
 
 
 Python package
--------------------------
+--------------------------------------
 
 The Python package is built by default. The corresponding
 CMake option is `SPIRIT_BUILD_FOR_PYTHON`.
@@ -82,15 +79,15 @@ e.g. `pip install spirit --user`.
 
 
 OpenMP backend
--------------------------
+--------------------------------------
 
 The OpenMP backend can be used to speed up calculations by
 using a multicore CPU.
 
 At least version 4.5 of OpenMP needs to be supported by your
 compiler.
 
-### Build
+**Build**
 
 You need to set the corresponding CMake variable, e.g.
 by calling
@@ -103,7 +100,7 @@ cd ..
 
 
 CUDA backend
--------------------------
+--------------------------------------
 
 The CUDA backend can be used to speed up calculations by
 using a GPU.
@@ -116,10 +113,10 @@ Spirit uses [unified memory](https://devblogs.nvidia.com/unified-memory-cuda-beg
 to `float` in order to avoid the performance cost of `double`
 precision operations on GPUs.
 
-### Build
+**Build**
 
-You need to set the corresponding CMake variable, e.g.
-by calling
+You need to set the corresponding `SPIRIT_USE_CUDA` CMake
+variable, e.g. by calling
 
 ```
 cd build
@@ -128,17 +125,20 @@ cd ..
 ```
 
 You may additionally need to
-- select the appropriate arch for your GPU using the `SPIRIT_CUDA_ARCH` CMake variable
+- pass the `CUDA_TOOLKIT_ROOT_DIR` to cmake or edit it in
+  the root CMakeLists.txt
+- select the appropriate arch for your GPU using the
+  `SPIRIT_CUDA_ARCH` CMake variable
 
 
 Web assembly library
--------------------------
+--------------------------------------
 
 Using emscripten, Spirit can be built as a Web assembly
 library, meaning that it can be used e.g. from within
 JavaScript.
 
-### Build
+**Build**
 
 The CMake option you need to set to `ON` is called
 `SPIRIT_BUILD_FOR_JS`.
@@ -153,4 +153,19 @@ cd build
 cmake .. -DCMAKE_TOOLCHAIN_FILE=/usr/local/emsdk/emscripten/1.38.29/cmake/Modules/Platform/Emscripten.cmake
 make
 cd ..
-```
+```
+
+
+Further build configuration options
+--------------------------------------
+
+More options than described above are available,
+allowing for example to deactivate building the
+Python library or the unit tests.
+
+To list all available build options, call
+```
+cd build
+cmake -LH ..
+```
+The build options of Spirit all start with `SPIRIT_`.
diff --git a/docs/Build_Windows.md b/docs/Build_Windows.md
@@ -8,15 +8,10 @@ or the desktop user interface yourself.
 The **Spirit** framework is designed to run across different
 platforms and uses `CMake` for its build process, which will
 generate the appropriate build scripts for each platform.
-To list all available build options, call
-```
-cd build
-cmake -LH ..
-```
 
 
 Core library
--------------------------
+--------------------------------------
 
 The Visual Studio Version needs to be specified and it usually
 makes sense to specify 64bit, as it otherwise defaults to 32bit.
@@ -46,12 +41,12 @@ for debugging.
 
 
 Desktop GUI
--------------------------
+--------------------------------------
 
 By default, the desktop GUI will try to build. The corresponding
 CMake option is `SPIRIT_UI_CXX_USE_QT`.
 
-### Additional requirements
+**Additional requirements**
 
 - Qt >= 5.7 (including qt-charts)
 - OpenGL drivers >= 3.3
@@ -64,7 +59,7 @@ remotely modern graphics card.
 
 
 Python package
--------------------------
+--------------------------------------
 
 The Python package is built by default. The corresponding
 CMake option is `SPIRIT_BUILD_FOR_PYTHON`.
@@ -79,15 +74,15 @@ e.g. `pip install spirit --user`.
 
 
 OpenMP backend
--------------------------
+--------------------------------------
 
 Using OpenMP on Windows is not officially supported.
 While it is possible to use it, the build process is
 nontrivial.
 
 
 CUDA backend
--------------------------
+--------------------------------------
 
 The CUDA backend can be used to speed up calculations by
 using a GPU.
@@ -98,10 +93,7 @@ At least version 8 of the CUDA toolkit is required!
 to `float` in order to avoid the performance cost of `double`
 precision operations on GPUs.
 
-### Build
-
-The CMake option you need to set to `ON` is called
-`SPIRIT_BUILD_FOR_JS`.
+**Build**
 
 You need to set the corresponding `SPIRIT_USE_CUDA` CMake
 variable, e.g. by calling
@@ -115,16 +107,41 @@ cd ..
 or by setting the option in the CMake GUI and re-generating.
 
 You may additionally need to
-- manually set the host compiler ("C:/Program Files (x86)/.../bin/cl.exe)
-- select the appropriate arch for your GPU using the `SPIRIT_CUDA_ARCH` CMake variable
+- manually set the host compiler
+  ("C:/Program Files (x86)/.../bin/cl.exe)
+- manually set the CUDA Toolkit directory in the CMake GUI or
+  pass the `CUDA_TOOLKIT_ROOT_DIR` to cmake or edit it in the
+  root CMakeLists.txt
+- select the appropriate arch for your GPU using the
+  `SPIRIT_CUDA_ARCH` CMake variable
+- add the CUDA Toolkit directory to the Windows PATH, so that
+  the libraries will be found when the code is executed
 
 
 Web assembly library
--------------------------
+--------------------------------------
 
 Using emscripten, Spirit can be built as a Web assembly
 library, meaning that it can be used e.g. from within
 JavaScript.
 
+The CMake option you need to set to `ON` is called
+`SPIRIT_BUILD_FOR_JS`.
+
 The build process on Windows has not been tested by us
-and we do not officially support it.
+and we do not officially support it.
+
+
+Further build configuration options
+--------------------------------------
+
+More options than described above are available,
+allowing for example to deactivate building the
+Python library or the unit tests.
+
+To list all available build options, call
+```
+cd build
+cmake -LH ..
+```
+The build options of Spirit all start with `SPIRIT_`.
diff --git a/docs/UI-Qt.md b/docs/UI-Qt.md
@@ -65,22 +65,47 @@ Additional features
 How to perform an energy minimisation
 --------------------------------------------
 
-*Descriptions will appear here*
+The most straightforward way of minimising the energy of a
+spin configuration is to use the LLG method and the velocity
+projection (VP) solver:
+
+![GUI controls](https://imgur.com/smLr1DS.png "GUI controls")
+
+By pressing "start" or the space bar, the calculation is started.
 
 
 How to perform an LLG dynamics calculation
 --------------------------------------------
 
-*Descriptions will appear here*
+To perform a dynamics simulation, use for example the Depondt
+solver. In this case, parameters such as temperature or spin
+current will have an effect and the passed time has physical
+meaning:
+
+![GUI info panel](https://imgur.com/glOmCeO.png "GUI info panel")
 
 
 How to perform a GNEB calculation
 --------------------------------------------
 
-*Descriptions will appear here*
+Select the GNEB method and the VP solver.
+
+In order to perform a geodesic nudged elastic band (GNEB)
+calculation, you need to first create a chain of spin systems,
+in this context called "images".
+You can do this by pressing `ctrl+c` to "copy" the current image
+and then `ctrl+rightarrow` multiple times to insert the copy
+into the chain until the desired number of images is reached.
+The GUI will show the length of the chain:
+
+![GUI controls](https://imgur.com/y3VhqBj.png "GUI controls")
+
+You can use the buttons or the right and left arrow keys to
+switch between images.
 
-A data plot is available to visualise your chain of spin systems. It can also
-show interpolated energies if you run a GNEB calculation.
+A data plot is available to visualise your chain of spin systems.
+The interpolated energies become available when you run a GNEB
+calculation.
 
 ![GNEB Transition Plot](http://i.imgur.com/TQpOcuh.png "Minimum energy path")
 

diff --git a/ui-cpp/README.md b/ui-cpp/README.md
@@ -1,7 +1,7 @@
 UI - CPP
 ------------
 
-By setting the CMake switch `UI_CXX_USE_QT`, you can choose wether to use a regular
+By setting the CMake switch `SPIRIT_UI_CXX_USE_QT`, you can choose wether to use a regular
 command line interface or a powerful QT user interface.
 
 Both interfaces can be stopped with `Ctrl+C`.