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

Dict of elemental mass fractions to be kept fixed (e.g., {‘Fe’: 0.4, ‘O’: 0.6}). Normally not used

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 save the non-annotated SEM image.

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

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)

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

method: str

spectrum_lims: Tuple[float, float]

fit_tolerance: float

use_instrument_background: bool

use_project_specific_std_dict: bool

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'] = 'auto', is_known_powder_mixture_meas: bool = False, 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

‘auto’ for automatic particle navigation, ‘manual’ to prompt user to center each particle (default: ‘auto’).

Type:

str

is_known_powder_mixture_meas

Whether sample is a known binary mixture of powders. Used to characterize precursor extent of intermixing (Default = False).

Type:

bool

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')

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

is_known_powder_mixture_meas: bool

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>, w_frs: ~typing.Dict[str, float] | None = None)

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 powder precursor intermixing (i.e., powder_meas_cfg_kwargs[“is_known_powder_mixture_meas”] = 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. Quantification flags indicate whether the quantification or the fit of each spectrum is likely to be affected by large errors:

• 0 : Quantification is ok, although it may be affected by large analytical error.

• -1

  : As above, but quantification did not converge within 30 steps.

• 1 : Error during EDS acquisition. No fit executed.

2Total counts < 90% of target counts, likely due to wrong segmentation. Fit interrupted if interrupt_fits_bad_spectra=True.

• 3 : Too little low-energy signal, causing poor quantification in that region. Fit interrupted if interrupt_fits_bad_spectra=True.

• 4 : Poor fit. Fit interrupted if interrupt_fits_bad_spectra=True.

• 5 : High analytical error (>50%), possibly due to missing element or other major error. Fit interrupted if interrupt_fits_bad_spectra=True.

• 6 : Excessive X-ray absorption. Fit interrupted if interrupt_fits_bad_spectra=True.

• 7 : Excessive contamination from substrate.

• 8 : Too few background counts below reference peak, likely leading to large quantification errors.

• 9 : Unknown fitting error.

• 10 : (Only for measurement of experimental standards) Reference peak missing.

Type:

List[int]

w_frs

Dictionary of element symbols and their corresponding weight fractions (computed via pymatgen) if is_exp_std_measurement is True and formula is valid; otherwise None.

Type:

Optional[Dict[str, float]]

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]

w_frs: Dict[str, float] | None

model_config = {'extra': 'forbid'}

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

class autoemx.config.runtime_configs.PlotConfig(*, show_unused_comps_clust: bool = True, els_excluded_clust_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)

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]

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]

show_unused_comps_clust: bool

els_excluded_clust_plot: List[str]

show_legend_clustering: bool

save_plots: bool

show_plots: bool

use_custom_plots: bool

custom_plot_file: str | None

model_config = {'extra': 'forbid'}

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