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, Gemini, Grok, 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. The LLM sees them in the source where a reader of the documentation alone would miss them.

In other words, the LLM gets the full context of BornAgain’s API.

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/v24.0, which gives the LLM access to the complete library and to the example scripts;
  • the corresponding web documentation at https://bornagainproject.org/24/, which gives it the prose explanations, conventions, and tutorials.

Modern web chat assistants can follow these links and read what they find there. Agentic assistants additionally have direct access to the local source tree, which works even better.

A sample prompt

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

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.

Why this approach works

Given the open source code as context, an LLM is genuinely good at producing correct, idiomatic BornAgain scripts — often faster and more reliably than working through the documentation page by page. The quality of the answer depends on the available context, and for BornAgain that context is public and complete.

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.