mapstorch 0.0.2

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:

• Parameter optimization for XRF spectrum fitting
• Element selection decision support
• Integration with existing XRF-Maps workflows

See paper for technical details.

Get Started

Python 3.10 or newer is required. The core engine supports NumPy 2 and needs only NumPy, PyTorch, h5py, and tqdm:

pip install mapstorch

Optional tools are available as extras:

pip install 'mapstorch[plot]'    # Matplotlib plots and SciencePlots styles
pip install 'mapstorch[widget]'  # Notebook widgets
pip install 'mapstorch[apps]'    # Apps and scripts, including plots and widgets
pip install 'mapstorch[all]'     # All optional tools

Develop with Pixi

We keep the development environment reproducible with Pixi. Once Pixi is installed:

1. Resolve the environment: pixi install
2. Enter the shell: pixi shell
3. Install MapsTorch in editable mode: pixi run install

After that you can run examples or scripts in the Pixi shell, e.g. python scripts/fit_spec.py -h or marimo run apps/guess_elements.py.

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

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

If you have an override parameters file:

python fit_spec.py DATASET.h5 -e 12.0 --override_params_file parameters_override.txt

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 xyin@anl.gov or aglowacki@anl.gov

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.