開発版ドキュメント · 0.2.3 30c2f8ba · 入門例の検証対象 0.2.3 · 版情報 · 既知の制限

Fields#

Unified field API entrypoint.

class gwexpy.fields.ScalarField(value, *, unit=None, name=None, epoch=None, channel=None, dtype=None, copy=True, subok=True, order=None, ndmin=0, axis0=None, axis1=None, axis2=None, axis3=None, axis_names=None, axis0_domain: str = 'time', space_domain: str | dict[str, str] = 'real')#

ベースクラス: FieldBase

A 4-dimensional scalar field with domain tracking.

ScalarField represents a physical field defined on a 4D grid (typically 1 time and 3 spatial dimensions). It supports domain transformations (Fourier transforms) while preserving coordinate metadata and units.

パラメータ:

data (array-like) -- 4-dimensional input data.
unit (str, ~astropy.units.Unit, optional) -- Physical unit of the field values.
axis0 (array-like, optional) -- Coordinate values for axis 0 (Time or Frequency).
axis1 (array-like, optional) -- Coordinate values for spatial axes.
axis2 (array-like, optional) -- Coordinate values for spatial axes.
axis3 (array-like, optional) -- Coordinate values for spatial axes.
axis_names (iterable of str, optional) -- Names for each axis (length 4).
axis0_domain ({'time', 'frequency'}, optional) -- Initial domain of the first axis.
space_domain ({'real', 'k'} or dict, optional) -- Initial domain of the spatial axes.
**kwargs -- Additional keyword arguments passed to FieldBase.

メモ

A key feature of ScalarField is that slicing always returns a 4D ScalarField. Integer indices are automatically converted to length-1 slices to prevent dimension loss.

サンプル

>>> import numpy as np
>>> from gwexpy.fields import ScalarField
>>> data = np.ones((2, 2, 2, 2))
>>> sf = ScalarField(data, axis0=[0, 1], axis1=[0, 1],
...                  axis2=[0, 1], axis3=[0, 1])
>>> sf
<ScalarField([[[[1., 1.],
                [1., 1.]],
...
             axis0_domain='time',
             space_domains={'x': 'real', 'y': 'real', 'z': 'real'},
             axis0_offset=None)>

coherence_map(ref_point, plane='xy', at=None, **kwargs)#

Compute coherence map from a reference point.

This is a convenience wrapper around coherence_map().

パラメータ:

ref_point (tuple of Quantity) -- Reference point coordinates (x, y, z).
plane (str) -- 2D plane to map: 'xy', 'xz', or 'yz'. Default 'xy'.
at (dict, optional) -- Fixed value for the axis not in the plane.
**kwargs -- Additional keyword arguments passed to coherence_map.

戻り値:

Coherence map.

戻り値の型:

ScalarField or FieldDict

参考

gwexpy.fields.signal.coherence_map: Full documentation.

compute_psd(point_or_region, **kwargs)#

Compute power spectral density using Welch's method.

This is a convenience wrapper around compute_psd().

パラメータ:

point_or_region (tuple, list of tuples, or dict) -- Spatial location(s) to extract: - Single point: (x, y, z) tuple of Quantities - Multiple points: list of (x, y, z) tuples - Region dict: {'x': slice or value, 'y': ..., 'z': ...}
**kwargs -- Additional keyword arguments passed to compute_psd: nperseg, noverlap, window, detrend, scaling, average.

戻り値:

PSD estimate(s).

戻り値の型:

FrequencySeries or FrequencySeriesList

参考

gwexpy.fields.signal.compute_psd: Full documentation.

compute_xcorr(point_a, point_b, **kwargs)#

Compute cross-correlation between two spatial points.

This is a convenience wrapper around compute_xcorr().

パラメータ:

point_a (tuple of Quantity) -- Spatial coordinates (x, y, z) for the two points.
point_b (tuple of Quantity) -- Spatial coordinates (x, y, z) for the two points.
**kwargs -- Additional keyword arguments passed to compute_xcorr.

戻り値:

Cross-correlation function with lag axis.

戻り値の型:

TimeSeries

参考

gwexpy.fields.signal.compute_xcorr: Full documentation.

diff(n=1, axis=-1, *, mode=None)#

Compute a GWpy finite difference or compare two fields.

パラメータ:

n (int or ScalarField, optional) -- Difference order for the GWpy-compatible route. Passing another ScalarField explicitly selects the field-comparison extension.
axis (int or str, optional) -- Difference axis, or the legacy positional comparison mode when n is a ScalarField.
mode (str, keyword-only, optional) -- Comparison mode: - 'diff': Difference (self - other) - 'ratio': Ratio (self / other) - 'percent': Percentage difference ((self - other) / other * 100) Default is 'diff'.

戻り値:

Result field. For 'diff', unit is same as input. For 'ratio', unit is dimensionless. For 'percent', unit is percent.

戻り値の型:

ScalarField

例外:

ValueError -- If mode is not recognized.
ValueError -- If shapes are incompatible.
astropy.units.UnitConversionError -- If the two fields have incompatible data units.

サンプル

>>> import numpy as np
>>> from gwexpy.fields import ScalarField
>>> sf = ScalarField(np.ones((2, 2, 2, 2)))
>>> sf
<ScalarField(2, 2, 2, 2)@time, 1.0>

extract_points(points: Sequence[Sequence[Quantity]] | Sequence[tuple[Quantity, ...]], interp: str = 'linear') → Any#

Extract time series at specified spatial points.

パラメータ:

points (list of tuple) -- List of (x, y, z) coordinates.
interp (str, optional) -- Interpolation method ('linear' or 'nearest'). Default is 'linear'.

戻り値:

List of time series, one per point.

戻り値の型:

TimeSeriesList

extract_profile(axis: str, at: dict[str, u.Quantity], reduce: str | None = None, interp: str = 'linear') → tuple[IndexLike, Any]#

Extract a 1D profile along a specified axis.

パラメータ:

axis (str) -- Axis name to extract along ('x', 'y', 'z', or their k-variants).
at (dict) -- Dictionary specifying fixed values for the other axes. Must include all axes except the extraction axis. Example: {'t': 0.5 * u.s, 'y': 2.0 * u.m, 'z': 0.0 * u.m}
reduce (None) -- Reserved for future averaging support. Currently ignored.
interp (str, optional) -- Interpolation method ('linear' or 'nearest'). Default is 'linear'.

戻り値:

(axis_index, values): Both are ~astropy.units.Quantity arrays. axis_index is the coordinate along the extraction axis, values is the data values along that axis.

戻り値の型:

tuple

fft_space(axes: Iterable[str] | None = None, n: Sequence[int] | None = None, overwrite: bool = False) → ScalarField#

Compute FFT along spatial axes.

This method uses two-sided FFT (scipy.fft.fftn) and produces angular wavenumber (k = 2π·fftfreq).

パラメータ:

axes (iterable of str, optional) -- Axis names to transform (e.g., ['x', 'y']). If None, transforms all spatial axes in 'real' domain.
n (tuple of int, optional) -- FFT lengths for each axis.
overwrite (bool, optional) -- If True, perform FFT in-place on a temporary copy of the data to reduce peak memory usage. Default is False.

戻り値:

Transformed field with specified axes in 'k' domain.

戻り値の型:

ScalarField

例外:

ValueError -- If any specified axis is not in 'real' domain.
ValueError -- If any specified axis is not uniformly spaced.

メモ

Angular Wavenumber Convention

The wavenumber axis is computed as k = 2π * fftfreq(n, d=dx), satisfying k = 2π / λ. This is the standard angular wavenumber definition in physics, with units of [rad/length].

Note: This is NOT the cycle wavenumber (1/λ) commonly used in some fields. To convert: k_cycle = k_angular / (2π).

Sign Convention for Descending Axes (dx < 0)

If the spatial axis is descending (dx < 0), the k-axis is sign-flipped to preserve physical consistency with the phase factor convention e^{+ikx}. This ensures that positive k corresponds to waves propagating in the positive x direction, regardless of the data storage order.

This convention differs from the standard FFT behavior (which ignores axis direction) but maintains physical consistency for interferometer simulations and wave propagation analysis.

This formula has been validated through unit tests and independent technical review (2026-02-01). The 2π factor is correctly applied, and units are properly set as 1/dx_unit.

参照

fft_time(nfft: int | None = None) → ScalarField#

Compute FFT along the time axis (axis 0).

Transforms the field from 'time' to 'frequency' domain using scipy.fft.rfft, applying GWpy-style half-sided normalization.

パラメータ:: nfft (int, optional) -- Length of the FFT. Defaults to the length of axis 0.
戻り値:: A new field with axis0_domain='frequency'.
戻り値の型:: ScalarField

メモ

Normalizes by 1/nfft and doubles non-DC/non-Nyquist bins to preserve amplitude.

参考

gwpy.timeseries.TimeSeries.fft: The underlying transformation.

filter(*args, **kwargs) → ScalarField#

Apply a filter along the time axis (axis 0).

パラメータ:

*args -- Filter specification. Supports same arguments as gwpy.timeseries.TimeSeries.filter().
**kwargs -- Filter specification. Supports same arguments as gwpy.timeseries.TimeSeries.filter().

戻り値:

Filtered field.

戻り値の型:

ScalarField

freq_space_map(axis, at=None, **kwargs)#

Compute frequency-space map along a spatial axis.

This is a convenience wrapper around freq_space_map().

パラメータ:

axis (str) -- Spatial axis to scan along ('x', 'y', or 'z').
at (dict, optional) -- Fixed values for the other two spatial axes.
**kwargs -- Additional keyword arguments passed to freq_space_map.

戻り値:

2D frequency-space map.

戻り値の型:

ScalarField

参考

gwexpy.fields.signal.freq_space_map: Full documentation.

classmethod from_pyroomacoustics_field(room: Any, *, grid_shape: tuple[int, ...], source: int = 0, mode: str = 'rir', unit: Any | None = None) → ScalarField#

Create from pyroomacoustics room with grid-placed microphones.

パラメータ:

room (pyroomacoustics.Room) -- Room with microphones on a regular spatial grid.
grid_shape (tuple of int) -- Spatial grid shape (nx, ny, nz) or (nx, ny).
source (int, default 0) -- Source index (for mode='rir').
mode ({'rir', 'signals'}) -- 'rir' for impulse responses, 'signals' for mic signals.
unit (str or astropy.units.Unit, optional) -- Unit to assign to the data.

戻り値の型:

ScalarField

ifft_space(axes: Iterable[str] | None = None, n: Sequence[int] | None = None, overwrite: bool = False) → ScalarField#

Compute inverse FFT along k-space axes.

パラメータ:

axes (iterable of str, optional) -- Axis names to transform (e.g., ['kx', 'ky']). If None, transforms all spatial axes in 'k' domain.
n (tuple of int, optional) -- Output lengths for each axis.
overwrite (bool, optional) -- If True, perform IFFT in-place on a temporary copy.

戻り値:

Transformed field with specified axes in 'real' domain.

戻り値の型:

ScalarField

例外:

ValueError -- If any specified axis is not in 'k' domain.

ifft_time(nout: int | None = None) → ScalarField#

Compute inverse FFT along frequency axis (axis 0).

This method applies the inverse normalization of fft_time() / GWpy's FrequencySeries.ifft().

パラメータ:

nout (int, optional) -- Length of the output time series. If None, computed as (n_freq - 1) * 2.

戻り値:

Transformed field with axis0_domain='time'.

戻り値の型:

ScalarField

例外:

ValueError -- If axis0_domain is not 'frequency'.
ValueError -- If frequency axis length < 2 or is irregularly spaced.

参考

gwpy.frequencyseries.FrequencySeries.ifft: Reference implementation.

plot_map2d(plane='xy', at=None, mode='real', method='pcolormesh', ax=None, add_colorbar=True, vmin=None, vmax=None, title=None, cmap=None, **kwargs)#

Plot a 2D map (heatmap) of the field.

パラメータ:

plane (str, optional) -- The plane to plot: 'xy', 'xz', 'yz', 'tx', 'ty', 'tz'. Default is 'xy'.
at (dict, optional) -- Dictionary specifying fixed values for axes not in the plane. If None, axes with length=1 are used automatically.
mode (str, optional) -- Component to extract from complex data: 'real', 'imag', 'abs', 'angle', 'power'. Default is 'real'.
method (str, optional) -- Plot method: 'pcolormesh' or 'imshow'. Default is 'pcolormesh'.
ax (matplotlib.axes.Axes, optional) -- Axes to plot on. If None, creates new figure.
add_colorbar (bool, optional) -- Whether to add a colorbar. Default is True.
vmin (float, optional) -- Color scale limits.
vmax (float, optional) -- Color scale limits.
title (str, optional) -- Plot title.
cmap (str or Colormap, optional) -- Colormap to use.
**kwargs -- Additional arguments passed to the plot method.

戻り値:

(fig, ax): The matplotlib figure and axes objects.

戻り値の型:

tuple

サンプル

>>> import numpy as np
>>> from gwexpy.fields import ScalarField
>>> sf = ScalarField(np.ones((1, 10, 10, 1)))
>>> fig, ax = sf.plot_map2d('xy', at={'z': 0.0})

plot_profile(axis, at, mode='real', ax=None, label=None, **kwargs)#

Plot a 1D profile along a specified axis.

パラメータ:

axis (str) -- Axis name to plot along.
at (dict) -- Dictionary specifying fixed values for other axes.
mode (str, optional) -- Component to extract: 'real', 'imag', 'abs', 'angle', 'power'. Default is 'real'.
ax (matplotlib.axes.Axes, optional) -- Axes to plot on. If None, creates new figure.
label (str, optional) -- Line label for legend.
**kwargs -- Additional arguments passed to plot.

戻り値:

(fig, ax): The matplotlib figure and axes objects.

戻り値の型:

tuple

サンプル

>>> import numpy as np
>>> from gwexpy.fields import ScalarField
>>> sf = ScalarField(np.ones((2, 4, 4, 1)))
>>> fig, ax = sf.plot_profile('x', at={'t': 0.5 * u.s, 'y': 0.0 * u.m, 'z': 0.0 * u.m})

plot_time_space_map(axis='x', at=None, mode='real', method='pcolormesh', ax=None, add_colorbar=True, vmin=None, vmax=None, title=None, cmap=None, **kwargs)#

Plot a 2D time-space map (t vs one spatial axis).

パラメータ:

axis (str, optional) -- Spatial axis name. Default is 'x'.
at (dict, optional) -- Fixed values for other spatial axes.
mode (str, optional) -- Component to extract. Default is 'real'.
method (str, optional) -- Plot method. Default is 'pcolormesh'.
ax (matplotlib.axes.Axes, optional) -- Axes to plot on.
add_colorbar (bool, optional) -- Whether to add colorbar. Default is True.
vmin (float, optional) -- Color scale limits.
vmax (float, optional) -- Color scale limits.
title (str, optional) -- Plot title.
cmap (str or Colormap, optional) -- Colormap to use.
**kwargs -- Additional plot arguments.

戻り値:

(fig, ax): The matplotlib figure and axes objects.

戻り値の型:

tuple

サンプル

>>> import numpy as np
>>> from gwexpy.fields import ScalarField
>>> from astropy import units as u
>>> sf = ScalarField(np.ones((100, 4, 1, 1)), axis1=np.arange(4)*u.m)
>>> fig, ax = sf.plot_time_space_map('x')

plot_timeseries_points(points, labels=None, interp='nearest', ax=None, legend=True, **kwargs)#

Plot time series extracted at specified spatial points.

パラメータ:

points (list of tuple) -- List of (x, y, z) coordinates.
labels (list of str, optional) -- Labels for each time series. If None, auto-generated.
interp (str, optional) -- Interpolation method. Default is 'nearest'.
ax (matplotlib.axes.Axes, optional) -- Axes to plot on. If None, creates new figure.
legend (bool, optional) -- Whether to show legend. Default is True.
**kwargs -- Additional arguments passed to plot.

戻り値:

(fig, ax): The matplotlib figure and axes objects.

戻り値の型:

tuple

サンプル

>>> import numpy as np
>>> from gwexpy.fields import ScalarField
>>> sf = ScalarField(np.ones((1024, 1, 1, 1)))
>>> psd = sf.compute_psd((0, 0, 0))

psd(**kwargs)#

Compute power spectral density along time axis.

Convenience method equivalent to spectral_density(axis=0). Uses Welch's method by default for robust PSD estimation.

パラメータ:

**kwargs --

Keyword arguments passed to spectral_density() or compute_psd() (if point_or_region is used). Common options:

point_or_regiontuple or list, optional
If provided, computes PSD at specific spatial point(s) or region average instead of full field. Returns FrequencySeries(List).
method : {'welch', 'fft'}, default 'welch'
fftlengthfloat, optional
Segment length in seconds (time-based specification)
nfftint, optional
Number of samples per segment (sample-based specification)
overlapfloat, optional
Overlap in seconds
noverlapint, optional
Number of overlapping samples
window : str, window function
scaling : {'density', 'spectrum'}

戻り値:

PSD field with axis0_domain='frequency'.

戻り値の型:

ScalarField

サンプル

>>> from astropy import units as u
>>> # Time-based specification
>>> psd_field = field.psd(fftlength=1.0, overlap=0.5)
>>> # Or sample-based specification
>>> psd_field = field.psd(nfft=512, noverlap=256)
>>> psd_field.shape  # (n_freq, nx, ny, nz)

参考

spectral_density: Generalized spectral density for any axis.

resample(rate, **kwargs) → ScalarField#

Resample the field along the time axis (axis 0).

パラメータ:

rate (float, Quantity) -- The new sampling rate (e.g., in Hz).
**kwargs -- Additional arguments passed to gwpy.timeseries.TimeSeries.resample().

戻り値:

Resampled field.

戻り値の型:

ScalarField

classmethod simulate(method: str, *args: Any, **kwargs: Any) → ScalarField#

Generate a simulated ScalarField.

パラメータ:

method (str) -- Name of the generator from gwexpy.noise.field. (e.g., 'gaussian', 'plane_wave').
*args -- Arguments passed to the generator.
**kwargs -- Arguments passed to the generator.

戻り値:

Generated field.

戻り値の型:

ScalarField

サンプル

>>> from gwexpy.fields import ScalarField
>>> field = ScalarField.simulate('gaussian', shape=(100, 10, 10, 10))

slice_map2d(plane='xy', at=None)#

Extract a 2D slice (map) from the 4D field.

パラメータ:

plane (str, optional) -- The plane to extract: 'xy', 'xz', 'yz', 'tx', 'ty', 'tz'. Default is 'xy'.
at (dict, optional) -- Dictionary specifying fixed values for axes not in the plane. If None, axes with length=1 are used automatically.

戻り値:

A ScalarField with the non-plane axes having length=1.

戻り値の型:

ScalarField

例外:

ValueError -- If plane specification is invalid.
ValueError -- If at is None and there is ambiguity about which axes to fix.

サンプル

>>> # Extract xy plane at a specific time and z
>>> field_2d = field.slice_map2d('xy', at={'t': 0.5 * u.s, 'z': 0.0 * u.m})
>>> field_2d.plot_map2d()

spectral_density(axis=0, **kwargs)#

Compute spectral density along any axis.

Generalized spectral density function that works on time axis (0) or spatial axes (1-3). Returns a new ScalarField with the transformed axis in spectral domain.

パラメータ:

axis (int or str) -- Axis to transform. Default 0 (time axis).
**kwargs -- Additional arguments passed to spectral_density(). See that function for full parameter list.

戻り値:

Spectral density field with transformed axis.

戻り値の型:

ScalarField

サンプル

>>> # Time PSD
>>> psd_field = field.spectral_density(axis=0)
>>> psd_field.axis0_domain  # 'frequency'

>>> # Spatial wavenumber spectrum
>>> kx_spec = field.spectral_density(axis='x')

参考

gwexpy.fields.signal.spectral_density: Full documentation.
psd: Convenience alias for time-axis PSD.

time_delay_map(ref_point, plane='xy', at=None, **kwargs)#

Compute time delay map from a reference point.

This is a convenience wrapper around time_delay_map().

パラメータ:

ref_point (tuple of Quantity) -- Reference point coordinates (x, y, z).
plane (str) -- 2D plane to map: 'xy', 'xz', or 'yz'. Default 'xy'.
at (dict, optional) -- Fixed value for the axis not in the plane.
**kwargs -- Additional keyword arguments passed to time_delay_map.

戻り値:

Time delay map.

戻り値の型:

ScalarField

参考

gwexpy.fields.signal.time_delay_map: Full documentation.

time_space_map(axis='x', at=None, mode='real', reduce=None)#

Extract a 2D time-space map (t vs one spatial axis).

パラメータ:

axis (str, optional) -- Spatial axis name ('x', 'y', 'z' or k-variants). Default is 'x'.
at (dict, optional) -- Fixed values for the other two spatial axes.
mode (str, optional) -- Component to extract: 'real', 'imag', 'abs', 'angle', 'power'. Default is 'real'.
reduce (None) -- Reserved for future averaging support. Currently ignored.

戻り値:

(t_axis, space_axis, data_2d): Quantity arrays for axes and 2D numpy array for the data.

戻り値の型:

tuple

例外:

ValueError -- If axis is not valid.
ValueError -- If at dictionary is missing required axes.

サンプル

>>> import numpy as np
>>> from astropy import units as u
>>> from gwexpy.fields import ScalarField
>>> sf = ScalarField(np.ones((100, 10, 1, 1)))
>>> t, x, data = sf.time_space_map('x', at={'y': 0 * u.m, 'z': 0 * u.m})

time_stat_map(stat='mean', t_range=None, plane='xy', at=None)#

Compute a time-aggregated 2D map.

パラメータ:

stat (str, optional) -- Statistic to compute: 'mean', 'std', 'rms', 'max', 'min'. Default is 'mean'.
t_range (tuple of Quantity, optional) -- Time range (t_start, t_end) to aggregate over. If None, uses the entire time axis.
plane (str, optional) -- Spatial plane to visualize: 'xy', 'xz', 'yz'. Default is 'xy'.
at (dict, optional) -- Fixed values for axes not in the plane.

戻り値:

Result field with time axis reduced to length=1.

戻り値の型:

ScalarField

例外:

ValueError -- If stat is not recognized.

サンプル

>>> import numpy as np
>>> from gwexpy.fields import ScalarField
>>> from astropy import units as u
>>> sf = ScalarField(np.ones((100, 2, 2, 2)), axis0=np.arange(100)*u.s)
>>> mean_map = sf.time_stat_map('mean', t_range=(0 * u.s, 1 * u.s))

wavelength(axis: str | int) → Quantity#

Compute wavelength from wavenumber axis.

パラメータ:: axis (str or int) -- The k-domain axis name or index.
戻り値:: Wavelength values ($\lambda = 2\pi / |k|$). k=0 returns inf.
戻り値の型:: ~astropy.units.Quantity
例外:: ValueError -- If the axis is not in 'k' domain.

zscore(baseline_t=None)#

Compute z-score normalized field using a baseline period.

The z-score is computed as (data - mean) / std, where mean and std are computed from the baseline period along axis 0 (time).

パラメータ:

baseline_t (tuple of Quantity, optional) -- Time range (t_start, t_end) for computing baseline statistics. If None, uses the entire time axis.

戻り値:

Z-score normalized field (dimensionless).

戻り値の型:

ScalarField

例外:

ValueError -- If axis0_domain is not 'time'.
ValueError -- If baseline time range is outside the available data.

サンプル

>>> import numpy as np
>>> from astropy import units as u
>>> from gwexpy.fields import ScalarField
>>> sf = ScalarField(np.ones((100, 2, 2, 2)), axis0=np.arange(100)*u.s)
>>> sf.zscore(baseline_t=(0 * u.s, 1 * u.s))
<ScalarField(100, 2, 2, 2)@time, ...>

gwexpy.fields.make_demo_scalar_field(pattern: ~typing.Literal['gaussian', 'sine', 'standing', 'noise'] = 'gaussian', nt: int = 100, nx: int = 16, ny: int = 16, nz: int = 16, dt: ~astropy.units.quantity.Quantity = <Quantity 0.01 s>, dx: ~astropy.units.quantity.Quantity = <Quantity 0.1 m>, dy: ~astropy.units.quantity.Quantity | None = None, dz: ~astropy.units.quantity.Quantity | None = None, unit: ~astropy.units.core.Unit = Unit("m / s"), seed: int = 42, **kwargs) → ScalarField#

Generate a deterministic demo ScalarField with known waveforms.

This function provides reproducible ScalarField data for testing, tutorials, and examples. All generated fields have proper axis metadata and units.

パラメータ:

pattern ({'gaussian', 'sine', 'standing', 'noise'}) -- Type of demo pattern: - 'gaussian': Propagating Gaussian pulse (default) - 'sine': Plane sinusoidal wave - 'standing': Standing wave pattern - 'noise': White noise (for PSD validation)
nt (int) -- Number of time points. Default is 100.
nx (int) -- Number of spatial points per axis. Default is 16.
ny (int) -- Number of spatial points per axis. Default is 16.
nz (int) -- Number of spatial points per axis. Default is 16.
dt (Quantity) -- Time step. Default is 0.01 s.
dx (Quantity) -- Spatial step for x-axis. Default is 0.1 m.
dy (Quantity, optional) -- Spatial steps for y and z. If None, uses dx.
dz (Quantity, optional) -- Spatial steps for y and z. If None, uses dx.
unit (Unit) -- Physical unit of the data. Default is m/s.
seed (int) -- Random seed for reproducibility. Default is 42.
**kwargs -- Additional keyword arguments passed to the specific pattern generator: - For 'gaussian': velocity, sigma_t, sigma_x - For 'sine': frequency, k_direction - For 'standing': mode_x, mode_y, mode_z, omega

戻り値:

Deterministic demo field with proper metadata.

戻り値の型:

ScalarField

サンプル

>>> from gwexpy.fields.demo import make_demo_scalar_field
>>> field = make_demo_scalar_field('gaussian', nt=50, nx=32)
>>> field.shape
(50, 32, 16, 16)
>>> field.axis0_domain
'time'

>>> # White noise for PSD testing
>>> noise_field = make_demo_scalar_field('noise', seed=123)

gwexpy.fields.make_propagating_gaussian(**kw) → ScalarField#: Generate a propagating Gaussian demo field. See make_demo_scalar_field.

gwexpy.fields.make_sinusoidal_wave(**kw) → ScalarField#: Generate a sinusoidal wave demo field. See make_demo_scalar_field.

gwexpy.fields.make_standing_wave(**kw) → ScalarField#: Generate a standing wave demo field. See make_demo_scalar_field.

gwexpy.fields.compute_psd(field: ScalarField, point_or_region: tuple[Quantity, Quantity, Quantity] | list[tuple[Quantity, Quantity, Quantity]] | dict[str, Any], *, fftlength: float | None = None, overlap: float | None = None, nfft: int | None = None, noverlap: int | None = None, window: str = 'hann', detrend: str | bool = 'constant', scaling: Literal['density', 'spectrum'] = 'density', average: Literal['mean', 'median'] = 'mean', return_onesided: bool = True, **kwargs) → FrequencySeries | FrequencySeriesList#

Compute power spectral density using Welch's method.

Extracts time series from one or more spatial points/regions and estimates their PSD using scipy.signal.welch.

パラメータ:

field (ScalarField) -- Input 4D field with axis0_domain='time'.
point_or_region (tuple, list of tuples, or dict) --
Spatial location(s) to extract:
- Single point: (x, y, z) tuple of Quantities
- Multiple points: list of (x, y, z) tuples
- Region dict: {'x': slice or value, 'y': ..., 'z': ...} If region, averages over all points in the region.
fftlength (float, optional) -- Segment length in seconds. Default is min(256, len(time_axis)) samples.
overlap (float, optional) -- Overlap in seconds. Default is fftlength / 2.
nfft (int, optional) -- FFT segment length in samples. Alternative to fftlength.
noverlap (int, optional) -- Overlap in samples. Alternative to overlap.
window (str) -- Window function name. Default is 'hann'.
detrend (str or bool) -- Detrending method: 'constant', 'linear', or False. Default 'constant'.
scaling ({'density', 'spectrum'}) -- 'density' for PSD (V²/Hz), 'spectrum' for power spectrum (V²). Default is 'density'.
average ({'mean', 'median'}) -- Averaging method for segments. Default is 'mean'.
return_onesided (bool) -- If True, return one-sided spectrum for real data. Default True.
**kwargs -- Additional keyword arguments. Passing the removed nperseg or noverlap parameters will raise TypeError.

戻り値:

Single point: FrequencySeries with PSD values
Multiple points: FrequencySeriesList

戻り値の型:

FrequencySeries or FrequencySeriesList

例外:

ValueError -- If time axis is not regularly spaced or axis0_domain != 'time'.

サンプル

>>> from astropy import units as u
>>> psd = compute_psd(field, (1.0*u.m, 2.0*u.m, 0.0*u.m))
>>> psd.frequencies  # Frequency axis with units

>>> # Multiple points
>>> points = [(0*u.m, 0*u.m, 0*u.m), (1*u.m, 0*u.m, 0*u.m)]
>>> psd_list = compute_psd(field, points)

gwexpy.fields.freq_space_map(field: ScalarField, axis: str, at: dict[str, Quantity] | None = None, *, method: Literal['welch', 'fft'] = 'welch', fftlength: float | None = None, overlap: float | None = None, nfft: int | None = None, noverlap: int | None = None, window: str = 'hann', detrend: str | bool = 'constant', scaling: Literal['density', 'spectrum'] = 'density', **kwargs) → ScalarField#

Compute frequency-space map along a spatial axis.

Scans along the specified spatial axis, computing PSD at each position while fixing other spatial coordinates. Produces a 2D map with frequency on one axis and spatial coordinate on the other.

パラメータ:

field (ScalarField) -- Input 4D field with axis0_domain='time'.
axis (str) -- Spatial axis to scan along ('x', 'y', or 'z').
at (dict, optional) -- Fixed values for the other two spatial axes. Example: {'y': 0*u.m, 'z': 0*u.m} when axis='x'.
method ({'welch', 'fft'}) -- PSD estimation method. Default is 'welch'.
fftlength (float, optional) -- Segment length in seconds. Default is min(256, nt) samples.
overlap (float, optional) -- Overlap in seconds. Default is fftlength / 2.
nfft (int, optional) -- FFT segment length in samples. Alternative to fftlength.
noverlap (int, optional) -- Overlap in samples. Alternative to overlap.
window (str) -- Window function. Default is 'hann'.
detrend (str or bool) -- Detrending method. Default is 'constant'.
scaling ({'density', 'spectrum'}) -- PSD scaling. Default is 'density'.
**kwargs -- Additional keyword arguments. Passing the removed nperseg or noverlap parameters will raise TypeError.

戻り値:

2D frequency-space map stored as ScalarField with: - axis0: frequency (with axis0_domain='frequency') - axis1: spatial coordinate - axis2, axis3: length-1 dummy axes

戻り値の型:

ScalarField

サンプル

>>> from astropy import units as u
>>> fsmap = freq_space_map(field, 'x', at={'y': 0*u.m, 'z': 0*u.m})
>>> fsmap.shape  # (n_freq, n_x, 1, 1)

参考

compute_psd: Single-point PSD computation.
compute_freq_space: Alias for this function.

gwexpy.fields.compute_freq_space(field: ScalarField, axis: str, at: dict[str, Quantity] | None = None, *, method: Literal['welch', 'fft'] = 'welch', fftlength: float | None = None, overlap: float | None = None, nfft: int | None = None, noverlap: int | None = None, window: str = 'hann', detrend: str | bool = 'constant', scaling: Literal['density', 'spectrum'] = 'density', **kwargs) → ScalarField#

Compute frequency-space map along a spatial axis.

Scans along the specified spatial axis, computing PSD at each position while fixing other spatial coordinates. Produces a 2D map with frequency on one axis and spatial coordinate on the other.

パラメータ:

field (ScalarField) -- Input 4D field with axis0_domain='time'.
axis (str) -- Spatial axis to scan along ('x', 'y', or 'z').
at (dict, optional) -- Fixed values for the other two spatial axes. Example: {'y': 0*u.m, 'z': 0*u.m} when axis='x'.
method ({'welch', 'fft'}) -- PSD estimation method. Default is 'welch'.
fftlength (float, optional) -- Segment length in seconds. Default is min(256, nt) samples.
overlap (float, optional) -- Overlap in seconds. Default is fftlength / 2.
nfft (int, optional) -- FFT segment length in samples. Alternative to fftlength.
noverlap (int, optional) -- Overlap in samples. Alternative to overlap.
window (str) -- Window function. Default is 'hann'.
detrend (str or bool) -- Detrending method. Default is 'constant'.
scaling ({'density', 'spectrum'}) -- PSD scaling. Default is 'density'.
**kwargs -- Additional keyword arguments. Passing the removed nperseg or noverlap parameters will raise TypeError.

戻り値:

2D frequency-space map stored as ScalarField with: - axis0: frequency (with axis0_domain='frequency') - axis1: spatial coordinate - axis2, axis3: length-1 dummy axes

戻り値の型:

ScalarField

サンプル

>>> from astropy import units as u
>>> fsmap = freq_space_map(field, 'x', at={'y': 0*u.m, 'z': 0*u.m})
>>> fsmap.shape  # (n_freq, n_x, 1, 1)

参考

compute_psd: Single-point PSD computation.
compute_freq_space: Alias for this function.

gwexpy.fields.compute_xcorr(field: ScalarField, point_a: tuple[Quantity, Quantity, Quantity], point_b: tuple[Quantity, Quantity, Quantity], *, max_lag: int | Quantity | None = None, mode: Literal['full', 'same', 'valid'] = 'full', normalize: bool = True, detrend: bool = True, window: str | None = None) → TimeSeries#

Compute cross-correlation between two spatial points.

Calculates the normalized (or unnormalized) cross-correlation function between time series extracted at two spatial locations.

パラメータ:

field (ScalarField) -- Input 4D field with axis0_domain='time'.
point_a (tuple of Quantity) -- Spatial coordinates (x, y, z) for the two points.
point_b (tuple of Quantity) -- Spatial coordinates (x, y, z) for the two points.
max_lag (int or Quantity, optional) -- Maximum lag to compute. If Quantity, converted to samples. If None, uses all available lags.
mode ({'full', 'same', 'valid'}) -- Correlation mode (see numpy.correlate). Default is 'full'.
normalize (bool) -- If True, normalize to [-1, 1] range. Default True.
detrend (bool) -- If True, remove mean before correlation. Default True.
window (str, optional) -- Window function to apply before correlation. Default None.

戻り値:

Cross-correlation function with lag axis in time units. Positive lag means point_b leads point_a.

戻り値の型:

TimeSeries

サンプル

>>> from astropy import units as u
>>> xcorr = compute_xcorr(field, (0*u.m, 0*u.m, 0*u.m), (1*u.m, 0*u.m, 0*u.m))
>>> xcorr.times  # Lag axis
>>> xcorr.value  # Correlation values

メモ

The correlation is computed as correlate(a, b, mode), where positive values in the output correspond to b leading a.

gwexpy.fields.time_delay_map(field: ScalarField, ref_point: tuple[Quantity, Quantity, Quantity], plane: str = 'xy', at: dict[str, Quantity] | None = None, *, max_lag: int | Quantity | None = None, stride: int | Quantity = 1, roi: dict[str, slice] | None = None, normalize: bool = True, detrend: bool = True) → ScalarField#

Compute time delay map from a reference point to a 2D slice.

For each point in the specified plane, computes cross-correlation with the reference point and extracts the lag at maximum correlation.

パラメータ:

field (ScalarField) -- Input 4D field with axis0_domain='time'.
ref_point (tuple of Quantity) -- Reference point coordinates (x, y, z).
plane (str) -- 2D plane to map: 'xy', 'xz', or 'yz'. Default 'xy'.
at (dict, optional) -- Fixed value for the axis not in the plane. Example: {'z': 0*u.m} when plane='xy'.
max_lag (int or Quantity, optional) -- Maximum lag to search for peak. Default uses all lags.
stride (int or Quantity, optional) -- Spatial subsample stride. If int, treated as grid point stride. If Quantity, treated as physical distance stride and converted to grid points based on spatial resolution. Default 1.
roi (dict, optional) -- Region of interest as dict of slices. Example: {'x': slice(10, 50), 'y': slice(20, 80)}
normalize (bool) -- Normalize correlation. Default True.
detrend (bool) -- Detrend before correlation. Default True.

戻り値:

Time delay map as ScalarField slice with delay values in time units. Shape matches the input plane dimensions (with stride applied).

戻り値の型:

ScalarField

サンプル

>>> from astropy import units as u
>>> delay_map = time_delay_map(
...     field,
...     ref_point=(0*u.m, 0*u.m, 0*u.m),
...     plane='xy',
...     at={'z': 0*u.m},
...     stride=0.05*u.m  # spatial stride in meters
... )

メモ

Positive delay means the point leads the reference.

gwexpy.fields.coherence_map(field: ScalarField, ref_point: tuple[Quantity, Quantity, Quantity], *, plane: str = 'xy', at: dict[str, Quantity] | None = None, band: tuple[Quantity, Quantity] | None = None, fftlength: float | None = None, overlap: float | None = None, nfft: int | None = None, noverlap: int | None = None, window: str = 'hann', stride: int | Quantity = 1, **kwargs) → ScalarField | FieldDict#

Compute magnitude-squared coherence map from a reference point.

Calculates coherence between the reference time series and all points in the specified 2D slice.

パラメータ:

field (ScalarField) -- Input 4D field with axis0_domain='time'.
ref_point (tuple of Quantity) -- Reference point coordinates (x, y, z).
plane (str) -- 2D plane to map: 'xy', 'xz', or 'yz'. Default 'xy'.
at (dict, optional) -- Fixed value for the axis not in the plane.
band (tuple of Quantity, optional) -- Frequency band (fmin, fmax) to average coherence over. If None, returns coherence at all frequencies.
fftlength (float, optional) -- Segment length in seconds. Default min(256, nt) samples. Cannot be used with nfft.
overlap (float, optional) -- Overlap in seconds. Default fftlength / 2. Cannot be used with noverlap.
nfft (int, optional) -- Number of samples per segment (alternative to fftlength). Cannot be used with fftlength.
noverlap (int, optional) -- Number of overlapping samples (alternative to overlap). Cannot be used with overlap.
window (str) -- Window function. Default 'hann'.
stride (int or Quantity, optional) -- Spatial subsample stride. If int, treated as grid point stride. If Quantity, treated as physical distance stride and converted to grid points based on spatial resolution. Default 1.
**kwargs -- Additional keyword arguments.

戻り値:

If band is specified: ScalarField with scalar coherence values (0-1).
If band is None: FieldDict with keys as frequency indices, or a single ScalarField with frequency as axis0.

戻り値の型:

ScalarField or FieldDict

サンプル

>>> from astropy import units as u
>>> # Compute coherence map with time-based FFT parameters
>>> coh_map = coherence_map(
...     field,
...     ref_point=(0*u.m, 0*u.m, 0*u.m),
...     plane='xy',
...     at={'z': 0*u.m},
...     band=(10*u.Hz, 100*u.Hz),
...     fftlength=1.0,    # 1.0 seconds
...     overlap=0.5,      # 0.5 seconds
...     window='hann'
... )

>>> # Or with sample-based FFT parameters
>>> coh_map = coherence_map(
...     field,
...     ref_point=(0*u.m, 0*u.m, 0*u.m),
...     nfft=1024,        # samples
...     noverlap=512,     # samples
...     stride=0.1*u.m    # spatial stride in meters
... )

class gwexpy.fields.FieldList(items=None, validate=False)#

ベースクラス: _FieldCollectionArithmetic, list

A list of ScalarField objects with batch operations.

FieldList provides a container for multiple fields, supporting arithmetic and batch processing across the list.

パラメータ:

items (list, optional) -- A list of ScalarField objects.
validate (bool, optional) -- If True, ensures that all fields have matching axes.

サンプル

>>> import numpy as np
>>> from gwexpy.fields import ScalarField, FieldList
>>> sf = ScalarField(np.ones((2, 2, 2, 2)))
>>> fl = FieldList([sf])
>>> fl
[<ScalarField(2, 2, 2, 2)@time, 1.0>]

fft_time_all(**kwargs)#: Apply fft_time to all fields, returning FieldList.

ifft_time_all(**kwargs)#: Apply ifft_time to all fields, returning FieldList.

fft_space_all(axes=None, **kwargs)#: Apply fft_space to all fields, returning FieldList.

ifft_space_all(axes=None, **kwargs)#: Apply ifft_space to all fields, returning FieldList.

resample_all(rate, **kwargs)#: Apply resample to all fields, returning FieldList.

filter_all(*args, **kwargs)#: Apply filter to all fields, returning FieldList.

sel_all(**kwargs)#: Apply sel to all fields, returning FieldList.

isel_all(**kwargs)#: Apply isel to all fields, returning FieldList.

class gwexpy.fields.FieldDict(items=None, validate=False)#

ベースクラス: _FieldCollectionArithmetic, dict

A dictionary of ScalarField objects with batch operations.

FieldDict provides a labeled container for multiple fields, supporting arithmetic and batch processing.

パラメータ:

items (dict, optional) -- A dictionary mapping labels to ScalarField objects.
validate (bool, optional) -- If True, ensures that all fields have matching axes.

サンプル

>>> import numpy as np
>>> from gwexpy.fields import ScalarField, FieldDict
>>> f = ScalarField(np.ones((2, 2, 2, 2)))
>>> fd = FieldDict({'E': f})
>>> fd
{'E': <ScalarField(2, 2, 2, 2)@time, 1.0>}

copy() → FieldDict#: Return a copy of this FieldDict.

fft_time_all(**kwargs)#: Apply fft_time to all fields, returning FieldDict.

ifft_time_all(**kwargs)#: Apply ifft_time to all fields, returning FieldDict.

fft_space_all(axes=None, **kwargs)#: Apply fft_space to all fields, returning FieldDict.

ifft_space_all(axes=None, **kwargs)#: Apply ifft_space to all fields, returning FieldDict.

resample_all(rate, **kwargs)#: Apply resample to all fields, returning FieldDict.

filter_all(*args, **kwargs)#: Apply filter to all fields, returning FieldDict.

sel_all(**kwargs)#: Apply sel to all fields, returning FieldDict.

isel_all(**kwargs)#: Apply isel to all fields, returning FieldDict.

class gwexpy.fields.VectorField(components=None, basis: Literal['cartesian', 'custom'] = 'cartesian', validate: bool = True)#

ベースクラス: FieldDict

A vector-valued field composed of ScalarField components.

VectorField maintains a collection of ScalarField objects representing different components (e.g., 'x', 'y', 'z') of a vector field. It ensures that all components share the same spatial and temporal grid.

パラメータ:

components (dict[str, ScalarField], optional) -- Mapping of component names to field objects.
basis ({'cartesian', 'custom'}, optional) -- The coordinate basis. Default is 'cartesian'.
validate (bool, optional) -- If True (default), validates that all components have consistent axes and units.

メモ

Vector-specific operations like norm(), dot(), and cross() are supported, returning either a ScalarField or a new VectorField.

サンプル

>>> import numpy as np
>>> from gwexpy.fields import VectorField
>>> v = VectorField(np.ones((2, 2, 2, 2, 3)))
>>> v
<VectorField(2, 2, 2, 2, 3)@time, 1.0>

copy() → VectorField#: Return a copy of this VectorField.

to_array() → ndarray#

Convert components to a single 5D ndarray.

The last axis (axis 4) corresponds to the vector components.

戻り値:: A 5D array of shape (axis0, axis1, axis2, axis3, n_components).
戻り値の型:: numpy.ndarray

norm() → ScalarField#

Compute the L2 norm of the vector field.

戻り値:: A scalar field representing the magnitude $\sqrt{\sum |E_i|^2}$.
戻り値の型:: ScalarField

dot(other: VectorField) → ScalarField#

Compute the scalar (dot) product with another VectorField.

パラメータ:: other (VectorField) -- The other vector field to dot with. Must have identical components.
戻り値:: The resulting dot product field.
戻り値の型:: ScalarField

cross(other: VectorField) → VectorField#

Compute the cross product with another VectorField (3-components).

パラメータ:: other (VectorField) -- The other vector field. Both must have exactly 'x', 'y', 'z' components.
戻り値:: The resulting vector field.
戻り値の型:: VectorField

project(direction: VectorField) → ScalarField#

Project the vector field onto a given direction.

Result is (self . direction) / norm(direction).

パラメータ:: direction (VectorField) -- The direction to project onto.
戻り値:: The projected scalar field.
戻り値の型:: ScalarField

plot_magnitude(x=None, y=None, **kwargs)#

Plot the magnitude (norm) of the vector field.

パラメータ:

x (str, optional) -- X-axis name.
y (str, optional) -- Y-axis name.
**kwargs -- Fixed coordinates and arguments passed to ScalarField.plot.

quiver(x=None, y=None, **kwargs)#

Plot the vector field using arrows (quiver).

パラメータ:

x (str, optional) -- X-axis name.
y (str, optional) -- Y-axis name.
**kwargs -- Fixed coordinates and arguments passed to FieldPlot.add_vector.

streamline(x=None, y=None, **kwargs)#

Plot the vector field using streamlines.

パラメータ:

x (str, optional) -- X-axis name.
y (str, optional) -- Y-axis name.
**kwargs -- Fixed coordinates and arguments passed to FieldPlot.add_vector.

plot(x=None, y=None, **kwargs)#

Plot magnitude and overlay quiver.

This is a convenience method combining plot_magnitude and quiver.

class gwexpy.fields.TensorField(components: dict[tuple[int, ...], ScalarField] | ndarray | None = None, rank: int | None = None, validate: bool = True)#

ベースクラス: FieldDict

A tensor-valued field as a collection of ScalarField components.

TensorField represents a higher-order (typically rank-2) field. Each component is indexed by a tuple of integers (e.g., (0, 0) for $T_{00}$). It supports standard linear algebra operations carried out independently at each grid point.

パラメータ:

components (dict[tuple, ScalarField] or numpy.ndarray, optional) -- Mapping of index tuples to ScalarField objects, or a 6-D numpy array of shape (n0, n1, n2, n3, i, j) representing a rank-2 tensor field. When a numpy array is supplied the last two dimensions are the tensor indices and each (n0, n1, n2, n3) slice becomes a ScalarField with default arange coordinate axes. Axis metadata (units, custom coordinates) must be assigned after construction when using this path.
rank (int, optional) -- The tensor rank. If None, it is inferred from keys.
validate (bool, optional) -- If True (default), validates component consistency (shape, units, axes).

メモ

Rank-2 tensor operations like @ (matrix multiplication) and trace() are implemented.

サンプル

>>> import numpy as np
>>> from gwexpy.fields import TensorField
>>> t = TensorField(np.ones((2, 2, 2, 2, 3, 3)))
>>> t
<TensorField(2, 2, 2, 2, 3, 3)@time, 1.0>
>>> t.trace()
<ScalarField(...), axis0_domain='time', ...>

copy() → TensorField#: Return a copy of this TensorField.

trace() → ScalarField#

Compute the trace of a rank-2 tensor.

戻り値:: The sum of diagonal components $\sum T_{ii}$.
戻り値の型:: ScalarField
例外:: ValueError -- If the tensor rank is not 2.

to_array(order: Literal['first', 'last'] = 'last') → ndarray#

Convert components into a single NumPy array.

パラメータ:: order ({'first', 'last'}, optional) -- If 'first' (default for VectorField), the tensor dimensions are at the beginning. If 'last' (preferred for linalg), they are at the end.
戻り値:: Shape (dim1, dim2, N0, N1, N2, N3) if order='first'. Shape (N0, N1, N2, N3, dim1, dim2) if order='last'.
戻り値の型:: ndarray

det() → ScalarField#

Compute the determinant of a rank-2 tensor.

戻り値:: The determinant field.
戻り値の型:: ScalarField

symmetrize() → TensorField#

Symmetrize a rank-2 tensor: $S_{ij} = (T_{ij} + T_{ji}) / 2$.

戻り値:: The symmetrized tensor.
戻り値の型:: TensorField
例外:: ValueError -- If the tensor rank is not 2.

plot_components(x=None, y=None, **kwargs)#

Plot the tensor components in a grid layout.

パラメータ:

x (str, optional) -- X-axis name.
y (str, optional) -- Y-axis name.
**kwargs -- Fixed coordinates and arguments passed to FieldPlot.add_scalar.