solprop.stats.spec#

The request a run records statistics by: StatsSpec and its apertures.

Module Attributes

ApertureWeighting

How an aperture's profile weights the collected spectrum (SEP 23 section 4.5).

MAX_APERTURES

The most apertures one ApertureSet carries.

MAX_REGIONS

The most rows StatsSpec.spectral_regions carries.

Functions

check_aperture_choices(profile, weighting)

Refuse, by name, an aperture profile or weighting that does not exist.

far_field_tables(spec, omega, *, k_x, k_y, ...)

Form the far-field statistics' tables of a spec on Cartesian columns (SEP 23 §6).

class solprop.stats.spec.ApertureSet(centres, diameters, distances, edges=None, profile='hard', weighting='amplitude', labels=None, shapes=None, profiles=None, extents=None)[source]#

Bases: object

Apertures in a far-field or Fourier plane behind a free-space run.

The tables of aperture_spectrum and aperture_on_axis_spectrum (SEP 23): each aperture collects the light whose paraxial image x = z c kappa / omega falls inside it, a chromatic weight on the stored transverse spectrum. Every position is physical: a beam travelling towards positive x lands at positive x. Circles by default; shapes asks for an ellipse, a rectangle or a half-plane on any row. Equality is by identity; the arrays are owned read-only copies.

Attributes:
centresnumpy.ndarray

Aperture centres (x, y) in the mask plane, in m, shape (n_apertures, 2). A half-plane has an edge rather than a centre: its row holds the edge’s position on the axis it names and zero on the other.

diametersnumpy.ndarray

Diameters in m, shape (n_apertures,): finite and positive on a circle’s row, zero on any other. On a line a circle is a slit of this full width along x.

distancesnumpy.ndarray

Distance from the exit face to the mask plane, or a lens’s focal length for a Fourier plane, in m, finite and positive, shape (n_apertures,).

edgesnumpy.ndarray or None

Edge widths w in m for tanh and rcos, orders n >= 2 for supergauss, zero for a hard row beside others, shape (n_apertures,); None when every row is hard, and only then. An ellipse’s edge width is in its circular frame: w a/sqrt(a b) along x and w b/sqrt(a b) along y, in m.

profile{‘hard’, ‘tanh’, ‘rcos’, ‘supergauss’}

The edge profile the set shares (solprop.spatial.aperture_profile()). The default is hard.

weighting{‘amplitude’, ‘quadrature’}

amplitude (the default) models a mask of amplitude transmission W and weights the collected spectrum by W**2; quadrature uses a smooth profile once, at the corrected diameter, as a quadrature weight for a hard hole. Quadrature is refused with supergauss.

labelstuple of str

One unique non-empty label per aperture, recorded with the run’s configuration; None (the default) labels them "0", "1", …

shapestuple of str or None

Each row’s outline, one of solprop.spatial.APERTURE_SHAPES: circle, ellipse, rectangle, or a half-plane named for the side it keeps, half_plane_x_ge (x >= X), half_plane_x_lt (x < X), half_plane_y_ge and half_plane_y_lt. None (the default) is a circle on every row, and all circles are stored as None. A set of unset shapes, profiles and extents records and hashes as it did before they existed.

profilestuple of str or None

Each row’s edge profile, for a set that mixes them; profile is then left at its default, and rows that all agree are stored as that profile.

extentsnumpy.ndarray or None

Full widths (D_x, D_y) in m, shape (n_apertures, 2): finite and positive on the row of an ellipse or a rectangle, zero on any other; None when no row needs them, and only then.

Raises:
ProcessingError

If there are no apertures or more than MAX_APERTURES; an array is not finite or not of its stated shape; a diameter, an extent or a distance breaks its rule above; a half-plane’s centre is off the axis it names; an edge is missing, given for a hard set or row, or out of its range (with D a circle’s diameter, sqrt(D_x D_y) of an ellipse and the smaller of a rectangle’s widths: 0 < w <= D/4 for rcos and for tanh under amplitude weighting, 0 < w <= D/8 for tanh under quadrature weighting, D/10 on a rectangle; w > 0 on a half-plane; n >= 2 for supergauss); quadrature weighting or a half-plane is asked of supergauss; profile is given beside profiles; an aperture reaches the paraxial disc’s edge, |X| + D/2 (+ w for rcos) >= z (a half-plane’s edge must lie inside it); or the labels are not unique non-empty strings, one per aperture.

Warns:
solprop.exceptions.ApertureEdgeWarning

Once per set, for tanh under amplitude weighting with r/w < 4 (w > D/8): the profile slopes at its centre, so a bright beam there is collected with a lattice error near 1e-5. The set is built as asked; rcos is the recommended smooth profile.

Examples

>>> from solprop.stats import ApertureSet
>>> holes = ApertureSet(
...     centres=[[4e-3, 4e-3], [-4e-3, -4e-3]],
...     diameters=[1.5e-3, 1.5e-3],
...     distances=[0.25, 0.25],
...     edges=[40e-6, 40e-6],
...     profile="tanh",
...     weighting="quadrature",
...     labels=("probe", "signal"),
... )
>>> holes.n_apertures, holes.labels
(2, ('probe', 'signal'))

A knife edge at a fixed position in the plane, beside an apodised hole:

>>> mixed = ApertureSet(
...     centres=[[2e-3, 0.0], [-4e-3, 0.0]],
...     diameters=[0.0, 1.5e-3],
...     distances=[0.25, 0.25],
...     edges=[0.0, 40e-6],
...     shapes=("half_plane_x_ge", "circle"),
...     profiles=("hard", "rcos"),
... )
>>> mixed.row_shapes
('half_plane_x_ge', 'circle')
centres: Sequence[Sequence[float]] | ndarray#
diameters: Sequence[float] | ndarray#
distances: Sequence[float] | ndarray#
edges: Sequence[float] | ndarray | None = None#
extents: Sequence[Sequence[float]] | ndarray | None = None#
labels: tuple[str, ...] | None = None#
property n_apertures: int[source]#

How many apertures the set holds.

profile: Literal['hard', 'tanh', 'rcos', 'supergauss'] = 'hard'#
profiles: tuple[Literal['hard', 'tanh', 'rcos', 'supergauss'], ...] | None = None#
property row_profiles: tuple[Literal['hard', 'tanh', 'rcos', 'supergauss'], ...][source]#

Every row’s edge profile.

One of solprop.spatial.APERTURE_PROFILES per aperture.

property row_shapes: tuple[Literal['circle', 'ellipse', 'rectangle', 'half_plane_x_ge', 'half_plane_x_lt', 'half_plane_y_ge', 'half_plane_y_lt'], ...][source]#

Every row’s outline.

One of solprop.spatial.APERTURE_SHAPES per aperture.

same_as(other)[source]#

Return whether another set describes the same apertures, entry for entry.

Parameters:
otherApertureSet or None

The set to compare.

Returns:
bool

True when every table, each row’s shape and profile, the weighting and the labels agree exactly: a structural comparison of two requests.

shapes: tuple[Literal['circle', 'ellipse', 'rectangle', 'half_plane_x_ge', 'half_plane_x_lt', 'half_plane_y_ge', 'half_plane_y_lt'], ...] | None = None#
weighting: Literal['amplitude', 'quadrature'] = 'amplitude'#
solprop.stats.spec.ApertureWeighting#

How an aperture’s profile weights the collected spectrum (SEP 23 section 4.5).

alias of Literal[‘amplitude’, ‘quadrature’]

solprop.stats.spec.MAX_APERTURES = 16#

The most apertures one ApertureSet carries.

solprop.stats.spec.MAX_REGIONS = 16#

The most rows StatsSpec.spectral_regions carries.

class solprop.stats.spec.StatsSpec(names=(), energy_windows=<factory>, periodic=(), period=1, apertures=None, spectral_regions=<factory>)[source]#

Bases: object

Which statistics a run asks for, and the windows and period they need.

This is the object of the kernel contract §8: the translation layer carries it into a backend, the driver hands it to collect(), and both read the same names. Equality is by identity (eq=False) because energy_windows is an array.

Attributes:
namestuple

Statistics to evaluate at every saved plane, in the order they are evaluated. Every name must be in CATALOGUE and must be implemented.

energy_windowsnumpy.ndarray

Spectral windows, shape (n_windows, 2), rad/s, each row (lo, hi) with lo < hi. Infinite edges are allowed, so that a pair of windows can tile the whole axis. Required by energy_window and peak_power_window.

periodictuple

The subset of names a backend also evaluates between planes, for step-level diagnostics. Must be a subset of names, and every entry must carry between_planes: a statistic whose cost is only bearable once per plane is refused here rather than made the run’s per-step cost.

periodint

How many accepted steps apart the periodic subset is evaluated, at least 1.

aperturesApertureSet or None

Far-field apertures, required by aperture_spectrum and aperture_on_axis_spectrum (SEP 23). None by default, and then left out of the run’s configuration record, so every earlier record keeps its hash.

spectral_regionsnumpy.ndarray

Boxes of physical transverse wavevector in rad/m, shape (n_regions, 4), rows (kx_lo, kx_hi, ky_lo, ky_hi), each a half-open box [lo, hi) on both axes, at most MAX_REGIONS rows, infinite edges allowed. Required by region_spectrum. Empty by default, and then left out of the configuration record.

Raises:
ProcessingError

If a name is unknown, reserved or repeated; if a window or a region is malformed; if periodic is not a subset of names or names a statistic no backend evaluates between planes; if period is below 1; or if a name needs a far-field table the spec does not carry.

Examples

>>> import numpy as np
>>> from solprop.stats import StatsSpec
>>> spec = StatsSpec(
...     names=("energy", "energy_window"),
...     energy_windows=np.array([[2.0e15, 3.0e15]]),
... )
>>> spec.n_windows
1
apertures: ApertureSet | None = None#
energy_windows: Float[ndarray, 'n_windows 2']#
property n_apertures: int[source]#

How many far-field apertures the spec carries.

The apertures of apertures, or zero without them.

property n_regions: int[source]#

How many regions of transverse wavevector the spec carries.

The rows of spectral_regions.

property n_windows: int[source]#

How many spectral windows the spec carries.

names: tuple[str, ...] = ()#
period: int = 1#
periodic: tuple[str, ...] = ()#
spectral_regions: Float[ndarray, 'n_regions 4']#
solprop.stats.spec.check_aperture_choices(profile, weighting)[source]#

Refuse, by name, an aperture profile or weighting that does not exist.

The check ApertureSet makes of its two choices. It takes any object, because a caller outside the test session’s runtime type checker can pass anything.

Parameters:
profileobject

The edge profile asked for.

weightingobject

The weighting asked for.

Raises:
ProcessingError

If either is not one of its choices.

Examples

>>> from solprop.stats import check_aperture_choices
>>> check_aperture_choices("tanh", "quadrature") is None
True
solprop.stats.spec.far_field_tables(spec, omega, *, k_x, k_y, weights, on_axis)[source]#

Form the far-field statistics’ tables of a spec on Cartesian columns (SEP 23 §6).

The per-aperture constants – each row’s outline of solprop.spatial.aperture_outline(), whose half-width under quadrature weighting is the corrected D_q/2 of a circle or an ellipse (unchanged on a line, whose edges are straight, and on the straight edges of a rectangle or a half-plane) – and the scale table of solprop.spatial.aperture_scale(), with the columns’ axes, weights and on-axis vector and the spec’s regions. On a line every column has kappa_y = 0 and the light is uniform in y, so a rectangle has no y edges to meet: it is a slit of its x width, the row a circle of that diameter forms. Every backend reaches this through solprop.translate.spatial.aperture_tables() at construction and solprop.stats.collect() calls it for a saved plane, so all of them use the same scale to the bit.

Parameters:
specsolprop.stats.StatsSpec

The request and its far-field tables.

omeganumpy.ndarray

Physical frequency axis in rad/s, shape (n_omega,).

k_x, k_ynumpy.ndarray

The stored transverse wavevector axes in rad/m, in FFT order; k_y has one entry, zero, on a line uniform in y.

weightsnumpy.ndarray

Parseval weights of the stored columns, shape (n_x*n_y,).

on_axisnumpy.ndarray

On-axis reconstruction weights of the columns, complex, shape (n_x*n_y,).

Returns:
solprop.spatial.ApertureTables

The tables.

Raises:
ProcessingError

On a line, for an aperture whose centre is off y = 0, a half-plane bounded in y or an ellipse, which have no meaning uniform in y, or a region whose kappa_y interval excludes zero, which would select nothing.