SampleModel to Experiment/Measurement linking

[damskii9992]

General

Our users will have many different and all valid refinement workflows, in general they can be split into 4 groups: single, simultaneous, sequential and decoupled:

1. Single Refinement

• 1.1. One sample model, one measured dataset.
  This is the simplest case. Unfortunately, life is often more complicated, but it’s a good starting point.

• 1.2. Multiple sample models, one measured dataset.
  A slightly more complex case. For example, two crystallographic phases both contribute to the measured data. Both sample models need to be considered during refinement.

2. Simultaneous Refinement

• 2.1. One sample model, multiple datasets.
  This scenario covers measurements of the same sample on different instruments or under different measurement conditions.
  In this case, the same sample model parameters are refined simultaneously across multiple datasets, while instrument parameters can be specific to each dataset.

• 2.2. Multiple sample models, multiple datasets.
  Each dataset may include contributions from different sample models. For example:

  • A neutron diffraction dataset might have the main contribution from the sample of interest, plus a minor contribution from a sample environment (e.g., a cryostat).
  • A synchrotron X-ray dataset of the same composition, from a different preparation batch, could have the main contribution from the sample of interest plus a minor contribution from an impurity phase.

  In this case, all datasets are refined simultaneously as part of a single combined refinement, with both:

  • Shared (constrained) parameters across datasets for the main sample model
  • Independent parameters specific to each dataset, covering minor phases and instrument-specific parameters.

3. Sequential Refinement

• 3.1. Single or multiple sample models contributing to multiple datasets.
  For example, studying temperature dependence in a phase transition by measuring datasets at different temperatures.
  • The refinement is done sequentially: each dataset is refined one after another.
  • The refined parameters from one dataset are used as the starting point for the next.
    This sequential strategy is particularly important when working with large datasets, such as hundreds of measurements collected at small temperature steps, or in imaging where flight-path calibration has to be done for every experiment.

4. Decoupled Refinement

• 4.1. Multiple sample models tested on a single measured dataset to select the best-fitting model.
  For example, comparing several candidate magnetic structures to determine which one best fits the data.
  • In this case, each model is refined independently; the results can be compared afterward to identify the best solution.
  • This could also be viewed as a type of parallel refinement, where multiple models are processed in sequence (or even simultaneously), but without interaction between their refinements.

Because different techniques have very different requirements, we have 2 different API's / strategies to support these many different types of refinement. All techniques should use one of these two API's / strategies.

1: Linking SampleModel to the Measurement/Experiment happens in Analysis

The linking of which SampleModel goes with which Measurement/Experiment happens in the Analysis page in the GUI or when constructing the Analysis object in the library.

This is the strategy employed by EasyImaging and EasyDynamics.

Library API

Users simply pass a list of models and experiments to the Analysis object when creating it. The choice of the refinement strategy is decided with keyword arguments:

analysis = Analysis(
   sample_models = [model_1, model_2],
   experiments = [experiment_1, experiment_2],
   mode = 'Sequential'
   )

The Analysis class handles the logic of choosing which type of refinement is chosen based on its inputs.

Application Workflow

The users can load in as many datasets as they want in a project and create as many Measurement/Experiments as they want and choose which one to view on the Measurements/Experiment page.
On the SampleModel page the user can also define as many models as they wish and choose which one to view.

On the Analysis page, a table/list/stack of all Measurements/Experiments are shown and another table/list/stack of all SampleModels are shown. An Analysis object can then be created by dragging Measurements/Experiments from its stack and SampleModels from its stack into an empty Analysis table/list/stack. As many Analysis objects can be created as the user wants by simply adding another empty Analysis to the stack.

On the Sumary page, a table/list/stack of all Analysis objects are shown, so a summary of each one can be viewed separately or compared.

2: Linking SampleModel to the Experiment happens in Experiment

This strategy defines the relationship between a SampleModel and an Experiment as part of the Experiment, rather than creating the relationship later in Analysis.

This is the strategy employed by EasyDiffraction and EasyReflectometry.

Motivation

For diffraction, the Experiment is the natural place where measured data, instrument configuration, and sample contributions come together.

This approach is also consistent with IUCr CIF standards, which separate structural and experimental information into different datablocks. A structure datablock describes the sample model, while an experiment datablock describes the measurement and contains references to the structures contributing to that experiment.

From this perspective, an experiment represents measured data collected from one or more sample contributions using a specific instrument setup. Therefore, an Experiment should contain:

• measured data
• instrument parameters
• background and correction parameters
• references to contributing sample models
• contribution parameters associated with each sample model (e.g. scale factors)

Important

Importantly, the experiment stores only references to sample models (for example, unique identifiers or names) and experiment-specific contribution parameters. It does not own or duplicate the sample model objects themselves.

This keeps structural information and experimental information clearly separated while preserving the relationship between them.

Library API

The Experiment owns the information describing which sample models contribute to its calculated pattern.

For example:

pdf_expt.linked_phases.create(id='lbco', scale=2.0)
bragg_expt.linked_phases.create(id='lbco', scale=13.0)  # same structural model as in pdf_expt
bragg_expt.linked_phases.create(id='si', scale=1.0)  # additional structural model not present in pdf_expt

In this example, both experiments reference the same structural model (lbco) while maintaining independent experiment-specific contribution parameters. The Bragg experiment additionally references a second structural model (si) that does not contribute to the PDF experiment. This demonstrates that experiments can share sample models while also defining different sets of contributing sample models.

The Analysis object does not create or manage model–experiment relationships. Instead, it operates on the relationships already defined by the experiments and focuses solely on fitting strategy and execution.

For example:

project.analysis.fitting_mode.type = 'single'
project.analysis.fitting_mode.type = 'joint'
project.analysis.fitting_mode.type = 'sequential'

In a joint Bragg + PDF refinement, multiple experiments may reference the same sample model while each experiment maintains its own instrument parameters, background, scale factors, resolution functions, and other experiment-specific settings.

Application Workflow

Sample Model Page

The user defines one or more sample models.

Experiment Page

The user defines one or more experiments.

For each experiment, the user can view and edit the list of contributing sample models together with experiment-specific contribution parameters such as scale factors.

Typical functionality includes:

• automatically linking all available sample models to a newly created experiment
• manually adding or removing sample model references
• defining different sample model contributions for different experiments

This allows each experiment to accurately represent the physical system measured in that dataset.

Analysis Page

The Analysis page does not recreate model–experiment relationships.

Instead, it only defines how the existing experiments should be processed, for example:

• single
• joint
• sequential

Analysis jobs are automatically generated from the set of experiments and their linked sample models.

This keeps the Analysis page focused on fitting strategy rather than on redefining the physical content of experiments.

Advantages

This approach is particularly suitable for diffraction because:

• it follows the natural diffraction workflow: sample model → experiment → analysis
• it aligns with the separation of structural and experimental information used in IUCr CIF standards
• it keeps sample contributions and contribution parameters close to the measured data to which they belong
• it avoids duplicating experiment configuration or model–experiment mappings in the Analysis layer

---

Link to the ADR suggestion:
#31