mapstorch 0.0.1

A differentiable modeling package for automating X-ray fluorescence (XRF) analysis

MapsTorch

MapsTorch is a differentiable modeling package for automating X-ray fluorescence (XRF) analysis. It combines the physics-based MAPS model with PyTorch's automatic differentiation framework.

Key features:

• Automated parameter optimization for XRF spectrum fitting
• Automatic element detection and decision support
• GPU acceleration support for spectrum volume fitting
• Integration with existing XRF-Maps workflows

See extended abstract from M&M 2024.

Get Started

Latest development version:

pip install git+https://github.com/xyin-anl/MapsTorch.git

Latest release version:

pip install mapstorch

Optional: For GPU acceleration of spectra volume fitting, install PyTorch with CUDA support following https://pytorch.org/get-started/locally/

Prepare Data

MapsTorch works with HDF5 files produced by XRFMaps. The HDF5 file must contain:

• Spectra volume data in MAPS/mca_arr group
• Integrated spectra array in MAPS/int_spec group

An example dataset is provided in the assets folder. We recommend using H5Web to view HDF5 files.

For numpy array data, use the create_dataset function in mapstorch.io:

def create_dataset(
    spec_vol,
    energy_dim,
    output_path,
    fit_elems=None,
    dtype=np.float32,
    compression="gzip",
    compression_opts=4,
):
    """Create an HDF5 file compatible with read_dataset function.

    Args:
        spec_vol: 3D numpy array or path to .npy file containing spectral volume
        energy_dim: Which dimension (0,1,2) contains the energy channels
        output_path: Path where to save the HDF5 file
        fit_elems: Optional list of element names
        dtype: numpy dtype for data storage (e.g. np.float32, np.float16). Default: np.float32
        compression: Compression filter to use. Options: 'gzip', 'lzf', None. Default: 'gzip'
        compression_opts: Compression settings. For 'gzip', this is the compression level (0-9). Default: 4
    """

Interactive Apps

We provide marimo notebooks in the apps folder that can be run as web apps (download the notebooks and run them in a Python environment with mapstorch installed):

Guess elements:

marimo run guess_elements.py

Optimize parameters:

marimo run optimize_parameters.py

Example Scripts

The scripts folder contains example scripts like fit_spec.py for fitting integrated spectra. Usage:

python fit_spec.py DATASET.h5 -e 12.0

For all options:

python scripts/fit_spec.py -h

Contact

• Bug reports and feature requests: Open GitHub Issues
• Contributions: Fork repository, create branch, submit pull request
• XRF analysis help: Contact [e-mail] or [e-mail]

Acknowledgement

This research used resources of the Advanced Photon Source, an U.S. Department of Energy (DOE) Office of Science User Facility operated for the DOE Office of Science by Argonne National Laboratory under Contract No. DE-AC02-06CH11357. The authors acknowledge funding support from Argonne LDRD 2023-0049.