Table Of ContentNmag micromagnetic simulation tool – software
engineering lessons learned
Hans Fangohr Maximilian Albert Matteo Franchin
UniversityofSouthampton UniversityofSouthampton Cambridge
SO171BJSouthampton SO171BJSouthampton UnitedKingdom
UnitedKingdom UnitedKingdom [email protected]
[email protected] [email protected]
6
1
0 ABSTRACT der the hood, to solve time-dependent partial differential
2
equations using finite element discretizations. It has been
We review design and development decisions and their im-
b in use for nearly a decade, and with this review, we try to
pact for the open source code Nmag from a software en-
e shareexperiencetohelp improvefuturegenerations of soft-
gineering in computational science point of view. We sum-
F ware engineering projects in computationalscience.
mariselessonslearnedandrecommendationsforfuturecom-
8 putationalscienceprojects. Keylessonsincludethatencap- We start by summarizing key lessons and recommenda-
2 sulating the simulation functionality in a library of a gen- tions on this page below, with pointers to more detailed
eral purpose language, here Python, provides great flexi- discussion in themain part of thepaper (Sect 2to Sect 4).
] bility in using the software. The choice of Python for the
E There are two points of view to consider in the develop-
top-leveluserinterfacewasverywellreceivedbyusersfrom
S mentofatoolforcomputationalscientists. Ontheonehand,
the science and engineering community. The from-source
s. installation in which required external libraries and depen- timheperonvde-utsheerisrwscaienntcteh.eOsonfttwhaeroetthoerbehaeansdy,ttoheusdeevinelooprderesrtoof
c dencies are compiled from a tarball was remarkably robust.
thesoftware care about additional aspects, such as extensi-
[ In places, the code is a lot more ambitious than necessary,
bility and maintainability. We divideour recommendations
whichintroducesunnecessarycomplexityandreducesmain-
2 according to these twodifferent points of view:
tainability. Tests distributed with the package are useful,
v
although more unit tests and continuous integration would
2
9 have been desirable. The detailed documentation, together Recommendations primarily affecting end- Sect.
3 withatutorialfortheusageofthesystem,wasperceivedas users
7 one of its main strengthsby thecommunity. Embedding simulation into existing programming 4.1
0 language provides unrivaledflexibility
. CCSConcepts
1 Python-based top-levels of the tool allow users to 4.2
0 •Software and its engineering → Software creation modify it to suit theirneeds
6 andmanagement;•Computingmethodologies→Mod-
1 eling and simulation; Continuous models; •Applied com- Python is a popular language that is perceived to 4.2
v: puting → Computer-aided design; Physics; beeasy to learn by(non-computer)scientists
i Documentation and tutorials are important 4.11
X
Keywords
r
a Nmag,ComputationalScienceSoftwareEngineering,Python,
Finite Elements Recommendations primarily affecting de- Sect.
velopers
1. SUMMARY Version control tool useis essential 4.9
The Nmag software was developed from 2005 to early Systemtestsareessential,unittestsareveryuseful 4.10
2012, and first released in 2007 as open source code. Nmag
Continuousintegration is very useful 4.12
has a Python user interface, and uses Objective Caml code
and established High Performance Computing libraries un- Limitthesupportedoranticipatedfunctionalityto 4.8
minimize complexity and enhancemaintainability
Permissiontomakedigitalorhardcopiesofallorpartofthisworkforpersonalor Codegenerationbasedonuserprovidedequations 4.6
classroomuseisgrantedwithoutfeeprovidedthatcopiesarenotmadeordistributed
is up-front investment but widens applicability of
forprofitorcommercialadvantageandthatcopiesbearthisnoticeandthefullcita-
tiononthefirstpage. Copyrightsforcomponentsofthisworkownedbyothersthan tool
ACMmustbehonored.Abstractingwithcreditispermitted.Tocopyotherwise,orre-
Choice of unconventional programming language 4.2
publish,topostonserversortoredistributetolists,requirespriorspecificpermission
and/[email protected]. can limit the number of scientists joining the
SE4Science’16,May162016,Austin,TX,USA project as developers
(cid:13)c 2016ACM.ISBN978-1-4503-4167-7/16/05...$15.00 OCaml not quiteas fast as C/C++/Fortran 4.4
DOI:http://dx.doi.org/10.1145/2897676.2897677
Figure 1: The OOMMF graphical user interface for
problem definitions
2. INTRODUCTION
Nmagisamicromagneticsimulationpackage. Micromag-
netics is a continuum theory of magnetization at the nano-
andmicrometerscale. Themagnetizationisacontinuous3d Figure 2: Nmag architecture overview
vector field defined throughout a ferromagnetic body. The
dynamicsof thisvectorfield aredeterminedbyanequation
of motion, which depends on solving a non-linear partial The aim of the Nmag package was, among other things,
integro-differential equation. Using spatial discretization, toprovidea finiteelement based discretization approachto
this partial differential equation (PDE) can be solved nu- complement the OOMMF tool. Simultaneously, and with-
merically. Nmag uses a combination of finite element and out being aware of each others efforts, the finite element
boundary element methods [16, Section 2.2] to solve the Magparcodewasdeveloped,andlaterreleasedasopensource
integro-PDE in every time step. Within this finite element [19].
model,themagnetizationisrepresentedas3d-vectordegrees In this report, we focus on software engineering aspects
of freedom at every finite element node. For the time inte- of the Nmag tool, including the user interface, the choice
gration, the degrees of freedom at all nodes are treated as of languages and tools, and the open source model. We
a system of coupled ordinary differential equations, in line summarizetheNmagprojectinsection3,beforeaddressing
withtherelatedopensourcesoftwareMagpar[19]andother thelessons learned in section 4.
tools that are not freely available.
Nmag is summarized in a short paper [12]. More tech- 3. NMAGPROJECTSUMMARY
nical detail, in particular on the underlying multi-physics
Architecture: Figure 2 summarizes the Nmag architec-
finite element library nsim, is given in a manuscript avail-
ture: the blue box at the top represents the (Python) code
able on the arXiv [11]. Some aspects of the parallel exe-
thattheend-userassemblestodefinethesimulationcompu-
cution model have been published [13]. The project home
tation; this includes material parameters, the file name of
page [1] contains the code as a tar-file. For reference, the
the finite element mesh to define the geometry, the physi-
repository from which the tarball is built, is available as a
cal process that should be simulated etc. The instructions
Mercurial repository on Bitbucket [2]. A number of PhD
are written as a Python script that makes use of the nmag
students have contributed to the software, and their the-
Python library (top green box),which in turncomposes its
ses are an additional useful source of information, covering
functionality from the (Python) nsim multi-physics library.
an overview of the capabilities of the code [14, chapter 5],
ThePythonNsimmulti-physicslibraryisaninterfacetothe
long-range demagnetization field calculation, boundary el-
functionalityprovidedthroughtheimplementation(bottom
ements and matrix compression [16], macro-geometry peri-
green box) in OCaml [4]. We make use of existing high
odic boundaryconditions and mesh generation [7].
performance computing libraries such as PETSC for sparse
and dense matrix calculation, PARMETIS for partitioning
Computational micromagnetics became feasible and ac- the mesh across multiple MPI processes, and the CVODE
cessiblewiththepublicdomainreleaseoftheOOMMFSoft- time integration tools that come with the SUNDIALS tool
warebytheNationalInstituteofStandardsandTechnology suite. Thecode is parallelized with MPI.
(NIST) in the late 90s [8]. The OOMMF software uses a The code implements a dependency engine for physical
finite difference discretization (with different strengths and fields [11, Section 4.4]. This allows lazy evaluation to only
weaknessesthanthefiniteelementdiscretizationbutoutside compute entities when they are truly required, and to min-
the scope of this paper), which is based on C++ code with imizethecomputationoffieldsthatdependon eachothers.
aTcl andTk interface. A simulation runcan beconfigured Periodic boundary conditions are difficult in micromag-
through a graphical user interface (see figure 1 for an ex- neticsimulationsduetothelongrangenatureofthemagne-
ample),orthroughsettingparametersinaconfigurationfile tostatic interactions. A new computational model has been
which uses Tcl syntax. developed and implemented (the ’macro geometry’ [10]),
import nmag
from nmag import SI
# Create simulation object
sim = nmag.Simulation()
# Define magnetic material
Py = nmag.MagMaterial(
name = ’Py’, Ms = SI(1e6, ’A/m’),
exchange_coupling = SI(13.0e-12, ’J/m’))
# Load mesh
sim.load_mesh(’sphere1.nmesh.h5’,
[(’sphere’, Py)],
unit_length = SI(1e-9, ’m’))
# Set initial magnetisation
sim.set_m([1, 0, 0])
# Set external field
Figure 3: Nmag citations from Web of Science up
sim.set_H_ext([0, 0, 0], SI(’A/m’))
to January 2016.
# Save and display data in a variety of ways
sim.save_data(fields=’all’)
which has subsequently been used by the Nmag successor # Sample demagnetisation field through sphere
codeFinmag[5],andothermicromagnetictoolssuchasthe for i in range(-10, 11):
x = i * 1e-9 # x-position in metres
GPU-based package Mumax3[20].
H_demag = sim.probe_subfield_siv(
Time line: TheplanningforNmagstartedaround2003, ’H_demag’, [x, 0, 0])
funding was secured in 2005, and the work started soon af- print("x =", x, ": H_demag = ", H_demag)
terwards. The first version was publicly released in 2007.
Thetoolwasactivelymaintainedandfurtherdevelopedun-
Figure 4: Nmag end-user script example.
til January 2012, when key developers moved on and no
further funding was available. Since then, the software has
been hosted ‘as is’.
Otherparts,inparticularthePython-levelmicromagnetic
Uptake: As of February 2016, the official Nmag publi-
interface nmag were developed in a more agile style, with
cation [12] has been cited 103 times in publications (Web
multiple iterations of development, use of automated tests
of Science, Thomson Reuters) and 182 times on Google
(section4.10),wherebothrefactoringandadditionalfeature
Scholar. More than 150 users are known by name (from
implementation was carried out in subsequentiterations.
the mailing list, or off-line queries), and the web site is fre-
quented from academic and industry domain names, with
45000 visits since 2006. Figure 3 shows the breakdown of 4. LESSONS LEARNED
citations per year. Development and maintenance stopped
early 2012, which (so far) seems to not have affected the 4.1 Userinterface through Pythonlibrary
usefulness of thetool for research.
A key design decision was to embed the functionality of
Nmag team: The principal funding for the project was
foraresearchfellowfor2.5years. Theteammanagedtofind thesimulation intoa general purpose language, in this case
3 PhD student projects that supported the lead developer Python (see also [11, section 5.11.1]).
as part of their work [7, 14, 16], and in the later phases Figure 4 shows an Nmag simulation script, which is a
there were smaller contributions from others. Later (2009- Python script that imports and uses thenmag library.
2012), a research fellow from another project contributed In comparison to definition of simulation configurations
significantly to the project. The background of the team through configuration text files or graphical user interfaces
was in physics and mathematics. None of the participants (see for example Figure 1), this approach has a number of
had any formal training in software engineering, which is a advantages: (i)noparserneedstobewritten–Pythonisthe
common situation in the developmentof research software. parser, (ii) the user has complete freedom in using Python
Communitysupport: Communitysupportinvolvesthe constructs to combine the simulation commands provided
bythenmaglibraryasneededfortheparticularapplication,
following tools andstrategies: theNmagwebpagehoststhe
code, installation instructions, the manual [1], a link to the (iii) data pre- and post-processing, and calculations that
mailinglistarchives[3]andtheRedmineWiki. TheUniver- takeplaceduringthesimulationcanmakeuseofthePython
sity of Southamptonis hostingthe mailing list, and Google ecosystemofavailablescientificlibraries, (iv)theconfigura-
Groups is used to archive all communication in that mail- tion of the simulation can make use of Python functions
inglist. ARedmineserverisusedsimplytohostaWikithat to provide, for example, initial magnetization vector field
configurations,thatshowacomplicatedspatialdependence.
userscanedit(https://nmag.soton.ac.uk/community/wiki/nmag).
Software engineering process: Parts of the software (Seealso section 5.11.2 in [11]).
were written in an effectively plan-driven approach, broken
4.2 Choiceofprogramming languages
into separate requirement analysis, design, implementation
and testing phases. In particular the Nsim multi-physics Figure5showssomestatisticsregardingtheprogramming
core was realized as one large piece of work by the lead languages / tools and respective lines of code in the Nmag
developer without significant subsequentchange. project.
Language files comment lines code lines Inmoredetail: theusersstartsan executablecalled nsim
OCaml 174 15111 53445 compiled from OCaml code. This executable initializes the
Python 588 17718 49286 simulation engine, and then calls an embedded Python in-
C 49 2548 12375 terpreter, which processes the user’s simulation commands
BourneShell 47 1232 9184 (which are typically given through a file mysim.py to the
make 138 391 2831 nsim executable, i.e. the command line call would be nsim
C/C++ Header 14 410 820 mysim.py). Ifnofiletoprocessisgiven,aPythoninterpreter
SUM: 1010 37410 127941 is displayed in which Python commands can be entered in-
teractively,and thenmag library is accessible.
Figure 5: Output of cloc (v1.65) run on Nmag An alternative setup would be that the user starts the
source code, tests, and documentation files. ’usual’ Python interpreter, and that a nmag package can be
imported, which carries out the housekeeping work, initial-
ization of MPI and and execution of required OCaml code
Nmag uses Python as the language for the user to de- when imported.
fine how the micromagnetic simulation should be carried With hindsight, we suggest that the alternative arrange-
out. It should be noted that the micromagnetic capabili- mentwouldhavebeenmuchpreferableforanumberofrea-
ties as well as the testing infrastructure and system tests sons: (i) nsim activates a Python interpreter (in which the
areimplementedatthePythonlevel,whiletheOCamlcode nmag library is accessible), so it will seem more logical to
providesagenericmulti-physicssimulationenvironmentand the user if that command is python and not nsim. (ii) The
containssignificantpartsofthemulti-physicsfiniteelement Pythoninterpretercomingthroughnsimisingeneraldiffer-
code. TheOCamlmulti-physicsengineiscapableofsolving ent from the system Python interpreter (and with the cur-
problems in areas outside micromagnetism. rentinstall,seesection4.12,thisPythoninterpreterisbuilt
Pythonwasagoodchoiceforthehighleveluser-interface, from source and installed locally); and third party Python
and internals of the package: it is a user-friendly language modules (such as numpy, scipy, matplotlib) may end up
[9] that has gained substantially in popularity in computa- havingto beinstalled separately for both interpreters.
tional science and elsewhere since 2005; resulting in addi-
tional benefits from the critical mass of users. Anecdotal 4.4 OCamlperformance
evidence and the increase of Python-based simulation tools
TheOCaml-basedmulti-physicsenginesubdividesthecom-
and libraries support our point that Python is a high pro-
putationintotwophases: initialisationandtimeintegration.
ductivity language in computational science. In micromag-
Inthefirstphase,asetofsparseanddensematricesarepre-
netism, packages developed after Nmag have followed the
computed and stored in memory. These matrices capture
model of providinga Python library to offer their function-
thevariousphysicalinteractionsthatgovernthebehaviorof
ality [6,5].
the simulated system and are mainly computed by OCaml
For Objective Caml (OCaml) as the work horse of the
code. In the second phase, the time integration is carried
multi-physics engine, the situation is less clear. There are
out, using thepre-computed matrices. These computations
technical reasons why OCaml is a good choice, including
are mainly done using the PETSC library. Micromagnetic
its C interoperability interface, its (interactive) interpreter
simulationsofrealmaterialsanddevicesrequirefinemeshes
and its native code compiler. OCaml also offers automatic
corresponding to pre-computed matrices of size of tens of
memory management, expressive power and functional ca-
Gigabytes and matrix assemble timesof theorderof hours.
pabilities (see section 5.13 in [11]).
It is therefore important to make the OCaml initialisation
In hindsight, we have identified a disadvantage of a so-
phasefastandefficient. InvestigationsoftheOCamlengine
cial engineering nature: OCaml is not a wide-spread lan-
codeperformancerevealedsomelimitations ofthelanguage
guage (certainly not outside computer science and mathe-
anditscompilerwhenusedinourcontext,whicheventually
matics), and there are virtually no users of the Nmag soft-
ledustorewritepartsofthematrixinitializationcodeinC.
ware that have OCaml experience. Furthermore, OCaml
First we comment on array efficiency. OCaml native ar-
is very rarely taught and due to its (powerful but some-
rays are unidimensional. A rank-2 tensor (i.e. a matrix)
what non-mainstream) functional style, it presents a steep
canstillberepresentedasanarrayofarraysoffloatswhich,
learning curve to the typical Nmag user, who tends to be
however, is not memory efficient: the floats are not stored
a researcher in material science, engineering, physics, biol-
in contiguous areas of memory, requiring extra memory for
ogy,geographyandmedicine(butgenerallynotacomputer
storing pointers and thus additional indirections during ar-
scientist). For an open source project, it is important that
ray accesses. Moreover, the sub-arrays are not guaranteed
thecodeisaccessiblebytheusercommunitytoattractnew
tohavethesamelengths. Thismakesmulti-dimensionalar-
contributors.
rays difficult toanalyze and optimize for a compiler. While
ComparisonofexecutionperformanceofcompiledOCaml
theBigarray modulein OCamlprovidesmulti-dimensional
code with C/C++ code have shown that the OCaml code
arrayswhicharestoredcontiguouslyinmemoryandthusal-
can be noticeably slower than the C code. We address this
lowtoovercomesomeoftheseproblems,accessestoOCaml
point in more detail in section 4.4.
big-arraysarenotinlined,leadingtopoorperformance[15].
Second, we have found that OCaml has limited support
4.3 Pythoninterpreter activatedfromOCaml
for some compiler optimisations that are particularly use-
For technical reasons and the capabilities of the existing ful in numerical code, such as bounds-checkingelimination,
PyCaml interface [21] that connects OCaml and Python, loop unrolling, and vectorisation. These optimization tech-
theNmagsetupissuchthatthePythoninterpreteriscalled niques are now common in mainstream languages and are
from within an OCaml executable. performed by freely available compilers such as gcc and
clang, which of course receive a vastly greater investment ods, and the combined C-code is written to disk, compiled,
and contribution from theprivatesoftware industry. and dynamically linked. The auto-generated code will au-
We provide electronic supplementary material [15] with tomatically translate the user provided indices to the right
samplecodethatunderpinstheresultsreportedinthissec- memorylocations,whichisnon-trivialformulti-physicssim-
tion,andadditionalinterpretation. Theexamplesshowthat ulations where multiple fieldsare definedat every node.
rewriting an OCaml loop in C/C++ can give speedups of (ii)Theusercanalsoprovidealgebraicexpressionswhich
a factor 4. This is significant because performance critical represent the required operation, which are automatically
numerical code often consist of simple for-loops. translated into C code. We provide an example to demon-
In summary, the lack of native multi-dimensional array strate this. In the micromagnetic problem, there is a mag-
support is a problem for scientific code, and a better com- netizationvectorfieldm(r)thatdefinesa3dvectoratevery
pilerwouldbringOCamlclosertoCintermsofperformance. point r in 3d space. In this example, we look at the map-
pingof themagnetization m ontoitstimederivative dm as
4.5 Symbolic derivation of PDE calculations dt
is necessary to compute the equation of motion (1) for this
atrun-time magnetization vectorfunction m(r):
In finite elements, a mathematical problem in form of a dm
PDE is solved in a given number of spatial dimensions n; dt =c1m×H+c2m×(m×H) (1)
these are typically n = 3, or n = 1, n = 2, corresponding
We note that H is obtained as a function of m by solving
to 3d space as we know it, and reduced models where a 1d
certain partial differential equations[16, Section 2.2].
or 2d space is sufficient. On these n-dimensional domains,
Wecan rewrite (1) usingindex notation as:
we operate with scalars, vectors or tensors, which can have
tfauhnneeicrxtiadomnimspelaenn)s,diot(nhtaeaslkietiynhgakvo.enlFtyhineciaorlnloytwi,nntuhopeuorselyGinsaolmaerivkaailnroieretdlyeemroepfn.btsasaiss ddmti = j,k "c1ǫijkmjHk+ p,q c2ǫijkmj(ǫkpqmpHq)# (2)
X X
Traditionally, the right equation for a particular mathe-
For this formulation, nsim provides a small domain spe-
matical operator isderived with pen and paperfor particu-
cific language. We show how equation (2) is represented as
lar values of the dimensions of space n, the dimensionality
a string in this domain specific language:
ofthedegreeoffreedomkandbasisfunctionorderp. Once
theequationhasbeenderived,itishard-codedasanimple- dmdt = """%range i:3, j:3, k:3, p:3, q:3
dmdt(i) <- c1 * eps(i, j, k) * m(j) * H(k)
mentation for this specific case. This code is then used to
+ c2 * eps(i, j, k) * m(j)
populate the finiteelement matrices. In the micromagnetic
* eps(k, p, q) * m(p) * H(q)"""
context,theMagpar package[19] is such an example.
Nmag’s approach is different: here, the relevant analytic Wehavefoundtheinterface(ii)usefultoquicklyandflex-
operations,whichincludedifferentiationandintegration,are iblyextendtheequationofmotion. TheabilitytospecifyC
carriedoutsymbolically(withintheNsimOCamlcodebase) codedirectlythroughmethod(i)allowstosidestepthensim
to generate specialized instructions to compute the matrix framework where functionality is required that was not an-
entriesfortheparticularoperator,dimensionality,basisfunc- ticipated initially. By using C code (rather than Python
tion order etc. that the user requires. The nsim code sup- code,say)goodperformanceisachieved,inparticularwhen
portsarbitrarybasisfunctionordersp,dimensionalityofthe loops overall degrees of freedom are involved. A very simi-
degree of freedom k and and arbitrary dimensionality n of
larmechanismtomethod(i)isprovidedinthemulti-physics
thedomain.
finiteelementlibraryFEniCS[17]throughtheinstantmod-
Thisapproachprovidesmuchgreaterflexibilitytochange
ule, which can be used to initialize fields with arbitrary C
the equations in the model (an important consideration in
expressions. An approach similar to (ii) is used in FEniCS
thecontextofexploratoryresearch),orthenumericalmodel
for the non-local PDEoperators.
parameters such as the order of the basis functions. It also
FEniCS [17] started beingdeveloped at thesame time as
avoids repetitive manual analytical work, and – assuming
Nsim and is now widely used, including in the micromag-
the symbolic computations are implemented correctly – re-
netic package Magnum.fe [6] and the Nmag successor soft-
duces the chance of errors. We discuss the associated addi-
wareFinmag[5]. FEniCShascoreroutineswritteninC++
tional complexityin section 4.8.1.
and providesa Python interface.
4.6 Auto-generationofcodeforlocalfieldmap- 4.7 Parallelexecution model
pings
The parallel execution model of Nmag is that only one
The primary entities of interest in finite element simula- Pythonprocessisrunning,drivingslavesthroughMPIfrom
tions are fields, such as the magnetization vector field, the within theOCaml code [13]. This allows end-usersto write
temperature scalar field, a displacement vector field, etc. truly sequential Python code and to completely ignore the
Nmagusesauto-generationofcodeatruntimetoallowthe parallel execution of the micromagnetic equations. This is
usertocomputetailoredexpressionsthatmapfromonefield different from the FEniCS parallel model [17], where also
to another field (details in [11, section 5.11.4]). There are the Python code executes in parallel. While the FEniCS
two possible ways of achieving this: modelrequiresmorethoughtatthePythonlevel,itallowsto
(i)TheuserprovidesCcodethatcontainsthemathemat- add computationally demanding operations to be executed
ical mapping operation that is required. At run time (as inparallelthroughPython. Forexpertusersandscalability,
theuser-providedstringisnotknowbeforethen),thisuser- theFEniCS model is preferable.
provided C-code string is embedded into a template that
4.8 Complexity originatingfrom generality
providesaccesstotherelevantfieldarraysandaccessmeth-
4.8.1 Arbitrarynumberofdimensions tionontopofthis,itmayhavebeenmoreefficienttobuilda
Asintroducedinsection4.5,infiniteelements,somemath- micromagneticprototypefirst,andusetheexperiencegath-
ematical problem is solved in a given number of spatial di- ered with this in developinga more generic framework.
mensions n; where the nsim code supports calculations in We note that as the multi-physics capabilities were not
arbitrary numberof spatial dimensions. part of the funded research program, they have not been
While there are problems defined on space that is higher developed and documented to the level of the core micro-
dimensional than 3d space in science and engineering, none magnetic functionality, and are thusnot used widely.
of that functionality has been used in the lifetime of the
4.8.4 Associatingnumberswithunits
Nmagsoftware. Thecomplexityofthecodecouldhavebeen
reduced (and maintainability and accessibility increased) if All Nmag input physical entities have to be expressed as
we had limited its functionality to spatial dimensions n of aproductofanumberandproductofpowersofdimensions
1, 2 and 3. (such as m, kg, s, A, K,mol, cd). Forexample, the Python
We note for context that the FEniCS [17] multi physics expression x = SI(100e-9, "m") describes a length of 100
library follows a similar path of using symbolic calculation nano meters. For multi-physics simulations, this provides
atruntimetoderivefiniteelementmatrixentries,andthat great advantages as the output fields emerging from user-
theFEniCSfunctionalityislimitedto3orfewerdimensions. defined operations automatically carry the right units. It
also allows to scale numbers internally (to reduce chances
4.8.2 Arbitraryhighlevellanguagesupport of overflow etc), and to use arbitrary unit systems (such as
Theoperatornotationusedin(thePython)nsimlibraryis SI, CGS, or custom). In the context of micromagnetics –
representingdifferentialoperatorsthroughastring(seesec- Nmag’s application domain – the capability met a mixed
tion 4.3.1 and example A.2 in [11]). An alternative would reception: some users find it useful, others dislike the over-
be to create classes in Python that represent mathematical head ofhavingtotypethedimensions, whentheynormally
objects and differential operators, and use operator over- use SIunits (asis enforced in theOOMMF [8] package).
loading to integratethemathematical description naturally
4.9 Versioncontrol andsource
within the Python language. The FEniCS project [17] has
followed thelatter path with their Pythoninterface [18]. DevelopmentofNmagstartedin2005andhasusedthree
The motivation behind the design decision to prefer the different version control systems through its history: start-
stringrepresentationoverthe(object-oriented)operatorrep- ingwithCVS,beforechangingtoSubversion,beforeswitch-
resentation for the differential equation was to avoid cou- ing to Mercurial in 2010. Initially, the source code was in-
pling the notation too tightly to the Python scripting lan- cluded in thetarballs containing the’source’ releases of the
guage: bysticking to strings, onecan substitutePython by project,andlatertheMercurialrepositorieshavebeenmade
another language more easily as and when required. Note available on Bitbucket [2]. There are separate repositories
thatwhenNmagwascreatedPythonwasbyfarnotasmain- for the source, the tests, the documentation, the webpage,
streaminscientificcomputingasitistoday;forexample,the the distribution, and one additional meta repository that
Python numerical library numpy was only created in 2005. provides a script to clone them all together into the right
Fromauser’spointofview,webelievethatitispreferable relative subdirectory structure. Useof version control tools
to use Python objects over strings to define the differential is essential. The distributed tools, such as Mercurial and
equations: this is more natural and allows to exploit auto- Git, are more flexiblethan CVS and Subversion.
completionandtoexplorecapabilitiesanddocumentationof
4.10 Testing
objectswhenworkinginteractivelywiththePythonprompt.
Itmayhavebeenbeneficialtoapproach thisdesign ques- There about 75 tests coming with the code, combining
tion in a more agile way by fully buying into the Python unittests(ofonlysomepartsofthecode),withafairnum-
languageandtheoverloadedoperatornotationinitiallyand ber of system tests, and a few regression tests. While un-
revisiting the decision as the project evolved. As a decade doubtedly more unit tests would have been desirable, the
has passed, we now know that there is no need to intro- availabilityoftheexistingtestsisextremelyusefulasafirst
duceanotherhighlevellanguageforNmag: Pythonisdoing indicator of a working installation, etc. Test-driven devel-
fine,and thedevelopmentof theNmag project hasstopped opment was not generally used for theproject.
anyway. Anotherpossibility would betointroduceabridge
4.11 Documentation
element that translates the object oriented equations into
stringswhenrequired,whichwouldallowcombiningthelong In addition to documentation in the source code files,
term strategy of expressing differential equations through there is the official Nmag documentation that is available
stringswiththeabilitytoofferoperatoroverloadinginPython [1] as html or pdf (183 pages). Key components include
to theuser. a tutorial-like, step-by-step introduction and walk-through
of Nmag, starting from simple and common use cases to
4.8.3 Multi-physicscapabilities
morecomplicatedandspecializedapplicationexamples(112
Nmagisbuiltonthemulti-physicslibraryNsim,andthus pages), explanation of general concepts (7 pages), a com-
themicromagneticmodel thatisavailablethroughNmagis mand reference, which is built from the Python documen-
only one of many possible types of PDE-based simulations tation strings defined in the source code (20 pages), an
thatcouldbebuiltontopof nsim. Themulti-physicscapa- overview of executable scripts including their options and
bilities wereindeeduniqueinthemicromagneticsimulation usage examples, and Nmag datafiletypes(12 pages), a list
landscape, but bringsignificant additional complexity. of 20 frequently asked questions and answers (9 pages), a
While we attempted to immediately implement a multi- mini-tutorial into micromagnetic modeling (not specific for
physicsframework,andthenbuildamicromagneticsimula- Nmag, but experience shows that new Nmag users are also
oftennewtothefield). Thedocumentationisoftencitedby simulation code based on FEniCS. Journal of
users as being very good, and useful. Magnetism and Magnetic Materials, 345:29–35, 2013.
[7] G. Bordignon. Simulations of ferromagnetic
4.12 Installation
nano-structures. PhD thesis, Universityof
Nmag depends on a large number of support libraries. Southampton,2008.
Many of these are of scientific origin and change often, in- http://eprints.soton.ac.uk/65634/.
cludingchangesintheinterface. Asaresult,theNmagcode [8] M. Donahueand D.Porter. OOMMF User’s Guide,
needs updatingto compile correctly after any such update. Version 1.0, Interagency Report NISTIR6376.
For some time, there were installation options through Technical report, National Instituteof Standardsand
a Debian package, a KNOPPIX Live Linux CD (this was Technology,Gaithersburg, MD (US),September1999.
beforevirtualmachineswerewidelyused),andfromsource. [9] H.Fangohr. A comparison of C, MATLAB, and
Later, wefocused ourenergyon providingan installation Pythonas teaching languages in engineering. In
setupthatisasindependentaspossiblefromversionchanges Computational Science-ICCS 2004, pages 1210–1217.
oflibrariesthatareinstalledthroughtheLinuxdistribution Springer,2004.
tomaximizethechancesforlongtermavailability inasitu-
[10] H.Fangohr, G. Bordignon, M. Franchin,A. Knittel,
ation without maintenanceresources.
P.A. deGroot, and T. Fischbacher. A new approach
The resulting setup compiles and installs all the required
to(quasi) periodic boundaryconditions in
1
dependencies fromsource,thenbuildsNmagbasedonthese
micromagnetics: Themacrogeometry. Journal of
supportlibraries. CompilationdoesonlyworkonLinux(al-
Applied Physics, 105(7):07D529, 2009.
though on alarge variety of distributions and releases).
[11] T. Fischbacherand H. Fangohr. Continuum
This setup has been remarkable robust, and only failed
multi-physicsmodeling with scripting languages: the
once in 4 years of no maintenanceupdates. The one failure
Nsim simulation compiler prototypefor classical field
was due to more recent gcc versions reporting commenting
theory.arXiv, abs/0907.1587, 2009.
through a double slash in C header files of the hdf5 library
http://arxiv.org/abs/0907.1587.
as illegal, which previously only triggered a warning.
[12] T. Fischbacher, M. Franchin,G. Bordignon, and
Thepricetopayforthisrobustnessisthatthecompressed
H.Fangohr. A systematic approach to multiphysics
tarballcontainingallthelibrarysourcecodeisabout91MB
extensionsof finite-element-basedmicromagnetic
in size. Once Nmag has compiled all the support libraries,
simulations: Nmag.Magnetics, IEEE Transactions on,
these take together 1.4GB of disk space storage. After re-
43(6):2896–2898, 2007.
movingtemporarybuildfiles0.5GBremain. Asthesupport
[13] T. Fischbacher, M. Franchin,G. Bordignon,
librariesaresnapshotsfromtheirsourcedistributioninearly
A.Knittel, and H.Fangohr. Parallel execution and
2012,noimprovementsorbugfixesdevelopedinthesupport
scriptability in micromagnetic simulations. Journal of
libraries will affect theNmag compilation and executables.
Applied Physics, 105(7):07D527, 2009.
It would have been useful to use continuous integration
(to runtests, build documentation andreleases) to support [14] M. Franchin.Multiphysics simulations of magnetic
more frequent releases. nanostructures. PhD thesis, University of
Southampton,2009.
Acknowledegments: Weacknowledgefinancialsupportfrom http://eprints.soton.ac.uk/161207/.
theUK’sEngineeringandPhysicalSciencesResearchCoun- [15] M. Franchin,M. Albert,and H. Fangohr.
cil (EPSRC) from grants EP/E040063/1, EP/E039944/1 https://github.com/fangohr/paper-supplement-ocaml-performance,
and Doctoral Training Centre EP/G03690X/1), from the DOI:10.5281/zenodo.45235.
European Community’s FP7 Grant Agreement no. 233552 [16] A.Knittel. Micromagnetic simulations of three
(DYNAMAG),from Horizon 2020 Research Infrastructures dimensional core-shell nanostructures. PhD thesis,
project#676541(OpenDreamKit),andfromtheUniversity
Universityof Southampton,2011.
of Southampton,all of which contributedin part to thede-
http://eprints.soton.ac.uk/333186.
velopment of the Nmagtool suiteand this review.
[17] A.Logg, K.-A.Mardal, G. N.Wells, et al. Automated
Solution of Differential Equations by the Finite
5. REFERENCES Element Method. Springer, 2012.
[1] Nmag code. http://nmag.soton.ac.uk. [18] A.Logg and G. N.Wells. DOLFIN:Automated Finite
Element Computing. ACM Transactions on
[2] Nmag codeon Bitbucket.
Mathematical Software, 37(2), 2010.
https://bitbucket.org/fangohr/nmag-meta.
[19] W.Scholz, J. Fidler, T. Schrefl,D.Suess, R.Dittrich,
[3] nmag-users mailing list archive.
H.Forster, and V. Tsiantos. Scalable Parallel
https://groups.google.com/d/forum/nmag-users.
Micromagnetic Solversfor Magnetic Nanostructures.
[4] Ocaml. http://ocaml.org.
Computational Materials Science, 28:366–383, 2003.
[5] Finmag — FEniCS-based micromagnetic simulation
[20] A.Vansteenkiste,J. Leliaert, M. Dvornik,M. Helsen,
tool. 2012–2016. University of Southampton,UK.
F. Garcia-Sanchez, and B. VanWaeyenberge. The
[6] C. Abert,L. Exl, F. Bruckner,A.Drews, and
design and verification of mumax3. AIP Advances,
D.Suess. magnum.fe: A micromagnetic finite-element
4(10), 2014.
1
atlas-3.6.0, cryptokit-1.2, gsl-1.14, ipython-0.1, lapack, mpich2- [21] A.Yerkes,T. Fischbacher, H.Fangohr, and
1.2.1p1, numarray-1.5.2, numpy-1.5.0, ocaml-3.12.0, ocamlgsl-0.6.0, B. Schwartz.
ocaml-findlib-1.2.1, ParMetis-3.1.1, Python-2.7.2.tar.bz2, petsc-lite-
https://github.com/chemoelectric/pycaml.
3.1-p5, PyVTK, qhull-2003.1, tables-2.1.2, scipy-0.7.2 py-0.9.1 ply-
3.3,sundials-2.3.0,HLib-1.3p19
