pymdkit 1.5.2__tar.gz → 1.5.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymdkit
-Version: 1.5.2
+Version: 1.5.4
 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.125 0.25 0.375 0.5 0.625 0.75 0.875 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,12 @@ 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 fixed-width, right-aligned 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 +237,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;
+three decimal places are supported, so grids containing `0.125`, `0.375`,
+`0.625`, and `0.875` are preserved exactly in generated CIF files.
 
 `gather-fs` recursively scans all job folders below the current directory. For
 VASP it follows the global `vaspout.h5 > vasprun.xml > OUTCAR` priority and
@@ -298,7 +306,7 @@ and `Cl`. Oxidation numbers remain in the separate
 
 Newly serialized floating-point values use eight digits after the decimal
 point across PMK structure, trajectory, data, report, and screen output. CIF
-`_atom_site_occupancy` values use two digits and
+`_atom_site_occupancy` values use three digits and
 `_atom_type_oxidation_number` values use one digit. In extended XYZ, zero components
 inside the second-line `Lattice="..."` value remain `0.0`; other generated
 floating-point values use eight digits. Commands that select or concatenate
@@ -318,6 +326,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.4}/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.125 0.25 0.375 0.5 0.625 0.75 0.875 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,12 @@ 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 fixed-width, right-aligned 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 +210,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;
+three decimal places are supported, so grids containing `0.125`, `0.375`,
+`0.625`, and `0.875` are preserved exactly in generated CIF files.
 
 `gather-fs` recursively scans all job folders below the current directory. For
 VASP it follows the global `vaspout.h5 > vasprun.xml > OUTCAR` priority and
@@ -271,7 +279,7 @@ and `Cl`. Oxidation numbers remain in the separate
 
 Newly serialized floating-point values use eight digits after the decimal
 point across PMK structure, trajectory, data, report, and screen output. CIF
-`_atom_site_occupancy` values use two digits and
+`_atom_site_occupancy` values use three digits and
 `_atom_type_oxidation_number` values use one digit. In extended XYZ, zero components
 inside the second-line `Lattice="..."` value remain `0.0`; other generated
 floating-point values use eight digits. Commands that select or concatenate
@@ -291,6 +299,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.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pymdkit"
-version = "1.5.2"
+version = "1.5.4"
 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.4}/src/pymdkit/__init__.py

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

{pymdkit-1.5.2 → pymdkit-1.5.4}/src/pymdkit/commands/_cifio.py

@@ -198,7 +198,7 @@ def _format_cif_scalar(value, precision, force=False):
 def _format_cif_numbers(block):
     for tag, value in list(block.data.items()):
         if tag == OCCUPANCY_TAG:
-            precision = 2
+            precision = 3
         elif tag == OXIDATION_TAG:
             precision = 1
         else:

pymdkit-1.5.4/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()))