plagioclase 1.0.0

For modeling diffusion in plagioclase

plag — diffusion modeling in plagioclase

A Python library for building and running trace-element diffusion models in plagioclase feldspar.

For complete documentation please see vsc.code-pages.usgs.gov/petro/tools/plag.

docs only available on internal USGS network for now, but will be made public in the future

Motivation

Diffusion chronometry in plagioclase is a powerful tool for constraining the timescales of magmatic processes. It is fairly ubiquitous in igneous systems, crystallizing over a wide range of $P-T-X-fO_2$ conditions, and has chronometers that span orders of magnitude allowing for the quantification of a range of timescales (i.e., days - millennia). Furthermore, many parameters to help aid in petrologic investigations (partition coefficients for calculating melt composition proxies) and diffusion studies (diffusion coefficients) can be calculated by only having knowledge of the plagioclase composition, temperature, and basic melt composition, making it a powerful tool in the petrologist toolkit. This, however, is where the fun seemingly ends. While these observations are incredibly useful, their numerical implementation is not exactly straightforward, and setting up forward diffusion models involves many interrelated steps: choosing partitioning and diffusivity models, constructing initial profiles, running finite-difference simulations, and propagating analytical and temperature uncertainties through Monte Carlo resampling.

plag wraps this entire workflow into a single, coherent API so that you can focus on the science rather than the bookkeeping.

Goals

1. Provide a structured, reproducible workflow for calculations involving trace-element diffusion modeling in plagioclase.
2. Make it easy to compare different partitioning and diffusivity parameterisations from the literature.
3. Propagate uncertainties rigorously via Monte Carlo methods with random sampling that incorporates the covariance structure of the data that determines all the parameters utilized in the random sampling (e.g., $RT\ln{K_d} = A(\pm \sigma_A)\cdot X_{An} + B(\pm \sigma_B)$).
4. Take advantage of numba accelerated finite-difference solvers for fast forward modeling on a standard personal computer.

Installation

It is recommended to do this in a fresh virtual environment:

# Create a virtual environment (conda example)
conda create -n diffusion-modeling python=3.13
conda activate diffusion-modeling

# Install from PyPI
pip install plagioclase

# Install from source
git clone https://code.usgs.gov/vsc/petro/tools/plag.git
cd plag
pip install .

For development (includes pytest, pytest-cov, ruff):

pip install -e ".[dev]"

Citation

If you use plag in your research, please cite it:

Lubbers, J. (2026) plag, version 1.0.0: U.S. Geological Survey software release https://doi.org/10.5066/P13OEK4A

To do

See todo.md for the full list of outstanding work items, each annotated with implementation guidance.