spirit-code / spirit

Atomistic Spin Simulation Framework

SPIRIT

SPIN SIMULATION FRAMEWORK

 

Core Library:

Branch	Build Status	Python Package Coverage	Core Library Coverage
master:
develop:

Python package:

 

The code is released under MIT License.
If you intend to present and/or publish scientific results or visualisations for which you used Spirit, please cite G. P. Müller et al., Phys. Rev. B 99, 224414 (2019) and read the docs/REFERENCE.md.

This is an open project and contributions and collaborations are always welcome!! See docs/CONTRIBUTING.md on how to contribute or write an email to [email protected]
For contributions and affiliations, see docs/CONTRIBUTORS.md.

Please note that a version of the Spirit Web interface is hosted by the Research Centre Jülich at http://juspin.de

 

 

Contents

1. Introduction
2. Getting started with the Desktop User Interface
3. Getting started with the Python Package

---

 

Introduction

A modern framework for magnetism science on clusters, desktops & laptops and even your Phone

Spirit is a platform-independent framework for spin dynamics, written in C++14. It combines the traditional cluster work, using using the command-line, with modern visualisation capabilites in order to maximize scientists' productivity.

"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

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.

Physics Features

• Atomistic Spin Lattice Heisenberg Model including also DMI and dipole-dipole
• Spin Dynamics simulations obeying the Landau-Lifschitz-Gilbert equation
• Direct Energy minimisation with different solvers
• Minimum Energy Path calculations for transitions between different spin configurations, using the GNEB method

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 parallelisation on GPU (CUDA) and CPU (OpenMP)

Documentation

More details may be found at spirit-docs.readthedocs.io or in the Reference section including

• Unix/OSX build instructions
• Windows build instructions
• Input File Reference

There is also a Wiki, hosted by the Research Centre Jülich.

---

 

Getting started with the Desktop Interface

See the build instructions for Unix/OSX or Windows on how to get the desktop user interface.

The user interface provides a powerful OpenGL visualisation window using the VFRendering library. 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 Solver
• Configure the Visualization (arrows, isosurfaces, lighting, ...)

See the UI-QT Reference for the key bindings of the various features.

Unfortunately, distribution of binaries for the Desktop UI is not possible due to the restrictive license on QT-Charts.

---

 

Getting started with the Python Package

To install the Spirit python package, either build and install from source (Unix/OSX, Windows) 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

from spirit import state, simulation
with state.State("input/input.cfg") as p_state:
    simulation.start(p_state, simulation.METHOD_LLG, simulation.SOLVER_SIB)

Where SOLVER_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:

def skyrmion_on_homogeneous(p_state):
    from spirit import configuration
    configuration.plus_z(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:

from spirit import state, chain, configuration, transition, simulation

### Copy the system and set chain length
chain.image_to_clipboard(p_state)
noi = 7
chain.set_length(p_state, noi)

### First image is homogeneous with a Skyrmion in the center
configuration.plus_z(p_state, idx_image=0)
configuration.skyrmion(p_state, 5.0, phase=-90.0, idx_image=0)
simulation.start(p_state, simulation.METHOD_LLG, simulation.SOLVER_VP, idx_image=0)
### Last image is homogeneous
configuration.plus_z(p_state, idx_image=noi-1)
simulation.start(p_state, simulation.METHOD_LLG, simulation.SOLVER_VP, idx_image=noi-1)

### Create transition of images between first and last
transition.homogeneous(p_state, 0, noi-1)

### GNEB calculation
simulation.start(p_state, simulation.METHOD_GNEB, simulation.SOLVER_VP)

where SOLVER_VP denotes a direct minimization with the velocity projection algorithm.

You may also use Spirit order to extract quantitative data, such as the energy.

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!

spirit's Issues

QHull is built twice

This is due to the need for two build targets, but this can be circumvented somehow.

UI-Web needs Method and Optimizer selection tab

Optimizers:

• SIB
• Heun
• VP

UI-QT: Add more Infos to StatusBar

• Energy
• max Torque
• total z magnetization

Effective Field is not correctly saved in Spin Systems

We need to decide wether to save the effective field or the force.

The Method::Post_Iteration function is where the data should be copied to the spin system. The Method should have a temporary data member for this.

UI-QT needs a fullscreen visualisation mode

An almost Fullscreen visualisation would suffice, but menu bar, dockwidgets and other controls should be hidden

GL: coordinate cross z-axis in HSV map and white background

The axis is hidden when the background and the axis are both white.
Maybe there should be a small (e.g. circular) background behind the coordinate cross in this case? or maybe thicker gray lines placed behind the colored lines?

I/O file format specifications

Should improve support for different spin file formats (CSV, table, with and without spin position). Better Energy file output would also be nice

GL Error on Linux (Arch inside VBox)

This needs to be verified for other Linux Systems, since OSX and Windows are not affected.

When pressing one of the configuration Buttons, the renderers produce OpenGL errors in their respective updateSpins functions (e.g. SphereSpinRenderer l. 75).

It is unclear why this happens.
The initialisation is fine, simulations can be run as well.
Only the changing of the current state and subsequent update of the renderers crashes the program. It might thus be related to the update call coming from SettingsWidget.

Zooming into origin quickly may invert the camera

Numerical imprecision results in a flip of the camera if one quickly zooms into the origin

Optimizer should display the initial force before starting iterations

Before, the initial force that was displayed was sometimes nonsense.
Currently, it is not displayed at all.

WebGL needs touch input

Core: MMF Method is not working

This needs intensive investigation...

All spin systems have the same RNG seed

Create option to auto-generate seed by DateTime? Otherwise multiple images which were initialized with Random exhibit the same configuration.

We should think about what should happen when a system is copied.

UI-QT: make settings persistent

Save Settings and load them at startup:

• controlWidget settings
• general settings
  • mode
  • miniview
  • coordinatecross
• background color
• camera
• arrow size and lod

There is no way to calculate total Magnetization

This function should probably be placed into Utilities

UI-Web needs Method selection tab

This should be implemented after #14

Methods:

• LLG
• GNEB

VFRendering: Coordinate cross in orthographic projection

The orthographic projection of the coordinate cross seems to change with the proportions of the window (in contrast to the other renderers). Two examples for non-quadratic windows:

GNEB Method: add "stationary" image option

This would be analogous to switching to climbing/falling, but it would mean the image is not moved at all, acting as a new boundary inside the chain.

For these options a new enum class { normal, climbing, falling, stationary} should be created.

Hamiltonians should be rewritten with class structure in mind

The Hamiltonians do not properly exhibit the following structure:

• Energy Contributions per spin should be calculated per spin and saved in a scalarfield
• Energy Contributions should be calculated by contracting the per_spin arrays
• Energy should be calculated as the sum of contributions

The last point should be done in the base class.
By using scalarfields, the functions can be nicely ported to CUDA.

UI-Python: most getters for arrays don't work

The getters do not propagate the changes out of the function, as vec3(vector) creates a new instance, copying the values of vector.
Functions have to be rewritten such that the values are copied into the original array or list after the shared library function has been called.

Output fails if folder is not existent

Maybe this is not so doable currently.

The C++17 Filesystem TS might be a possibility...

API: write setters for Hamiltonian_Anisotropic

These are needed for the Anisotropic Hamiltonian to be useable in a dynamic scenario.
Example: changing Jij in the Web UI (since the long-term goal is to remove the Isotropic Hamiltonian).

DD neighbours/pairs are always recalculated

It would make sense for the code to save the list of neighbours or pairs for the dipole-dipole interaction. In the case of pairs, it should of course only save the pairs of one basis cell.
A keyword should be added indicating a file from which to read the neighbours/pairs on startup.

Output File with used Parameters

It would be quite nice to have an output file which contains ALL the necessary parameters which were important to do the calculations:

• input parameters from the .cfg
• interaction parameters
• spin dynamic relevant stuff (e.g. algorithm or whatever you can choose) ...

With this you are one the one hand able to check whether you choose the good parameters (which can be confusing as the parameters are only read once at the start of the program) and on the other hand it's easier to reproduce data.

The file should somehow have the same time stamp as the corresponding log. It would of course be nice (but not mandatory), if this file would have a format which can be used to start directly calculations based on it ;)

Core: write CUDA backend for SIB Optimizer

This is the only Optimizer which needs extra backend functions.

Input Log: Pairs and Quadruplets (Hamiltonian_Anisotropic)

See also #2

UI-QT: surface visualisation needs improvement

Since #4 is done, the behaviour of the surface visualisation needs improvement:

• The surface is a regular s_z=0 isosurface on startup (function needs to be set before first draw)
• The function for the isovalue now needs to be improved such that the surface can be moved more gradually and up to the bounding box.

The following screenshot shows the latter problem

UI-Web needs buttons to switch between images of a chain

Method: implement history for relevant quantities

Useful quantities for convergence plots:

• max_torque
• E_tot (LLG)
• M_z (LLG)

They should be implemented in the Method base class and they should be updated every log_steps

String formatting should be homogenized throughout the core

Examples of Classes or Namespaces which (I think) format strings separate from each-other:

• Optimizer
• Method
• IO_Configwriter
• Logging
• IO_Filedump

There is no way to calculate the topological charge

This would be useful, especially for skyrmions

Hamiltonian: finite differences is likely incorrect

Hamiltonian base class has FD gradient and Hessian.
The Hessian is most likely incorrect, the gradient might be too.

Default input should be updated and UIs should use "input.txt" by default

The default input needs to be checked in terms of convergence parameters etc.
The UIs should use input.txt in order to make it easier for people to use.

Surface Visualisation for 3D Systems

We need a proper surface mode for 3D systems. Features should include:

• contour surfaces (z slider)
• planar cut of the system
• block cut of the system

Inefficient pairs in Hamiltonian_Anisotropic

Hamiltonian_Anisotropic uses std::vector to store two ints!

Moving the camera position with right mouse click

Since alt+mouse1 may be a system keybind which interferes with the program, it would make sense to be able to move the camera using just mouse2, analogous to camera rotation with mouse1.

Logging: catch exceptions in API

This should be done such that severe exceptions are logged and the code is ended as gracefully as possible.

Visualise magnitudes in the vector field (e.g. eff. field)

In the case that we want to visualise e.g. the effective field or forces, we need the vectors to either scale their size or e.g. their transparancy (probably not so well possible) with the vector magnitude.

UI-Web needs camera control buttons

Energy file output should not always be per spin

Energy per spin becomes imprecise when the number of spins grows large. In the file output it should thus be total energy (not per spin).
Maybe build a switch which one to use in console print?

• per spin
• per unit cell
• total

Check which data should really be vectorfield for CUDA case

It needs to be checked wether the vectorfields etc. are immediately allocated on device, or only if they are passed into a kernel...
If all datasets use vectorfield etc. instead of std::vector, this might become a memory problem on the GPU...

Core: Build_Spins is inefficient

For very large systems this becomes a big issue.
It is unclear how to optimize the first part.

The second part (verification that no two spins are on the same position can be easily made by checking the basis and checking for overlaps when translating the basis in any combination of the translation vectors.

Hamiltonian: use e.g. std::map or std::pair for energy contributions

Ideas are std::map or std::pair or std::touple.

This way, the difderent contributions can be labeled with strings, only adding those contributions which are nonzero. The file or console output could be nicer this way, as only the relevant contributions would be outpt

CMake: should implement OSX App bundle

Being able to create a relocatable .App for OSX would be a very useful feature.
If we would attach the resulting .App's to the GH releases, we would need to check license conditions first.

UI-QT: NOI indicator is not updated when images are inserted

Big memory leak in triangulation

Currently, due to alignment issues on Windows with std::vector<tetrahedron_t>, it is copied into an array and the pointer to that array (instead of a pointer to the first element of the vector) is passed out through the API.

Because this array is not deleted, the memory is leaked.

It might make sense to use something different than the tetrahedron_t struct...

Core: write CUDA backend for Hamiltonian_Anisotropic

The Anisotropic is the first Hamiltonian which should receive a CUDA backend.

Invalid Method when starting simulation in "fullscreen" mode

It appears that when the corresponding box is hidden, the contents is not read correctly and the simulation can thus not be started correctly.

This is an issue on the master branch: cd3e452 i.e. v1.1.0

Isotropic Hamiltonian needs DMI type switch

The Hamiltonian should contain a switch between Neel and Bloch type DMI vector orientation

Desktop GUI needs double-/range-sliders

For z-range sliders, double sliders would be nicer than two coupled sliders.

Here is an example implementation: http://stackoverflow.com/a/26025796