neuralmag 1.0.0

NeuralMag is a micromagnetic GPU code implementing the nodal FD discretization

Built to be used with AI assistants. NeuralMag is fully differentiable micromagnetics (JAX/PyTorch) that ships its own machine-readable, version-matched context, so assistants like Claude, Cursor or ChatGPT can help you write correct NeuralMag code — just run python -m neuralmag. See NeuralMag & AI assistants.

NeuralMag is a micromagnetic simulation software using the nodal finite-difference discretization scheme, designed specifically with inverse problems in mind. It uses either JAX or PyTorch as a numerical backend for tensor operations and automatic differentiation, enabling computations on both CPU and GPU systems. At the moment NeuralMag implements the most common micromagnetic effective-field contributions

• external field
• exchange field
• demagnetization field
• uniaxial/cubic anisotropy
• DMI (interface and bulk)
• interlayer exchange

as well as a differentiable time-domain solver for the Landau-Lifshitz-Gilbert equation.

NeuralMag is designed in a modular fashion resulting in a very high flexibility for the problem definition. For instance, all simulation parameters (e.g. material parameters) can be functions of space, time or any other simulation parameter.

At the heart of NeuralMag is a form compiler powered by SymPy that translates arbitrary functionals and linear weak forms into vectorized PyTorch or JAX code. This allows to easily add new effective-field contributions by simply stating the corresponding energy as a sympy expression.

NeuralMag & AI assistants

We treat AI assistants as first-class users of NeuralMag — both for using it and for contributing to it.

Using NeuralMag with an AI assistant. Because NeuralMag is specialized, a general LLM often guesses its API wrong. NeuralMag ships its own machine-readable, version-matched context so your assistant stays accurate:

• Run python -m neuralmag (or call neuralmag.llm_context() in Python) and hand the output to your assistant. You get a concise guide — design philosophy, configuration, a canonical workflow, multi-domain materials, inverse-problem patterns and common pitfalls — prefixed with live facts about your install (backend, dtype, available field terms), so it never describes an API you don't have.
• On the web, the same content is published as llms.txt / llms-full.txt, following the llms.txt convention — point a chat assistant at the URL.
• Tip: in your own project, add a CLAUDE.md or AGENTS.md with a line like "When using neuralmag, run python -m neuralmag to load its API guide" to make this automatic.

Contributing to NeuralMag with an AI assistant. AGENTS.md is the checked-in, tool-neutral project guide (architecture, discretization schemes, backends, design principles), written to be read by AI coding agents as well as humans.

• Cursor and most agentic IDEs read AGENTS.md from the repo root directly.

• Claude Code reads a CLAUDE.md. The repo doesn't ship one (keep it personal), but setup is one line — create CLAUDE.md in the repo root that imports the shared guide:

  @AGENTS.md
  

  Claude Code then loads AGENTS.md into context automatically.

The same information is in the documentation: Using NeuralMag with AI assistants.

Documentation

The documentation of NeuralMag including a reference to all classes as well as several examples can found here.

NeuralMag in the cloud

Experience NeuralMag without installing it locally by accessing it directly in the cloud via Binder. Simply click the badge to get started:

Using NeuralMag on Binder allows you to experience its features, without the hassle of setting up your local environment. It provides a quick and accessible way to test and experiment with the software from any device with a web browser. It is important to note that the Binder-hosted version is a CPU-only JAX implementation, and it will run slower than a local installation. Sessions are temporary and may time out after a period of inactivity, and any files created or modified during your session will not be saved. To avoid losing your work, please remember to download any files you create or edit before your session ends.

Download and Install

NeuralMag is a Python package and requires Python >=3.8 (>=3.10 for JAX backend). To install the latest version with pip either run

pip install "neuralmag[jax]"

to install NeuralMag with JAX as a backend or

pip install "neuralmag[torch]"

to install NeuralMag with PyTorch as a backend. You can also install NeuralMag with both backends and choose the backend at runtime.

How to cite

If you use NeuralMag in scientific work, please cite the accompanying paper:

C. Abert, F. Bruckner, A. Voronov, M. Lang, S. A. Pathak, S. Holt, R. Kraft, R. Allayarov, P. Flauger, S. Koraltan, T. Schrefl, A. Chumak, H. Fangohr, D. Suess, "NeuralMag: an open-source nodal finite-difference code for inverse micromagnetics", npj Comput. Mater. 11, 193 (2025). doi:10.1038/s41524-025-01688-1

BibTeX:

@article{Abert2025NeuralMag,
  author  = {Abert, Claas and Bruckner, Florian and Voronov, Andrii and
             Lang, Martin and Pathak, Swapneel Amit and Holt, Sam and
             Kraft, Roman and Allayarov, Rustam and Flauger, Paul and
             Koraltan, Sabri and Schrefl, Thomas and Chumak, Andrii and
             Fangohr, Hans and Suess, Dieter},
  title   = {{NeuralMag}: an open-source nodal finite-difference code for
             inverse micromagnetics},
  journal = {npj Computational Materials},
  volume  = {11},
  pages   = {193},
  year    = {2025},
  doi     = {10.1038/s41524-025-01688-1},
}

Contribute

Thank you for considering contributing to our project! We welcome any contributions, whether they are in the form of bug fixes, feature enhancements, documentation improvements, or any other kind of enhancement. NeuralMag is licensed under the MIT License. By contributing to this project, you agree to license your contributions under the terms of the MIT License.

See CONTRIBUTING.md for how to set up a development environment and run the tests. For an overview of the architecture, discretization schemes, backends, and the design principles that new code should follow, see AGENTS.md; for using it with AI coding assistants, see NeuralMag & AI assistants above.