✨ Why this documentation was needed

Pyxel already provides a detailed API reference for internal data structures such as pixel containers, including volatile and non-volatile components. However, the conceptual meaning of this distinction—and its impact on configuration design—was not previously explained in the user documentation.

As a result, users could be surprised when identical configurations produced slightly different results across simulation runs, or unsure where to express variability versus stable detector properties.

This documentation closes that gap by explaining the distinction in plain language, before users encounter it indirectly through behavior.

🔧 What changed

A new section titled “Volatile and Non-Volatile Parameters” was added to the Configuration files documentation.

• Explains what “volatile” and “non-volatile” mean in Pyxel
• Connects detector physics to simulation behavior
• Clarifies why results may differ between runs
• Guides users on where to place parameters in YAML files
• Avoids duplicating API reference documentation

The focus is intentionally conceptual, helping users build a correct mental model rather than exposing internal implementation details.

🧠 Volatile vs non-volatile: the core idea

In Pyxel, not all detector-related quantities are expected to behave the same way between runs.

Non-volatile parameters describe stable properties of the instrument—such as geometry, layout, material characteristics, and fixed-pattern effects—that remain constant across executions.

Volatile effects, on the other hand, represent stochastic physical processes like noise, dark current fluctuations, or cosmic ray events. These are expected to vary naturally from run to run and are typically introduced through pipeline models.

Making this distinction explicit helps users reason about reproducibility, realism, and correct configuration design.

🌱 Why this matters

Good scientific software documentation is not only about describing APIs—it is about setting expectations.

By clearly explaining which aspects of a simulation are stable and which are intentionally variable, Pyxel enables users to:

• Interpret simulation results correctly
• Design configurations with confidence
• Balance reproducibility with physical realism

This change does not alter Pyxel’s behavior. It simply makes existing design choices visible, understandable, and easier to work with.