BornAgain ≻ git-develop ≻ Documentation ≻ Python scripting ≻ AI-assisted scripting

Writing BornAgain scripts with an LLM

For writing a new BornAgain script, or for adapting an existing example to the problem, we recommend asking a large language model (LLM) — ChatGPT, Claude, or any comparable assistant.

This applies to newcomers and to experienced users alike. Both modes work well:

  • a plain web chat (“just ask the chatbot”);
  • an agentic coding assistant that edits files in the local project directory and runs scripts directly.

Why this works for BornAgain

BornAgain is open source. The complete source tree — core, Python API, and the example library — is publicly readable. That is the decisive advantage:

  • The source code itself is the most complete and up-to-date reference for everything BornAgain can do.
  • The library of example scripts is part of that source tree, so the LLM can ground its answers in real, tested code.
  • Some constructors, function arguments, and parameter combinations are not (yet) documented on these web pages but are perfectly usable. Reading their source definitions can clarify these details.

How to give the LLM the right context

The single most important step is to pin the LLM to the installed BornAgain version. Otherwise it may mix in constructs from old releases, or invent things remembered from unrelated projects.

The prompt should include two links pointing to the installed version:

  • the source tree at the matching git tag, https://jugit.fz-juelich.de/mlz/bornagain/-/tree/v25.0.0, which gives the LLM access to the complete library and to the example scripts;
  • the corresponding web documentation at https://bornagainproject.org/25.0/, which gives it the prose explanations, conventions, and tutorials.

Ask the assistant to read the relevant examples and source files. If it cannot open the links, provide those files or use an assistant with access to a local checkout.

A sample prompt

I am writing a Python script using BornAgain version 25.0.0. Please use only constructs that are valid in this version. Source code: https://jugit.fz-juelich.de/mlz/bornagain/-/tree/v25.0.0. Documentation: https://bornagainproject.org/25.0/.

The script should ⟨describe your simulation or fit here⟩. Start from the example that most closely resembles this problem, and adapt it.

The prompt can be refined iteratively: by asking for explanations, alternative formulations, more comments, a different plotting style, wrapping the simulation in a fit, and so on.

Validate the output

LLMs still make mistakes, and the BornAgain Python API evolves between releases. As always:

  • run the script and check that it produces the expected output;
  • if a result looks wrong, ask the LLM to justify it, or compare against a trusted example;
  • report a bug if BornAgain itself appears to misbehave.