solprop.adiabatic#
Certify adiabatic forward transport through a real index that varies along z.
A radial or Cartesian spectral column propagates with the real longitudinal wave number
\(q(z) = \operatorname{Re}k_z\), and the forward-only model drops its coupling to
the backward wave. For a positive real q of bounded variation over the run path, the
exact scalar problem bounds what that drops (SEP 34, section 4.5): with
\(\Lambda = \tfrac12\operatorname{TV}(\ln q)\), kinks and declared jumps alike, the
reflected power is at most \(R_* = \tanh^2\Lambda\) (reflection_bound()) and
the relative error of the retained forward field at most
\(\delta_* = \operatorname{expm1}(\Lambda\tanh\Lambda)\)
(field_error_bound()). The bound is for the linear background problem only.
AdiabaticAccuracyholds the two budgets every propagating column of the active band must meet over the whole path.certify_wave_path()andcertify_radial_path()certify a path without sampling it: the wave-number square is affine in the number densities, so the variation is enclosed piece by piece from each density’ssolprop.profiles.PathVariation, with the arithmetic error bounded.AdiabaticAdmissionis the resulting certificate, kept with a run’s output as plain values byadmission_record()and read back byadmission_from_record().
The bound, the refusals and the enclosure are in docs/guide/free-space/flux.md,
section “The adiabatic certificate”.
Functions
|
Rebuild a varying path's certificate from its output record. |
|
Return a path certificate as plain values, for a record that outlives the run. |
|
Certify a spatial medium's z-varying path for every column of a radial grid. |
|
Certify the columns of a material whose wave-number square is affine in z. |
|
Return the forward-field error bound |
|
Return the reflected-power bound |
Classes
|
The budgets a z-varying path must meet to use adiabatic forward transport. |
|
The record that a path met its adiabatic budgets. |
- class solprop.adiabatic.AdiabaticAccuracy(field_error=0.0001, reflected_energy=0.0001)[source]#
Bases:
objectThe budgets a z-varying path must meet to use adiabatic forward transport.
These are model budgets chosen by the maintainer, not physical constants or integrator tolerances. Callers may tighten them.
- Attributes:
- field_errorfloat
Largest certified relative error of the retained forward field,
expm1(Lambda tanh Lambda), finite and positive. Default 1e-4.- reflected_energyfloat
Largest certified reflected fraction of the power,
tanh(Lambda)**2, finite and positive. Default 1e-4.
- Raises:
- MaterialError
If a budget is not finite and positive.
Examples
>>> from solprop.adiabatic import AdiabaticAccuracy >>> AdiabaticAccuracy().field_error 0.0001
- class solprop.adiabatic.AdiabaticAdmission(identity, z_span, accuracy, variation, reflection, field_error, worst_kperp_sq, worst_omega, omega, spectral_variation, support, jumps, exact=True, interpolation_envelope=0.0)[source]#
Bases:
objectThe record that a path met its adiabatic budgets.
- Attributes:
- identitycollections.abc.Mapping
The represented material path: the material and each density path’s structural identity (
Nonefor a custom path, which has none).- z_spantuple of float
The certified run path
(z0, z1)in m.- accuracyAdiabaticAccuracy
The budgets met.
- variationfloat
The largest enclosed
Lambdaover the propagating columns.- reflectionfloat
tanh(variation)**2, the largest reflected-power bound.- field_errorfloat
expm1(variation tanh variation), the largest forward-field bound.- worst_kperp_sqfloat or None
Transverse wave-number square in m^-2 of the column attaining variation;
Nonewhen no column varies.- worst_omegafloat or None
Its angular frequency in rad/s.
- omeganumpy.ndarray
The certified angular frequencies in rad/s, shape
(n_omega,).- spectral_variationnumpy.ndarray
The largest
Lambdaover the propagating columns at each frequency, zero where none propagates, shape(n_omega,).- supportnumpy.ndarray
Which columns propagate over the whole path, shape
(n_modes, n_omega); the others are nonpropagating everywhere.- jumpsnumpy.ndarray
Declared jumps of the material inside the path, in m.
- exactbool
Whether every piece was certified monotone, so that
variationis the attained value up to rounding rather than an upper bound.- interpolation_envelopefloat
Relative error of the run’s tabulated operator against the represented path, a separate envelope from the certificate’s bounds (SEP 34 section 4.5); zero when no table stands between them.
- accuracy: AdiabaticAccuracy#
- jumps: Float[ndarray, 'n_jumps']#
- omega: Float[ndarray, 'n_omega']#
- spectral_variation: Float[ndarray, 'n_omega']#
- support: Bool[ndarray, 'n_modes n_omega']#
- solprop.adiabatic.admission_from_record(record)[source]#
Rebuild a varying path’s certificate from its output record.
The inverse of
admission_record(). The path’s structural identity is kept as the text it was recorded as.- Parameters:
- recordcollections.abc.Mapping
The
admissionentry of aflux_planrecord, as held in memory or as read back from a file.
- Returns:
- AdiabaticAdmission
The certificate.
- solprop.adiabatic.admission_record(admission)[source]#
Return a path certificate as plain values, for a record that outlives the run.
The certificate’s scope is the linear background’s forward coordinates, not the nonlinear run or an omitted reflected field (SEP 34 section 4.5). Its path identity is kept as text, and a certificate already read from a record keeps that text.
- Parameters:
- admissionsolprop.adiabatic.AdiabaticAdmission
The certificate.
- Returns:
- dict
The values
admission_from_record()rebuilds it from.
- solprop.adiabatic.certify_radial_path(dispersion, kperp_sq, z_span, accuracy=None)[source]#
Certify a spatial medium’s z-varying path for every column of a radial grid.
- Parameters:
- dispersionsolprop.spatial.SpatialDispersion
The medium and the temporal grid, whose active band is certified.
- kperp_sqnumpy.ndarray
Transverse wave-number squares in m^-2, for a radial grid
k_r**2.- z_spantuple of float
The run path
(z0, z1)in m.- accuracyAdiabaticAccuracy or None, optional
The budgets;
Nonetakes the defaults.
- Returns:
- AdiabaticAdmission
The record of a path within budget; a uniform medium is admitted with zero variation.
- Raises:
- MaterialError
- solprop.adiabatic.certify_wave_path(omega, permittivity, susceptibilities, paths, kperp_sq, z_span, accuracy=None, *, identity=None)[source]#
Certify the columns of a material whose wave-number square is affine in z.
The longitudinal square of every column is \(s = (\omega/c)^2(\varepsilon + \sum_i\rho_i(z)\chi_i) - k_\perp^2\) (
docs/guide/free-space/flux.mdgives the enclosure).- Parameters:
- omeganumpy.ndarray
Finite positive angular frequencies in rad/s, shape
(n_omega,).- permittivitynumpy.ndarray
The constant part
epsilonof the relative permittivity, shape(n_omega,).- susceptibilitiesnumpy.ndarray
Per-density susceptibility
chi_i, in the inverse unit of the paths, shape(n_paths, n_omega).- pathssequence of ZProfile
The densities
rho_i(z); each must enclose its variation.- kperp_sqnumpy.ndarray
Transverse wave-number squares in m^-2, finite and nonnegative, shape
(n_modes,).- z_spantuple of float
The run path
(z0, z1)in m, finite withz0 < z1.- accuracyAdiabaticAccuracy or None, optional
The budgets;
Nonetakes the defaults.- identitycollections.abc.Mapping or None, optional
The represented path’s identity, recorded in the admission.
- Returns:
- AdiabaticAdmission
The record of a path within budget.
- Raises:
- MaterialError
If a budget is exceeded (naming the worst column, its frequency and the bound), a column crosses
q = 0over the path, the imaginary index varies, a path cannot enclose its variation, or an input is invalid.
Examples
>>> import numpy as np >>> from solprop.adiabatic import certify_wave_path >>> from solprop.profiles import Linear >>> omega = np.array([2.35e15]) >>> admission = certify_wave_path( ... omega, np.ones(1), np.array([[1e-3]]), [Linear(0.0, 1.0, 1e-3)], ... np.zeros(1), (0.0, 1e-3)) >>> f"{admission.variation:.6e}" '2.498751e-04'
- solprop.adiabatic.field_error_bound(variation)[source]#
Return the forward-field error bound
expm1(Lambda tanh Lambda).- Parameters:
- variationfloat or numpy.ndarray
Lambda, half the total variation ofln q, nonnegative.
- Returns:
- float or numpy.ndarray
The relative complex error bound of the retained forward field.
Examples
>>> from solprop.adiabatic import field_error_bound >>> float(field_error_bound(1e-9)) 1e-18
- solprop.adiabatic.reflection_bound(variation)[source]#
Return the reflected-power bound
tanh(Lambda)**2.- Parameters:
- variationfloat or numpy.ndarray
Lambda, half the total variation ofln q, nonnegative.
- Returns:
- float or numpy.ndarray
The bound;
tanhis accurate to a few ulps for tiny arguments.
Examples
>>> from solprop.adiabatic import reflection_bound >>> float(reflection_bound(1e-9)) 1e-18