# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""The session namespace: everything a person types at a prompt, behind one import.
For a terminal or a notebook, **not** for library code::
import solprop.sol as sol # or: from solprop.sol import *
sol.capillary_params(125e-6, "He", 1.0, energy=275e-6, fwhm=7.5e-15,
wavelength=800e-9)
run = sol.prop_capillary(125e-6, 1.0, "He", 1.0, wavelength=800e-9, ...)
sol.prop_2d(run)
sol.compress_taylor(run)
The one module whose import has side effects: :func:`start_session` (called on import,
idempotent) configures logging at ``INFO`` and silences
:class:`~solprop.exceptions.MaterialRangeWarning`; :func:`end_session` undoes both,
:func:`material_warnings` turns the warning back on and :func:`set_log_level` changes
the level. The names are flat, a plot taking a ``plot_`` prefix where it shares a name
with a processing function (``energy`` measures, ``plot_energy`` draws), and ``numpy``
and ``matplotlib.pyplot`` are deliberately not re-exported. The manual page, with the
table of names, is ``docs/guide/workflows/interactive.md``.
"""
import logging
import warnings
from typing import cast
from solprop.driver.executors import Local, Pool, Queue, Slurm
from solprop.driver.interface import (
prop_capillary,
prop_free,
prop_gnlse,
prop_planar,
prop_waveguide,
)
from solprop.driver.scan import Scan, ScanPoint, run_scan
from solprop.driver.settings import SimulationSettings
from solprop.driver.simulation import Simulation
from solprop.driver.tdse import HaccPreset, hacc_basis, hacc_preset
from solprop.driver.tdse_consistency import ConsistencyResult, check_consistency
from solprop.exceptions import MaterialRangeWarning
from solprop.grid import EnvelopeGrid, FieldGrid, FreeGrid, LineGrid, RadialGrid
from solprop.log import PACKAGE_LOGGER, configure_logging
from solprop.modes import (
IndexTable,
MarcatiliMode,
ModeCollection,
PlanarGrid,
RectMode,
SlabMode,
StepIndexMode,
TabulatedHollowMode,
TabulatedMode,
TubeLattice,
VincettiMode,
gaussian_coupling,
gaussian_projection,
gaussian_to_per_unit_width,
per_unit_width_to_gaussian,
)
from solprop.modes.base import (
aeff,
alpha,
beta,
beta1,
beta2,
db_per_m,
loss_length,
transmission,
zdw,
)
from solprop.nonlinear import (
DampedOscillator,
DispersiveKerrResponse,
EnvelopePlasmaResponse,
HaccBasis,
KerrResponse,
PlasmaResponse,
RamanResponse,
RotationalLines,
SpecifiedMode,
TDSEAtomicWindow,
TDSEBasis,
TDSECalibration,
TDSEConsistency,
TDSEExecution,
TDSEGasResponse,
TDSESampling,
)
from solprop.nonlinear.optmat_rates import OptmatRate
from solprop.optics import (
Chain,
ChirpedMirror,
GratingPair,
Material,
PrismGeometry,
PrismPair,
PrismPaths,
TaylorPhase,
TransferFunction,
brewster_angle,
brewster_apex,
chirped_mirrors,
littrow_angle,
)
from solprop.output import (
CallbackOutput,
HDF5Output,
MemoryOutput,
TDSEArchive,
open_tdse_archive,
)
from solprop.output.hdf5 import open_file
from solprop.physdata import (
Gas,
MaterialSelection,
Mixture,
barium_fluoride,
bk7,
calcium_fluoride,
density,
fused_silica,
glass,
magnesium_fluoride,
n2,
refractive_index,
sapphire,
species,
)
from solprop.plotting import (
plot_energy,
plot_stats,
prop_2d,
spec_1d,
spectrogram,
time_1d,
wavelength_to_axis,
)
from solprop.processing import (
CepOptimum,
Compression,
FluenceMap,
Passband,
apply_transfer,
arrival_time,
band_coherence,
bandpass,
channel_amplitudes,
channel_labels,
coherence_time,
compress_gratings,
compress_material,
compress_mirrors,
compress_prisms,
compress_taylor,
coordinate_intensity,
electric_field,
energy,
example_output,
far_field,
field_autocorrelation,
field_spectrogram,
fluence_along,
fluence_map,
fwhm,
fwhm_f,
fwhm_t,
g12,
g12_of,
get_field,
get_phase,
get_power,
get_power_weight,
get_spectral_density,
get_spectrogram,
get_spectrum,
grid_of,
half_max_range,
instantaneous_flux,
intensity_autocorrelation,
magnetic_field,
moment,
nearest_plane,
on_axis_power,
on_axis_spectra,
on_axis_spectrogram,
optimise_cep,
peak_power,
physical_energy,
radial_intensity,
radial_spectrum,
real_field_oversampling,
reconstructed_flux,
spatial_grid_of,
specres,
spectral_bands,
time_axis,
time_bandwidth,
transform_limit,
)
from solprop.processing.scans import ScanOutput, open_scan
from solprop.profiles import (
Constant,
DensityPath,
Linear,
PathVariation,
PiecewiseLinear,
PressureGradient,
)
from solprop.pulses import (
CustomPulse,
CWPulse,
DataPulse,
GaussianPulse,
PlanarPulse,
SechPulse,
SpatialPulse,
TimeDataPulse,
)
from solprop.stats import StatsSpec
from solprop.stepper import Multistep, RungeKutta
from solprop.tools import (
RDW,
ZDW,
BeamParams,
DesignRoots,
GasRatio,
NonlinearPhase,
SolitonContent,
SolitonOrder,
SolitonParams,
beam_params,
beam_through_lens,
capillary_design,
capillary_params,
dispersion_length,
field_to_intensity,
fission_length,
gas_ratio,
intensity_to_field,
lambda_rdw,
lambda_rdw_all,
nonlinear_coefficient,
nonlinear_length,
phase_mismatch,
pressure_rdw,
pressure_zdw,
pulse_energy,
pulse_peak_power,
pulse_width,
radius_zdw,
self_focusing_power,
soliton_content,
soliton_order,
soliton_params,
soliton_peak_power,
solve_parameter,
)
__all__ = [
"RDW",
"ZDW",
"BeamParams",
"CWPulse",
"CallbackOutput",
"CepOptimum",
"Chain",
"ChirpedMirror",
"Compression",
"ConsistencyResult",
"Constant",
"CustomPulse",
"DampedOscillator",
"DataPulse",
"DensityPath",
"DesignRoots",
"DispersiveKerrResponse",
"EnvelopeGrid",
"EnvelopePlasmaResponse",
"FieldGrid",
"FluenceMap",
"FreeGrid",
"Gas",
"GasRatio",
"GaussianPulse",
"GratingPair",
"HDF5Output",
"HaccBasis",
"HaccPreset",
"IndexTable",
"KerrResponse",
"LineGrid",
"Linear",
"Local",
"MarcatiliMode",
"Material",
"MaterialSelection",
"MemoryOutput",
"Mixture",
"ModeCollection",
"Multistep",
"NonlinearPhase",
"OptmatRate",
"Passband",
"PathVariation",
"PiecewiseLinear",
"PlanarGrid",
"PlanarPulse",
"PlasmaResponse",
"Pool",
"PressureGradient",
"PrismGeometry",
"PrismPair",
"PrismPaths",
"Queue",
"RadialGrid",
"RamanResponse",
"RectMode",
"RotationalLines",
"RungeKutta",
"Scan",
"ScanOutput",
"ScanPoint",
"SechPulse",
"Simulation",
"SimulationSettings",
"SlabMode",
"Slurm",
"SolitonContent",
"SolitonOrder",
"SolitonParams",
"SpatialPulse",
"SpecifiedMode",
"StatsSpec",
"StepIndexMode",
"TDSEArchive",
"TDSEAtomicWindow",
"TDSEBasis",
"TDSECalibration",
"TDSEConsistency",
"TDSEExecution",
"TDSEGasResponse",
"TDSESampling",
"TabulatedHollowMode",
"TabulatedMode",
"TaylorPhase",
"TimeDataPulse",
"TransferFunction",
"TubeLattice",
"VincettiMode",
"aeff",
"alpha",
"apply_transfer",
"arrival_time",
"band_coherence",
"bandpass",
"barium_fluoride",
"beam_params",
"beam_through_lens",
"beta",
"beta1",
"beta2",
"bk7",
"brewster_angle",
"brewster_apex",
"calcium_fluoride",
"capillary_design",
"capillary_params",
"channel_amplitudes",
"channel_labels",
"check_consistency",
"chirped_mirrors",
"coherence_time",
"compress_gratings",
"compress_material",
"compress_mirrors",
"compress_prisms",
"compress_taylor",
"configure_logging",
"coordinate_intensity",
"db_per_m",
"density",
"dispersion_length",
"electric_field",
"end_session",
"energy",
"example_output",
"far_field",
"field_autocorrelation",
"field_spectrogram",
"field_to_intensity",
"fission_length",
"fluence_along",
"fluence_map",
"fused_silica",
"fwhm",
"fwhm_f",
"fwhm_t",
"g12",
"g12_of",
"gas_ratio",
"gaussian_coupling",
"gaussian_projection",
"gaussian_to_per_unit_width",
"get_field",
"get_phase",
"get_power",
"get_power_weight",
"get_spectral_density",
"get_spectrogram",
"get_spectrum",
"glass",
"grid_of",
"hacc_basis",
"hacc_preset",
"half_max_range",
"instantaneous_flux",
"intensity_autocorrelation",
"intensity_to_field",
"lambda_rdw",
"lambda_rdw_all",
"littrow_angle",
"loss_length",
"magnesium_fluoride",
"magnetic_field",
"material_warnings",
"moment",
"n2",
"nearest_plane",
"nonlinear_coefficient",
"nonlinear_length",
"on_axis_power",
"on_axis_spectra",
"on_axis_spectrogram",
"open_file",
"open_scan",
"open_tdse_archive",
"optimise_cep",
"peak_power",
"per_unit_width_to_gaussian",
"phase_mismatch",
"physical_energy",
"plot_energy",
"plot_stats",
"pressure_rdw",
"pressure_zdw",
"prop_2d",
"prop_capillary",
"prop_free",
"prop_gnlse",
"prop_planar",
"prop_waveguide",
"pulse_energy",
"pulse_peak_power",
"pulse_width",
"radial_intensity",
"radial_spectrum",
"radius_zdw",
"real_field_oversampling",
"reconstructed_flux",
"refractive_index",
"run_scan",
"sapphire",
"self_focusing_power",
"set_log_level",
"soliton_content",
"soliton_order",
"soliton_params",
"soliton_peak_power",
"solve_parameter",
"spatial_grid_of",
"spec_1d",
"species",
"specres",
"spectral_bands",
"spectrogram",
"start_session",
"time_1d",
"time_axis",
"time_bandwidth",
"transform_limit",
"transmission",
"wavelength_to_axis",
"zdw",
]
logger = logging.getLogger(__name__)
_OWN_FILTER = ("ignore", None, MaterialRangeWarning, None, 0)
"""The entry :func:`warnings.filterwarnings` makes for this module's one filter."""
[docs]
def material_warnings(enabled: bool) -> None:
"""Turn the material-range warnings on or off for this session.
Off installs one ``"ignore"`` filter for
:class:`~solprop.exceptions.MaterialRangeWarning`; on removes exactly that entry, so
whatever was in force before this module was imported is in force again -- Python's
default, or a stricter filter of your own, which is never touched or shadowed. (An
``"ignore"`` filter of your own for the same category is the same entry, and goes
with it.)
Parameters
----------
enabled : bool
``True`` to see the warnings again; ``False`` to silence them, as importing
this module does.
Examples
--------
>>> import warnings
>>> from solprop import sol
>>> from solprop.exceptions import MaterialRangeWarning
>>> with warnings.catch_warnings():
... sol.material_warnings(False)
... warnings.warn("outside the fit", MaterialRangeWarning)
"""
if not enabled:
warnings.filterwarnings("ignore", category=MaterialRangeWarning)
return
# `warnings` has no public call that removes one filter. Removing an "ignore" entry
# from the list is safe without the module's private bookkeeping, which exists to
# invalidate the once-per-location registries: an ignored warning is never entered
# in one.
filters = cast("list[object]", warnings.filters) # typeshed calls it a Sequence
while _OWN_FILTER in filters:
filters.remove(_OWN_FILTER)
[docs]
def set_log_level(level: int | str) -> None:
"""Set the level of the package's log output for this session.
Parameters
----------
level : int or str
A :mod:`logging` level or its name: ``"DEBUG"`` for the translation
summaries, ``"WARNING"`` for a quiet session.
"""
configure_logging(level)
[docs]
def start_session(level: int | str = logging.INFO) -> None:
"""Configure logging and silence the material-range warnings.
What importing :mod:`solprop.sol` does. Calling it again changes nothing: one
handler, one filter.
Parameters
----------
level : int or str, optional
Level of the package's log output.
"""
configure_logging(level)
material_warnings(False)
logger.debug("interactive session started")
[docs]
def end_session() -> None:
"""Undo :func:`start_session`: remove the log handler and show the warnings.
For a test, or a long-lived process that wants the library's defaults back. The
handler installed by :func:`solprop.log.configure_logging` is removed and the
package logger returns to inheriting its level.
"""
package = logging.getLogger(PACKAGE_LOGGER)
for handler in list(package.handlers):
if getattr(handler, "_solprop_installed", False):
package.removeHandler(handler)
handler.close()
package.setLevel(logging.NOTSET)
material_warnings(True)
start_session()