solprop.stats.spec#
The request a run records statistics by: StatsSpec and its apertures.
StatsSpec: the names, the between-planes subset, the energy windows and the far-field regions and apertures, checked against the catalogue on construction.ApertureSet,ApertureWeighting,check_aperture_choices()and the limitsMAX_APERTURESandMAX_REGIONS(SEP 23).far_field_tables(): the far-field statistics’ tables of a spec on Cartesian columns, which every backend and the saved-plane statistics share.
Module Attributes
How an aperture's profile weights the collected spectrum (SEP 23 section 4.5). |
|
The most apertures one |
|
The most rows |
Functions
|
Refuse, by name, an aperture profile or weighting that does not exist. |
|
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:
objectApertures in a far-field or Fourier plane behind a free-space run.
The tables of
aperture_spectrumandaperture_on_axis_spectrum(SEP 23): each aperture collects the light whose paraxial imagex = z c kappa / omegafalls 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
win m fortanhandrcos, ordersn >= 2forsupergauss, zero for ahardrow beside others, shape(n_apertures,);Nonewhen every row ishard, and only then. An ellipse’s edge width is in its circular frame:w a/sqrt(a b)along x andw 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 ishard.- weighting{‘amplitude’, ‘quadrature’}
amplitude(the default) models a mask of amplitude transmissionWand weights the collected spectrum byW**2;quadratureuses a smooth profile once, at the corrected diameter, as a quadrature weight for a hard hole. Quadrature is refused withsupergauss.- 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_geandhalf_plane_y_lt.None(the default) is a circle on every row, and all circles are stored asNone. 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;
profileis then left at its default, and rows that all agree are stored as thatprofile.- 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;Nonewhen no row needs them, and only then.
- Raises:
- OutputError
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 ahardset or row, or out of its range (withDa circle’s diameter,sqrt(D_x D_y)of an ellipse and the smaller of a rectangle’s widths:0 < w <= D/4forrcosand fortanhunder amplitude weighting,0 < w <= D/8fortanhunder quadrature weighting,D/10on a rectangle;w > 0on a half-plane;n >= 2forsupergauss); quadrature weighting or a half-plane is asked ofsupergauss;profileis 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
tanhunder amplitude weighting withr/w < 4(w > D/8): the profile slopes at its centre, so a bright beam there is collected with a lattice error near1e-5. The set is built as asked;rcosis 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')
- property row_profiles: tuple[Literal['hard', 'tanh', 'rcos', 'supergauss'], ...][source]#
Every row’s edge profile.
One of
solprop.spatial.APERTURE_PROFILESper 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_SHAPESper 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.
- 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
ApertureSetcarries.
- solprop.stats.spec.MAX_REGIONS = 16#
The most rows
StatsSpec.spectral_regionscarries.
- class solprop.stats.spec.StatsSpec(names=(), energy_windows=<factory>, periodic=(), period=1, apertures=None, spectral_regions=<factory>)[source]#
Bases:
objectWhich 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) becauseenergy_windowsis an array.- Attributes:
- namestuple
Statistics to evaluate at every saved plane, in the order they are evaluated. Every name must be in
CATALOGUEand must be implemented.- energy_windowsnumpy.ndarray
Spectral windows, shape
(n_windows, 2), rad/s, each row(lo, hi)withlo < hi. Infinite edges are allowed, so that a pair of windows can tile the whole axis. Required byenergy_windowandpeak_power_window.- periodictuple
The subset of
namesa backend also evaluates between planes, for step-level diagnostics. Must be a subset ofnames, and every entry must carrybetween_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_spectrumandaperture_on_axis_spectrum(SEP 23).Noneby 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 mostMAX_REGIONSrows, infinite edges allowed. Required byregion_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
periodicis not a subset ofnamesor names a statistic no backend evaluates between planes; ifperiodis 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.
- 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
ApertureSetmakes 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:
- OutputError
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 correctedD_q/2of 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 ofsolprop.spatial.aperture_scale(), with the columns’ axes, weights and on-axis vector and the spec’s regions. On a line every column haskappa_y = 0and 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 throughsolprop.translate.spatial.aperture_tables()at construction andsolprop.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_yhas 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:
- OutputError
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 whosekappa_yinterval excludes zero, which would select nothing.