macromax.utils package

This module contains functionality that is not directly related to the rest of the library and can be used independently.

Subpackages

• macromax.utils.display package
  • Submodules
  • macromax.utils.display.colormap module
    • InterpolatedColorMap
      • InterpolatedColorMap.__init__()
      • InterpolatedColorMap.__call__()
      • InterpolatedColorMap.__copy__()
      • InterpolatedColorMap.__eq__()
      • InterpolatedColorMap.copy()
      • InterpolatedColorMap.from_list()
      • InterpolatedColorMap.get_bad()
      • InterpolatedColorMap.get_over()
      • InterpolatedColorMap.get_under()
      • InterpolatedColorMap.is_gray()
      • InterpolatedColorMap.resampled()
      • InterpolatedColorMap.reversed()
      • InterpolatedColorMap.set_bad()
      • InterpolatedColorMap.set_extremes()
      • InterpolatedColorMap.set_gamma()
      • InterpolatedColorMap.set_over()
      • InterpolatedColorMap.set_under()
      • InterpolatedColorMap.with_extremes()
      • InterpolatedColorMap.colorbar_extend
  • macromax.utils.display.complex2rgb module
    • complex2rgb()
  • macromax.utils.display.format_image_axes module
    • format_image_axes()
  • macromax.utils.display.grid2extent module
    • grid2extent()
  • macromax.utils.display.hsv module
    • hsv2rgb()
    • rgb2hsv()
• macromax.utils.ft package
  • Submodules
  • macromax.utils.ft.grid module
    • Grid
      • Grid.__init__()
      • Grid.from_ranges()
      • Grid.ndim
      • Grid.shape
      • Grid.step
      • Grid.center
      • Grid.center_at_index
      • Grid.flat
      • Grid.origin_at_center
      • Grid.as_flat
      • Grid.as_non_flat
      • Grid.as_origin_at_0
      • Grid.as_origin_at_center
      • Grid.swapaxes()
      • Grid.transpose()
      • Grid.project()
      • Grid.first
      • Grid.extent
      • Grid.size
      • Grid.dtype
      • Grid.f
      • Grid.k
      • Grid.__add__()
      • Grid.__mul__()
      • Grid.__rmul__()
      • Grid.__matmul__()
      • Grid.__sub__()
      • Grid.__truediv__()
      • Grid.__neg__()
      • Grid.__len__()
      • Grid.__iter__()
      • Grid.immutable
      • Grid.mutable
      • Grid.__eq__()
      • Grid.multidimensional
      • Grid.__init_subclass__()
      • Grid.count()
      • Grid.index()
    • MutableGrid
      • MutableGrid.__init__()
      • MutableGrid.shape
      • MutableGrid.step
      • MutableGrid.center
      • MutableGrid.flat
      • MutableGrid.origin_at_center
      • MutableGrid.__add__()
      • MutableGrid.__eq__()
      • MutableGrid.__init_subclass__()
      • MutableGrid.__iter__()
      • MutableGrid.__len__()
      • MutableGrid.__matmul__()
      • MutableGrid.__mul__()
      • MutableGrid.__neg__()
      • MutableGrid.__rmul__()
      • MutableGrid.__sub__()
      • MutableGrid.__truediv__()
      • MutableGrid.as_flat
      • MutableGrid.as_non_flat
      • MutableGrid.as_origin_at_0
      • MutableGrid.as_origin_at_center
      • MutableGrid.center_at_index
      • MutableGrid.count()
      • MutableGrid.extent
      • MutableGrid.f
      • MutableGrid.first
      • MutableGrid.from_ranges()
      • MutableGrid.immutable
      • MutableGrid.index()
      • MutableGrid.k
      • MutableGrid.multidimensional
      • MutableGrid.mutable
      • MutableGrid.ndim
      • MutableGrid.project()
      • MutableGrid.size
      • MutableGrid.swapaxes()
      • MutableGrid.transpose()
      • MutableGrid.dtype
      • MutableGrid.__iadd__()
      • MutableGrid.__imul__()
      • MutableGrid.__isub__()
      • MutableGrid.__idiv__()
  • macromax.utils.ft.subpixel module
    • register()
    • roll()
    • roll_ft()
    • Registration
      • Registration.__init__()
      • Registration.shift
      • Registration.ndim
      • Registration.factor
      • Registration.error
      • Registration.image_ft
      • Registration.image
      • Registration.__array__()
      • Registration.original_ft
      • Registration.original
    • Reference
      • Reference.__init__()
      • Reference.ndim
      • Reference.shape
      • Reference.register()

Submodules

macromax.utils.beam module

class macromax.utils.beam.Beam(grid, propagation_axis=None, vacuum_wavenumber=1.0, vacuum_wavelength=None, background_permittivity=1.0, background_refractive_index=None, field=None, field_ft=None)

Bases: object

__init__(grid, propagation_axis=None, vacuum_wavenumber=1.0, vacuum_wavelength=None, background_permittivity=1.0, background_refractive_index=None, field=None, field_ft=None)

Represents the wave equation solution that is propagated using the beam-propagation method. The grid must be one dimension higher than that of the beam sections. The field or field_ft argument specify sections as for the associated BeamSection object.

Parameters:

• grid (Grid) – The regularly-spaced grid at which to calculate the field values. This grid includes the propagation dimension (indicated the propagation_axis argument).

• propagation_axis (Optional[int]) – The propagation axes. Default: -grid.ndim.

• vacuum_wavenumber (Optional[Complex]) – (optional) The vacuum wavenumber in rad/m, can also be specified as wavelength.

• vacuum_wavelength (Optional[Real]) – (optional) Vacuum wavelength, alternative for wavenumber in units of meter.

• background_permittivity (Optional[Complex]) – (optional) The homogeneous background permittivity as a scalar, default 1. Heterogeneous distributions are specified when querying the results from this object.

• background_refractive_index (Optional[Complex]) – (optional) Alternative to the above, the square of the permittivity.

• field (Union[Complex, Sequence, array, Callable[[Union[Complex, Sequence, array], Union[Complex, Sequence, array]], Union[Complex, Sequence, array]], None]) – (optional) The field specification at propagation distance 0 as specified on the transverse dimensions of the grid.

• field_ft (Union[Complex, Sequence, array, Callable[[Union[Complex, Sequence, array], Union[Complex, Sequence, array]], Union[Complex, Sequence, array]], None]) – (optional) Alternative field specification as its fft (not fftshifted).

property grid: Grid

The grid of sample points at which the beam’s field is calculated and at which the material properties are defined.

property propagation_axis: int

The propagation axis index in the polarization vector, i.e. the longitudinal polarization.

property vectorial: bool

Returns True if this is a vectorial beam propagation, and False if it is scalar.

property shape: ndarray

The shape of the returned `field` or `field_ft` array.

property dtype

The data type of the field return in the iterator and by the `Beam.field` method.

beam_section_at_exit(permittivity=None, refractive_index=None)

Propagates the field through the calculation volume and returns the beam section at the exit surface.

Parameters:

• permittivity – (optional) The permittivity distribution within the calculation volume. Default: the background permittivity, unless refractive_index is specified.

• refractive_index – (optional) The refractive index distribution within the calculation volume. Default: the background refractive index, unless permittivity is specified.

Return type:

BeamSection

Returns:

The BeamSection object after propagating through the calculation volume.

__iter__(permittivity=None, refractive_index=None)

Iterator returning BeamSections for propagation in an arbitrary medium (by default homogeneous) A BeamSection object is generated _after_ propagating through each section of material.

Parameters:

• permittivity (Union[Complex, Sequence, array, None]) – (optional) The (complex) permittivity (distribution) that the beam traverses prior to yielding each field-section. This should be a sequence/generator of permittivity slices or None.

• refractive_index (Union[Complex, Sequence, array, None]) – (optional) Alternative specification of the permittivity squared. This should be a sequence/generator of refractive index slices or None.

Return type:

Generator[BeamSection, None, None]

Returns:

A Generator object producing BeamSections.

field(permittivity=None, refractive_index=None, out=None)

Calculates the field at the grid points self.grid for the specified (or default) permittivity / refractive index.

Parameters:

• permittivity (Union[Sequence, Iterable]) – (optional) The 3D permittivity distribution as a sequence or iterable.

• refractive_index (Union[Sequence, Iterable]) – (optional) The 3D refractive index distribution as a sequence or iterable.

• out (Union[Complex, Sequence, array]) – (optional) The output array where to store the result.

Return type:

ndarray

Returns:

A `numpy.ndarray` of which the final four dimensions are polarization, z, y, and x.

__array__()

Returns all field values. This is the same as Beam.field().

Return type:

ndarray

class macromax.utils.beam.BeamSection(grid, propagation_axis=-3, vacuum_wavenumber=1.0, vacuum_wavelength=None, background_permittivity=1.0, background_refractive_index=None, field=None, field_ft=None, dtype=None, vectorial=None)

Bases: object

__init__(grid, propagation_axis=-3, vacuum_wavenumber=1.0, vacuum_wavelength=None, background_permittivity=1.0, background_refractive_index=None, field=None, field_ft=None, dtype=None, vectorial=None)

Represents a single transversal section of the wave equation solution that is propagated using the beam-propagation method. Its main purpose is to propagate the field from one plane to the next using the `propagate(...)` method, for use in the `Beam` class. The field can be scalar or vectorial. In the latter case, the polarization must be represented by axis -4 in the field and field_ft arrays. Singleton dimensions must be added for lower-dimensional calculations.

Parameters:

• grid (Grid) – The regularly-spaced grid at which the field values are defined. This grid can have up to three dimensions. By default, the third dimension from the right is the propagation dimension. If the grid has less than 3 dimensions, new dimensions will be added on the left.

• propagation_axis (int) – The grid index of the propagation axis and that of the longitudinal polarization. Default: -3

• vacuum_wavenumber (Optional[Complex]) – (optional) The vacuum wavenumber in rad/m, can also be specified as wavelength.

• vacuum_wavelength (Optional[Complex]) – (optional) Vacuum wavelength, alternative for wavenumber in units of meter.

• background_permittivity (Optional[Complex]) – (optional) The homogeneous background permittivity as a scalar, default 1. Heterogeneous distributions are specified when querying the results from this object.

• background_refractive_index (Optional[Complex]) – (optional) Alternative to the above, the square of the permittivity.

• field (Union[Complex, Sequence, array, Callable[[Union[Complex, Sequence, array], Union[Complex, Sequence, array]], Union[Complex, Sequence, array]], None]) – (optional) The field specification (at propagation distance 0). If it is vectorial, the polarization axis should be 4th from the right (-4).

• field_ft (Union[Complex, Sequence, array, Callable[[Union[Complex, Sequence, array], Union[Complex, Sequence, array]], Union[Complex, Sequence, array]], None]) – (optional) Alternative field specification as its Fourier transform (not fftshifted). If the number of dimensions of field or field_ft equals that of the grid, a singleton dimension is prepended on the left to indicate a scalar field. Otherwise, the polarization_axis indicates whether this is a vectorial calculation or not. If it is vectorial, the polarization axis should be 4th from the right (-4).

• dtype – (optional) The complex dtype of the returned results. Default: that of field or field_ft.

• vectorial (Optional[bool]) – (optional) Indicates scalar (False) or vectorial = polarized (True) calculations. Default: consisted with the size of the polarization axis of the field or field_ft array.

property grid: Grid

The real space sampling grid.

property transverse_grid: Grid

The real space sampling grid of the transverse slice at the center. Its 3D shape is the same as the full 3D grid except for the propagation axis which has shape 1.

property propagation_axis: int

The propagation axis as a negative index in the inputs and outputs. This also corresponds to the longitudinal polarization.

property polarization_axis: int

The polarization axis as a negative index in the inputs and outputs. This is currently fixed to -4.

property vectorial: bool

Returns True if this is a vectorial beam propagation, and False if it is scalar.

property shape: ndarray

The shape of field (`BeamSection.field` or `BeamSection.field_ft`) of a single slice, including the polarisation dimension. I.e.: [3, 1, y, x], [3, 1, 1, x], [3, 1, 1, 1], [1, 1, y, x], [1, 1, 1, x], [1, 1, 1, 1], [3, z, 1, x], or … Dimensions on the left are added as broadcast.

property ndim: int

The number of dimensions of the values returned by the `BeamSection.field` and `BeamSection.field_ft` methods.

property dtype

The data type of the field return by the `BeamSection.field` and `BeamSection.field_ft` methods.

property vacuum_wavenumber: Real

The vacuum wavenumber of the wave being propagated.

property wavenumber: Real

The wavenumber of the wave being propagated in the background material.

property vacuum_wavelength: Real

The vacuum wavelength of the wave being propagated.

property wavelength: Real

The wavelength of the wave being propagated in the background material.

property background_permittivity: Real

The permittivity of the background medium. This is the permittivity that is assumed between scattering events.

property background_refractive_index: Real

The refractive index of the background medium. This is the refractive index that is assumed between scattering events.

property field: array

The electric field in the current section at the sample points are given by `BeamSection.transverse_grid`. The dimension to the left of that indicates the polarization. Scalar propagation was used if it is a singleton, vectorial propagation otherwise.

__array__()

Returns the current field values. This is the same as BeamSection.field

Return type:

ndarray

property field_ft: array

The electric field in k-space, sampled at the grid specified by `BeamSection.k` (i.e. not fftshifted). The shape of the polarisation dimension on the left (axis -self.grid.ndim-1) will be 3 when doing a vectorial calculation and 1 when doing a scalar calculation.

propagate(distance, permittivity=None, refractive_index=None)

Propagates the beam section forward by a distance distance, optionally through a heterogeneous material with refractive index or permittivity as specified. If no material properties are specified, the homogeneous background medium is assumed. If the propagation distance is negative, time-reversal is assumed. I.e. the phases changes in the opposite direction and attenuation becomes gain.

The current BeamSection is updated and returned.

Parameters:

• distance (float) – The distance (in meters) to propagate forward.

• permittivity (Union[Complex, Sequence, array, Callable[[Union[Complex, Sequence, array], Union[Complex, Sequence, array]], Union[Complex, Sequence, array]], None]) – The permittivity at the spatial grid points or as a function of (y, x).

• refractive_index (Union[Complex, Sequence, array, Callable[[Union[Complex, Sequence, array], Union[Complex, Sequence, array]], Union[Complex, Sequence, array]], None]) – The refractive index at the spatial grid points or as a function of (y, x).

Return type:

BeamSection

Returns:

The BeamSection propagated to the new position.

macromax.utils.dim module

macromax.utils.dim.add(arr, left=None, right=None, ndim=None)

A function that returns a view with additional singleton dimensions on the left or right. This is useful when stacking arrays along a new dimension that is further out to the left, or to broadcast and expand on the left-hand side with an array of an arbitrary number of dimensions on the right-hand side.

Parameters:

• arr (Union[Complex, Sequence, ndarray]) – The original array or sequence of numbers that can be converted to an array.

• left (Optional[int]) – (optional) The number of axes to add on the left-hand side. Default: 0. When negative, singleton dimensions are removed from the left. This will fail if those on the left are not singleton dimensions.

• right (Optional[int]) – (optional) The number of axes to add on the right-hand side. Default: 0. When negative, singleton dimensions are removed from the right. This will fail if those on the right are not singleton dimensions.

• ndim (Optional[int]) – (optional) The total disired number of axes after adding those specified by left or right. The remaining axes are added or removed at the right when right is not specified, if not, on the left when left is not specified. This argument is ignored if both left and right are specified.

Return type:

ndarray

Returns:

A view with ndim == arr.ndim + left + right dimensions, where any singleton dimensions are added or removed on the left or right.

macromax.utils.dim.right_to(arr, ndim)

A function that returns a view with additional singleton dimensions on the right up to a fixed number of dimensions. This is useful to broadcast and expand on the left-hand side with an array of an arbitrary number of dimensions on the right-hand side.

Parameters:

• arr (Union[Complex, Sequence, ndarray]) – The original array or sequence of numbers that can be converted to an array.

• ndim (int) – The total number of axes of the returned view.

Return type:

ndarray

Returns:

A view with ndim == arr.ndim + right dimensions, where any singleton dimensions are added or removed on the right.

macromax.utils.dim.left_to(arr, ndim)

A function that returns a view with additional singleton dimensions on the left up to a fixed number of dimensions. This is useful when stacking arrays along a new dimension that is further out to the left.

Parameters:

• arr (Union[Complex, Sequence, ndarray]) – The original array or sequence of numbers that can be converted to an array.

• ndim (int) – (optional) The total number of axes of the returned view.

Return type:

ndarray

Returns:

A view with ndim == arr.ndim + left dimensions, where any singleton dimensions are added or removed on the left.

macromax.utils.dim.to_axis(arr, axis=0, ndim=None)

Returns a view in which the first axis of the original array is at the target index. Negative indices count back from the right-most dimension in the view to the last axis of the original array. The total number of dimensions of the view can optionally be specified. This is useful to orient vectors along a desired dimensions.

Parameters:

• arr (Union[Complex, Sequence, ndarray]) – the input array

• axis (int) – the target axis for the first axis of the original array in the target view (default: 0) When negative values are specified, the axes are counted from the right-hand side to the last axis of the original array.

• ndim (Optional[int]) – the number of desired dimensions. Default: max(axis, 1-axis) + arr.ndim

Return type:

ndarray

Returns:

an n-dimensional array view with all-but-one singleton dimension

macromax.utils.round125 module

macromax.utils.round125.round125(values)

Rounds numbers to the nearest 0, 1x10^n, 2x10^n or 5x10^n for display.

Parameters:

values (Union[int, float, Sequence, ndarray]) – a number, a list of numbers, or an nd-array

Return type:

ndarray | float | int

Returns:

The rounded values as floating point values.