autoemx.config.runtime_configs module

AutoEMX configuration dataclasses.

Created on Mon Jul 28 10:33:35 2025

@author: Andrea

This module provides configuration dataclasses for all stages of an automated X-ray spectroscopy workflow, including microscope setup, sample and substrate definition, measurement and acquisition settings, spectrum fitting, quantification and filtering, powder measurement, and plotting.

Configurations:

• MicroscopeConfig: Settings for microscope hardware, calibration, and imaging parameters.

• SampleConfig: Defines the sample’s composition/type and spatial properties.

• SampleSubstrateConfig: Specifies the substrate composition and geometry supporting the sample.

• MeasurementConfig: Controls measurement type, beam parameters, and acquisition settings.

• QuantificationOptionsConfig: Runtime options for spectral fitting and quantification.

• PowderMeasurementConfig: Settings for analyzing powder samples and particle selection.

• BulkMeasurementConfig: Settings for analyzing non-powder samples.

• PlotConfig: Options for saving, displaying, and customizing plots.

Each dataclass includes attribute documentation and input validation.

class autoemx.config.runtime_configs.MicroscopeConfig(*, ID: str = 'PhenomXL', type: str = 'SEM', detector_type: str = 'BSD', is_auto_BC: bool = True, brightness: float | None = None, contrast: float | None = None, energy_zero: float | None = None, bin_width: float | None = None)

Bases: BaseModel

Configuration for the microscope hardware.

ID

Identifier for the microscope, defining instrument calibrations at ./XSp_calibs/Microscopes/ID.

Type:

str

type

Type of microscope. Allowed: ‘SEM’ (implemented), ‘STEM’ (not implemented).

Type:

str

is_auto_BC

If True, brightness/contrast are set automatically.

Type:

bool

brightness

Manual brightness value; required if is_auto_BC is False.

Type:

Optional[float]

contrast

Manual contrast value; required if is_auto_BC is False.

Type:

Optional[float]

energy_zero

Set from detector calibration files during spectral collection.

Type:

Optional[float]

bin_width

Set from detector calibration files during spectral collection.

Type:

Optional[float]

Notes

• If is_auto_BC is False, both brightness and contrast must be provided.

• STEM mode is not implemented and will raise NotImplementedError.

• The microscope ID must correspond to a folder at ./XSp_calibs/Microscopes/ID containing all necessary calibration files.

ID: str

type: str

detector_type: str

is_auto_BC: bool

brightness: float | None

contrast: float | None

energy_zero: float | None

bin_width: float | None

ALLOWED_TYPES: ClassVar[Tuple[str, ...]] = ('SEM', 'STEM')

ALLOWED_DETECTOR_TYPES: ClassVar[Tuple[str, ...]] = ('BSD',)

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class autoemx.config.runtime_configs.SampleConfig(*, elements: List[str], type: str = 'powder', w_frs: Dict[str, float] | None = None, center_pos: Tuple[float, float] = (0.0, 0.0), half_width_mm: float = 2.9, is_powder_sample: bool = False, is_surface_rough: bool = False, is_grid_acquisition: bool = False, is_particle_acquisition: bool = False)

Bases: BaseModel

Configuration for the sample.

elements

List of elemental symbols (e.g., [‘Fe’, ‘O’]).

Type:

List[str]

type

Sample type. Allowed types: - powder: Expects particles, and uses geometrical correction factors during spectral fits. - powder_continuous: Expects a quasi-continuous powder mixture, sampled in a grid (NO PARTICLE DETECTION APPLIED).

Applies geometrical correction factors during spectral fits.

• bulk: Expects a flat, continuous surface, sampled in a grid. Does not apply geometrical factors.

• bulk_rough: Expects a continuous surface, sampled in a grid. Applies geometrical factors.

• film: NOT IMPLEMENTED YET

Type:

str

w_frs

Known elemental mass fractions, kept fixed during fits (e.g., {‘Fe’: 0.4, ‘O’: 0.6}). Set automatically for experimental standards from their formula (ExpStandardsConfig.formula_w_frs).

Type:

Dict[str,float]

center_pos

(x, y) center position of the sample on the stage, in mm.

Type:

Tuple[float, float]

half_width_mm

Half-width of the sample in millimeters.

Type:

float

Notes

• Only ‘powder’ and ‘bulk’ type are implemented. ‘film’ will raise NotImplementedError.

• Element symbols are validated. An error is raised if any symbol is unrecognized.

elements: List[str]

type: str

w_frs: Dict[str, float] | None

center_pos: Tuple[float, float]

half_width_mm: float

ALLOWED_TYPES: ClassVar[Tuple[str, ...]] = ('powder', 'powder_continuous', 'bulk', 'bulk_rough', 'film')

POWDER_SAMPLES_TYPES: ClassVar[List[str]] = ['powder', 'powder_continuous']

is_powder_sample: bool

ROUGH_SURFACE_TYPES: ClassVar[List[str]] = ['powder', 'powder_continuous', 'bulk_rough']

is_surface_rough: bool

GRID_ACQUISITION_TYPES: ClassVar[Tuple[str, ...]] = ('bulk', 'powder_continuous', 'bulk_rough', 'film')

is_grid_acquisition: bool

PARTICLE_ACQUISITION_TYPES: ClassVar[str] = 'powder'

is_particle_acquisition: bool

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class autoemx.config.runtime_configs.SampleSubstrateConfig(*, elements: List[str] = <factory>, type: str = 'Ctape', shape: str = 'circle', auto_detection: bool = True, stub_w_mm: float = 12)

Bases: BaseModel

Configuration for the sample substrate.

elements

List of element symbols present in the sample substrate.

Type:

List[str]

type

Type of the sample substrate. Allowed values: ‘Ctape’.

Type:

str

shape

Shape of the sample substrate. Allowed values: ‘circle’, ‘rectangle’.

Type:

str

auto_detection

Whether to attempt automatic detection of substrate. (implemented only for type = Ctape & shape = ‘circle’)

Type:

bool

stub_w_mm

Lateral dimension of substrate holder in mm, used for determining image size for auto_detection.

Type:

float

Notes

• Element symbols are validated. An error is raised if any symbol is unrecognized.

elements: List[str]

type: str

shape: str

auto_detection: bool

stub_w_mm: float

ALLOWED_TYPES: ClassVar[Tuple[str, ...]] = ('Ctape', 'None')

ALLOWED_SHAPES: ClassVar[Tuple[str, ...]] = ('circle', 'square')

ALLOWED_AUTO_DETECTION_TYPES: ClassVar[str] = 'Ctape'

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class autoemx.config.runtime_configs.MeasurementConfig(**data: Any)

Bases: BaseModel

Configuration for the measurement/acquisition session.

type

Measurement type. Allowed: ‘EDS’ (implemented), ‘WDS’ (not implemented).

Type:

str

mode

Measurement mode (e.g., ‘point’). Defines set of measurement parameters (i.e., beam current), determining detector calibration parameters

Type:

str

working_distance

Working distance to use for current measurement, in mm. Takes it from EM_driver if left unspecified.

Type:

Optional[float]

working_distance_tolerance

Defines maximum accepted deviation of working distance from its typical value, in mm. Used to prevent gross mistakes from EM autofocus. Default: 1 mm.

Type:

Optional[float]

beam_energy_keV

Electron beam energy in keV.

Type:

float

beam_current

Beam current; must be provided at initialization or via detector channel calibration file.

Type:

Optional[float]

emergence_angle

Emergence angle; updated from microscope driver file if not provided.

Type:

Optional[float]

is_manual_navigation

If True, instrument navigation is performed manually.

Type:

bool

max_acquisition_time

Maximum X-ray spectral acquisition time in seconds.

Type:

float

target_acquisition_counts

Target number of counts for acquisition of X-ray spectrum.

Type:

int

min_n_spectra

Minimum number of spectra to acquire.

Type:

int

max_n_spectra

Maximum number of spectra to acquire.

Type:

int

powder_meas_cfg

Powder acquisition settings.

Type:

Optional[PowderMeasurementConfig]

bulk_meas_cfg

Bulk/grid acquisition settings.

Type:

Optional[BulkMeasurementConfig]

exp_stds_cfg

Experimental standards settings.

Type:

Optional[ExpStandardsConfig]

saved_images_extension

Extension used when saving SEM frame images.

Type:

str

save_raw_images

Whether to also save the non-annotated version of annotated SEM images (frame images, and particle images when annotate_particle_images is True).

Type:

bool

annotate_particle_images

Whether to draw the spectrum spots (dot + spectrum ID) and a scale bar on the particle images saved during acquisition. If False (default), raw particle images are saved; annotated copies can be made afterwards with Annotate_Particle_Images.py.

Type:

bool

type: str

mode: str

working_distance: float | None

working_distance_tolerance: float

beam_energy_keV: float

beam_current: float | None

emergence_angle: float | None

is_manual_navigation: bool

max_acquisition_time: float

target_acquisition_counts: int

min_n_spectra: int

max_n_spectra: int

powder_meas_cfg: PowderMeasurementConfig | None

bulk_meas_cfg: BulkMeasurementConfig | None

exp_stds_cfg: ExpStandardsConfig | None

saved_images_extension: str

save_raw_images: bool

annotate_particle_images: bool

ALLOWED_IMAGE_EXTENSIONS: ClassVar[Tuple[str, ...]] = ('tif', 'tiff', 'png', 'jpg', 'jpeg', 'webp', 'bmp')

PARTICLE_STATS_MEAS_TYPE_KEY: ClassVar[str] = 'particle_stats'

ALLOWED_TYPES: ClassVar[Tuple[str, ...]] = ('EDS', 'WDS', 'particle_stats')

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class autoemx.config.runtime_configs.QuantificationOptionsConfig(*, method: str = 'PB', spectrum_lims: Tuple[float, float]=(14, 1100), fit_tolerance: float = 0.0001, use_instrument_background: bool = False, use_project_specific_std_dict: bool = False, min_total_counts_fraction: float = 0.9, is_known_phase_mixture: bool = False, identify_missing_elements: bool = True, identification_seed_spectra: int = 10, identification_z_range: Tuple[int, int]=(5, 83), identification_excluded_elements: List[str] = <factory>)

Bases: BaseModel

Configuration for X-ray spectrum fitting and quantification.

method

Method to use for quantification. Currently only accepts ‘PB’

Type:

str

spectrum_lims

Lower and upper spectral index limits.

Type:

Tuple[float, float]

fit_tolerance

lmfit tolerance for fit convergence

Type:

float

use_instrument_background

Whether to use the instrument background in the fit (Default: False). If False, AutoEMX computes the background while fitting.

Type:

bool

use_project_specific_std_dict

If True, tries to load the dictionary of reference standards from the project folder. If not found, uses the default file “EDS_Stds_{beamenergy}keV.json” at XSp_calibs/Microscopes/your_microscope.

Type:

bool

min_total_counts_fraction

Minimum accepted total spectrum counts as a fraction of target_acquisition_counts. Spectra below this threshold are flagged quant_flag = 2 (“Total counts too low”). Default is 0.9 (90%). Lower this to quantify shorter acquisitions; 0 disables the check.

Type:

float

is_known_phase_mixture

Whether the sample is a mixture of known phases (the candidate phases). If True, spectra are quantified with the reference P/B values of the standards of these phases, and the analysis characterizes their intermixing. Default is False. Not part of the quantification fingerprint, since the P/B values it selects are (reference_values_by_el_line).

Type:

bool

identify_missing_elements

If True, each spectrum is checked for elements missing from its fit before quantification (see autoemx.core.fitter.peak_identification). Elements whose addition surely improves the fit of the peaks are added and quantified (or only fitted, if no standard is available); weaker detections are only reported as possibly present. Default is False.

Type:

bool

identification_seed_spectra

Number of spectra checked without prior knowledge; the elements found in them are then tested first in the remaining spectra, to save time. Default is 10.

Type:

int

identification_z_range

Atomic numbers of the elements the identification of missing elements may propose. Default is (5, 83), B to Bi; use (5, 92) to include Th and U.

Type:

Tuple[int, int]

identification_excluded_elements

Elements never proposed. Default: Tc, Pm (no stable isotopes) and the noble gases Ne, Kr, Xe, Rn.

Type:

List[str]

DEFAULT_MIN_TOTAL_COUNTS_FRACTION: ClassVar[float] = 0.9

method: str

spectrum_lims: Tuple[float, float]

fit_tolerance: float

use_instrument_background: bool

use_project_specific_std_dict: bool

min_total_counts_fraction: float

is_known_phase_mixture: bool

identify_missing_elements: bool

identification_seed_spectra: int

identification_z_range: Tuple[int, int]

identification_excluded_elements: List[str]

ALLOWED_METHODS: ClassVar[List[str]] = ['PB']

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class autoemx.config.runtime_configs.PowderMeasurementConfig(*, par_selection_mode: Literal['auto', 'manual', 'list'] = 'auto', img_shift_tracking: bool = True, par_search_frame_width_um: float | None = None, max_n_par_per_frame: int = 30, max_spectra_per_par: int = 3, max_area_par: float = 300.0, min_area_par: float = 10.0, par_mask_margin: float = 1.0, xsp_spots_distance_um: float = 1.0, par_spot_selection_mode: Literal['auto', 'callback'] = 'auto', par_segmentation_model: str = 'threshold_bright', par_brightness_thresh: int = 100, par_xy_spots_thresh: int = 100, par_feature_selection: str = 'random', par_spot_spacing: str = 'random')

Bases: BaseModel

Configuration for powder measurement.

par_selection_mode

Particle navigation mode (default: ‘auto’): - 'auto': automatic frame scan and particle detection - 'manual': prompt the user to center each particle - 'list': visit a caller-supplied list of ledger particle ids or

absolute stage coordinates in mm (see batch_acquire_and_analyze)

Type:

str

img_shift_tracking

Whether to use image shift tracking during acquisition (Default = True).

Type:

bool

par_search_frame_width_um

Frame width used when searching for particles, in um. Default: min(20*max_par_radius, 500 um)

Type:

float, optional

max_n_par_per_frame

Maximum number of particles analyzed in a single frame. Used to ensure spatial representation of the analyzed sample.

Type:

int

max_spectra_per_par

Maximum number of spot X-ray spectra collected in a single particle. Limiting this ensures more particles are analyzed.

Type:

int

max_area_par

Maximum area (in µm²) for a particle to be considered.

Type:

float

min_area_par

Minimum area (in µm²) for a particle to be considered.

Type:

float

par_mask_margin

Margin (in µm) from particle edge where X-ray spectra should not be collected.

Type:

float

xsp_spots_distance_um

Min distance between X-ray spectrum acquisition points

Type:

float

par_segmentation_model

Model to use for particle segmentation. Default: “threshold_bright”

Type:

str

par_brightness_thresh

Intensity threshold in 8-bit image that defines a particle over a dark background.

Type:

int

par_xy_spots_thresh

Intensity threshold in 8-bit image that defines bright (i.e., thickest) regions in particles. X-ray spectra are acquired only from these regions. Particle pixel intensities are scaled to 8-bit prior threhsolding, i.e., darkest pixel will be set to 0, and brightest to 255.

Type:

int

par_feature_selection

‘random’ for random selection of points within bright regions, ‘peaks’ for brightest peak spots (default: ‘random’).

Type:

str

par_spot_spacing

‘random’ for unbiased spot selecton, ‘maximized’ for maximized spot spacing over particle (default: ‘random’).

Type:

str

par_spot_selection_mode

‘auto’ for built-in spot selection, ‘callback’ to supply spots via xsp_spot_selector (default: ‘auto’).

Type:

str

DEFAULT_PAR_SEGMENTATION_MODEL: ClassVar[str] = 'threshold_bright'

AVAILABLE_SPOT_SELECTION_MODES: ClassVar[Tuple[str, ...]] = ('auto', 'callback')

AVAILABLE_PAR_SELECTION: ClassVar[Tuple[str, ...]] = ('auto', 'manual', 'list')

par_selection_mode: Literal['auto', 'manual', 'list']

img_shift_tracking: bool

par_search_frame_width_um: float | None

max_n_par_per_frame: int

max_spectra_per_par: int

max_area_par: float

min_area_par: float

par_mask_margin: float

xsp_spots_distance_um: float

par_spot_selection_mode: Literal['auto', 'callback']

par_segmentation_model: str

par_brightness_thresh: int

par_xy_spots_thresh: int

par_feature_selection: str

par_spot_spacing: str

AVAILABLE_PAR_SEGMENTATION_MODELS: ClassVar[List[str]] = ['threshold_bright', 'Rettenberger2024']

AVAILABLE_FEATURE_SELECTION: ClassVar[Tuple[str, ...]] = ('random', 'peaks')

AVAILABLE_SPOT_SPACING_SELECTION: ClassVar[Tuple[str, ...]] = ('random', 'maximized')

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class autoemx.config.runtime_configs.BulkMeasurementConfig(*, grid_spot_spacing_um: float = 100.0, min_xsp_spots_distance_um: float = 5.0, image_frame_width_um: float | None = None, randomize_frames: bool = False, exclude_sample_margin: bool = False)

Bases: BaseModel

Configuration for characterization or bulk-like samples.

grid_spot_spacing_um

Distance between grid points to measure, in micrometers (µm).

Type:

float

min_xsp_spots_distance_um

Offset distance for acquisition spot grid if the original grid does not contain enough spots to measure the required number of spectra, in micrometers (µm).

Type:

float

image_frame_width_um

Width of the image frame in micrometers (µm). If not specified, defaults to 10 × grid_spot_spacing_um.

Type:

float, optional

randomize_frames

Whether to randomize the order of spectra acquisition in the constructed grid.

Type:

bool

exclude_sample_margin

Whether to exclude the margin of the sample (useful if contaminated).

Type:

bool

grid_spot_spacing_um: float

min_xsp_spots_distance_um: float

image_frame_width_um: float | None

randomize_frames: bool

exclude_sample_margin: bool

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class autoemx.config.runtime_configs.ExpStandardsConfig(*, is_exp_std_measurement: bool = False, formula: str = '', els_to_use_for_mean_PB_calc: ~typing.List[str] | None = ['all'], generate_separate_std_dict: bool = False, min_acceptable_PB_ratio: float = 10, quant_flags_accepted: ~typing.List[int] = <factory>)

Bases: BaseModel

Configuration for the collection of experimental standards.

is_exp_std_measurement

Whether the configuration corresponds to the measurement of an experimental standard (Default = False) If True, a valid formula must be provided and weight fractions will be automatically calculated.

Type:

bool

formula

Chemical formula of the experimental standard. Required if is_exp_std_measurement is True. Must be parseable by pymatgen.core.Composition.

Type:

str

els_to_use_for_mean_PB_calc

List of element symbols (e.g., [“Fe”, “O”]) to use for mean PB calculation. Special values:

[“all”] or [“All”]: use all elements/lines as standards (default) None, [], [“none”], or [“None”]: use no elements/lines

Type:

Optional[List[str]]

generate_separate_std_dict

Whether the acquired reference standard values are added to the current reference dictionary. If True, copies the current standard dictionary to the project folder and updates it. If such .json file is already present in the project folder, then it updates it. This is generally used when measuring the extent of the intermixing of known phases (samples quantified with QuantificationOptionsConfig.is_known_phase_mixture = True).

Type:

bool

min_acceptable_PB_ratio

Minimum PB ratio required for a peak to be accepted as a standard. in cnts/cnts*keV^-1 (Default = 10).

Type:

float

quant_flags_accepted

List of quantification flags considered acceptable. Other spectra are filtered out before clustering. See the user documentation page “Quantification flags (quant_flag)” for the meaning of each value. Common defaults are [0] (experimental standards) or [0, -1] (analysis workflows).

Type:

List[int]

Raises:

ValueError – If is_exp_std_measurement is True but formula is missing or invalid.

is_exp_std_measurement: bool

formula: str

els_to_use_for_mean_PB_calc: List[str] | None

generate_separate_std_dict: bool

min_acceptable_PB_ratio: float

quant_flags_accepted: List[int]

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

formula_w_frs() → Dict[str, float] | None

Mass fractions of the standard computed from its formula, or None if no formula is set.

The standard’s composition is stored in SampleConfig.w_frs, which is set from this value.

class autoemx.config.runtime_configs.PlotConfig(*, show_unused_comps_clust: bool = True, els_excluded_clust_plot: List[str] = <factory>, els_to_plot: List[str] = <factory>, show_legend_clustering: bool = True, save_plots: bool = True, show_plots: bool = False, use_custom_plots: bool = False, custom_plot_file: str | None = None, plot_best_mixture: bool = True, intermixing_violin_plots: bool | None = None)

Bases: BaseModel

Configuration for plotting.

show_unused_comps_clust

Whether to plot unused data points in clustering plot.

Type:

bool

els_excluded_clust_plot

Elements to exclude in cluster plot when more than 3 elements are present.

Type:

List[str]

els_to_plot

Elements forced onto the clustering plot axes (opposite of els_excluded_clust_plot). When non-empty, these elements are kept and the final axes must contain exactly 2 or 3 elements.

Type:

List[str]

show_legend_clustering bool

Whether to show the legend in the clustering plot. Default: True

save_plots

Whether to save plots to disk.

Type:

bool

show_plots

Whether to display plots interactively.

Type:

bool

use_custom_plots

Whether to use custom plotting routines.

Type:

bool

custom_plot_file

Path to a user-editable custom plotting file.

Type:

Optional[str]

plot_best_mixture

Whether to plot the top-ranked mixture of each cluster, when it combines 2 or 3 candidate phases (Mixture_plot_cl<i>.png). Default: True

Type:

bool

intermixing_violin_plots

Whether to plot the intermixing of the phases of the reported mixtures as violin plots (Mixture_decomposition_plot_cl<i>_*.png). If None (default), they are plotted for samples quantified as known phase mixtures (QuantificationOptionsConfig.is_known_phase_mixture).

Type:

Optional[bool]

show_unused_comps_clust: bool

els_excluded_clust_plot: List[str]

els_to_plot: List[str]

show_legend_clustering: bool

save_plots: bool

show_plots: bool

use_custom_plots: bool

custom_plot_file: str | None

plot_best_mixture: bool

intermixing_violin_plots: bool | None

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].