Improved documentation.

- Restructured Readme
- Added docs folders for framework and core
- Improved build instructions

LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 Gideon Müller and Daniel Schürhoff
+Copyright (c) 2015 Gideon Müller and collaborators
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

core/README.md

@@ -1,30 +1,16 @@
-Core
----------
+Spirit
+=============
+
+This is the core library of the **Spirit** framework.
 
-This is the core library of the Spirit framework.
 It is meant to provide useful and easy API functions to enable productive work
-with atomistic dynamics simulations and optimizations.
+with Atomistic Dynamics Simulations and Optimizations.
 The current implementation is specific to atomistic spin models, but it may
 easily be generalised.
 
-### C interface
-
-The API is exposed as a C interface and revolves around a simulation `State`
-and may also be used from other languages, such as Python, Julia or even
-JavaScript (see *ui-web*).
-
-The `State` contains all the necessary data and keeps track of running
-Optimizers. A new state can be created with `State_Setup`, where you can pass
-a config file specifying your initial system parameters. If you do not pass a
-config file, the implemented defaults are used. *Note that you currently
-cannot change the geometry of the systems in your state once they are
-initialized.*
+The library is written in C++ but has been wrapped in Python for easier install and use.
+Other bindings should be easy to create.
 
-The interface exposes functions for:
-* Control of simulations
-* Manipulation of parameters
-* Extracting information
-* Generating spin configurations and transitions
-* Logging messages
-* Reading spin configurations
-* Saving datafiles
+### Documentation
+* [Build instructions](docs/BUILD.md)
+* [API Reference](docs/API.md)

core/docs/API.md

@@ -0,0 +1,52 @@
+SPIRIT API
+====================
+
+This will list the available API functions of the Spirit library.
+
+The API is exposed as a C interface and may thus also be used from other
+languages, such as Python, Julia or even JavaScript (see *ui-web*).
+The API revolves around a simulation `State` which contains all the necessary
+data and keeps track of running Optimizers.
+
+The API exposes functions for:
+* Control of simulations
+* Manipulation of parameters
+* Extracting information
+* Generating spin configurations and transitions
+* Logging messages
+* Reading spin configurations
+* Saving datafiles
+
+
+
+C API
+----------
+A new state can be created with `State_Setup`, where you can pass
+a config file specifying your initial system parameters
+
+```C
+    #import "Spirit/State.h"
+
+    State * p_state = State_Setup("");
+```
+
+If you do not pass a config file, the implemented defaults are used. *Note that you currently
+cannot change the geometry of the systems in your state once they are
+initialized.*
+
+
+
+Python API
+----------
+
+A new `State` can be created with 
+
+```python
+    from spirit import state
+    with state.State("") as p_state:
+        pass
+```
+
+where you can pass a config file specifying your initial system parameters.
+If you do not pass a config file, the implemented defaults are used.
+*Note that you currently cannot change the geometry of the systems in your state once they are initialized.*

core/docs/BUILD.md

@@ -0,0 +1,132 @@
+BUILD THE SPIRIT LIBRARY
+========================
+
+
+C/C++ Library <a name="CPP"></a>
+---------------------------------------------
+
+| Dependencies | Versions |
+| :----------: | -------- |
+| gcc          | >= 4.8.1 (C++11 stdlib) or any modern compiler |
+| CMake        | >= 2.8.12 |
+
+This is pretty much a standalone library and should be easy to implement into existing
+projects in which CMake is already used.
+It can be built as shared or static and API headers are located in
+`path/to/Spirit/core/include/Spirit`
+
+|  CMake Options          | Use |
+| :---------------------: | :-: |
+| SPIRIT_USE_CUDA         | Use CUDA to speed up numerically intensive parts of the core |
+| SPIRIT_SCALAR_TYPE      | Should be e.g. `double` or `float`. Sets the C++ type for scalar variables, arrays etc. |
+| SPIRIT_BUILD_TEST       | Build unit tests for the core library |
+| SPIRIT_BUILD_FOR_CXX    | Build the static library for C++ applications |
+| SPIRIT_BUILD_FOR_JULIA  | Build the shared library for Julia |
+| SPIRIT_BUILD_FOR_PYTHON | Build the shared library for Python |
+| SPIRIT_BUILD_FOR_JS     | Build the JavaScript library (uses a different toolchain!) |
+
+
+Note that the CMake Options for the core library are also set in the root CMakeLists.txt.
+
+### Integrating into other CMake Projects
+This is currently untested, but you should be able to use *Spirit* either via
+`ExternalProject` or `AddSubdirectory`.
+You should thus be able to simply copy the `core` directory as `Spirit` into
+the thirdparty folder of your Project and use it as is done commonly.
+
+Note that setting `qhull_LIBS` and `qhull_INCLUDE_DIRS` if qhull is present on
+your disk removes the need for Spirit to clone and build it separately.
+
+A set of CMake variables is pushed to the parent scope by the core CMakeLists.
+These include:
+- SPIRIT_LIBRARIES
+- SPIRIT_LIBRARIES_STATIC
+- SPIRIT_INCLUDE_DIRS
+
+---------------------------------------------
+
+
+
+&nbsp;
+
+
+
+Unit Tests <a name="Tests"></a>
+---------------------------------------------
+
+| Dependencies | Versions |
+| :----------: | -------- |
+| gcc          | >= 4.8.1 (C++11 stdlib) or any modern compiler |
+| CMake        | >= 2.8.12 |
+| Python       | >= 2.7 or >= 3.5 (for the python tests) |
+
+The core library includes a set of unit tests in order to make sure certain conditions are
+fulfilled by the librarys functions.
+We use `CMake`s `CTest` for unit testing.
+You can run
+
+	cd build && ctest --output-on-failure && cd ..
+
+or execute any of the test executables manually.
+To execute the tests from the Visual Studio IDE, simply rebuild the `RUN_TESTS` project.
+
+|  CMake Options   | Use |
+| :--------------: | :-: |
+| CORE_BUILD_TEST  | Build unit tests for the core library |
+| BUILD_UI_PYTHON  | Python tests are only built if this is ON |
+
+---------------------------------------------
+
+
+
+&nbsp;
+
+
+
+Python Package <a name="Python"></a>
+---------------------------------------------
+
+| Dependencies | Versions |
+| :----------: | -------- |
+| Python       | >= 2.7 or >= 3.5  |
+
+|  CMake Options   | Use |
+| :--------------: | :-: |
+| BUILD_UI_PYTHON  | Build the shared library for python |
+| CORE_BUILD_TEST  | Will build python unit tests if the shared lib for python is built |
+
+You may use the python package simply by adding a `path/to/Spirit/core/python` to your
+PYTHONPATH.
+
+To build a proper python package including binary wheel, you need to
+build the shared library for Python and then execute
+
+	cd path/to/Spirit/core/python
+    python setup.py sdist bdist_wheel
+
+The resulting package can then be installed with e.g.
+
+	pip install -e /path/to/package/dist/spirit-<tags>.whl
+
+---------------------------------------------
+
+
+
+&nbsp;
+
+
+
+Julia Package <a name="Julia"></a>
+---------------------------------------------
+
+These bindings are currently completely experimental.
+However, it seems it would be easy to create Julia bindings analogous
+to the [Python Bindings](#Python).
+
+| Dependencies | Versions |
+| :----------: | -------- |
+| None         | -        |
+
+|  CMake Options   | Use |
+| :--------------: | :-: |
+| BUILD_UI_JULIA  | Build the shared library for julia |

core/python/README.md

@@ -1,43 +1,7 @@
 Spirit Python Library
----------------------
+=====================
 
-This library is meant to provide useful and easy API functions to enable productive work
-with atomistic dynamics simulations and optimizations.
-The current implementation is specific to atomistic spin models, but it may
-easily be generalised.
+See https://spirit-code.github.io
 
-The library is written in C++ but has been wrapped in Python for easier install and use.
-
-
-### API functions
-
-The API revolves around a simulation `State` which contains all the necessary
-data and keeps track of running Optimizers.
-A new `State` can be created with 
-
-    from Spirit import state
-    with state.State(cfgfile) as p_state:
-        pass
-
-where you can pass a config file specifying your initial system parameters.
-If you do not pass a config file, the implemented defaults are used.
-*Note that you currently cannot change the geometry of the systems in your state once they are initialized.*
-
-The interface exposes functions for:
-* Control of simulations
-* Manipulation of parameters
-* Extracting information
-* Generating spin configurations and transitions
-* Logging messages
-* Reading spin configurations
-* Saving datafiles
-
-
-### Running a Simulation
-
-An easy example is a Landau-Lifshitz-Gilbert (LLG) dynamics simulation
-using the Semi-implicit method B (SIB):
-
-    from spirit import state
-    with state.State(cfgfile) as p_state:
-        simulation.PlayPause(p_state, "LLG", "SIB")
+For API documentations for this package, see
+https://github.com/spirit-code/spirit/core/docs/API.md