xcal

Functions:

Estimate(energies)

The Estimate class provides a structured approach for parameter estimation by separating input arguments into data and optimization domains, thereby reducing duplicate input.

Material(formula, density)

A class to store chemical formula and density.

calc_forward_matrix(homogenous_vol_masks, ...)

Calculate the forward matrix for a combination of multiple solid objects using a given forward projector.
class xcal.Estimate(energies)[source]

Bases: object

The Estimate class provides a structured approach for parameter estimation by separating input arguments into data and optimization domains, thereby reducing duplicate input. The Estimate class provides estimation of both discrete and continuous parameters within a unified framework.

Parameters:

energies (numpy.ndarray) – X-ray energies of a poly-energetic source in units of keV.

add_data(nrad, forward_matrix, component_models, weight=None)[source]

Add data for parameter estimation, which allows adding multiple datasets scanned with different X-ray system setting.

Parameters:

  • nrad (numpy.ndarray) – Normalized radiograph with dimensions [N_views, N_rows, N_cols].

  • forward_matrix (numpy.ndarray) – Forward matricx corresponds to nrad with dimensions [N_views, N_rows, N_cols, N_energiy_bins]. We provide xcal.calc_forward_matrix.rst to calculate a forward matrix from a 3D mask for a homogenous object.

  • component_models (object) – An instance of Base_Spec_Model.

  • weight (numpy.ndarray) – Weight corresponds to the normalized radiograph.

Returns:

fit(learning_rate=0.001, max_iterations=5000, stop_threshold=0.0001, optimizer_type='Adam', loss_type='transmission', logpath=None, num_processes=1)[source]

Estimate both discrete and continuous parameters.

Parameters:

  • learning_rate (float, optional) – [Default=0.001] Learning rate for the optimization process.

  • max_iterations (int, optional) – [Default=5000] Maximum number of iterations for the optimization.

  • stop_threshold (float, optional) – [Default=1e-4] Scalar valued stopping threshold in percent. If stop_threshold=0.0, then run max iterations.

  • optimizer_type (str, optional) – [Default=’Adam’] Type of optimizer to use. If we do not have accurate initial guess use ‘Adam’, otherwise, ‘NNAT_LBFGS’ can provide a faster convergence.

  • loss_type (str, optional) – [Default=’transmission’] Calculate loss function in ‘transmission’ or ‘attenuation’ space.

  • logpath (optional) – [Default=None] Path for logging, if required.

  • num_processes (int, optional) – [Default=1] Number of processes to use for parallel computation.

Returns:

get_spec_models()[source]

Obtain optimized spectral models.

Returns:

A list of compenent lists. Each compenent list contains all used components to scan the corresponding radiograph.

Return type:

list

get_spectra()[source]

Obtain optimized system responses corresponding to list of added nrad.

Returns:

A list of system responses.

Return type:

list

get_params()[source]

Read estimated parameters as a dictionary.

Returns:

Dictionary containing estimated parameters.

Return type:

dict

get_all_estimates()[source]

Generates a list of tuples, each containing a combination of discrete and continuous parameters. This function explores all possible combinations of given parameters to facilitate comprehensive analysis or optimization tasks.

Each tuple in the list comprises three elements: 1. Stopped iterations: The number of iterations after which the evaluation stopped. 2. Cost value: The cost or objective function value associated with the parameter combination. 3. A dictionary of estimated parameters: Keys are parameter names, and values are the corresponding discrete or continuous values for that combination.

Returns:

A list of tuples, each representing a unique combination of parameters and their evaluation metrics.

Return type:

List[Tuple[int, float, Dict[str, Union[int, float]]]]

class xcal.Material(formula, density)[source]

Bases: object

A class to store chemical formula and density.

Parameters:

  • formula (str) – Chemical formula

  • density (float) – Material density g/cm³

xcal.calc_forward_matrix(homogenous_vol_masks, lac_vs_energies, forward_projector, slices=None)[source]

Calculate the forward matrix for a combination of multiple solid objects using a given forward projector.

Parameters:

  • homogenous_vol_masks (list of numpy.ndarray) – Each 3D array in the list represents a mask for a homogenous, pure object.

  • lac_vs_energies (list of numpy.ndarray) – Each 1D array contains the linear attenuation coefficient (LAC) curve and the corresponding energies for the materials represented in homogenous_vol_masks.

  • forward_projector (object) – An instance of a class that implements a forward projection method. This instance should have a method, forward(mask), that takes a 3D volume mask as input and computes the photon’s line path length.

  • slices (tuple of slice objects, optional) – Slices to apply to the forward projection output to reduce memory usage. Each element in the tuple corresponds to a dimension of the 3D volume output of the forward_projector (views, rows, and columns), and specifies the portion of the data to include in the calculation. If not provided, the entire volume will be used.

Returns:

The calculated forward matrix for spectral estimation. This matrix represents the exponential attenuation of photons through the combined materials, with dimensions corresponding to the input volumes and the energy levels specified in lac_vs_energies.

Return type:

numpy.ndarray

xcal.get_filter_response(energies, mat, den, thickness)[source]

Calculates the filter response for a specified material, density, and thickness.

Parameters:

  • energies (numpy.ndarray) – 1D array of energy values (in keV) at which to calculate the filter response.

  • mat (str) – Chemical formula of the filter material (e.g., ‘Al’ for aluminum).

  • den (float) – Density of the filter material in g/cm³.

  • thickness (float) – Thickness of the filter in mm.

Returns:

Array containing the filter response at each specified energy as a numpy array.

Return type:

numpy.ndarray

xcal.get_scintillator_response(energies, mat, den, thickness)[source]

Calculates the scintillator response for a specified material, density, and thickness.

Parameters:

  • energies (numpy.ndarray) – 1D array of energy values (in keV) at which to calculate the scintillator response.

  • mat (str) – Chemical formula of the scintillator material (e.g., ‘Al’ for aluminum).

  • den (float) – Density of the scintillator material in g/cm³.

  • thickness (float) – Thickness of the scintillator in mm.

Returns:

Array containing the filter response at each specified energy as a numpy array.

Return type:

numpy.ndarray