solprop.backends.numpy_ref.passes.plasma#

The plasma passes: ionisation rates, populations and the plasma currents.

The field grid’s plasma, the ionisation_rate, plasma_scan and plasma_current stages of responses.response_order: ionisation_rate() looks the rate up on the field’s magnitude, plasma_scan() integrates the ionised fraction and the free current along t, and plasma_total_current() adds the loss current; plasma_channel_fractions() and plasma_channels_current() are the same for independent channels. held_plasma_spectrum() turns a current held at the temporal collar into its polarisation spectrum (SEP 27). plasma_current() and plasma_channels_polarisation() integrate to the time-domain polarisation, the oracle form, and plasma_integration_diagnostics() measures the running integral (SEP 18). The envelope grid’s plasma is cycle-averaged: envelope_sources() and envelope_populations() split each sample’s complex envelope into its polarisation ellipse by an SVD, read the cycle moments of the rate (solprop.translate.envelope_plasma.cycle_moments()) and integrate the exposure by the trapezoid.

Functions

envelope_populations(field_t, assembly, ...)

Recompute each node's final population and peak cycle-averaged rate.

envelope_sources(field_t, assembly, scalars, ...)

Form two windowed sources from independently recomputed channel populations.

held_plasma_spectrum(gated, edge, omega, ...)

Transform a current held at the temporal collar (SEP 27 section 4.4).

ionisation_rate(field_t, table)

Look the ionisation rate up on the magnitude of the field.

plasma_channel_fractions(field_t, channels, ...)

Evaluate independent exposure scans in channel order.

plasma_channels_current(field_t, channels, ...)

Return every channel's free and loss current, summed, before the last integral.

plasma_channels_polarisation(field_t, ...[, ...])

Sum channel weights before the two shared current integrals.

plasma_current(field_t, rate, fraction, ...)

Add the ionisation loss to the free current and integrate to a polarisation.

plasma_integration_diagnostics(field_t, ...)

Return the parts of the column's integration diagnostics (SEP 18).

plasma_integration_statistics(parts)

Form the three diagnostics from plasma_integration_diagnostics()'s parts.

plasma_scan(field_t, rate, coefficients, *, ...)

Integrate the ionised fraction and the free-electron current along t.

plasma_total_current(field_t, rate, ...)

Add the guarded loss current to the free current, per unit density.

solprop.backends.numpy_ref.passes.plasma.envelope_populations(field_t, assembly, initials, dt)[source]#

Recompute each node’s final population and peak cycle-averaged rate.

Parameters:
field_tnumpy.ndarray

Physical V/m envelopes, shape (n_nodes, n_pol, n_to).

assemblyEnvelopePlasmaAssembly

Compiled channels in population order.

initialstuple of float

Initial fractions at this position in channel order.

dtfloat

Fine time spacing in s.

Returns:
tuple of numpy.ndarray

Final fractions and peak cycle-averaged rates in s^-1, both shaped (n_channels, n_nodes). Every call scans the supplied field afresh.

solprop.backends.numpy_ref.passes.plasma.envelope_sources(field_t, assembly, scalars, dt, window)[source]#

Form two windowed sources from independently recomputed channel populations.

Parameters:
field_tnumpy.ndarray

Physical complex V/m envelope, shape (n_nodes, n_pol, n_to).

assemblyEnvelopePlasmaAssembly

Labelled channels and validated cycle data.

scalarsStageScalars

Density and pre-ionisation at this RHS position in channel order.

dtfloat

Fine time spacing in s.

windownumpy.ndarray

Material-source collar, shape (n_to,).

Returns:
tuple of numpy.ndarray

Drude drive in A m^-2 s^-1 and loss current in A m^-2, each with the field’s shape. Projection and temporal FFT follow this function.

solprop.backends.numpy_ref.passes.plasma.held_plasma_spectrum(gated, edge, omega, crop_index, active)[source]#

Transform a current held at the temporal collar (SEP 27 section 4.4).

Form DFT[g J]/(i omega) - DFT[g' J]/(i omega)^2 only on active bins. Projection can precede or follow this linear map; crop and amplitude factors belong to the route. No running integral or numerical derivative enters it.

Parameters:
gated, edgenumpy.ndarray

Sampled g J and g' J, in A/m^2 and A/(m^2 s), with time last.

omeganumpy.ndarray

Coarse angular frequencies in rad/s, shape (n_omega,).

crop_indexnumpy.ndarray

Coarse positions in the fine half-spectrum, shape (n_omega,).

activenumpy.ndarray

Active frequency mask, shape (n_omega,); all selected frequencies positive.

Returns:
numpy.ndarray

Polarisation-equivalent spectrum in raw DFT units, with inactive bins zero.

solprop.backends.numpy_ref.passes.plasma.ionisation_rate(field_t, table)[source]#

Look the ionisation rate up on the magnitude of the field.

The intensity and ionisation_rate stages of the fused pass, together: the magnitude is what the intensity stage forms and the only thing the rate needs. For one component that is |E|; for two it is hypot(E_x, E_y) rather than sqrt(E_x^2 + E_y^2), because the tunnelling exponent is tens to hundreds and turns one unit in the last place of the magnitude into 1e-13 of the rate (solprop.nonlinear.responses.PlasmaResponse.evaluate() takes the same route).

The table is exactly zero below its field_min and holds its last value above field_max rather than extrapolating, which is what keeps the loss current of plasma_current() finite and a diverged step from becoming an infinity.

Parameters:
field_tnumpy.ndarray

The real field at the chunk’s nodes, shape (n_nodes_chunk, n_pol, n_to), in V/m.

tablesolprop.translate.ionisation.RateTable

The compiled rate, responses.plasma_coefficients.rate.

Returns:
numpy.ndarray

The rate per atom in s^-1, shape (n_nodes_chunk, n_to), finite and non-negative.

Examples

>>> import numpy as np
>>> from solprop.backends.numpy_ref.passes.plasma import ionisation_rate
>>> from solprop.nonlinear.optmat_rates import OptmatRate
>>> from solprop.translate.ionisation import build_rate_table
>>> table = build_rate_table(OptmatRate("He", 800e-9), (2e9, 1e11), rtol=1e-4)
>>> field = np.array([[[5e10, 1e6]]])
>>> np.round(np.log10(ionisation_rate(field, table)[0, 0]), 3).item()
11.207
solprop.backends.numpy_ref.passes.plasma.plasma_channel_fractions(field_t, channels, preionisation, dt, integral=None)[source]#

Evaluate independent exposure scans in channel order.

Parameters:
field_tnumpy.ndarray

Real node fields in V/m, shape (n_nodes_chunk, n_pol, n_to).

channelstuple of PlasmaChannel

The independent rate tables and population metadata.

preionisationtuple of float

Initial fractions, in channel order, in [0, 1].

dtfloat

Fine-grid sample spacing in s.

integralsolprop.nonlinear.ionisation.RunningIntegral or None, optional

The running-integral rule; None is the trapezoid.

Returns:
ratesnumpy.ndarray

Instantaneous rates in s^-1, shape (n_channels, n_nodes_chunk, n_to).

fractionsnumpy.ndarray

Ionised fractions with the same shape, dimensionless.

Raises:
BackendError

If the channel scalars do not match their declared count.

solprop.backends.numpy_ref.passes.plasma.plasma_channels_current(field_t, channels, densities, preionisation, dt, integral=None)[source]#

Return every channel’s free and loss current, summed, before the last integral.

The integrand of plasma_channels_polarisation(), and what a stage holds at the collar: the free current is the one shared integral of the weighted field, the loss current is pointwise.

Parameters:
field_tnumpy.ndarray

Real node fields in V/m, shape (n_nodes_chunk, n_pol, n_to).

channelstuple of PlasmaChannel

Ordered independent channel coefficients.

densitiestuple of float

Number density of each population in m^-3.

preionisationtuple of float

Initial fraction of each population, dimensionless in [0, 1].

dtfloat

Fine-grid sample spacing in s.

integralsolprop.nonlinear.ionisation.RunningIntegral or None, optional

The running-integral rule shared by every channel; None is the trapezoid.

Returns:
numpy.ndarray

The total plasma current density in A/m^2, with the field’s shape.

Raises:
BackendError

If there is not one density per channel.

solprop.backends.numpy_ref.passes.plasma.plasma_channels_polarisation(field_t, channels, densities, preionisation, dt, *, integral=None)[source]#

Sum channel weights before the two shared current integrals.

Each fraction has its own exposure scan (plasma_channel_fractions()). The free-current weight is sum rho_c f_c e_c^2/m_c (times each channel’s electrons per event); the loss numerator is sum rho_c I_p,c W_c (1-f_c), divided by |E|^2 and directed along the field as in plasma_current(). The densities are inside the sums, where the one-channel pass keeps its density outside the integrals.

Parameters:
field_tnumpy.ndarray

Real node fields in V/m, shape (n_nodes_chunk, n_pol, n_to).

channelstuple of PlasmaChannel

Ordered independent channel coefficients.

densitiestuple of float

Number density of each population in m^-3.

preionisationtuple of float

Initial fraction of each population, dimensionless in [0, 1].

dtfloat

Fine-grid sample spacing in s.

integralsolprop.nonlinear.ionisation.RunningIntegral or None, optional

The running-integral rule shared by every channel; None is the trapezoid.

Returns:
numpy.ndarray

Plasma polarisation in C/m², with the field shape.

Raises:
BackendError

If there is not one density per channel.

solprop.backends.numpy_ref.passes.plasma.plasma_current(field_t, rate, fraction, free_current, coefficients, *, density, dt, integral=None)[source]#

Add the ionisation loss to the free current and integrate to a polarisation.

The plasma_current stage, and the third cumulative integral. J_loss = I_p W (1 - f) E / |E|^2 is added pointwise; its form is fixed by E . J_loss = I_p W (1 - f) = I_p df/dt, so the field pays exactly one ionisation potential for every electron it frees. For one component it is I_p W (1-f)/E, sign and all; for two it is that magnitude directed along the field, which is what makes a linearly polarised pulse give the scalar answer rotated. The polarisation is P = rho int (J_free + J_loss) dt.

The division is written with a where mask rather than a branch, as the oracle writes it, so it never happens at a sample where the rate or the field vanishes: the term is finite only because the rate is exactly zero below threshold, which is what solprop.translate.ionisation.RateTable guarantees below its field_min; a clipped but non-zero rate would divide by a tiny |E|^2.

Parameters:
field_tnumpy.ndarray

The real field at the chunk’s nodes, shape (n_nodes_chunk, n_pol, n_to), in V/m.

ratenumpy.ndarray

The ionisation rate from ionisation_rate(), s^-1, shape (n_nodes_chunk, n_to).

fractionnumpy.ndarray

The fraction ionised from plasma_scan(), shape (n_nodes_chunk, n_to).

free_currentnumpy.ndarray

J_free from plasma_scan(), shape (n_nodes_chunk, n_pol, n_to).

coefficientssolprop.translate.responses.PlasmaCoefficients

The compiled plasma group; only ionisation_potential is read here.

densityfloat

The density path at this position, responses.density(z), in m^-3, non-negative. The currents are per atom; this is what turns them into a polarisation.

dtfloat

Sample spacing of the fine time grid, s, positive.

integralsolprop.nonlinear.ionisation.RunningIntegral or None, optional

The running-integral rule, responses.plasma_integral; None is the trapezoid.

Returns:
numpy.ndarray

The plasma polarisation in C/m^2, shape (n_nodes_chunk, n_pol, n_to).

Examples

>>> import numpy as np
>>> from solprop.backends.numpy_ref.passes.plasma import plasma_current
>>> from solprop.nonlinear.optmat_rates import OptmatRate
>>> from solprop.nonlinear.responses import PlasmaResponse
>>> from solprop.translate.responses import plasma_coefficients
>>> compiled = plasma_coefficients(
...     PlasmaResponse("Ar", OptmatRate("Ar", 800e-9)), (1e9, 1e11), z_max=1.0
... )
>>> zeros = np.zeros((1, 1, 4))
>>> flat = np.zeros((1, 4))
>>> plasma_current(
...     zeros, flat, flat, zeros, compiled, density=1e25, dt=1e-16
... ).tolist()
[[[0.0, 0.0, 0.0, 0.0]]]
solprop.backends.numpy_ref.passes.plasma.plasma_integration_diagnostics(field_t, channels, preionisation, dt, integral=None)[source]#

Return the parts of the column’s integration diagnostics (SEP 18).

For every channel and node: the exposure S as the rule forms it, before the floor, and its increments; the fraction; the work the loss current pays per ionisation potential, int W (1 - f) dt by the trapezoid of the raw rate; the electrons that freed, f_end - f_0; and the free-current integrand |f E|. Every part is a maximum over nodes and channels, so chunks combine by taking the largest of each, and each ratio is normalised by the most-ionised node rather than node by node: a node the field barely ionises, whose rate is one sampled spike, would otherwise report the filter’s full undershoot on a rate at the level of rounding (plasma_integration_statistics() forms the ratios).

Parameters:
field_tnumpy.ndarray

Real node fields in V/m, shape (n_nodes_chunk, n_pol, n_to).

channelssequence of PlasmaCoefficients

The channels’ compiled coefficients, each with its rate table.

preionisationtuple of float

Each channel’s initial fraction at this plane.

dtfloat

Fine-grid sample spacing in s.

integralsolprop.nonlinear.ionisation.RunningIntegral or None, optional

The running-integral rule; None is the trapezoid.

Returns:
numpy.ndarray

The largest exposure dip -min dS and rise max dS; the largest |paid - freed| and freed; the largest |f E| in the first 2K samples and anywhere. Dimensionless but for the last two, in V/m.

solprop.backends.numpy_ref.passes.plasma.plasma_integration_statistics(parts)[source]#

Form the three diagnostics from plasma_integration_diagnostics()’s parts.

Parameters:
partsnumpy.ndarray

The six maxima, combined over every chunk of nodes.

Returns:
tuple of float

The undershoot max(-dS) / max(dS), the work defect max |paid - freed| / max freed and the boundary level, each zero where its denominator is.

solprop.backends.numpy_ref.passes.plasma.plasma_scan(field_t, rate, coefficients, *, preionisation, dt, integral=None)[source]#

Integrate the ionised fraction and the free-electron current along t.

The plasma_scan stage: two of the three cumulative integrals the response declares, which is why its domain is memory – the value at one sample depends on every earlier sample and on none of the later ones.

f = 1 - (1 - f_0) exp(-int W dt), with the pre-ionised fraction inside the exponential. Writing f_0 + 1 - exp(-int W dt) instead would let f exceed one, make 1 - f negative and stop df/dt being W (1 - f), so the loss term would no longer pay exactly one ionisation potential per electron. Then J_free = (e^2/m_e) int f E dt, the current of electrons already freed and still being accelerated: what lowers the refractive index and blue-shifts the pulse.

Both integrals are the problem’s running-integral rule (SEP 18), applied in the argument order of solprop.nonlinear.responses.PlasmaResponse.evaluate(), each a vectorised cumulative sum (scipy.integrate.cumulative_trapezoid); this pass and the oracle are the same computation, and other backends’ scans are held to the scan’s rounding bound (SEP 25), not to its order. Under the band rule the exposure is floored at zero, so the fraction stays in [preionisation, 1) and is non-decreasing to within the filter’s undershoot. Here the multipass form is the reference, and fusing the three sums into one sequential sweep belongs to the native backend (docs/guide/media/nonlinear.md).

Parameters:
field_tnumpy.ndarray

The real field at the chunk’s nodes, shape (n_nodes_chunk, n_pol, n_to), in V/m.

ratenumpy.ndarray

The ionisation rate from ionisation_rate(), s^-1, shape (n_nodes_chunk, n_to).

coefficientssolprop.translate.responses.PlasmaCoefficients

The compiled plasma group; only charge_mass_ratio is read here.

preionisationfloat

The pre-ionised fraction at this position, coefficients.preionisation(z), in [0, 1].

dtfloat

Sample spacing of the fine time grid, s, positive.

integralsolprop.nonlinear.ionisation.RunningIntegral or None, optional

The running-integral rule, responses.plasma_integral; None is the trapezoid.

Returns:
fractionnumpy.ndarray

The fraction ionised, shape (n_nodes_chunk, n_to), in [preionisation, 1] and non-decreasing in time (under the band rule, to within the filter’s undershoot).

free_currentnumpy.ndarray

J_free per unit density, shape (n_nodes_chunk, n_pol, n_to), in C/(m^2 s) per m^-3.

Examples

>>> import numpy as np
>>> from solprop.backends.numpy_ref.passes.plasma import plasma_scan
>>> from solprop.nonlinear.optmat_rates import OptmatRate
>>> from solprop.nonlinear.responses import PlasmaResponse
>>> from solprop.translate.responses import plasma_coefficients
>>> compiled = plasma_coefficients(
...     PlasmaResponse("Ar", OptmatRate("Ar", 800e-9)), (1e9, 1e11), z_max=1.0
... )
>>> field = np.zeros((1, 1, 4))
>>> fraction, current = plasma_scan(
...     field, np.zeros((1, 4)), compiled, preionisation=0.25, dt=1e-16
... )
>>> fraction.tolist(), bool(np.all(current == 0.0))
([[0.25, 0.25, 0.25, 0.25]], True)
solprop.backends.numpy_ref.passes.plasma.plasma_total_current(field_t, rate, fraction, free_current, coefficients)[source]#

Add the guarded loss current to the free current, per unit density.

J_free + I_p W (1 - f) E / |E|^2, the integrand of plasma_current() and what a stage holds at the collar (SEP 27); the guard is the one plasma_current() describes.

Parameters:
field_tnumpy.ndarray

The real field at the chunk’s nodes, shape (n_nodes_chunk, n_pol, n_to), in V/m.

ratenumpy.ndarray

The ionisation rate from ionisation_rate(), s^-1, shape (n_nodes_chunk, n_to).

fractionnumpy.ndarray

The fraction ionised from plasma_scan(), shape (n_nodes_chunk, n_to).

free_currentnumpy.ndarray

J_free from plasma_scan(), shape (n_nodes_chunk, n_pol, n_to).

coefficientssolprop.translate.responses.PlasmaCoefficients

The compiled plasma group; only ionisation_potential is read here.

Returns:
numpy.ndarray

The total current per unit number density, in A m, with the field’s shape.