{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "96c703e8",
   "metadata": {},
   "source": [
    "# Fermi Surface\n",
    "Generate and visualize Fermi surfaces from BXSF files.\n",
    "The Fermi surface mesh is generated in the frontend (JavaScript marching cubes); Python prepares the volumetric data and optional Brillouin-zone mesh via seekpath.\n\n",
    "\n",
    "Requires the optional `fermi-surface` dependencies (includes `seekpath`):\n",
    "\n",
    "```bash\n",
    "pip install \"weas-widget[fermi-surface]\"\n",
    "```\n",
    "\n",
    "Here's an example of how to use the `add_fermi_surface_from_bxsf` method:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0e43920b",
   "metadata": {},
   "outputs": [],
   "source": [
    "from weas_widget import WeasWidget\n",
    "viewer = WeasWidget()\n",
    "viewer.add_fermi_surface_from_bxsf(file_path=\"../../examples/copper.bxsf\",\n",
    "                                    clip_bz=True,\n",
    "                                    brillouin_zone_options={\"opacity\": 0.1,\n",
    "                                                            \"color\": \"#34ebd8\"})\n",
    "viewer"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "127efff6",
   "metadata": {},
   "source": [
    "\n",
    "Parameters summary for `add_fermi_surface_from_bxsf`:\n",
    "\n",
    "- `file_path`: Path to the `.bxsf` file.\n",
    "- `fermi_energy`: Override the Fermi energy (default: use value in file).\n",
    "- `drop_periodic`: Drop the duplicated periodic end points (default: `True`).\n",
    "- `clip_bz`: Clip to the first Brillouin zone (default: `True`, requires `seekpath`).\n",
    "- `show_bz`: Add the Brillouin zone mesh (default: `True`).\n",
    "- `show_reciprocal_axes`: Add reciprocal axes vectors (default: `True`).\n",
    "- `band_index`: Render a single band by index (default: `None`).\n",
    "- `combine_bands`: Merge all Fermi-crossing bands into one mesh (default: `False`).\n",
    "- `name`: Mesh name override.\n",
    "- `color`: RGB list for the mesh color or hex color string.\n",
    "- `opacity`: Alpha channel applied to the mesh.\n",
    "- `material_type`: Material type for the mesh (default: `\"Standard\"`).\n",
    "- `brillouin_zone_options`: Extra keyword arguments forwarded to `add_brillouin_zone` (e.g., custom color/opacity).\n",
    "- `reciprocal_axes_options`: Extra keyword arguments forwarded to `add_reciprocal_axes`.\n",
    "\n",
    "Notes:\n",
    "\n",
    "- The Fermi surface mesh is generated in the frontend (JavaScript marching cubes).\n",
    "- If `band_index` is `None`, all Fermi-crossing bands are used.\n",
    "- If `combine_bands=False`, each band is added as a separate mesh.\n",
    "- A `ValueError` is raised when no Fermi-crossing bands are found.\n",
    "\n",
    "\n",
    "\n",
    "You can customize the reciprocal axes and Brillouin-zone overlays when rendering a\n",
    "Fermi surface. For example, change the color and opacity of the Brillouin zone, and\n",
    "show the reciprocal axes with custom color and radius:\n",
    "\n",
    "```python\n",
    "    viewer.add_fermi_surface_from_bxsf(\n",
    "        \"copper.bxsf\",\n",
    "        clip_bz=True,\n",
    "        show_bz=True,\n",
    "        show_reciprocal_axes=True,\n",
    "        brillouin_zone_options={\"opacity\": 0.1,\n",
    "                                \"color\": \"#34ebd8\",\n",
    "                                \"show_edges\": True},\n",
    "        reciprocal_axes_options={\"color\": \"#ff5733\",\n",
    "                                \"radius\": 0.05},\n",
    "    )\n",
    "```"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}