Example usage of `spglib.get_magnetic_symmetry_dataset`

mp_magnetism.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Magnetic symmetry analysis with Spglib"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Prepare NiO (AFM) structures"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/home/shinohara/.pyenv/versions/miniconda3-4.3.30/envs/spglib/lib/python3.10/site-packages/pymatgen/analysis/phase_diagram.py:24: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html\n",
      "  from tqdm.autonotebook import tqdm\n"
     ]
    }
   ],
   "source": [
    "from pathlib import Path\n",
    "\n",
    "import numpy as np\n",
    "from mp_api import MPRester\n",
    "from pymatgen.core import Structure\n",
    "\n",
    "from spglib import get_symmetry_dataset, get_spacegroup_type\n",
    "from spglib import get_magnetic_symmetry_dataset, get_magnetic_spacegroup_type  # develop branch"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "with open(Path.home() / \".mp_api\") as f:\n",
    "    api_key = f.readline().strip(\"\\n\")\n",
    "mpr = MPRester(api_key)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "def pmg_structure_to_cell(structure: Structure):\n",
    "    lattice = structure.lattice.matrix\n",
    "    positions = structure.frac_coords\n",
    "    numbers = [site.specie.number for site in structure]\n",
    "    magmoms = [site.properties.get(\"magmom\") for site in structure]\n",
    "    cell = (lattice, positions, numbers, magmoms)\n",
    "    return cell"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Retrieving MaterialsDoc documents: 100%|██████████| 1/1 [00:00<00:00, 8289.14it/s]\n",
      "Document primary key has changed from mp-1232476 to mp-19009, returning data for mp-19009 in summary route.    \n",
      "Retrieving SummaryDoc documents: 100%|██████████| 1/1 [00:00<00:00, 8867.45it/s]"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Full Formula (Ni2 O2)\n",
      "Reduced Formula: NiO\n",
      "abc   :   2.983077   2.983082   5.159941\n",
      "angles: 106.802163  73.197727 119.998063\n",
      "pbc   :       True       True       True\n",
      "Sites (4)\n",
      "  #  SP           a         b         c    magmom\n",
      "---  ----  --------  --------  --------  --------\n",
      "  0  Ni    0         0         0           -1.742\n",
      "  1  Ni    0.5       0.5       0.5          1.742\n",
      "  2  O     0.250001  0.749999  0.249993     0\n",
      "  3  O     0.749999  0.250001  0.750007     0\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    }
   ],
   "source": [
    "# https://static-content.springer.com/esm/art%3A10.1038%2Fs41524-019-0199-7/MediaObjects/41524_2019_199_MOESM1_ESM.pdf\n",
    "# NiO (AFM, type-IV)\n",
    "task_id = \"mp-1232476\"\n",
    "\n",
    "structure_doc = mpr.summary.get_data_by_id(task_id, fields=[\"structure\"])\n",
    "# mag_doc = mpr.magnetism.get_data_by_id(task_id)\n",
    "\n",
    "structure = structure_doc.structure\n",
    "print(structure)\n",
    "cell = pmg_structure_to_cell(structure)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Space group (family space group)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'number': 225, 'international_short': 'Fm-3m', 'international_full': 'F 4/m -3 2/m', 'international': 'F m -3 m', 'schoenflies': 'Oh^5', 'hall_number': 523, 'hall_symbol': '-F 4 2 3', 'choice': '', 'pointgroup_international': 'm-3m', 'pointgroup_schoenflies': 'Oh', 'arithmetic_crystal_class_number': 72, 'arithmetic_crystal_class_symbol': 'm-3mF'}\n",
      "Number of symmetry operations: 24\n"
     ]
    }
   ],
   "source": [
    "# Relaxed cell is relatively distorted. Thus, we use higher symprec.\n",
    "# When we ignore magmoms, the unit cell is half of conventional FCC\n",
    "dataset = get_symmetry_dataset(cell[:-1], symprec=1e-2)\n",
    "print(get_spacegroup_type(dataset[\"hall_number\"]))\n",
    "print(\"Number of symmetry operations:\", len(dataset[\"rotations\"]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Analyze magnetic space group as collinear spin\n",
    "\n",
    "Use `is_axial=False` if spatial symmetry operation $\\{ \\mathbf{R} \\mid \\mathbf{\\tau} \\}$ transforms magmom $(0, 0, m_{i})^{\\top}$ to $\\mathbf{R} (0, 0, m_{i})^{\\top}$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'uni_number': 1332, 'litvin_number': 1332, 'bns_number': '166.102', 'og_number': '166.6.1332', 'number': 166, 'type': 4}\n",
      "Number of symmetry operations: 24\n"
     ]
    }
   ],
   "source": [
    "dataset_as_collinear = get_magnetic_symmetry_dataset(cell, symprec=1e-2, is_axial=False)\n",
    "\n",
    "# Type-IV MSG\n",
    "# Maximal space subgroup: R-3m (No. 166)\n",
    "uni_number = dataset_as_collinear[\"uni_number\"]  # Range from 1 to 1651\n",
    "magnetic_spacegroup_type = get_magnetic_spacegroup_type(uni_number)\n",
    "print(magnetic_spacegroup_type)\n",
    "print(\"Number of symmetry operations:\", len(dataset_as_collinear[\"rotations\"]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Standardized cell"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Full Formula (Ni6 O6)\n",
      "Reduced Formula: NiO\n",
      "abc   :   2.983167   2.983077  14.592009\n",
      "angles:  90.000857  89.999878 120.000886\n",
      "pbc   :       True       True       True\n",
      "Sites (12)\n",
      "  #  SP            a          b         c    magmom\n",
      "---  ----  ---------  ---------  --------  --------\n",
      "  0  Ni     0          0         0           -1.742\n",
      "  1  Ni     0.333333   0.666667  0.666667    -1.742\n",
      "  2  Ni     0.666667   0.333333  0.333333    -1.742\n",
      "  3  Ni     0.666667   0.333333  0.833333     1.742\n",
      "  4  Ni    -0         -0         0.5          1.742\n",
      "  5  Ni     0.333333   0.666667  0.166667     1.742\n",
      "  6  O     -0          0         0.75         0\n",
      "  7  O      0.333333   0.666667  0.416667     0\n",
      "  8  O      0.666667   0.333333  0.083333     0\n",
      "  9  O      0.333333   0.666667  0.916667     0\n",
      " 10  O      0.666667   0.333333  0.583333     0\n",
      " 11  O     -0         -0         0.25         0\n"
     ]
    }
   ],
   "source": [
    "# Standardized cell: Use the same setting convention as BNS symbols (maximal space subspace for type-IV MSG)\n",
    "def cell_to_pmg_structure(lattice, positions, numbers, magmoms) -> Structure:\n",
    "    structure = Structure(\n",
    "        lattice=lattice,\n",
    "        species=numbers,\n",
    "        coords=positions,\n",
    "        site_properties={\"magmom\": magmoms},\n",
    "    )\n",
    "    return structure\n",
    "\n",
    "\n",
    "std_structure = cell_to_pmg_structure(\n",
    "    dataset_as_collinear[\"std_lattice\"],\n",
    "    dataset_as_collinear[\"std_positions\"],\n",
    "    dataset_as_collinear[\"std_types\"],\n",
    "    dataset_as_collinear[\"std_tensors\"],\n",
    ")\n",
    "print(std_structure)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Magnetic symmetry operations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "def equivalent_operations(rotation1, translation1, rotation2, translation2):\n",
    "    if not np.allclose(rotation1, rotation2):\n",
    "        return False\n",
    "    diff_mod = translation1 - translation2\n",
    "    diff_mod -= np.rint(diff_mod)\n",
    "    return np.allclose(diff_mod, 0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Family space group\n",
    "# When we ignore \"time_reversal\" parts, recover symmetry operations by `get_symmetry_dataset`\n",
    "for R1, tau1 in zip(dataset_as_collinear[\"rotations\"], dataset_as_collinear[\"translations\"]):\n",
    "    count = 0\n",
    "    for R2, tau2 in zip(dataset[\"rotations\"], dataset[\"translations\"]):\n",
    "        if equivalent_operations(R1, tau1, R2, tau2):\n",
    "            count += 1\n",
    "    assert count == 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Maximal subspace group\n",
    "# Only half of magnetic symmetry operations are time_reversal=False for type-IV MSG\n",
    "assert sum(dataset_as_collinear[\"time_reversals\"]) == dataset_as_collinear[\"n_operations\"] // 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[0.5 0.5 0.5]\n"
     ]
    }
   ],
   "source": [
    "# Anti translation in type-IV MSG\n",
    "# For this example, corresponding to the translation between Ni with magmom=-1.742 to Ni with magmom=1.742\n",
    "for i in range(dataset_as_collinear[\"n_operations\"]):\n",
    "    if (\n",
    "        np.allclose(dataset_as_collinear[\"rotations\"][i], np.eye(3))\n",
    "        and dataset_as_collinear[\"time_reversals\"][i]\n",
    "    ):\n",
    "        print(dataset_as_collinear[\"translations\"][i])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Analyze magnetic space group as non-collinear \n",
    "\n",
    "Use `is_axial=True` if spatial symmetry operation $\\{ \\mathbf{R} \\mid \\mathbf{\\tau} \\}$ transforms magmom $(0, 0, m_{i})^{\\top}$ to $(\\det \\mathbf{R}) \\cdot \\mathbf{R} (0, 0, m_{i})^{\\top}$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'uni_number': 1338, 'litvin_number': 1333, 'bns_number': '167.108', 'og_number': '166.7.1333', 'number': 167, 'type': 4}\n",
      "24\n"
     ]
    }
   ],
   "source": [
    "dataset_as_noncollinear = get_magnetic_symmetry_dataset(cell, symprec=1e-2, is_axial=True)\n",
    "uni_number = dataset_as_noncollinear[\"uni_number\"]  # Range from 1 to 1651\n",
    "magnetic_spacegroup_type = get_magnetic_spacegroup_type(uni_number)\n",
    "print(magnetic_spacegroup_type)\n",
    "print(len(dataset_as_noncollinear[\"rotations\"]))"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.4"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": true
  },
  "vscode": {
   "interpreter": {
    "hash": "2641854f03b65a170e7cfe63fc585b64f03f733afd114aecf4aa18a7512ec467"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}