{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Loading and Plotting MHD Data\n\nThis example introduces the two steps needed to go from a PSI data file to a\nrendered scene:\n\n1. **Fetching a dataset** \u2014 :func:`~pyvisual.utils.data.fetch_datasets`\n   downloads (or retrieves from cache) a version-pinned HDF5 file from the\n   PSI asset server and returns its local path.\n2. **Reading the data** \u2014 :func:`~psi_io.psi_io.read_hdf_by_index` loads the array\n   values and the three coordinate grids $(r, \\theta, \\phi)$ from the\n   file.  Passing ``None`` for a dimension selects its full extent; passing an\n   integer index fixes that dimension to a single grid point.\n\nThe dataset used here is the radial magnetic field $B_r$ from a\nThermo 2 steady-state coronal simulation for Carrington Rotation 2282\n(CR 2282), covering the domain $r \\in [1,\\,30]\\,R_\\odot$.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from psi_io import read_hdf_by_index\nfrom pyvisual import Plot3d\nfrom pyvisual.utils.data import fetch_datasets"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Fetching a Dataset\n\n:func:`~pyvisual.utils.data.fetch_datasets` accepts a *domain* identifier\n(``'cor'`` for the coronal domain, ``'hel'`` for heliospheric) and a\n*variable* name.  It returns a :func:`~collections.namedtuple` whose fields\nare named ``\"{domain}_{variable}\"``.  The first call downloads the file to\nthe local cache; subsequent calls return the cached copy immediately without\nhitting the network.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "datasets = fetch_datasets(\"cor\", \"br\")\nbr_file = datasets.cor_br"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Reading a 2-D Radial Slice\n\n:func:`~psi_io.psi_io.read_hdf_by_index` reads the HDF5 file and returns\n``(data, r, t, p)`` \u2014 the scalar array followed by the three coordinate\nvectors.  Index arguments control which portion of the grid is loaded:\n\n- ``None`` \u2014 load the full extent of that dimension.\n- An integer ``i`` \u2014 fix that dimension to the ``i``-th grid point\n  (1-based), collapsing it to a length-1 array.\n\nHere the colatitude is fixed at index 71 (the equatorial plane,\n$\\theta_{71} \\approx \\pi/2$), while $r$ and $\\phi$\nspan their full extents.  The result is a 2-D surface in the equatorial\nplane colored by $B_r$.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "data, r, t, p = read_hdf_by_index(br_file, None, 71, None)\n\nplotter = Plot3d()\nplotter.show_axes()\nplotter.add_sun()\nplotter.add_2d_slice(r, t, p, data, cmap='seismic', clim=(-1, 1),\n                     show_scalar_bar=True)\nplotter.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Scaling by $r^2$\n\nThe radial magnetic field falls off geometrically as $1/r^2$ with\ndistance.  Multiplying by $r^2$ removes this trend and reveals the\nlongitudinal structure of open-field regions at all radii \u2014 a common\ndiagnostic in solar wind modeling.  Because ``r`` is a plain NumPy array,\nthe scaling is a single element-wise operation before passing to the plotter.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "plotter = Plot3d()\nplotter.show_axes()\nplotter.add_sun()\nplotter.add_2d_slice(r, t, p, data * r ** 2, cmap='seismic', clim=(-1, 1),\n                     show_scalar_bar=True)\nplotter.show()"
      ]
    }
  ],
  "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.13.12"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}