Phase

class BasePhaseProfile[source]

Bases: ABC

Abstract base class for defining phase profiles on a surface.

This class defines the interface that all phase profile strategies must implement. It uses a registry pattern to handle serialization and deserialization, allowing for easy extension with custom phase profiles.

property efficiency: float

The diffraction efficiency of the phase profile.

Returns:: The efficiency, a value between 0 and 1.

classmethod from_dict(data: dict) → BasePhaseProfile[source]

Deserializes a phase profile from a dictionary.

Parameters:: data – A dictionary representation of a phase profile.
Returns:: An instance of a BasePhaseProfile subclass.
Raises:: ValueError – If the phase_type is unknown.

abstract get_gradient(x: be.Array, y: be.Array, wavelength: be.Array) → tuple[be.Array, be.Array, be.Array][source]

Calculates the gradient of the phase at coordinates (x, y).

Parameters:

x – The x-coordinates of the points of interest.
y – The y-coordinates of the points of interest.

Returns:

A tuple containing the x, y, and z components of the phase gradient (d_phi/dx, d_phi/dy, d_phi/dz).

abstract get_paraxial_gradient(y: be.Array, wavelength: be.Array) → be.Array[source]

Calculates the paraxial phase gradient at y-coordinate.

This is the gradient d_phi/dy evaluated at x=0.

Parameters:: y – The y-coordinates of the points of interest.
Returns:: The paraxial phase gradient at each y-coordinate.

abstract get_phase(x: be.Array, y: be.Array, wavelength: be.Array) → be.Array[source]

Calculates the phase added by the profile at coordinates (x, y).

Parameters:

x – The x-coordinates of the points of interest.
y – The y-coordinates of the points of interest.

Returns:

The phase at each (x, y) coordinate.

to_dict() → dict[source]

Serializes the phase profile to a dictionary.

Returns:: A dictionary representation of the phase profile.

class ConstantPhaseProfile(phase: float = 0.0)[source]

Bases: BasePhaseProfile

A phase profile that is constant everywhere.

This class represents a phase profile that has a constant value and zero gradient at all points. It is useful for representing surfaces that have no phase contribution.

Parameters:: phase (float, optional) – The constant phase value. Defaults to 0.0.

property efficiency: float

The diffraction efficiency of the phase profile.

Returns:: The efficiency, a value between 0 and 1.

classmethod from_dict(data: dict) → ConstantPhaseProfile[source]

Deserializes a phase profile from a dictionary.

Parameters:: data – A dictionary representation of a phase profile.
Returns:: An instance of a ConstantPhaseProfile.

get_gradient(x: be.Array, y: be.Array, wavelength: be.Array = None) → tuple[be.Array, be.Array, be.Array][source]

Calculates the gradient of the phase at coordinates (x, y).

Parameters:

x – The x-coordinates of the points of interest.
y – The y-coordinates of the points of interest.

Returns:

A tuple containing the x, y, and z components of the phase gradient, which are always zero for this profile.

get_paraxial_gradient(y: be.Array, wavelength: be.Array = None) → be.Array[source]

Calculates the paraxial phase gradient at y-coordinate.

This is the gradient d_phi/dy evaluated at x=0.

Parameters:: y – The y-coordinates of the points of interest.
Returns:: The paraxial phase gradient at each y-coordinate, which is always zero for this profile.

get_phase(x: be.Array, y: be.Array, wavelength: be.Array = None) → be.Array[source]

Calculates the phase added by the profile at coordinates (x, y).

Parameters:

x – The x-coordinates of the points of interest.
y – The y-coordinates of the points of interest.

Returns:

The phase at each (x, y) coordinate.

phase_type = 'constant'

to_dict() → dict[source]

Serializes the phase profile to a dictionary.

Returns:: A dictionary representation of the phase profile.

class GridPhaseProfile(x_coords: be.Array, y_coords: be.Array, phase_grid: be.Array)[source]

Bases: BasePhaseProfile

A phase profile defined by a grid of phase values.

This class interpolates the phase and its gradient at arbitrary points using the active backend.

Parameters:

x_coords (be.Array) – The x-coordinates of the grid points.
y_coords (be.Array) – The y-coordinates of the grid points.
phase_grid (be.Array) – The phase values at the grid points. The shape must be (len(y_coords), len(x_coords)).

property efficiency: float

The diffraction efficiency of the phase profile.

Returns:: The efficiency, a value between 0 and 1.

classmethod from_dict(data: dict) → GridPhaseProfile[source]

Deserializes a phase profile from a dictionary.

Parameters:: data – A dictionary representation of a phase profile.
Returns:: An instance of a BasePhaseProfile subclass.
Raises:: ValueError – If the phase_type is unknown.

get_gradient(x: be.Array, y: be.Array, wavelength: be.Array = None) → tuple[be.Array, be.Array, be.Array][source]

Calculates the gradient of the phase at coordinates (x, y).

Parameters:

x – The x-coordinates of the points of interest.
y – The y-coordinates of the points of interest.

Returns:

A tuple containing the x, y, and z components of the phase gradient (d_phi/dx, d_phi/dy, d_phi/dz).

get_paraxial_gradient(y: be.Array, wavelength: be.Array = None) → be.Array[source]

Calculates the paraxial phase gradient at y-coordinate.

This is the gradient d_phi/dy evaluated at x=0.

Parameters:: y – The y-coordinates of the points of interest.
Returns:: The paraxial phase gradient at each y-coordinate.

get_phase(x: be.Array, y: be.Array, wavelength: be.Array = None) → be.Array[source]

Calculates the phase added by the profile at coordinates (x, y).

Parameters:

x – The x-coordinates of the points of interest.
y – The y-coordinates of the points of interest.

Returns:

The phase at each (x, y) coordinate.

phase_type = 'grid'

to_dict() → dict[source]

Serializes the phase profile to a dictionary.

Returns:: A dictionary representation of the phase profile.

class HeightProfile(x_coords: be.Array, y_coords: be.Array, height_map: be.Array)[source]

Bases: BasePhaseProfile

A phase profile defined by a height map and a dispersive material.

The phase is calculated as:: phi(x, y, λ) = (2π / λ) * (n_post(λ) - n_pre(λ)) * h(x, y)

Parameters:

x_coords (be.Array) – X-coordinates of the height map grid.
y_coords (be.Array) – Y-coordinates of the height map grid.
height_map (be.Array) – Height values at grid points with shape (len(y_coords), len(x_coords)).

property efficiency: float

The diffraction efficiency of the phase profile.

Returns:: The efficiency, a value between 0 and 1.

classmethod from_dict(data: dict) → HeightProfile[source]

Deserializes a phase profile from a dictionary.

Parameters:: data – A dictionary representation of a phase profile.
Returns:: An instance of a BasePhaseProfile subclass.
Raises:: ValueError – If the phase_type is unknown.

get_gradient(x: be.Array, y: be.Array, wavelength: be.Array) → tuple[be.Array, be.Array, be.Array][source]

Calculates the gradient of the phase at coordinates (x, y).

Parameters:

x – The x-coordinates of the points of interest.
y – The y-coordinates of the points of interest.

Returns:

A tuple containing the x, y, and z components of the phase gradient (d_phi/dx, d_phi/dy, d_phi/dz).

get_paraxial_gradient(y: be.Array, wavelength: be.Array) → be.Array[source]

Calculates the paraxial phase gradient at y-coordinate.

This is the gradient d_phi/dy evaluated at x=0.

Parameters:: y – The y-coordinates of the points of interest.
Returns:: The paraxial phase gradient at each y-coordinate.

get_phase(x: be.Array, y: be.Array, wavelength: be.Array) → be.Array[source]

Calculates the phase added by the profile at coordinates (x, y).

Parameters:

x – The x-coordinates of the points of interest.
y – The y-coordinates of the points of interest.

Returns:

The phase at each (x, y) coordinate.

phase_type = 'height_profile'

to_dict() → dict[source]

Serializes the phase profile to a dictionary.

Returns:: A dictionary representation of the phase profile.

class LinearGratingPhaseProfile(period: float, angle: float = 0.0, order: int = 1, efficiency: float = 1.0)[source]

Bases: BasePhaseProfile

A linear grating phase profile.

This profile defines a constant phase gradient across the surface, representing a simple transmission or reflection grating.

The phase is defined as: φ(x, y) = K_x * x + K_y * y where (K_x, K_y) is the grating wavevector.

The grating vector is defined by its magnitude |K| = 2π / period and its angle (theta) relative to the positive x-axis. K_x = (2π / period) * cos(angle) K_y = (2π / period) * sin(angle)

Parameters:

period (float) – The spatial period of the grating in mm. Must be positive.
angle (float, optional) – The angle of the grating’s wavevector (direction of phase gradient) in radians, measured counter-clockwise from the positive x-axis. Defaults to 0, which creates grooves parallel to the y-axis.
order (int, optional) – The diffraction order. Defaults to 1.
efficiency (float, optional) – The diffraction efficiency for the specified order, between 0 and 1. Defaults to 1.0.

property efficiency: float

The diffraction efficiency of the phase profile.

Returns:: The efficiency, a value between 0 and 1.

classmethod from_dict(data: dict) → LinearGratingPhaseProfile[source]

Deserializes a phase profile from a dictionary.

Parameters:: data – A dictionary representation of a phase profile.
Returns:: An instance of a LinearGratingPhaseProfile.

get_gradient(x: be.Array, y: be.Array, wavelength: be.Array = None) → tuple[be.Array, be.Array, be.Array][source]

Calculates the gradient of the phase at coordinates (x, y).

For a linear grating, the gradient (d_phi/dx, d_phi/dy) is constant, and d_phi/dz is zero.

Parameters:

x – The x-coordinates of the points of interest. Used for shape.
y – The y-coordinates of the points of interest. Used for shape.

Returns:

A tuple containing the x, y, and z components of the phase gradient (K_x, K_y, 0), broadcast to the shape of the input coordinates.

get_paraxial_gradient(y: be.Array) → be.Array[source]

Calculates the paraxial phase gradient at y-coordinate.

This is the gradient d_phi/dy evaluated at x=0. For a linear grating, this is constant and equal to K_y.

Parameters:: y – The y-coordinates of the points of interest. Used for shape.
Returns:: The paraxial phase gradient (K_y) at each y-coordinate.

get_phase(x: be.Array, y: be.Array, wavelength: be.Array = None) → be.Array[source]

Calculates the phase added by the profile at coordinates (x, y).

Parameters:

x – The x-coordinates of the points of interest.
y – The y-coordinates of the points of interest.

Returns:

The phase at each (x, y) coordinate.

phase_type = 'linear_grating'

to_dict() → dict[source]

Serializes the phase profile to a dictionary.

Returns:: A dictionary representation of the phase profile.

class RadialPhaseProfile(coefficients: list[float])[source]

Bases: BasePhaseProfile

A radially symmetric phase profile defined by a polynomial in r.

The phase is defined as a sum of even powers of the radial coordinate r: φ(r) = a_2 * r^2 + a_4 * r^4 + …

Parameters:: coefficients (List[float]) – A list of coefficients [a_2, a_4, …].

property efficiency: float

The diffraction efficiency of the phase profile.

Returns:: The efficiency, a value between 0 and 1.

classmethod from_dict(data: dict) → RadialPhaseProfile[source]

Deserializes a phase profile from a dictionary.

Parameters:: data – A dictionary representation of a phase profile.
Returns:: An instance of a RadialPhaseProfile.

get_gradient(x: be.Array, y: be.Array, wavelength: be.Array = None) → tuple[be.Array, be.Array, be.Array][source]

Calculates the gradient of the phase at coordinates (x, y).

Parameters:

x – The x-coordinates of the points of interest.
y – The y-coordinates of the points of interest.

Returns:

A tuple containing the x, y, and z components of the phase gradient (d_phi/dx, d_phi/dy, 0).

get_paraxial_gradient(y: be.Array, wavelength: be.Array = None) → be.Array[source]

Calculates the paraxial phase gradient at y-coordinate.

This is the gradient d_phi/dy evaluated at x=0.

Parameters:: y – The y-coordinates of the points of interest.
Returns:: The paraxial phase gradient at each y-coordinate.

get_phase(x: be.Array, y: be.Array, wavelength: be.Array = None) → be.Array[source]

Calculates the phase added by the profile at coordinates (x, y).

Parameters:

x – The x-coordinates of the points of interest.
y – The y-coordinates of the points of interest.

Returns:

The phase at each (x, y) coordinate.

phase_type = 'radial'

to_dict() → dict[source]

Serializes the phase profile to a dictionary.

Returns:: A dictionary representation of the phase profile.