{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# User Guide"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This example goes through the main usages of gizio. To follow along, make sure gizio is installed, and the [sample data](http://yt-project.org/data/FIRE_M12i_ref11.tar.gz) is downloaded."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import gizio"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Snapshot"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First load the snapshot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "snap = gizio.load('data/FIRE_M12i_ref11/snapshot_600.hdf5')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Inspection"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once a snapshot is loaded, several of its general peoperties are extracted as attributes, and could be inspected like the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "snap.header"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "snap.shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "snap.cosmology"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Field Access"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Fields could be accessed through a dictionary interface. The available keys could be queried by"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "snap.keys()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A field could be accessed through"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "snap['PartType0', 'Coordinates']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the field is loaded as a [unyt](https://unyt.readthedocs.io) array."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Particle Selector\n",
    "\n",
    "Particle selector is a more flexible interface to access fields. Default particle selectors according to particle types are created automatically when loading the snapshot, and could be accessed from"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "snap.pt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's have a look at the gas particle selector:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gas = snap.pt['gas']\n",
    "gas.keys()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Different from the snapshot interface, shorthand keys are used in the particle selector interface, except for unrecognized ones like `'Potential'`. So we have the following equality:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "(gas['p'] == snap['PartType0', 'Coordinates']).all()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The number of selected particles can be gotten from"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "len(gas)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some other particle selector properties could be queried like the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gas.pmask"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gas.shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gas.direct_fields()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Derived Fields"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Among the listed keys, one is special: `'t'` for temperature. There isn't a `('PartType0', 'Temperature')` field in the snapshot. Actually, temperature is computed from internal energy. So we call it a derived field:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gas['t']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We could check the code that does the computation (be careful this is not part of the public interface yet):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import inspect\n",
    "print(inspect.getsource(gas._field_registry['t']))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It's also pretty easy to register a custom derived field:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def volume(field_system):\n",
    "    return (field_system['m'] / field_system['rho']).to('kpc**3')\n",
    "\n",
    "gas.register_field('vol', volume)\n",
    "gas['vol']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Boolean Masking"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The particle selection could be further refined by boolean masking. For example, to select hot gas, we could do:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hot_gas = gas[gas['t'].to_value('K') > 1e5]\n",
    "hot_gas['t'].min()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Set-like Composing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another way to construct a new particle selector is to compose existing ones. A set-like interface is implemented for particle selectors to compose. For example, to define baryon as gas or star:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "star = snap.pt['star']\n",
    "baryon = gas | star"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Only keys from both gas and star are kept in the result:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "set(baryon.keys()) == set(gas.keys()) & set(star.keys())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here's another example to define dark matter as all but baryon:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dm = snap.pt['all'] - baryon"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Snapshot Format Spec"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Snapshot format are specified by a class. A GIZMO spec is built into gizio. It could be accessed as an attribute:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "snap.spec"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To customize a spec, subclass `SpecBase` or `GIZMOSpec` and modify its class attributes. For example, here we subclass `GIZMOSpec`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gizio.spec import GIZMOSpec\n",
    "\n",
    "class MySpec(GIZMOSpec):\n",
    "    pass\n",
    "\n",
    "MySpec.FIELD_SPEC"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And then modify the field spec so that `'ParticleIDs'` is aliased to `'pid'` instead of `'id'`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "MySpec.FIELD_SPEC[2] = ('ParticleIDs', 'pid', '')\n",
    "MySpec.FIELD_SPEC"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Load the snapshot with this new spec and we see `'pid'` in the keys."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "snap = gizio.load('data/FIRE_M12i_ref11/snapshot_600.hdf5', spec=MySpec())\n",
    "snap.pt['gas'].keys()"
   ]
  }
 ],
 "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.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}