osiris-utils 1.1.10a0__tar.gz → 1.2.1__tar.gz

osiris_utils-1.2.1/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.8       # pin the latest stable
+    hooks:
+      - id: ruff
+        args: ["--fix", "--select", "F,E,I,W,B,C90"]         # auto‑apply safe fixes (TCH rules disabled here)
+      - id: ruff-format

{osiris_utils-1.1.10a0 → osiris_utils-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: osiris_utils
-Version: 1.1.10a0
+Version: 1.2.1
 Summary: Utilities to manipulate and visualise OSIRIS plasma PIC output data
 Author-email: João Pedro Ferreira Biu <joaopedrofbiu@tecnico.ulisboa.pt>
 License: MIT
@@ -12,8 +12,6 @@ Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -32,7 +30,6 @@ Requires-Dist: pytest>=8.1; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pre-commit>=3.7; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"
-Requires-Dist: isort>=5.13; extra == "dev"
 Requires-Dist: types-tqdm; extra == "dev"
 Requires-Dist: types-Pillow; extra == "dev"
 Provides-Extra: docs
@@ -46,16 +43,23 @@ Dynamic: license-file
 
 OSIRIS_UTILS
 ============
+.. image:: https://raw.githubusercontent.com/joaopedrobiu6/osiris_utils/main/docs/source/_static/Imagem1.png
+   :width: 200px
+   :align: right
+
+
 |Pypi|
 
 .. image:: https://github.com/joaopedrobiu6/osiris_utils/actions/workflows/ci.yml/badge.svg
    :target: https://github.com/joaopedrobiu6/osiris_utils/actions
    :alt: CI status
+
 .. image:: https://codecov.io/gh/joaopedrobiu6/osiris_utils/branch/main/graph/badge.svg
    :target: https://codecov.io/gh/joaopedrobiu6/osiris_utils
    :alt: Coverage
 
-
+.. image:: https://zenodo.org/badge/889119723.svg
+  :target: https://doi.org/10.5281/zenodo.17382244
 
 This package contains a set of utilities to open and analyze OSIRIS output files, using Python. All the methods implemented are fully integrated with `NumPy`, and use `np.ndarray` as the main data structure.
 High-level functions are provided to manipulate data from OSIRIS, from reading the data of the diagnostics, to making post-processing calculations.
@@ -95,6 +99,48 @@ Quick-start
    cd osiris_utils
    python examples/quick_start.py examples/example_data/thermal.1d
 
+Command-Line Interface
+----------------------
+
+osiris_utils includes a command-line interface for common operations. After installation, the ``osiris`` command becomes available::
+
+   osiris --version                     # Check version
+   osiris --help                        # Show available commands
+
+**Available Commands:**
+
+- ``osiris info`` - Display metadata about OSIRIS files and simulations
+- ``osiris export`` - Convert data to CSV, JSON, or NumPy formats
+- ``osiris plot`` - Create quick visualizations
+- ``osiris validate`` - Check file integrity
+
+**Examples:**
+
+Show simulation information::
+
+   osiris info path/to/simulation
+   osiris info path/to/file.h5 --brief
+
+Export data to different formats::
+
+   osiris export file.h5 --format csv --output data.csv
+   osiris export diagnostic/dir --format npy --output data.npy
+
+Generate quick plots::
+
+   osiris plot file.h5 --save plot.png
+   osiris plot file.h5 --save plot.png --title "Ez Field" --cmap viridis
+
+Validate simulation data::
+
+   osiris validate path/to/simulation
+   osiris validate path/to/simulation --check-missing
+
+For detailed help on any command::
+
+   osiris <command> --help
+
+
 Documentation
 -------------
 
@@ -106,7 +152,15 @@ The documentation is available at https://osiris-utils.readthedocs.io or via thi
 
 .. _authors:
 
-Authors and Contributors
-------------------------
+Author
+------
 
 - João Biu
+
+Contributors
+------------
+
+- Diogo Carvalho
+- João Cândido
+- Margarida Pereira
+

{osiris_utils-1.1.10a0 → osiris_utils-1.2.1}/README.rst

@@ -1,15 +1,22 @@
 OSIRIS_UTILS
 ============
+.. image:: https://raw.githubusercontent.com/joaopedrobiu6/osiris_utils/main/docs/source/_static/Imagem1.png
+   :width: 200px
+   :align: right
+
+
 |Pypi|
 
 .. image:: https://github.com/joaopedrobiu6/osiris_utils/actions/workflows/ci.yml/badge.svg
    :target: https://github.com/joaopedrobiu6/osiris_utils/actions
    :alt: CI status
+
 .. image:: https://codecov.io/gh/joaopedrobiu6/osiris_utils/branch/main/graph/badge.svg
    :target: https://codecov.io/gh/joaopedrobiu6/osiris_utils
    :alt: Coverage
 
-
+.. image:: https://zenodo.org/badge/889119723.svg
+  :target: https://doi.org/10.5281/zenodo.17382244
 
 This package contains a set of utilities to open and analyze OSIRIS output files, using Python. All the methods implemented are fully integrated with `NumPy`, and use `np.ndarray` as the main data structure.
 High-level functions are provided to manipulate data from OSIRIS, from reading the data of the diagnostics, to making post-processing calculations.
@@ -49,6 +56,48 @@ Quick-start
    cd osiris_utils
    python examples/quick_start.py examples/example_data/thermal.1d
 
+Command-Line Interface
+----------------------
+
+osiris_utils includes a command-line interface for common operations. After installation, the ``osiris`` command becomes available::
+
+   osiris --version                     # Check version
+   osiris --help                        # Show available commands
+
+**Available Commands:**
+
+- ``osiris info`` - Display metadata about OSIRIS files and simulations
+- ``osiris export`` - Convert data to CSV, JSON, or NumPy formats
+- ``osiris plot`` - Create quick visualizations
+- ``osiris validate`` - Check file integrity
+
+**Examples:**
+
+Show simulation information::
+
+   osiris info path/to/simulation
+   osiris info path/to/file.h5 --brief
+
+Export data to different formats::
+
+   osiris export file.h5 --format csv --output data.csv
+   osiris export diagnostic/dir --format npy --output data.npy
+
+Generate quick plots::
+
+   osiris plot file.h5 --save plot.png
+   osiris plot file.h5 --save plot.png --title "Ez Field" --cmap viridis
+
+Validate simulation data::
+
+   osiris validate path/to/simulation
+   osiris validate path/to/simulation --check-missing
+
+For detailed help on any command::
+
+   osiris <command> --help
+
+
 Documentation
 -------------
 
@@ -60,7 +109,15 @@ The documentation is available at https://osiris-utils.readthedocs.io or via thi
 
 .. _authors:
 
-Authors and Contributors
-------------------------
+Author
+------
+
+- João Biu
+
+Contributors
+------------
+
+- Diogo Carvalho
+- João Cândido
+- Margarida Pereira
 
-- João Biu

osiris_utils-1.2.1/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()

osiris_utils-1.2.1/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)

{osiris_utils-1.1.10a0 → osiris_utils-1.2.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;
 }

osiris_utils-1.2.1/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

{osiris_utils-1.1.10a0 → osiris_utils-1.2.1}/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

{osiris_utils-1.1.10a0 → osiris_utils-1.2.1}/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"]

{osiris_utils-1.1.10a0 → osiris_utils-1.2.1}/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:**