Using NeuralMag with AI assistants#

NeuralMag is designed to be used with AI coding assistants. Because NeuralMag is a specialized package, a general large language model often guesses its API wrong, so NeuralMag ships its own machine-readable, version-matched usage context.

For users#

Give your assistant accurate, install-matched context in one step:

  • in Python, call neuralmag.llm_context() and paste the result into your assistant, or

  • in a terminal, run python -m neuralmag.

The returned guide covers the design philosophy, the configuration model, a canonical workflow, multi-domain materials, inverse-problem patterns and common pitfalls. It is prefixed with live facts about your installation (backend, dtype and the field terms actually available), so the assistant never relies on an API that your version does not provide.

The same content is published on the web following the llms.txt convention:

Point a chat assistant (or a documentation-aware tool) at those URLs.

Tip

In your own project you can make this automatic: add a CLAUDE.md or AGENTS.md containing a line such as “When using neuralmag, run python -m neuralmag to load its API guide.”

For contributors#

When developing NeuralMag itself, the source of truth for architecture, discretization schemes, backends and the design principles new code must follow is AGENTS.md in the repository root. It is tool-neutral and written to be read by AI coding agents as well as humans.

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

  • Claude Code reads a CLAUDE.md. The repository does not ship one (keep it personal / out of version control); create one in the repository root that imports the shared guide:

    @AGENTS.md

    and Claude Code will load AGENTS.md into context automatically.

See also#