osiris-utils 1.1.4__py3-none-any.whl → 1.1.7__py3-none-any.whl

examples/example_Simulation_Diagnostic.ipynb

@@ -0,0 +1,379 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import osiris_utils as ou\n",
+    "import numpy as np\n",
+    "import matplotlib.pyplot as plt\n",
+    "from matplotlib.colors import LogNorm"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Example notebook for the `Simulation` and `Diagnostic` classes"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### `Simulation`\n",
+    "The `Simulation` class takes in:\n",
+    "- `simulation_folder`: the folder where the input deck is located\n",
+    "- `species`: the species in case we are interested in diagnostics that are species-specific (such as vfl1, T11, etc.)\n",
+    "\n",
+    "Acts as a wrapper for the `Diagnostic` class, allowing for an easy access to diagnostics of the simulation using a **dictionary-like** syntax."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### `Diagnostic`\n",
+    "\n",
+    "The `Diagnostic` class takes in:\n",
+    "- `simulation_folder`: the folder where the input deck is located\n",
+    "- `species`: the species in case we are interested in diagnostics that are species-specific (such as vfl1, T11, etc.)\n",
+    "\n",
+    "\n",
+    "The `Diagnostic` class has the some relevant methods and properties that you should be aware of:\n",
+    "- `get_quantity`: \"loads\" the quantity. Accessing the diagnostic through the `Simulations` using the dictionary-like syntax this will be called automatically.\n",
+    "- once the quantity is loaded, you can access the data at a specific time through indexing (e.g. `diag['vfl1'][0]` for the first time step). This doesn't store the data in memory, only uses a data generator to access the data (lazy loading).\n",
+    "- `load_all`: loads all the time steps of the quantity, storing it in memory\n",
+    "- `unload`: unloads the data from memory\n",
+    "- `time`: the time steps of the quantity at a specific index\n",
+    "- Has operator overloading for the `+`, `-`, `*`, `/` operators, allowing for easy manipulation of the data, even when it is not loaded in memory and is accessed through indexing."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# sim is a Simulation object\n",
+    "sim = ou.Simulation(input_deck_path=\"example_data/thermal.1d\")\n",
+    "\n",
+    "print(\"Simulation:\")\n",
+    "print(sim)\n",
+    "print(sim.__dict__.keys())\n",
+    "print(f\"\\n\")\n",
+    "\n",
+    "# e3 is a Diagnostic object\n",
+    "e3 = ou.Diagnostic(\"example_data\", \"electrons\")\n",
+    "# now we need to load the data\n",
+    "e3.get_quantity(\"e3\") # it knows the path there since OSIRIS always saves the data in the same way\n",
+    "\n",
+    "print(\"Diagnostic: (e3)\")\n",
+    "print(e3)\n",
+    "print(e3.__dict__.keys())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If the diagnostic that you want to access if related to a species, you need to access it by using the species name as the first key."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# An electric field if not relatec to a species, so you can access it by doing:\n",
+    "sim[\"e3\"]\n",
+    "\n",
+    "# To access a species-related diagnostic, you can do:\n",
+    "sim[\"electrons\"][\"vfl1\"]\n",
+    "\n",
+    "# To see the available species of a simulation, you can do:\n",
+    "sim.species"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Notice that the `Diagnostic` class does not have `data` as the data is not saved in memory if `load_all` is not called. The data is accessed through the `__getitem__` method using indexing."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To get a `Diagnostic` from a `Simulation`, you can access it through the dictionary-like syntax, where the key is the name of the diagnostic (e.g. `sim['vfl1']` is a `Diagnostic` with the `vfl1` quantity)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sim[\"e3\"] # This is equivalent to e3\n",
+    "\n",
+    "print(sim[\"e3\"])\n",
+    "print(sim[\"e3\"].__dict__.keys())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If we want to access the data of the diagnostic at a specific time, we can use the indexing syntax (e.g. `sim['vfl1'][0]` for the first time step, using a `Simulation`, or `e3[0]`, using the `Diagnostic` directly)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(sim[\"e3\"][100].shape) # nx\n",
+    "print(e3[100].shape)        # nx\n",
+    "\n",
+    "print(\"Are they the same?\", np.isclose(sim[\"e3\"][100], e3[100]).all())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This is useful when we want to access a specific iteration of the diagnostic, without loading all the data in memory. \n",
+    "\n",
+    "For a quick plot, we can even use the other attributes of the `Diagnostic` class, such as `time`, `x` for the axis, of `axis` for info about the axis."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plt.figure(figsize=(12,4))\n",
+    "plt.subplot(121)\n",
+    "plt.plot(sim[\"e3\"].x, sim[\"e3\"][100], label=\"Simulation\", c=\"tab:orange\")\n",
+    "plt.title(\"Using Simulation\")\n",
+    "plt.xlabel(sim[\"e3\"].axis[0][\"plot_label\"])\n",
+    "plt.legend()\n",
+    "\n",
+    "plt.subplot(122)\n",
+    "plt.plot(e3.x, e3[100], label=\"Diagnostic\", c=\"tab:blue\")\n",
+    "plt.title(\"Using Diagnostic\")\n",
+    "plt.xlabel(e3.axis[0][\"plot_label\"])\n",
+    "plt.legend()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If we want to load all the data in memory, we can use the `load_all` method, which will load all the data in memory. This is useful to study how diagnostics vary in time, for example. \n",
+    "\n",
+    "The data is stored in the `data` attribute of the `Diagnostic` class. \n",
+    "\n",
+    "If we want to unload the data from memory, we can use the `unload` method."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "From now on, I'll only use `sim[diagnostic]` to show what can be done with `Diagnostic` objects, but remember that you can access the `Diagnostic` object directly if you want to use the `load_all`, `unload`, `time`, `x`, and `axis` attributes."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sim[\"e3\"].load_all()\n",
+    "\n",
+    "# now, the data is loaded in memory\n",
+    "print(sim[\"e3\"].data.shape) # (n_steps, nx)\n",
+    "\n",
+    "sim[\"e3\"].unload()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Since diagnostics have operator overloading, we can easily manipulate the data, even when it is not loaded in memory. For example, we can do `sim['vfl1'] + sim['e1']` to get the sum of the two diagnostics, or `sim['vfl1'] / sim['e1']` to get the division of the two diagnostics.\n",
+    "\n",
+    "When operations are done, a new `Diagnostic` is created, with the new data. This new `Diagnostic` can be accessed through the indexing syntax, and the data can be loaded in memory using the `load_all` method."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sum_of_diag = sim[\"electrons\"][\"T11\"] + sim[\"electrons\"][\"vfl1\"] \n",
+    "\n",
+    "print(sum_of_diag)\n",
+    "print(sum_of_diag.__dict__.keys())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can use the method of the `Diagnostic` class as usual, for example, `load_all`, and `unload`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# we can load all the data at once\n",
+    "sum_of_diag.load_all()\n",
+    "print(sum_of_diag.data.shape) # (n_steps, nx)\n",
+    "sum_of_diag.unload()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "And accessing a specific time step of the new `Diagnostic` is done through indexing, as usual."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plt.figure(figsize=(12,4))\n",
+    "plt.subplot(121)\n",
+    "plt.plot(sum_of_diag.x, sum_of_diag[100], label=\"T11 + vfl1\", c=\"tab:orange\")\n",
+    "plt.title(\"Diagnostic from sum of two diagnostics\")\n",
+    "plt.xlabel(sum_of_diag.axis[0][\"plot_label\"])\n",
+    "plt.legend()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This is really useful when we want a quantity that OSIRIS doesn't provide. For example, when the pressure is adiabatic, we can calculate the pressure using the formula `P = n * T`, where `P` is the pressure, `n` is the density, and `T` is the temperature. We can calculate the pressure using the formula `P = n * T` using the `Diagnostic` class, and then use the pressure to calculate the adiabatic index `gamma = 5/3` using the formula `gamma = P / (n * T)`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "nT = -1*sim[\"electrons\"][\"T11\"]*sim[\"electrons\"][\"charge\"] # -1 because we are dealing with electrons"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plt.figure(figsize=(6,4))\n",
+    "plt.plot(nT.x, nT[100], label=r\"$n_eT_{11}$\", c=\"tab:green\")\n",
+    "plt.title(r\"$n_eT_{11}$\")\n",
+    "plt.xlabel(nT.axis[0][\"plot_label\"])\n",
+    "plt.legend()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If the `load_all` method is called before the operations, the whole data will be stored in the new quantity."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sim[\"electrons\"][\"vfl1\"].load_all()\n",
+    "sim[\"electrons\"][\"charge\"].load_all()\n",
+    "\n",
+    "v_times_charge = sim[\"electrons\"][\"vfl1\"]*sim[\"electrons\"][\"charge\"]\n",
+    "\n",
+    "print(v_times_charge)\n",
+    "print(v_times_charge.__dict__.keys())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The whole data is computed if stored in the diagnostics before the operations"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(v_times_charge.data.shape)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "And it can be unloaded from memory using the `unload` method."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "v_times_charge.unload()\n",
+    "\n",
+    "# print something that checks that data is none\n",
+    "print(\"Is `v_times_charge.data` None?\", v_times_charge._data is None)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "tese-env",
+   "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.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}