solprop.translate.modal_tables#
Flatten a general guide’s sampled tables into the record a run’s seam carries.
The provider sampling – tracking, interpolation and validation of the dense tables
– lives in solprop.modes.tables. This module takes one of those tables and
builds ModalTransformTables, the flat transform.modal_tables leaf of a
PropagationProblem: the dense E/H reference, the synthesis S and projection
Q maps tabulated on the run’s coarse grid (modal_transform_tables()), with
the per-sample builders projection_map() and coordinate_dual() that the
moving-guide record of solprop.translate.modal_path reuses. It also projects a
declared transverse field onto a table’s channels (project_transverse_field(),
returning a ProjectedLaunch).
Functions
|
Build the functional that recovers amplitudes from a physical field. |
|
Build the flat seam record from a dense reference table. |
|
Project a declared transverse electric field onto a guide's channels. |
|
Build the source projection Q of one frequency and position. |
Classes
|
Own the full E/H reference of a general guide, flat, as the seam will take it. |
|
What a declared transverse field becomes in a guide's channels. |
- class solprop.translate.modal_tables.ModalTransformTables(omega, omega_fine, z_edges, synthesis, projection, electric, magnetic, backward_electric, backward_magnetic, reciprocal_gram, coordinate_dual, node_xy, weights, region_index, source_frequency_factor, valid, profile_error, factors, gauge_id, model_id, policy_id)[source]#
Bases:
DisplayedOwn the full E/H reference of a general guide, flat, as the seam will take it.
Built from a
DenseModalTablebymodal_transform_tables(), or along a moving guide bysolprop.translate.modal_path. It is flat – arrays, not a nest of samples – because that is what a backend can be handed, and it is thetransform.modal_tablesleaf of aPropagationProblem.factorsis alwaysNone; the denseelectricandmagneticreferences, thecoordinate_dualand the execution mapssynthesisandprojectionare filled. Frequency is the last axis and is contiguous. Both maps are tabulated on the coarse ``omega``: the state is a coarse spectrum and the fine grid is zero everywhere butgrids.crop_index, so a synthesis tabulated onomega_finewould carry columns no run can read. The oversampled grid is where the field lives, not where the map does: the pass synthesises on the coarse grid and places the result in the fine spectrum atcrop_index.- Attributes:
- omeganumpy.ndarray
Coarse angular frequencies in rad/s, shape (n_omega,), increasing and non-negative. On a
PropagationProblemit isgrids.omegaitself, whose first bin is zero on a field grid, with the inactive bins explicitly zero rather than evaluated.- omega_finenumpy.ndarray
Fine angular frequencies in rad/s, shape (n_omega_fine,), increasing and non-negative; the problem’s fine spectrum, by the same rule.
- z_edgesnumpy.ndarray
Stored positions in m, shape (n_z,), increasing; they are the edges the interval-indexed arrays are counted over, one interval per pair of positions and one for a single snapshot.
- synthesis, projectionnumpy.ndarray or None
The execution maps, supplied together or not at all, both on
omega.synthesisis S in V/(m sqrt(W)), shape(n_intervals, n_deg, n_nodes, 3, n_modes, n_omega);projectionis Q in V m/sqrt(W), shape(n_intervals, n_deg, n_modes, n_nodes, 3, n_omega), carrying the area weights and the reciprocal normalisation and excluding the separatesource_frequency_factor. The leading pair of axes is a Chebyshev expansion along z inside each interval, so one interval carrying a single coefficient (degree zero) is a constant map.- electric, magneticnumpy.ndarray
Reference E and H in V/m and A/m per sqrt(W), shape (n_z, n_nodes, 3, n_modes, n_omega).
- backward_electric, backward_magnetic, reciprocal_gramnumpy.ndarray or None
Reciprocal partners and their bilinear pairing, supplied together or not at all.
- coordinate_dualnumpy.ndarray or None
Amplitude recovery from a physical field, shape (n_z, n_modes, n_nodes, 6, n_omega): the first three components pair with E and the last three with H, in sqrt(W) m/V and sqrt(W) m/A.
- node_xynumpy.ndarray
Node positions in m, shape (n_z, n_nodes, 2).
- weightsnumpy.ndarray
Positive area weights in m², shape (n_z, n_nodes).
- region_indexnumpy.ndarray
Non-negative int32 material index per node, shape (n_nodes,).
- source_frequency_factornumpy.ndarray
The
-i omegathe projected polarisation is multiplied by, shape (n_omega,), in rad/s.- validnumpy.ndarray
Fine-grid support mask, shape (n_z, n_modes, n_omega_fine).
- profile_errornumpy.ndarray
Declared non-negative profile error per interval and coarse frequency, shape (n_intervals, n_omega), dimensionless.
- factorsobject or None
A factored representation; not implemented, so refused unless
None.- gauge_id, model_id, policy_idstr
Non-empty phase/coordinate, physical-model and numeric-policy identities.
- backward_electric: Complex[ndarray, 'n_z_backward_electric n_nodes_backward_electric 3 n_modes_backward_electric n_omega_backward_electric'] | None#
- backward_magnetic: Complex[ndarray, 'n_z_backward_magnetic n_nodes_backward_magnetic 3 n_modes_backward_magnetic n_omega_backward_magnetic'] | None#
- electric: Complex[ndarray, 'n_z_electric n_nodes_electric 3 n_modes_electric n_omega_electric']#
- property frozen_rule: bool[source]#
Whether one node rule was broadcast across every position.
A record built over several positions from one rule – the same Cartesian nodes and the same area weights at every z – is the frozen-rule case. It is legitimate and it is not free: along a path the panel edge leaves the material interface, and the interpolated basis’s flux defect grows linearly with that displacement (4.9e-7, 9.8e-7 and 1.95e-6 at a quarter, a half and the whole of a 1e-5 relative radius change). A taper needs sections with their own rules (
solprop.translate.modal_path); a snapshot is trivially frozen.True when
node_xyandweightsdo not vary along z.
- property identity: Mapping[str, JsonValue][source]#
Scalar identity a run records and a resume compares.
The record is
eq=False: two of them are never compared by value, and a resume must not compare megabytes of E and H field by field either. What enters identity is this mapping – the three declared IDs, the six extents, the region count, the band and position endpoints, which optional representations are present, the frozen-rule flag and the profile-error budget. Every entry is a scalar, a string, a boolean or a list of scalars; no array is included by value.A factored map enters by its declared
kindtag, never by itsrepr: a defaultreprcarries a memory address, which is not stable across the two processes a resume compares.The profile-error budget is the caller’s declared one, which on the general modal route is the guide’s measured error; it therefore enters at
MEASURED_DIGITSsignificant digits, exactly assolprop.modes.guide.ModalSampling.identityrecords the same number, so that the two agree and a re-solve on another BLAS does not move either of them.JSON-serialisable scalars, stable across processes.
- magnetic: Complex[ndarray, 'n_z_magnetic n_nodes_magnetic 3 n_modes_magnetic n_omega_magnetic']#
- node_xy: Float[ndarray, 'n_z_xy n_nodes_xy 2']#
- omega: Float[ndarray, 'n_omega_modal']#
- omega_fine: Float[ndarray, 'n_omega_fine_modal']#
- profile_error: Float[ndarray, 'n_intervals_profile_error n_omega_profile_error']#
- projection: Complex[ndarray, 'n_intervals_projection n_deg_projection n_modes_projection n_nodes_projection n_components_projection n_omega_projection'] | None#
- reciprocal_gram: Complex[ndarray, 'n_z_reciprocal n_modes_reciprocal_out n_modes_reciprocal_in n_omega_reciprocal'] | None#
- region_index: Int32[ndarray, 'n_nodes_region_index']#
- source_frequency_factor: Complex[ndarray, 'n_omega_source_factor']#
- synthesis: Complex[ndarray, 'n_intervals_synthesis n_deg_synthesis n_nodes_synthesis n_components_synthesis n_modes_synthesis n_omega_synthesis'] | None#
- valid: Bool[ndarray, 'n_z_valid n_modes_valid n_omega_fine_valid']#
- weights: Float[ndarray, 'n_z_weights n_nodes_weights']#
- z_edges: Float[ndarray, 'n_edges_modal']#
- class solprop.translate.modal_tables.ProjectedLaunch(amplitudes, captured, residual, residual_share)[source]#
Bases:
DisplayedWhat a declared transverse field becomes in a guide’s channels.
The result of
project_transverse_field(): the channel amplitudes, the power those amplitudes carry, and what the guide’s bound channels do not carry of the declared field. The last is named rather than discarded, because a projection that captured a tenth of what was declared and said nothing would be a silent change of the initial-value problem.- Attributes:
- amplitudesnumpy.ndarray
The channel amplitudes, complex128, shape
(n_modes, n_omega), in the square root of watts – the true-power amplitude every route uses (seedocs/dev/decisions.md), because the basis is flux-normalised.- capturednumpy.ndarray
The longitudinal Poynting flux the projected field carries, float64, shape
(n_omega,), in W. It is the physicalint Re(E x conj(H))/2 . z dAof the projected field, formed from the guide’s own stored E and H, which equalsa.H W aand is notsum_m |a_m|^2unless the basis is exactly orthonormal.- residualnumpy.ndarray
Share of the declared field the bound channels do not reproduce, float64, shape
(n_omega,), dimensionless and non-negative – and, likeresidual_sharebelow, not clipped at one:sum_q w_q |E - sum_m a_m e_m|^2 / sum_q w_q |E|^2at each bin, in the guide’s own quadrature norm. It isnanwhere the declared field is identically zero, because there is no share of nothing.- residual_sharefloat
The same quantity over the whole declared field, weighting each bin by its own declared norm rather than equally: one number for the projection. It is not clipped at one: on a basis that is not orthonormal the flux projection can overshoot, leaving a residual larger than the declared field itself, and a share above one says exactly that. Clipping it would report a projection that missed everything as one that missed all of it, which are different statements.
- Raises:
- ModeError
If the arrays disagree in shape, or the residual share is not finite and non-negative.
- amplitudes: Complex[ndarray, 'n_modes_launch n_omega_launch']#
- captured: Float[ndarray, 'n_omega_captured']#
- residual: Float[ndarray, 'n_omega_residual']#
- solprop.translate.modal_tables.coordinate_dual(sample, weights)[source]#
Build the functional that recovers amplitudes from a physical field.
The amplitude of channel
min a field(E, H)sampled at the nodes isa = W^-1 BwithB_m = int(E x h_m* + e_m* x H)_z dA / 4, the same Hermitian Poynting pairing the flux metric is built from, so that synthesising a declared amplitude vector and contracting this against it returns that vector. Only the transverse components enter the longitudinal flux, so the two longitudinal columns are zero. It is for amplitude recovery, not for nonlinear projection, which carries the separate-i omegafactor.- Parameters:
- samplesolprop.modes.vector.ModalSample
Internal-convention sample at one frequency and position.
- weightsnumpy.ndarray
The rule’s positive area weights in m², shape (n_nodes,).
- Returns:
- numpy.ndarray
Coefficients, shape (n_modes, n_nodes, 6): the first three pair with E in sqrt(W) m/V and the last three with H in sqrt(W) m/A.
- solprop.translate.modal_tables.modal_transform_tables(table, omega, *, profile_error, omega_fine=None, z=None, policy_id='dense-knots-cubic-frequency')[source]#
Build the flat seam record from a dense reference table.
The one constructor of
ModalTransformTables. It evaluates the table on the grid a run will use – which need not be the table’s own knots, and in general is not – and stores the fields, the reciprocal partners, the coefficient dual, the two execution maps and the node geometry as arrays.Outside the table’s band the record is explicitly zero, and the fine grid’s
validmask is false there. A canonical field grid starts at zero and runs past any guide’s support, so a leaf tabulated on it necessarily leaves the band; what must not happen is an evaluated profile there, which extrapolates a mode past the frequencies it was solved at. A zero reference is a zero source and a zero synthesised field: a run whose active band leaves the guide’s support is refused where the problem is assembled, not silently propagated against zeros.The execution maps are built for a snapshot table only. S and Q are stored as one Chebyshev coefficient per interval, which is exact when the map does not vary along z and an average when it does, so a table sampled over a path of positions gets
synthesisandprojectionofNoneand the general route refuses it: a moving basis needs sections with their own node rules, whichsolprop.translate.modal_pathbuilds. A snapshot is broadcast across every requested position, which is the frozen-rule caseModalTransformTables.frozen_rulenames.- Parameters:
- tableDenseModalTable
Tracked reference knots. Requested frequencies outside its band are stored as zeros; requested positions outside a path table’s own are refused, and a snapshot is broadcast to all of them.
- omeganumpy.ndarray
Coarse angular frequencies in rad/s, shape (n_omega,), increasing.
- profile_errorarray_like or float
Declared non-negative profile error of the representation, per interval and coarse frequency or one value for all of them. It is a budget the caller has measured, for example with
validate_modal_table(); nothing here infers it.- omega_finearray_like or None, optional
Fine angular frequencies in rad/s;
Noneuses the coarse grid, which is what a run with no oversampling declares.- zarray_like or None, optional
Positions in m to store;
Noneuses the table’s own.- policy_idstr, optional
Identity of the numeric policy this record was built under.
- Returns:
- ModalTransformTables
The validated flat record, with
factorsleftNoneand thecoordinate_dualfilled.
- Raises:
- ModeError
If a position leaves a path table’s domain, or the record does not validate.
- solprop.translate.modal_tables.project_transverse_field(tables, electric)[source]#
Project a declared transverse electric field onto a guide’s channels.
The launch a caller declares as a field rather than as a channel: the amplitude of each channel in a declared
E(x, y, omega)sampled at the guide’s own quadrature nodes, with the power captured and the remainder named.The map is the coordinate dual, not the source projection. The amplitude of a field in a flux-normalised basis is
a = W^-1 BwithB_m = int(E x h_m* + e_m* x H)_z dA / 4, the same Hermitian Poynting pairing the flux metric is built from, and that is whattables.coordinate_dualcarries.Q, the record’s other map, contracts a polarisation with the conjugated electric profile and carries the reciprocal normalisation for a source term; it is a different operation and gives a different number.Only E is declared, so the H half is closed by the forward-field assumption. For any superposition of these channels travelling forward, the two halves of
B_mare equal – the Poynting cross matrix of a lossless bound basis is Hermitian – soB_m = 2 int(E x h_m*)_z dA / 4and the declared E alone determines the amplitudes. Measured on the step-index parity pair, a field synthesised from known amplitudes comes back through this map to 1.412e-15 of them, which is rounding and not the basis’s Gram defect (1.3e-6), so the closure is exact for this package’s providers rather than approximate. (Its last digits move with the BLAS thread count, as a 288-node reduction’s rounding does; the quoted number is one thread everywhere, and the bound the test asserts is 1e-13.) That exactness is a statement about a lossless basis: the Hermitian symmetry of the Poynting cross matrix is what makes the two halves equal, and a complexPermittivityLawbreaks it, so on such a basis the closure would be wrong by an amount only a growing residual share would show. No such basis can reach here: both providers this package ships refuse a complex permittivity when they solve, by name ("provider material differs from its lossless step-index law"and"radial provider requires positive lossless permittivity"), so the condition is enforced upstream and a future lossy provider must re-derive the closure rather than inherit it. A field that is not forward-propagating – a declared backward or evanescent component – is not what this map returns either, and nothing here can see the difference; declare the amplitudes directly if that is wanted.What is not captured is named. The bound channels span what they span: a declared field with power in radiation modes, in a channel the guide did not solve for, or simply outside the node rule’s reach leaves a residual, and ProjectedLaunch.residual reports it as a share of the declared field in the guide’s own quadrature norm. Reprojecting a field creates a new initial-value problem; it is not a resume path.
- Parameters:
- tablesModalTransformTables
The guide’s reference, which must carry its coordinate dual.
- electricnumpy.ndarray
The declared transverse field at the guide’s nodes, real or complex (a real profile is the common case and is taken as it is), shape
(n_nodes, n_components, n_omega), in V/m, on the record’s own coarse frequency axis. A profile that does not depend on frequency is broadcast to it by the caller.
- Returns:
- ProjectedLaunch
The amplitudes, the captured flux and the residual.
- Raises:
- ModeError
If the record carries no coordinate dual, or the declared field does not lie on its nodes, components and frequencies.
- solprop.translate.modal_tables.projection_map(sample, weights)[source]#
Build the source projection Q of one frequency and position.
The modal source functional of a bound reciprocal basis is
da_m/dz = -i omega [W^-1]_mn int(e_n* . P) dA / 4, so the map that takes a nodal polarisation to an amplitude rate, without the separate-i omegafactor, isQ[m, q, c] = [W^-1]_mn conj(e_n[q, c]) w[q] / 4,the same Hermitian pairing and the same reciprocal normalisation the coefficient dual is built from. Source projection and amplitude recovery are different operations: this one contracts a polarisation in C/m^2 and has units V m/sqrt(W), so
Q P omegais in sqrt(W)/m.- Parameters:
- samplesolprop.modes.vector.ModalSample
Internal-convention sample at one frequency and position.
- weightsnumpy.ndarray
The rule’s positive area weights in m², shape (n_nodes,).
- Returns:
- numpy.ndarray
Qin V m/sqrt(W), shape (n_modes, n_nodes, 3).