osiris-utils 1.1.10a0__py3-none-any.whl → 1.2.1__py3-none-any.whl

benchmarks/benchmark_hdf5_io.py

@@ -0,0 +1,46 @@
+import time
+
+import osiris_utils as ou
+
+
+def benchmark_hdf5_io():
+    """Benchmark HDF5 file opening and reading."""
+    print("=" * 60)
+    print("Benchmarking HDF5 I/O Performance")
+    print("=" * 60)
+
+    filepath = "examples/example_data/MS/FLD/e3/e3-000100.h5"
+
+    # Warm-up (file may be cached by OS)
+    _ = ou.OsirisGridFile(filepath)
+
+    # Benchmark multiple loads
+    n_iterations = 100
+    times = []
+
+    print(f"\nLoading file {n_iterations} times...")
+    for _ in range(n_iterations):
+        start = time.time()
+        data = ou.OsirisGridFile(filepath)
+        times.append(time.time() - start)
+
+    avg_time = sum(times) / len(times)
+    min_time = min(times)
+    max_time = max(times)
+
+    print("\nResults:")
+    print(f"  Average load time: {avg_time * 1000:.2f}ms")
+    print(f"  Min load time: {min_time * 1000:.2f}ms")
+    print(f"  Max load time: {max_time * 1000:.2f}ms")
+    print(f"  Data shape: {data.data.shape}")
+    print(f"  Data size: {data.data.nbytes / 1024:.1f} KB")
+
+    # Calculate throughput
+    throughput = (data.data.nbytes / 1024 / 1024) / avg_time
+    print(f"  Throughput: {throughput:.1f} MB/s")
+
+    print("\n" + "=" * 60)
+
+
+if __name__ == "__main__":
+    benchmark_hdf5_io()

benchmarks/benchmark_load_all.py

@@ -0,0 +1,54 @@
+import sys
+import time
+
+import osiris_utils as ou
+
+# Use example data if available
+data_path = "examples/example_data"
+
+
+def benchmark_loading():
+    """Benchmark parallel vs sequential loading."""
+    _ = f"{data_path}/MS/FLD/e3"
+
+    print("=" * 60)
+    print("Benchmarking Diagnostic.load_all() performance")
+    print("=" * 60)
+
+    # Test with sequential loading
+    print("\n1. Testing SEQUENTIAL loading...")
+    d = ou.Diagnostic(simulation_folder=data_path)
+    d.get_quantity("e3")
+
+    start = time.time()
+    data_seq = d.load_all(use_parallel=False)
+    seq_time = time.time() - start
+    print(f"   Sequential time: {seq_time:.3f}s for {len(d)} timesteps")
+    print(f"   Data shape: {data_seq.shape}")
+
+    # Unload to test parallel
+    d.unload()
+
+    # Test with parallel loading
+    print("\n2. Testing PARALLEL loading...")
+    start = time.time()
+    data_par = d.load_all(use_parallel=True)
+    par_time = time.time() - start
+    print(f"   Parallel time: {par_time:.3f}s for {len(d)} timesteps")
+    print(f"   Data shape: {data_par.shape}")
+
+    # Calculate speedup
+    speedup = seq_time / par_time if par_time > 0 else 0
+    print(f"\n✓ Speedup: {speedup:.2f}x faster with parallel loading")
+    print(f"  Time saved: {seq_time - par_time:.3f}s ({100 * (seq_time - par_time) / seq_time:.1f}%)")
+
+    print("\n" + "=" * 60)
+
+
+if __name__ == "__main__":
+    try:
+        benchmark_loading()
+    except Exception as e:
+        print(f"Error running benchmark: {e}")
+        print("Make sure example_data is available in the examples directory")
+        sys.exit(1)

docs/source/_static/custom.css

@@ -1,6 +1,7 @@
 /* Sidebar background */
 .wy-nav-side {
-  background: #88cbf8;  /* Change to your preferred color */
+  background: #88cbf8;
+  /* Change to your preferred color */
 }
 
 /* Sidebar link color */
@@ -18,12 +19,17 @@
   background: #2f93f0;
 }
 
-.wy-menu-vertical li.current > a {
+.wy-menu-vertical li.current>a {
   background: #aeecff;
 }
 
 /* Header (H1, H2, etc.) colors */
-h1, h2, h3, h4, h5, h6 {
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
   color: #57bafb;
 }
 
@@ -43,11 +49,21 @@ a:hover {
 
 /* Keep your existing table width overrides */
 @media screen and (min-width: 767px) {
-.wy-table-responsive table td {
-  white-space: normal !important;
-}
+  .wy-table-responsive table td {
+    white-space: normal !important;
+  }
 
-.wy-table-responsive {
-  overflow: visible !important;
+  .wy-table-responsive {
+    overflow: visible !important;
+  }
 }
+
+/* Small easter-egg logo sizing */
+.wy-side-nav-search .logo img,
+.wy-side-nav .logo img,
+.rst-sidebar .logo img,
+.logo img {
+  max-width: 80px;
+  margin: 6px 8px;
+  height: auto;
 }

docs/source/api/decks.rst

@@ -0,0 +1,48 @@
+Deck Handling
+=============
+
+This section documents the utilities for handling OSIRIS input decks.
+
+InputDeckIO
+-----------
+
+.. autoclass:: osiris_utils.decks.decks.InputDeckIO
+   :members:
+   :special-members: __init__, __getitem__
+   :undoc-members:
+   :noindex:
+
+   Class to handle parsing and modifying OSIRIS input decks.
+
+   **Key Features:**
+
+   * Parse input decks into python objects
+   * Modify parameters programmatically
+   * Save modified decks to new files
+   * Automatic handling of OSIRIS syntax idiosyncrasies
+
+   **Usage Example:**
+
+   .. code-block:: python
+
+       from osiris_utils import InputDeckIO
+
+       # Load an input deck
+       deck = InputDeckIO("osiris.inp")
+
+       # Get simulation dimension
+       print(f"Simulation dimension: {deck.dim}")
+
+       # Modify a parameter
+       # (Assuming there is a 'time_step' section with 'dt' parameter)
+       deck.set_param("time_step", "dt", "0.05")
+
+       # Save to a new file
+       deck.print_to_file("osiris_modified.inp")
+
+Coordinate Conversion
+---------------------
+
+.. function:: osiris_utils.decks.decks.deval
+
+   .. autofunction:: osiris_utils.decks.decks.deval

docs/source/api/postprocess.rst

@@ -86,7 +86,7 @@ Derivative_Simulation Class
        from osiris_utils.postprocessing import Derivative_Simulation
        
        # Create a simulation interface
-       sim = Simulation('/path/to/input/deck')
+       sim = Simulation('/path/to/input/deck.inp')
        
        # Create a derivative processor for x₁ derivatives
        dx1 = Derivative_Simulation(sim, 'x1')
@@ -206,7 +206,7 @@ This example shows how to compute the z-component of curl(B):
     from osiris_utils.postprocessing import Derivative
     
     # Setup
-    sim = Simulation('/path/to/input/deck')
+    sim = Simulation('/path/to/input/deck.inp')
     dx1 = Derivative_Simulation(sim, 'x1')
     dx2 = Derivative_Simulation(sim, 'x2')
 
@@ -227,7 +227,7 @@ This example shows how to compute the divergence of E:
     from osiris_utils.postprocessing import Derivative_Diagnostic
     
     # Setup
-    e1 = Diagnostic('/path/to/folder', Species, "path/to/input/deck")
+    e1 = Diagnostic('/path/to/folder', species=None, input_deck="/path/to/input/deck.inp")
     
     # Create derivative processor for x₁ and x₂ derivatives
     de1_dx1 = Derivative_Diagnostic(e1, 'x1')
@@ -281,7 +281,7 @@ FFT_Simulation Class
        from osiris_utils.postprocessing import FFT_Simulation
        
        # Create a simulation interface
-       sim = Simulation('/path/to/input/deck')
+       sim = Simulation('/path/to/input/deck.inp')
        
        # Create an FFT processor for the first spatial dimension
        fft = FFT_Simulation(sim, 1)
@@ -379,7 +379,7 @@ This example shows how to compute and visualize a dispersion relation:
     import matplotlib.pyplot as plt
     
     # Setup
-    sim = Simulation('/path/to/input/deck')
+    sim = Simulation('/path/to/input/deck.inp')
     
     # Create FFT processor for both time and space
     # We'll do a 2D FFT - time (axis 0) and x1 (axis 1)
@@ -467,7 +467,7 @@ MFT_Simulation Class
        from osiris_utils.postprocessing import MFT_Simulation
        
        # Create a simulation interface
-       sim = Simulation('/path/to/input/deck')
+       sim = Simulation('/path/to/input/deck.inp')
        
        # Create MFT analyzer for x₁ direction (axis=1)
        mft = MFT_Simulation(sim, 1)
@@ -602,8 +602,72 @@ For large datasets, consider these performance optimizations:
    * Only call `load_all()` when analyzing the full time evolution
    * Use `delete()` and `delete_all()` to free memory when finished with results
 
-2. **Computation Efficiency**:
+   2. **Computation Efficiency**:
 
    * Averaging is computationally inexpensive compared to other operations
    * For 2D/3D data, consider which axis to average along based on your physics
-   * For iterative analysis, calculate fluctuations only when needed
+   * For iterative analysis, calculate fluctuations only when needed
+
+Field Centering
+===============
+
+.. _field-centering-api:
+
+The `FieldCentering` module provides tools to center fields on the grid cells, converting from the Yee mesh positions to cell centers.
+
+FieldCentering_Simulation Class
+-------------------------------
+
+.. autoclass:: osiris_utils.postprocessing.field_centering.FieldCentering_Simulation
+   :members:
+   :special-members: __init__, __getitem__
+   :show-inheritance:
+   :noindex:
+
+   Post-processor for centering electromagnetic fields.
+
+   The FieldCentering_Simulation class provides a convenient interface for centering fields from the Yee mesh to cell centers.
+
+   **Key Features:**
+
+   * Centers fields from Yee mesh to cell centers
+   * Handles periodic boundaries
+   * Supports 1D, 2D, and 3D simulations
+   * Lazy evaluation
+
+   **Usage Examples:**
+
+   .. code-block:: python
+
+       from osiris_utils.data import Simulation
+       from osiris_utils.postprocessing import FieldCentering_Simulation
+
+       # Create a simulation interface
+       sim = Simulation('/path/to/input/deck.inp')
+
+       # Create a field centering processor
+       centered_sim = FieldCentering_Simulation(sim)
+
+       # Get centered E1 field
+       e1_centered = centered_sim['e1']
+
+       # Access specific timestep (interpolated on-demand)
+       timestep_10 = e1_centered[10]
+
+FieldCentering_Diagnostic Class
+-------------------------------
+
+.. autoclass:: osiris_utils.postprocessing.field_centering.FieldCentering_Diagnostic
+   :members:
+   :special-members: __init__, __getitem__
+   :show-inheritance:
+   :noindex:
+
+   Specialized diagnostic that represents the centered field.
+
+   This class handles the actual interpolation while maintaining the Diagnostic interface.
+
+   **Key Methods:**
+
+   * ``load_all()`` - Compute and store the complete centered field
+   * ``__getitem__(index)`` - Compute centered field for a specific timestep on-demand

docs/source/api/sim_diag.rst

@@ -36,8 +36,8 @@ Simulation Class
    
        from osiris_utils.data import Simulation
        
-       # Create a simulation interface for electron data
-       sim = Simulation('path/to/simulation', "name_of_input_deck")
+       # Create a simulation interface
+       sim = Simulation('path/to/simulation/osiris.inp')
        
        # Access the E1 field diagnostic (doesn't load data yet) - this is a Diagnostic object
        # Since it is a diagnostic not related with the species, the species argument is not needed
@@ -63,7 +63,7 @@ Simulation Class
        b3 = sim['b3']
        
        # Load specific timesteps
-       e1[10:20]  # Load timesteps 10-19
+       e1[10:20, 0:10]  # Load timesteps 10-19 and x1 0-10
        
        # Clean up to free memory
        sim.delete_diagnostic('e1')
@@ -110,7 +110,7 @@ Diagnostic Base Class
    
    **Key Attributes:**
    
-   * ``species`` - The plasma species being analyzed (Specie object)
+   * ``species`` - The plasma species being analyzed (Species object)
    * ``dx`` - Grid spacing in each direction
    * ``nx`` - Number of grid points in each direction
    * ``x`` - Grid coordinates
@@ -134,7 +134,9 @@ Diagnostic Base Class
    .. code-block:: python
    
        # Create diagnostic for electron charge
-       diag = Diagnostic("/path/to/simulation", species)
+       # Note: Use Simulation class for easier access instead of Diagnostic directly
+       electrons = Species("electrons", rqm=-1, q=-1)
+       diag = Diagnostic("/path/to/simulation", species=electrons)
        diag.get_quantity("charge")
        
        # Access specific timestep (without loading all data)
@@ -151,7 +153,7 @@ Diagnostic Base Class
    .. code-block:: python
    
        # Operations between diagnostics
-       sim = Simulation("/path/to/simulation", species)
+       sim = Simulation("/path/to/simulation/osiris.inp")
        e1 = sim["e1"]
        vfl1 = sim["electron"]["vfl1"]
        
@@ -221,7 +223,7 @@ One of the most powerful features of the Diagnostic system is that new diagnosti
 .. code-block:: python
 
     # Create base diagnostics
-    sim = Simulation("/path/to/simulation", "file_input_deck")
+    sim = Simulation("/path/to/simulation/osiris.inp")
     e1 = sim["e1"]
     e2 = sim["e2"] 
     e3 = sim["e3"]

docs/source/api/utilities.rst

@@ -1,7 +1,7 @@
 Utilities API
 =============
 
-This document provides a reference to the osiris_utils utilities API.
+This document provides a reference to the `osiris_utils` utilities API, which includes tools for reading various OSIRIS data formats (Grid, Raw Particles, Tracks, HIST) and helper functions for common physics calculations and data operations.
 
 Data Readers Structures
 -----------------------
@@ -79,7 +79,7 @@ Particle Data
    .. code-block:: python
   
       import osiris_utils as ou  
-      raw = ou.raw = ou.OsirisRawFile("path/to/raw/file.h5")
+      raw = ou.OsirisRawFile("path/to/raw/file.h5")
       print(raw.data.keys())
       print(raw.data["x1"][0:10])  # Access x1 position of first 10 particles
 
@@ -107,7 +107,7 @@ Particle Data
          raw = ou.OsirisRawFile("path/to/raw/file/.../.h5")
          # Selecting 5 random tags from particles with energy>5
          mask = raw.data["ene"] >    5.
-         raw_to_file_tags("output.tag", type="random", n_tags=5, mask=mask)
+         raw.raw_to_file_tags("output.tag", type="random", n_tags=5, mask=mask)
 
 
 
@@ -149,7 +149,7 @@ TRACK Data
    .. code-block:: python
   
       import osiris_utils as ou
-      track = ou.OsirisTrackFile(path/to/track_file.h5)
+      track = ou.OsirisTrackFile("path/to/track_file.h5")
       print(track.data[0:10, :]["x1"]) # Access x1 position of first 10 particles over all time steps
 
 
@@ -175,7 +175,7 @@ Convert track file to the older more readable format
    .. code-block:: python
       
       >>> import osiris_utils as ou 
-      >>> ou.utils.convert_tracks('path/to/input_trackfile.h5')
+      >>> ou.convert_tracks('path/to/input_trackfile.h5')
       >>> # The output will be saved as 'path/to/input_trackfile-v2.h5'
 
    **Notes:**  
@@ -209,7 +209,7 @@ To create a tag file directly from raw data, see :class:`osiris_utils.data.data.
       import osiris_utils as ou 
       import numpy as np
       tags = np.array([[1, 12345], [2, 67890], [3, 11111]])  # Example tags
-      ou.utils.create_file_tags('output.tag', tags)
+      ou.create_file_tags('output.tag', tags)
       # This will generate a file 'output.tag' with the particle tags.
 
    **Notes:**  

docs/source/conf.py

@@ -26,7 +26,7 @@ sys.path.append(os.path.abspath("../.."))
 project = "osiris_utils"
 copyright = "2025, João Biu"
 author = "João Biu"
-version = "v1.1.10a"
+version = "v1.2.0"
 release = version
 
 
@@ -46,16 +46,36 @@ extensions = [
     "sphinx.ext.napoleon",
     "sphinx_copybutton",
     "sphinx_github_style",
+    "myst_parser",
 ]
 
 nb_execution_mode = "off"  # use stored output; avoids long CI builds
 # options for sphinx_github_style
 top_level = "OSIRIS Utils"
-linkcode_blob = "head"
+linkcode_blob = "main"
 linkcode_url = r"https://github.com/joaopedrobiu6/osiris_utils/"
 linkcode_link_text = "Source"
 
 
+def linkcode_resolve(domain, info):
+    """Return a URL to the source code for ``info``.
+
+    This implementation avoids invoking git or requiring a tag; it
+    constructs URLs pointing at the `linkcode_blob` branch on GitHub.
+    """
+    if domain != "py":
+        return None
+
+    module = info.get("module")
+    if not module:
+        return None
+
+    # Convert module path to file path
+    filename = module.replace(".", "/") + ".py"
+
+    return f"{linkcode_url}blob/{linkcode_blob}/{filename}"
+
+
 # numpydoc_class_members_toctree = False
 # Napoleon settings
 napoleon_google_docstring = False
@@ -80,11 +100,11 @@ templates_path = ["_templates"]
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-source_suffix = [".rst", ".md"]
-# source_suffix = {
-#     '.rst': 'restructuredtext',
-#     '.md': 'markdown',
-# }
+# source_suffix = [".rst", ".md"]
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
 # The master toctree document.
 master_doc = "index"
 
@@ -135,7 +155,7 @@ html_css_files = ["custom.css"]
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-# html_logo = '_static/images/logo_small_clear.png'
+html_logo = '_static/Imagem1.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

docs/source/examples/example_Derivatives.md

@@ -0,0 +1,78 @@
+```python
+%load_ext autoreload
+%autoreload 2
+```
+
+
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+
+import osiris_utils as ou
+```
+
+# Derivatives using `Derivative_Simulation` object
+
+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. 
+
+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:
+
+$$
+\frac{\partial n}{\partial t} + \frac{\partial}{\partial x}(n v_1) = 0
+$$
+
+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.
+
+Initialize the simulation object:
+
+
+```python
+sim = ou.Simulation(input_deck_path="example_data/thermal.1d")
+```
+
+Initialize the `Derivative_Simulation` objects with respect to the time and $x_1$ coordinate, since these are the derivatives that we want to compute.
+
+
+```python
+d_dt = ou.Derivative_Simulation(sim, "t")
+d_dx1 = ou.Derivative_Simulation(sim, "x1")
+```
+
+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.
+
+
+```python
+# Create a new diagnostic n * vfl1
+nVfl1 = sim["electrons"]["n"] * sim["electrons"]["vfl1"]
+# Add this to the simulation (electrons)
+sim["electrons"].add_diagnostic(nVfl1, "nVfl1")
+```
+
+Now that we have the diagnostics needed in our `Simulation` object, we can directly reconstruct the equation desired:
+
+
+```python
+continuity = d_dt["electrons"]["n"] + d_dx1["electrons"]["nVfl1"]
+```
+
+This is a new diagnostic, and we can now access to its iterations using indexing
+
+
+```python
+plt.figure(figsize=(8, 6))
+plt.title("Continuity equation residuals")
+plt.xlabel(continuity.axis[0]["plot_label"])
+
+plt.plot(continuity.x, continuity[10], label="Continuity equation")
+plt.legend()
+plt.xlim(continuity.x[0], continuity.x[-1])
+plt.show()
+```
+
+
+```python
+plt.plot(continuity.x, ou.integrate(continuity[10], continuity.dx), label=r"$\int \partial_t n + \partial_x( n v_{fl1}) dx$")
+plt.legend()
+plt.xlim(continuity.x[0], continuity.x[-1])
+plt.show()
+```