### Download Example Datasets (Python)

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/3_Introduction-to-the-GUI.ipynb

Downloads and extracts specified openPMD example datasets. Requires `wget` and `tarfile` modules. Ensures data is available for visualization.

```Python
import os

def download_if_absent( dataset_name ):
    """Function that downloads and decompress a chosen dataset"""
    if os.path.exists( dataset_name ) is False:
        import wget, tarfile
        tar_name = "%s.tar.gz" %dataset_name
        url = "https://github.com/openPMD/openPMD-example-datasets/raw/draft/%s" %tar_name
        wget.download(url, tar_name)
        with tarfile.open( tar_name ) as tar_file:
            tar_file.extractall()
        os.remove( tar_name )

download_if_absent( 'example-2d' )
download_if_absent( 'example-3d' )
download_if_absent( 'example-thetaMode' )
```

--------------------------------

### Download Example Data

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/1_Introduction-to-the-API.ipynb

Downloads and decompresses example openPMD datasets if they are not already present. It uses `wget` and `tarfile` for this purpose, ensuring data availability for local testing.

```python
import os

def download_if_absent( dataset_name ):
    """Function that downloads and decompress a chosen dataset"""
    if os.path.exists( dataset_name ) is False:
        import wget, tarfile
        tar_name = "%s.tar.gz" %dataset_name
        url = "https://github.com/openPMD/openPMD-example-datasets/raw/draft/%s" %tar_name
        wget.download( url, tar_name )
        with tarfile.open( tar_name ) as tar_file:
            tar_file.extractall()
        os.remove( tar_name )

download_if_absent( 'example-2d' )
```

--------------------------------

### Download Example Data

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/5_Laser-plasma_tools.ipynb

Downloads and extracts a specified openPMD dataset if it does not already exist locally. This function is essential for running the laser-plasma tools with example data.

```python
import os

def download_if_absent( dataset_name ):
    """Function that downloads and decompress a chosen dataset"""
    if os.path.exists( dataset_name ) is False:
        import wget, tarfile
        tar_name = "%s.tar.gz" %dataset_name
        url = "https://github.com/openPMD/openPMD-example-datasets/raw/draft/%s" %tar_name
        wget.download(url, tar_name)
        with tarfile.open( tar_name ) as tar_file:
            tar_file.extractall()
        os.remove( tar_name )

download_if_absent( 'example-2d' )
```

--------------------------------

### Download Example Data

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/4_Particle_selection.ipynb

A utility function to download and extract openPMD example datasets if they are not present locally. It uses the `wget` and `tarfile` modules for downloading and decompression.

```python
import os

def download_if_absent( dataset_name ):
    """Function that downloads and decompress a chosen dataset"""
    if os.path.exists( dataset_name ) is False:
        import wget, tarfile
        tar_name = "%s.tar.gz" %dataset_name
        url = "https://github.com/openPMD/openPMD-example-datasets/raw/draft/%s" %tar_name
        wget.download( url, tar_name )
        with tarfile.open( tar_name ) as tar_file:
            tar_file.extractall()
        os.remove( tar_name )

download_if_absent( 'example-2d' )
```

--------------------------------

### Switch to Development Branch

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/CONTRIBUTING.md

Steps to switch to the development branch and install the project locally.

```git
git checkout dev
python -m pip wheel .
python -m pip install *whl
```

--------------------------------

### Install openPMD-viewer with pip

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/index.rst

Installs the openPMD-viewer package using pip. This is the standard method for Python package installation.

```shell
pip install openpmd-viewer
```

--------------------------------

### Install Jupyter for Interactive GUI

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/README.md

Installs the Jupyter package, which is required if you intend to use the interactive GUI features of the openPMD-viewer within Jupyter Notebooks.

```bash
pip install jupyter
```

--------------------------------

### Install openPMD-viewer with Pip

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/README.md

Installs the openPMD-viewer package using the pip package installer. This method is suitable for users who prefer pip or are not using Anaconda.

```bash
pip install openpmd-viewer
```

--------------------------------

### Python Function Docstring Example

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/CONTRIBUTING.md

Example of a Python function docstring following PEP 257 conventions, detailing parameters and return values.

```python
def get_data( dset, i_slice=None, pos_slice=None ) :
    """
    Extract the data from a (possibly constant) dataset
    Slice the data according to the parameters i_slice and pos_slice

    Parameters:
    -----------
    dset: an h5py.Dataset or h5py.Group (when constant)
        The object from which the data is extracted

    i_slice: int, optional
       The index of the slice to be taken

    pos_slice: int, optional
       The position at which to slice the array
       When None, no slice is performed

    Returns:
    --------
    An np.ndarray (non-constant dataset) or a single double (constant dataset)
    """
```

--------------------------------

### Load openPMD Data

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/openpmd_viewer/notebook_starter/Template_notebook.ipynb

Initializes an OpenPMDTimeSeries object to load and manage openPMD data files. The path to the data directory must be specified.

```python
# Replace the string below, to point to your data
ts = OpenPMDTimeSeries('./diags/hdf5/')
```

--------------------------------

### Install openPMD-viewer with conda

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/index.rst

Installs the openPMD-viewer package using conda, specifically from the conda-forge channel. This is an alternative installation method.

```shell
conda install -c conda-forge openpmd-viewer
```

--------------------------------

### Install openPMD-viewer with Conda

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/README.md

Installs the openPMD-viewer package and its dependencies using the conda package manager from the conda-forge channel. This is the recommended installation method for users with the Anaconda distribution.

```bash
conda install -c conda-forge openpmd-viewer
```

--------------------------------

### Launch openPMD-viewer Notebook

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/README.md

Executes the openPMD_notebook command to automatically create and open a new pre-filled Jupyter notebook in the browser, launching the interactive GUI. This command is available after installation.

```bash
openPMD_notebook
```

--------------------------------

### Install openPMD-viewer on Remote Cluster

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/README.md

Installs the openPMD-viewer package for a specific user on a remote scientific cluster. Ensure necessary modules like numpy, scipy, and h5py are loaded beforehand.

```bash
pip install openpmd-viewer --user
```

--------------------------------

### Run Project Tests

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/CONTRIBUTING.md

Execute the project's test suite using pytest after installing necessary dependencies.

```python
python -m pip wheel .
python -m pip install *whl matplotlib jupyter
python -m pytest tests
```

--------------------------------

### Download Example Datasets

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/2_Specific-field-geometries.ipynb

Downloads and extracts example datasets required for visualizing openPMD data. It checks if the dataset already exists before downloading and handles tar.gz archives. Dependencies include `wget` and `tarfile`.

```Python
import os, sys

def download_if_absent( dataset_name ):
    """Function that downloads and decompress a chosen dataset"""
    if os.path.exists( dataset_name ) is False:
        import wget, tarfile
        tar_name = "%s.tar.gz" %dataset_name
        url = "https://github.com/openPMD/openPMD-example-datasets/raw/draft/%s" %tar_name
        wget.download(url, tar_name)
        with tarfile.open( tar_name ) as tar_file:
            tar_file.extractall()
        os.remove( tar_name )

download_if_absent( 'example-3d' )
download_if_absent( 'example-thetaMode' )
```

--------------------------------

### Display Interactive GUI

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/openpmd_viewer/notebook_starter/Template_notebook.ipynb

Launches an interactive graphical user interface (GUI) for the loaded openPMD data. This allows users to explore the data through sliders and other interactive controls.

```python
# Interactive GUI
ts.slider()
```

--------------------------------

### Import openPMD Viewer Libraries

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/openpmd_viewer/notebook_starter/Template_notebook.ipynb

Imports necessary Python libraries including NumPy for numerical operations, Matplotlib for plotting, and the OpenPMDTimeSeries class from openpmd_viewer for handling openPMD data files. It also includes IPython magic commands for interactive plotting.

```python
import numpy as np
%matplotlib widget
# or "%matplotlib inline" for non-interactive plots
import matplotlib.pyplot as plt
from openpmd_viewer import OpenPMDTimeSeries
```

--------------------------------

### Get Available Species

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/1_Introduction-to-the-API.ipynb

Lists all available particle species within the openPMD dataset. This information is crucial for correctly specifying the `species` argument in `get_particle` calls.

```python
print(ts.avail_species)
```

--------------------------------

### Get Available Fields

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/1_Introduction-to-the-API.ipynb

Lists all available physical fields (e.g., 'rho', 'E', 'B') within the openPMD dataset. This is used to determine valid arguments for the `field` parameter in `get_field` calls.

```python
print(ts.avail_fields)
```

--------------------------------

### Iterate and Get Charge

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/5_Laser-plasma_tools.ipynb

Applies the get_charge method iteratively across all time steps or iterations for a specified particle species, returning a sequence of charge values.

```python
ts_2d.iterate( ts_2d.get_charge, species='electrons' )
```

--------------------------------

### Get Field Data by Time

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/1_Introduction-to-the-API.ipynb

Retrieves a specific field (e.g., 'E' along 'x' coordinate) at a given physical time. The API interpolates to the closest available time step if an exact match is not found. It returns field data and metadata.

```python
Ex, info_Ex = ts.get_field( t=100.e-15, field='E', coord='x' )
```

--------------------------------

### Get Field Data by Iteration

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/1_Introduction-to-the-API.ipynb

Retrieves a specific field (e.g., 'rho') at a given iteration number. It returns the field data as a NumPy array and associated metadata, including grid information.

```python
rho, info_rho = ts.get_field( iteration=300, field='rho' )
```

--------------------------------

### Plot Reconstructed Trajectories (z and uz) using ts.iterate

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/4_Particle_selection.ipynb

Plots the reconstructed longitudinal position (z) and momentum (uz) trajectories for selected particles (indices 0, 10, 19) against the iteration number. This example visualizes the results obtained using the `ts.iterate` method.

```python
plt.figure(figsize=(10, 4))
plt.subplot(121)
plt.plot( ts.iterations, z_trajectories[:,0], '-o' )
plt.plot( ts.iterations, z_trajectories[:,10], '-o' )
plt.plot( ts.iterations, z_trajectories[:,19], '-o' )
plt.ylabel('Longitudinal position z')
plt.xlabel('Iteration')

plt.subplot(122)
plt.plot( ts.iterations, uz_trajectories[:,0], '-o' )
plt.plot( ts.iterations, uz_trajectories[:,10], '-o' )
plt.plot( ts.iterations, uz_trajectories[:,19], '-o' )
plt.ylabel('Longitudinal momentum uz')
plt.xlabel('Iteration')
plt.tight_layout()
```

--------------------------------

### Get Radial Field Component (Python)

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/2_Specific-field-geometries.ipynb

Retrieves the radial component ('r') of a field in cylindrical geometry. This example shows how to access specific field components using the `coord` argument.

```python
Er, info_Er = ts_circ.get_field( field='E', coord='r', iteration=500, m=0, 
                              plot=True, theta=0.5)

```

--------------------------------

### Launch interactive openPMD notebook

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/index.rst

Executes a command-line tool that automatically creates and opens a pre-filled Jupyter notebook for interactive data visualization with openPMD-viewer.

```shell
openPMD_notebook
```

--------------------------------

### Initialize OpenPMDTimeSeries Object

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/1_Introduction-to-the-API.ipynb

Creates an instance of `OpenPMDTimeSeries` by providing the path to the directory containing the openPMD data files. This object represents the entire dataset and is used for all subsequent data access.

```python
ts = OpenPMDTimeSeries('./example-2d/hdf5/')
```

--------------------------------

### OpenPMDTimeSeries API Documentation

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/1_Introduction-to-the-API.ipynb

Provides access to the detailed docstring for the `OpenPMDTimeSeries` class and its methods, such as `get_field` and `get_particle`. This allows users to explore parameters, return values, and usage details directly within their environment.

```APIDOC
OpenPMDTimeSeries:
  __init__(path, backend='openPMD', **kwargs)
    Initializes the time series reader.
    path: Path to the directory containing openPMD data files.
    backend: The backend to use (e.g., 'openPMD', 'adios').

  iterations: property
    Returns a numpy array of available iteration numbers.

  t: property
    Returns a numpy array of corresponding physical time values.

  avail_fields: property
    Returns a list of available field names.

  avail_species: property
    Returns a list of available species names.

  get_field(field, iteration=None, t=None, coord=None, plot=False, **kwargs)
    Retrieves field data.
    Parameters:
      field (str): The name of the field to retrieve (e.g., 'rho', 'E').
      iteration (int, optional): The iteration number. Defaults to None.
      t (float, optional): The physical time. Defaults to None.
      coord (str, optional): The coordinate for vector fields (e.g., 'x', 'y', 'z'). Defaults to None.
      plot (bool, optional): If True, plots the field data. Defaults to False.
    Returns:
      tuple: A tuple containing (field_data, info_object).
        field_data: NumPy array of the field values.
        info_object: Object containing metadata like grid positions (e.g., info.x, info.z).

  get_particle(var_list, iteration=None, t=None, species=None, plot=False, **kwargs)
    Retrieves particle data.
    Parameters:
      var_list (list): A list of particle quantities to retrieve (e.g., ['x', 'charge']).
      iteration (int, optional): The iteration number. Defaults to None.
      t (float, optional): The physical time. Defaults to None.
      species (str, optional): The name of the particle species. Defaults to None.
      plot (bool, optional): If True, plots the particle data. Defaults to False.
    Returns:
      tuple: A tuple of NumPy arrays, one for each requested quantity in var_list.

  close():
    Closes the time series reader and releases resources.
```

--------------------------------

### PyPI Configuration File (.pypirc)

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/RELEASING.md

Configuration file for `twine` to manage PyPI and test PyPI credentials. It specifies repository URLs and usernames for uploading Python packages.

```INI
[distutils]
index-servers=
	pypitest
	pypi

[pypitest]
repository = https://testpypi.org/pypi
username = <yourPypiUsername>

[pypi]
repository = https://pypi.org/pypi
username = <yourPypiUsername>
```

--------------------------------

### Use GUI Slider for 2D Data (Python)

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/3_Introduction-to-the-GUI.ipynb

Creates an interactive GUI slider for visualizing 2D openPMD data. Allows navigation through time steps and selection of fields/particles.

```Python
ts_2d = OpenPMDTimeSeries('./example-2d/hdf5/')
ts_2d.slider()
```

--------------------------------

### Get Particle Charge

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/5_Laser-plasma_tools.ipynb

Calculates the total charge of a specified particle species at a given iteration. Optionally, particles can be filtered using the 'select' parameter.

```python
ts_2d.get_charge(iteration=300, species='electrons')
```

--------------------------------

### Clone openPMD-viewer Repository

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/CONTRIBUTING.md

Instructions to clone the forked openPMD-viewer repository to your local machine using Git.

```git
git clone git@github.com:<YourUserLogin>/openPMD-viewer.git
```

--------------------------------

### Import OpenPMDTimeSeries Class

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/1_Introduction-to-the-API.ipynb

Imports the main class for interacting with openPMD data from the `openpmd_viewer` library. This class is essential for loading and accessing time series data.

```python
from openpmd_viewer import OpenPMDTimeSeries
```

--------------------------------

### Get Particle Divergence

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/5_Laser-plasma_tools.ipynb

Computes the divergence of selected particles, defined as the average of arctan(ux/uz) and arctan(uy/uz) at a specific iteration. Particle selection is supported.

```python
ts_2d.get_divergence(iteration=300, species='electrons')
```

--------------------------------

### Get Mean Gamma

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/5_Laser-plasma_tools.ipynb

Calculates the mean relativistic factor (gamma) and its standard deviation for selected particles at a given iteration. Particles can be filtered by momentum or other properties.

```python
ts_2d.get_mean_gamma(iteration=300, species='electrons', select={'uz' : [0.05, None]})
```

--------------------------------

### Enable Matplotlib Widget (Python)

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/3_Introduction-to-the-GUI.ipynb

Configures the Jupyter environment to use the interactive matplotlib backend. Essential for interactive GUI elements within the notebook.

```Python
%matplotlib widget
```

--------------------------------

### Get Particle Current

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/5_Laser-plasma_tools.ipynb

Calculates the instantaneous longitudinal current (along the z-axis) generated by selected particles at a given iteration. The method can optionally plot the current profile directly.

```python
ts_2d.get_current(iteration=300, species='electrons', plot=True);
```

--------------------------------

### Get Laser Envelope

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/5_Laser-plasma_tools.ipynb

Computes the envelope of a laser field for a specified polarization ('x' or 'y') at a given iteration. The method can return a 1D or 2D array depending on the slice analyzed.

```python
ts_2d.get_laser_envelope(iteration=300, pol='y');
```

--------------------------------

### Initialize OpenPMD TimeSeries

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/4_Particle_selection.ipynb

Imports necessary plotting libraries and initializes the `OpenPMDTimeSeries` object. This object is used to load and access data from openPMD files, pointing to the directory containing the data.

```python
%matplotlib inline
import matplotlib.pyplot as plt
import numpy as np

from openpmd_viewer import OpenPMDTimeSeries
ts = OpenPMDTimeSeries('./example-2d/hdf5/')
```

--------------------------------

### Load OpenPMDTimeSeries (Python)

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/3_Introduction-to-the-GUI.ipynb

Loads the `OpenPMDTimeSeries` class from the `openpmd_viewer` library. This is the primary object for accessing and visualizing openPMD data.

```Python
from openpmd_viewer import OpenPMDTimeSeries
```

--------------------------------

### Access openPMD-viewer get_particle Docstring

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/1_Introduction-to-the-API.ipynb

Shows how to access the detailed docstring for the `get_particle` method in an IPython environment. This is useful for understanding all available parameters and functionalities. It uses the `?` operator.

```python
ts.get_particle?
```

--------------------------------

### Get Field with Specific Azimuthal Mode (Python)

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/2_Specific-field-geometries.ipynb

Retrieves a specific azimuthal mode of a field component in cylindrical geometry. This is useful for analyzing data where fields are decomposed into modes, such as laser-wakefield simulations.

```python
Ey, info_Ey = ts_circ.get_field( field='E', coord='y', iteration=500, m=0, 
                              plot=True, theta=0.5)

```

--------------------------------

### Instantiate LpaDiagnostics

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/5_Laser-plasma_tools.ipynb

Loads the LpaDiagnostics class from openpmd_viewer.addons and creates an instance to analyze laser-plasma simulation data. This class inherits from OpenPMDTimeSeries.

```python
from openpmd_viewer.addons import LpaDiagnostics

ts_2d = LpaDiagnostics('./example-2d/hdf5/')
```

--------------------------------

### Get Field with Sum of All Azimuthal Modes (Python)

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/2_Specific-field-geometries.ipynb

Retrieves the sum of all azimuthal modes for a field component in cylindrical geometry. This is useful for visualizing the total field contribution when multiple modes are present, like in laser fields.

```python
Ey, info_Ey = ts_circ.get_field( field='E', coord='y', iteration=500, m='all', 
                              plot=True, theta=0.5)

```

--------------------------------

### Get Normalized Emittance

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/5_Laser-plasma_tools.ipynb

Calculates the normalized root-mean-square (RMS) emittance in the x and y planes for selected particles. This is based on the formula \epsilon_{n,rms}=\sqrt{\langle x^2 \rangle \langle u_x^2 \rangle - \langle x u_x \rangle^2}.

```python
ts_2d.get_emittance(iteration=300, species='electrons')
```

--------------------------------

### Use GUI Slider for 3D Data (Python)

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/3_Introduction-to-the-GUI.ipynb

Creates an interactive GUI slider for visualizing 3D Cartesian openPMD data. Allows specifying separate figures for fields and particles.

```Python
ts_3d = OpenPMDTimeSeries('./example-3d/hdf5/')
ts_3d.slider( fields_figure=2, particles_figure=3 )
```

--------------------------------

### Push Changes to Origin

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/CONTRIBUTING.md

Push your local branch with new commits to your forked repository on GitHub.

```git
git push -u origin <NewBranchName>
```

--------------------------------

### Track Particles Across Iterations

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/4_Particle_selection.ipynb

Explains how to track particles by first selecting a subset at a specific iteration using `ParticleTracker`, and then retrieving these same particles at potentially different iterations. The `ParticleTracker` instance is passed to `get_particle`'s `select` argument.

```python
from openpmd_viewer import ParticleTracker

# Select particles to be tracked at iteration 300 based on criteria
pt = ParticleTracker( ts, iteration=300, select={'uz':[0.05,0.2], 'z':[22e-6,26e-6]}, species='electrons' )

plot_iteration = 300
# Plot the selected particles at the initial iteration
ts.get_particle( ['z', 'uz'], species='electrons', iteration=plot_iteration, plot=True, vmax=1e12 )
z_selected, uz_selected = ts.get_particle( ['z', 'uz'], species='electrons', iteration=plot_iteration, select=pt )
plt.plot(z_selected, uz_selected, 'r.')

# Retrieve and plot the same tracked particles at a different iteration (e.g., 350)
plot_iteration = 350
z_tracked, uz_tracked = ts.get_particle( ['z', 'uz'], species='electrons', iteration=plot_iteration, select=pt )
plt.plot(z_tracked, uz_tracked, 'r.')
```

--------------------------------

### Select Particles by Criteria

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/4_Particle_selection.ipynb

Demonstrates how to select particles based on specific criteria using the `get_particle` method with the `select` argument. The `select` argument takes a dictionary where keys are particle quantities and values are lists defining the bounds for selection. Multiple criteria can be combined.

```python
# Plot all electrons in phase space
ts.get_particle( ['z', 'uz'], species='electrons', iteration=300, plot=True, vmax=1e12 )

# Select and plot electrons with uz between 0.05 and 0.2
z_selected, uz_selected = ts.get_particle( ['z', 'uz'], species='electrons', 
                            iteration=300, select={'uz':[0.05,0.2]} )
plt.plot(z_selected, uz_selected, 'g.')

# Select and plot electrons with uz between 0.05 and 0.2 AND z between 22e-6 and 26e-6
z_selected, uz_selected = ts.get_particle( ['z', 'uz'], species='electrons', 
                            iteration=300, select={'uz':[0.05,0.2], 'z':[22e-6,26e-6]} )
plt.plot(z_selected, uz_selected, 'g.')
```

--------------------------------

### Get 3D Cartesian Slice (across y)

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/2_Specific-field-geometries.ipynb

Retrieves a 2D slice of the 'E' field along the 'z' coordinate from a 3D Cartesian dataset. The slice is taken across the 'y' axis, resulting in a plane parallel to the x-z plane. The `plot=True` argument displays the slice.

```Python
# Slice across y (i.e. in a plane parallel to x-z)
Ez1, info_Ez1 = ts_3d.get_field( field='E', coord='z', iteration=500, 
                                    slice_across='y', plot=True )
```

--------------------------------

### Get 3D Cartesian Slice (across z)

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/2_Specific-field-geometries.ipynb

Retrieves a 2D slice of the 'E' field along the 'z' coordinate from a 3D Cartesian dataset. The slice is taken across the 'z' axis, resulting in a plane parallel to the x-y plane. The `plot=True` argument displays the slice.

```Python
# Slice across z (i.e. in a plane parallel to x-y)
Ez2, info_Ez2 = ts_3d.get_field( field='E', coord='z', iteration=500,
                                    slice_across='z', plot=True )
```

--------------------------------

### Get Full 3D Cartesian Array (Python)

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/2_Specific-field-geometries.ipynb

Retrieves the field data as a full 3D Cartesian array by setting `theta=None`. This bypasses the cylindrical projection and provides raw 3D data, suitable for manual analysis with libraries like NumPy or comparison with Cartesian simulations.

```python
# Get the full 3D Cartesian array
Ey_3d, info_Ey3d = ts_circ.get_field( field='E', coord='y', iteration=500, theta=None )
print( Ey_3d.ndim )

```

--------------------------------

### Commit Changes

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/CONTRIBUTING.md

Commands to stage and commit your code changes.

```git
git add <ChangedFiles>
git commit
```

--------------------------------

### Get 3D Cartesian Slice (across x and y)

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/2_Specific-field-geometries.ipynb

Retrieves a 1D slice (line) of the 'E' field along the 'z' coordinate from a 3D Cartesian dataset. The slice is taken across both 'x' and 'y' axes, resulting in a line parallel to the z-axis. The `plot=True` argument displays the slice.

```Python
# Slice across x and y (i.e. along a line parallel to the z axis)
Ez2, info_Ez2 = ts_3d.get_field( field='E', coord='z', iteration=500,
                                    slice_across=['x','y'], plot=True )
```

--------------------------------

### Use GUI Slider for Cylindrical Data (Python)

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/3_Introduction-to-the-GUI.ipynb

Creates an interactive GUI slider for visualizing cylindrical openPMD data with azimuthal decomposition. The GUI adapts to show mode selection and angle options.

```Python
ts_circ = OpenPMDTimeSeries('./example-thetaMode/hdf5/')
ts_circ.slider( fields_figure=4 )
```

--------------------------------

### Get Full 3D Cartesian Array

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/2_Specific-field-geometries.ipynb

Retrieves the complete 3D Cartesian array for the 'E' field along the 'z' coordinate at a given iteration. Setting `slice_across=None` bypasses slicing, returning the full volume data, which can be useful for manual analysis with libraries like NumPy. The output `ndim` is printed to confirm it's a 3D array.

```Python
# Get the full 3D Cartesian array
Ez_3d, info_Ez_3d = ts_3d.get_field( field='E', coord='z', iteration=500, slice_across=None )
print( Ez_3d.ndim )
```

--------------------------------

### Manually Reconstruct and Store Trajectories

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/4_Particle_selection.ipynb

Demonstrates the manual process of reconstructing particle trajectories by iterating through all available time steps. It retrieves the 'uz' component for selected particles at each iteration and stores them in a NumPy array for later analysis or plotting.

```python
N_iterations = len(ts.iterations)
N_particles = pt.N_selected

uz_trajectories = np.empty( ( N_iterations, N_particles ) )
for i in range( N_iterations ):
    uz, = ts.get_particle( ['uz'], select=pt, iteration=ts.iterations[i], species='electrons' )
    uz_trajectories[i, :] = uz[:]
```

--------------------------------

### Get 3D Cartesian Slice (relative position)

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/2_Specific-field-geometries.ipynb

Retrieves a 2D slice of the 'E' field along the 'z' coordinate from a 3D Cartesian dataset, specifying a relative position along the slicing axis. A value of -0.9 for `slice_relative_position` selects a slice near the lower bound (e.g., z_min) when slicing across 'z'. The `plot=True` argument displays the slice.

```Python
# Slice across z, very close to zmin.
Ez2, info_Ez2 = ts_3d.get_field( field='E', coord='z', iteration=500, 
     slice_across='z', slice_relative_position=-0.9, plot=True )
```

--------------------------------

### Create New Feature Branch

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/CONTRIBUTING.md

How to create a new branch from the development branch for implementing a new feature.

```git
git checkout -b <NewBranchName>
```

--------------------------------

### Initialize ParticleTracker for Trajectory Reconstruction

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/tutorials/4_Particle_selection.ipynb

Initializes a ParticleTracker object to select and track specific electrons based on their properties (uz, z) over a range of iterations. The `preserve_particle_index=True` argument is crucial for ensuring consistent particle indexing across iterations.

```python
pt = ParticleTracker( ts, iteration=300, select={'uz':[0.05,0.1], 'z':[22e-6,26e-6]},
                        species='electrons', preserve_particle_index=True )
```

--------------------------------

### OpenPMDTimeSeries Class and Methods

Source: https://github.com/openpmd/openpmd-viewer/blob/dev/docs/source/api_reference/generic_interface.rst

Provides a high-level interface to read and process openPMD data files across multiple time steps. It allows access to fields and particles, iteration over time steps, and dynamic adjustments using sliders.

```APIDOC
OpenPMDTimeSeries:
  A class providing a generic interface to openPMD data files.

  Methods:
    get_field(field_name, iteration=None, mpi_rank=0, mpi_size=1, **kwargs):
      Retrieves a specific field from the dataset for a given time step.
      - Parameters:
        - field_name (str): The name of the field to retrieve (e.g., 'E/x', 'B/y').
        - iteration (int, optional): The time step index. If None, the current iteration is used.
        - mpi_rank (int, optional): The MPI rank for distributed data access.
        - mpi_size (int, optional): The total number of MPI ranks.
        - **kwargs: Additional keyword arguments for specific field access.
      - Returns: A data structure representing the field (e.g., numpy.ndarray).

    get_particle(particle_type, iteration=None, mpi_rank=0, mpi_size=1, **kwargs):
      Retrieves particle data for a specified particle type at a given time step.
      - Parameters:
        - particle_type (str): The type of particles to retrieve (e.g., 'electron', 'proton').
        - iteration (int, optional): The time step index. If None, the current iteration is used.
        - mpi_rank (int, optional): The MPI rank for distributed data access.
        - mpi_size (int, optional): The total number of MPI ranks.
        - **kwargs: Additional keyword arguments for specific particle data access.
      - Returns: A data structure containing particle data (e.g., a dictionary of numpy.ndarray).

    iterate(field_name=None, particle_type=None, mpi_rank=0, mpi_size=1):
      Iterates over the time steps of the dataset, optionally loading specified fields or particle types.
      - Parameters:
        - field_name (str, optional): The name of the field to load for each iteration.
        - particle_type (str, optional): The type of particles to load for each iteration.
        - mpi_rank (int, optional): The MPI rank for distributed data access.
        - mpi_size (int, optional): The total number of MPI ranks.
      - Yields: The current iteration index and loaded data (fields/particles).

    slider(field_name=None, particle_type=None, iteration=None, mpi_rank=0, mpi_size=1):
      Provides a mechanism to dynamically adjust or select data based on a 'slider' concept, typically for interactive visualization or analysis.
      - Parameters:
        - field_name (str, optional): The name of the field to associate with the slider.
        - particle_type (str, optional): The type of particles to associate with the slider.
        - iteration (int, optional): The initial or current time step for the slider.
        - mpi_rank (int, optional): The MPI rank for distributed data access.
        - mpi_size (int, optional): The total number of MPI ranks.
      - Returns: An object or interface that allows manipulation of the current time step or data selection.
```