ozzy.fields

This submodule includes functions to analyze field data.

local_maxima_and_zero_crossings

local_maxima_and_zero_crossings(
    da,
    comoving_var="x1_box",
    transv_var="x2",
    tvar="t",
    transv_range=None,
    transv_irange=None,
    transv_pos=None,
    transv_ipos=None,
    amplitude_mode="noisy",
    expected_wvl=2 * np.pi,
    amplitude_max_for="negative_charge",
)

Find local field maxima and zero crossings in a DataArray.

This function analyzes a field (typically an electric field) to identify local maxima and zero crossings along a specified dimension. It can process the data in different ways depending on whether the field data is noisy or smooth.

Parameters:

Name	Type	Description	Default
da	DataArray	The data array containing the field to analyze.	required
comoving_var	str	The name of the coordinate representing the comoving dimension.	'x1_box'
transv_var	str	The name of the coordinate representing the transverse dimension.	'x2'
tvar	str	The name of the coordinate representing time.	't'
transv_range	tuple | list | ndarray	Range of transverse positions to average over, specified as (min, max).	None
transv_irange	tuple | list | ndarray	Range of transverse indices to average over, specified as (min, max).	None
transv_pos	float	Specific transverse position to analyze.	None
transv_ipos	int	Specific transverse index to analyze.	None
amplitude_mode	str	Method for handling amplitude analysis. Must be either 'noisy' or 'smooth'. For 'noisy' data, a moving window average is applied before analysis.	'noisy'
expected_wvl	float	Expected wavelength of the oscillations in the field in normalized units (i.e. \(k_p^{-1}\)) used for window sizing.	2 * pi
amplitude_max_for	str	Specifies which charge sign to find the maximum accelerating amplitude for. Must be either 'negative_charge' or 'positive_charge'.	'negative_charge'

Returns:

Type	Description
tuple	A tuple containing two xarray.Dataset objects: First element: Dataset with local maxima information Second element: Dataset with zero crossing information

Raises:

Type	Description
ValueError	If required coordinates are missing from the DataArray. If invalid options are provided for amplitude_mode or amplitude_max_for. If invalid ranges or positions are specified for transverse selection.

Notes

The function processes data differently based on the amplitude_mode:

• For 'noisy' data: Applies a moving window average before analysis

• For 'smooth' data: Analyzes the raw data directly

Examples:

Basic usage with default parameters

import xarray as xr
import numpy as np

# Create a sample dataset with a sinusoidal field
x = np.linspace(0, 10*np.pi, 1000)
y = np.linspace(-5, 5, 20)
t = np.array([0.0, 1.0, 2.0])

# Create field data with some noise
field = np.zeros((len(t), len(y), len(x)))
for i in range(len(t)):
    for j in range(len(y)):
        field[i, j, :] = np.sin(x) + 0.1*np.random.randn(len(x))

# Create DataArray
da = xr.DataArray(
    field,
    coords={'t': t, 'x2': y, 'x1_box': x},
    dims=['t', 'x2', 'x1_box']
)

# Find zero crossings and maxima
maxima, zeros = local_maxima_and_zero_crossings(da)

# The returned datasets contain information about zero crossings and maxima
# zeros contains 'zero_crossings' coordinate
# maxima contains 'max_locs' and 'max_vals' coordinates

Using custom parameters for a smooth field

import xarray as xr
import numpy as np

# Create a sample dataset with a clean sinusoidal field
x = np.linspace(0, 10*np.pi, 1000)
y = np.linspace(-5, 5, 20)
t = np.array([0.0, 1.0, 2.0])

# Create clean field data
field = np.zeros((len(t), len(y), len(x)))
for i in range(len(t)):
    for j in range(len(y)):
        field[i, j, :] = np.sin(x)

# Create DataArray
da = xr.DataArray(
    field,
    coords={'t': t, 'x2': y, 'x1_box': x},
    dims=['t', 'x2', 'x1_box']
)

# Find zero crossings and maxima with custom parameters
maxima, zeros = local_maxima_and_zero_crossings(
    da,
    comoving_var="x1_box",
    transv_range=(-2, 2),  # Average over this transverse range
    amplitude_mode="smooth",  # Use smooth mode for clean data
    amplitude_max_for="positive_charge"  # Find positive field amplitude maximum
)

vphi_from_fit

vphi_from_fit(
    da,
    x_zero,
    xvar="x1_box",
    tvar="t",
    window_len=2.5,
    k=1.0,
    boundary="trim",
    quasistatic_fixed_z=False,
)

Measure the phase (\(\phi\)) and phase velocity (\(v_\phi\)) from stacked lineouts of a wave (waterfall data) by fitting a sinusoidal function to blocks of data.

Parameters:

Name	Type	Description	Default
da	DataArray	The input xarray.DataArray containing the data to be analyzed. The data should be two-dimensional: time or propagation distance along one dimension, and a longitudinal coordinate along the other dimension.	required
x_zero	float	Position along the longitudinal coordinate where the sine should be considered to start, and with respect to which the phase will be measured. For example, a seed position.	required
xvar	str	The name of the spatial dimension along which to perform the fit. Default is 'x1'.	'x1_box'
tvar	str	The name of the time or propagation dimension. Default is 't'.	't'
window_len	float	The length of the window (in units of the plasma wavelength) over which to perform the fit. Default is 2.5.	2.5
k	float | str	The wavenumber to use in the definition of the window length. If 'fft', the wavenumber will be calculated from the FFT of the data. Default is 1.0.	1.0
boundary	str	How to handle boundaries when coarsening the data into blocks. One of 'trim', 'pad', or 'drop'. See xarray.DataArray.coarsen.	'trim'
quasistatic_fixed_z	bool	If True, the phase velocity is calculated assuming a quasistatic approximation with a fixed z-dimension. Default is False.	False

Returns:

Type	Description
Dataset	A dataset containing the calculated phase velocity ('vphi'), phase ('phi'), and phase error ('phi_err').