.. _Introduction: Introduction ============ |Nmag| is a flexible finite element micromagnetic simulation package with an user interface based on the Python_ programming language. If you use Nmag in your published work, please cite: * Thomas Fischbacher, Matteo Franchin, Giuliano Bordignon, and Hans Fangohr. *A Systematic Approach to Multiphysics Extensions of Finite-Element-Based Micromagnetic Simulations: Nmag*, in IEEE Transactions on Magnetics, **43**, 6, 2896-2898 (2007). (Available `online `__) .. _|Nmag| Philosophy: |Nmag| Philosophy ----------------- Many specialized simulation codes used in research today consist of a highly specialized core application which initially was written to simulate the behaviour of some very specific system. Often, the core application then evolved into a more broadly applicable tool through the introduction of additional parameters. Some simulation codes reach a point where it becomes evident that they need an amount of flexibility that can only be provided by including some script programming capabilities. The approach underlying |Nmag| turns this very common pattern of software evolution (which we also have seen in web browsers, CAD software, word processors, etc) on its head: rather than gradually providing more and more flexibility in an ad-hoc manner through adding configuration parameters, slowly evolving into an extensive specialized programming language, |Nmag| starts out as an extension to a widely used programming language (Python_) from which it gains all its flexibility and evolves towards more specialized notions to conveniently define and study the properties of very specific physical systems [#FischbacherEtAl1]_. The main advantage of this approach is two-fold: first, we do not gradually evolve another ad-hoc (and potentially badly implemented) special purpose programming language. Second, by drawing upon the capabilities of a well supported existing framework for flexibility, we get a lot of additional power for free: the user can employ readily available and well supported Python libraries for tasks such as data post-processing and analysis, e.g. generating images for web pages etc. In addition to this, some users may benefit from the capability to use |Nmag| interactively from a command prompt, which can be very helpful during the development phase of an involved simulation script [#FischbacherEtAl2]_. The disadvantage is of course that a novice user may be confronted with much more freedom than he can handle. We try to cope with this issue by providing a collection of example scripts (in the :ref:`Guided Tour`) for the most common applications that only need very slight modification for basic use (e.g. changing of the mesh filename or material parameters). At present, |Nmag| is based on the Python programming language. This seems to be a somewhat reasonable choice at present, as Python is especially friendly towards casual users who do not want to be forced to first become expert programmers before they can produce any useful results. Furthermore, Python is quite widespread and widely supported these days. .. [#FischbacherEtAl1] Thomas Fischbacher, Matteo Franchin, Giuliano Bordignon,, Hans Fangohr, *A Systematic Approach to Multiphysics Extensions of Finite-Element-Based Micromagnetic Simulations: Nmag*, IEEE Transactions on Magnetics **43**, 6, 2896-2898 (2007), online at http://eprints.soton.ac.uk/46725/ .. [#FischbacherEtAl2] Thomas Fischbacher, Matteo Franchin, Giuliano Bordignon, Andreas Knittel, Hans Fangohr, *Parallel execution and scriptability in micromagnetic simulations*, Journal of Applied Physics **105**, 07D527 (2009), online at http://link.aip.org/link/?JAPIAU/105/07D527/1 .. comment: As most of the underlying field theoretical foundations used by |Nmag| are derived from the low level |Nsim| multiphysics simulator which is not closely tied to Python, it would be possible to provide support for other scripting languages in the future should the need arise (e.g. in case Python should become unpopular over the years). .. _How to read this document: How to read this document ------------------------- We suggest you follow the :ref:`Guided Tour` through a number of examples to get a quick overview of what |nmag| looks like in real use, and to see examples that can be used to carry out typical simulations. We provide a number of skeletons that are easily adapted to specific systems which show how to compute hysteresis loops, do energy minimisation, or compute time evolution. The :ref:`Command Reference` section explains the relevant commands provided by |Nmag| in full detail. This should be especially useful to advanced users who want to design sophisticated simulation scripts in Python. If you are new to micromagnetic modelling, you may want to start with the :ref:`mini tutorial micromagnetic modelling`. .. _Development status: Development status ------------------ .. comment: |Nmag| is a relatively young piece of software. It almost certainly contains bugs and we encourage users to report these to the :ref:`nmag team `, so they can be document and fixed; assuming the resources for this are available. It is also very likely that parts of the user interface will change over time. We will try to make changes backward compatible where this is feasible and acceptable. Some features do exist that have not been documented in the manual yet. This may be (i) because the nmag team has not found the time yet to create the documentation. However, it is also possible that (ii) we are still testing how a feature and its interface *feels* when being used, and we hesitate to document an interface if we consider it likely that it might be changed in the near future. Finally, (iii) we will not rush to publish any new functionality if we are not aware of any users who would be interested in this feature. For this reason, we do encourage users to contact the :ref:`nmag team ` to suggest features that would be relevant to them. We are also interested in generic feedback (good and bad; ideally constructive). While we have only limited resources for the development and maintenance of the code and will therefore not be able to react immediately (or at all) to requests and suggestions, it is important that we maintain an up-to-date understanding of the requirements of the community. The first Nmag release was late in 2007, and many bugs have been fixed since then. Having said that, without doubt there are bugs left in the system, and there is a long list of wishes for extra features, changes, improvements. Currently, there is no significant amount of funding or man power available to support Nmag users or develop it further. The software should thus be seen to be provided as is. Should you use Nmag for your work, please cite * Thomas Fischbacher, Matteo Franchin, Giuliano Bordignon, and Hans Fangohr, *A Systematic Approach to Multiphysics Extensions of Finite-Element-Based Micromagnetic Simulations: Nmag*, IEEE Transactions on Magnetics **43**, 6, 2896-2898 (2007), online: `preprint `__ and http://dx.doi.org/10.1109/TMAG.2007.893843 to demonstrate the value of open-source infrastructure in the community. (We should also cite the corresponding recommended publications when using OOMMF, Magpar, Mumax, MicroMagnum etc). .. _Mailing list: Mailing list ------------ If you are using |nmag|, we recommend that you subscribe to at least one of these following two lists. If you have a question about how to use the software, we suggest you subscribe to :ref:`nmag-users`, and post it there. .. comment: (If you prefer to contact only the developers, see :ref:`nmag team `.) .. _nmag-announce: nmag-announce ~~~~~~~~~~~~~ **nmag-announce@lists.soton.ac.uk** is a low traffic read-only mailing list which will broadcast updates of nmag and any other relevant news. To subscribe to this list, send an email to `nmag-announce-request@lists.soton.ac.uk `__ with an empty subject and the word ``subscribe`` in the body of the email. The **archives** can be found and searched at http://groups.google.com/group/nmag-announce. .. _nmag-users: nmag-users ~~~~~~~~~~ **nmag-users@lists.soton.ac.uk** is a mailing list to discuss the use of nmag, and for users to support users. Any announcements to ``nmag-announce`` will also be sent to this mailing list. To subscribe to this list, send an email to `nmag-users-request@lists.soton.ac.uk `__ with an empty subject and the word ``subscribe`` in the body of the email. Information about how to unsubscribe are provided with the welcome message once you have subscribed. The **archives** can be found and searched at http://groups.google.com/group/nmag-users. .. _Support: Support ------- Support will be provided within our limited resources (which may be None). After consulting the manual, please feel free to use the :ref:`mailing list` ``nmag-users@lists.soton.ac.uk`` to seek advice, or contact the :ref:`nmag team ` directly. .. _License and Disclaimer: License and Disclaimer ---------------------- This software was developed at the University of Southampton, United Kingdom. It is released under the GNU General Public License (GPL_) as published by the Free Software Foundation; either version 2, or (at your option) any later version. |Nmag| is an experimental system. Neither the University of Southampton nor the authors assume any responsibility whatsoever for its use by other parties, and makes no guarantees, expressed or implied, about its quality, reliability, or any other characteristic.