solprop.translate.envelope_plasma#

Compile validated cycle integrals and the envelope plasma spectral assembly.

Only numeric, read-only data cross into a backend. Density and population histories are not part of the cycle cache; they are evaluated afresh for every RHS input.

Functions

`assembly_record`(assembly, omega)	Describe the physical approximation and numerical source representation.
`build_cycle_integrals`(response, field_range)	Build and independently validate the accepted cycle representation.
`cycle_moments`(major, ratio, cycle)	Evaluate both accepted directional moments with explicit refinement failure.
`source_factors`(grid, *, shock)	Compile inverse-frequency factors only on the positive supported band.

Classes

`AngularRule`(nodes, weights)	Hold one Gauss-Legendre rule on the dimensionless interval [-1, 1].
`CycleIntegralData`(rate, rules, validation, ...)	Hold an instantaneous rate table and its validated angular rules.
`CycleValidation`(probes, residuals, cutoff_rate)	Record independent off-knot validation of a cycle representation.
`EnvelopePlasmaAssembly`(channels, factors)	Declare the independent currents and their final spectral assembly.
`EnvelopePlasmaChannel`(label, ...[, ...])	Bind one independent envelope population to compiled material data.
`EnvelopeSourceFactors`(active, drude, loss, ...)	Own the coarse-axis internal-FFT plasma multipliers.

class solprop.translate.envelope_plasma.AngularRule(nodes, weights)[source]#

Bases: object

Hold one Gauss-Legendre rule on the dimensionless interval [-1, 1].

Attributes:

nodes, weightsnumpy.ndarray: Finite, read-only vectors of equal length, with positive weights.

nodes: Float[ndarray, 'n_nodes']#

weights: Float[ndarray, 'n_weights']#

class solprop.translate.envelope_plasma.CycleIntegralData(rate, rules, validation, identity, moment_rtol=2e-06, negligible_rate=1e-30)[source]#

Bases: object

Hold an instantaneous rate table and its validated angular rules.

Attributes:

rateRateTable: Read-only instantaneous-isotropic magnitude rate.
rulestuple of AngularRule: Rules of orders 64, 128, 256 and 512, in refinement order.
validationCycleValidation: Independent Cartesian oracle evidence on off-knot probes.
identitystr: Digest including the rate, conventions, rules, budgets and probe version.
moment_rtolfloat: Relative budget for each positive directional moment, fixed at 2e-6.
negligible_ratefloat: Comparison denominator floor in s^-1, fixed at 1e-30.

identity: str#

moment_rtol: float = 2e-06#

negligible_rate: float = 1e-30#

rate: RateTable#

rules: tuple[AngularRule, ...]#

validation: CycleValidation#

class solprop.translate.envelope_plasma.CycleValidation(probes, residuals, cutoff_rate, format_version=1)[source]#

Bases: object

Record independent off-knot validation of a cycle representation.

Attributes:

probesnumpy.ndarray: Major amplitude in V/m and minor/major ratio, shape (n_probe, 2).
residualsnumpy.ndarray: Relative errors in the mean rate and both directional moments, shape (n_probe, 3). The denominator floor is negligible_rate.
cutoff_ratefloat: Source rate in s^-1 at the table’s lower cutoff, recorded separately from interpolation error. For an explicitly supplied table, zero denotes that table’s own exactly-zero discarded domain.
format_versionint: Probe and representation version, used by the cache identity.

cutoff_rate: float#

format_version: int = 1#

probes: Float[ndarray, 'n_probe n_coordinates']#

residuals: Float[ndarray, 'n_residual n_quantities']#

class solprop.translate.envelope_plasma.EnvelopePlasmaAssembly(channels, factors)[source]#

Bases: object

Declare the independent currents and their final spectral assembly.

Attributes:

channelstuple of EnvelopePlasmaChannel: Unique labelled populations in material order.
factorsEnvelopeSourceFactors: Multipliers applied after projection, temporal FFT and coarse cropping. Ordinary polarisation is summed only at this spectral assembly point.

channels: tuple[EnvelopePlasmaChannel, ...]#

factors: EnvelopeSourceFactors#

class solprop.translate.envelope_plasma.EnvelopePlasmaChannel(label, species_identity, ionisation_potential, density, preionisation, cycle, charge_mass_ratio=2.8179403208349128e-08, electrons_per_event=1)[source]#

Bases: object

Bind one independent envelope population to compiled material data.

Attributes:

labelstr: Unique component label.
species_identitystr: Chemical species identity for provenance.
ionisation_potentialfloat: First ionisation potential in J, positive.
charge_mass_ratiofloat: Compiled e²/m_e in C²/kg, positive.
density, preionisationPiecewiseChebyshev: Particle density in m^-3 and initial ionised fraction along z.
cycleCycleIntegralData: Validated cycle-integral representation.
electrons_per_eventint: Exactly one; sequential charge states are outside this model.

charge_mass_ratio: float = 2.8179403208349128e-08#

cycle: CycleIntegralData#

density: PiecewiseChebyshev#

electrons_per_event: int = 1#

ionisation_potential: float#

label: str#

preionisation: PiecewiseChebyshev#

property rate: RateTable[source]#

Return the instantaneous magnitude table carried by this channel.

Returns:

RateTable: The table used inside the cycle integral, not an averaged rate.

species_identity: str#

class solprop.translate.envelope_plasma.EnvelopeSourceFactors(active, drude, loss, carrier_policy, omega0)[source]#

Bases: object

Own the coarse-axis internal-FFT plasma multipliers.

Attributes:

activenumpy.ndarray: Supported positive absolute-frequency mask, shape (n_omega,).
drudenumpy.ndarray: -1/omega², in s², zero outside the mask.
lossnumpy.ndarray: -i/omega, in s, zero outside the mask.
carrier_policystr: 'absolute-frequency' or the warned 'frozen-carrier' approximation.
omega0float: Positive carrier angular frequency in rad/s.

active: Bool[ndarray, 'n_active']#

carrier_policy: Literal['absolute-frequency', 'frozen-carrier']#

drude: Float[ndarray, 'n_drude']#

loss: Complex[ndarray, 'n_loss']#

omega0: float#

solprop.translate.envelope_plasma.assembly_record(assembly, omega)[source]#

Describe the physical approximation and numerical source representation.

Parameters:

assemblyEnvelopePlasmaAssembly: Compiled channels and masked frequency factors.
omeganumpy.ndarray: Absolute coarse frequencies in rad/s.

Returns:

dict: Additive configuration/provenance data, independent of output layouts. No time-dependent population state is serialised here.

solprop.translate.envelope_plasma.build_cycle_integrals(response, field_range)[source]#

Build and independently validate the accepted cycle representation.

Parameters:

responseEnvelopePlasmaResponse: Species-bound explicitly instantaneous magnitude rate.
field_rangetuple of float or None: Intended amplitude domain in V/m. The table begins at the model’s own threshold, even when the requested domain begins higher. A supplied RateTable states its own domain and requires None.

Returns:

CycleIntegralData: Cached immutable rate and rule data, with off-knot Cartesian evidence.

Raises:

TranslationError: If the model cannot be tabulated or its domain is not declared.
ConvergenceError: If angular refinement or independent validation fails.

solprop.translate.envelope_plasma.cycle_moments(major, ratio, cycle)[source]#

Evaluate both accepted directional moments with explicit refinement failure.

Parameters:

majorfloat: Finite non-negative major-axis field amplitude in V/m.
ratiofloat: Finite minor/major amplitude ratio in [0, 1].
cycleCycleIntegralData: Validated numeric cycle representation.

Returns:

numpy.ndarray: Cosine and sine moments in s^-1. Their combination Mc + ratio² Ms is the cycle-averaged rate.

Raises:

TranslationError: If the amplitude or ratio is invalid.
ConvergenceError: If either moment fails to converge by the 512-point rule.

solprop.translate.envelope_plasma.source_factors(grid, *, shock)[source]#

Compile inverse-frequency factors only on the positive supported band.

Parameters:

gridEnvelopeGrid: Coarse spectral axis, containing absolute angular frequencies in rad/s.
shockbool: Use the frequency-dependent factors; false freezes them at the carrier. Translation also freezes the explicit UPPE numerator under this policy.

Returns:

EnvelopeSourceFactors: Finite read-only internal-FFT factors and their active mask.

Warns:

SolpropWarning: Once per call when shock=False selects the carrier approximation.