Metadata-Version: 2.4
Name: osiris_utils
Version: 1.2.4
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

