Metadata-Version: 2.4
Name: neuralmag
Version: 1.0.0
Summary: NeuralMag is a micromagnetic GPU code implementing the nodal FD discretization
Author-email: Claas Abert <claas.abert@univie.ac.at>, Florian Bruckner <florian.bruckner@univie.ac.at>, Martin Lang <martin.lang@mpsd.mpg.de>, Swapneel Amit Pathak <swapneel-amit.pathak@mpsd.mpg.de>, Samuel Holt <samuel.holt@mpsd.mpg.de>, Hans Fangohr <hans.fangohr@mpsd.mpg.de>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: sympy
Requires-Dist: pyvista
Requires-Dist: scipy
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: nbsphinx; extra == "dev"
Requires-Dist: pydata-sphinx-theme; extra == "dev"
Requires-Dist: jupyterlab; extra == "dev"
Requires-Dist: nbval; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: nbconvert==7.17.1; extra == "dev"
Provides-Extra: torch
Requires-Dist: torch; extra == "torch"
Requires-Dist: torchdiffeq; extra == "torch"
Provides-Extra: jax
Requires-Dist: jax>=0.8.0; extra == "jax"
Requires-Dist: diffrax; extra == "jax"
Requires-Dist: optax; extra == "jax"
Dynamic: license-file

<p align="center">
  <img src="logo/neuralmag.png" alt="NeuralMag" width="300">
</p>

> **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--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](https://jax.readthedocs.io/en/latest/) or [PyTorch](https://pytorch.org/) 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](https://www.sympy.org/)
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](https://neuralmag.gitlab.io/neuralmag/llms.txt) /
    [llms-full.txt](https://neuralmag.gitlab.io/neuralmag/llms-full.txt), following the
    [llms.txt](https://llmstxt.org) 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](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:

    ```markdown
    @AGENTS.md
    ```

    Claude Code then loads AGENTS.md into context automatically.

The same information is in the documentation:
[Using NeuralMag with AI assistants](https://neuralmag.gitlab.io/neuralmag/user_guide/ai_assistants.html).

Documentation
=============

The documentation of NeuralMag including a reference to all classes as well as several
examples can found [here](https://neuralmag.gitlab.io/neuralmag/index.html).

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:
[![Binder](https://notebooks.mpcdf.mpg.de/binder/badge_logo.svg)](https://notebooks.mpcdf.mpg.de/binder/v2/git/https%3A%2F%2Fgitlab.mpcdf.mpg.de%2Fneuralmag%2Fneuralmag.git/binder)

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

``` {.sourceCode .}
pip install "neuralmag[jax]"
```

to install NeuralMag with JAX as a backend or

``` {.sourceCode .}
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](https://doi.org/10.1038/s41524-025-01688-1)

BibTeX:

```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](https://opensource.org/license/MIT). By contributing to this project,
you agree to license your contributions under the terms of the MIT License.

See [CONTRIBUTING.md](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](AGENTS.md); for
using it with AI coding assistants, see [NeuralMag & AI assistants](#neuralmag--ai-assistants)
above.
