solprop.exceptions#

The exception and warning hierarchies.

Every error raised by solprop is a SolpropError and every warning it emits is a SolpropWarning, so callers can catch or filter the whole family with one clause and still tell the cases apart. Raise the most specific subclass; never raise a bare Exception, and never return a sentinel where raising is correct.

Exceptions

AdiabaticTaperWarning

A multimode run on a guide whose modes move along z omits their coupling.

ApertureEdgeWarning

A wide tanh aperture edge converges slowly for light at the aperture centre.

BackendError

A backend is unavailable, misused or failed during propagation.

ConvergenceError

A numerical procedure did not converge within its budget.

CouplingError

A field plane, a remap or a launch between simulations is refused (SEP 31).

DiluteScalingWarning

A gas's dilute-limit index departs from its finite-density law beyond a bound.

DriverError

A run was asked for something the driver cannot execute.

ExponentBudgetWarning

A step the run cannot shrink forms a propagator factor near the overflow limit.

GasFlowWarning

A steady-flow gas fill leaves the regime its laminar continuum law describes.

GeneralModalBasisWarning

A general modal basis leaves its budget somewhere the run's light can reach.

GrazingIncidenceWarning

A grazing-incidence model is evaluated outside the range it is valid in.

GridError

A time or frequency grid is inconsistent or unsupported.

MaterialError

A material, gas or model is unknown or used outside its validity range.

MaterialRangeWarning

A material model is evaluated outside the validity range of its source.

MaterialStatusWarning

A resolved material model is flagged provisional or untested by its source.

MemoryBudgetError

A run's estimated persistent memory exceeds its declared memory budget.

MemoryBudgetWarning

A run's estimated persistent memory exceeds a budget declared to warn.

ModeError

A waveguide mode or mode set is invalid.

NoiseError

A shot-noise request is invalid.

OpticsGeometryError

An optical setting has no forward, non-grazing ray or diffraction order.

OutputError

An output handler could not save, load or resume a run.

PolarisationError

A Jones or Stokes vector, optical element or polarisation angle is invalid.

ProcessingError

A post-processing or plotting request is invalid.

PulseError

An input pulse specification is invalid or does not fit the grid.

RamanTemperatureWarning

Rotational Raman populations are held at one temperature; the gas's varies.

ResponseBudgetError(message, *, z, field, calls)

A run stopped before its end because its source-call budget was spent.

RunTerminated(signal_number)

A run stopped by SIGTERM, after writing where it stood.

SampledPeakWarning

A node-maximum plasma statistic is read where no quadrature node is on the axis.

SolpropError

Base class for every error raised by solprop.

SolpropWarning

Base class for every warning raised by solprop.

StepperError

A tableau, controller, schedule or landing setting is invalid.

SurrogateAreaWarning

A scalar model takes a provider channel's area at a frequency nobody chose.

TDSEArchiveError

A TDSE response archive could not be opened, serialized or written (SEP 20).

TDSEConsistencyError

A haCC response failed, or could not complete, its weak-field linear check.

TDSEConsistencyWarning

A haCC weak-field linear check warned, or was skipped at the caller's request.

TDSECostWarning

A TDSE response runs on a many-node radial rule: each node is one atom a call.

TDSEDomainWarning

A haCC preset is used beyond its qualifying duration, intensity or carrier.

TDSEUnqualifiedModelWarning

A custom haCC basis has no qualified accuracy, or lacks the current closure.

ToolsError

A design calculation was asked for something it cannot answer.

TranslationError

The translation layer could not build a valid kernel problem.

exception solprop.exceptions.AdiabaticTaperWarning[source]#

Bases: SolpropWarning

A multimode run on a guide whose modes move along z omits their coupling.

exception solprop.exceptions.ApertureEdgeWarning[source]#

Bases: SolpropWarning

A wide tanh aperture edge converges slowly for light at the aperture centre.

Amplitude-weighted tanh with 2 <= r/w < 4 (SEP 23, open question 10): the profile slopes at its centre, so a bright beam there is collected with a lattice error near 1e-5, where rcos is flat inside r - w.

exception solprop.exceptions.BackendError[source]#

Bases: SolpropError, RuntimeError

A backend is unavailable, misused or failed during propagation.

exception solprop.exceptions.ConvergenceError[source]#

Bases: SolpropError, RuntimeError

A numerical procedure did not converge within its budget.

exception solprop.exceptions.CouplingError[source]#

Bases: SolpropError, ValueError

A field plane, a remap or a launch between simulations is refused (SEP 31).

exception solprop.exceptions.DiluteScalingWarning[source]#

Bases: SolpropWarning

A gas’s dilute-limit index departs from its finite-density law beyond a bound.

exception solprop.exceptions.DriverError[source]#

Bases: SolpropError, RuntimeError

A run was asked for something the driver cannot execute.

exception solprop.exceptions.ExponentBudgetWarning[source]#

Bases: SolpropWarning

A step the run cannot shrink forms a propagator factor near the overflow limit.

A replayed schedule’s step, or the step floor dz_min, between nine tenths of log(DBL_MAX) and the limit itself (SEP 22 section 4.5): the run completes only while its field stays small enough that the factor times it does not overflow.

exception solprop.exceptions.GasFlowWarning[source]#

Bases: SolpropWarning

A steady-flow gas fill leaves the regime its laminar continuum law describes.

exception solprop.exceptions.GeneralModalBasisWarning[source]#

Bases: SolpropWarning

A general modal basis leaves its budget somewhere the run’s light can reach.

exception solprop.exceptions.GrazingIncidenceWarning[source]#

Bases: SolpropWarning

A grazing-incidence model is evaluated outside the range it is valid in.

A spatial spectral bin with an unresolved clamp branch, a coherent wall block near its validity limit, or a wall-pair guide (rectangular or slab) past its first-order ratios.

exception solprop.exceptions.GridError[source]#

Bases: SolpropError, ValueError

A time or frequency grid is inconsistent or unsupported.

exception solprop.exceptions.MaterialError[source]#

Bases: SolpropError, ValueError

A material, gas or model is unknown or used outside its validity range.

exception solprop.exceptions.MaterialRangeWarning[source]#

Bases: SolpropWarning

A material model is evaluated outside the validity range of its source.

exception solprop.exceptions.MaterialStatusWarning[source]#

Bases: SolpropWarning

A resolved material model is flagged provisional or untested by its source.

exception solprop.exceptions.MemoryBudgetError[source]#

Bases: DriverError

A run’s estimated persistent memory exceeds its declared memory budget.

exception solprop.exceptions.MemoryBudgetWarning[source]#

Bases: SolpropWarning

A run’s estimated persistent memory exceeds a budget declared to warn.

exception solprop.exceptions.ModeError[source]#

Bases: SolpropError, ValueError

A waveguide mode or mode set is invalid.

exception solprop.exceptions.NoiseError[source]#

Bases: SolpropError, ValueError

A shot-noise request is invalid.

exception solprop.exceptions.OpticsGeometryError[source]#

Bases: MaterialError

An optical setting has no forward, non-grazing ray or diffraction order.

exception solprop.exceptions.OutputError[source]#

Bases: SolpropError, RuntimeError

An output handler could not save, load or resume a run.

exception solprop.exceptions.PolarisationError[source]#

Bases: SolpropError, ValueError

A Jones or Stokes vector, optical element or polarisation angle is invalid.

exception solprop.exceptions.ProcessingError[source]#

Bases: SolpropError, ValueError

A post-processing or plotting request is invalid.

exception solprop.exceptions.PulseError[source]#

Bases: SolpropError, ValueError

An input pulse specification is invalid or does not fit the grid.

exception solprop.exceptions.RamanTemperatureWarning[source]#

Bases: SolpropWarning

Rotational Raman populations are held at one temperature; the gas’s varies.

exception solprop.exceptions.ResponseBudgetError(message, *, z, field, calls)[source]#

Bases: ConvergenceError

A run stopped before its end because its source-call budget was spent.

Raised before a trial that the budget could not pay for, so no step is accepted to fit the budget and the run is never marked complete (SEP 13 section 5). The state at the last accepted step travels with the error; a file output holds every plane reached, from which the run resumes afresh.

Parameters:
messagestr

What stopped and where.

zfloat

Position of the last accepted step, m.

fieldnumpy.ndarray or None

The state there.

callsint

Source calls charged before the stop.

Attributes:
zfloat

Position of the last accepted step, m.

fieldnumpy.ndarray or None

The state there, in the kernel’s canonical layout and FFT convention.

callsint

Source calls charged before the stop.

exception solprop.exceptions.RunTerminated(signal_number)[source]#

Bases: SystemExit

A run stopped by SIGTERM, after writing where it stood.

A scheduler’s time limit (Slurm’s, for one) sends SIGTERM before it kills the process. During a run it raises this at once, or as soon as the step or the save being written is complete, so the run’s terminal checkpoint and march snapshot are written as for any failure and resume=True continues the run. It is a SystemExit carrying the conventional exit status 128 + SIGTERM (143), so a script that does not catch it ends as a terminated process does.

Parameters:
signal_numberint

The signal that stopped the run.

Examples

>>> import signal
>>> from solprop.exceptions import RunTerminated
>>> error = RunTerminated(signal.SIGTERM)
>>> error.code, str(error)
(143, 'terminated by SIGTERM')
exception solprop.exceptions.SampledPeakWarning[source]#

Bases: SolpropWarning

A node-maximum plasma statistic is read where no quadrature node is on the axis.

A field-scale radial rule of few nodes (SEP 19) integrates the source but samples the axial peak at its innermost node; the on_axis_* statistics read the axis.

exception solprop.exceptions.SolpropError[source]#

Bases: Exception

Base class for every error raised by solprop.

exception solprop.exceptions.SolpropWarning[source]#

Bases: UserWarning

Base class for every warning raised by solprop.

exception solprop.exceptions.StepperError[source]#

Bases: SolpropError, ValueError

A tableau, controller, schedule or landing setting is invalid.

exception solprop.exceptions.SurrogateAreaWarning[source]#

Bases: SolpropWarning

A scalar model takes a provider channel’s area at a frequency nobody chose.

exception solprop.exceptions.TDSEArchiveError[source]#

Bases: OutputError

A TDSE response archive could not be opened, serialized or written (SEP 20).

Raised before any provider call when the archive path is refused, and in place of the next provider call after a failed write, so a run stops at its last optical checkpoint. A provider failure stays the primary error when recording it also fails.

exception solprop.exceptions.TDSEConsistencyError[source]#

Bases: MaterialError

A haCC response failed, or could not complete, its weak-field linear check.

Raised before any propagation call when the per-atom linear susceptibility of the atomic model departs from optmat’s helium by more than the declared refuse bound, or when the check’s own extraction is invalid (SEP 20, section 5.4). The structured result is attached as result when one exists.

result: object | None = None#
exception solprop.exceptions.TDSEConsistencyWarning[source]#

Bases: SolpropWarning

A haCC weak-field linear check warned, or was skipped at the caller’s request.

exception solprop.exceptions.TDSECostWarning[source]#

Bases: SolpropWarning

A TDSE response runs on a many-node radial rule: each node is one atom a call.

exception solprop.exceptions.TDSEDomainWarning[source]#

Bases: SolpropWarning

A haCC preset is used beyond its qualifying duration, intensity or carrier.

exception solprop.exceptions.TDSEUnqualifiedModelWarning[source]#

Bases: SolpropWarning

A custom haCC basis has no qualified accuracy, or lacks the current closure.

exception solprop.exceptions.ToolsError[source]#

Bases: SolpropError, ValueError

A design calculation was asked for something it cannot answer.

exception solprop.exceptions.TranslationError[source]#

Bases: SolpropError, ValueError

The translation layer could not build a valid kernel problem.