diff --git a/LICENSE.txt b/LICENSE.txt index ff832609a..3bdfb2cdd 100644 --- a/LICENSE.txt +++ b/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 diff --git a/README.md b/README.md index 2e3b3916c..af12db301 100644 --- a/README.md +++ b/README.md @@ -1,238 +1,207 @@ -Spirit -======== -**Spin Simulation Framework**
-The code is released under [MIT License](../master/LICENSE.txt).
+SPIRIT +============================= +**SPIN SIMULATION FRAMEWORK**
+ +The code is released under [MIT License](LICENSE.txt).
If you intend to *present and/or publish* scientific results for which you used Spirit, -please read the [REFERENCE.md](../master/REFERENCE.md) +please read the [REFERENCE.md](docs/REFERENCE.md) -For contributions and affiliations, see [CONTRIBUTORS.md](../master/CONTRIBUTORS.md) +This is an open project and contributions and collaborations are always welcome!! +See [Contributing](#Contributing) on how to contribute or write an email to g.mueller@fz-juelich.de
+For contributions and affiliations, see [CONTRIBUTORS.md](docs/CONTRIBUTORS.md) Wiki Page: https://iffwiki.fz-juelich.de/index.php/Spirit -Please note that a version of the Spirit Web interface is hosted by the Research Centre Jülich at +Please note that a version of the *Spirit Web interface* is hosted by the Research Centre Jülich at http://juspin.de - - - -![Skyrmions](http://imgur.com/BInvmEs.jpg "Skyrmions on a 2D grid") - -Contents --------- -1. [Introduction](#Introduction) -2. [User Interfaces](#UserInterfaces) -3. [Branches](#Branches) -4. [Code Dependencies](#Dependencies) -5. [Installation Instructions](#Installation) -6. [Unit Tests](#UnitTests) -7. [Contributing](#Contributing)   - - -Introduction ----------------------------------------- - -**Platform-independent** code with optional visualization, written in C++11. -The build process is platform-independent as well, using CMake. -This code has been developed as a flexible solution to various use-cases, including: -* **Spin Dynamics simulations** obeying the - [Landau-Lifschitz-Gilbert equation](https://en.wikipedia.org/wiki/Landau%E2%80%93Lifshitz%E2%80%93Gilbert_equation "Titel, der beim Überfahren mit der Maus angezeigt wird") -* Direct **Energy minimisation** of a spin system -* **Minimum Energy Path calculations** for transitions between different - spin configurations, using the GNEB method -* Energy Landscape **Saddlepoint searches** using the MMF method -More details may be found in the [Wiki](https://iffwiki.fz-juelich.de/index.php/Spirit "Click me..."). + ----------------------------------------- +![Skyrmions](http://imgur.com/JgPj8t5.jpg "Skyrmions on a 2D grid")   - - -User Interfaces ---------------------------------------------- -The overall code is separated into several folders, representing the 'core' physics code -and the various user interfaces you may build. -* **core**: Core Physics code -* **ui-console**: C++ command line interface -* **ui-python**: Python command line interface -* **ui-qt**: OpenGL visualisation inside QT -* **ui-web**: WebGL visualisation inside a website - -Due to this modularisation and the fact that the core library exposes an API written -in C, arbitrary user interfaces may be placed on top of the core physics code. -The command-line versions may be useful to be run on clusters or for repetitive tasks, -whereas the GUI-versions are useful to provide live visualisations of the simulations -to the user. -Note that the current web interface is primarily meant for educational purposes and has -less features. Since the core needs to be transpiled to JavaScript and is executed -user-side, it is necessarily slower than the regular code. - ----------------------------------------- -  -Branches --------------------------------- -We aim to adhere to the "git flow" branching model: http://nvie.com/posts/a-successful-git-branching-model/ +Contents +-------- ->Release (`master` branch) versions are tagged `x.x.x`, starting at `1.0.0` +1. [Introduction](#Introduction) +2. [Getting started with the Desktop User Interface](#Desktop) +3. [Getting started with the Python Package](#Python) +4. [Contributing](#Contributing) -Download the latest stable version from https://github.com/spirit-code/spirit/releases +--------------------------------------------- -The develop branch contains the latest updates, but is generally less consistently tested than the releases. -----------------------------------------   -Code Dependencies ---------------------------------------------- - -The core library does not have dependencies, except for C++11. -Due to the modular CMake Project structure, when building only a specific library or UI, -one does thus not need any libraries on which other projects may depend. -Most *external* dependencies are included in the thirdparty folder. -The following lists all *external* dependencies which are not included: - -### Core -* 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. +Introduction +--------------------------------------------- -### VFRendering -* OpenGL Drivers >= 3.3 -* CMake >= 3.5 +#### A modern framework for magnetism science on clusters, desktops & laptops and even your Phone -Necessary OpenGL drivers *should* be available through the regular drivers for any -remotely modern graphics card. +**Spirit** is a **platform-independent** framework for spin dynamics, written in C++11. +It combines the traditional cluster work, using using the command-line, with modern +visualisation capabilites in order to maximize scientists' productivity. -### UI-QT -* QT >= 5.7 +> "It is unworthy of excellent men to lose hours like slaves in +> the labour of calculation which could safely be relegated to +> anyone else if machines were used." +> - Gottfried Wilhelm Leibniz -Building and installing QT manually can be a big pain, but usually their installers or packages should work fine. -This UI needs at least version 5.7 due to the usage of the **QTCharts** library. +*Our goal is to build such machines*. The core library of the *Spirit* framework provides an +**easy to use API**, which can be used from almost any programming language, +and includes ready-to-use python bindings. +A **powerful desktop user interface** is available, providing real-time visualisation and +control of parameters. +
More details may be found in the [Wiki](https://iffwiki.fz-juelich.de/index.php/Spirit "Click me..."). -**Note** that you must install QTCharts (it may be deactivated by default). +### *Physics Features* +* Atomistic Spin Lattice Heisenberg Model including also DMI and dipole-dipole +* **Spin Dynamics simulations** obeying the + [Landau-Lifschitz-Gilbert equation](https://en.wikipedia.org/wiki/Landau%E2%80%93Lifshitz%E2%80%93Gilbert_equation "Titel, der beim Überfahren mit der Maus angezeigt wird") +* Direct **Energy minimisation** with different optimizers +* **Minimum Energy Path calculations** for transitions between different + spin configurations, using the GNEB method -### UI-Python -* Python +### *Highlights of the Framework* +* Cross-platform: everything can be built and run on Linux, OSX and Windows +* Standalone core library with C API which can be used from almost any programming language +* **Python package** making complex simulation workflows easy +* Desktop UI with powerful, live **3D visualisations** and direct control of most system parameters +* Modular backends including **GPU parallelisation** -We have not tested how far backwards the Python UI is compatible. -It should not matter if you use Python 2 or 3. +### *Documentation* +* [Framework build instructions](docs/BUILD.md) +* [Core build instructions](core/docs/BUILD.md) +* [Core API Reference](core/docs/API.md) -### UI-Web -* emscripten +--------------------------------------------- -In order to build the core.js JavaScript library, you need emscripten. -Note we have not tested this process on different machines. -----------------------------------------   -Installation Instructions ------------------------------------------------------ - ->The following assumes you are in the Spirit root directory. +Getting started with the Desktop Interface +--------------------------------------------- -Please be aware that our CMake scripts are written for our use cases and -you may need to adapt some paths and options in the Root CMakeLists.txt, specifically: +See [BUILD.md](docs/BUILD.md) on how to install the desktop user interface. -The important **Options** you can set under *### Build Flags ###* are: -* BUILD_UI_WEB - build the web interface instead of others -* BUILD_UI_PYTHON - build the python library -* BUILD_UI_JULIA - build the julia library -* BUILD_UI_CXX - build the C++ interfaces (console or QT) instead of others -* UI_CXX_USE_QT - build qt user interface instead of console version +![Desktop UI with Isosurfaces in a thin layer](http://imgur.com/QUcN4aG.jpg "Isosurfaces in a thin layer") -Core options: -* CORE_BUILD_TEST - build unit tests for the core library -* CORE_USE_CUDA - use CUDA to speed up numerically intensive parts of the core -* CORE_SCALAR_TYPE - should be e.g. `double` or `float`. Sets the C++ type for scalar variables, arrays etc. +The user interface provides a powerful OpenGL visualisation window. +It provides functionality to +- control calculations +- locally insert configurations (homogeneous, skyrmions, spin spiral, ... ) +- generate homogeneous transition paths +- change parameters of the Hamiltonian +- change parameters of the Method and Optimizer +- configure the visualization (arrows, isosurfaces, lighting, ...) -Further Options include: -* OSX_BUNDLE_APP - not yet functional -* PRINT_SOURCES - print all source files (for debugging) -* USER_PATHS_IFF - use default IFF (FZJ) cluster paths +*Unfortunately, distribution of binaries for the Desktop UI is not possible due +to the restrictive license on QT-Charts.* -The **Paths** you can set under *### User Paths ###* (just uncomment the corresponding line) are: -* USER_COMPILER_C and USER_COMPILER_CXX for the compiler name you wish to use -* USER_PATH_COMPILER for the directory your compiler is located in -* USER_PATH_QT for the path to your CMake installation -Otherwise, the developers' defaults will be used or CMake will try to use it's defaults. - -**Note** that in order to build with QT as a dependency on Windows, you need to have `path/to/qt/qtbase/bin` in your PATH variable. +--------------------------------------------- -Clear the build directory using - ./clean.sh - or - rm -rf build && mkdir build - -### Generate Build Files -`./cmake.sh` lets cmake generate makefiles for your system inside a 'build' folder. -Simply call - ./cmake.sh - or - cd build && cmake .. && cd .. +  -Passing `-debug` to the script will cause it to create a debug configuration, -meaning that you will be able to properly debug the entire application. -When on pure **Windows** (no MSys etc), you can simply use the git bash to do this. -When using MSys etc., CMake will create corresponding MSys makefiles. + -### Building the Projects -`./make.sh` executes the build and linking of the executable. Simply call +Getting started with the Python Package +--------------------------------------------- - ./make.sh - or - cd build && make && cd .. +To install the *Spirit python package*, either [build and install from source](docs/BUILD.md) +or simply use + + pip install spirit + +With this package you have access to powerful Python APIs to run and control +dynamics simulations or optimizations. +This is especially useful for work on clusters, where you can now script your +workflow, never having to re-compile when testing, debugging or adding features. + +The most simple example of a **spin dynamics simulation** would be +``` python + from spirit import state, simulation + with state.State("input/input.cfg") as p_state: + simulation.PlayPause(p_state, "LLG", "SIB") +``` +Where `"SIB"` denotes the semi-implicit method B and the starting configuration +will be random. + +To add some meaningful content, we can change the **initial configuration** by +inserting a Skyrmion into a homogeneous background: +``` python + def skyrmion_on_homogeneous(p_state): + from spirit import configuration + configuration.PlusZ(p_state) + configuration.Skyrmion(p_state, 5.0, phase=-90.0) +``` + +If we want to calculate a **minimum energy path** for a transition, we need to generate +a sensible initial guess for the path and use the **GNEB method**. Let us consider +the collapse of a skyrmion to the homogeneous state: +``` python + from spirit import state, chain, configuration, transition, simulation + + ### Copy the system a few times + chain.Image_to_Clipboard(p_state) + for number in range(1,7): + chain.Insert_Image_After(p_state) + noi = chain.Get_NOI(p_state) + + ### First image is homogeneous with a Skyrmion in the center + configuration.PlusZ(p_state, idx_image=0) + configuration.Skyrmion(p_state, 5.0, phase=-90.0, idx_image=0) + simulation.PlayPause(p_state, "LLG", "VP", idx_image=0) + ### Last image is homogeneous + configuration.PlusZ(p_state, idx_image=noi-1) + simulation.PlayPause(p_state, "LLG", "VP", idx_image=noi-1) + + ### Create transition of images between first and last + transition.Homogeneous(p_state, 0, noi-1) + + ### GNEB calculation + simulation.PlayPause(p_state, "GNEB", "VP") +``` +where `"VP"` denotes a direct minimization with the velocity projection algorithm. + +You may also use *Spirit* order to **extract quantitative data**, such as the energy. +``` python + def evaluate(p_state): + from spirit import system, quantities + M = quantities.Get_Magnetization(p_state) + E = system.Get_Energy(p_state) + return M, E +``` + +Obviously you may easily create significantly more complex workflows and use Python +to e.g. pre- or post-process data or to distribute your work on a cluster and much more! -If building any C++ UI, the executable `spirit` should now be in the root folder +--------------------------------------------- -When on pure **Windows** (no MSys etc), instead of using `make` or `./make.sh`, -you need to open the generated Solution in Visual Studio and build it there. -The execution folder should be 'build' and file paths at runtime will be -relative to this folder. -----------------------------------------   - - -Unit 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. The `ctest.sh` script may be used to run all tests. -Alternatively, 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. ----------------------------------------- - -  - Contributing ------------------------------------------ +--------------------------------------------- Contributions are always welcome! @@ -243,7 +212,7 @@ Contributions are always welcome! 5. Push to the branch: `git push origin feature-something` 6. Submit a pull request -Please keep your pull requests feature-specific and limit yourself +Please keep your pull requests *feature-specific* and limit yourself to one feature per feature branch. Remember to pull updates from this repository before opening a new feature branch. @@ -254,3 +223,14 @@ do not hesitate to contact us. There is no strict coding guideline, but please try to match your code style to the code you edited or to the style in the respective module. + + +### *Branches* + +We aim to adhere to the "git flow" branching model: http://nvie.com/posts/a-successful-git-branching-model/ + +> Release versions (`master` branch) are tagged `major.minor.patch`, starting at `1.0.0` + +Download the latest stable version from https://github.com/spirit-code/spirit/releases + +The develop branch contains the latest updates, but is generally less consistently tested than the releases. \ No newline at end of file diff --git a/core/README.md b/core/README.md index 110636fc0..d7d3623a6 100644 --- a/core/README.md +++ b/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 \ No newline at end of file +### Documentation +* [Build instructions](docs/BUILD.md) +* [API Reference](docs/API.md) \ No newline at end of file diff --git a/core/docs/API.md b/core/docs/API.md new file mode 100644 index 000000000..5e89944fd --- /dev/null +++ b/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.* diff --git a/core/docs/BUILD.md b/core/docs/BUILD.md new file mode 100644 index 000000000..0b0cb5ad5 --- /dev/null +++ b/core/docs/BUILD.md @@ -0,0 +1,132 @@ +BUILD THE SPIRIT LIBRARY +======================== + + +C/C++ Library +--------------------------------------------- + +| 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 + +--------------------------------------------- + + + +  + + + +Unit Tests +--------------------------------------------- + +| 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 | + +--------------------------------------------- + + + +  + + + +Python Package +--------------------------------------------- + +| 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-.whl + +--------------------------------------------- + + + +  + + + +Julia Package +--------------------------------------------- + +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 | \ No newline at end of file diff --git a/core/python/README.md b/core/python/README.md index 06d61008e..fa92e505b 100644 --- a/core/python/README.md +++ b/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") \ No newline at end of file +For API documentations for this package, see +https://github.com/spirit-code/spirit/core/docs/API.md \ No newline at end of file diff --git a/docs/BUILD.md b/docs/BUILD.md new file mode 100644 index 000000000..bd253fda0 --- /dev/null +++ b/docs/BUILD.md @@ -0,0 +1,164 @@ +Building Spirit's Framework Components +====================================== + +The **Spirit** framework is designed to run across different platforms +and so the build process is set up with `CMake`, which will generate +the appropriate build scripts for each platform. + +Please be aware that our CMake scripts are written for our use cases and +**you may need to adapt some paths and options in the Root CMakeLists.txt**. + + + +  + + + +Contents +-------- + +1. [General Build Process](#Build) +2. [Core Library](#Core) +4. [Desktop User Interface](#QT) + +--------------------------------------------- + + + +  + + + +General Build Process +--------------------------------------------- + +>The following assumes you are in the Spirit root directory. + +### Options +There are some important **Options** you may need to consider. +You can find them under *### Build Flags ###* in the **Root [CMakeLists.txt](../CMakeLists.txt)**. +Otherwise, the developers' defaults will be used. + +Some **Paths** you can set under *### User Paths ###* (just uncomment the corresponding line) are: +| CMake Variable | Use | +| :------------------------------------: | :-: | +| USER_COMPILER_C
USER_COMPILER_CXX | Name of the compiler you wish to use | +| USER_PATH_COMPILER | Directory your compiler is located in | +| USER_PATHS_IFF | use the default IFF (FZJ) cluster paths | + +### Clean +Clear the build directory using + + ./clean.sh + or + rm -rf build && mkdir build + +Further helper scripts for clean-up are `clean_log.sh`, `clean_output.sh`, + +### Generate Build Files +`./cmake.sh` lets cmake generate makefiles for your system inside a 'build' folder. +Simply call + + ./cmake.sh + or + cd build && cmake .. && cd .. + +Passing `-debug` to the script will cause it to create a debug configuration, +meaning that you will be able to properly debug the entire application. + +On **Windows** (no MSys) you can simply use the git bash to do this or use the CMake GUI. +When using MSys etc., CMake will create corresponding MSys makefiles. + +### Building the Projects +To execute the build and linking of the executable, simply call + + ./make.sh -jN + or + cd build && make -jN && cd .. + +where `-jN` is optional, with `N` the number of parallel build processes you want to create. + +On **Windows** (no MSys), CMake will by default have generated a Visual Studio Solution. +Open the generated Solution in the Visual Studio IDE and build it there. + +### Running the Unit Tests +We use `CMake`s `CTest` for unit testing. You can run + + ctest.sh + or + 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. + + +### Installing Components + +This is not yet supported! however, you can already run + + ./install.sh + or + cd build && make install && cd .. + +Which on OSX should build a .app bundle. + +--------------------------------------------- + + + +  + + + +Core Library +--------------------------------------------- + +For detailed build instructions concerning the standalone core library +or how to include it in your own project, see [core/docs/BUILD.md](../core/docs/BUILD.md). +* Shared and static library +* Python bindings +* Julia bindings +* Transpiling to JavaScript +* Unit Tests + +The **Root [CMakeLists.txt](../CMakeLists.txt)** has a few options you can set: +| 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!) | + +--------------------------------------------- + + + +  + + + +Desktop User Interface +--------------------------------------------- + +| Dependencies | Versions | +| :------------: | -------- | +| OpenGL Drivers | >= 3.3 | +| CMake | >= 3.5 | +| QT | 5.7 including QT-Charts | + +**Note** that in order to build with QT as a dependency on Windows, you may need to add +`path/to/qt/qtbase/bin` to your PATH variable. + +Necessary OpenGL drivers *should* be available through the regular drivers for any +remotely modern graphics card. + +| CMake Options | Use | +| :------------------: | :-: | +| SPIRIT_BUILD_FOR_CXX | Build the C++ interfaces (console or QT) instead of others | +| UI_CXX_USE_QT | Build qt user interface instead of console version | +| USER_PATH_QT | The path to your CMake installation | +| OSX_BUNDLE_APP | On OSX, create .app bundle (not yet fully functional) | \ No newline at end of file diff --git a/CONTRIBUTORS.md b/docs/CONTRIBUTORS.md similarity index 100% rename from CONTRIBUTORS.md rename to docs/CONTRIBUTORS.md diff --git a/REFERENCE.md b/docs/REFERENCE.md similarity index 90% rename from REFERENCE.md rename to docs/REFERENCE.md index 70cb983ac..c5786f371 100644 --- a/REFERENCE.md +++ b/docs/REFERENCE.md @@ -1,19 +1,19 @@ # Reference -**Spirit** is a scientific project. +The **Spirit** framework is a scientific project. If you present and/or publish scientific results that used Spirit, you should add a reference. - -### Papers -Currently, the publication should you reference is:
-(TBA) - You may use e.g. the following TeX code: \bibitem{spirit} {Spirit spin simulation framework} (see spirit-code.github.io) + +### Papers +Currently, the publication should you reference is:
+(TBA) + **Earlier papers**: (none yet)