osiris-utils 1.1.6__tar.gz → 1.1.7__tar.gz

osiris_utils-1.1.7/.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.1.7/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+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: Static type check (mypy)
+        run: |
+          python -m pip install mypy types-tqdm types-Pillow
+          mypy osiris_utils
+
+
+      - 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.1.7/.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.1.7/.gitignore

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

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

@@ -0,0 +1,12 @@
+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,TCH"]         # auto‑apply safe fixes
+      - id: ruff-format
+  - repo: https://github.com/pycqa/isort
+    rev: 6.0.1
+    hooks:
+      - id: isort
+        args: ["--profile", "black"]

osiris_utils-1.1.7/.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.1.7/CONTRIBUTING.rst

@@ -0,0 +1,64 @@
+Contributing to OSIRIS Utils
+============================
+
+Thank you for contributing!
+
+The following is a set of guidelines for contributing to our code. These are
+mostly guidelines, not rules, so feel free to use your best judgment!
+
+Reporting Bugs
+~~~~~~~~~~~~~~
+
+How Do I Submit A (Good) Bug Report?
+------------------------------------
+
+Bugs are tracked as `GitHub issues <https://github.com/joaopedrobiu6/osiris_utils/issues/>`__.
+
+Explain the problem and include additional details to help maintainers
+reproduce the problem:
+
+-  **Use a clear and descriptive title** for the issue to identify the
+   problem.
+-  **Describe the exact steps which reproduce the problem** in as many
+   details as possible.
+-  **Provide specific examples to demonstrate the steps**. Include links
+   to files or copy/pasteable snippets.
+-  **Describe the behavior you observed after following the steps** and
+   point out what exactly is the problem with that behavior.
+-  **Explain which behavior you expected to see instead and why.**
+-  **Include plots** of results that you believe to be wrong.
+
+Adding Post-Processing routines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+How we contribute by adding post-processing classes? Here's a breakdown:
+
+1. First, you should implement a class that operates on simulations, usually called - ``NameOfPostProcess_Simulation``:
+
+* Inherits from ``PostProcess``
+* It should have a ``__getitem__(self, key)`` with if statements to separate the species diagnostics from the general ones
+
+2. A class to deal with the diagnostics - ``NameOfPostProcess_Diagnostic``
+
+* Inherits from ``Diagnostic``
+* Must have a ``load_all``, ``_data_generator`` and ``__getitem__``. They need to have these names to work well with ``Diagnostic`` objects. The first two are more specific to the process that you want, and you can understand from the already implemented what stuff you need to take into account (usually that `load_all` makes the data have `(t, x, y, z)` and `_data_generator` only yields `(x, y, z)`, and once `load_all` is used, `_data_generator` should use already read data)
+* The access by indexing should only return ``np.ndarray``. If you need different stuff, for example, a list of ``np.ndarray``, implement it in auxiliary classes. 
+* Eg.: The Mean Field Theory should give us access to the averaged field and the fluctuations for each quantity. Since this would be 2 arrays and not 1, MFT has two diagnostic classes, one for averages and another for fluctuations.
+
+3. A class to deal with species-related diagnostics - ``NameOfProcess_Species_Handler``
+
+* Does not inherit from anything
+* Just works as a wrapper for the dictionary-like syntax to be consistent.
+
+By implementing it and taking these steps into consideration, the integration with the rest of the package should be fairly straightforward. 
+However, since post-processes may differ a lot from each other, some things may be more of a case-to-case situation. 
+If any help is needed, please open an issue or contact João Biu via `email <joaopedrofbiu@tecnico.ulisboa.pt>`__ or `GitHub <https://github.com/joaopedrobiu6>`__.
+
+To be consistent with the syntax of other classes:
+
+.. code-block :: python
+                                                                                                                                 
+  sim = ou.Simulation("folder", "input_deck")
+  PostProcessExample_for_sim = PostProcessExample_Simulation(sim, ...)
+  PostProcessExample_for_sim["non_species_related_quantity"][index] # this should return the values of the post-processed quantity for that index
+  PostProcessExample_for_sim["species"]["quantity"][index] # this should return the value of the post-processed species-related quantity at the specified index

{osiris_utils-1.1.6/osiris_utils.egg-info → osiris_utils-1.1.7}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: osiris_utils
-Version: 1.1.6
-Summary: Utilities to manipulate and visualize OSIRIS framework output data
-Author: ['João Pedro Ferreira Biu', 'João Cândido', 'Diogo Carvalho']
-Author-email: ['joaopedrofbiu@tecnico.ulisboa.pt']
+Version: 1.1.7
+Summary: Utilities to manipulate and visualise OSIRIS plasma PIC output data
+Author: João Cândido, Diogo Carvalho
+Author-email: João Pedro Ferreira Biu <joaopedrofbiu@tecnico.ulisboa.pt>
 License: MIT
-Project-URL: Issues Tracker, https://github.com/joaopedrobiu6/osiris_utils/issues
 Project-URL: Source Code, https://github.com/joaopedrobiu6/osiris_utils
-Keywords: OSIRIS,particle-in-cell,plasma,physics
+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
@@ -22,31 +22,45 @@ Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
-Requires-Dist: numpy
-Requires-Dist: matplotlib
-Requires-Dist: pandas
-Requires-Dist: scipy
-Requires-Dist: h5py
-Requires-Dist: pyside6
-Requires-Dist: pyarrow
-Requires-Dist: tqdm
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: keywords
-Dynamic: license
+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: isort>=5.13; extra == "dev"
+Requires-Dist: mypy>=1.10; 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"
+Provides-Extra: plot
+Requires-Dist: seaborn>=0.13; extra == "plot"
 Dynamic: license-file
-Dynamic: project-url
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
 
 OSIRIS_UTILS
 ============
 |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
+
+
+
 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.
 
@@ -70,6 +84,25 @@ 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
+
+.. image:: docs/source/_static/quick_start_ez.png
+   :alt: Example Ez plot produced by the quick-start
+   :width: 400px
+
 Documentation
 -------------
 

{osiris_utils-1.1.6 → osiris_utils-1.1.7}/README.rst

@@ -2,6 +2,15 @@ OSIRIS_UTILS
 ============
 |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
+
+
+
 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.
 
@@ -25,6 +34,25 @@ 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
+
+.. image:: docs/source/_static/quick_start_ez.png
+   :alt: Example Ez plot produced by the quick-start
+   :width: 400px
+
 Documentation
 -------------
 

osiris_utils-1.1.7/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

osiris_utils-1.1.7/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

osiris_utils-1.1.7/docs/source/_static/custom.css

@@ -0,0 +1,53 @@
+/* Sidebar background */
+.wy-nav-side {
+  background: #88cbf8;  /* Change to your preferred color */
+}
+
+/* Sidebar link color */
+.wy-menu-vertical a {
+  color: #ffffff;
+}
+
+/* Sidebar link hover color */
+.wy-menu-vertical a:hover {
+  background-color: #36a8f3;
+}
+
+/* Selected item in sidebar */
+.wy-menu-vertical li.current {
+  background: #2f93f0;
+}
+
+.wy-menu-vertical li.current > a {
+  background: #aeecff;
+}
+
+/* Header (H1, H2, etc.) colors */
+h1, h2, h3, h4, h5, h6 {
+  color: #57bafb;
+}
+
+a:hover {
+  color: #a5c0fe;
+}
+
+/* Code block background */
+.highlight {
+  background: #000000;
+}
+
+/* Keep your existing settings for content width */
+.wy-nav-content {
+  max-width: 1200px !important;
+}
+
+/* Keep your existing table width overrides */
+@media screen and (min-width: 767px) {
+.wy-table-responsive table td {
+  white-space: normal !important;
+}
+
+.wy-table-responsive {
+  overflow: visible !important;
+}
+}