emitter_geometry

Reusable emitter geometry generators.

mqed.utils.emitter_geometry.equatorial_ring_nearest_neighbor_chord_nm(emitter_count: int, emitter_radius_nm: float) → float

Return the nearest-neighbor chord distance for an equatorial ring.

Parameters:

• emitter_count – Number of emitters in the ring. Must be a positive integer.

• emitter_radius_nm – Ring radius in nanometers. Must be finite and positive.

Returns:

Nearest-neighbor chord distance in nanometers. For one emitter, returns 0.0 because there is no distinct neighbor.

mqed.utils.emitter_geometry.equatorial_ring_positions_orientations_nm(emitter_count: int, emitter_radius_nm: float, z_nm: float = 0.0, phase_offset_deg: float = 0.0, orientation: str = 'orthoradial') → Tuple[numpy.ndarray, numpy.ndarray]

Generate positions and dipole orientations for an equatorial ring.

Emitters are placed in the xy plane with angles phase_offset_deg + 360*j/emitter_count for j = 0..N-1. The endpoint is excluded, so arbitrary N produces evenly spaced points without a duplicate at 360 degrees.

Parameters:

• emitter_count – Number of emitters in the ring. Must be a positive integer.

• emitter_radius_nm – Ring radius in nanometers. Must be finite and positive.

• z_nm – Shared z coordinate in nanometers. Must be finite.

• phase_offset_deg – Angular phase offset in degrees. Must be finite.

• orientation – Orientation mode. "orthoradial" gives local azimuthal unit vectors [-sin(phi), cos(phi), 0]. "radial" gives outward radial unit vectors [cos(phi), sin(phi), 0]. "out_of_plane" gives the same unit vector [0, 0, 1] for every emitter, normal to the equatorial ring plane.

Returns:

Tuple (positions_nm, orientations) where both arrays have shape (emitter_count, 3) and dtype float.

Raises:

ValueError – If any parameter is invalid or the orientation mode is unsupported.

mqed.utils.emitter_geometry.generate_equatorial_ring_from_config(ring_config: Mapping[str, object]) → Tuple[numpy.ndarray, numpy.ndarray]

Generate equatorial-ring positions and orientations from a config mapping.

Parameters:

ring_config – Mapping containing emitter_count, radius settings, and optional z_nm, phase_offset_deg, and orientation keys.

Returns:

Tuple (positions_nm, orientations) with shape (N, 3).

mqed.utils.emitter_geometry.normalize_orientation_vectors(vectors: numpy.ndarray, expected_count: int, allow_single_vector: bool = False) → numpy.ndarray

Validate and normalize orientation vectors without norm overflow.

Each row is first scaled by its largest absolute component before its Euclidean norm is evaluated. This keeps very large or very small finite vectors numerically stable while preserving their direction.

Parameters:

• vectors – Orientation vector or array of vectors.

• expected_count – Required number of output rows.

• allow_single_vector – If true, a single shape-(3,) vector is repeated for every emitter.

Returns:

Finite unit vectors with shape (expected_count, 3).

Raises:

ValueError – If the shape is invalid or any vector is non-finite or zero.

mqed.utils.emitter_geometry.resolve_equatorial_ring_radius_nm(ring_config: Mapping[str, object]) → float

Resolve an equatorial-ring radius from explicit or sphere-gap settings.

emitter_radius_nm may be supplied directly. Alternatively, sphere_radius_nm plus emitter_surface_gap_nm derives the radius as sphere_radius_nm + emitter_surface_gap_nm. If both forms are supplied, they must agree. A positive exterior gap is required whenever sphere geometry is used because emitters exactly on the boundary are delicate for strict-region Mie calculations.

Parameters:

ring_config – Mapping with emitter_radius_nm or both sphere_radius_nm and emitter_surface_gap_nm.

Returns:

Ring radius in nanometers.

Raises:

ValueError – If radius settings are missing, non-finite, non-positive, or inconsistent.