pymdkit 1.5.2__tar.gz → 1.5.3__tar.gz

{pymdkit-1.5.2 → pymdkit-1.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.5.2
+Version: 1.5.3
 Summary: A unified command-line toolkit for atomistic / MD structure workflows.
 Author-email: Yueda Wang <ydwang0608@ustc.edu.cn>
 License-Expression: GPL-3.0-or-later
@@ -110,6 +110,7 @@ pmk gpumd-group -elements Li Y Cl                              # scan subfolders
 pmk convert -i opted.vasp -o opted.xyz                          # convert one structure
 pmk convert -if vasp-opted -of cif-opted -oe cif                # folder conversion target format
 pmk convert -it train.xyz -ot train.extxyz                      # convert a complete trajectory
+pmk convert -if Li4YCl6-disorder -of Li4YCl6-order -d2o -sc-matrix 1x1x1
 pmk supercell -i opted.vasp -o sc.vasp -max-abc 20            # cell lengths <= 20 A
 pmk supercell -if vasp-opted -max-abc 20 -individual          # per-structure ./<name>/<name>.<ext>
 pmk supercell -if extxyz-opted -max-abc 24 -individual -temp 500 600 -md-if input-files -group Li Y Cl
@@ -135,6 +136,7 @@ pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30
 nohup pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30 > submit-vasp.log 2>&1 &
 pmk realloc-occ -i 66-Li4YCl6-5.cif -of chg-balance -formula Li3YCl6
 pmk realloc-occ -if cifs -of chg-balance -formula Li3YCl6
+pmk realloc-occ -i 66-Li4YCl6-5.cif -of chg-balance -formula Li3YCl6 -occ 0 0.25 0.5 0.75 1
 pmk substitute -i Li3YCl6.cif -se Li -sn 3 -we Na -wn 3 -on 100
 pmk substitute -i Li3YCl6.cif -se Li -sn 3 -we none -on 100
 pmk substitute -i Li96Ta6La11Cl72.cif -se Li1 Li2 -sn 20 67 -we none -on 100
@@ -211,8 +213,11 @@ followed by three directional SDC columns. PMK takes the arithmetic mean over
 the last 50% of the SDC correlation-time range, converts A^2/ps to cm^2/s by
 multiplying by `1e-4`, and reports `D_total = (D_x + D_y + D_z) / 3`.
 Each job receives `msd/group_INDEX_ELEMENT_TEMP_msd.txt`, a matching `_sdc.txt`,
-and a `_results.txt`. The root receives `sigma-sdc-summary.txt` with directional
-and total diffusion coefficients and conductivities.
+and a `_results.txt`. The root receives a compact `sigma-sdc-summary.txt` with
+one row per job folder. Conductivities use two decimal places; diffusion
+coefficients use compact scientific notation with two decimal places. If the
+mobile ion occupies multiple groups, conductivities are summed and diffusion
+coefficients are particle-count-weighted.
 
 Ionic conductivity uses the Nernst-Einstein relation with the mean temperature
 of the final SDC-producing MD run and the official 18-column
@@ -231,7 +236,9 @@ oxidation-number loop, and preserves the original symmetry, coordinates,
 Wyckoff labels, and CIF layout. Every input receives `OUTPUT/INPUT_STEM/`; for
 the supplied Li4YCl6 example, the two outputs are `...-d1.cif` with `Li1=0.50`
 and `...-d2.cif` with `Li2=0.50`. Folder mode uses `-if` with the same `-of` and
-`-formula` options.
+`-formula` options. Add `-occ` followed by the only permitted occupancy values;
+for example, `-occ 0 0.25 0.5 0.75 1` also permits the valid allocation
+`Li1=0.75, Li2=0.75`.
 
 `gather-fs` recursively scans all job folders below the current directory. For
 VASP it follows the global `vaspout.h5 > vasprun.xml > OUTCAR` priority and
@@ -318,6 +325,17 @@ Single-file and trajectory modes infer the target format from `-o` and `-ot`.
 Because Wyckoff metadata describes one crystal structure, each `.cif` output
 file accepts exactly one frame.
 
+`convert -d2o` orders partially occupied CIF structures. `-sc-matrix 1x1x1`
+means a 1x1x1 cell; three diagonal factors or nine integer matrix entries are
+also accepted. Folder ordering scans recursively and mirrors input subfolders.
+It uses pymatgen `EnumerateStructureTransformation` with one worker to remove
+symmetry-equivalent orderings and select the lowest Ewald energy, then falls
+back to bounded `OrderDisorderedStructureTransformation` when enumlib is not
+available. Equivalent results from separate disorder files are merged and
+written as `BASE-o1.cif`, `BASE-o2.cif`, and so on. For convenience, supplying
+`-sc-matrix` without `-d2o` automatically enables ordering when a disordered
+CIF is detected; ordered inputs instead receive an ordinary supercell.
+
 After `supercell -temp` creates all requested jobs, it checks generated folders
 that contain `run.in`, `model.xyz`, and `nep.txt`. Existing `ensemble npt_scr`
 lines retain their temperature parameters but are rewritten with three

{pymdkit-1.5.2 → pymdkit-1.5.3}/README.md

@@ -83,6 +83,7 @@ pmk gpumd-group -elements Li Y Cl                              # scan subfolders
 pmk convert -i opted.vasp -o opted.xyz                          # convert one structure
 pmk convert -if vasp-opted -of cif-opted -oe cif                # folder conversion target format
 pmk convert -it train.xyz -ot train.extxyz                      # convert a complete trajectory
+pmk convert -if Li4YCl6-disorder -of Li4YCl6-order -d2o -sc-matrix 1x1x1
 pmk supercell -i opted.vasp -o sc.vasp -max-abc 20            # cell lengths <= 20 A
 pmk supercell -if vasp-opted -max-abc 20 -individual          # per-structure ./<name>/<name>.<ext>
 pmk supercell -if extxyz-opted -max-abc 24 -individual -temp 500 600 -md-if input-files -group Li Y Cl
@@ -107,7 +108,8 @@ pmk vasp2xyz -position-only                    # write positions only, without e
 pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30
 nohup pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30 > submit-vasp.log 2>&1 &
 pmk realloc-occ -i 66-Li4YCl6-5.cif -of chg-balance -formula Li3YCl6
-pmk realloc-occ -if cifs -of chg-balance -formula Li3YCl6
+pmk realloc-occ -if cifs -of chg-balance -formula Li3YCl6
+pmk realloc-occ -i 66-Li4YCl6-5.cif -of chg-balance -formula Li3YCl6 -occ 0 0.25 0.5 0.75 1
 pmk substitute -i Li3YCl6.cif -se Li -sn 3 -we Na -wn 3 -on 100
 pmk substitute -i Li3YCl6.cif -se Li -sn 3 -we none -on 100
 pmk substitute -i Li96Ta6La11Cl72.cif -se Li1 Li2 -sn 20 67 -we none -on 100
@@ -184,8 +186,11 @@ followed by three directional SDC columns. PMK takes the arithmetic mean over
 the last 50% of the SDC correlation-time range, converts A^2/ps to cm^2/s by
 multiplying by `1e-4`, and reports `D_total = (D_x + D_y + D_z) / 3`.
 Each job receives `msd/group_INDEX_ELEMENT_TEMP_msd.txt`, a matching `_sdc.txt`,
-and a `_results.txt`. The root receives `sigma-sdc-summary.txt` with directional
-and total diffusion coefficients and conductivities.
+and a `_results.txt`. The root receives a compact `sigma-sdc-summary.txt` with
+one row per job folder. Conductivities use two decimal places; diffusion
+coefficients use compact scientific notation with two decimal places. If the
+mobile ion occupies multiple groups, conductivities are summed and diffusion
+coefficients are particle-count-weighted.
 
 Ionic conductivity uses the Nernst-Einstein relation with the mean temperature
 of the final SDC-producing MD run and the official 18-column
@@ -204,7 +209,9 @@ oxidation-number loop, and preserves the original symmetry, coordinates,
 Wyckoff labels, and CIF layout. Every input receives `OUTPUT/INPUT_STEM/`; for
 the supplied Li4YCl6 example, the two outputs are `...-d1.cif` with `Li1=0.50`
 and `...-d2.cif` with `Li2=0.50`. Folder mode uses `-if` with the same `-of` and
-`-formula` options.
+`-formula` options. Add `-occ` followed by the only permitted occupancy values;
+for example, `-occ 0 0.25 0.5 0.75 1` also permits the valid allocation
+`Li1=0.75, Li2=0.75`.
 
 `gather-fs` recursively scans all job folders below the current directory. For
 VASP it follows the global `vaspout.h5 > vasprun.xml > OUTCAR` priority and
@@ -291,6 +298,17 @@ Single-file and trajectory modes infer the target format from `-o` and `-ot`.
 Because Wyckoff metadata describes one crystal structure, each `.cif` output
 file accepts exactly one frame.
 
+`convert -d2o` orders partially occupied CIF structures. `-sc-matrix 1x1x1`
+means a 1x1x1 cell; three diagonal factors or nine integer matrix entries are
+also accepted. Folder ordering scans recursively and mirrors input subfolders.
+It uses pymatgen `EnumerateStructureTransformation` with one worker to remove
+symmetry-equivalent orderings and select the lowest Ewald energy, then falls
+back to bounded `OrderDisorderedStructureTransformation` when enumlib is not
+available. Equivalent results from separate disorder files are merged and
+written as `BASE-o1.cif`, `BASE-o2.cif`, and so on. For convenience, supplying
+`-sc-matrix` without `-d2o` automatically enables ordering when a disordered
+CIF is detected; ordered inputs instead receive an ordinary supercell.
+
 After `supercell -temp` creates all requested jobs, it checks generated folders
 that contain `run.in`, `model.xyz`, and `nep.txt`. Existing `ensemble npt_scr`
 lines retain their temperature parameters but are rewritten with three

{pymdkit-1.5.2 → pymdkit-1.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pymdkit"
-version = "1.5.2"
+version = "1.5.3"
 description = "A unified command-line toolkit for atomistic / MD structure workflows."
 readme = "README.md"
 requires-python = ">=3.9"

{pymdkit-1.5.2 → pymdkit-1.5.3}/src/pymdkit/__init__.py

@@ -1,3 +1,3 @@
 """pymdkit -- a unified CLI for atomistic / MD structure workflows."""
 
-__version__ = "1.5.2"
+__version__ = "1.5.3"

pymdkit-1.5.3/src/pymdkit/commands/convert.py

@@ -0,0 +1,488 @@
+"""Convert structures and trajectories, including disorder-to-order workflows."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from collections import defaultdict
+from pathlib import Path
+
+try:
+    from . import _cifio, _fileio, _precision
+except ImportError:
+    import _cifio
+    import _fileio
+    import _precision
+
+COMMAND = "convert"
+HELP = "Convert structures/trajectories and order disordered structures."
+
+
+def _read(path, all_frames=False):
+    from ase.io import read
+
+    try:
+        return read(str(path), index=":" if all_frames else -1)
+    except Exception as ase_error:
+        if all_frames:
+            raise ValueError(
+                f"ASE could not read trajectory {path}: {ase_error}"
+            ) from ase_error
+        try:
+            from pymatgen.core import Molecule, Structure
+            from pymatgen.io.ase import AseAtomsAdaptor
+
+            try:
+                obj = Structure.from_file(str(path))
+            except Exception:
+                obj = Molecule.from_file(str(path))
+            return AseAtomsAdaptor.get_atoms(obj)
+        except Exception as pmg_error:
+            raise ValueError(
+                f"neither ASE nor pymatgen could read {path}: "
+                f"ASE={ase_error}; pymatgen={pmg_error}"
+            ) from pmg_error
+
+
+def _ase_format(path):
+    suffix = Path(path).suffix.lower()
+    if suffix in {".xyz", ".extxyz"}:
+        return "extxyz"
+    if suffix == ".vasp":
+        return "vasp"
+    return None
+
+
+def _normalize_output(path):
+    suffix = Path(path).suffix.lower()
+    if suffix in {".xyz", ".extxyz"}:
+        _precision.normalize_extxyz(path)
+    elif suffix == ".vasp":
+        _precision.normalize_vasp(path)
+
+
+def _write(path, atoms):
+    path = Path(path)
+    if _cifio.is_cif(path):
+        if isinstance(atoms, (list, tuple)) and len(atoms) != 1:
+            raise ValueError("CIF output supports exactly one structure per file")
+        one = atoms[0] if isinstance(atoms, (list, tuple)) else atoms
+        _cifio.write_cif(one, path, data_name=path.stem)
+        return
+
+    from ase.io import write
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    kwargs = {}
+    output_format = _ase_format(path)
+    if output_format:
+        kwargs["format"] = output_format
+    if output_format == "vasp":
+        kwargs["direct"] = True
+    try:
+        write(str(path), atoms, **kwargs)
+        _normalize_output(path)
+        return
+    except Exception as ase_error:
+        if isinstance(atoms, (list, tuple)) and len(atoms) != 1:
+            raise ValueError(
+                f"ASE cannot write this multi-frame trajectory to {path}: "
+                f"{ase_error}"
+            ) from ase_error
+        one = atoms[0] if isinstance(atoms, (list, tuple)) else atoms
+        try:
+            from pymatgen.io.ase import AseAtomsAdaptor
+
+            if one.pbc.any():
+                obj = AseAtomsAdaptor.get_structure(one)
+            else:
+                obj = AseAtomsAdaptor.get_molecule(one)
+            obj.to(filename=str(path))
+            _normalize_output(path)
+        except Exception as pmg_error:
+            raise ValueError(
+                f"neither ASE nor pymatgen could write {path}: "
+                f"ASE={ase_error}; pymatgen={pmg_error}"
+            ) from pmg_error
+
+
+def _read_structure(path):
+    from pymatgen.core import Structure
+
+    return Structure.from_file(str(path))
+
+
+def _write_structure(path, structure, refine=True):
+    path = Path(path)
+    if _cifio.is_cif(path):
+        _cifio.write_cif(
+            structure, path, data_name=path.stem, refine=refine
+        )
+        return
+    from pymatgen.io.ase import AseAtomsAdaptor
+
+    _write(path, AseAtomsAdaptor.get_atoms(structure))
+
+
+def _matrix_determinant(matrix):
+    return (
+        matrix[0][0] * (matrix[1][1] * matrix[2][2]
+                        - matrix[1][2] * matrix[2][1])
+        - matrix[0][1] * (matrix[1][0] * matrix[2][2]
+                          - matrix[1][2] * matrix[2][0])
+        + matrix[0][2] * (matrix[1][0] * matrix[2][1]
+                          - matrix[1][1] * matrix[2][0])
+    )
+
+
+def parse_supercell_matrix(values):
+    if not values:
+        return None
+    tokens = []
+    for value in values:
+        tokens.extend(token for token in re.split(r"[ ,xX]+", str(value)) if token)
+    try:
+        numbers = [int(token) for token in tokens]
+    except ValueError as exc:
+        raise ValueError("-sc-matrix values must be integers") from exc
+    if len(numbers) == 3:
+        if any(value <= 0 for value in numbers):
+            raise ValueError("diagonal -sc-matrix factors must be positive")
+        return [[numbers[0], 0, 0], [0, numbers[1], 0], [0, 0, numbers[2]]]
+    if len(numbers) == 9:
+        matrix = [numbers[0:3], numbers[3:6], numbers[6:9]]
+        if _matrix_determinant(matrix) == 0:
+            raise ValueError("-sc-matrix must be nonsingular")
+        return matrix
+    raise ValueError(
+        "-sc-matrix accepts 1x1x1, three diagonal factors, or nine matrix entries"
+    )
+
+
+def convert_one(input_path, output_path, trajectory=False, supercell_matrix=None):
+    if supercell_matrix is not None:
+        if trajectory:
+            raise ValueError("-sc-matrix is not supported with trajectory mode")
+        structure = _read_structure(input_path)
+        structure.make_supercell(supercell_matrix)
+        _write_structure(output_path, structure)
+    else:
+        atoms = _read(input_path, all_frames=trajectory)
+        _write(output_path, atoms)
+    count = len(atoms) if trajectory and supercell_matrix is None else 1
+    label = f" ({count} frame(s))" if trajectory else ""
+    print(f"{input_path} -> {output_path}{label}")
+
+
+def _recursive_structure_files(folder, cif_only=False):
+    folder = Path(folder)
+    if not folder.is_dir():
+        raise SystemExit(f"Error: input folder not found: {folder}")
+    files = [
+        path for path in folder.rglob("*")
+        if _fileio.is_structure(path)
+        and (not cif_only or path.suffix.lower() == ".cif")
+    ]
+    files.sort(key=lambda path: path.relative_to(folder).as_posix())
+    if not files:
+        kind = "CIF" if cif_only else "structure"
+        raise SystemExit(f"Error: no {kind} files found recursively in {folder}")
+    return files
+
+
+def _add_oxidation_states(structure, source):
+    if all(hasattr(specie, "oxi_state")
+           for site in structure for specie in site.species):
+        return structure
+    if Path(source).suffix.lower() != ".cif":
+        raise ValueError("Ewald ordering requires oxidation-state-decorated input")
+    try:
+        from .realloc_occ import parse_cif
+    except ImportError:
+        from realloc_occ import parse_cif
+
+    parsed = parse_cif(source)
+    oxidation = {}
+    for site in parsed.sites:
+        previous = oxidation.setdefault(site.element, site.oxidation)
+        if abs(previous - site.oxidation) > 1.0e-8:
+            raise ValueError(
+                f"{site.element} has multiple oxidation states; "
+                "site-specific Ewald decoration is ambiguous"
+            )
+    structure.add_oxidation_state_by_element(oxidation)
+    return structure
+
+
+def _ranked_structure(result):
+    if isinstance(result, list):
+        if not result:
+            raise ValueError("ordering transformation returned no structures")
+        result = result[0]
+    return result["structure"] if isinstance(result, dict) else result
+
+
+def _ewald_energy_per_atom(structure):
+    from pymatgen.analysis.ewald import EwaldSummation
+
+    return float(EwaldSummation(structure).total_energy) / len(structure)
+
+
+def _order_source(source, supercell_matrix):
+    structure = _read_structure(source)
+    if structure.is_ordered:
+        return None
+    structure = _add_oxidation_states(structure, source)
+    structure.make_supercell(supercell_matrix)
+    try:
+        from pymatgen.transformations.advanced_transformations import (
+            EnumerateStructureTransformation,
+        )
+
+        transformation = EnumerateStructureTransformation(
+            min_cell_size=1,
+            max_cell_size=1,
+            symm_prec=0.1,
+            refine_structure=False,
+            sort_criteria="ewald",
+            n_jobs=1,
+        )
+        result = transformation.apply_transformation(
+            structure, return_ranked_list=1
+        )
+        method = "EnumerateStructureTransformation"
+    except Exception as enum_error:
+        from pymatgen.transformations.standard_transformations import (
+            OrderDisorderedStructureTransformation,
+        )
+
+        transformation = OrderDisorderedStructureTransformation(
+            algo=OrderDisorderedStructureTransformation.ALGO_BEST_FIRST
+        )
+        result = transformation.apply_transformation(
+            structure, return_ranked_list=1
+        )
+        method = (
+            "OrderDisorderedStructureTransformation fallback "
+            f"({type(enum_error).__name__}: {enum_error})"
+        )
+    ordered = _ranked_structure(result)
+    if not ordered.is_ordered:
+        raise ValueError("ordering transformation returned a disordered structure")
+    return ordered, _ewald_energy_per_atom(ordered), method
+
+
+def _deduplicate_orderings(candidates):
+    from pymatgen.analysis.structure_matcher import StructureMatcher
+
+    matcher = StructureMatcher()
+    unique = []
+    for candidate in sorted(candidates, key=lambda item: item[1]):
+        structure = candidate[0]
+        if any(matcher.fit(structure, kept[0]) for kept in unique):
+            continue
+        unique.append(candidate)
+    return unique
+
+
+def _ordering_base(path):
+    return re.sub(r"-d\d+$", "", Path(path).stem, flags=re.IGNORECASE)
+
+
+def _folder_contains_disorder(folder):
+    folder = Path(folder)
+    if not folder.is_dir():
+        raise SystemExit(f"Error: input folder not found: {folder}")
+    for source in sorted(folder.rglob("*.cif")):
+        try:
+            if not _read_structure(source).is_ordered:
+                return True
+        except Exception:
+            continue
+    return False
+
+
+def _single_contains_disorder(source):
+    return Path(source).suffix.lower() == ".cif" and not _read_structure(source).is_ordered
+
+
+def order_single(source, output, supercell_matrix):
+    candidate = _order_source(Path(source), supercell_matrix)
+    if candidate is None:
+        raise ValueError(f"input structure is already ordered: {source}")
+    structure, energy, method = candidate
+    output = Path(output)
+    if output.suffix.lower() != ".cif":
+        raise ValueError("disorder-to-order output must be a .cif file")
+    _write_structure(output, structure, refine=False)
+    print(f"{source} -> {output} (Ewald={energy:.8f} eV/atom; {method})")
+
+
+def order_folder(input_folder, output_folder, supercell_matrix):
+    input_folder = Path(input_folder)
+    output_folder = Path(output_folder)
+    groups = defaultdict(list)
+    for source in _recursive_structure_files(input_folder, cif_only=True):
+        relative_parent = source.parent.relative_to(input_folder)
+        groups[(relative_parent, _ordering_base(source))].append(source)
+
+    written, processed, failed = 0, 0, 0
+    for (relative_parent, base), sources in sorted(
+            groups.items(), key=lambda item: (item[0][0].as_posix(), item[0][1])):
+        candidates = []
+        for source in sources:
+            try:
+                candidate = _order_source(source, supercell_matrix)
+                if candidate is None:
+                    print(f"{source}: already ordered -> skipped")
+                    continue
+                candidates.append((*candidate, source))
+                processed += 1
+            except Exception as exc:
+                failed += 1
+                print(f"{source}: ordering failed ({exc})")
+        destination = output_folder / relative_parent
+        destination.mkdir(parents=True, exist_ok=True)
+        for number, candidate in enumerate(
+                _deduplicate_orderings(candidates), start=1):
+            structure, energy, method, source = candidate
+            output = destination / f"{base}-o{number}.cif"
+            _write_structure(output, structure, refine=False)
+            print(
+                f"{source} -> {output} "
+                f"(Ewald={energy:.8f} eV/atom; {method})"
+            )
+            written += 1
+    print(
+        f"Done: ordered {processed} disordered CIF(s), wrote {written} "
+        f"symmetry-distinct lowest-energy CIF(s) to {output_folder}"
+    )
+    return 0 if processed and written and not failed else 1
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("-i", "-input", dest="input",
+                        help="Single input structure.")
+    parser.add_argument("-o", "-output", dest="output",
+                        help="Single output structure; with -if, output folder.")
+    parser.add_argument("-it", "-input-trajectory", dest="input_trajectory",
+                        help="Input trajectory containing multiple structures.")
+    parser.add_argument("-ot", "-output-trajectory", dest="output_trajectory",
+                        help="Output trajectory.")
+    parser.add_argument("-if", "-input-folder", dest="input_folder",
+                        help="Folder of input structures.")
+    parser.add_argument("-of", "-output-folder", dest="output_folder",
+                        help="Output folder for batch conversion.")
+    parser.add_argument("-oe", "-output-extension", dest="output_extension",
+                        default="xyz",
+                        help="Batch/scan output extension (default: xyz).")
+    parser.add_argument(
+        "-d2o", action="store_true",
+        help="Order partially occupied structures and retain lowest-Ewald results.",
+    )
+    parser.add_argument(
+        "-sc-matrix", nargs="+", metavar="N",
+        help="Supercell as 1x1x1, three diagonal factors, or nine matrix entries.",
+    )
+
+
+def _extension(value):
+    value = str(value).strip()
+    return value if value.startswith(".") else "." + value
+
+
+def run(args) -> int:
+    modes = [bool(args.input), bool(args.input_trajectory), bool(args.input_folder)]
+    if sum(modes) > 1:
+        raise SystemExit("Error: use only one of -i, -it, or -if.")
+    try:
+        supercell_matrix = parse_supercell_matrix(args.sc_matrix)
+    except ValueError as exc:
+        raise SystemExit(f"Error: {exc}") from exc
+    if args.input_trajectory and (args.d2o or supercell_matrix is not None):
+        raise SystemExit("Error: -d2o and -sc-matrix do not support -it.")
+
+    ordering_mode = bool(args.d2o)
+    if supercell_matrix is not None and not ordering_mode:
+        if args.input:
+            ordering_mode = _single_contains_disorder(args.input)
+        elif args.input_folder:
+            ordering_mode = _folder_contains_disorder(args.input_folder)
+    if ordering_mode:
+        matrix = supercell_matrix or [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
+        if args.input:
+            if not args.output:
+                raise SystemExit("Error: -o is required with -i -d2o.")
+            try:
+                order_single(args.input, args.output, matrix)
+            except Exception as exc:
+                raise SystemExit(f"Error: {exc}") from exc
+            return 0
+        if args.input_folder:
+            if args.output and args.output_folder:
+                raise SystemExit("Error: use only one of -o or -of with -if.")
+            folder_option = args.output_folder or args.output
+            output_folder = (
+                Path(folder_option) if folder_option
+                else Path(args.input_folder).with_name(
+                    Path(args.input_folder).name + "-order"
+                )
+            )
+            return order_folder(args.input_folder, output_folder, matrix)
+        raise SystemExit("Error: -d2o requires -i or -if.")
+
+    if args.input:
+        if not args.output:
+            raise SystemExit("Error: -o is required with -i.")
+        convert_one(
+            args.input, args.output, supercell_matrix=supercell_matrix
+        )
+        return 0
+
+    if args.input_trajectory:
+        if not args.output_trajectory:
+            raise SystemExit("Error: -ot is required with -it.")
+        convert_one(args.input_trajectory, args.output_trajectory, trajectory=True)
+        return 0
+
+    extension = _extension(args.output_extension)
+    if args.input_folder:
+        input_folder = Path(args.input_folder)
+        if args.output and args.output_folder:
+            raise SystemExit("Error: use only one of -o or -of with -if.")
+        folder_option = args.output_folder or args.output
+        output_folder = (
+            Path(folder_option) if folder_option
+            else input_folder.with_name(input_folder.name + "-converted")
+        )
+        output_folder.mkdir(parents=True, exist_ok=True)
+        files = _fileio.structure_files(input_folder)
+        for path in files:
+            convert_one(
+                path,
+                output_folder / (path.stem + extension),
+                supercell_matrix=supercell_matrix,
+            )
+        print(f"Done: converted {len(files)} file(s) to {output_folder}")
+        return 0
+
+    if supercell_matrix is not None:
+        raise SystemExit("Error: -sc-matrix requires -i or -if.")
+    count = 0
+    for folder in _fileio.subfolders("."):
+        for path in sorted(folder.iterdir()):
+            if not _fileio.is_structure(path):
+                continue
+            if path.suffix.lower() == extension.lower():
+                continue
+            name = args.output if args.output else path.stem + extension
+            convert_one(path, folder / name)
+            count += 1
+    print(f"Done: converted {count} file(s) across sub-folders.")
+    return 0
+
+
+if __name__ == "__main__":
+    _parser = argparse.ArgumentParser(description=__doc__)
+    add_arguments(_parser)
+    raise SystemExit(run(_parser.parse_args()))

{pymdkit-1.5.2 → pymdkit-1.5.3}/src/pymdkit/commands/gpumd_msd.py

@@ -391,32 +391,39 @@ def analyze_job(root, folder, thermo_path, args):
     return records
 
 
+def _compact_scientific(value):
+    mantissa, exponent = f"{float(value):.2e}".split("e")
+    return f"{mantissa}e{int(exponent)}"
+
+
 def write_summary(root, records, diffuse_ion):
     columns = [
-        "Job", "T(K)", "V(A^3)", "Ensemble", "Volume_source",
-        "Group", "Element", "N", "average_start(ps)", "average_end(ps)",
-        "D_x(cm^2/s)", "D_y(cm^2/s)", "D_z(cm^2/s)", "D_total(cm^2/s)",
-        "sigma_x(mS/cm)", "sigma_y(mS/cm)", "sigma_z(mS/cm)",
-        "sigma_total(mS/cm)",
+        "Folder", "sigma_total(mS/cm)", "sigma_x(mS/cm)",
+        "sigma_y(mS/cm)", "sigma_z(mS/cm)", "D_total(cm^2/s)",
+        "D_x(cm^2/s)", "D_y(cm^2/s)", "D_z(cm^2/s)",
     ]
     lines = [
         "GPUMD SDC and Nernst-Einstein conductivity summary",
         f"Mobile ion: {diffuse_ion}",
         "SDC average: arithmetic mean over the last 50% of correlation time",
         "\t".join(columns),
+        "-" * len("\t".join(columns).expandtabs(4)),
     ]
-    for record in sorted(records, key=lambda item: (item["job"], item["group_id"])):
-        conductivity = record["conductivity"]
-        sigma = ([f"{value:.8f}" for value in conductivity]
-                 if conductivity is not None else ["N/A"] * 4)
+    jobs = {}
+    for record in records:
+        if record["element"] == diffuse_ion and record["conductivity"] is not None:
+            jobs.setdefault(record["job"], []).append(record)
+    for job, job_records in sorted(jobs.items()):
+        sigma = np.sum([record["conductivity"] for record in job_records], axis=0)
+        count = sum(record["count"] for record in job_records)
+        diffusion = sum(
+            record["diffusion"] * record["count"] for record in job_records
+        ) / count
         fields = [
-            record["job"], f"{record['temperature']:.8f}",
-            f"{record['volume']:.8f}", record["ensemble"],
-            record["volume_source"], str(record["group_id"]),
-            record["element"], str(record["count"]),
-            f"{record['average_start']:.8f}",
-            f"{record['average_end']:.8f}",
-            *(f"{value:.8f}" for value in record["diffusion"]), *sigma,
+            job,
+            *(f"{sigma[index]:.2f}" for index in (3, 0, 1, 2)),
+            *(_compact_scientific(diffusion[index])
+              for index in (3, 0, 1, 2)),
         ]
         lines.append("\t".join(fields))
     (Path(root) / SUMMARY_FILE).write_text(

{pymdkit-1.5.2 → pymdkit-1.5.3}/src/pymdkit/commands/realloc_occ.py

@@ -3,6 +3,7 @@
 Examples:
     pmk realloc-occ -i 66-Li4YCl6-5.cif -of chg-balance -formula Li3YCl6
     pmk realloc-occ -if structures -of chg-balance -formula Li3YCl6
+    pmk realloc-occ -i input.cif -of out -formula Li3YCl6 -occ 0 0.5 1
 """
 
 from __future__ import annotations
@@ -244,7 +245,73 @@ def _infer_z(parsed, target):
     return min(scores)[2]
 
 
-def _adjustment_options(sites, target_count):
+def _normalize_occupancies(values):
+    if values is None:
+        return None
+    occupancies = []
+    for value in values:
+        number = float(value)
+        if not -TOLERANCE <= number <= 1.0 + TOLERANCE:
+            raise ValueError("-occ values must be between 0 and 1")
+        rounded = round(number, 2)
+        if abs(number - rounded) > TOLERANCE:
+            raise ValueError("-occ values support at most two decimal places")
+        occupancies.append(min(1.0, max(0.0, rounded)))
+    result = tuple(sorted(set(occupancies)))
+    if not result:
+        raise ValueError("-occ requires at least one occupancy value")
+    return result
+
+
+def _grid_occupancy_options(sites, target_count, allowed_occupancies):
+    if len(sites) > MAX_ADJUSTABLE_SITES:
+        raise ValueError(f"more than {MAX_ADJUSTABLE_SITES} adjustable sites")
+    minimum, maximum = min(allowed_occupancies), max(allowed_occupancies)
+    options = []
+
+    def visit(index, total, values):
+        if len(options) > MAX_OUTPUTS:
+            raise ValueError(f"occupancy allocations exceed {MAX_OUTPUTS}")
+        if index == len(sites):
+            if abs(total - target_count) <= TOLERANCE:
+                options.append(tuple(values))
+            return
+        remaining = sites[index + 1:]
+        minimum_remaining = sum(site.multiplicity * minimum for site in remaining)
+        maximum_remaining = sum(site.multiplicity * maximum for site in remaining)
+        site = sites[index]
+        choices = sorted(
+            allowed_occupancies,
+            key=lambda value: (abs(value - site.occupancy), value),
+        )
+        for value in choices:
+            subtotal = total + site.multiplicity * value
+            if subtotal + minimum_remaining > target_count + TOLERANCE:
+                continue
+            if subtotal + maximum_remaining < target_count - TOLERANCE:
+                continue
+            visit(index + 1, subtotal, values + [value])
+
+    visit(0, 0.0, [])
+    options = list(dict.fromkeys(options))
+    options.sort(key=lambda values: (
+        sum(abs(site.occupancy - value) > TOLERANCE
+            for site, value in zip(sites, values)),
+        tuple(index for index, (site, value) in enumerate(zip(sites, values))
+              if abs(site.occupancy - value) > TOLERANCE),
+        values,
+    ))
+    if not options:
+        allowed = ", ".join(f"{value:.2f}" for value in allowed_occupancies)
+        raise ValueError(
+            f"no allocation reaches the target using -occ values: {allowed}"
+        )
+    return options
+
+
+def _adjustment_options(sites, target_count, allowed_occupancies=None):
+    if allowed_occupancies is not None:
+        return _grid_occupancy_options(sites, target_count, allowed_occupancies)
     current = sum(site.multiplicity * site.occupancy for site in sites)
     delta = target_count - current
     if abs(delta) <= TOLERANCE:
@@ -296,7 +363,7 @@ def _adjustment_options(sites, target_count):
     return options
 
 
-def generate_candidates(parsed, target_formula):
+def generate_candidates(parsed, target_formula, allowed_occupancies=None):
     target = _parse_formula(target_formula)
     sites_by_element = OrderedDict()
     for index, site in enumerate(parsed.sites):
@@ -313,8 +380,11 @@ def generate_candidates(parsed, target_formula):
 
     element_options = []
     for element, indexed_sites in sites_by_element.items():
-        options = _adjustment_options([site for _, site in indexed_sites],
-                                      target_counts.get(element, 0.0))
+        options = _adjustment_options(
+            [site for _, site in indexed_sites],
+            target_counts.get(element, 0.0),
+            allowed_occupancies,
+        )
         element_options.append((indexed_sites, options))
     output_count = math.prod(len(options) for _, options in element_options)
     if output_count > MAX_OUTPUTS:
@@ -389,9 +459,11 @@ def _detected_formula(parsed):
     return _format_formula(composition)
 
 
-def process_one(source, output_root, target_formula):
+def process_one(source, output_root, target_formula, allowed_occupancies=None):
     parsed = parse_cif(source)
-    target, target_counts, z, candidates = generate_candidates(parsed, target_formula)
+    target, target_counts, z, candidates = generate_candidates(
+        parsed, target_formula, allowed_occupancies
+    )
     destination = Path(output_root) / Path(source).stem
     if destination.exists() and (not destination.is_dir()
                                  or any(destination.iterdir())):
@@ -417,6 +489,10 @@ def add_arguments(parser):
                         help="Top-level output folder; each input gets a subfolder.")
     parser.add_argument("-formula", required=True,
                         help="Target reduced formula, for example Li3YCl6.")
+    parser.add_argument(
+        "-occ", nargs="+", type=float,
+        help="Allowed site occupancies, for example 0 0.25 0.5 0.75 1.",
+    )
 
 
 def run(args):
@@ -432,12 +508,19 @@ def run(args):
         if not sources:
             raise SystemExit(f"Error: no CIF files found in {folder}")
 
+    try:
+        allowed_occupancies = _normalize_occupancies(args.occ)
+    except ValueError as exc:
+        raise SystemExit(f"Error: {exc}") from exc
+
     output_root = Path(args.output_folder)
     output_root.mkdir(parents=True, exist_ok=True)
     files_written, inputs_done = 0, 0
     for source in sources:
         try:
-            files_written += process_one(source, output_root, args.formula)
+            files_written += process_one(
+                source, output_root, args.formula, allowed_occupancies
+            )
             inputs_done += 1
         except Exception as exc:
             print(f"{source}: failed ({exc})")

{pymdkit-1.5.2 → pymdkit-1.5.3}/src/pymdkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.5.2
+Version: 1.5.3
 Summary: A unified command-line toolkit for atomistic / MD structure workflows.
 Author-email: Yueda Wang <ydwang0608@ustc.edu.cn>
 License-Expression: GPL-3.0-or-later
@@ -110,6 +110,7 @@ pmk gpumd-group -elements Li Y Cl                              # scan subfolders
 pmk convert -i opted.vasp -o opted.xyz                          # convert one structure
 pmk convert -if vasp-opted -of cif-opted -oe cif                # folder conversion target format
 pmk convert -it train.xyz -ot train.extxyz                      # convert a complete trajectory
+pmk convert -if Li4YCl6-disorder -of Li4YCl6-order -d2o -sc-matrix 1x1x1
 pmk supercell -i opted.vasp -o sc.vasp -max-abc 20            # cell lengths <= 20 A
 pmk supercell -if vasp-opted -max-abc 20 -individual          # per-structure ./<name>/<name>.<ext>
 pmk supercell -if extxyz-opted -max-abc 24 -individual -temp 500 600 -md-if input-files -group Li Y Cl
@@ -135,6 +136,7 @@ pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30
 nohup pmk submit-vasp -subscript sub_vasp -queue slurm -max-job-num 30 > submit-vasp.log 2>&1 &
 pmk realloc-occ -i 66-Li4YCl6-5.cif -of chg-balance -formula Li3YCl6
 pmk realloc-occ -if cifs -of chg-balance -formula Li3YCl6
+pmk realloc-occ -i 66-Li4YCl6-5.cif -of chg-balance -formula Li3YCl6 -occ 0 0.25 0.5 0.75 1
 pmk substitute -i Li3YCl6.cif -se Li -sn 3 -we Na -wn 3 -on 100
 pmk substitute -i Li3YCl6.cif -se Li -sn 3 -we none -on 100
 pmk substitute -i Li96Ta6La11Cl72.cif -se Li1 Li2 -sn 20 67 -we none -on 100
@@ -211,8 +213,11 @@ followed by three directional SDC columns. PMK takes the arithmetic mean over
 the last 50% of the SDC correlation-time range, converts A^2/ps to cm^2/s by
 multiplying by `1e-4`, and reports `D_total = (D_x + D_y + D_z) / 3`.
 Each job receives `msd/group_INDEX_ELEMENT_TEMP_msd.txt`, a matching `_sdc.txt`,
-and a `_results.txt`. The root receives `sigma-sdc-summary.txt` with directional
-and total diffusion coefficients and conductivities.
+and a `_results.txt`. The root receives a compact `sigma-sdc-summary.txt` with
+one row per job folder. Conductivities use two decimal places; diffusion
+coefficients use compact scientific notation with two decimal places. If the
+mobile ion occupies multiple groups, conductivities are summed and diffusion
+coefficients are particle-count-weighted.
 
 Ionic conductivity uses the Nernst-Einstein relation with the mean temperature
 of the final SDC-producing MD run and the official 18-column
@@ -231,7 +236,9 @@ oxidation-number loop, and preserves the original symmetry, coordinates,
 Wyckoff labels, and CIF layout. Every input receives `OUTPUT/INPUT_STEM/`; for
 the supplied Li4YCl6 example, the two outputs are `...-d1.cif` with `Li1=0.50`
 and `...-d2.cif` with `Li2=0.50`. Folder mode uses `-if` with the same `-of` and
-`-formula` options.
+`-formula` options. Add `-occ` followed by the only permitted occupancy values;
+for example, `-occ 0 0.25 0.5 0.75 1` also permits the valid allocation
+`Li1=0.75, Li2=0.75`.
 
 `gather-fs` recursively scans all job folders below the current directory. For
 VASP it follows the global `vaspout.h5 > vasprun.xml > OUTCAR` priority and
@@ -318,6 +325,17 @@ Single-file and trajectory modes infer the target format from `-o` and `-ot`.
 Because Wyckoff metadata describes one crystal structure, each `.cif` output
 file accepts exactly one frame.
 
+`convert -d2o` orders partially occupied CIF structures. `-sc-matrix 1x1x1`
+means a 1x1x1 cell; three diagonal factors or nine integer matrix entries are
+also accepted. Folder ordering scans recursively and mirrors input subfolders.
+It uses pymatgen `EnumerateStructureTransformation` with one worker to remove
+symmetry-equivalent orderings and select the lowest Ewald energy, then falls
+back to bounded `OrderDisorderedStructureTransformation` when enumlib is not
+available. Equivalent results from separate disorder files are merged and
+written as `BASE-o1.cif`, `BASE-o2.cif`, and so on. For convenience, supplying
+`-sc-matrix` without `-d2o` automatically enables ordering when a disordered
+CIF is detected; ordered inputs instead receive an ordinary supercell.
+
 After `supercell -temp` creates all requested jobs, it checks generated folders
 that contain `run.in`, `model.xyz`, and `nep.txt`. Existing `ensemble npt_scr`
 lines retain their temperature parameters but are rewritten with three

pymdkit-1.5.2/src/pymdkit/commands/convert.py

@@ -1,186 +0,0 @@
-"""Convert structures and trajectories between ASE/pymatgen formats."""
-
-from __future__ import annotations
-
-import argparse
-from pathlib import Path
-
-try:
-    from . import _cifio, _fileio, _precision
-except ImportError:
-    import _cifio
-    import _fileio
-    import _precision
-
-COMMAND = "convert"
-HELP = "Convert structures or trajectories between ASE/pymatgen formats."
-
-
-def _read(path, all_frames=False):
-    from ase.io import read
-
-    try:
-        return read(str(path), index=":" if all_frames else -1)
-    except Exception as ase_error:
-        if all_frames:
-            raise ValueError(f"ASE could not read trajectory {path}: {ase_error}") from ase_error
-        try:
-            from pymatgen.core import Molecule, Structure
-            from pymatgen.io.ase import AseAtomsAdaptor
-
-            try:
-                obj = Structure.from_file(str(path))
-            except Exception:
-                obj = Molecule.from_file(str(path))
-            return AseAtomsAdaptor.get_atoms(obj)
-        except Exception as pmg_error:
-            raise ValueError(
-                f"neither ASE nor pymatgen could read {path}: "
-                f"ASE={ase_error}; pymatgen={pmg_error}"
-            ) from pmg_error
-
-
-def _ase_format(path):
-    suffix = Path(path).suffix.lower()
-    if suffix in {".xyz", ".extxyz"}:
-        return "extxyz"
-    if suffix == ".vasp":
-        return "vasp"
-    return None
-
-
-def _normalize_output(path):
-    suffix = Path(path).suffix.lower()
-    if suffix in {".xyz", ".extxyz"}:
-        _precision.normalize_extxyz(path)
-    elif suffix == ".vasp":
-        _precision.normalize_vasp(path)
-
-
-def _write(path, atoms):
-    path = Path(path)
-    if _cifio.is_cif(path):
-        if isinstance(atoms, (list, tuple)) and len(atoms) != 1:
-            raise ValueError("CIF output supports exactly one structure per file")
-        one = atoms[0] if isinstance(atoms, (list, tuple)) else atoms
-        _cifio.write_cif(one, path, data_name=path.stem)
-        return
-
-    from ase.io import write
-
-    path.parent.mkdir(parents=True, exist_ok=True)
-    kwargs = {}
-    output_format = _ase_format(path)
-    if output_format:
-        kwargs["format"] = output_format
-    if output_format == "vasp":
-        kwargs["direct"] = True
-    try:
-        write(str(path), atoms, **kwargs)
-        _normalize_output(path)
-        return
-    except Exception as ase_error:
-        if isinstance(atoms, (list, tuple)) and len(atoms) != 1:
-            raise ValueError(
-                f"ASE cannot write this multi-frame trajectory to {path}: {ase_error}"
-            ) from ase_error
-        one = atoms[0] if isinstance(atoms, (list, tuple)) else atoms
-        try:
-            from pymatgen.io.ase import AseAtomsAdaptor
-
-            if one.pbc.any():
-                obj = AseAtomsAdaptor.get_structure(one)
-            else:
-                obj = AseAtomsAdaptor.get_molecule(one)
-            obj.to(filename=str(path))
-            _normalize_output(path)
-        except Exception as pmg_error:
-            raise ValueError(
-                f"neither ASE nor pymatgen could write {path}: "
-                f"ASE={ase_error}; pymatgen={pmg_error}"
-            ) from pmg_error
-
-
-def convert_one(input_path, output_path, trajectory=False):
-    atoms = _read(input_path, all_frames=trajectory)
-    _write(output_path, atoms)
-    count = len(atoms) if trajectory else 1
-    label = f" ({count} frame(s))" if trajectory else ""
-    print(f"{input_path} -> {output_path}{label}")
-
-
-def add_arguments(parser: argparse.ArgumentParser) -> None:
-    parser.add_argument("-i", "-input", dest="input",
-                        help="Single input structure.")
-    parser.add_argument("-o", "-output", dest="output",
-                        help="Single output structure; with -if, output folder.")
-    parser.add_argument("-it", "-input-trajectory", dest="input_trajectory",
-                        help="Input trajectory containing multiple structures.")
-    parser.add_argument("-ot", "-output-trajectory", dest="output_trajectory",
-                        help="Output trajectory.")
-    parser.add_argument("-if", "-input-folder", dest="input_folder",
-                        help="Folder of input structures.")
-    parser.add_argument("-of", "-output-folder", dest="output_folder",
-                        help="Output folder for batch conversion.")
-    parser.add_argument("-oe", "-output-extension", dest="output_extension",
-                        default="xyz",
-                        help="Batch/scan output extension (default: xyz).")
-
-
-def _extension(value):
-    value = str(value).strip()
-    return value if value.startswith(".") else "." + value
-
-
-def run(args) -> int:
-    modes = [bool(args.input), bool(args.input_trajectory), bool(args.input_folder)]
-    if sum(modes) > 1:
-        raise SystemExit("Error: use only one of -i, -it, or -if.")
-
-    if args.input:
-        if not args.output:
-            raise SystemExit("Error: -o is required with -i.")
-        convert_one(args.input, args.output)
-        return 0
-
-    if args.input_trajectory:
-        if not args.output_trajectory:
-            raise SystemExit("Error: -ot is required with -it.")
-        convert_one(args.input_trajectory, args.output_trajectory, trajectory=True)
-        return 0
-
-    extension = _extension(args.output_extension)
-    if args.input_folder:
-        input_folder = Path(args.input_folder)
-        if args.output and args.output_folder:
-            raise SystemExit("Error: use only one of -o or -of with -if.")
-        folder_option = args.output_folder or args.output
-        output_folder = (
-            Path(folder_option) if folder_option
-            else input_folder.with_name(input_folder.name + "-converted")
-        )
-        output_folder.mkdir(parents=True, exist_ok=True)
-        files = _fileio.structure_files(input_folder)
-        for path in files:
-            convert_one(path, output_folder / (path.stem + extension))
-        print(f"Done: converted {len(files)} file(s) to {output_folder}")
-        return 0
-
-    count = 0
-    for folder in _fileio.subfolders("."):
-        for path in sorted(folder.iterdir()):
-            if not _fileio.is_structure(path):
-                continue
-            if path.suffix.lower() == extension.lower():
-                continue
-            name = args.output if args.output else path.stem + extension
-            convert_one(path, folder / name)
-            count += 1
-    print(f"Done: converted {count} file(s) across sub-folders.")
-    return 0
-
-
-if __name__ == "__main__":
-    _parser = argparse.ArgumentParser(description=__doc__)
-    add_arguments(_parser)
-    raise SystemExit(run(_parser.parse_args()))