sources.smf

Single-Mode Fiber (SMF) Source Module

This module implements an extended Gaussian source that generates a ray bundle correctly representing the output of a single-mode fiber (SMF). The source produces rays with Gaussian distributions in both the spatial and angular domains, using quasi-random Sobol sequences for high-quality sampling.

Key features:

  • Spatial profile defined by the Mode Field Diameter (MFD).

  • Angular profile defined by the 1/e² full divergence angle.

  • Non-paraxial direction cosines computed via tangent mapping.

  • Sobol quasi-random sampling for low-discrepancy ray sets.

  • Optional point-source mode (zero spatial extent).

Note on num_rays:

Sobol sequences require the sample count to be a power of two. The generate_rays method automatically rounds the requested num_rays up to the nearest power of two, so the returned RealRays object may contain more rays than requested.

Classes

SMFSource(mfd_um, wavelength_um[, ...])

Extended Gaussian source representing a single-mode fiber output.
class SMFSource(mfd_um: float, wavelength_um: float, divergence_deg_1e2: float | None = None, total_power: float = 1.0, position: tuple[float, float, float] = (0.0, 0.0, 0.0), is_point_source: bool = False)[source]

Extended Gaussian source representing a single-mode fiber output.

This source generates rays with independent Gaussian distributions in both spatial (x, y) and angular (θ_x, θ_y) phase-space dimensions. It is designed to faithfully represent the far-field emission profile of a single-mode optical fiber.

Sampling uses 4-dimensional Sobol sequences (two spatial, two angular) transformed to Gaussian distributions via the inverse error function. Direction cosines are computed non-paraxially from the sampled angles using the tangent mapping, ensuring physical accuracy at large divergence angles.

Parameters:

  • mfd_um (float) – Mode Field Diameter in micrometers (µm). The 1/e² beam diameter at the fiber facet. The beam waist w₀ is mfd / 2.

  • divergence_deg_1e2 (float) – Full-angle 1/e² far-field divergence in degrees.

  • wavelength_um (float) – Operating wavelength in micrometers (µm).

  • total_power (float) – Total optical power in Watts. Defaults to 1.0.

  • position (tuple[float, float, float]) – Source position (x, y, z) in millimeters. Defaults to (0, 0, 0).

  • is_point_source (bool) – If True, spatial coordinates are set to zero (ideal point source). Defaults to False.

wavelength

Wavelength in µm.

Type:

float

total_power

Total power in W.

Type:

float

mfd_um

Mode Field Diameter in µm.

Type:

float

divergence_deg_1e2

Full 1/e² divergence in degrees.

Type:

float

sigma_spatial_mm

Spatial sampling sigma (mm), equal to w₀/2 converted to mm.

Type:

float

sigma_angular_rad

Angular sampling sigma (rad), equal to half-angle / 2.

Type:

float

is_point_source

Whether to emit from a single point.

Type:

bool

Note

The actual number of rays returned by generate_rays is rounded up to the nearest power of two because Sobol sampling requires this. For example, requesting 1000 rays will generate 1024.

draw(num_rays: int = 5000, propagation_distance: float = 0.1, figsize: tuple[float, float] = (18, 8), cross_spatial: tuple[str, str] = ('x', 'y'), cross_angular: tuple[str, str] = ('L', 'M')) → tuple[Figure, list[Axes]]

Visualize the extended source with a comprehensive 6-panel plot.

This method creates a visualization showing the spatial and angular distributions and propagation characteristics of the rays generated by this source. The plot consists of six panels arranged in a 2x3 grid:

Column 1: Spatial and Angular Distributions - Panel (0,0): XY spatial distribution with intensity color-coding - Panel (1,0): Angular distribution (L vs M direction cosines)

Column 2: Cross-sections - Panel (0,1): Spatial cross-sections (X and Y profiles) - Panel (1,1): Angular cross-sections (L and M profiles)

Column 3: Ray Propagation - Panel (0,2): XZ ray propagation paths with intensity-based coloring - Panel (1,2): YZ ray propagation paths with intensity-based coloring

Parameters:

  • num_rays (int, optional) – Number of rays to generate for visualization. Defaults to 5000.

  • propagation_distance (float, optional) – Distance in mm to propagate rays for path visualization. Defaults to 0.1.

  • figsize (tuple[float, float], optional) – Figure size (width, height) in inches. Defaults to (18, 8).

  • cross_spatial (tuple[str, str], optional) – Spatial cross-section axes. Defaults to (“x”, “y”).

  • cross_angular (tuple[str, str], optional) – Angular cross-section axes. Defaults to (“L”, “M”).

Returns:

Matplotlib figure and list of 6 axes objects.

Return type:

tuple[Figure, list[Axes]]

generate_rays(num_rays: int) → RealRays[source]

Generate rays from the SMF source using Sobol quasi-random sampling.

Produces a ray bundle with Gaussian spatial and angular distributions appropriate for a single-mode fiber. Direction cosines are computed non-paraxially.

Because Sobol sequences require a power-of-two sample count, the actual number of rays returned is 2 ** ceil(log2(num_rays)).

Parameters:

num_rays (int) – Desired number of rays. Must be positive.

Returns:

The generated ray bundle.

Return type:

RealRays

Raises:

ValueError – If num_rays is not a positive integer.