solprop.modes.path#
Sample a guide whose geometry moves along z, section by section, in its own gauge.
A solid guide’s modes change shape along a taper, so the general route’s synthesis
S and projection Q move with z; this module samples that motion.
path_sections() cuts the path at its declared kinks; path_rule() and
path_snapshot() solve one position on the provider’s own rule there and in its
own gauge; sample_modal_path() doubles the Chebyshev-Lobatto degree per section
(from INITIAL_PATH_DEGREE to MAX_PATH_DEGREE) until the expansion
reproduces held-out solves, returning a ModalPathTable: the snapshots beside
the ModalPath record of the sampling, which a guide keeps and a run rebuilds
the same snapshots from. What a run reads of it is built in
solprop.translate.modal_path.
Two invariants. The node rule moves with the geometry, so node q stays in one
material region and a map stored there is smooth in z; the connection’s Eulerian
derivative keeps the union-split rule of
solprop.modes.connection.connection_nodes() instead. The gauge is the
provider’s own, because the connection is measured in it, so a provider whose gauge
is discontinuous along the path is refused (GAUGE_PHASE_ATOL). The full account
is docs/guide/waveguides/moving-modal.md, section “A guide whose geometry moves
along z”.
Module Attributes
Chebyshev degree along z a path's accuracy search starts at, per section. |
|
Highest Chebyshev degree along z a path's accuracy search tries per section. |
|
Smallest held-out error along z a path's accuracy search is asked to reach. |
|
Largest phase, rad, between two neighbouring samples' aligned overlap. |
Functions
|
Return the provider's own rule at z, asked for exactly as rule was. |
|
Return the section edges of a moving provider's path, in m. |
|
Solve one position of a path over the band, in the provider's own gauge. |
|
Sample a moving guide along its sections, at the degree its accuracy demands. |
Classes
|
Record how a moving guide was sampled along z, and what that measured. |
|
Hold a moving guide's snapshots at its path's Chebyshev-Lobatto points. |
- solprop.modes.path.GAUGE_PHASE_ATOL = 1e-09#
Largest phase, rad, between two neighbouring samples’ aligned overlap.
The connection is measured in the provider’s own gauge with its stencil aligned to the centre, which removes any phase the gauge accumulates along z; the maps are expanded in the same gauge without that alignment. They agree only where the provider’s gauge has no phase rate of its own, and the two qualified providers’ fields are real up to a fixed factor, so their overlaps are real to rounding. A provider whose gauge drifts would put
i phi'on the maps’ diagonal and not on the connection’s, which is refused rather than propagated.
- solprop.modes.path.INITIAL_PATH_DEGREE = 4#
Chebyshev degree along z a path’s accuracy search starts at, per section.
Four is five solves per section before anything is measured. The search doubles from here, and the Chebyshev-Lobatto points nest bitwise under a doubling, so no solve is ever repeated (
solprop.modes.quadrature.lobatto_points()).
- solprop.modes.path.MAX_PATH_DEGREE = 32#
Highest Chebyshev degree along z a path’s accuracy search tries per section.
The same ceiling
solprop.translate.coupled.MAX_SECTION_DEGREEputs on a coupled flow’s sections, and for the same reason: a smooth section of a declared taper resolves at a low degree, and a degree this high means the section spans structure the provider should declare as a kink, or the caller should divide.
- class solprop.modes.path.ModalPath(z_edges, degree, sections, rtol, z_error, gram_departure)[source]#
Bases:
DisplayedRecord how a moving guide was sampled along z, and what that measured.
The z half of a guide’s sampling (
ModalSampling), filled byfrom_provider()for a provider whose geometry moves. The path is cut into sections – the provider’s declared kink intervals, each divided sections times (path_sections()) – and every section is solved at the Chebyshev-Lobatto points of one degree along z, the degree the accuracy check demanded: doubled until the expansion reproduced a fresh solve at the points a doubling adds to within rtol (sample_modal_path(), whoseModalPathTableholds the snapshots beside this record). A run rebuilds the same positions from this record rather than searching again.- Attributes:
- z_edgesnumpy.ndarray
Section edges in m, strictly increasing, shape
(n_edges_path,): the provider’s z domain split at its interior breakpoints and subdivided.- degreeint
The Chebyshev degree along z every section is sampled at, positive; each section holds
degree + 1positions, its two ends included.- sectionsint
How many sections each kink interval was divided into, positive.
- rtolfloat
The budget the degree was searched against, positive: by default the frequency interpolation’s own measured profile error, so that the sampling in z is never the coarser of the two.
- z_errorfloat
The measured held-out departure at the degree kept, dimensionless and non-negative: the largest relative maximum-norm departure of E, H or the generator from a fresh solve between the sampled positions.
- gram_departurefloat
The largest
norm(W - I, 2)of the expanded basis at those same held-out positions, dimensionless and non-negative.
- Raises:
- ModeError
Naming the field that is out of range.
Examples
>>> import numpy as np >>> from solprop.modes.path import ModalPath >>> path = ModalPath(np.array([0.0, 1e-3]), 2, 1, 1e-6, 3e-7, 1e-8) >>> path.positions.round(6).tolist() [[0.0, 0.0005, 0.001]] >>> round(float(path.interpolate(np.array([0.0, 1.0, 2.0]), 2.5e-4)), 12) 0.5
- property identity: Mapping[str, JsonValue][source]#
What a run records of the path, and a resume compares.
The declared edges, degree, subdivision and budget exactly; the two measured departures at
MEASURED_DIGITS, as every other measured entry of a guide’s identity is.JSON-serialisable scalars and lists of scalars.
- interpolate(values, z)[source]#
Evaluate values sampled at the path’s positions at any position.
The barycentric form of the interpolating polynomial through one section’s Chebyshev-Lobatto samples – weights
(-1)^j, halved at the two ends – which is the same polynomial the translation layer’s Chebyshev coefficients carry, evaluated stably. A position outside the path holds the nearest end’s value, as aZProfileholds its own beyond its span: a run’s tables reach a few per cent past its end, and the geometry is not declared there.- Parameters:
- valuesnumpy.ndarray
One value per position, in
positionsorder flattened, position axis first, shape(n_intervals * (degree + 1), *value_shape).- zfloat
Position in m.
- Returns:
- numpy.ndarray
The value at z, shape
value_shape.
- Raises:
- ModeError
If values does not carry one row per position.
- property positions: Float[ndarray, 'n_intervals_path n_deg_path'][source]#
Every sampled position, section by section, m.
Shape
(n_intervals, degree + 1), increasing inside a section, so a position on an interior edge appears twice.
- section(z)[source]#
Return the section a position lies in, clamped to the path’s ends.
- Parameters:
- zfloat
Position in m.
- Returns:
- int
The section index; a position on an interior edge takes the section starting there, and one outside the path the nearest end’s.
- z_edges: Float[ndarray, 'n_edges_path']#
- class solprop.modes.path.ModalPathTable(path, tables)[source]#
Bases:
DisplayedHold a moving guide’s snapshots at its path’s Chebyshev-Lobatto points.
What
sample_modal_path()returns: the record of how the path was sampled and the snapshot solved at each of its positions.- Attributes:
- pathModalPath
How the path was sampled and what that measured: its section edges, degree, positions and held-out departures.
- tablestuple of solprop.modes.tables.DenseModalTable
One snapshot per position of
path.positions, section by section and increasing inside each, so a position on an edge between two sections appears twice, as the end of one and the start of the next.
- Raises:
- solprop.exceptions.ModeError
If the tables do not sit at the path’s positions, in order.
- section_tables(index)[source]#
Return one section’s snapshots, increasing in z.
- Parameters:
- indexint
The section, in
[0, path.n_intervals).
- Returns:
- tuple of solprop.modes.tables.DenseModalTable
Its
path.degree + 1snapshots.
- tables: tuple[DenseModalTable, ...]#
- solprop.modes.path.PATH_RTOL_FLOOR = 1e-10#
Smallest held-out error along z a path’s accuracy search is asked to reach.
The default target is the frequency interpolation’s own measured error, and a very well sampled band can measure below what a provider’s solves reproduce between two positions: the fields at a node are a sum over a quadrature and an eigenproblem, and their relative round-off is of order
1e-13to1e-12. Below this floor the search would be doubling to resolve round-off.
- solprop.modes.path.path_rule(provider, rule, z)[source]#
Return the provider’s own rule at z, asked for exactly as rule was.
The frequency and the resolution are read from rule’s own identity, so the rule at every position of a path is the one the provider would have built there on the same request: its panel edges on that position’s interfaces, its tail certified there. It must keep rule’s structure – the same node count and the same material region at every node – because node
qis one moving point along the whole path and the seam carries one region index per node.- Parameters:
- providersolprop.modes.vector.ModalProvider
The guide.
- rulesolprop.modes.vector.ModalNodeRule
The entrance rule, whose identity names
omega,n_randn_theta.- zfloat
Position in m inside the provider’s z domain.
- Returns:
- solprop.modes.vector.ModalNodeRule
The rule at z.
- Raises:
- solprop.exceptions.ModeError
If rule does not say how it was asked for, or the rule at z changes its node count or any node’s material region.
- solprop.modes.path.path_sections(provider, sections=1)[source]#
Return the section edges of a moving provider’s path, in m.
The provider’s z domain split at every declared breakpoint strictly inside it – each a kink of the geometry, where the connection jumps with the slope – and each of those intervals divided into sections equal parts.
- Parameters:
- providersolprop.modes.vector.ModalProvider
The guide, whose
z_domainandz_breakpointsare read.- sectionsint, optional
Sections per kink interval, positive; one by default.
- Returns:
- numpy.ndarray
The edges in m, strictly increasing, from the domain’s start to its end.
- Raises:
- solprop.exceptions.ModeError
If sections is not a positive integer.
Examples
>>> import numpy as np >>> from solprop.modes.graded_index import ( ... GradedIndexProvider, PowerLawPermittivity, ... ) >>> from solprop.modes.material import IndexMaterial >>> from solprop.profiles import PiecewiseLinear >>> from solprop.modes.path import path_sections >>> guide = GradedIndexProvider( ... permittivity=PowerLawPermittivity(IndexMaterial(1.45), 0.005), ... exterior=IndexMaterial(1.45 * np.sqrt(1 - 2 * 0.005)), ... radius=PiecewiseLinear( ... np.array([0.0, 4e-4, 1e-3]), np.array([25e-6, 24e-6, 22.5e-6]) ... ), ... family="LP", count=2, elements=16, extent=2.0, ... ) >>> [round(one, 6) for one in path_sections(guide, 2).tolist()] [0.0, 0.0002, 0.0004, 0.0007, 0.001]
- solprop.modes.path.path_snapshot(provider, omega, z, nodes, *, degenerate_blocks=(), basis=None, gram_atol=0.0001)[source]#
Solve one position of a path over the band, in the provider’s own gauge.
Unlike
solprop.modes.tables.sample_modal_table()the knots are not aligned to one another: they are kept exactly as the provider returns them, with the gauge’s continuity across the band checked instead (GAUGE_PHASE_ATOL), because the connection a moving guide is propagated with is measured in that gauge. A declared basis is applied after, as it is there.- Parameters:
- providersolprop.modes.vector.ModalProvider
The guide.
- omeganumpy.ndarray
At least four increasing positive frequencies in rad/s, shape (n_omega,).
- zfloat
Position in m inside the provider’s z domain.
- nodessolprop.modes.vector.ModalNodeRule
The rule at z (
path_rule()).- degenerate_blockssequence of sequence of int, optional
The declared degenerate blocks, retained on the table.
- basissolprop.modes.guide.ChannelBasis or None, optional
A declared constant unitary change of the channel coordinates.
- gram_atolfloat, optional
The table’s construction budget on its sampled Gram defect.
- Returns:
- solprop.modes.tables.DenseModalTable
A snapshot table at z.
- Raises:
- solprop.exceptions.ModeError
If the provider’s gauge is not continuous across the band, or on anything the provider or the table refuses.
- solprop.modes.path.sample_modal_path(provider, omega, rule, *, rtol=None, sections=None, path=None, degenerate_blocks=(), basis=None, gram_atol=0.0001, known=None)[source]#
Sample a moving guide along its sections, at the degree its accuracy demands.
The path is cut into sections (
path_sections()), and each section is solved at the Chebyshev-Lobatto points of a degree, starting atINITIAL_PATH_DEGREE, on the provider’s own rule at each position (path_rule()) and in its own gauge (path_snapshot()). The expansion along z is then checked against fresh solves at the points a doubling adds, which are the natural held-out points: they lie between every pair of the current ones and are exactly the solves the next degree needs, so the check costs nothing the doubling would not. The degree is doubled, for every section together because the seam’s degree axis is rectangular, until the largest relative departure of E, H and the generator is within rtol; the degree then kept is the one whose error was measured, not the doubled one, so that the certificate is a measurement of what is stored.With a qualified path given instead, nothing is searched or measured: the snapshots are solved at its edges and degree, and it is carried as it stands, which is how a run rebuilds the path its guide already qualified.
- Parameters:
- providersolprop.modes.vector.ModalProvider
The moving guide.
- omeganumpy.ndarray
The frequency knots in rad/s, shape (n_omega,), at least four.
- rulesolprop.modes.vector.ModalNodeRule
The entrance rule, which every position’s rule is asked for like (
path_rule()).- rtolfloat or None, optional
Budget on the held-out departure, positive and finite, for a search; given unless path is.
- sectionsint or None, optional
Sections per kink interval of a search, positive;
Noneis one. Not given with path.- pathModalPath or None, optional
A path already qualified, which skips the search.
- degenerate_blockssequence of sequence of int, optional
The declared degenerate blocks.
- basissolprop.modes.guide.ChannelBasis or None, optional
A declared constant unitary change of the channel coordinates.
- gram_atolfloat, optional
Each snapshot’s construction budget on its sampled Gram defect.
- knownmapping or None, optional
Snapshots already solved, keyed by position, reused rather than solved again.
- Returns:
- ModalPathTable
The path record and its snapshots.
- Raises:
- solprop.exceptions.ModeError
If neither or both of a search’s budget and a qualified path are given, rtol is not positive and finite, sections is not a positive integer, the held-out departure is still above rtol at
MAX_PATH_DEGREE, or on anything a snapshot refuses.