{
 "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": [
    "### SFTP download"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Most datasets are downloaded via the SFTP protocol from the remote server if they are not already available in the local cache directory or if their hash differs from the one in the registry.\n",
    "\n",
    "Before downloading the dataset, **users need to have access to the remote server.**\n",
    "All datasets are not yet publicly available.\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": [
    "### Other download methods"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext",
    "vscode": {
     "languageId": "raw"
    }
   },
   "source": [
    "Some datasets are publicly available via DOI links.\n",
    "URL links to the corresponding data can be accessed by using the :obj:`.get_urls` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from cherab.lhd.tools.fetch import get_urls\n",
    "\n",
    "get_urls()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The path to the publicly available dataset can be also retrieved like this:\n",
    "\n",
    "```python\n",
    ">>> path = fetch_file(\"grid-demo.nc\")\n",
    "```"
   ]
  },
  {
   "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
}