plagioclase 1.0.0__tar.gz

plagioclase-1.0.0/.gitignore

@@ -0,0 +1,62 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing / coverage
+.pytest_cache/
+.test_output/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+
+# Jupyter
+.ipynb_checkpoints/
+
+# mypy / type checking
+.mypy_cache/
+.pytype/
+
+# Ruff
+.ruff_cache/
+
+# MkDocs site output
+site/
+
+# tox / nox
+.tox/
+.nox/
+
+# cache files
+.cache
+
+# kiro
+.kiro

plagioclase-1.0.0/LICENSE

@@ -0,0 +1,47 @@
+License
+=======
+
+Unless otherwise noted, This project is in the public domain in the United
+States because it contains materials that originally came from the United
+States Geological Survey, an agency of the United States Department of
+Interior. For more information, see the official USGS copyright policy at
+https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits
+
+Additionally, we waive copyright and related rights in the work
+worldwide through the CC0 1.0 Universal public domain dedication.
+
+
+CC0 1.0 Universal Summary
+-------------------------
+
+This is a human-readable summary of the
+[Legal Code (read the full text)][1].
+
+
+### No Copyright
+
+The person who associated a work with this deed has dedicated the work to
+the public domain by waiving all of his or her rights to the work worldwide
+under copyright law, including all related and neighboring rights, to the
+extent allowed by law.
+
+You can copy, modify, distribute and perform the work, even for commercial
+purposes, all without asking permission.
+
+
+### Other Information
+
+In no way are the patent or trademark rights of any person affected by CC0,
+nor are the rights that other persons may have in the work or in how the
+work is used, such as publicity or privacy rights.
+
+Unless expressly stated otherwise, the person who associated a work with
+this deed makes no warranties about the work, and disclaims liability for
+all uses of the work, to the fullest extent permitted by applicable law.
+When using or citing the work, you should not imply endorsement by the
+author or the affirmer.
+
+
+
+[1]: https://creativecommons.org/publicdomain/zero/1.0/legalcode
+

plagioclase-1.0.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: plagioclase
+Version: 1.0.0
+Summary: For modeling diffusion in plagioclase
+Project-URL: Homepage, https://vsc.code-pages.usgs.gov/petro/tools/plag
+Project-URL: Repository, https://code.usgs.gov/vsc/petro/tools/plag
+Author-email: Jordan Lubbers <jelubber@gmail.com>
+License: License
+        =======
+        
+        Unless otherwise noted, This project is in the public domain in the United
+        States because it contains materials that originally came from the United
+        States Geological Survey, an agency of the United States Department of
+        Interior. For more information, see the official USGS copyright policy at
+        https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits
+        
+        Additionally, we waive copyright and related rights in the work
+        worldwide through the CC0 1.0 Universal public domain dedication.
+        
+        
+        CC0 1.0 Universal Summary
+        -------------------------
+        
+        This is a human-readable summary of the
+        [Legal Code (read the full text)][1].
+        
+        
+        ### No Copyright
+        
+        The person who associated a work with this deed has dedicated the work to
+        the public domain by waiving all of his or her rights to the work worldwide
+        under copyright law, including all related and neighboring rights, to the
+        extent allowed by law.
+        
+        You can copy, modify, distribute and perform the work, even for commercial
+        purposes, all without asking permission.
+        
+        
+        ### Other Information
+        
+        In no way are the patent or trademark rights of any person affected by CC0,
+        nor are the rights that other persons may have in the work or in how the
+        work is used, such as publicity or privacy rights.
+        
+        Unless expressly stated otherwise, the person who associated a work with
+        this deed makes no warranties about the work, and disclaims liability for
+        all uses of the work, to the fullest extent permitted by applicable law.
+        When using or citing the work, you should not imply endorsement by the
+        author or the affirmer.
+        
+        
+        
+        [1]: https://creativecommons.org/publicdomain/zero/1.0/legalcode
+        
+License-File: LICENSE
+Keywords: diffusion modeling,geochemistry,plagioclase,trace elements
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: joblib>=1.3
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numba>=0.58
+Requires-Dist: numpy>=1.24
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: tqdm>=4.60
+Provides-Extra: dev
+Requires-Dist: arviz>=0.15; extra == 'dev'
+Requires-Dist: lasertram; extra == 'dev'
+Requires-Dist: pymc>=5.0; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-jupyter; extra == 'docs'
+Requires-Dist: mkdocs-material<10,>=9.7.5; extra == 'docs'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# `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](https://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:
+
+```bash
+# 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):
+
+```bash
+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](todo.md) for the full list of outstanding work items, each annotated with implementation guidance.
+

plagioclase-1.0.0/README.md

@@ -0,0 +1,55 @@
+# `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](https://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:
+
+```bash
+# 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):
+
+```bash
+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](todo.md) for the full list of outstanding work items, each annotated with implementation guidance.
+

plagioclase-1.0.0/pyproject.toml

@@ -0,0 +1,132 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "plagioclase"
+dynamic = ["version"]
+authors = [{name = "Jordan Lubbers", email = "jelubber@gmail.com"}]
+description = "For modeling diffusion in plagioclase"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=1.24",
+    "numba>=0.58",
+    "matplotlib>=3.7",
+    "statsmodels>=0.14",
+    "scipy>=1.10",
+    "pandas>=2.0",
+    "openpyxl>=3.1",
+    "tqdm>=4.60",
+    "joblib>=1.3",
+]
+classifiers = [
+    # How mature is this project? Common values are
+    #   3 - Alpha
+    #   4 - Beta
+    #   5 - Production/Stable
+    "Development Status :: 4 - Beta",
+    "Topic :: Scientific/Engineering",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+
+]
+keywords = ["plagioclase","diffusion modeling","geochemistry","trace elements"]
+
+[project.urls]
+Homepage = "https://vsc.code-pages.usgs.gov/petro/tools/plag"
+Repository = "https://code.usgs.gov/vsc/petro/tools/plag"
+
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+    "ruff",
+    "pymc>=5.0",
+    "arviz>=0.15",
+    "lasertram",
+]
+docs = [
+    "mkdocs>=1.6,<2",
+    "mkdocs-material>=9.7.5,<10",
+    "mkdocstrings[python]",
+    "mkdocs-jupyter",
+]
+
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short -m 'not notebooks'"
+markers = [
+    "slow: computationally expensive tests (solvers, MC, convergence)",
+    "notebooks: end-to-end notebook execution tests (slow, requires docs extras)",
+]
+
+[tool.hatch.version]
+path = "src/plag/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/plag"]
+
+# ── Linting & Formatting ─────────────────────────────────────────────
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+    "NPY", # numpy-specific rules
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+    "B905",   # zip-strict (not needed for scientific code)
+    "SIM108", # ternary operator (readability preference)
+    "SIM102", # collapsible-if (readability preference for guard clauses)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["plag"]
+
+[tool.ruff.lint.per-file-ignores]
+"docs/examples/*.ipynb" = [
+    "E402",   # module-level import not at top of cell (normal in notebooks)
+    "E741",   # ambiguous variable name 'l' (common loop var for plot labels)
+    "NPY002", # legacy np.random (gradual migration)
+]
+"tests/*" = [
+    "NPY002", # legacy np.random in test fixtures (gradual migration)
+]
+"src/plag/core.py" = [
+    "NPY002", # fallback path for backward compat when no rng passed
+]
+
+[tool.ruff.format]
+quote-style = "double"
+
+# ── Coverage ─────────────────────────────────────────────────────────
+[tool.coverage.run]
+source = ["plag"]
+
+[tool.coverage.report]
+show_missing = true
+omit = ["tests/*"]
+

plagioclase-1.0.0/src/plag/__init__.py

@@ -0,0 +1,120 @@
+"""
+plag — diffusion modelling in plagioclase.
+
+A Python toolkit for trace-element diffusion chronometry in
+plagioclase feldspar.  Provides diffusivity parameterisations,
+partitioning models, explicit finite-difference solvers, and
+Monte-Carlo uncertainty propagation.
+"""
+
+import logging
+
+__version__ = "1.0.0"
+
+# Bundled experimental data (lazy submodule)
+from . import experimental_data
+
+# Core utilities
+from .core import (
+    cl_to_cs,
+    cs_to_cl,
+    cs_to_rtlncl,
+    fit_model,
+    linear_regression_with_uncertainty,
+    make_tgrid,
+    random_profile,
+    rtlncl_to_cs,
+)
+
+# Diffusion coefficients
+from .diffusivities import (
+    cherniak_watson_diffusivity,
+    cherniak_watson_diffusivity_random,
+    costa_diffusivity,
+    faak_diffusivity,
+    faak_diffusivity_random,
+    giletti_casserly_diffusivity,
+    giletti_casserly_diffusivity_druitt,
+    giletti_diffusivity_random,
+    grocolas_diffusivity,
+    grocolas_diffusivity_random,
+    van_orman_diffusivity,
+    van_orman_diffusivity_random,
+)
+
+# Example datasets
+from .example_data import load_example_data
+
+# Main model class
+from .model import PlagDiffusionModel
+
+# Partitioning / Kd models
+from .partitioning import (
+    bindeman_kd_calc,
+    dohmen_activity_calc,
+    dohmen_kd_calc,
+    dohmen_kd_calc_lepr,
+    generate_random_activities,
+    mutch_A_calc,
+    mutch_B_calc,
+    mutch_kd_calc,
+    plag_activity_calc,
+    plag_eq_prof,
+)
+
+# Numerical solvers
+from .solvers import (
+    diffuse_forward_plag,
+    diffuse_forward_plag_cn,
+    diffuse_forward_plag_lazy,
+    diffuse_forward_plag_lazy_cn,
+)
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    # core
+    "fit_model",
+    "make_tgrid",
+    "random_profile",
+    "linear_regression_with_uncertainty",
+    "cs_to_rtlncl",
+    "rtlncl_to_cs",
+    "cs_to_cl",
+    "cl_to_cs",
+    # diffusivities
+    "faak_diffusivity",
+    "faak_diffusivity_random",
+    "van_orman_diffusivity",
+    "costa_diffusivity",
+    "giletti_casserly_diffusivity",
+    "giletti_casserly_diffusivity_druitt",
+    "cherniak_watson_diffusivity",
+    "cherniak_watson_diffusivity_random",
+    "grocolas_diffusivity",
+    "giletti_diffusivity_random",
+    "grocolas_diffusivity_random",
+    "van_orman_diffusivity_random",
+    # partitioning
+    "bindeman_kd_calc",
+    "dohmen_kd_calc",
+    "dohmen_kd_calc_lepr",
+    "mutch_kd_calc",
+    "mutch_A_calc",
+    "mutch_B_calc",
+    "plag_activity_calc",
+    "dohmen_activity_calc",
+    "plag_eq_prof",
+    "generate_random_activities",
+    # solvers
+    "diffuse_forward_plag",
+    "diffuse_forward_plag_cn",
+    "diffuse_forward_plag_lazy",
+    "diffuse_forward_plag_lazy_cn",
+    # model
+    "PlagDiffusionModel",
+    # example data
+    "load_example_data",
+    # experimental data
+    "experimental_data",
+]