+++
title = "AI-assisted scripting"
weight = 15
+++

## 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]({{< url-src >}}/auto/Examples) 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/v{{< release-number >}}`,
  which gives the LLM access to the complete library and to the
  example scripts;
* the corresponding web documentation at
  `https://bornagainproject.org/{{< release-major >}}/`,
  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
> `{{< release-number >}}`.
> Please use only constructs that are valid in this version.
> Source code:
> `https://jugit.fz-juelich.de/mlz/bornagain/-/tree/v{{< release-number >}}`.
> Documentation:
> `https://bornagainproject.org/{{< release-major >}}/`.
>
> 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]({{< url-src >}}/auto/Examples);
* [report a bug](/howto/get-help) if BornAgain itself appears to
  misbehave.
