{
 "cells": [
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext",
    "vscode": {
     "languageId": "raw"
    }
   },
   "source": [
    ".. _data:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Data Handling\n",
    "\n",
    "`cherab-lhd` handles LHD-related data like EMC3-EIRENE grid configuration, machine geometry, measurement geometry, etc.\n",
    "Here is a brief description of the dataset containing the above-mentioned data."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Dataset Registries"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext",
    "vscode": {
     "languageId": "raw"
    }
   },
   "source": [
    "`cherab-lhd` provides a list of hash values of the files instead of providing the data files\n",
    "themselves.\n",
    ":obj:`~cherab.lhd.tools.fetch` module offers functionalities to manage the download of the data files\n",
    "by checking if the files are not present in the cache directory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from cherab.lhd.tools.fetch import show_registries\n",
    "\n",
    "show_registries()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Retrieving the Dataset"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The dataset is downloaded through sftp protocol from the remote server if it is not already available\n",
    "in the local cache directory or its hash differs from the one in the registry.\n",
    "\n",
    "Before downloading the dataset, **users need to have access to the remote server.**\n",
    "The dataset has not been opened to the public yet.\n",
    "Those who want to access the dataset must contact the package maintainers.\n",
    "\n",
    "After getting permission to deal with the dataset, users need to set the following environment variables:\n",
    "- `SSH_RAYTRACE_HOSTNAME`: The hostname of the remote server (e.g. sftp://hostname/directory/).\n",
    "- `SSH_RAYTRACE_USERNAME`: The username to log in to the remote server.\n",
    "- `SSH_RAYTRACE_PASSWORD`: The password to log in to the remote server."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext",
    "vscode": {
     "languageId": "raw"
    }
   },
   "source": [
    "Then, use the :obj:`.fetch_file` function:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    ">>> from cherab.lhd.tools.fetch import fetch_file\n",
    ">>> path = fetch_file(\"emc3/grid-360.nc\")\n",
    "```"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext",
    "vscode": {
     "languageId": "raw"
    }
   },
   "source": [
    "Or, manually specify them as arguments to the :obj:`.fetch_file` function."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    ">>> path = fetch_file(\"emc3/grid-360.nc\", host=\"sftp://hostname/directory/\", username=\"username\", password=\"password\")\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Downloaded files are stored in the user's cache directory:\n",
    "- Linux: `~/.cache/cherab/lhd/`\n",
    "- macOS: `~/Library/Caches/cherab/lhd/`\n",
    "\n",
    "If the dataset is no longer needed, please delete the downloaded files manually."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Locate the Dataset file manually\n",
    "\n",
    "Users can put dataset files in the cache directory manually.\n",
    "Please confirm the cache directory depending on the operating system as specified above and place the files under the `cherab/lhd` directory with corresponding subdirectories (e.g. `emc3`, `machine`, `observer`, etc.)\n",
    "\n",
    "Note that even if the files are placed locally, they will be downloaded from the remote server if the hash value is different from the one in the registry."
   ]
  }
 ],
 "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.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}