osiris-utils 1.1.6__py3-none-any.whl → 1.1.8__py3-none-any.whl

docs/source/index.rst

@@ -0,0 +1,35 @@
+.. osiris-utils documentation master file
+
+OSIRIS Utils Documentation
+==========================
+
+.. include:: ../../README.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Simulation and Diagnostic API:
+   :hidden:
+   
+   api/sim_diag
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Post-Processing API:
+   :hidden:
+
+   api/postprocess
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Utilities API:
+   :hidden:
+   
+   api/utilities
+
+.. toctree::
+   :maxdepth: 3
+   :caption: How to Contribute:
+   :hidden:
+
+   contrib
+

examples/edited-deck.1d

@@ -0,0 +1,107 @@
+simulation
+{
+	random_seed = BOTH CHANGED,
+	wall_clock_limit = "BOTH CHANGED",
+	wall_clock_check = 2000,
+	wall_clock_checkpoint = .true.,
+}
+
+node_conf
+{
+	node_number(1:1) = 4,
+	if_periodic(1:1) = .true.,
+}
+
+grid
+{
+	nx_p(1:1) = 500,
+	coordinates = "cartesian",
+}
+
+time_step
+{
+	dt = 0.0099,
+	ndump = 1,
+}
+
+restart
+{
+	if_restart = .false.,
+}
+
+space
+{
+	xmin(1:1) = 0.,
+	xmax(1:1) = 5.0,
+	if_move(1:1) = .false.,
+}
+
+time
+{
+	tmin = 0.0d0,
+	tmax = 2.5,
+}
+
+el_mag_fld
+{
+}
+
+emf_bound
+{
+	type(1:2,1) = "open", "open",
+}
+
+diag_emf
+{
+	ndump_fac = 1,
+	ndump_fac_ene_int = 1,
+	reports = "e1", "e2", "e3",
+}
+
+particles
+{
+	interpolation = "linear",
+	num_species = 1,
+}
+
+species
+{
+	name = "electrons",
+	num_par_max = 2048,
+	rqm = -1.0,
+	num_par_x(1:1) = 64,
+}
+
+udist
+{
+	uth_type = "thermal",
+	uth(1:3) = 0.01, 0.01, 0.01,
+}
+
+profile
+{
+	density = 1,
+	profile_type = "uniform",
+}
+
+spe_bound
+{
+}
+
+diag_species
+{
+	ndump_fac_ene = 1,
+	ndump_fac_temp = 1,
+	ndump_fac = 1,
+	reports = "charge",
+	rep_udist = "vfl1", "T11",
+}
+
+smooth
+{
+}
+
+diag_current
+{
+}
+

examples/example_Derivatives.ipynb

@@ -0,0 +1,167 @@
+{
+ "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": [
+    "# Derivatives using `Derivative_Simulation` object\n",
+    "\n",
+    "In this notebook we will show how to use the `Derivative_Simulation` object to compute derivatives of a function with respect to the time and space coordinates. \n",
+    "\n",
+    "As an example, we will compute the residual of the continuity equation of a thermal plasma, in the x-direction, this is, the LHS of:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "$$\n",
+    "\\frac{\\partial n}{\\partial t} + \\frac{\\partial}{\\partial x}(n v_1) = 0\n",
+    "$$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For this, we need the derivatives of the density `n` and the velocity `v1` with respect to the time and space coordinates. The `Derivative_Simulation` object will compute these derivatives using finite differences."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Initialize the simulation object:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sim = ou.Simulation(input_deck_path=\"example_data/thermal.1d\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Initialize the `Derivative_Simulation` objects with respect to the time and $x_1$ coordinate, since these are the derivatives that we want to compute."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "d_dt = ou.Derivative_Simulation(sim, \"t\")\n",
+    "d_dx1 = ou.Derivative_Simulation(sim, \"x1\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note that the derivative with respect to $x_1$ is applied not to one diagnostic, but to the product of two diagnostics. We can take advantage of the operations between diagnostics to compute this \"new\" diagnostic, the product of the density and the fluid velocity."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create a new diagnostic n * vfl1\n",
+    "nVfl1 = sim[\"electrons\"][\"n\"] * sim[\"electrons\"][\"vfl1\"] \n",
+    "# Add this to the simulation (electrons)\n",
+    "sim[\"electrons\"].add_diagnostic(nVfl1, \"nVfl1\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now that we have the diagnostics needed in our `Simulation` object, we can directly reconstruct the equation desired:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "continuity = d_dt[\"electrons\"][\"n\"] + d_dx1[\"electrons\"][\"nVfl1\"]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This is a new diagnostic, and we can now access to its iterations using indexing"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plt.figure(figsize=(8, 6))\n",
+    "plt.title(\"Continuity equation residuals\")\n",
+    "plt.xlabel(continuity.axis[0][\"plot_label\"])\n",
+    "\n",
+    "plt.plot(continuity.x, continuity[10], label=\"Continuity equation\")\n",
+    "plt.legend()\n",
+    "plt.xlim(continuity.x[0], continuity.x[-1])\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plt.plot(continuity.x, ou.integrate(continuity[10], continuity.dx), label=r\"$\\int \\partial_t n + \\partial_x( n v_{fl1}) dx$\")\n",
+    "plt.legend()\n",
+    "plt.xlim(continuity.x[0], continuity.x[-1])\n",
+    "plt.show()"
+   ]
+  }
+ ],
+ "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
+}

examples/example_FFT.ipynb

@@ -0,0 +1,235 @@
+{
+ "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": [
+    "## Initialize an object of the Simulation class\n",
+    "- The Simulation class takes the `simulation_folder`, this is, the file where the input deck is located.\n",
+    "- It can also take the `species` when we want to use quantities related to a specific species, such as velocities, charge, temperature, etc."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# In this case, since we only want to study the electric field, no species is needed\n",
+    "sim = ou.Simulation(input_deck_path=\"example_data/thermal.1d\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `Simulation` object acts as a container for the simulation diagnostics, that can be easily accessed from the `Simulation` object using a dictionary-like syntax\n",
+    "In this case, to access the component of the electric field in the z direction, we can use `sim['e3']`. This is a `Diagnostic` object, that loads the data as requested using a data generator, using indices to choose the time step - a lazy loading approach."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# This is a Diagnostic object\n",
+    "sim[\"e3\"]\n",
+    "\n",
+    "# This is also a Diagnostic object but initialized directly and not through the Simulation object\n",
+    "e3 = ou.Diagnostic(simulation_folder=\"example_data\")\n",
+    "e3.get_quantity(\"e3\")\n",
+    "\n",
+    "print(\"sim['e3'] class:\", sim[\"e3\"].__class__)\n",
+    "print(\"e3 class:\", e3.__class__)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The data of the diagnostic at a given index can be accessed by indexing the iteration number, e.g. `sim['e3'][0]` will return the electric field in the z direction at the first time step. The data is not stored in memory, but loaded from the file when requested, using a data generator (lazy loading). For example, to plot the electric field in the z direction at the 100th time step, we can use `sim['e3'][100]`, and use the other attributes of the `Diagnostic` object to get the time step, the grid, labels, etc."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plt.figure(figsize=(8, 3))\n",
+    "plt.plot(sim[\"e3\"].x, sim[\"e3\"][100])\n",
+    "plt.xlabel(sim[\"e3\"].axis[0][\"plot_label\"])\n",
+    "plt.title(rf\"${sim['e3'].label}$ @ $t = {sim['e3'].time(100)[0]:.2f}$ $[{sim['e3'].tunits}]$\")\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If we want to load the data of the diagnostic at all time steps, we can use the `load_all()` method of the `Diagnostic` object, e.g. `sim['e3'].load_all()` will load the electric field in the z direction at all time steps and store it in memory. This is useful when we want to do the FFT of the data in the time domain, for example. Using the method `unload()` we can clear the data from memory."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sim[\"e3\"].load_all()\n",
+    "print(sim[\"e3\"].data.shape)\n",
+    "\n",
+    "e3.load_all()\n",
+    "print(e3.data.shape)\n",
+    "\n",
+    "np.isclose(sim[\"e3\"].data, e3.data).all()\n",
+    "\n",
+    "sim[\"e3\"].unload()\n",
+    "e3.unload()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now we are going to use a post process on the simulation data and on the diagnostic. We can think of a `PostProcess` as an operator over the `Diagnostic`'s of the `Simulation`. We define it on the simulation, and to access a post-processed quantity of the simulation, we use the same dictionary-like syntax, e.g. `sim_fft[\"e3]` to access the FFT of the electric field in the z direction. \n",
+    "\n",
+    "The data is loaded in memory when requested, using a data generator, and can be accessed using the same indexing syntax, e.g. `sim_fft[\"e3\"][0]` to access the FFT of the electric field in the z direction at the first time step. The data can be loaded using the `load_all()` method, and cleared from memory using the `unload()` method.\n",
+    "\n",
+    "The post-processing classes inherit from the `PostProcess` class and the `Diagnostic` class, and can be used as a `Diagnostic` object, with the same attributes and methods, ensuring that operations between diagnostics and post-processes are consistent.\n",
+    "\n",
+    "Each diagnostic has a version to be applied to `Simulation` objects and another to be applied to `Diagnostic` objects. The first has the name `<name of post-process>`_Simulation, and the second has the name `<name of post-process>_Diagnostic`. For example, the post-process routines for Fast Fourier Transforms are called `FastFourierTransform_Diagnostic` and `FFT_Diagnostic`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sim_fft = ou.FFT_Simulation(sim, (0, 1)) # \"operator\" FFT applied to Simulation object, axis 0 and 1\n",
+    "\n",
+    "e3_fft = ou.FFT_Diagnostic(e3, (0, 1)) # \"operator\" FFT applied to Diagnostic object, axis 0 and 1"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sim_fft[\"e3\"][100] # this will only return the kx axis, since we are only requesting the 100th time step of the FFT of e3\n",
+    "\n",
+    "e3_fft[100] # this will return the kx and ky axis, since we are only requesting the 100th time step of the FFT of e3\n",
+    "\n",
+    "np.isclose(sim_fft[\"e3\"][100], e3_fft[100]).all() # They are the same!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Since my goal is to plot the dispersion relation, I will need to use `.load_all()` to load all the time steps, and have access to the data in the frequency domain."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sim_fft[\"e3\"].load_all()\n",
+    "e3_fft.load_all()\n",
+    "\n",
+    "np.isclose(sim_fft[\"e3\"].data, e3_fft.data).all() # They are the same!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can now plot!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plt.imshow(sim_fft[\"e3\"].data, origin = 'lower', norm=LogNorm(vmin = 1e-7, vmax = 0.01),\n",
+    "           extent = ( -sim_fft[\"e3\"].kmax, sim_fft[\"e3\"].kmax, -sim_fft[\"e3\"].omega_max, sim_fft[\"e3\"].omega_max ),\n",
+    "           aspect = 'auto', cmap = 'gray')\n",
+    "\n",
+    "# Plotting the dispersion relation\n",
+    "k = np.linspace(-e3_fft.kmax, e3_fft.kmax, num = 512)\n",
+    "w=np.sqrt(1 + k**2)\n",
+    "plt.plot( k, w, label = r\"$\\omega^2 = \\omega_p^2 + k^2c^2$\", color = 'r', ls = '-.' )\n",
+    "plt.xlim(0, e3_fft.kmax)\n",
+    "plt.ylim(0, e3_fft.omega_max)\n",
+    "\n",
+    "plt.xlabel(r\"$k$ $[\\omega_e/c]$\")\n",
+    "plt.ylabel(r\"$\\omega$ $[\\omega_e]$\")\n",
+    "plt.legend()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plt.imshow(e3_fft.data, origin = 'lower', norm=LogNorm(vmin = 1e-7, vmax = 0.01),\n",
+    "           extent = ( -e3_fft.kmax, e3_fft.kmax, -e3_fft.omega_max, e3_fft.omega_max ),\n",
+    "           aspect = 'auto', cmap = 'gray')\n",
+    "\n",
+    "# Plotting the dispersion relation\n",
+    "k = np.linspace(-e3_fft.kmax, e3_fft.kmax, num = 512)\n",
+    "w=np.sqrt(1 + k**2)\n",
+    "plt.plot( k, w, label = r\"$\\omega^2 = \\omega_p^2 + k^2c^2$\", color = 'r', ls = '-.' )\n",
+    "plt.xlim(0, e3_fft.kmax)\n",
+    "plt.ylim(0, e3_fft.omega_max)\n",
+    "\n",
+    "plt.xlabel(r\"$k$ $[\\omega_e/c]$\")\n",
+    "plt.ylabel(r\"$\\omega$ $[\\omega_e]$\")\n",
+    "plt.legend()\n",
+    "plt.show()"
+   ]
+  }
+ ],
+ "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
+}