Foundation core¶
The dependency-light foundation namespace: typed units, physical constants, temporal grids and the optical-material interface. See Foundation core for the guide and the stable/satellite boundary.
photonics_helper.core.units ¶
Typed unit classes — a foundation primitive.
Re-exports the unit-safe scalar/array types from
:mod:photonics_helper.base. This module exists so that downstream code can
type against photonics_helper.core.units as the stable foundation surface;
the implementation currently lives in base.py (moving it is deferred).
Importing this module is dependency-light: numpy, scipy and pydantic only.
AngularFrequency ¶
Angular optical frequency stored internally in rad/s.
Accepts rad/s or rad/ps on construction; converts to rad/s in __post_init__.
from_meep
classmethod
¶
from_meep(value: float, base_length: Wavelength | None = None) -> Self
Create from MEEP frequency units.
In MEEP, c = 1, so f_Meep = ω·a/(2πc). Therefore ω = 2π·f_Meep·c/a.
AngularFrequencyArray ¶
Array of angular frequencies stored internally in rad/s.
to_equally_spaced ¶
to_equally_spaced(points=51) -> NDArray
Return equally-spaced angular frequency values between min and max.
from_meep
classmethod
¶
from_meep(value: float | NDArray, base_length: Wavelength | None = None) -> Self
Create from MEEP frequency units.
In MEEP, c = 1, so f_Meep = ω·a/(2πc). Therefore ω = 2π·f_Meep·c/a.
Area ¶
Area stored internally in square meters (m²).
Accepts m^2, cm^2, mm^2, um^2, or nm^2 on construction; converts to m² in __post_init__.
Energy ¶
Energy stored internally in Joules.
Accepts J, mJ, uJ, nJ, pJ, eV, or meV on construction; converts to Joules in __post_init__.
Frequency ¶
Optical frequency stored internally in Hz.
Accepts THz, GHz, MHz, or Hz on construction; converts to Hz in __post_init__.
from_meep
classmethod
¶
from_meep(value: float, base_length: Wavelength | None = None) -> Self
Create from MEEP frequency units.
In MEEP, c = 1, so f_Meep = ν·a/c. Therefore ν = f_Meep·c/a.
FrequencyArray ¶
Array of frequencies stored internally in Hz.
to_equally_spaced ¶
to_equally_spaced(points=51) -> NDArray
Return equally-spaced frequency values between min and max.
from_meep
classmethod
¶
from_meep(value: float | NDArray, base_length: Wavelength | None = None) -> Self
Create from MEEP frequency units.
In MEEP, c = 1, so f_Meep = ν·a/c. Therefore ν = f_Meep·c/a.
Length ¶
Length stored internally in meters.
Accepts km, m, cm, mm, um, nm, or pm on construction; converts to meters in __post_init__.
PeakPower ¶
Bases: Power
Peak power of a pulse, tying normalized envelopes to physical watts.
A thin :class:Power subclass. The conversion from a normalized envelope
amplitude A (in V/m, or any consistent field unit) to a physical peak
power follows from the plane-wave intensity relation
.. math::
I = \tfrac{1}{2} n \, c \, \varepsilon_0 \, |A|^2
\qquad\Longrightarrow\qquad
P_\mathrm{peak} = I_\mathrm{peak} \, A_\mathrm{eff}
= \tfrac{1}{2} n \, c \, \varepsilon_0 \, A_\mathrm{eff} \, |A|^2.
Wave.peak_power() uses the same relation; this class exposes it for
one-shot conversions where only the envelope amplitude is at hand.
from_envelope
classmethod
¶
from_envelope(A: NDArray | float, A_eff: Area, n: float = 1.0, lambda0: Wavelength | None = None) -> PeakPower
Convert a normalized envelope amplitude to a physical peak power.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
A
|
complex envelope amplitude (array or scalar) in field units.
|
|
required |
A_eff
|
effective mode area.
|
|
required |
n
|
refractive index at the carrier wavelength (default 1.0).
|
|
1.0
|
lambda0
|
optional vacuum carrier wavelength. Retained so call sites
|
record the wavelength the refractive index refers to; validated when supplied. |
None
|
Returns:
| Type | Description |
|---|---|
PeakPower — the peak power in watts (a :class:`Power`).
|
|
Permeability ¶
Permittivity ¶
Power ¶
Power stored internally in Watts.
Accepts kW, W, mW, uW, or nW on construction; converts to Watts in __post_init__.
from_meep
classmethod
¶
from_meep(value: float, base_length: Wavelength | None = None) -> Self
Create from MEEP power units.
Energy unit ħc/a joined with Energy.as_meep (which uses the
Planck constant h, not ħ) gives P_meep = P·a²/(h·c²),
the exact inverse of :attr:as_meep.
Time ¶
Time stored internally in seconds.
Accepts s, ms, us, ns, ps, fs, or as on construction; converts to seconds in __post_init__.
Wavelength ¶
Wavelength stored internally in meters.
Accepts nm, um, or m on construction; converts to meters in __post_init__.
from_meep
classmethod
¶
from_meep(value: float, base_length: Wavelength | None = None) -> Self
Create from MEEP frequency units.
In MEEP, c = 1, so f_Meep = a/λ where a is the base_length.
WavelengthArray ¶
Array of wavelengths stored internally in meters.
from_wavelengths
classmethod
¶
from_wavelengths(wavelengths: list[Wavelength]) -> Self
Build from a list of Wavelength scalars (stored internally in m).
to_equally_spaced ¶
to_equally_spaced(points=51) -> NDArray
Return equally-spaced wavelength values between min and max.
from_meep
classmethod
¶
from_meep(value: float | NDArray, base_length: Wavelength | None = None) -> Self
Create from MEEP frequency units.
In MEEP, c = 1, so f_Meep = a/λ where a is the base_length.
Wavenumber ¶
Wavenumber stored internally in 1/m.
Accepts 1/cm or 1/m on construction; converts to 1/m in __post_init__.
from_meep
classmethod
¶
from_meep(value: float, base_length: Wavelength | None = None) -> Self
Create from MEEP frequency units.
In MEEP, c = 1, so f_Meep = k·a/(2π).
WavenumberArray ¶
Array of wavenumbers stored internally in 1/m.
photonics_helper.core.constants ¶
Physical constants — a foundation primitive.
Re-exports the constants from :mod:photonics_helper.base under a stable
namespace. Values come from :mod:scipy.constants (CODATA).
photonics_helper.core.grids ¶
Temporal grids — a foundation primitive.
TemporalGrid defines the time/frequency sampling and the FFT convention used
throughout the library (FFT(A)·dt forward, /dt inverse, both
fftshifted), so Parseval holds with the paired transforms. It is deliberately
free of plotting dependencies: :mod:photonics_helper.pulse re-exports this
same class object for backwards compatibility.
The FFTs execute on the configured backend (:mod:photonics_helper._fftw) —
FFTW3 when pyfftw is installed, otherwise numpy.
TemporalGrid ¶
Uniform temporal grid with FFT helpers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
N
|
number of samples.
|
|
required |
Tmax
|
total time window.
|
|
required |
fft ¶
fft(A_t)
Forward FFT — analysis kernel e^{+iΩt}, scaled by dt.
Convention swap 2026-09 (openspec fix-audit-issues-batch,
ISSUES.md #0): the analysis kernel is now e^{+iΩt} and the
companion :meth:ifft synthesis kernel e^{−iΩt}, the standard
Agrawal pairing (A(z,T) = ∫Ã(Ω)·e^{−iΩT}; the carrier factor is
e^{−iω₀t}). Implemented as conj(DFT(conj(·))) on the same
backend primitive (the DFT pair mirrored). Bin w > 0 under the
λ map λ = c/(ω₀ + grid.w) is the blue side, and Parseval still
holds with the paired transforms.
ifft ¶
ifft(A_w)
Inverse FFT paired with :meth:fft (includes 1/dt scaling).
Synthesis kernel e^{−iΩt} after the #0 convention swap; see
:meth:fft.
for_pulse_train
classmethod
¶
for_pulse_train(repetition_rate: Frequency, n_pulses: int, pulse_width: Time, N: int = 2 ** 12) -> Self
Compute the right Tmax to cover a pulse train.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
repetition_rate
|
Frequency — pulse spacing = 1 / repetition_rate
|
|
required |
n_pulses
|
number of pulses
|
|
required |
pulse_width
|
T₀ — characteristic width, used to estimate needed padding
|
|
required |
N
|
number of time points (default 2¹²)
|
|
2 ** 12
|
photonics_helper.core.materials ¶
Optical-material interface — a foundation primitive.
Two things live here:
- :class:
OpticalMaterial, a runtime-checkable protocol describing a wavelength-dependent material (a name, the tabulatedn/kandwlarrays, the interpolatingn_func/k_func, and a provenancesource). Downstream code can type against the interface instead of the concrete :class:~photonics_helper.materials.RefractiveIndex. - :func:
material, a convenience lookup that builds a :class:Materialfrom the bundled database via the existing :meth:RefractiveIndex.from_material_databasepath.
This module is additive: nothing here replaces the existing
photonics_helper.materials API.
OpticalMaterial ¶
Bases: Protocol
Wavelength-dependent optical material.
Satisfied structurally by any object exposing these attributes/methods.
Material
dataclass
¶
Material(name: str, index: RefractiveIndex, source: str | None = None, license: str | None = None)
Concrete :class:OpticalMaterial wrapping a :class:RefractiveIndex.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
material name (as looked up in the database).
|
|
required |
index
|
the underlying tabulated/interpolated refractive index.
|
|
required |
source
|
provenance string (citation/author key) when known, else ``None``.
|
|
None
|
license
|
licence identifier/sentinel for the data when known, else ``None``.
|
|
None
|
material ¶
material(name: str, *, axis: str | None = None, n_points: int = 200) -> Material
Load a material from the bundled database.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
material name or ``material-author`` tabulated key.
|
|
required |
axis
|
for birefringent crystals, ``"extraordinary"`` (default canonical
|
row) or |
None
|
n_points
|
number of samples when the source is a Sellmeier equation.
|
|
200
|
Returns:
| Type | Description |
|---|---|
Material
|
A concrete :class: |
Raises:
| Type | Description |
|---|---|
ValueError
|
With an actionable message when the material is unknown, the axis is unknown/unavailable, or the database is missing, empty or corrupt. |