osiris-utils 1.1.10__py3-none-any.whl → 1.2.0__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/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.decks 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

@@ -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')
+
+       # 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

@@ -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

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
 -----------------------

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.10"
+version = "v1.2.0"
 release = version
 
 
@@ -46,6 +46,7 @@ extensions = [
     "sphinx.ext.napoleon",
     "sphinx_copybutton",
     "sphinx_github_style",
+    "myst_parser",
 ]
 
 nb_execution_mode = "off"  # use stored output; avoids long CI builds

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()
+```

docs/source/examples/example_FFT.md

@@ -0,0 +1,152 @@
+# FFT Analysis
+
+```python
+%load_ext autoreload
+%autoreload 2
+```
+
+
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.colors import LogNorm
+
+import osiris_utils as ou
+```
+
+## Initialize an object of the Simulation class
+- The Simulation class takes the `simulation_folder`, this is, the file where the input deck is located.
+- It can also take the `species` when we want to use quantities related to a specific species, such as velocities, charge, temperature, etc.
+
+
+```python
+# In this case, since we only want to study the electric field, no species is needed
+sim = ou.Simulation(input_deck_path="example_data/thermal.1d")
+```
+
+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
+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.
+
+
+```python
+# This is a Diagnostic object
+sim["e3"]
+
+# This is also a Diagnostic object but initialized directly and not through the Simulation object
+e3 = ou.Diagnostic(simulation_folder="example_data")
+e3.get_quantity("e3")
+
+print("sim['e3'] class:", sim["e3"].__class__)
+print("e3 class:", e3.__class__)
+```
+
+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.
+
+
+```python
+plt.figure(figsize=(8, 3))
+plt.plot(sim["e3"].x, sim["e3"][100])
+plt.xlabel(sim["e3"].axis[0]["plot_label"])
+plt.title(rf"${sim['e3'].label}$ @ $t = {sim['e3'].time(100)[0]:.2f}$ $[{sim['e3'].tunits}]$")
+plt.show()
+```
+
+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.
+
+
+```python
+sim["e3"].load_all()
+print(sim["e3"].data.shape)
+
+e3.load_all()
+print(e3.data.shape)
+
+np.isclose(sim["e3"].data, e3.data).all()
+
+sim["e3"].unload()
+e3.unload()
+```
+
+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. 
+
+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.
+
+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.
+
+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`.
+
+
+```python
+sim_fft = ou.FFT_Simulation(sim, (0, 1))  # "operator" FFT applied to Simulation object, axis 0 and 1
+
+e3_fft = ou.FFT_Diagnostic(e3, (0, 1))  # "operator" FFT applied to Diagnostic object, axis 0 and 1
+```
+
+
+```python
+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
+
+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
+
+np.isclose(sim_fft["e3"][100], e3_fft[100]).all()  # They are the same!
+```
+
+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.
+
+
+```python
+sim_fft["e3"].load_all()
+e3_fft.load_all()
+
+np.isclose(sim_fft["e3"].data, e3_fft.data).all()  # They are the same!
+```
+
+We can now plot!
+
+
+```python
+plt.imshow(
+    sim_fft["e3"].data,
+    origin='lower',
+    norm=LogNorm(vmin=1e-7, vmax=0.01),
+    extent=(-sim_fft["e3"].kmax, sim_fft["e3"].kmax, -sim_fft["e3"].omega_max, sim_fft["e3"].omega_max),
+    aspect='auto',
+    cmap='gray',
+)
+
+# Plotting the dispersion relation
+k = np.linspace(-e3_fft.kmax, e3_fft.kmax, num=512)
+w = np.sqrt(1 + k**2)
+plt.plot(k, w, label=r"$\omega^2 = \omega_p^2 + k^2c^2$", color='r', ls='-.')
+plt.xlim(0, e3_fft.kmax)
+plt.ylim(0, e3_fft.omega_max)
+
+plt.xlabel(r"$k$ $[\omega_e/c]$")
+plt.ylabel(r"$\omega$ $[\omega_e]$")
+plt.legend()
+plt.show()
+```
+
+
+```python
+plt.imshow(
+    e3_fft.data,
+    origin='lower',
+    norm=LogNorm(vmin=1e-7, vmax=0.01),
+    extent=(-e3_fft.kmax, e3_fft.kmax, -e3_fft.omega_max, e3_fft.omega_max),
+    aspect='auto',
+    cmap='gray',
+)
+
+# Plotting the dispersion relation
+k = np.linspace(-e3_fft.kmax, e3_fft.kmax, num=512)
+w = np.sqrt(1 + k**2)
+plt.plot(k, w, label=r"$\omega^2 = \omega_p^2 + k^2c^2$", color='r', ls='-.')
+plt.xlim(0, e3_fft.kmax)
+plt.ylim(0, e3_fft.omega_max)
+
+plt.xlabel(r"$k$ $[\omega_e/c]$")
+plt.ylabel(r"$\omega$ $[\omega_e]$")
+plt.legend()
+plt.show()
+```

docs/source/examples/example_InputDeck.md

@@ -0,0 +1,148 @@
+```python
+%load_ext autoreload
+%autoreload 2
+```
+
+
+```python
+import osiris_utils as ou
+```
+
+# Interface with Osiris Input Decks
+
+For many tasks, it might be useful to read simulation parameters directly from the input deck, or algorithmically generate new Osiris input decks (e.g.to run large parameter scans). 
+
+The class `InputDeckIO` allows you to easily perform theses tasks.
+You need to provide it two inputs:
+- `filename`: path to OSIRIS input deck
+- `verbose`: if `True` will print auxiliary information when parsing the input deck
+
+
+## Reading an input deck
+
+
+```python
+deck = ou.InputDeckIO('example_data/thermal.1d', verbose=True)
+```
+
+Not only does the object load the different module parameters, but also automatically determines other useful information for downstream tasks.
+
+Examples include:
+- `dim`: number of dimensions
+- `n_species`: number of species
+- `species`: dictionary with `Species` objects with relevant information (e.g. charge, rqm, etc.)
+
+
+```python
+print("Simulation Dimensions:", deck.dim)
+print("Number of species:", deck.n_species)
+print("Species:", deck.species)
+```
+
+`InputDeckIO` stores the state of the input deck in the parameter `self._sections`.
+
+You should not access this value directly, instead you can use for example its getter function `self.sections` which returns a deepcopy.
+
+The returned value corresponds to a list of pairs [section_name, dictionary] where the section_name matches the Osiris input deck section name and he dictionary contains the list of (key, values) for the parameters of the section.
+
+
+```python
+print(deck.sections[0])
+print(deck.sections[1])
+print('Number of sections:', len(deck.sections))
+```
+
+Another option is to query the object as if it is an iterator, where the key is the section name.
+
+This will return a list of dictionaries, since multiple sections can have the same name (e.g. you might have multiple species).
+
+Once again, a deepcopy is being returned so editing the returned values of the dictionaries will not change the original `InputDeckIO` object.
+
+
+```python
+print(deck['simulation'])
+print(deck['node_conf'])
+```
+
+Finally you can also ask for a specific parameter directly with `get_param()`
+
+
+```python
+# this one returns a list since there can be multiple sections with the same name
+print(deck.get_param(section='simulation', param='random_seed')[0])
+# which is equivalent to doing this
+print(deck["simulation"][0]['random_seed'])
+```
+
+## Editing an input deck
+
+To safely edit the value of a parameter in an input deck you can use `set_parameter()`.
+
+**Note**: This re-writes the object values!
+
+
+
+```python
+# edit a parameter already exists
+print('Before', deck['simulation'])
+deck.set_param('simulation', 'random_seed', value=42)
+print('After', deck['simulation'])
+```
+
+
+```python
+# add a parameter
+print("Before", deck["simulation"])
+deck.set_param("simulation", "new_parameter", value='HI!', unexistent_ok=True)
+print("After", deck["simulation"])
+```
+
+And you can also delete the parameter using `delete_param()`.
+
+
+```python
+# delete a parameter
+print("Before", deck["simulation"])
+deck.delete_param("simulation", "new_parameter")
+print("After", deck["simulation"])
+```
+
+Something slighlty more powerful, is the ability to edit a string in the whole input deck (use with care!)
+
+This can be done for example to automatically change multiple parameter values that are shared / depend on an external quantity.
+
+We can do this using the function `set_tag()`.
+
+**Note**: This only works on the parameter values, not section names / parameter names.
+
+
+```python
+# this a dummy example where we change some values to #tag#
+print("Before", deck["simulation"])
+deck.set_tag(
+    '42', # this has to be a string
+    '#tag#',
+)
+deck.set_tag(
+    '23:50:00', # this has to be a string
+    '#tag#',
+)
+print("After 1", deck["simulation"])
+
+# and here we change both values at once
+deck.set_tag('#tag#', "BOTH CHANGED")
+print("After 2", deck["simulation"])
+# There is a reason why wall_clock_limit has an extra "" done worry
+# it is because it should be a string, while random_seed is an int!
+# InputDeckIO handles these things for you
+```
+
+## Writing changes to file
+
+Once you did your changes, you can simply generate a new input deck with `print_to_file()`.
+
+
+```python
+deck.print_to_file("edited-deck.1d")
+! cat edited-deck.1d
+```