MatRiFFlow 2.0.1__tar.gz

matrifflow-2.0.1/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2024-2026 Inverse Materials Design Group
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

matrifflow-2.0.1/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: MatRiFFlow
+Version: 2.0.1
+Summary: Pymatgen add-ons and cluster job-submission tools for the Inverse Materials Design group (formerly IMDgroup-pymatgen)
+Author-email: Ihor Radchenko <yantar92@posteo.net>, "Oleksandr I. Malyi" <oleksandrmalyi@gmail.com>
+License-Expression: MIT
+Project-URL: homepage, https://yantar92.github.io/MatRiFFlow/
+Keywords: crystal,materials,science,structure,VASP,pymatgen,cluster,MACE,slurm,ase
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Clustering
+Requires-Python: <3.14,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: pymatgen
+Requires-Dist: alive_progress==3.3.0
+Requires-Dist: ase>=3.23.0
+Requires-Dist: termcolor
+Requires-Dist: rich
+Requires-Dist: pandas
+Requires-Dist: python-dateutil
+Requires-Dist: pytimeparse
+Requires-Dist: scikit-learn
+Requires-Dist: networkx
+Requires-Dist: cachetools
+Requires-Dist: duecredit>=0.11
+Requires-Dist: lmdb
+Requires-Dist: typing-extensions
+Provides-Extra: dev
+Requires-Dist: pyright; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+Requires-Dist: autodocsumm>=0.2; extra == "docs"
+Requires-Dist: myst-parser>=2.0; extra == "docs"
+Requires-Dist: sphinxcontrib-mermaid>=0.7; extra == "docs"
+Provides-Extra: mace
+Requires-Dist: mace-torch; extra == "mace"
+Requires-Dist: torch; extra == "mace"
+Dynamic: license-file
+
+
+
+# MatRiFFlow (formerly IMDgroup-pymatgen)
+
+Python and command-line tools for **iterative development of
+computational workflows** for VASP atomistic simulations, built on top
+of [pymatgen](https://pymatgen.org/).
+
+Works with ordinary calculation directories produced manually, by scripts,
+or by **any existing workflow tooling that writes standard VASP files**.
+The independent commands do not require a workflow manager or prescribe
+how jobs must be executed.
+
+Also includes `gorun`, a cluster-agnostic job-submission script for VASP,
+MACE fine-tuning, ATAT, and generic GPU jobs on Slurm clusters.
+
+Documentation: <https://yantar92.github.io/MatRiFFlow/>
+
+![img](docs/img/workflow-development.svg)
+
+`mrf` can handle large collections of calculations (including
+running) and detect anomalies or incomparable results.  It
+deliberately **does not automate fixing anomalies**, leaving it up to
+the user to explore the problems and identify the solutions (with the
+optional help of `mrf` tooling).
+
+
+## Workflow manager compatibility
+
+`mrf` operates directly on standard VASP directory trees without a
+workflow manager-specific database or import. It can complement manual
+calculations, custom scripts, and existing workflow managers.
+
+`mrf analyze` groups runs by identical settings, `mrf diff` compares
+INCAR settings and structures, and `mrf analyze` provides calculation
+summaries.
+
+
+## High-throughput optimization
+
+`mrf` can handle directory trees containing **thousands of
+calculations**. Parsing VASP outputs (XML, OUTCAR) is costly on
+supercomputer file systems, so the tools cache parsed results on disk
+(with invalidation if the original data changes).
+
+See the [Python API](https://yantar92.github.io/MatRiFFlow/python_api.html) for `MRFVaspDir`, the class providing cached
+directory inspection.
+
+
+## Installation
+
+    git clone https://github.com/yantar92/MatRiFFlow
+    cd MatRiFFlow
+    pip install .
+
+This installs the `mrf` and `gorun` commands.
+
+Note: the `lmdb` dependency (on-disk result cache) links against the
+native LMDB library. On some systems &ndash; especially HPC clusters &ndash; you
+must provide it before `pip install .`, for example `module load lmdb`
+or the system dev package (`apt install liblmdb-dev`,
+`dnf install lmdb-devel`). If the build fails while compiling `lmdb`,
+load the module and re-run `pip install .`.
+
+
+## Next steps
+
+-   [Quickstart](https://yantar92.github.io/MatRiFFlow/quickstart.html): example graphite (mp-48) workflow
+-   [Why this exists](https://yantar92.github.io/MatRiFFlow/concepts.html): semi-automated workflow development
+-   [Command-line reference](https://yantar92.github.io/MatRiFFlow/cli.html) and [job submission](https://yantar92.github.io/MatRiFFlow/gorun.html)
+-   [Python API](https://yantar92.github.io/MatRiFFlow/python_api.html)
+
+
+## Contributing
+
+Contributions are welcome.
+
+-   Report bugs and propose features by opening an [issue](https://github.com/yantar92/MatRiFFlow/issues).
+-   Ask questions and discuss design in [GitHub Discussions](https://github.com/yantar92/MatRiFFlow/discussions).
+-   Submit changes as [pull requests](https://github.com/yantar92/MatRiFFlow/pulls).
+
+You can also contact the maintainer directly by email
+(`yantar92@posteo.net`) or on GitHub.
+

matrifflow-2.0.1/README.md

@@ -0,0 +1,84 @@
+
+
+# MatRiFFlow (formerly IMDgroup-pymatgen)
+
+Python and command-line tools for **iterative development of
+computational workflows** for VASP atomistic simulations, built on top
+of [pymatgen](https://pymatgen.org/).
+
+Works with ordinary calculation directories produced manually, by scripts,
+or by **any existing workflow tooling that writes standard VASP files**.
+The independent commands do not require a workflow manager or prescribe
+how jobs must be executed.
+
+Also includes `gorun`, a cluster-agnostic job-submission script for VASP,
+MACE fine-tuning, ATAT, and generic GPU jobs on Slurm clusters.
+
+Documentation: <https://yantar92.github.io/MatRiFFlow/>
+
+![img](docs/img/workflow-development.svg)
+
+`mrf` can handle large collections of calculations (including
+running) and detect anomalies or incomparable results.  It
+deliberately **does not automate fixing anomalies**, leaving it up to
+the user to explore the problems and identify the solutions (with the
+optional help of `mrf` tooling).
+
+
+## Workflow manager compatibility
+
+`mrf` operates directly on standard VASP directory trees without a
+workflow manager-specific database or import. It can complement manual
+calculations, custom scripts, and existing workflow managers.
+
+`mrf analyze` groups runs by identical settings, `mrf diff` compares
+INCAR settings and structures, and `mrf analyze` provides calculation
+summaries.
+
+
+## High-throughput optimization
+
+`mrf` can handle directory trees containing **thousands of
+calculations**. Parsing VASP outputs (XML, OUTCAR) is costly on
+supercomputer file systems, so the tools cache parsed results on disk
+(with invalidation if the original data changes).
+
+See the [Python API](https://yantar92.github.io/MatRiFFlow/python_api.html) for `MRFVaspDir`, the class providing cached
+directory inspection.
+
+
+## Installation
+
+    git clone https://github.com/yantar92/MatRiFFlow
+    cd MatRiFFlow
+    pip install .
+
+This installs the `mrf` and `gorun` commands.
+
+Note: the `lmdb` dependency (on-disk result cache) links against the
+native LMDB library. On some systems &ndash; especially HPC clusters &ndash; you
+must provide it before `pip install .`, for example `module load lmdb`
+or the system dev package (`apt install liblmdb-dev`,
+`dnf install lmdb-devel`). If the build fails while compiling `lmdb`,
+load the module and re-run `pip install .`.
+
+
+## Next steps
+
+-   [Quickstart](https://yantar92.github.io/MatRiFFlow/quickstart.html): example graphite (mp-48) workflow
+-   [Why this exists](https://yantar92.github.io/MatRiFFlow/concepts.html): semi-automated workflow development
+-   [Command-line reference](https://yantar92.github.io/MatRiFFlow/cli.html) and [job submission](https://yantar92.github.io/MatRiFFlow/gorun.html)
+-   [Python API](https://yantar92.github.io/MatRiFFlow/python_api.html)
+
+
+## Contributing
+
+Contributions are welcome.
+
+-   Report bugs and propose features by opening an [issue](https://github.com/yantar92/MatRiFFlow/issues).
+-   Ask questions and discuss design in [GitHub Discussions](https://github.com/yantar92/MatRiFFlow/discussions).
+-   Submit changes as [pull requests](https://github.com/yantar92/MatRiFFlow/pulls).
+
+You can also contact the maintainer directly by email
+(`yantar92@posteo.net`) or on GitHub.
+

matrifflow-2.0.1/pyproject.toml

@@ -0,0 +1,127 @@
+[build-system]
+requires = ["setuptools >= 61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "MatRiFFlow"
+version = "2.0.1"
+description = "Pymatgen add-ons and cluster job-submission tools for the Inverse Materials Design group (formerly IMDgroup-pymatgen)"
+authors = [ {name = "Ihor Radchenko", email = "yantar92@posteo.net"},
+            {name = "Oleksandr I. Malyi", email = "oleksandrmalyi@gmail.com"} ]
+license = "MIT"
+readme = {file = "README.md", content-type = "text/markdown"}
+keywords = ["crystal", "materials", "science", "structure", "VASP", "pymatgen", "cluster", "MACE", "slurm", "ase"]
+classifiers = [
+	    "Development Status :: 4 - Beta",
+            "Environment :: Console",
+            "Operating System :: OS Independent",
+            "Programming Language :: Python :: 3.12",
+            "Programming Language :: Python :: 3.13",
+            "Topic :: Scientific/Engineering :: Chemistry",
+            "Topic :: Scientific/Engineering :: Information Analysis",
+            "Topic :: Scientific/Engineering :: Physics",
+            "Topic :: Software Development :: Libraries :: Python Modules",
+            "Topic :: System :: Clustering"]
+requires-python = ">=3.12, <3.14"
+dependencies = [
+"numpy>=1.26.4",
+"pymatgen",
+"alive_progress==3.3.0",
+"ase>=3.23.0",
+"termcolor",
+"rich",
+"pandas",
+"python-dateutil",
+"pytimeparse",
+"scikit-learn",
+"networkx",
+"cachetools",
+"duecredit>=0.11",
+"lmdb",
+"typing-extensions"
+]
+
+[project.urls]
+homepage = "https://yantar92.github.io/MatRiFFlow/"
+
+[project.optional-dependencies]
+dev = ["pyright"]
+test = ["pytest", "pytest-cov"]
+docs = [
+    "sphinx>=7.0",
+    "sphinx-rtd-theme>=2.0",
+    "autodocsumm>=0.2",
+    "myst-parser>=2.0",
+    "sphinxcontrib-mermaid>=0.7",
+]
+mace = [
+    "mace-torch",
+    "torch",
+]
+
+[project.scripts]
+mrf = "matrifflow.pymatgen.cli.mrf:main"
+imdg = "matrifflow.pymatgen.cli.mrf:main_deprecated_imdg"
+gorun = "matrifflow.gorun.gorun:main"
+gorun-mace = "matrifflow.gorun.gorun:main_mace"
+gorun-mace-finetune = "matrifflow.gorun.gorun:main_mace"
+gorun-atat-local = "matrifflow.gorun.gorun_atat_local:main"
+gorun-maps = "matrifflow.gorun.gorun_maps:main"
+
+[tool.setuptools]
+script-files = ["scripts/gorun-all-ready.sh"]
+
+[tool.setuptools.packages.find]
+exclude = ["tests"]
+where = ["src/"]
+include = [
+	"matrifflow.pymatgen",
+	"matrifflow.pymatgen.*",
+        "matrifflow",
+        "matrifflow.*",
+        "IMDgroup",
+        "IMDgroup.*",
+        ]
+
+[tool.setuptools.package-data]
+"matrifflow.pymatgen.io.vasp" = ["*.cif", "*.yaml"]
+"matrifflow.gorun" = ["data/*.toml"]
+
+[tool.pylint]
+source-roots=['./src']
+
+[tool.pyright]
+include = ["src"]
+exclude = ["**/__pycache__", "build", "**/.mypy_cache"]
+typeCheckingMode = "strict"
+pythonPlatform = "Linux"
+
+[tool.coverage.run]
+branch = true
+source = ["matrifflow"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -m 'not heavy' --cov=matrifflow --cov-report=term-missing"
+pythonpath = ["src"]
+filterwarnings = [
+    # Upstream warnings we cannot fix; harmless in tests.
+    "ignore:Casting complex values to real discards the imaginary part:numpy.exceptions.ComplexWarning:pymatgen\\.core\\.operations",
+    # No module field on the next two filters.  pytest.warns() re-emits
+    # every warning it did not match itself with module="warnings" (see
+    # _pytest/recwarn.py), so a module-scoped filter never matches a
+    # warning raised inside a pytest.warns() block.  The POTCAR warning is
+    # also raised with stacklevel=2, which reports the caller's module
+    # instead of pymatgen.io.vasp.outputs.
+    "ignore:No POTCAR file with matching TITEL fields:UserWarning",
+    "ignore:Set OLD_ERROR_HANDLING to false and catch the errors directly:DeprecationWarning",
+    # Emitted outside pytest.warns() blocks, so these stay module-scoped.
+    "ignore:Setting the shape on a NumPy array has been deprecated:DeprecationWarning:ase\\.atoms",
+    # Our own warning, expected noise in integration tests: the fake VASP
+    # fixture has no vdw_kernel.bindat.
+    "ignore:Cannot find vdw_kernel.bindat:UserWarning:matrifflow\\.gorun\\.cleanVASP",
+]
+markers = [
+    "integration: tests that require generated VASP fixtures (see scripts/prepare_vasp_fixtures.sh)",
+    "heavy: slow tests, skipped by default (run with pytest -m heavy)",
+]

matrifflow-2.0.1/scripts/gorun-all-ready.sh

@@ -0,0 +1,245 @@
+#!/usr/bin/env bash
+
+# MIT License
+#
+# Copyright (c) 2024-2026 Inverse Materials Design Group
+#
+# Author: Ihor Radchenko <yantar92@posteo.net>
+#
+# This file is a part of MatRiFFlow package
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# gorun-all-ready.sh - Submit pending VASP jobs marked with 'gorun_ready' files
+#
+# This script searches for directories containing a 'gorun_ready' file,
+# waits until the user's Slurm job count drops below a limit, then submits
+# the job with 'sbatch sub' and removes the marker file.
+#
+# Usage: gorun-all-ready.sh [OPTIONS]
+#
+# Options:
+#   -n, --max-jobs NUM   Maximum concurrent Slurm jobs (default: 100)
+#   -d, --directory DIR  Search root directory (default: current directory)
+#   -t, --timeout SEC    Sleep interval between queue checks (default: 5)
+#   -q, --quiet          Do not print extra information
+#   -h, --help           Show this help text
+#
+# Example:
+#   gorun-all-ready.sh -n 20 -d /path/to/projects
+#
+# Exit codes:
+#   0  Success
+#   1  Argument error
+#   2  Missing required command (squeue, sbatch, find)
+#   3  No 'gorun_ready' files found
+#   4  Sub‑mission failure (sbatch returned non‑zero)
+#
+# The script requires a working Slurm environment and the 'sub' script
+# in each target directory.
+
+set -euo pipefail
+
+# ------------------------------------------------------------
+# Configuration and defaults
+# ------------------------------------------------------------
+readonly PROGNAME="${0##*/}"
+readonly VERSION="1.0.0"
+
+MAX_JOBS=100
+SEARCH_DIR="."
+SLEEP_INTERVAL=5
+VERBOSE=true
+
+# ------------------------------------------------------------
+# Utility functions
+# ------------------------------------------------------------
+
+err() {
+    printf "%s: %s\n" "$PROGNAME" "$*" >&2
+}
+
+log() {
+    if "$VERBOSE"; then
+        printf "%s: %s\n" "$PROGNAME" "$*"
+    fi
+}
+
+die() {
+    err "$@"
+    exit 1
+}
+
+usage() {
+    cat <<EOF
+$PROGNAME - Submit pending VASP jobs marked with 'gorun_ready' files
+
+Usage: $PROGNAME [OPTIONS]
+
+Options:
+  -n, --max-jobs NUM   Maximum concurrent Slurm jobs (default: 100)
+  -d, --directory DIR  Search root directory (default: current directory)
+  -t, --timeout SEC    Sleep interval between queue checks (default: 5)
+  -q, --quiet          Do not print extra information
+  -h, --help           Show this help text
+  --version            Show version information
+
+Example:
+  $PROGNAME -n 20 -d /path/to/projects
+
+Exit codes:
+  0  Success
+  1  Argument error
+  2  Missing required command
+  3  No 'gorun_ready' files found
+  4  Submission failure
+EOF
+}
+
+version() {
+    echo "$PROGNAME $VERSION"
+}
+
+# Check that required commands are available
+check_commands() {
+    local cmd
+    for cmd in squeue sbatch find; do
+        if ! command -v "$cmd" >/dev/null 2>&1; then
+            die "Required command '$cmd' not found in PATH"
+        fi
+    done
+}
+
+# Count current Slurm jobs for the current user
+# Output: number of jobs (integer)
+get_n_jobs() {
+    # Use -o %Z to get job state column; tail -n +2 skips header line
+    # The count includes pending and running jobs.
+    local count
+    if ! count=$(squeue -u "$USER" -o %Z 2>/dev/null | tail -n +2 | wc -l); then
+        err "squeue failed; assuming 0 jobs"
+        echo 0
+        return 1
+    fi
+    echo "$count"
+}
+
+# ------------------------------------------------------------
+# Argument parsing
+# ------------------------------------------------------------
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -n|--max-jobs)
+            if [[ -z "${2:-}" ]]; then
+                die "Missing argument for $1"
+            fi
+            if [[ ! "$2" =~ ^[0-9]+$ ]]; then
+                die "Max jobs must be a positive integer"
+            fi
+            MAX_JOBS="$2"
+            shift 2
+            ;;
+        -d|--directory)
+            if [[ -z "${2:-}" ]]; then
+                die "Missing argument for $1"
+            fi
+            if [[ ! -d "$2" ]]; then
+                die "Directory '$2' does not exist"
+            fi
+            SEARCH_DIR="$2"
+            shift 2
+            ;;
+        -t|--timeout)
+            if [[ -z "${2:-}" ]]; then
+                die "Missing argument for $1"
+            fi
+            if [[ ! "$2" =~ ^[0-9]+$ ]]; then
+                die "Timeout must be a positive integer"
+            fi
+            SLEEP_INTERVAL="$2"
+            shift 2
+            ;;
+        -q|--quiet)
+            VERBOSE=false
+            shift
+            ;;
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        --version)
+            version
+            exit 0
+            ;;
+        *)
+            die "Unknown option: $1"
+            ;;
+    esac
+done
+
+# ------------------------------------------------------------
+# Main
+# ------------------------------------------------------------
+check_commands
+
+log "Starting with max_jobs=$MAX_JOBS, search_dir=$SEARCH_DIR, sleep=$SLEEP_INTERVAL"
+
+# Collect directories containing gorun_ready
+readarray -t ready_dirs < <(
+    find "$SEARCH_DIR" -type f -name 'gorun_ready' -printf '%h\n' | sort -u
+)
+
+if [[ ${#ready_dirs[@]} -eq 0 ]]; then
+    log "No 'gorun_ready' files found in $SEARCH_DIR"
+    exit 3
+fi
+
+log "Found ${#ready_dirs[@]} directories with gorun_ready"
+
+for dir in "${ready_dirs[@]}"; do
+    log "Processing $dir"
+
+    # Wait until job count drops below limit
+    while [[ $(get_n_jobs) -ge "$MAX_JOBS" ]]; do
+        log "Job count $(get_n_jobs) >= $MAX_JOBS, sleeping $SLEEP_INTERVAL seconds"
+        sleep "$SLEEP_INTERVAL"
+    done
+
+    # Enter directory and submit
+    (
+        cd "$dir" || die "Cannot cd to $dir"
+
+        if [[ ! -f "sub" ]]; then
+            err "Missing 'sub' script in $dir; skipping"
+            exit 0
+        fi
+
+        log "Submitting job in $dir"
+        if sbatch sub; then
+            rm -f gorun_ready
+            log "Submitted and removed gorun_ready in $dir"
+        else
+            err "sbatch failed in $dir; keeping gorun_ready"
+            exit 4
+        fi
+    )
+done
+
+log "All pending jobs submitted"
+exit 0

matrifflow-2.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

matrifflow-2.0.1/src/IMDgroup/__init__.py

@@ -0,0 +1,82 @@
+"""Deprecated compatibility package for the MatRiFFlow rename.
+
+``IMDgroup`` was the import package name before the project was renamed to
+MatRiFFlow (import package ``matrifflow``).  Importing anything under
+``IMDgroup`` emits a :class:`DeprecationWarning` and resolves to the
+corresponding ``matrifflow`` module, so existing scripts keep working
+during the transition.
+"""
+
+import importlib
+import importlib.abc
+import importlib.util
+import sys
+import warnings
+
+_LEGACY = "IMDgroup"
+_TARGET = "matrifflow"
+
+# The 8 CLI subcommand modules were renamed ``imdg*`` -> ``mrf*`` during the
+# MatRiFFlow rename.  The prefix-only mapping above cannot recover those, so
+# map their basenames explicitly.  Everything else shares its basename.
+_CLI_REMAP = {
+    "imdg": "mrf",
+    "imdg_create": "mrf_create",
+    "imdg_derive": "mrf_derive",
+    "imdg_diff": "mrf_diff",
+    "imdg_analyze": "mrf_analyze",
+    "imdg_status": "mrf_status",
+    "imdg_visualize": "mrf_visualize",
+    "imdg_run": "mrf_run",
+}
+
+warnings.warn(
+    "IMDgroup is deprecated; use matrifflow instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+
+class _AliasLoader(importlib.abc.Loader):
+    """Loader that returns the already-imported real module.
+
+    Reusing the real module object (rather than re-executing its source)
+    means ``IMDgroup.X`` *is* ``matrifflow.X``, so ``isinstance`` checks,
+    pickling, and pymatgen's MSONable registry keep working across the two
+    import paths.
+    """
+
+    def __init__(self, real_name: str):
+        self._real_name = real_name
+
+    def create_module(self, spec):
+        _ = spec # unused
+        return importlib.import_module(self._real_name)
+
+    def exec_module(self, module):
+        _ = module # unused
+        # Already executed by create_module()'s import_module() call.
+        pass
+
+
+class _AliasFinder(importlib.abc.MetaPathFinder):
+    def find_spec(self, fullname, path=None, target=None):
+        _, _ = path, target # unused
+        if fullname == _LEGACY or not fullname.startswith(_LEGACY + "."):
+            return None
+        real_name = _TARGET + fullname[len(_LEGACY):]
+        pkg, _, leaf = real_name.rpartition(".")
+        if leaf in _CLI_REMAP:
+            real_name = f"{pkg}.{_CLI_REMAP[leaf]}"
+        real_spec = importlib.util.find_spec(real_name)
+        if real_spec is None:
+            return None
+        spec = importlib.util.spec_from_loader(fullname, _AliasLoader(real_name))
+        assert spec is not None
+        if real_spec.submodule_search_locations is not None:
+            spec.submodule_search_locations = list(real_spec.submodule_search_locations)
+        return spec
+
+
+if not any(isinstance(f, _AliasFinder) for f in sys.meta_path):
+    sys.meta_path.insert(0, _AliasFinder())