osiris-utils 1.2.2__tar.gz → 1.2.4__tar.gz

osiris_utils-1.2.4/CONTRIBUTING.rst

@@ -0,0 +1,276 @@
+Contributing to OSIRIS Utils
+============================
+
+Thank you for contributing!
+
+This document contains guidelines (not strict rules) for contributing to
+**osiris_utils**. If something here doesn't fit your use case, use your best
+judgment — and feel free to open an issue to discuss improvements.
+
+Reporting Bugs
+~~~~~~~~~~~~~~
+
+How do I submit a good bug report?
+----------------------------------
+
+Bugs are tracked as GitHub `issues <https://github.com/joaopedrobiu6/osiris_utils/issues/>`_.
+
+To help maintainers reproduce (and fix) the problem quickly, please include:
+
+- **A clear and descriptive title**.
+- **Exact steps to reproduce**, in order.
+- **A minimal example** (copy/pasteable snippet) whenever possible.
+- **What you observed**, including the full traceback or error message.
+- **What you expected to happen**, and why.
+- **Relevant context**, such as:
+  - OS / Python version
+  - osiris_utils version or commit hash
+  - input deck details if relevant
+- **Plots** if the bug is about “wrong-looking” physics or unexpected results.
+
+If the bug involves post-processing or arithmetic with diagnostics, it helps a
+lot to include a small snippet like:
+
+.. code-block:: python
+
+   import osiris_utils as ou
+   sim = ou.Simulation("path/to/input_deck.txt")
+
+   # reproduce here
+   diag = sim["electrons"]["n"]
+   out = diag[0]
+   print(out.shape, out.dtype)
+
+Adding Post-Processing routines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Post-processing routines in **osiris_utils** are implemented as wrappers around
+the existing ``Simulation`` / ``Diagnostic`` interface.
+
+**Core idea**
+
+- Indexing must behave consistently across all diagnostics:
+
+  - ``diag[i]`` returns a single timestep ``np.ndarray``
+  - ``diag[i:j]`` returns a stacked array over time (shape ``(t, ...)``)
+  - ``diag[i, :, 10:20]`` must work (tuple indexing with spatial slicing)
+
+- Post-processed diagnostics should remain compatible with diagnostic operations:
+
+  - ``diag + other``, ``diag * other``, etc.
+
+- Spatial slicing should be efficient when possible: pass the ``data_slice`` down
+  to the base diagnostic (so HDF5 can load only the requested region).
+
+The recommended structure is:
+
+1) ``NameOfPostProcess_Simulation`` (simulation wrapper)
+2) ``NameOfPostProcess_Diagnostic`` (diagnostic wrapper)
+3) ``NameOfPostProcess_Species_Handler`` (species wrapper)
+
+1) Simulation-level wrapper: ``NameOfPostProcess_Simulation``
+-------------------------------------------------------------
+
+Implement a wrapper class that behaves like a ``Simulation``.
+
+**Requirements**
+
+- Inherits from ``PostProcess``
+- Stores the wrapped simulation in ``self._simulation``
+- Implements ``__getitem__`` that:
+
+  - returns a *species handler* when ``key`` is a species name
+  - returns a *post-processed diagnostic* when ``key`` is a quantity name
+
+- Uses caches (dicts) to avoid rebuilding wrappers repeatedly
+
+Typical skeleton:
+
+.. code-block:: python
+
+   class MyPost_Simulation(PostProcess):
+       def __init__(self, simulation: Simulation, ...):
+           super().__init__("MyPost", simulation)
+           self._computed = {}
+           self._species_handler = {}
+
+       def __getitem__(self, key):
+           if key in self._simulation._species:
+               if key not in self._species_handler:
+                   self._species_handler[key] = MyPost_Species_Handler(self._simulation[key], ...)
+               return self._species_handler[key]
+
+           if key not in self._computed:
+               self._computed[key] = MyPost_Diagnostic(self._simulation[key], ...)
+           return self._computed[key]
+
+**Note on “chainable” post-processes**
+
+Some post-processes (e.g. derivatives) should be chainable:
+
+.. code-block:: python
+
+   d1 = ou.Derivative_Simulation(sim, "x1")
+   d2 = ou.Derivative_Simulation(d1, "t")
+
+If your post-process needs to be chainable, avoid hard checks like:
+
+- ``isinstance(simulation, Simulation)``
+
+Instead, validate by capability:
+
+- has ``__getitem__``
+- has ``species`` or ``_species``
+
+2) Diagnostic-level wrapper: ``NameOfPostProcess_Diagnostic``
+-------------------------------------------------------------
+
+This class performs the actual post-processing while still behaving like a
+``Diagnostic``.
+
+**Requirements**
+
+- Inherits from ``Diagnostic``
+- Wraps a base diagnostic in ``self._diag``
+- Copies relevant metadata (e.g. ``_dt``, ``_dx``, ``_dim``, ``_maxiter``, etc.)
+- Implements:
+
+  - ``load_all()``: eager computation into ``self._data`` (shape ``(t, ...)``)
+  - ``_frame(index, data_slice=None)``: lazy single-timestep computation
+
+**Important:** you generally do **not** need to implement ``__getitem__``.
+The base ``Diagnostic.__getitem__`` already supports:
+
+- int indexing
+- time slices
+- tuple indexing ``(time_index, spatial_slices...)``
+
+and it calls:
+
+- ``self._frame(time_index, data_slice=data_slice)``
+
+So the minimal contract is:
+
+.. code-block:: python
+
+   class MyPost_Diagnostic(Diagnostic):
+       def load_all(self) -> np.ndarray:
+           ...
+
+       def _frame(self, index: int, data_slice: tuple | None = None) -> np.ndarray:
+           ...
+
+**Shape conventions**
+
+- ``load_all()`` returns ``(t, x, y, z)`` (or lower dimensions depending on ``dim``)
+- ``_frame()`` returns one timestep ``(x, y, z)`` (or lower dimensions)
+
+**Slicing support**
+
+If your base diagnostic supports efficient disk slicing, pass it through:
+
+.. code-block:: python
+
+   f = self._diag._frame(index, data_slice=data_slice)
+
+That ensures ``diag[10, :, 100:200]`` loads only the requested region.
+
+3) Species handler: ``NameOfPostProcess_Species_Handler``
+---------------------------------------------------------
+
+Species handlers are thin wrappers for dictionary-like access.
+
+**Requirements**
+
+- Does **not** inherit from anything
+- Stores the wrapped species handler in ``self._species_handler``
+- Lazily builds post-processed diagnostics per key and caches them
+
+Example:
+
+.. code-block:: python
+
+   class MyPost_Species_Handler:
+       def __init__(self, species_handler, ...):
+           self._species_handler = species_handler
+           self._computed = {}
+
+       def __getitem__(self, key):
+           if key not in self._computed:
+               self._computed[key] = MyPost_Diagnostic(self._species_handler[key], ...)
+           return self._computed[key]
+
+Rules and common pitfalls
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- **Indexing should return only** ``np.ndarray``.
+  If you need multiple arrays (e.g., MFT average + fluctuations), create
+  auxiliary diagnostic classes and expose them via an additional layer:
+
+  .. code-block:: python
+
+     mft = ou.MFT_Simulation(sim, axis=1)["e3"]
+     avg = mft["avg"][0]
+     flt = mft["delta"][0]
+
+- **Avoid overriding ``Diagnostic.__getitem__``**.
+  If you override it, you must re-implement tuple slicing and time slicing
+  correctly, or indexing will break in subtle ways.
+
+- **Implement ``_frame(index, data_slice=None)``** for lazy access.
+  This is what enables:
+
+  - tuple indexing and spatial slicing
+  - arithmetic operation diagnostics (``diag + other``)
+  - consistent interaction with ``load_all``
+
+- **Time FFT cannot be computed from a single timestep**.
+  If your transform includes axis 0 (time), you must require ``load_all()``
+  (or implement a different algorithm explicitly designed for streaming).
+  A “per-timestep” FFT can only work for *spatial* axes.
+
+Consistent usage examples
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import osiris_utils as ou
+
+   sim = ou.Simulation("path/to/input_deck.txt")
+
+   pp = MyPost_Simulation(sim, ...)
+
+   # Non-species diagnostic
+   arr = pp["e3"][10]
+
+   # Species diagnostic
+   arr = pp["electrons"]["n"][10]
+
+   # Spatial slicing
+   arr = pp["e3"][10, :, 100:200]
+   arr = pp["electrons"]["n"][0:10, :, 50:]
+
+Pull Requests
+~~~~~~~~~~~~~
+
+General expectations for PRs:
+
+- Keep PRs focused: one feature/fix per PR if possible.
+- Include an explanation of *why* the change is needed (not only what changed).
+- If you introduce a new post-process:
+  - follow the structure described above
+  - include at least a small usage example
+  - add/update documentation if user-facing behavior changes
+- If the PR changes physics / normalization / conventions, include a plot or a
+  small validation test case.
+
+If you're unsure about design choices (especially around performance or API
+consistency), open an issue first to discuss.
+
+Contact
+~~~~~~~
+
+If you need help, open an issue or contact João Biu via email:
+``joaopedrofbiu@tecnico.ulisboa.pt``
+or GitHub:
+``https://github.com/joaopedrobiu6``

{osiris_utils-1.2.2/osiris_utils.egg-info → osiris_utils-1.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: osiris_utils
-Version: 1.2.2
+Version: 1.2.4
 Summary: Utilities to manipulate and visualise OSIRIS plasma PIC output data
 Author-email: João Pedro Ferreira Biu <joaopedrofbiu@tecnico.ulisboa.pt>
 License: MIT

osiris_utils-1.2.4/docs/source/api/postprocess.rst

@@ -0,0 +1,380 @@
+Post-Processing Framework
+=========================
+
+.. _postprocessing:
+
+The ``osiris_utils`` package provides a lightweight framework for post-processing OSIRIS simulation data.
+Post-processors are implemented as wrappers around the existing ``Simulation`` / ``Diagnostic`` interface so that:
+
+- indexing works the same way everywhere (lazy, sliceable, tuple-sliceable)
+- arithmetic between diagnostics keeps working (``+``, ``-``, ``*``, ``/``, etc.)
+- post-processors can be chained when it makes sense (e.g., derivatives)
+
+This page documents the framework and the main post-processors currently available.
+
+
+PostProcess Base Class
+----------------------
+
+.. _postprocess-class:
+
+.. autoclass:: osiris_utils.postprocessing.postprocess.PostProcess
+   :members:
+   :special-members: __init__
+   :show-inheritance:
+   :noindex:
+
+The ``PostProcess`` class is the base class for all simulation-level post-processors.
+
+**Design goals**
+
+A post-processor should behave like a ``Simulation``:
+
+- ``pp["e3"]`` returns a diagnostic-like object (usually a ``Diagnostic`` subclass)
+- ``pp["electrons"]["n"]`` returns a species diagnostic
+- it caches created wrappers so repeated access is cheap
+
+Most post-processors follow the same pattern:
+
+1. A simulation wrapper (``Something_Simulation``) inheriting from ``PostProcess``
+2. A diagnostic wrapper (``Something_Diagnostic``) inheriting from ``Diagnostic``
+3. An optional species handler (``Something_Species_Handler``) for species-dependent quantities
+
+
+Integration with OSIRIS Diagnostics
+-----------------------------------
+
+Post-processors are designed to work seamlessly with the OSIRIS diagnostic system:
+
+- **Chaining (when appropriate)**: some post-processors can wrap other post-processors
+  (e.g., derivatives of already-derived quantities).
+- **Compatibility with visualization**: results remain ``Diagnostic``-like and can be plotted the same way.
+- **Uniform indexing contract**:
+
+  - ``diag[i]`` returns a single timestep ``np.ndarray`` (shape ``(x, y, z)`` depending on dimension)
+  - ``diag[i:j]`` returns a stacked time array (shape ``(t, x, y, z)``)
+  - ``diag[i, :, 100:200]`` uses tuple indexing (time index + spatial slices)
+
+**Important implementation note**
+
+The base ``Diagnostic.__getitem__`` already implements:
+
+- int and slice time indexing
+- tuple indexing (time + spatial slices)
+- fast path for in-memory data
+
+So post-processed diagnostics should generally implement:
+
+- ``load_all()`` to build ``self._data`` (shape includes time)
+- ``_frame(index, data_slice=None)`` to return a single timestep lazily (shape excludes time)
+
+You usually **do not** need to override ``__getitem__`` in post-processed diagnostics.
+
+
+Derivative Post-Processing
+==========================
+
+.. _derivative-api:
+
+The ``Derivative_Simulation`` module provides tools for computing time and spatial derivatives of diagnostics.
+
+Derivative_Simulation Class
+---------------------------
+
+.. autoclass:: osiris_utils.postprocessing.derivative.Derivative_Simulation
+   :members:
+   :special-members: __init__, __getitem__
+   :show-inheritance:
+   :noindex:
+
+``Derivative_Simulation`` behaves like an operator acting on all diagnostics inside a simulation:
+
+- wraps a ``Simulation`` (or a compatible post-process wrapper)
+- returns derivative diagnostics on demand
+- supports species and non-species diagnostics
+- supports lazy evaluation and efficient spatial slicing
+- may be chained (e.g., derivative of a derivative)
+
+**Derivative types**
+
+- ``t``  : time derivative :math:`\\partial/\\partial t`
+- ``x1`` : spatial derivative :math:`\\partial/\\partial x_1`
+- ``x2`` : spatial derivative :math:`\\partial/\\partial x_2`
+- ``x3`` : spatial derivative :math:`\\partial/\\partial x_3`
+- ``xx`` : second derivative in two spatial axes (mixed or repeated), e.g. :math:`\\partial^2/\\partial x_i\\partial x_j`
+- ``xt`` : :math:`\\partial/\\partial x` of :math:`\\partial/\\partial t`
+- ``tx`` : :math:`\\partial/\\partial t` of :math:`\\partial/\\partial x`
+
+**Usage examples**
+
+.. code-block:: python
+
+   from osiris_utils.data import Simulation
+   from osiris_utils.postprocessing import Derivative_Simulation
+
+   sim = Simulation("/path/to/input/deck.inp")
+
+   # Spatial derivative d/dx1 of every diagnostic
+   dx1 = Derivative_Simulation(sim, "x1")
+
+   dE1_dx1 = dx1["e1"]
+   dvfl1_dx1 = dx1["electrons"]["vfl1"]
+
+   # Single timestep
+   arr = dE1_dx1[5]
+
+   # Time slice
+   arr_t = dE1_dx1[5:10]
+
+   # Spatial slicing (efficient if underlying diagnostic supports it)
+   arr_slice = dE1_dx1[5, :, 100:200]
+
+   # Full in-memory derivative (use only when needed)
+   dE1_dx1.load_all()
+
+**Implementation details and accuracy**
+
+- Spatial derivatives use finite differences (2nd or 4th order depending on configuration).
+- Time derivatives must account for OSIRIS ``ndump``:
+
+  effective :math:`\\Delta t = dt \\times ndump`
+
+- For mixed derivatives (``tx``, ``xt``), the implementation applies the corresponding operator ordering.
+
+**Performance tips**
+
+- Prefer indexing (lazy computation) when exploring data.
+- Use spatial slices to reduce IO and compute time.
+- Call ``load_all()`` only when you truly need the full time history in memory.
+
+
+Derivative_Diagnostic Class
+---------------------------
+
+.. autoclass:: osiris_utils.postprocessing.derivative.Derivative_Diagnostic
+   :members:
+   :special-members: __init__
+   :show-inheritance:
+   :noindex:
+
+A derivative diagnostic is a ``Diagnostic`` wrapper that computes derivatives lazily using ``_frame`` and can compute eagerly using ``load_all``.
+It preserves metadata (grid spacing, dimensions, etc.) from the original diagnostic and remains compatible with diagnostic arithmetic.
+
+
+Spectral Analysis with Fast Fourier Transform
+=============================================
+
+.. _fft-api:
+
+The ``FFT_Simulation`` module provides tools for computing power spectra using the Fast Fourier Transform (FFT).
+
+FFT_Simulation Class
+--------------------
+
+.. autoclass:: osiris_utils.postprocessing.fft.FFT_Simulation
+   :members:
+   :special-members: __init__, __getitem__
+   :show-inheritance:
+   :noindex:
+
+``FFT_Simulation`` is a simulation wrapper that returns ``FFT_Diagnostic`` objects.
+
+**Key points about FFT axes**
+
+- OSIRIS diagnostics loaded with ``load_all()`` have shape ``(t, x1, x2, x3)`` (depending on dimension).
+  In that case:
+  - axis ``0`` is time
+  - axes ``1,2,3`` are spatial
+
+- A *single timestep* returned by indexing has no time dimension, only spatial:
+  - axes become ``(x1, x2, x3)`` → numpy axes ``0,1,2``
+
+**Important constraint**
+
+- If the FFT includes the time axis (axis ``0``), you cannot compute it from a single timestep.
+  Time-domain FFT requires the full time series, therefore it requires ``load_all()`` on the FFT diagnostic.
+
+- Spatial FFTs *can* be computed per-timestep lazily.
+
+**Usage example**
+
+.. code-block:: python
+
+   from osiris_utils.data import Simulation
+   from osiris_utils.postprocessing import FFT_Simulation
+
+   sim = Simulation("/path/to/input/deck.inp")
+
+   # Spatial spectrum at each timestep (FFT along x1)
+   fft_x1 = FFT_Simulation(sim, 1)
+   e3_k = fft_x1["e3"]
+   k_spectrum_t10 = e3_k[10]  # OK: spatial FFT at timestep 10
+
+   # Dispersion-like spectrum (time + space) requires load_all
+   fft_wk = FFT_Simulation(sim, (0, 1))
+   e3_wk = fft_wk["e3"]
+   e3_wk.load_all()           # required
+   P = e3_wk.data             # power spectrum |FFT|^2
+
+
+FFT_Diagnostic Class
+--------------------
+
+.. autoclass:: osiris_utils.postprocessing.fft.FFT_Diagnostic
+   :members:
+   :special-members: __init__
+   :show-inheritance:
+   :noindex:
+
+A specialized diagnostic representing an FFT-based power spectrum.
+
+**Behavior**
+
+- ``load_all()`` computes the FFT over the requested axes (including time if axis 0 is included).
+- ``_frame(index, data_slice=None)`` computes a per-timestep FFT only for spatial axes.
+- The returned data is a **power spectrum** (typically :math:`|\\mathrm{FFT}|^2`) and is shifted using ``fftshift`` so that
+  zero frequency / wavenumber is centered.
+
+**Frequency / wavenumber arrays**
+
+- Use ``omega()`` for the time-frequency axis (when axis 0 was transformed and data is loaded).
+- Use ``k(axis=...)`` for spatial wavenumbers.
+- ``kmax`` reports the Nyquist wavenumber :math:`\\pi/\\Delta x` for the relevant spatial axes.
+
+
+Example: Dispersion relation (ω–k)
+----------------------------------
+
+.. code-block:: python
+
+   from osiris_utils.data import Simulation
+   from osiris_utils.postprocessing import FFT_Simulation
+   import numpy as np
+   import matplotlib.pyplot as plt
+
+   sim = Simulation("/path/to/input/deck.inp")
+
+   fft = FFT_Simulation(sim, (0, 1))
+   e1_fft = fft["e1"]
+   e1_fft.load_all()
+
+   omega = e1_fft.omega()      # angular frequency axis (shifted)
+   k1 = e1_fft.k(1)            # k for x1 axis (shifted)
+
+   P = np.log10(e1_fft.data + 1e-30)  # safer for plotting
+
+   plt.figure()
+   plt.pcolormesh(k1, omega, P, shading="auto")
+   plt.xlabel("k1")
+   plt.ylabel("ω")
+   plt.title("Dispersion-like spectrum: E1")
+   plt.show()
+
+
+Mean Field Theory Analysis
+==========================
+
+.. _mft-api:
+
+The Mean Field Theory (MFT) module provides tools for decomposing diagnostics into an average (mean) component and fluctuations along a chosen axis.
+
+MFT_Simulation Class
+--------------------
+
+.. autoclass:: osiris_utils.postprocessing.mft.MFT_Simulation
+   :members:
+   :special-members: __init__, __getitem__
+   :show-inheritance:
+   :noindex:
+
+The MFT decomposition returns a container-like diagnostic with two components:
+
+- ``"avg"``   : mean field :math:`\\langle A \\rangle`
+- ``"delta"`` : fluctuations :math:`\\delta A = A - \\langle A \\rangle`
+
+Usage example:
+
+.. code-block:: python
+
+   from osiris_utils.data import Simulation
+   from osiris_utils.postprocessing import MFT_Simulation
+
+   sim = Simulation("/path/to/input/deck.inp")
+
+   mft = MFT_Simulation(sim, 1)       # average along x1 direction
+   e1 = mft["e1"]
+
+   e1_avg = e1["avg"]
+   e1_delta = e1["delta"]
+
+   avg_t10 = e1_avg[10]
+   flt_t10 = e1_delta[10]
+
+
+MFT_Diagnostic Classes
+----------------------
+
+.. autoclass:: osiris_utils.postprocessing.mft.MFT_Diagnostic
+   :members:
+   :special-members: __init__, __getitem__
+   :show-inheritance:
+   :noindex:
+
+.. autoclass:: osiris_utils.postprocessing.mft.MFT_Diagnostic_Average
+   :members:
+   :special-members: __init__
+   :show-inheritance:
+   :noindex:
+
+.. autoclass:: osiris_utils.postprocessing.mft.MFT_Diagnostic_Fluctuations
+   :members:
+   :special-members: __init__
+   :show-inheritance:
+   :noindex:
+
+
+Field Centering
+===============
+
+.. _field-centering-api:
+
+The ``FieldCentering`` module provides tools to convert electromagnetic fields from the Yee mesh locations to cell centers.
+
+FieldCentering_Simulation Class
+-------------------------------
+
+.. autoclass:: osiris_utils.postprocessing.field_centering.FieldCentering_Simulation
+   :members:
+   :special-members: __init__, __getitem__
+   :show-inheritance:
+   :noindex:
+
+Field centering is a purely spatial operation and can be computed lazily per timestep.
+
+Usage example:
+
+.. code-block:: python
+
+   from osiris_utils.data import Simulation
+   from osiris_utils.postprocessing import FieldCentering_Simulation
+
+   sim = Simulation("/path/to/input/deck.inp")
+
+   centered = FieldCentering_Simulation(sim)
+
+   e1c = centered["e1"]
+   arr = e1c[10]              # centered field at timestep 10
+   arr_slice = e1c[10, :, :]  # supports spatial slicing
+
+
+FieldCentering_Diagnostic Class
+-------------------------------
+
+.. autoclass:: osiris_utils.postprocessing.field_centering.FieldCentering_Diagnostic
+   :members:
+   :special-members: __init__
+   :show-inheritance:
+   :noindex:
+
+This diagnostic wraps a field diagnostic and returns its cell-centered version. The implementation assumes periodic boundaries when using shifts/rolls.
+``