Inputs and outputs¶

Each experiment has its own directory containing experiment.yaml, a starting structure CIF, and experimental .cif_pets data.

Required inputs¶

File	Contents
`experiment.yaml`	Input filenames and settings for the experiment.
`.cif`	Starting crystal structure.
`.cif_pets`	Experimental diffraction data reduced by PETS2.

Paths written in experiment.yaml are measured from the experiment directory:

inputs:
  structure: structure.cif
  exp_data: experiment.cif_pets
  # Optional: force all CIF ADPs to refine as Uiso.
  isotropic_displacements_only: false

The structure CIF supplies the atoms, fractional coordinates, occupancies, atomic displacement parameters (ADPs), and space-group symmetry operations.

The .cif_pets file supplies the observed reflection intensities and uncertainties, crystal orientations, goniometer angles, electron wavelength, unit cell, and apparent mosaicity.

Unit cell¶

Both input files contain a unit cell. diffBloch uses the .cif_pets cell for the simulation and uses the structure-CIF cell as a consistency check.

A difference greater than 1% in any cell parameter produces a warning.
A difference greater than 5% stops the calculation.

ADP parameterization¶

By default, diffBloch preserves the ADP kinds declared by the structure CIF: Uani sites refine with anisotropic ADPs, and Uiso sites refine with isotropic ADPs. Set inputs.isotropic_displacements_only: true to force every atom onto isotropic ADPs even when the CIF contains _atom_site_aniso_* rows.

Atoms that were already Uiso keep their CIF U_iso_or_equiv seed. Atoms that were Uani are seeded from the crystallographic equivalent isotropic value, Ueq, computed from their CIF Uij tensor using the same unit cell that defines the refinement ADP frame. The original parsed structure record is not mutated; this is an experiment parameterization choice applied when refinement inputs are built.

The flag changes the preprocessed starting point and is recorded in the per-dataset checkpoint identity. When refinement writes refined_structure.cif, force-converted atoms are written as Uiso and stale anisotropic rows are removed so the output re-reads with the same effective ADP kinds.

Excluding rotations¶

Individual rotations can be excluded when their diffraction data should not be used, for example after beam damage has degraded the crystal or when no usable reflections were recorded. Rotations are selected by their zero-based indices:

blochwave:
  ignore_orientations: [0, 1, 18, 56]

Excluded rotations are not used during preprocessing, inference, or refinement.

Multiple datasets¶

Several .cif_pets files from the same material can be combined in one refinement:

inputs:
  structure: structure.cif
  multi_dataset: true
  exp_data:
    - crystal_1.cif_pets
    - crystal_2.cif_pets

The rotations from all files are combined against one structure. Each dataset keeps its own orientations and thicknesses. The files must describe the same crystal and use the same electron energy. The first .cif_pets file supplies the unit cell used for the combined refinement.

When the learned thickness model is enabled (refinement.thickness_nn, the default), each dataset trains its own network over its own tilt range — pooled datasets with overlapping tilt ranges are never forced onto one shared thickness-vs-alpha curve. The refinement report carries one Thickness NN -- <ref> section and one thickness_nn_shape_<stem>.png plot per dataset.

Outputs¶

Running preprocessing or refinement adds results to the experiment directory:

Output	Contents
`refined_structure.cif`	Refined crystal structure.
`refinement_report.txt`	Final residuals, reflection counts, and refinement summary.
`thickness_optim/`	Thickness-search plots when plotting is enabled.
`thickness_nn_shape_<stem>.png`	Learned thickness curve per `.cif_pets` dataset, when the thickness network and plotting are enabled.
`reproducibility/plan.<stem>.npz`	Saved preprocessing for each `.cif_pets` dataset.
`reproducibility/plan.<stem>.lock`	Inputs and settings used for the saved preprocessing.
`reproducibility/refined_parameters.npz`	Refined parameter values.
`reproducibility/refinement.lock`	Inputs and settings used for the refinement.

reproducibility/experiment.lock is not one of these calculation outputs. It identifies the raw input files accepted for the experiment and is created automatically the first time any command runs against the experiment directory. See Reproducibility for the create-only lock-experiment command and the warning about invalidating plan and refinement locks after input changes.

See Refinement for the refinement report and Reproducibility for the lock files.