Source code for ase2sprkkr_cli.commands.symmetry

"""Analyse crystal symmetry and optionally export transformed unit cells."""

import json
from pathlib import Path


help = "Analyse crystal symmetry and transform unit cells."
description = """Determine space groups, equivalent sites, Wyckoff positions, and
optionally construct a primitive or standardized cell using spglib.
Input/output structures use ASE formats (including registered SPR-KKR POT)."""


# The tags are taken from the selected CIF data block, not inferred from ASE
# coordinates or normalized to the conventional spglib setting.
_CIF_SYMMETRY_TAGS = {
    "number": (
        "_space_group.it_number", "_space_group_it_number",
        "_symmetry_int_tables_number",
    ),
    "hermann_mauguin": (
        "_space_group.name_h-m_alt", "_space_group_name_h-m_alt",
        "_symmetry_space_group_name_h-m", "_space_group.name_h-m_ref",
        "_space_group.name_h-m_full",
    ),
    "hall": (
        "_space_group.name_hall", "_space_group_name_hall",
        "_symmetry_space_group_name_hall",
    ),
    "crystal_system": (
        "_space_group.crystal_system", "_space_group_crystal_system",
        "_symmetry_cell_setting",
    ),
    "operations": (
        "_space_group_symop.operation_xyz", "_space_group_symop_operation_xyz",
        "_symmetry_equiv_pos_as_xyz",
    ),
}


[docs] def _declared_cif_symmetry(info): """Extract CIF-declared symmetry, preserving its values and not inferring P1.""" tags = {key.lower(): value for key, value in info.items() if isinstance(key, str)} declared = {} for field, candidates in _CIF_SYMMETRY_TAGS.items(): for name in candidates: value = tags.get(name) if value is None or (isinstance(value, str) and value.strip() in ("?", ".")): continue if field == "operations": value = [value] if isinstance(value, str) else list(value) if not value: continue declared[field] = value break return declared or None
[docs] def parser(parser): parser.add_argument("input", help="Structure file readable by ASE") mode = parser.add_mutually_exclusive_group() mode.add_argument("--primitive", action="store_true", help="Find a primitive cell") mode.add_argument("--standardize", action="store_true", help="Find the standard conventional cell") parser.add_argument( "--equivalence", choices=("site-types", "occupation"), default="site-types", help="Site-equivalence rule (default: site-types)" ) parser.add_argument("--symprec", type=float, default=1e-5, help="Position tolerance in Å") parser.add_argument("--angle-tolerance", type=float, default=-1.0, help="Angle tolerance in degrees") parser.add_argument("--idealize", action="store_true", help="Idealize in the original basis (also works without cell conversion)") parser.add_argument("--ase-arrays", choices=("require-equal", "discard", "choose-first"), default="require-equal", help="Transfer policy for additional ASE arrays") parser.add_argument("--sites", action="store_true", help="Show equivalent sites and Wyckoff positions") parser.add_argument("--operations", action="store_true", help="Show rotations and translations") parser.add_argument("-v", "--verbose", action="store_true", help="Show detailed symmetry information") parser.add_argument("--view", action="store_true", help="Visualize the resulting structure") parser.add_argument("-o", "--output", help="Write transformed structure to this file") parser.add_argument("-f", "--format", help="Override ASE output format") parser.add_argument("--report", help="Write JSON analysis report")
[docs] def _report(analysis, *, sites=False, operations=False): data = analysis.dataset result = { "spacegroup_number": int(data.number), "international": str(data.international), "hall": str(data.hall), "pointgroup": str(data.pointgroup), "number_of_operations": len(data.rotations), "number_of_sites": len(analysis.site_tags), "number_of_primitive_sites": len(set(map(int, data.mapping_to_primitive))), "equivalence": analysis.equivalence, "symprec": analysis.symprec, "angle_tolerance": analysis.angle_tolerance, "transformation_matrix": data.transformation_matrix.tolist(), "origin_shift": data.origin_shift.tolist(), } if sites: result["sites"] = [ { "index": i + 1, "tag": int(analysis.site_tags[i]), "equivalent_atom": int(data.equivalent_atoms[i]) + 1, "primitive_atom": int(data.mapping_to_primitive[i]) + 1, "wyckoff": str(data.wyckoffs[i]), "site_symmetry": str(data.site_symmetry_symbols[i]), } for i in range(len(analysis.site_tags)) ] if operations: result["operations"] = [ {"rotation": rot.tolist(), "translation": translation.tolist()} for rot, translation in zip(data.rotations, data.translations) ] return result
[docs] def run(args, global_args=None): from ase.io import read, write from ase.io.formats import filetype from ase2sprkkr.sprkkr.symmetry import analyze_symmetry if args.output and not (args.primitive or args.standardize or args.idealize): raise ValueError("--output requires --primitive, --standardize, or --idealize") if args.format and not args.output: raise ValueError("--format requires --output") if args.output and Path(args.output).resolve() == Path(args.input).resolve(): raise ValueError("Input file cannot be overwritten") is_cif = filetype(args.input) == "cif" atoms = read(args.input, **({"store_tags": True} if is_cif else {})) declared = _declared_cif_symmetry(atoms.info) if is_cif else None analysis = analyze_symmetry( atoms, equivalence=args.equivalence, symprec=args.symprec, angle_tolerance=args.angle_tolerance, ) data = analysis.dataset result = None if args.primitive: result = analysis.find_primitive(atoms, idealize=args.idealize, ase_arrays=args.ase_arrays) elif args.standardize: result = analysis.standardize(atoms, idealize=args.idealize, ase_arrays=args.ase_arrays) elif args.idealize: result = analysis.idealize(atoms) output = _report( analysis, sites=args.sites or args.verbose, operations=args.operations or args.verbose, ) if result is not None: output["transformed_sites"] = len(result) output["source_sites"] = len(atoms) if declared: output["cif_declared_symmetry"] = declared symbol = declared.get("hermann_mauguin") number = declared.get("number") description = str(symbol) if symbol is not None else "not named" if number is not None: description += f" (No. {number})" print(f"CIF-declared space group: {description}") if "hall" in declared: print(f"CIF-declared Hall: {declared['hall']}") if "crystal_system" in declared: print(f"CIF-declared crystal system: {declared['crystal_system']}") if "operations" in declared: print(f"CIF-declared symmetry operations: {len(declared['operations'])}") print( f"Space group{' (calculated)' if declared else ''}: " f"{data.international} (No. {data.number})" ) print(f"Hall: {data.hall}; Point group: {data.pointgroup}") if declared and "number" in declared: try: declared_number = int(declared["number"]) except (TypeError, ValueError): pass # Retain and print the original CIF value as-is. else: if declared_number != int(data.number): print("Note: CIF-declared and calculated space-group numbers differ.") print(f"Sites: {len(atoms)}; primitive sites: {output['number_of_primitive_sites']}") print(f"Symmetry operations: {len(data.rotations)}; equivalence: {args.equivalence}") if result is not None: print(f"Transformed cell: {len(result)} sites") if args.sites or args.verbose: print("Index Species Equivalent Primitive Wyckoff Site symmetry") for site in output["sites"]: print( f"{site['index']:>5} {site['tag']:>7} " f"{site['equivalent_atom']:>10} {site['primitive_atom']:>9} " f"{site['wyckoff']:>7} {site['site_symmetry']}" ) if args.operations or args.verbose: if declared and "operations" in declared: for index, operation in enumerate(declared["operations"], 1): print(f"CIF operation {index}: {operation}") for index, op in enumerate(output["operations"], 1): print(f"Operation {index}: rotation={op['rotation']}, translation={op['translation']}") if args.report: Path(args.report).write_text(json.dumps(output, indent=2) + "\n", encoding="utf-8") if args.output: kwargs = {"format": args.format} if args.format else {} write(args.output, result, **kwargs) if args.view: from ase.visualize import view view(result if result is not None else atoms)