Fidimag is an open-source scientific code for the study of magnetic materials at the nano- or micro-scale using either atomistic or finite difference micromagnetic simulations, which are based on solving the Landau-Lifshitz-Gilbert equation. In addition, it implements simple procedures for calculating energy barriers in the magnetisation through variants of the nudged elastic band method. This computer software has been developed with the aim of creating a simple code structure that can be readily installed, tested, and extended. An agile development approach was adopted, with a strong emphasis on automated builds and tests, and reproducibility of results. The main code and interface to specify simulations are written in Python, which allows simple and readable simulation and analysis configuration scripts. Computationally costly calculations are written in C and exposed to the Python interface as Cython extensions. Docker containers are shipped for a convenient setup experience. The code is freely available on GitHub and includes documentation and examples in the form of Jupyter notebooks.

The simulation of magnetic materials falls into several paradigms, depending on the length scales, materials and phenomena of interest. For many materials, the spin of atoms can be assumed to be localised around the atom, and a classical approximation can be made in which the atomic spin is treated as a point dipole – this is the classical Heisenberg model. Because the atomic crystal lattice of the material is considered, this discrete spin model is commonly referred to as atomistic [

Fidimag is a software library which allows researchers to model magnetic materials using both the classical Heisenberg and micromagnetic models. Users of the software provide the magnetic parameters of the material under study, the system geometry, and a set of initial conditions. The simulation can occur under different kind of dynamics, with Fidimag implementing the Landau-Lifshitz-Gilbert (LLG), the stochastic LLG (SLLG), and several spin-transfer torque variations of the LLG equation. From this initial setup, the user can then choose to evolve the system either through time, and hence study the magnetisation dynamics, or to “relax” the system to find its metastable energy states. In addition, the software implements the nudged elastic band method to find minimum energy paths and the size of energy barriers between different configuration states.

Fidimag has been used to obtain the results in several scientific publications [

The Micromagnetic Modeling Activity Group μmag has defined a number of Standard Problems for the validation and comparison of micromagnetic simulation software [

For illustration, we show here the solution of Standard Problem #4. In this example, the magnetisation reversal dynamics of a bar of Permalloy with the dimensions 500 × 125 × 3 nm are computed. First, a relaxed ‘s-state’ is obtained in the absence of an applied magnetic field. It is plotted in Figure

Snapshots of the unit magnetisation. The plots were created with the code in the function

Solution to the standard problem #4. The simulation defined in the function

The evolution of the spatially averaged magnetisation is shown in Figure

The components of the average magnetisation over time as computed with Fidimag and by OOMMF.

At the atomic level, the magnetic effects in magnetic materials originate from two angular momentum terms from electrons: their orbital motion around the nucleus and, mainly, from a quantum property of electrons called spin._{i} = μ_{i}_{i} representing a magnetic moment (a magnetic dipole) μ_{i}_{i}. This idea originates from Heisenberg’s model Hamiltonian to describe magnetic interactions [

An atom is at the scale of a few Angstrom, thus in large systems, which are at the nano-scale, it would be necessary to describe the system using thousands of spins, which is computationally expensive. Therefore, it is possible to approximate the material as a continuum, where the field from discrete magnetic moments turns into a continuum field called magnetisation that depends on the space coordinates _{i} → _{s} = _{s}, which is defined as a magnetic moment per unit volume, _{s} = μ/Δ_{i}.

To describe a magnetic system, we firstly specify its geometry. If we simulate this system using a discrete spin model, we have to generate a lattice of magnetic moments with a specific arrangement of atoms (according to the crystal symmetry) such that they describe this geometry. In the case of micromagnetics we use the finite differences numerical technique, thus the sample is discretised into cuboids and each one of them represents a volume with uniform magnetisation inside that volume.

Magnetic phenomena emerge from the interactions between magnetic moments and their interaction with external and internal magnetic fields, the later including dipolar interactions and anisotropic interactions, among others. These interactions depend on the material and specify the total energy of the system. In general, the spins perform a precessional motion following directions set by the magnetic interaction. The dynamics of the magnetic moments is given by the Landau-Lifshitz-Gilbert (LLG) equation [

at zero temperature, where _{eff} is an effective field that contains the sum of every magnetic interaction present in the system, γ is the Gilbert gyromagnetic ratio constant, which sets the time scale of the spin motion, and 0 ≤ α_{G} ≤ 1 is the Gilbert damping. The first term in equation 1 describes a precessional motion of spins around the effective field and the second term is a dissipative term that make spins follow the effective field direction.

In micromagnetics this equation has the same structure:

Fidimag can solve the non-linear differential equations 1 and 2, depending on the specified theoretical model. Accordingly, it is necessary to specify an initial magnetic configuration for the spin directions, and the magnetic interactions involved in the system. Currently, Fidimag has the following interactions implemented in the code,

The underlying equations that were used to implement these interactions can be found in Ref. [

One method for finding energy minima in the system’s energy landscape, which is implemented in the code, is to evolve the system with the LLG equation, since the spins will precess until a stable configuration is attained,

Dynamical effects such as the generation of spin waves, ferromagnetic resonance, domain wall motion, among other multiple magnetism related phenomena, are also given by the evolution of spins with the LLG equation. Variations of this equation are obtained when applying electric currents or temperature, which can also be specified in the code. Fidimag supports the inclusion of stochastic terms and spin-polarised currents in the equation of motion. The terms and their corresponding equations are shown in Ref. [

At zero temperature the length of the magnetic moments and the magnetisation vector is fixed. This condition must be specified in the equation of motion of spins explained in the last section, which sets a constraint to the spin length. Multiple magnetic phenomena can be explained at a zero-temperature formalism thus the majority of Fidimag’s equations are implemented in this regime.

Although this constraint is implicit in the LLG equation, numerically the spin length varies when integrated. To address this problem, a correction term is added to the right hand side of equations 1 and 2 in Fidimag (equation 4 in Ref. [

and similar in the micromagnetic model, by setting

Finding the lowest energy cost to drive a magnetic system from one equilibrium state towards another, also known as energy barrier, has become a relevant problem for the analysis of the stability of magnetic structures. An energy barrier is then associated to the transition path, between two states, that requires the least energy. This is important, for example, for the potential application of a magnetic structure in a technological device since an energy barrier can be used to estimate the lifetime of the structure against energy fluctuations from excitations such as thermal noise, present at finite temperatures. The nudged elastic band method (NEBM) is a technique for the calculation of minimum energy paths, and hence energy barriers. It was first used in chemistry to study molecular transitions [

A detailed review of the method can be found in Ref. [

Fidimag provides both micromagnetic and atomistic simulation capabilities and is the only software that allows switching between the two modelling paradigms. The most notable micromagnetic code is OOMMF, which had its alpha release in 1998. OOOMMF is written in C++ and Tcl/Tk. Fidimag is mostly implemented in the Python programming language, with performance critical parts realised in C and linked in via Cython. The code base consists of roughly 5000 lines of Python code and 4000 lines of C code and cython extensions.

This library model of execution, where Fidimag is imported into the namespace of a Python program empowers the user to deal with the complexity of the batch processing of simulations in a more easily tested and reproducible way compared to ad-hoc shell commands and specialised batch modes in software with graphical user interfaces [

The standard problem #3 especially examplifies how naturally Fidimag allows higher order logic thanks to these choices. In it, two possible magnetic configurations in cubes of increasing sizes are to be studied to determine when they are equally energetically favourable. In Listing

Solution to the standard problem #3. The code that computes the energy difference between the two possible magnetic configurations has been abstracted into the function

Finding the cube size of equal energies called

A similar approach had been used in Nmag, where it has proven to be successful [

Vampire is a performant atomistic code that defines its own declarative syntax [

Best practices recommend using version control for any kind of computational endeavours [

The source code is split into three major sections – ‘atomistic’, ‘micro’ and ‘common’ which contain code specifically for classical Heisenberg simulations, micromagnetic simulations, and for both respectively, as can be seen in Figure

Architecture of Fidimag as reflected by the directory structure and Python modules. Code useful to micromagnetic and atomistic simulations was extracted into a

There are many common components which can be shared between both types of simulation. The primary data in both atomistic and micromagnetics is stored in vector fields, and the mechanisms for passing this data through the simulation are kept in a common base ‘Sim’ class. This allows, for example, the saving of the magnetisation progressive steps in the simulations to be handled identically for both types of simulation. Fidimag comes with visualisation and data saving utilities out of the box.

As we mentioned earlier, we define a magnetic system by setting its geometry. How the geometry is approximated depends on the chosen model.

Within the continuum approximation, Fidimag uses finite differences which means dividing the sample into a mesh of cubes, as shown in Figure

Cuboid mesh and hexagonal lattice labelled according to the index of the sites.

For the calculation of the demagnetising field, Fidimag uses a fast-Fourier-transform method that requires a uniform grid, hence for complex geometries, such as curved samples, Fidimag still defines a cuboid mesh but boundaries or specific mesh sites without material are approximated by setting the magnetisation as zero, _{s} = 0. Thus to obtain a better approximation it is necessary to define a large number of cuboids and decrease the distance between their centres. In order to set a null magnetisation, the user can specify a Python function that has as an input the position vector and that returns _{s} according to the sample geometry [

In Listing

Definition of a 2 nm wide sphere geometry using micromagnetics.

In the case of discrete spin simulations, atoms order in a lattice according to different crystallographic arrangements. The most simple ordering is the

Using as a base the class structure of the meshes currently implemented in Fidimag, it is possible to define and implement other crystal lattices such as body-centered-cubic or face-centered-cubic arrangements.

Besides scalars, most of the physical quantities involved in micromagnetic computations are fields and vector fields. In Fidimag, they are represented with numpy arrays [

Testing small chunks of code and preferably isolated pieces of the system is unit testing. In Fidimag, most of the unit tests compute and check the physical quantities involved in succesfully running a simulation. Besides giving helpful feedback during development, the unit tests were a factor in increasing confidence to edit, enhance or refactor the code, resulting in the improved decoupling and maintainability of it. The coverage of Fidimag’s code base with unit tests is monitored using codecov [

Functional testing then examines a slice of the system. For example, one of the test cases covering the saving of scalar fields on hexagonal meshes to a VTK file in Fidimag is shown in Listing

A unit test in which a scalar field

Finally, system tests use Fidimag as a black box and compare simulation output to known good values. These values are obtained from problems that have analytical solutions like the macrospin or domain walls. As we saw earlier, the μmag standard problems are another good source of testing data. So are other finite difference codes, like the aforementioned OOMMF.

Fidimag is also tested against the output of earlier versions of itself by storing some simulation results in the repository. This is a form of regression testing, and since no external software or potentially long-running simulations are involved the fastest way to check if a changeset has affected the computational parts in a tangible way. The design choices discussed in the introduction and the focus on testing continue to provide tangible benefits to the collaborators working on the software, as well as the software itself, as shown above. They also increase the confidence in Fidimag›s results since unlike users, automated tests don›t distinguish between new and old code and test potentially seldom-used parts of the software just as often as the commonly used functions.

For maximum value, the tests need to be run often and ideally without manual intervention. This is why a test cycle is triggered on the continuous integration platform Travis CI [

To quickly check if Fidimag is installed and working on a machine, a user can launch an interactive Python shell and execute

GNU/Linux, Mac OS X and on any platform supported by Docker, like Azure and AWS.

Python version 3, C, cython.

E.g. memory, disk space, processor, input devices, output devices.

E.g. libraries, frameworks, incl. minimum version compatibility.

Numpy ≥ 1.10

SciPy ≥ 1.0.0

SUNDIALS ≥ 2.7.0

FFTW ≥ 3.3.4

Fidimag builds using the OpenMP versions of these libraries for multiprocessing purposes.

Please list anyone who helped to create the software (who may also not be an author of this paper), including their roles and affiliations.

Bisotti, Marc-Antonio

Wang, Weiwei

Cortés-Ortuño, David

Fangohr, Hans

Pepper, Ryan

Kluyver, Thomas

Vousden, Mark

Beg, Marijan

(e.g. institutional repository, general repository) (required please see instructions on journal website for depositing archive copy of software in a suitable repository)

(e.g. SourceForge, GitHub etc.) (required)

(if appropriate)

Language of repository, software and supporting files.

English.

The simulations are written in Python and use Fidimag as a library to be imported. Fidimag has been used to gather results for a number of scientific publications [

For this reason when we mention spins we strictly refer to the total angular momentum or magnetic moments.

Numbers obtained with cloc version 1.60.

The authors have no competing interests to declare.