{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "md1",
   "metadata": {},
   "source": [
    "# Examples\n",
    "\n",
    "Build a crystal structure in the Simple representation: a cell, sites in\n",
    "reduced coordinates, OPTIMADE-style species, and the species occupying each site."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "code1",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-07-22T22:37:46.937831Z",
     "iopub.status.busy": "2026-07-22T22:37:46.937457Z",
     "iopub.status.idle": "2026-07-22T22:37:47.004824Z",
     "shell.execute_reply": "2026-07-22T22:37:47.003006Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Species: ['Na', 'Cl']\n",
      "Sites: 2\n"
     ]
    }
   ],
   "source": [
    "from httk.atomistic import Structure, StructurePrimitiveView\n",
    "\n",
    "structure = Structure(\n",
    "    cell=[[5.64, 0.0, 0.0], [0.0, 5.64, 0.0], [0.0, 0.0, 5.64]],\n",
    "    sites=[[0.0, 0.0, 0.0], [0.5, 0.5, 0.5]],\n",
    "    species=[\n",
    "        {\"name\": \"Na\", \"chemical_symbols\": [\"Na\"], \"concentration\": [1.0]},\n",
    "        {\"name\": \"Cl\", \"chemical_symbols\": [\"Cl\"], \"concentration\": [1.0]},\n",
    "    ],\n",
    "    species_at_sites=[\"Na\", \"Cl\"],\n",
    ")\n",
    "\n",
    "print(\"Species:\", [s.name for s in structure.species])\n",
    "print(\"Sites:\", len(structure.sites))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "md2",
   "metadata": {},
   "source": [
    "A view presents the same structure through another representation. The primitive\n",
    "view is a genuine spglib-like `(lattice, positions, numbers)` tuple:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "code2",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-07-22T22:37:47.008562Z",
     "iopub.status.busy": "2026-07-22T22:37:47.008213Z",
     "iopub.status.idle": "2026-07-22T22:37:47.015047Z",
     "shell.execute_reply": "2026-07-22T22:37:47.013142Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Atomic numbers: (11, 17)\n"
     ]
    }
   ],
   "source": [
    "lattice, positions, numbers = StructurePrimitiveView(structure)\n",
    "print(\"Atomic numbers:\", numbers)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "md-components",
   "metadata": {},
   "source": [
    "The `cell`, `sites`, and `species` components get the same view/backend treatment.\n",
    "`structure.cell` is a `Cell` with derived quantities, and `SpeciesPrimitiveView`\n",
    "presents a species as an OPTIMADE dict:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "code-components",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-07-22T22:37:47.018902Z",
     "iopub.status.busy": "2026-07-22T22:37:47.018535Z",
     "iopub.status.idle": "2026-07-22T22:37:47.026361Z",
     "shell.execute_reply": "2026-07-22T22:37:47.024749Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Cell lengths: (5.64, 5.64, 5.64)\nCell volume: 179.40614399999998\nSpecies dict: {'name': 'Na', 'chemical_symbols': ['Na'], 'concentration': [1.0]}\n"
     ]
    }
   ],
   "source": [
    "from httk.atomistic import SpeciesPrimitiveView\n",
    "\n",
    "cell = structure.cell\n",
    "# lengths/volume are exact (SurdScalar); render them to floats at the presentation boundary.\n",
    "print(\"Cell lengths:\", tuple(round(length.to_float(), 4) for length in cell.lengths))\n",
    "print(\"Cell volume:\", cell.volume.to_float())\n",
    "print(\"Species dict:\", dict(SpeciesPrimitiveView(structure.species[0])))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "md3",
   "metadata": {},
   "source": [
    "Species that are not single, unattached chemical elements (for example a site with\n",
    "a vacancy probability) cannot be expressed as bare atomic numbers, so the\n",
    "primitive view refuses them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "code3",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-07-22T22:37:47.030619Z",
     "iopub.status.busy": "2026-07-22T22:37:47.030264Z",
     "iopub.status.idle": "2026-07-22T22:37:47.039259Z",
     "shell.execute_reply": "2026-07-22T22:37:47.037423Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "TypeError: This structure cannot be represented as a primitive structure (species 'Ti' is not a single, unattached chemical element)\n"
     ]
    }
   ],
   "source": [
    "vacancy_structure = Structure(\n",
    "    cell=[[3.0, 0.0, 0.0], [0.0, 3.0, 0.0], [0.0, 0.0, 3.0]],\n",
    "    sites=[[0.0, 0.0, 0.0]],\n",
    "    species=[{\"name\": \"Ti\", \"chemical_symbols\": [\"Ti\", \"vacancy\"], \"concentration\": [0.9, 0.1]}],\n",
    "    species_at_sites=[\"Ti\"],\n",
    ")\n",
    "try:\n",
    "    StructurePrimitiveView(vacancy_structure)\n",
    "except TypeError as exc:\n",
    "    print(\"TypeError:\", exc)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.12.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}