osiris-utils 1.2.3__tar.gz

osiris_utils-1.2.3/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

osiris_utils-1.2.3/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          # install the package and dev extras in one shot
+          pip install .[dev]
+
+      - name: Run pre-commit
+        uses: pre-commit/action@v3.0.1
+
+      - name: Run test suite
+        run: |
+          pytest --cov=osiris_utils --cov-report=term-missing
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v4
+        with: { python-version: '3.11' }
+
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          # dev + docs extras include sphinx, myst‑nb, sphinx_copybutton, nbsphinx, …
+          pip install -e '.[dev,docs]'
+
+      - name: Build docs
+        run: |
+          make -C docs html

osiris_utils-1.2.3/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish Python 🐍 distribution 📦 to PyPI 
+
+on: push
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+  publish-to-pypi:
+    name: >-
+      Publish Python 🐍 distribution 📦 to PyPI
+    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/osiris-utils  
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution 📦 to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_TOKEN }}
+        packages: dist/*

osiris_utils-1.2.3/.gitignore

@@ -0,0 +1,7 @@
+build/
+osiris_utils.egg-info/
+osiris_utils/__pycache__/
+*.pyc
+.DS_Store
+dist/
+osiris_utils/.DS_Store

osiris_utils-1.2.3/.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.2.3/.readthedocs.yaml

@@ -0,0 +1,27 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+  builder: html
+  fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+
+
+python:
+   install:
+   - requirements: requirements-dev.txt

osiris_utils-1.2.3/CONTRIBUTING.rst

@@ -0,0 +1,277 @@
+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.3/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 João Biu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

osiris_utils-1.2.3/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: osiris_utils
+Version: 1.2.3
+Summary: Utilities to manipulate and visualise OSIRIS plasma PIC output data
+Author-email: João Pedro Ferreira Biu <joaopedrofbiu@tecnico.ulisboa.pt>
+License: MIT
+Project-URL: Source Code, https://github.com/joaopedrobiu6/osiris_utils
+Project-URL: Issues Tracker, https://github.com/joaopedrobiu6/osiris_utils/issues
+Project-URL: Documentation, https://osiris-utils.readthedocs.io
+Classifier: Development Status :: 3 - Alpha
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+Requires-Dist: numpy>=1.25
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: h5py>=3.10
+Requires-Dist: tqdm>=4.66
+Provides-Extra: dev
+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: types-tqdm; extra == "dev"
+Requires-Dist: types-Pillow; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8; extra == "docs"
+Requires-Dist: ipykernel; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: sphinx-copybutton<=0.5.2; extra == "docs"
+Requires-Dist: sphinx-rtd-theme<3.0.3; extra == "docs"
+Requires-Dist: sphinx-github-style<=1.2.2; extra == "docs"
+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.
+
+All code is written in Python. To contact the dev team, please send an email to João Biu: `joaopedrofbiu@tecnico.ulisboa.pt <mailto:joaopedrofbiu@tecnico.ulisboa.pt>`_.
+The full dev team can be found below in the Authors and Contributors section.
+
+How to install it?
+------------------
+
+To install this package, you can use `pip`::
+
+    pip install osiris_utils
+
+To install it from source, you can clone this repository and run (in the folder containing ``setup.py``)::
+
+    git clone https://github.com/joaopedrobiu6/osiris_utils.git
+    pip install .
+
+Finally, you can install it in editor mode if you want to contribute to the code::
+    
+    git clone https://github.com/joaopedrobiu6/osiris_utils.git
+    pip install -e .
+
+Quick-start
+-----------
+
+.. image:: https://mybinder.org/badge_logo.svg
+   :target: https://mybinder.org/v2/gh/joaopedrobiu6/osiris_utils/main?filepath=examples%2Fquick_start.ipynb
+   :alt: Launch quick-start on Binder
+
+.. code-block:: bash
+
+   pip install osiris_utils              # from PyPI
+   python -m pip install matplotlib      # plotting backend (optional)
+   git clone https://github.com/joaopedrobiu6/osiris_utils  # sample data
+   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
+-------------
+
+The documentation is available at https://osiris-utils.readthedocs.io or via this link: `osiris-utils.readthedocs.io <https://osiris-utils.readthedocs.io>`_.
+
+.. |Pypi| image:: https://img.shields.io/pypi/v/osiris-utils
+    :target: https://pypi.org/project/osiris-utils/
+    :alt: Pypi
+
+.. _authors:
+
+Author
+------
+
+- João Biu
+
+Contributors
+------------
+
+- Diogo Carvalho
+- João Cândido
+- Margarida Pereira
+