solprop.modes.wall#

Condense a capillary’s outgoing wall condition onto its retained Marcatili modes.

The coherent wall replaces each mode’s own diagonal Marcatili loss by the rank-one Robin wall term that couples every retained mode to every other with a definite phase. CoherentWall is the declaration a capillary run takes; the operators it builds are WallOperator (wall_operator(), one scalar HE1m block) and VectorWallOperator (vector_wall_operator(), the vector families of WallFamily), each with its validity ratios in WallLimits (worst_wall_limits() over a path). Along a taper or a pressure gradient the moving basis carries the connection of wall_connection() and taper_connection() (blocks chosen by taper_coupling_block()), and wall_square_root_metric() is the metric those blocks are measured in. The modes themselves are MarcatiliMode; the manual pages are docs/guide/waveguides/coherent-wall.md and vector-wall.md.

Module Attributes

WallImpedance

Whether a coherent wall condenses one mean impedance or separate TE and TM ones.

Functions

taper_connection(modes[, z])

Return the taper connection of an HE_1m block at one position.

taper_coupling_block(modes)

Return the mode set the taper coupling is carried on, or None.

vector_wall_operator(modes, omega, *[, z, ...])

Build the condensed vector Robin wall generator of one azimuthal order.

wall_connection(modes[, z, impedance])

Return the moving-basis connection of a wall block at one position.

wall_operator(modes, omega, *[, z, active, ...])

Build the condensed Robin wall generator of a contiguous HE_1m block.

wall_square_root_metric(generator, wavenumber)

Return the square-root generator and its candidate flux metric, as a diagnostic.

worst_wall_limits(modes, omega, *, positions)

Return the validity ratios at the position where they are worst.

Classes

CoherentWall([condition_limit, ...])

Declare the coherent wall block of a capillary mode set.

VectorWallOperator(omega, active, generator, ...)

The condensed vector Robin wall generator of one azimuthal order.

WallFamily(label, azimuthal_order, ...)

One radial family of a vector coherent wall block.

WallLimits(transverse_ratio, vacuum_ratio, ...)

The dimensionless validity ratios of one coherent wall block.

WallOperator(omega, active, generator, ...)

The condensed Robin wall generator of a contiguous HE_1m block.

class solprop.modes.wall.CoherentWall(condition_limit=10000.0, validity_limit=0.25, sections=1, impedance='mean')[source]#

Bases: Displayed

Declare the coherent wall block of a capillary mode set.

The capillary route’s diagonal operator gives every mode its own Marcatili attenuation and no coupling at all. The coherent wall instead condenses the outgoing Robin boundary condition onto the retained basis, which makes the wall a rank-one term that couples every mode to every other one with a definite phase. Declaring one on solprop.driver.simulation.Simulation.from_capillary() replaces the diagonal Marcatili loss of the block’s channels by that operator, exactly as wall_operator() builds it.

Its physical content, in the optics convention of docs/dev/conventions.md section 2 and with the carrier removed, is the paraxial generator

\[G = D + H,\qquad D = -\frac{i}{2ka^2}\operatorname{diag}(u_m^2), \qquad H = g(a)\,hh^{T},\]

with \(h_m = -\sqrt2\,\operatorname{sgn}J_1(u_m)\,u_m\) the radial derivative of the orthonormal basis function at the wall, and \(g(a) = i/[2ka^2(2N - i k_{\rm eff}a)]\). The manual page is docs/guide/waveguides/coherent-wall.md.

A guide that varies along z – a pressure gradient, a taper – is carried by a frozen-residual split: the complete generator G_s = D(z_s) + H(z_s) is frozen at each section’s midpoint inside the exponential flow, and its variation joins the HE1m connection

\[C_{mn} = \frac{a'}{a}\frac{2s_ms_nu_mu_n}{u_m^2-u_n^2}\ (m\ne n), \qquad C_{nn} = 0\]

in the explicit residual R_s(z) = D(z) - D(z_s) + H(z) - H(z_s) - C(z), which the interaction-picture Runge-Kutta source carries. Freezing is a rearrangement of the same equation and not a second-order approximation, because the residual is evaluated exactly; sections is what trades the residual’s stiffness against the number of frozen blocks (solprop.translate.coupled.frozen_residual_flow()).

What it replaces, and what it therefore refuses. The block is the run’s loss model, so a capillary carrying one must keep the model’s loss: loss_scale=0, another scale or a measured alpha is refused by name rather than discarded. It is derived for the full capillary model, so model="reduced" is refused too. It needs the contiguous HE_11 to HE_1N set, whose every channel declares the same radius and density profiles and whose profiles carry analytic derivatives, and a scalar run. It carries the default "input" noise, drawn in the channel basis at the entrance and propagated like any field, and refuses the "modified" model, whose transport through a nonunitary coupled flow is not measured. numpy_ref and native execute the linear.coupled_flow leaf it becomes.

The vector boundary response is impedance="te_tm". The scalar block above condenses one impedance-averaged Robin condition, which is what a linearly polarised HE_1m field sees on azimuthal average; the vector block condenses the two conditions the wall actually imposes – the radial (TM-like) field sees k_o/n_r^2 and the tangential (TE-like) field sees k_o – and is therefore a block per total azimuthal order, coupling the two radial families of that order rather than one. See vector_wall_operator(); the averaged impedance is recovered from it as a limit rather than assumed.

Attributes:
impedancestr

"mean" for the impedance-averaged block, "te_tm" for the coupled azimuthal block, which gives the wall’s TE (tangential) and TM (radial) fields their own impedances. It names the wall’s two impedances and not the state’s polarisation axis: a "te_tm" run still carries one transverse component per channel. On a guide that varies along z – a taper, a pressure gradient – the vector block takes the same frozen-residual route as the scalar one, with a connection that is each radial family’s own and nothing between the families (wall_connection()). Which families the run carries is the mode set’s business and not this field’s: a set retaining one hybrid family alone is a legitimate vector block with no partner to couple to, and is the scalar block to the last bit, because that family’s Bessel order is zero and its diagonal impedance is the average. Declare the partner family – the hybrids of azimuthal index -nu – to have a conversion at all. The transverse order nu = 0 is not like that: TE_0m and TM_0m carry their own impedances whether or not the other is retained.

condition_limitfloat

Largest admitted norm(U) norm(U^-1) of one step’s flow action, dimensionless and at least one. The inverse action is what the interaction-picture source is carried back by, so an unbounded inverse is an unbounded amplification of that source; the backend measures the product per step and refuses above this. The default 1e4 admits a step that attenuates the most lossy retained mode by about nine e-foldings.

validity_limitfloat

Largest admitted value of the three dimensionless validity ratios of WallLimits. Above it the block is refused by name; above a tenth of it the construction warns, naming the ratio. The default 0.25 keeps the retained transverse scale well inside the paraxial and quasi-static regimes.

sectionsint

How many equal sections each interval of the run’s own linear-operator table is divided into, a positive integer. The placement is not this number’s: the edges are the table’s breakpoints, which already land on every declared kink of the radius and the density, subdivided sections times. One, the default, freezes one generator per declared interval; raising it reduces the residual’s norm and the inverse amplification, and is not permission to discard the residual. It has no effect on a constant guide, whose residual is exactly zero and which takes the single-section constant-Schur flow whatever this says.

Raises:
ModeError

If a limit or the section count is out of range.

Examples

>>> from solprop.modes import CoherentWall
>>> CoherentWall().impedance, CoherentWall(impedance="te_tm").impedance
('mean', 'te_tm')
>>> repr(CoherentWall())[:43]
'CoherentWall(impedance=mean, condition_limi'
condition_limit: float = 10000.0#
impedance: Literal['mean', 'te_tm'] = 'mean'#
sections: int = 1#
validity_limit: float = 0.25#
class solprop.modes.wall.VectorWallOperator(omega, active, generator, families, sector, family_traces, weight, wavenumber, impedance, limits)[source]#

Bases: Displayed

The condensed vector Robin wall generator of one azimuthal order.

The output of vector_wall_operator(), and the vector counterpart of WallOperator: the dense paraxial generator in the optics convention and in 1/m, the pieces it was factored from and the validity ratios it was checked against. Crossing to the internal FFT convention is the complex conjugate of the whole equation, exactly as for the scalar block.

The wall term is rank two, not rank one: one boundary trace vector per family, weighted by the condensed 2 x 2 impedance of the order.

Attributes:
omeganumpy.ndarray

The angular frequencies in rad/s the block is tabulated on, shape (n_omega,); the whole grid, with the inactive bins left exactly zero.

activenumpy.ndarray

Where the operator was evaluated, bool, shape (n_omega,).

generatornumpy.ndarray

G = D + H in 1/m, complex, shape (n_modes, n_modes, n_omega), in the optics convention with the carrier k removed.

familiestuple of WallFamily

The one or two radial families of this order, in the state’s channel order.

sectorint

The total azimuthal order nu >= 0 every channel of the block belongs to.

family_tracesnumpy.ndarray

The boundary traces h_m arranged one column per family, dimensionless, shape (n_modes, n_families), exactly zero outside each family’s own channels. The wall term is V W V^T with V this matrix.

weightnumpy.ndarray

W = i S/(2 k a^2) in 1/m, complex, shape (n_families, n_families, n_omega): the condensed impedance of the order, scaled by the paraxial reduction. Zero off the active band.

wavenumbernumpy.ndarray

The in-core wavenumber k = n_core omega / c in 1/m, complex, shape (n_omega,), zero off the active band.

impedancenumpy.ndarray

The wall’s own two impedances in m, complex, shape (2, n_omega): the radial (TM-like) v_TM/k_0 and the tangential (TE-like) v_TE/k_0, built from this package’s own Marcatili cladding terms. Their mean is the scalar block’s 1/k_eff and their half-difference is the anisotropy.

limitsWallLimits

The validity ratios over the active band.

Examples

>>> import numpy as np
>>> from solprop.modes import MarcatiliMode, vector_wall_operator
>>> modes = [MarcatiliMode(125e-6, "He", 1.0, kind=k, n=0) for k in ("TM", "TE")]
>>> block = vector_wall_operator(modes, np.array([2.356e15]))
>>> block.sector, block.n_families, block.generator.shape
(0, 2, (2, 2, 1))
>>> bool(abs(block.generator[0, 1, 0]) == 0.0)
True
active: Bool[ndarray, 'n_omega_vec_a']#
families: tuple[WallFamily, ...]#
family_traces: Float[ndarray, 'n_modes_vec_h n_families_vec_h']#
generator: Complex[ndarray, 'n_modes_vec_out n_modes_vec_in n_omega_vec_g']#
impedance: Complex[ndarray, 'n_wall_components n_omega_vec_z']#
limits: WallLimits#
property n_families: int[source]#

How many radial families the block carries.

One or two.

property n_modes: int[source]#

How many channels the block couples.

The total over its families.

omega: Float[ndarray, 'n_omega_vec']#
sector: int#
wavenumber: Complex[ndarray, 'n_omega_vec_k']#
weight: Complex[ndarray, 'n_families_w_out n_families_w_in n_omega_vec_w']#
class solprop.modes.wall.WallFamily(label, azimuthal_order, bessel_order, n_channels, angular, radial_sign)[source]#

Bases: object

One radial family of a vector coherent wall block.

A vector block is one total azimuthal order \(\nu\) of a capillary, and that order has at most two radial families, because the transverse field of an order-\(\nu\) mode is a combination of the two circular components \(\hat e_\pm\), whose Cartesian angular harmonics are \(\nu\mp1\) and whose radial functions are therefore \(J_{\nu-1}\) and \(J_{\nu+1}\). Each family is a contiguous m = 1 .. N_f set of this package’s own Marcatili channels.

Attributes:
labelstr

How the family prints: "HE_1m", "EH_1m", "TE_0m", "TM_0m" and the higher orders in the same spelling.

azimuthal_orderint

The channels’ own n. Within one sector the two families carry +nu and -nu; nu = 0 carries the two transverse kinds.

bessel_orderint

p, the order of the Bessel function the family’s radial basis is built from, >= 0: |n - 1| for a hybrid family and 1 for a transverse one.

n_channelsint

How many radial orders of this family the block retains, >= 1.

angulartuple of float

The family’s angular content at the wall, (radial, tangential), a unit two-vector: the fraction of its boundary field that is normal to the wall and the fraction tangential to it. (1, 0) for TM_0m and (0, 1) for TE_0m, which is why those two see the wall’s own two impedances; and (1, -1)/sqrt 2 and (1, 1)/sqrt 2 for the two hybrid families of an order nu >= 1, which is why those see the impedance average on the diagonal and the impedance difference between them.

radial_signfloat

The sign of the family’s implemented radial profile against J_p, +1 or -1. field() builds a hybrid from jv(n - 1, .), and J_{-p} = (-1)^p J_p, so the n = -nu family of an even order is implemented with the opposite sign to J_{nu+1}. It is a gauge of the mode and cancels out of every diagonal quantity, but it is the sign of the coupling between the two families, so the wall’s boundary traces carry it.

Examples

>>> from solprop.modes.wall import WallFamily
>>> family = WallFamily("TE_0m", 0, 1, 4, (0.0, 1.0), 1.0)
>>> family.truncation
9
angular: tuple[float, float]#
azimuthal_order: int#
bessel_order: int#
label: str#
n_channels: int#
radial_sign: float#
property truncation: int[source]#

The family’s boundary truncation constant 2 N_f + p_f.

The constant the condensation’s denominator carries for this family: the truncated boundary self term sum_m h_m^2/u_m^2 = 2 N_f of the retained orders plus the p_f of the exact recurrence q J_{p+1}(q) = (p - i eta) J_p(q). Dropping the p_f leaves a residue that does not fall with N.

solprop.modes.wall.WallImpedance#

Whether a coherent wall condenses one mean impedance or separate TE and TM ones.

alias of Literal[‘mean’, ‘te_tm’]

class solprop.modes.wall.WallLimits(transverse_ratio, vacuum_ratio, quasi_static, band, n_modes, radius)[source]#

Bases: Displayed

The dimensionless validity ratios of one coherent wall block.

Each is evaluated with the highest retained mode over the band the run scores (band below), which is where every approximation in it is worst there. None of them is a proof of Maxwell accuracy: they are the stated conditions under which the condensed paraxial model is the model it claims to be. In particular a converged paraxial Robin equation is not by itself Maxwell accuracy, and many retained basis components can exceed the in-core wavenumber without being propagating channels.

Attributes:
transverse_ratiofloat

u_N / (|k| a) with k the in-core wavenumber: how far the highest retained transverse scale is from paraxial. The paraxial generator’s own error is a quarter of its fourth power relative to the carrier.

vacuum_ratiofloat

u_N / (k_0 a) with k_0 the vacuum wavenumber: the grazing-incidence ratio the Marcatili expansion is asymptotic in, which the cladding term is referred to.

quasi_staticfloat

2N / |a k_eff|: the fraction of the eliminated boundary coordinate the condensation discards in the quasi-static wall limit. Raising N raises this, so it cannot by itself validate the condensation. A vector block takes the same ratio family by family and keeps the worst: (2N_f + p_f) sum_g |Z_fg| / a, with p_f the family’s Bessel order and Z its impedance matrix in m, which is the row sum the condensed S = (C - i a Z^-1)^-1 departs from i Z/a by (vector_wall_operator()).

bandtuple of float

Lowest and highest angular frequency in rad/s the ratios were taken over. On a run this is the error norm’s scored band (solprop.grid.TimeGrid.inband_mask, the requested wavelength limits), not the active band the operator is built on: a field grid’s active band reaches about twice the longest requested wavelength, where every ratio (each proportional to the wavelength) is about twice its in-band value, and those collar bins are absorbed rather than scored. Without a scored mask, or with one that holds no evaluated bin, it is the whole evaluated band.

n_modesint

How many channels the block carries, over every family in it.

radiusfloat

Core radius in m the ratios were taken at.

Examples

>>> from solprop.modes.wall import WallLimits
>>> limits = WallLimits(0.01, 0.01, 0.02, (1e15, 3e15), 4, 125e-6)
>>> f"{limits.worst:.3f}"
'0.020'
band: tuple[float, float]#
n_modes: int#
named()[source]#

Return the name and the value of the ratio that is worst.

Returns:
tuple

The ratio’s name as it is written here, and its value.

Examples

>>> from solprop.modes.wall import WallLimits
>>> WallLimits(0.3, 0.1, 0.2, (1e15, 3e15), 4, 125e-6).named()[0]
'transverse_ratio'
quasi_static: float#
radius: float#
transverse_ratio: float#
vacuum_ratio: float#
property worst: float[source]#

Largest of the three ratios.

The one a refusal or a warning is taken on.

class solprop.modes.wall.WallOperator(omega, active, generator, trace_vector, coupling, wavenumber, impedance, limits)[source]#

Bases: Displayed

The condensed Robin wall generator of a contiguous HE_1m block.

The output of wall_operator(): the dense paraxial generator in the optics convention and in 1/m, together with the factored pieces it was built from and the validity ratios it was checked against. Crossing to the internal FFT convention is the complex conjugate of the whole equation, c' = G c becoming c' = conj(G) c, which is what the translation layer stores; it is not -G, and a passive mode propagated with the wrong one grows (docs/dev/conventions.md section 2, ADR-017).

Attributes:
omeganumpy.ndarray

The angular frequencies in rad/s the block is tabulated on, shape (n_omega,); the whole grid, with the inactive bins left exactly zero.

activenumpy.ndarray

Where the operator was evaluated, bool, shape (n_omega,).

generatornumpy.ndarray

G = D + H in 1/m, complex, shape (n_modes, n_modes, n_omega), in the optics convention with the carrier k removed.

trace_vectornumpy.ndarray

h_m, dimensionless, shape (n_modes,): the radial derivative of the m-th orthonormal basis function at the wall.

couplingnumpy.ndarray

g(a) in 1/m, complex, shape (n_omega,), zero off the active band.

wavenumbernumpy.ndarray

The in-core wavenumber k = n_core omega / c in 1/m, complex, shape (n_omega,), zero off the active band.

impedancenumpy.ndarray

k_eff = k_0 / v_n in 1/m, complex, shape (n_omega,), zero off the active band: the vacuum wavenumber over the current filled-core cladding term, which is what makes the isolated block reproduce this package’s own capillary loss.

limitsWallLimits

The validity ratios over the active band.

n_modesint

How many channels the block couples.

Examples

>>> import numpy as np
>>> from solprop.modes import MarcatiliMode, wall_operator
>>> modes = [MarcatiliMode(125e-6, "He", 1.0, m=index) for index in (1, 2)]
>>> block = wall_operator(modes, np.array([2.356e15]))
>>> block.generator.shape
(2, 2, 1)
>>> bool(block.generator[0, 0, 0].real < 0.0)
True
active: Bool[ndarray, 'n_omega_wall_a']#
coupling: Complex[ndarray, 'n_omega_wall_g2']#
generator: Complex[ndarray, 'n_modes_wall_out n_modes_wall_in n_omega_wall_g']#
impedance: Complex[ndarray, 'n_omega_wall_e']#
limits: WallLimits#
property n_modes: int[source]#

How many channels the block couples.

omega: Float[ndarray, 'n_omega_wall']#
trace_vector: Float[ndarray, 'n_modes_wall_h']#
wavenumber: Complex[ndarray, 'n_omega_wall_k']#
solprop.modes.wall.taper_connection(modes, z=0.0)[source]#

Return the taper connection of an HE_1m block at one position.

The connection \(C_{mn} = \langle\psi_m|\partial_z\psi_n\rangle\) of the field-normalised J_0(u_m r/a) basis, exactly wall_connection()’s scalar block (impedance="mean") – real, antisymmetric, proportional to a'/a – without its two conditions that belong to the wall: it admits any loss and either capillary model, because the basis is the Dirichlet one whatever the modes’ effective index says. It is what the taper coupling carries on a multimode capillary without a wall.

Parameters:
modessequence of Mode

The contiguous HE_11 to HE_1N set in state order, every channel declaring the same radius and density profiles, each with an analytic derivative.

zfloat, optional

Position along the capillary in m.

Returns:
numpy.ndarray

C in 1/m, real, shape (n_modes, n_modes), with a zero diagonal.

Raises:
ModeError

If the set is not such a block.

Examples

>>> import numpy as np
>>> from solprop.modes.capillary import MarcatiliMode
>>> from solprop.modes.wall import taper_connection
>>> from solprop.profiles import Linear
>>> taper = Linear(125e-6, 62.5e-6, 1e-2)
>>> modes = [MarcatiliMode(taper, "He", 1.0, m=m, loss_scale=0.0) for m in (1, 2)]
>>> link = taper_connection(modes, 5e-3)
>>> bool(np.all(link == -link.T)), float(link[0, 0])
(True, 0.0)
solprop.modes.wall.taper_coupling_block(modes)[source]#

Return the mode set the taper coupling is carried on, or None.

The taper coupling – the moving-basis connection <psi_m|d_z psi_n> of taper_connection() in a coupled flow, with each channel’s own propagation constant on the flow’s diagonal – is carried by default on a multimode capillary whose radius varies along z, lossless or not. That is a set of two or more plain MarcatiliMode channels forming the contiguous HE_11 to HE_1N block, whose core radius is not constant. Every other set is None: one channel needs no connection; a constant bore – a pressure gradient included, which changes the effective index and not the J_0(u_m r/a) field – has none; and a structured cladding (a Vincetti mode), a tabulated mode or a set of several azimuthal orders is not the block the connection is derived for, and keeps the adiabatic route with its AdiabaticTaperWarning.

Parameters:
modessequence of Mode

The run’s mode set, in the state’s channel order.

Returns:
tuple of MarcatiliMode or None

The block, or None when the coupling does not apply.

Examples

>>> from solprop.modes.capillary import MarcatiliMode
>>> from solprop.modes.wall import taper_coupling_block
>>> from solprop.profiles import Linear
>>> taper = Linear(125e-6, 62.5e-6, 1e-2)
>>> modes = [MarcatiliMode(taper, "He", 1.0, m=m) for m in (1, 2)]
>>> len(taper_coupling_block(modes))
2
>>> taper_coupling_block([MarcatiliMode(125e-6, "He", 1.0, m=m) for m in (1, 2)])
>>> taper_coupling_block([MarcatiliMode(taper, "He", 1.0, m=m) for m in (1, 3)])
solprop.modes.wall.vector_wall_operator(modes, omega, *, z=0.0, active=None, scored=None, validity_limit=0.25)[source]#

Build the condensed vector Robin wall generator of one azimuthal order.

In outline (the manual page is docs/guide/waveguides/vector-wall.md), three steps.

The boundary response is a matrix, not a scalar. At grazing incidence the wall imposes \(\partial_rE = ik_oE\) on the field tangential to it and \(\partial_rE = i(k_o/n_r^2)E\) on the field normal to it. In the near-Dirichlet regime the condensation is linear in the impedance, so what enters is \(Z = \operatorname{diag}(1/k_{\rm TM}, 1/k_{\rm TE})\) in the \((\hat r,\hat\theta)\) components. Rotating it into the radial families of a total azimuthal order \(\nu\) – the angular quadrature \(Z_{fg} = \int_0^{2\pi}[Z_{rr}P_fP_g + Z_{\theta\theta}Q_fQ_g]\,d\theta\) over the unit-normalised angular patterns of WallFamily.angular – gives, for \(\nu \ge 1\),

\[Z = \bar z\,I + \delta\,\sigma_x,\qquad \bar z = \tfrac12(1/k_{\rm TM} + 1/k_{\rm TE}),\qquad \delta = \tfrac12(1/k_{\rm TM} - 1/k_{\rm TE}),\]

and, for \(\nu = 0\), the same matrix diagonalised: TM sees \(\bar z + \delta\) and TE sees \(\bar z - \delta\), with no coupling at all. The mean \(\bar z\) is exactly the scalar block’s \(1/k_{\rm eff}\), because v_HE is the mean of v_TE and v_TM; the anisotropy \(\delta\) is what the scalar average discards, and it is (n_r^2 - 1)/(n_r^2 + 1) of the mean – 35 % for silica, not a small correction.

The condensation is rank two. Truncating the Mittag-Leffler expansion of the exact recurrence \(qJ_{p+1}(q) = (p - i\eta)J_p(q)\) family by family gives \(T_p(\lambda) \simeq 2N_f + p_f + h_f^{T}(\lambda - D_f)^{-1}h_f\), and the exact two-family secular equation \(\det[\operatorname{diag}(T_{p_A}, T_{p_B}) - iaZ^{-1}] = 0\) is exactly the secular equation of

\[L_N = -\operatorname{diag}(u_m^2) + VSV^{T},\qquad S = (C - i\,aZ^{-1})^{-1},\qquad C = \operatorname{diag}(2N_f + p_f),\]

with V one boundary trace column per family. The truncation constant carries the family’s Bessel order p_f: without it the condensed eigenvalues stop converging to the exact roots. The paraxial reduction of \(M = k^2I + L_N/a^2\) is \(G = i(M - k^2)/(2k)\) in 1/m, as for the scalar block.

What is new beyond two copies of the scalar block. The scalar block is one family with one averaged impedance, and two copies of it for two polarisations are two copies of the same average. This block is per azimuthal order: it gives TE_0m and TM_0m their own impedances, which differ by n_r^2, and it couples the J_{nu-1} and J_{nu+1} families of every order nu >= 1 through \(\delta\), which converts power between them. Each family in isolation still reduces to this package’s own Marcatili loss for its own v_n.

Parameters:
modessequence of Mode

One total azimuthal order of one capillary, in the state’s channel order: either TM_0m and TE_0m sets, or the hybrid n = +nu set followed by the n = -nu one, each contiguous from m = 1. Either family may be retained alone, in which case the block carries no conversion and the report’s single-family loss limits are what it is. Every channel declares the same guide, fill and polarisation angle; anything else is refused by name.

omeganumpy.ndarray

Angular frequencies in rad/s, shape (n_omega,); the whole grid.

zfloat, optional

Position along the capillary in m the block is frozen at.

activenumpy.ndarray or None, optional

Bool mask of the bins to evaluate, shape (n_omega,). None takes every strictly positive frequency; an out-of-band bin is never evaluated.

scorednumpy.ndarray or None, optional

Bool mask of the bins the validity ratios are taken over, as for wall_operator(); None takes every evaluated bin.

validity_limitfloat, optional

Largest admitted validity ratio; above it the block is refused, above a tenth of it it warns. See CoherentWall.

Returns:
VectorWallOperator

The dense optics-convention generator, its factored pieces and its limits.

Raises:
ModeError

If the set is not one azimuthal order of a bare capillary, if a channel declares a loss setting or the reduced model, if the active band is empty, if the block is not passive on the branch the cladding terms land on, or if a validity ratio exceeds validity_limit.

Warns:
GrazingIncidenceWarning

When a validity ratio exceeds a tenth of validity_limit, naming it.

Examples

>>> import numpy as np
>>> from solprop.modes import MarcatiliMode, vector_wall_operator
>>> modes = [MarcatiliMode(125e-6, "He", 1.0, n=n, m=1) for n in (1, -1)]
>>> block = vector_wall_operator(modes, np.array([2.356e15]))
>>> block.sector, [family.label for family in block.families]
(1, ['HE_1m', 'EH_1m'])
>>> bool(abs(block.generator[0, 1, 0]) > 0.0)
True
solprop.modes.wall.wall_connection(modes, z=0.0, *, impedance='mean')[source]#

Return the moving-basis connection of a wall block at one position.

The basis of the condensed wall block is attached to the core radius, so a taper moves it. Writing the field as \(E = \sum_n c_n \psi_n(r; a(z))\) with \(\psi_n = \sqrt2 J_p(u_n r/a)/(a|J_{p+1}(u_n)|)\) orthonormal under \(\int_0^a \cdot\, r\,dr\) at every z, \(u_n\) the zeros of \(J_p\), the coefficients pick up \(c' = (iB - C)c\) with \(C_{mn} = \langle\psi_m|\partial_z\psi_n\rangle\):

\[C_{mn} = \frac{a'}{a}\,\frac{2s_ms_nu_mu_n}{u_m^2-u_n^2}\quad(m\ne n), \qquad C_{nn} = 0,\]

with \(s_m = \operatorname{sgn}J_{p+1}(u_m)\) the sign of the basis slope at the wall, \(-J_p'(u_m) = J_{p+1}(u_m)\). For the HE_1m block p = 0 and this is the scalar block’s formula. It is real – so the optics/internal conjugation of docs/dev/conventions.md section 2 leaves it alone – and antisymmetric, because swapping the indices flips the denominator alone, so the connection on its own is norm preserving and moves no power out of the retained set. The sign is checked by differentiating the implemented profile (tests/modes/test_wall_operator.py), not asserted.

The vector block (impedance="te_tm") is one total azimuthal order with at most two radial families, and its connection is block diagonal: each family carries the formula above with its own Bessel order p_f (WallFamily.bessel_order), zeros and signs, and the two families do not connect at all. The reason is exact rather than small: a taper moves the radius and nothing else, and every channel’s field is its radial function of r/a times an angular pattern that does not depend on a, so \(\langle\psi^A_m|\partial_z\psi^B_n\rangle\) is a radial integral times the angular overlap of the two families’ patterns, which is zero – the two hybrid families of an order nu >= 1 overlap as \(\cos 2\nu\theta\), and TE_0m and TM_0m are orthogonal at every point. A family’s implemented sign (WallFamily.radial_sign) enters \(s_m s_n\) squared and cancels. Both statements are measured on the implemented fields, not assumed.

The whole matrix scales with a'(z)/a(z), and nothing in it depends on frequency: the basis is the same set of Bessel orders at every bin.

Parameters:
modessequence of Mode

The block in the state’s channel order: the contiguous HE_11 to HE_1N set for impedance="mean", one azimuthal order of a capillary for "te_tm". Refused by name on exactly the conditions wall_operator() and vector_wall_operator() refuse.

zfloat, optional

Position along the capillary in m.

impedancestr, optional

Which block the connection is of, "mean" or "te_tm", as CoherentWall.impedance.

Returns:
numpy.ndarray

C in 1/m, real, shape (n_modes, n_modes), with a zero diagonal.

Examples

>>> import numpy as np
>>> from solprop.modes.capillary import MarcatiliMode
>>> from solprop.modes.wall import wall_connection
>>> from solprop.profiles import Linear
>>> taper = Linear(125e-6, 62.5e-6, 1e-2)
>>> modes = [MarcatiliMode(taper, "He", 1.0, m=index) for index in (1, 2)]
>>> link = wall_connection(modes, 5e-3)
>>> bool(np.all(link == -link.T)), float(link[0, 0])
(True, 0.0)
>>> vector = [MarcatiliMode(taper, "He", 1.0, n=n, m=1) for n in (1, -1)]
>>> float(wall_connection(vector, 5e-3, impedance="te_tm")[0, 1])
0.0
solprop.modes.wall.wall_operator(modes, omega, *, z=0.0, active=None, scored=None, validity_limit=0.25)[source]#

Build the condensed Robin wall generator of a contiguous HE_1m block.

In outline (the manual page is docs/guide/waveguides/coherent-wall.md), the orthonormal radial basis is \(\phi_m(x) = \sqrt2 J_0(u_m x)/|J_1(u_m)|\) on \(x = r/a\), whose derivative at the wall is \(h_m = -\sqrt2\,\operatorname{sgn}J_1(u_m)\,u_m\). Truncating the Mittag-Leffler expansion of the exact outgoing root equation \(qJ_1(q) + i\eta J_0(q) = 0\) at N orders and eliminating the boundary coordinate gives the condensed transverse operator \(L_N = -\operatorname{diag}(u_m^2) + hh^{T}/(2N - i\eta)\), and the paraxial reduction of \(M = k^2I + L_N/a^2\) about the in-core carrier is \(G = i(M - k^2)/(2k) = D + H\) in 1/m.

Two normalisations are re-derived here rather than assumed. The amplitude map is the identity up to one mode-independent positive scale: this package’s internal amplitude is a_m = E_m sqrt(N_m) with N_m = (pi/2) a^2 J_1(u_m)^2 eps_0 c (docs/dev/conventions.md section 4), and both that normalisation and the orthonormal basis above carry the same |J_1(u_m)|, so the two sets of coordinates differ by a sqrt(pi eps_0 c) for every channel alike and the generator is unchanged by the map. The impedance is k_eff = k_0 / v_n, the vacuum wavenumber over the cladding term this package’s own capillary index already uses, because that is the combination whose N = 1 limit is this package’s Marcatili transverse eigenvalue; the carrier k of the paraxial reduction is the in-core wavenumber. Referring the impedance to the core instead is identical for a vacuum core and differs at the order of half the gas susceptibility for a filled one.

Parameters:
modessequence of Mode

The contiguous block HE_11 to HE_1N, in the state’s channel order, sharing one polarisation angle, one capillary and one constant section. Anything else is refused by name.

omeganumpy.ndarray

Angular frequencies in rad/s, shape (n_omega,); the whole grid.

zfloat, optional

Position along the capillary in m the block is frozen at.

activenumpy.ndarray or None, optional

Bool mask of the bins to evaluate, shape (n_omega,). None takes every strictly positive frequency. An empty out-of-band bin is never evaluated: the wall formula divides by omega and its validity ratios are meaningless there, so the generator is left exactly zero.

scorednumpy.ndarray or None, optional

Bool mask of the bins the validity ratios are taken over, shape (n_omega,), intersected with the evaluated bins; a run passes the error norm’s scored band (solprop.grid.TimeGrid.inband_mask), so the absorbed collar a field grid adds below the requested band, at up to twice the longest requested wavelength, neither refuses nor warns. The generator is still built on every evaluated bin. None, or a mask that holds no evaluated bin, takes the ratios over every evaluated bin.

validity_limitfloat, optional

Largest admitted validity ratio; above it the block is refused, above a tenth of it it warns. See CoherentWall.

Returns:
WallOperator

The dense optics-convention generator, its factored pieces and its limits.

Raises:
ModeError

If the set is not one contiguous scalar block, if a channel declares a loss setting or the reduced model, if the active band is empty or holds a non-positive frequency, if the block is not passive on the branch the cladding term lands on, or if a validity ratio exceeds validity_limit.

Warns:
GrazingIncidenceWarning

When a validity ratio exceeds a tenth of validity_limit, naming it.

Examples

>>> import numpy as np
>>> from solprop.modes import MarcatiliMode, wall_operator
>>> modes = [MarcatiliMode(125e-6, "He", 1.0, m=index) for index in (1, 2, 3)]
>>> block = wall_operator(modes, np.array([2.356e15]))
>>> block.n_modes, f"{block.limits.worst:.4f}"
(3, '0.0090')
solprop.modes.wall.wall_square_root_metric(generator, wavenumber)[source]#

Return the square-root generator and its candidate flux metric, as a diagnostic.

For a constant, real, positive carrier k, the square-root model c' = iBc with B^2 = M = k^2 I - 2ikG satisfies

\[\frac{d}{dz}\left(c^\dagger W c\right) = -c^\dagger\frac{M - M^\dagger}{2ik}c,\qquad W = \frac{B + B^\dagger}{2k},\]

which is the flux balance of this scalar model. Its domain is exactly that statement. Production semantics are the paraxial generator, not this square root; W is positive semidefinite only when the Hermitian part of B is, which positive eigenvalues of B do not establish, and which the principal branch does not establish either; a complex k, an evanescent sector, a varying cross-section – which adds W' – and a varying k all fall outside it. Use it to measure the identity, not to define an error norm or to transport noise.

Parameters:
generatornumpy.ndarray

The optics-convention paraxial generator at one frequency in 1/m, complex, shape (n_modes, n_modes).

wavenumberfloat

The carrier k in 1/m, real and positive.

Returns:
tuple of numpy.ndarray

B in 1/m on the principal branch, and the dimensionless W.

Raises:
ModeError

If the carrier is not real, finite and positive.

Examples

>>> import numpy as np
>>> from solprop.modes import MarcatiliMode, wall_operator
>>> from solprop.modes.wall import wall_square_root_metric
>>> modes = [MarcatiliMode(125e-6, "He", 1.0, m=index) for index in (1, 2)]
>>> block = wall_operator(modes, np.array([2.356e15]))
>>> k = float(block.wavenumber[0].real)
>>> root, metric = wall_square_root_metric(block.generator[:, :, 0], k)
>>> bool(np.max(abs(root @ root - (k**2 * np.eye(2)
...      - 2j * k * block.generator[:, :, 0]))) < 1e-6 * k**2)
True
solprop.modes.wall.worst_wall_limits(modes, omega, *, positions, active=None, scored=None, validity_limit=0.25, impedance='mean')[source]#

Return the validity ratios at the position where they are worst.

A guide that varies along z has a different block at every section, and the three ratios of WallLimits are not monotone in the declared parameters in general – the radius, the fill’s index and the cladding term all enter them. The scan is therefore over the positions the caller actually builds the flow from, and the one call that carries the caller’s validity_limit is the one at the worst of them, so a run is refused or warned about once and names the geometry that did it rather than the entrance’s.

Parameters:
modessequence of Mode

The contiguous block HE_11 to HE_1N, in the state’s channel order.

omeganumpy.ndarray

Angular frequencies in rad/s, shape (n_omega,); the whole grid.

positionssequence of float

Positions in m to scan, non-empty.

activenumpy.ndarray or None, optional

Bool mask of the bins to evaluate, shape (n_omega,).

scorednumpy.ndarray or None, optional

Bool mask of the bins the ratios are taken over, shape (n_omega,) (wall_operator()); None takes every evaluated bin.

validity_limitfloat, optional

Largest admitted validity ratio, applied at the worst position alone.

impedancestr, optional

Which block to build, "mean" (wall_operator()) or "te_tm" (vector_wall_operator()). The scan is the same either way.

Returns:
WallLimits

The ratios at that position.

Raises:
ModeError

If positions is empty, or on everything the block’s own constructor refuses.

Warns:
GrazingIncidenceWarning

Once, from the worst position, when a ratio exceeds a tenth of the limit.

Examples

>>> import numpy as np
>>> from solprop.modes.capillary import MarcatiliMode
>>> from solprop.modes.wall import worst_wall_limits
>>> from solprop.profiles import Linear
>>> taper = Linear(125e-6, 100e-6, 1e-2)
>>> modes = [MarcatiliMode(taper, "He", 1.0, m=index) for index in (1, 2)]
>>> limits = worst_wall_limits(
...     modes, np.array([2.356e15]), positions=[0.0, 5e-3, 1e-2]
... )
>>> f"{limits.radius * 1e6:.1f} um"
'100.0 um'