Configuration

vectorwaves.config_stuff.Config dataclass

Bases: SerializableConfig

Main VectorWaves Configuration.

This is the root tree for initializing an experiment. It manages the global backend, the observation plane settings, and the complex light source properties.

Example: config = get_config() config.op.size = (20.0, 20.0) config.source.k_space.gaussian(sigma_k_perp=1.0) config.source.randomize.off()

Attributes:

Name	Type	Description
backend	Literal['auto', 'numpy', 'numba', 'cupy', 'cupy64']	Computational backend to execute evaluations. Defaults to "auto". All backends perform exactly the same physical superposition of plane waves, but scale differently based on hardware: - "numpy" : Vectorized CPU fallback (highest RAM usage, best for small sets). - "numba" : JIT compiled parallel CPU loops (low RAM usage, fast CPU). - "cupy32" : Single-precision GPU execution (fastest for massive computations). - "cupy64" : Double-precision GPU execution (slower than cupy, but exact). - "auto" : Defaults to cupy64 if available, else numba, else numpy.
op	OpConfig	Settings for the Observation Plane (grid size, center, resolution).
source	SourceConfig	Settings for the Light Source (beam axis, wavelength, spatial/spectral profiles).
verbose	bool	If True, prints execution details and deep warnings.

Source code in src\vectorwaves\config_stuff.py

@dataclass(slots=True)
class Config(SerializableConfig):
    """
    Main VectorWaves Configuration.

    This is the root tree for initializing an experiment. It manages the global 
    backend, the observation plane settings, and the complex light source properties.

    Example:
        `config = get_config()`
        `config.op.size = (20.0, 20.0)`
        `config.source.k_space.gaussian(sigma_k_perp=1.0)`
        `config.source.randomize.off()`

    Attributes
    ----------
    backend : Literal["auto", "numpy", "numba", "cupy", "cupy64"]
        Computational backend to execute evaluations. Defaults to "auto".
        All backends perform exactly the same physical superposition of plane waves, 
        but scale differently based on hardware:
        - "numpy"  : Vectorized CPU fallback (highest RAM usage, best for small sets).
        - "numba"  : JIT compiled parallel CPU loops (low RAM usage, fast CPU).
        - "cupy32" : Single-precision GPU execution (fastest for massive computations).
        - "cupy64" : Double-precision GPU execution (slower than cupy, but exact).
        - "auto"   : Defaults to cupy64 if available, else numba, else numpy.
    op : OpConfig
        Settings for the Observation Plane (grid size, center, resolution).
    source : SourceConfig
        Settings for the Light Source (beam axis, wavelength, spatial/spectral profiles).
    verbose : bool
        If True, prints execution details and deep warnings.
    """
    backend: Literal["auto", "numpy", "numba", "cupy32", "cupy64"] = "auto"
    op: OpConfig = field(default_factory=OpConfig)
    source: SourceConfig = field(default_factory=SourceConfig)
    verbose: bool = False

    def validate(self):
        self.op.validate()
        self.source.validate()

        self.backend = str(self.backend).lower()
        allowed = ["numba", "numpy", "auto", "cupy32", "cupy64"]
        if self.backend not in allowed:
            raise ValueError(f"Invalid backend: {self.backend}. Must be one of {allowed}")

        wls = np.atleast_1d(self.source.wavelength)
        min_wl = np.min(wls)
        if self.op.spacing > min_wl / 2:
            warnings.warn(
                f"Spatial aliasing detected. Grid spacing ({self.op.spacing}) "
                f"is larger than half the minimum wavelength ({min_wl/2:.4f}).", 
                UserWarning
            )

    def __post_init__(self):
        self.validate()

vectorwaves.config_stuff.SourceConfig dataclass

Bases: SerializableConfig

Light Source Configuration.

Aggregates all physical parameters defining the initial state of the light field, including nested properties like spatial modes and polarization. Access this via config.source.

Example: config.source.intensity_scale = 1e3 config.source.wavelength = 0.532 config.source.k_space.gaussian(sigma_k_perp=2.0) config.source.randomize.off()

Attributes:

Name	Type	Description
k_space	KSpaceConfig	Sub-configuration dictating the spatial distribution of momentum (k-vectors).
polychromatic	PolychromaticConfig	Sub-configuration dictating the spectral/wavelength envelope.
randomize	RandomizeConfig	Sub-configuration dictating random noise/coherence features.
intensity_scale	float	Scalar multiplier for total field intensity. Must be > 0.
wavelength	Union[float, List[float]]	The physical wavelength(s) of the simulation.
pol_vect	Tuple[complex, complex]	Jones vector (E1, E2) defining base polarization, normalized upon init.
beam_axis	Tuple[float, float, float]	Average propagation direction vector (kx, ky, kz), normalized upon init.
num_modes	int	Number of plane wave modes used for the angular spectrum sum.
theta_max	float	Maximum half-cone angle (radians) restricting the generated wavevectors.

Source code in src\vectorwaves\config_stuff.py

@dataclass(slots=True)
class SourceConfig(SerializableConfig):
    """
    Light Source Configuration. 

    Aggregates all physical parameters defining the initial state of the light
    field, including nested properties like spatial modes and polarization.
    Access this via `config.source`.

    Example:
        `config.source.intensity_scale = 1e3`
        `config.source.wavelength = 0.532`
        `config.source.k_space.gaussian(sigma_k_perp=2.0)`
        `config.source.randomize.off()`

    Attributes
    ----------
    k_space : KSpaceConfig
        Sub-configuration dictating the spatial distribution of momentum (k-vectors).
    polychromatic : PolychromaticConfig
        Sub-configuration dictating the spectral/wavelength envelope.
    randomize : RandomizeConfig
        Sub-configuration dictating random noise/coherence features.
    intensity_scale : float
        Scalar multiplier for total field intensity. Must be > 0.
    wavelength : Union[float, List[float]]
        The physical wavelength(s) of the simulation.
    pol_vect : Tuple[complex, complex]
        Jones vector (E1, E2) defining base polarization, normalized upon init.
    beam_axis : Tuple[float, float, float]
        Average propagation direction vector (kx, ky, kz), normalized upon init.
    num_modes : int
        Number of plane wave modes used for the angular spectrum sum.
    theta_max : float
        Maximum half-cone angle (radians) restricting the generated wavevectors.
    """
    k_space: KSpaceConfig = field(default_factory=KSpaceConfig)
    polychromatic: PolychromaticConfig = field(default_factory=PolychromaticConfig)
    randomize: RandomizeConfig = field(default_factory=RandomizeConfig)

    intensity_scale: float = 1e3
    wavelength: Union[float, List[float]] = 1.0
    pol_vect: Tuple[complex, complex] = (1+0j, 0+0j)
    beam_axis: Tuple[float, float, float] = (0.0, 0.0, 1.0)

    num_modes: int = 6000
    theta_max: float = np.pi/2

    def validate(self):
        self.intensity_scale = _check_scalar(self.intensity_scale, "source.intensity_scale", float)
        if self.intensity_scale <= 0: raise ValueError("source.intensity_scale must be > 0")

        self.num_modes = _check_scalar(self.num_modes, "source.num_modes", int)
        if self.num_modes <= 0: raise ValueError("source.num_modes must be > 0")

        if np.isscalar(self.wavelength):
            self.wavelength = _check_scalar(self.wavelength, "source.wavelength", float)
            if self.wavelength <= 0: raise ValueError("Wavelength must be > 0")
        else:
            if isinstance(self.wavelength, (np.ndarray, list, tuple)):
                self.wavelength =[_check_scalar(w, "source.wavelength", float) for w in self.wavelength]
                if any(w <= 0 for w in self.wavelength): raise ValueError("All wavelengths must be > 0")
            else:
                 raise TypeError(f"Expected float or list of floats for wavelength, got {type(self.wavelength)}")

        self.pol_vect = _coerce_tuple(self.pol_vect, 2, "source.pol_vect", dtype=complex)
        norm = np.linalg.norm(self.pol_vect)
        if norm < 1e-13: raise ValueError('pol_vect must have reasonable norm.')
        self.pol_vect = (self.pol_vect[0]/norm, self.pol_vect[1]/norm)

        axis = _coerce_tuple(self.beam_axis, 3, "source.beam_axis", dtype=float)
        norm = np.linalg.norm(axis)
        if norm < 1e-13: raise ValueError("beam_axis must have reasonable norm")
        self.beam_axis = (axis[0]/norm, axis[1]/norm, axis[2]/norm)

        self.theta_max = _check_scalar(self.theta_max, "source.theta_max", float)
        if not 0 < self.theta_max <= np.pi:
            raise ValueError("For fibonacci sampling, maximum angle must be in (0, pi).")

        self.k_space.validate()
        self.polychromatic.validate()
        self.randomize.validate()

    def __post_init__(self):
        self.validate()

vectorwaves.config_stuff.OpConfig dataclass

Bases: SerializableConfig

Observation Plane Configuration.

Defines the spatial grid where the optical field is evaluated. Access this via config.op.

Example: config.op.size = (10.0, 10.0) config.op.spacing = 0.05

Attributes:

Name	Type	Description
spacing	float	Grid pixel spacing. Must be strictly > 0.
size	tuple[float, float]	Physical size of the rectangular plane (width, height).
center	tuple[float, float]	Center position (x, y) of the plane relative to the global origin (0,0).

Source code in src\vectorwaves\config_stuff.py

@dataclass(slots=True)
class OpConfig(SerializableConfig):
    """
    Observation Plane Configuration.

    Defines the spatial grid where the optical field is evaluated. Access this
    via `config.op`.

    Example:
        `config.op.size = (10.0, 10.0)`
        `config.op.spacing = 0.05`

    Attributes
    ----------
    spacing : float
        Grid pixel spacing. Must be strictly > 0.
    size : tuple[float, float]
        Physical size of the rectangular plane (width, height).
    center : tuple[float, float]
        Center position (x, y) of the plane relative to the global origin (0,0).
    """
    spacing: float = 0.05
    size: Tuple[float, float] = (10.0, 10.0)
    center: Tuple[float, float] = (0.0, 0.0)

    def validate(self):
        self.spacing = _check_scalar(self.spacing, "op.spacing", float)
        if self.spacing <= 0: raise ValueError("op.spacing must be > 0")
        self.size = _coerce_tuple(self.size, 2, "op.size", float)
        if any(d <= 0 for d in self.size): raise ValueError("op.size must be positive")
        self.center = _coerce_tuple(self.center, 2, "op.center", float)

    def __post_init__(self):
        self.validate()

vectorwaves.config_stuff.KSpaceConfig dataclass

Bases: SerializableConfig

k-Space Spatial Profile Configuration.

Controls how plane wave modes are weighted depending on their wavevector. Access this via config.source.k_space.

Use fluent methods to modify the distribution: config.source.k_space.gaussian(sigma_k_perp=2.0) config.source.k_space.laguerre_gauss(p=0, l=1)

Attributes:

Name	Type	Description
profile	Callable	The active profile function (from KSpaceSpectra or custom).
params	Dict[str, Any]	Keyword arguments dynamically passed into the profile callable.
vectorised	bool	If True, indicates the callable supports numpy array vectorization.

Source code in src\vectorwaves\config_stuff.py

@dataclass(slots=True)
class KSpaceConfig(SerializableConfig):
    """
    k-Space Spatial Profile Configuration.

    Controls how plane wave modes are weighted depending on their wavevector.
    Access this via `config.source.k_space`.

    Use fluent methods to modify the distribution:
        `config.source.k_space.gaussian(sigma_k_perp=2.0)`
        `config.source.k_space.laguerre_gauss(p=0, l=1)`

    Attributes
    ----------
    profile : Callable
        The active profile function (from `KSpaceSpectra` or custom).
    params : Dict[str, Any]
        Keyword arguments dynamically passed into the `profile` callable.
    vectorised : bool
        If True, indicates the callable supports numpy array vectorization.
    """
    profile: Callable = field(default=KSpaceSpectra.gaussian)
    params: Dict[str, Any] = field(default_factory=lambda: {"sigma_k_perp": 1.5})
    vectorised: bool = True

    def uniform(self) -> "KSpaceConfig":
        """
        Sets k-space profile to a flat angular spectrum (Uniform k-space).
        Weights all plane waves equally.
        """
        self.profile = KSpaceSpectra.uniform
        self.params = {}
        return self

    def gaussian(self, sigma_k_perp: float = 1.5) -> "KSpaceConfig":
        """
        Sets k-space profile to a Gaussian envelope.

        Parameters
        ----------
        sigma_k_perp : float, default=1.5
            The standard deviation of the Gaussian envelope in k-space.
            Inversely proportional to the real-space beam waist.
        """
        self.profile = KSpaceSpectra.gaussian
        self.params = {'sigma_k_perp': sigma_k_perp}
        self.vectorised = True
        return self

    def tophat(self, k_perp_max: float = 1.0) -> "KSpaceConfig":
        """
        Sets k-space profile to a sharp Top-Hat cutoff, producing an Airy disk 
        in real space.

        Parameters
        ----------
        k_perp_max : float, default=1.0
            The maximum transverse spatial frequency allowed.
        """
        self.profile = KSpaceSpectra.tophat
        self.params = {'k_perp_max': k_perp_max}
        self.vectorised = True
        return self

    def laguerre_gauss(self, *, p: int = 0, l: int = 0, sigma_k_perp: float = 0.5) -> "KSpaceConfig":
        """
        Sets k-space profile to a Laguerre-Gauss mode carrying 
        Orbital Angular Momentum.

        Parameters
        ----------
        p : int, default=0
            Radial index (p >= 0). Determines the number of radial rings.
        l : int, default=0
            Azimuthal index (topological charge). Determines the OAM.
        sigma_k_perp : float, default=0.5
            Transverse scaling parameter in k-space.
        """
        if p < 0: raise ValueError("LG index p must be >= 0")
        self.profile = KSpaceSpectra.laguerre_gauss
        self.params = {'p': p, 'l': l, 'sigma_k_perp': sigma_k_perp}
        self.vectorised = True
        return self

    def hermite_gauss(self, *, l: int = 0, m: int = 0, sigma_k_perp: float = 0.5) -> "KSpaceConfig":
        """
        Sets k-space profile to a higher-order Hermite-Gauss transverse mode.

        Parameters
        ----------
        l : int, default=0
            Transverse mode index in the x-direction (l >= 0).
        m : int, default=0
            Transverse mode index in the y-direction (m >= 0).
        sigma_k_perp : float, default=0.5
            Transverse scaling parameter in k-space.
        """
        if l < 0 or m < 0: raise ValueError("HG indices l, m must be >= 0")
        self.profile = KSpaceSpectra.hermite_gauss
        self.params = {'l': l, 'm': m, 'sigma_k_perp': sigma_k_perp}
        self.vectorised = True
        return self

    def bessel_gauss(self, *, theta_deg: float = 10.0, sigma_theta: float = 0.05, l: int = 0) -> "KSpaceConfig":
        """
        Sets k-space profile to a Bessel-Gauss mode, creating a non-diffracting core.

        Parameters
        ----------
        theta_deg : float, default=10.0
            Cone opening angle (in degrees) of the Bessel beam in k-space.
        sigma_theta : float, default=0.05
            Angular thickness (in radians) of the Gaussian ring.
        l : int, default=0
            Topological charge. If l != 0, creates a Higher-Order Bessel beam.
        """
        if theta_deg > 70: 
            warnings.warn(
                "Large Bessel cone angles interact strangely with hemisphere clipping.",
                UserWarning
                )
        self.profile = KSpaceSpectra.bessel_gauss
        self.params = {'theta_0': np.radians(theta_deg), 'sigma_theta': sigma_theta, 'l': l}
        self.vectorised = True
        return self

    def custom(self, fn: Callable, vectorised: bool = False, **params) -> "KSpaceConfig":
        """
        Sets a user-defined custom k-space profile function.

        Parameters
        ----------
        fn : Callable
            Function signature: fn(k: np.ndarray, **params) -> complex/np.ndarray
        vectorised : bool, default=False
            If True, `fn` must accept a (3, N) array and return an (N,) array.
            Else: fn must accept a (3,) array and return a complex number.
        **params : Any
            Keyword arguments passed directly into `fn` during evaluation.

        Notes
        -----
        The provided function `fn` will be tested with a dummy wavevector 
        array (np.random.randn(3, 2) if vectorised else np.random.randn(3)) 
        to validate its return type and shape.
        """
        self.profile = fn
        self.params = params
        self.vectorised = vectorised
        self.validate()
        return self

    def validate(self):
        if getattr(self.profile, '__name__', '') == 'custom_callable_fail': return
        try:
            test_k = np.random.randn(3, 2) if self.vectorised else np.random.randn(3)
            res = self.profile(test_k, **self.params)
            if self.vectorised and (not hasattr(res, "__len__") or len(res) != 2): 
                raise ValueError("Vectorised function must return an array matching input shape.")
            elif not self.vectorised and not np.isscalar(res) and not isinstance(res, complex): 
                raise ValueError("Non-vectorised function must return a scalar.")
        except Exception as e:
            raise RuntimeError(f"K space profile failed validation: {e}")

    def __post_init__(self):
        self.validate()

bessel_gauss(*, theta_deg=10.0, sigma_theta=0.05, l=0)

Sets k-space profile to a Bessel-Gauss mode, creating a non-diffracting core.

Parameters:

Name	Type	Description	Default
theta_deg	float	Cone opening angle (in degrees) of the Bessel beam in k-space.	10.0
sigma_theta	float	Angular thickness (in radians) of the Gaussian ring.	0.05
l	int	Topological charge. If l != 0, creates a Higher-Order Bessel beam.	0

Source code in src\vectorwaves\config_stuff.py

def bessel_gauss(self, *, theta_deg: float = 10.0, sigma_theta: float = 0.05, l: int = 0) -> "KSpaceConfig":
    """
    Sets k-space profile to a Bessel-Gauss mode, creating a non-diffracting core.

    Parameters
    ----------
    theta_deg : float, default=10.0
        Cone opening angle (in degrees) of the Bessel beam in k-space.
    sigma_theta : float, default=0.05
        Angular thickness (in radians) of the Gaussian ring.
    l : int, default=0
        Topological charge. If l != 0, creates a Higher-Order Bessel beam.
    """
    if theta_deg > 70: 
        warnings.warn(
            "Large Bessel cone angles interact strangely with hemisphere clipping.",
            UserWarning
            )
    self.profile = KSpaceSpectra.bessel_gauss
    self.params = {'theta_0': np.radians(theta_deg), 'sigma_theta': sigma_theta, 'l': l}
    self.vectorised = True
    return self

custom(fn, vectorised=False, **params)

Sets a user-defined custom k-space profile function.

Parameters:

Name	Type	Description	Default
fn	Callable	Function signature: fn(k: np.ndarray, **params) -> complex/np.ndarray	required
vectorised	bool	If True, fn must accept a (3, N) array and return an (N,) array. Else: fn must accept a (3,) array and return a complex number.	False
**params	Any	Keyword arguments passed directly into fn during evaluation.	{}

Notes

The provided function fn will be tested with a dummy wavevector array (np.random.randn(3, 2) if vectorised else np.random.randn(3)) to validate its return type and shape.

Source code in src\vectorwaves\config_stuff.py

def custom(self, fn: Callable, vectorised: bool = False, **params) -> "KSpaceConfig":
    """
    Sets a user-defined custom k-space profile function.

    Parameters
    ----------
    fn : Callable
        Function signature: fn(k: np.ndarray, **params) -> complex/np.ndarray
    vectorised : bool, default=False
        If True, `fn` must accept a (3, N) array and return an (N,) array.
        Else: fn must accept a (3,) array and return a complex number.
    **params : Any
        Keyword arguments passed directly into `fn` during evaluation.

    Notes
    -----
    The provided function `fn` will be tested with a dummy wavevector 
    array (np.random.randn(3, 2) if vectorised else np.random.randn(3)) 
    to validate its return type and shape.
    """
    self.profile = fn
    self.params = params
    self.vectorised = vectorised
    self.validate()
    return self

gaussian(sigma_k_perp=1.5)

Sets k-space profile to a Gaussian envelope.

Parameters:

Name	Type	Description	Default
sigma_k_perp	float	The standard deviation of the Gaussian envelope in k-space. Inversely proportional to the real-space beam waist.	1.5

Source code in src\vectorwaves\config_stuff.py

def gaussian(self, sigma_k_perp: float = 1.5) -> "KSpaceConfig":
    """
    Sets k-space profile to a Gaussian envelope.

    Parameters
    ----------
    sigma_k_perp : float, default=1.5
        The standard deviation of the Gaussian envelope in k-space.
        Inversely proportional to the real-space beam waist.
    """
    self.profile = KSpaceSpectra.gaussian
    self.params = {'sigma_k_perp': sigma_k_perp}
    self.vectorised = True
    return self

hermite_gauss(*, l=0, m=0, sigma_k_perp=0.5)

Sets k-space profile to a higher-order Hermite-Gauss transverse mode.

Parameters:

Name	Type	Description	Default
l	int	Transverse mode index in the x-direction (l >= 0).	0
m	int	Transverse mode index in the y-direction (m >= 0).	0
sigma_k_perp	float	Transverse scaling parameter in k-space.	0.5

Source code in src\vectorwaves\config_stuff.py

def hermite_gauss(self, *, l: int = 0, m: int = 0, sigma_k_perp: float = 0.5) -> "KSpaceConfig":
    """
    Sets k-space profile to a higher-order Hermite-Gauss transverse mode.

    Parameters
    ----------
    l : int, default=0
        Transverse mode index in the x-direction (l >= 0).
    m : int, default=0
        Transverse mode index in the y-direction (m >= 0).
    sigma_k_perp : float, default=0.5
        Transverse scaling parameter in k-space.
    """
    if l < 0 or m < 0: raise ValueError("HG indices l, m must be >= 0")
    self.profile = KSpaceSpectra.hermite_gauss
    self.params = {'l': l, 'm': m, 'sigma_k_perp': sigma_k_perp}
    self.vectorised = True
    return self

laguerre_gauss(*, p=0, l=0, sigma_k_perp=0.5)

Sets k-space profile to a Laguerre-Gauss mode carrying Orbital Angular Momentum.

Parameters:

Name	Type	Description	Default
p	int	Radial index (p >= 0). Determines the number of radial rings.	0
l	int	Azimuthal index (topological charge). Determines the OAM.	0
sigma_k_perp	float	Transverse scaling parameter in k-space.	0.5

Source code in src\vectorwaves\config_stuff.py

def laguerre_gauss(self, *, p: int = 0, l: int = 0, sigma_k_perp: float = 0.5) -> "KSpaceConfig":
    """
    Sets k-space profile to a Laguerre-Gauss mode carrying 
    Orbital Angular Momentum.

    Parameters
    ----------
    p : int, default=0
        Radial index (p >= 0). Determines the number of radial rings.
    l : int, default=0
        Azimuthal index (topological charge). Determines the OAM.
    sigma_k_perp : float, default=0.5
        Transverse scaling parameter in k-space.
    """
    if p < 0: raise ValueError("LG index p must be >= 0")
    self.profile = KSpaceSpectra.laguerre_gauss
    self.params = {'p': p, 'l': l, 'sigma_k_perp': sigma_k_perp}
    self.vectorised = True
    return self

tophat(k_perp_max=1.0)

Sets k-space profile to a sharp Top-Hat cutoff, producing an Airy disk in real space.

Parameters:

Name	Type	Description	Default
k_perp_max	float	The maximum transverse spatial frequency allowed.	1.0

Source code in src\vectorwaves\config_stuff.py

def tophat(self, k_perp_max: float = 1.0) -> "KSpaceConfig":
    """
    Sets k-space profile to a sharp Top-Hat cutoff, producing an Airy disk 
    in real space.

    Parameters
    ----------
    k_perp_max : float, default=1.0
        The maximum transverse spatial frequency allowed.
    """
    self.profile = KSpaceSpectra.tophat
    self.params = {'k_perp_max': k_perp_max}
    self.vectorised = True
    return self

uniform()

Sets k-space profile to a flat angular spectrum (Uniform k-space). Weights all plane waves equally.

Source code in src\vectorwaves\config_stuff.py

def uniform(self) -> "KSpaceConfig":
    """
    Sets k-space profile to a flat angular spectrum (Uniform k-space).
    Weights all plane waves equally.
    """
    self.profile = KSpaceSpectra.uniform
    self.params = {}
    return self

vectorwaves.config_stuff.PolychromaticConfig dataclass

Bases: SerializableConfig

Polychromatic Envelope Configuration.

Controls the spectral (wavelength) distribution of the beam. Access this via config.source.polychromatic.

Use fluent methods to modify the distribution: config.source.polychromatic.gaussian(center=8.0, sigma=0.5)

Attributes:

Name	Type	Description
profile	Callable	The active profile function (from PolychromaticSpectra or custom).
params	Dict[str, Any]	Keyword arguments passed into the profile callable.

Source code in src\vectorwaves\config_stuff.py

@dataclass(slots=True)
class PolychromaticConfig(SerializableConfig):
    """
    Polychromatic Envelope Configuration.

    Controls the spectral (wavelength) distribution of the beam. Access this
    via `config.source.polychromatic`.

    Use fluent methods to modify the distribution:
        `config.source.polychromatic.gaussian(center=8.0, sigma=0.5)`

    Attributes
    ----------
    profile : Callable
        The active profile function (from `PolychromaticSpectra` or custom).
    params : Dict[str, Any]
        Keyword arguments passed into the `profile` callable.
    """
    profile: Callable = field(default=PolychromaticSpectra.uniform)
    params: Dict[str, Any] = field(default_factory=dict)

    def uniform(self) -> "PolychromaticConfig":
        """
        Sets a flat spectral envelope (all wavelengths weighted equally).
        """
        self.profile = PolychromaticSpectra.uniform
        self.params = {}
        return self

    def gaussian(self, center: float = 8.0, sigma: float = 0.5) -> "PolychromaticConfig":
        """
        Sets a Gaussian spectral weight distribution.

        Parameters
        ----------
        center : float, default=8.0
            The central wavelength (mean).
        sigma : float, default=0.5
            The spectral bandwidth (standard deviation).
        """
        self.profile = PolychromaticSpectra.gaussian
        self.params = {'center': center, 'sigma': sigma}
        return self

    def lorentzian(self, center: float = 8.0, gamma: float = 0.5) -> "PolychromaticConfig":
        """
        Sets a Lorentzian spectral weight distribution.

        Parameters
        ----------
        center : float, default=8.0
            The central resonance wavelength.
        gamma : float, default=0.5
            The Half-Width at Half-Maximum of the spectrum.
        """
        self.profile = PolychromaticSpectra.lorentzian
        self.params = {'center': center, 'gamma': gamma}
        return self

    def tophat(self, center: float = 8.0, width: float = 1.0) -> "PolychromaticConfig":
        """
        Sets a Top-Hat bandpass spectral envelope.

        Parameters
        ----------
        center : float, default=8.0
            The central wavelength of the bandpass.
        width : float, default=1.0
            The total spectral width of the bandpass.
        """
        self.profile = PolychromaticSpectra.tophat
        self.params = {'center': center, 'width': width}
        return self

    def custom(self, fn: Callable, **params) -> "PolychromaticConfig":
        """
        Sets a user-defined custom polychromatic envelope.

        Parameters
        ----------
        fn : Callable
            Function signature: fn(wavelength: float, **params) -> float
        **params : Any
            Keyword arguments passed directly into `fn` during evaluation.

        Notes
        -----
        The provided function `fn` will be tested with a dummy wavelength 
        (8.0) to validate that it returns a finite scalar.
        """
        self.profile = fn
        self.params = params
        self.validate()
        return self

    def validate(self):
        if getattr(self.profile, '__name__', '').endswith('fail'): return
        try:
            result = self.profile(8.0, **self.params)
            if not np.isscalar(result): raise ValueError(f"Polychromatic envelope must return a scalar. Got {type(result)}.")
            if not np.isfinite(result): raise ValueError(f"Polychromatic envelope returned non-finite value: {result}")
        except Exception as e:
            raise RuntimeError(f"Polychromatic profile failed validation: {e}\nEnsure signature is: fn(wavelength: float, **params) -> float") from e

    def __post_init__(self):
        self.validate()

custom(fn, **params)

Sets a user-defined custom polychromatic envelope.

Parameters:

Name	Type	Description	Default
fn	Callable	Function signature: fn(wavelength: float, **params) -> float	required
**params	Any	Keyword arguments passed directly into fn during evaluation.	{}

Notes

The provided function fn will be tested with a dummy wavelength (8.0) to validate that it returns a finite scalar.

Source code in src\vectorwaves\config_stuff.py

def custom(self, fn: Callable, **params) -> "PolychromaticConfig":
    """
    Sets a user-defined custom polychromatic envelope.

    Parameters
    ----------
    fn : Callable
        Function signature: fn(wavelength: float, **params) -> float
    **params : Any
        Keyword arguments passed directly into `fn` during evaluation.

    Notes
    -----
    The provided function `fn` will be tested with a dummy wavelength 
    (8.0) to validate that it returns a finite scalar.
    """
    self.profile = fn
    self.params = params
    self.validate()
    return self

gaussian(center=8.0, sigma=0.5)

Sets a Gaussian spectral weight distribution.

Parameters:

Name	Type	Description	Default
center	float	The central wavelength (mean).	8.0
sigma	float	The spectral bandwidth (standard deviation).	0.5

Source code in src\vectorwaves\config_stuff.py

def gaussian(self, center: float = 8.0, sigma: float = 0.5) -> "PolychromaticConfig":
    """
    Sets a Gaussian spectral weight distribution.

    Parameters
    ----------
    center : float, default=8.0
        The central wavelength (mean).
    sigma : float, default=0.5
        The spectral bandwidth (standard deviation).
    """
    self.profile = PolychromaticSpectra.gaussian
    self.params = {'center': center, 'sigma': sigma}
    return self

lorentzian(center=8.0, gamma=0.5)

Sets a Lorentzian spectral weight distribution.

Parameters:

Name	Type	Description	Default
center	float	The central resonance wavelength.	8.0
gamma	float	The Half-Width at Half-Maximum of the spectrum.	0.5

Source code in src\vectorwaves\config_stuff.py

def lorentzian(self, center: float = 8.0, gamma: float = 0.5) -> "PolychromaticConfig":
    """
    Sets a Lorentzian spectral weight distribution.

    Parameters
    ----------
    center : float, default=8.0
        The central resonance wavelength.
    gamma : float, default=0.5
        The Half-Width at Half-Maximum of the spectrum.
    """
    self.profile = PolychromaticSpectra.lorentzian
    self.params = {'center': center, 'gamma': gamma}
    return self

tophat(center=8.0, width=1.0)

Sets a Top-Hat bandpass spectral envelope.

Parameters:

Name	Type	Description	Default
center	float	The central wavelength of the bandpass.	8.0
width	float	The total spectral width of the bandpass.	1.0

Source code in src\vectorwaves\config_stuff.py

def tophat(self, center: float = 8.0, width: float = 1.0) -> "PolychromaticConfig":
    """
    Sets a Top-Hat bandpass spectral envelope.

    Parameters
    ----------
    center : float, default=8.0
        The central wavelength of the bandpass.
    width : float, default=1.0
        The total spectral width of the bandpass.
    """
    self.profile = PolychromaticSpectra.tophat
    self.params = {'center': center, 'width': width}
    return self

uniform()

Sets a flat spectral envelope (all wavelengths weighted equally).

Source code in src\vectorwaves\config_stuff.py

def uniform(self) -> "PolychromaticConfig":
    """
    Sets a flat spectral envelope (all wavelengths weighted equally).
    """
    self.profile = PolychromaticSpectra.uniform
    self.params = {}
    return self

vectorwaves.config_stuff.RandomizeConfig dataclass

Bases: SerializableConfig

Stochastic Process Configuration.

Controls which aspects of the light field are randomized during generation to simulate partially coherent beams, diffuse light, or specific speckle stats. Access this via config.source.randomize.

Example: To simulate fully coherent deterministic light: config.source.randomize.off()

Attributes:

Name	Type	Description
seed	int	Seed for the random number generator ensuring reproducible fields.
phase_max	float	Applies a random phase offset phi to each mode drawn from Uniform(-phase_max, +phase_max). This controls the degree of phase randomness: - phase_max = 0 for fully deterministic phase - 0 < phase_max < pi for partially randomized phase - phase_max = pi for fully randomized phase Must lie in [0, pi].
pol_rot_max	float	Maximum random rotation angle applied to the polarization vector drawn from Uniform(-pol_rot_max, +pol_rot_max) Controls the spread of polarization orientations: - pol_rot_max = 0 for deterministic polarization orientation - 0 < pol_rot_max < pi for partially randomized orientation - pol_rot_max = pi for fully randomized orientation Must lie in [0, pi]. Ignored if pol_state=True.
pol_state	bool	If True, samples fully random polarization states from the Poincaré sphere. Overrides pol_rot_max.
amplitude	bool	If True, applies a complex random normal factor to the mode amplitude.

Source code in src\vectorwaves\config_stuff.py

@dataclass(slots=True)
class RandomizeConfig(SerializableConfig):
    """
    Stochastic Process Configuration.

    Controls which aspects of the light field are randomized during generation
    to simulate partially coherent beams, diffuse light, or specific speckle stats.
    Access this via `config.source.randomize`.

    Example:
        To simulate fully coherent deterministic light:
        `config.source.randomize.off()`

    Attributes
    ----------
    seed : int
        Seed for the random number generator ensuring reproducible fields.

    phase_max : float
        Applies a random phase offset phi to each mode 
        drawn from Uniform(-phase_max, +phase_max).
        This controls the degree of phase randomness:
        - phase_max = 0      for fully deterministic phase
        - 0 < phase_max < pi for partially randomized phase
        - phase_max = pi     for fully randomized phase
        Must lie in [0, pi].

    pol_rot_max : float
        Maximum random rotation angle applied to the polarization vector 
        drawn from Uniform(-pol_rot_max, +pol_rot_max)
        Controls the spread of polarization orientations:
        - pol_rot_max = 0        for deterministic polarization orientation
        - 0 < pol_rot_max < pi for partially randomized orientation
        - pol_rot_max = pi     for fully randomized orientation
        Must lie in [0, pi].

        Ignored if `pol_state=True`.

    pol_state : bool
        If True, samples fully random polarization states from the Poincaré sphere.
        Overrides `pol_rot_max`.

    amplitude : bool
        If True, applies a complex random normal factor to the mode amplitude.

    """
    seed: int = 24459
    pol_rot_max: float = np.pi
    phase_max  : float = np.pi
    pol_state  : bool  = False
    amplitude  : bool  = True

    def validate(self):
        for f in["pol_state", "amplitude"]:
            val = getattr(self, f)
            if not isinstance(val, (bool, np.bool_)):
                raise TypeError(f"Config Error ['randomize.{f}']: Expected bool, got {type(val).__name__}")
        self.seed = _check_scalar(self.seed, "randomize.seed", int)

        self.phase_max = _check_scalar(self.phase_max, "randomize.phase_max", float)
        if not 0 <= self.phase_max <= np.pi:
            raise ValueError("Random phase_max must be in [0, pi].")
        self.pol_rot_max = _check_scalar(self.pol_rot_max, "randomize.pol_rot_max", float)
        if not 0 <= self.pol_rot_max <= np.pi:
            raise ValueError("Random pol_rot_max must be in [0, pi].")

        if self.pol_state and self.pol_rot_max > 0:
            warnings.warn(
                "'pol_state' is True and 'pol_rot_max' is present. 'pol_state' overrides 'pol_rot_max'.", 
                UserWarning
                )

    def off(self) -> "RandomizeConfig":
        """Turns off all randomness, making the beam perfectly coherent and deterministic."""
        self.pol_rot_max = 0
        self.phase_max = 0
        self.pol_state = False
        self.amplitude = False
        return self

    def __post_init__(self):
        self.validate()

off()

Turns off all randomness, making the beam perfectly coherent and deterministic.

Source code in src\vectorwaves\config_stuff.py

def off(self) -> "RandomizeConfig":
    """Turns off all randomness, making the beam perfectly coherent and deterministic."""
    self.pol_rot_max = 0
    self.phase_max = 0
    self.pol_state = False
    self.amplitude = False
    return self