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

INITIAL_PATH_DEGREE

Chebyshev degree along z a path's accuracy search starts at, per section.

MAX_PATH_DEGREE

Highest Chebyshev degree along z a path's accuracy search tries per section.

PATH_RTOL_FLOOR

Smallest held-out error along z a path's accuracy search is asked to reach.

GAUGE_PHASE_ATOL

Largest phase, rad, between two neighbouring samples' aligned overlap.

Functions

path_rule(provider, rule, z)

Return the provider's own rule at z, asked for exactly as rule was.

path_sections(provider[, sections])

Return the section edges of a moving provider's path, in m.

path_snapshot(provider, omega, z, nodes, *)

Solve one position of a path over the band, in the provider's own gauge.

sample_modal_path(provider, omega, rule, *)

Sample a moving guide along its sections, at the degree its accuracy demands.

Classes

ModalPath(z_edges, degree, sections, rtol, ...)

Record how a moving guide was sampled along z, and what that measured.

ModalPathTable(path, tables)

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_DEGREE puts 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: Displayed

Record how a moving guide was sampled along z, and what that measured.

The z half of a guide’s sampling (ModalSampling), filled by from_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(), whose ModalPathTable holds 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 + 1 positions, 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
degree: int#
gram_departure: float#
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 a ZProfile holds 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 positions order 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 n_intervals: int[source]#

How many sections the path is cut into.

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.

rtol: float#
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.

sections: int#
z_edges: Float[ndarray, 'n_edges_path']#
z_error: float#
class solprop.modes.path.ModalPathTable(path, tables)[source]#

Bases: Displayed

Hold 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.

path: ModalPath#
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 + 1 snapshots.

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-13 to 1e-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 q is 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_r and n_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_domain and z_breakpoints are 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 at INITIAL_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; None is 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.