Table of Contents

Class ElementaryFieldScalingPropagationOperators

Namespace
VirtualLabAPI.Core.FreeSpacePropagation
Assembly
VirtualLabAPI.dll

This class contains a number of static member functions performing well-known elementary wave propagation operators. In difference to the ElementaryPropagationOperators class all functions automatically change the number of sampling points and the sampling distance to avoid numerical errors. Additionally some functions are provided that can estimate the necessary number of sampling points and the sampling distance to avoid numerical errors.

public class ElementaryFieldScalingPropagationOperators
Inheritance
ElementaryFieldScalingPropagationOperators
Inherited Members

Methods

FarFieldPropagation(ComplexAmplitude, double, Complex, double, bool, double, VectorD, eApertureShape, double, bool, double, int, SamplingParameters, out bool, InterpolationMethod, FarFieldPropagationMode, bool, SpreadSheetObjectUsedIn, CancellationToken?)

Performs a far field propagation without paraxial approximation. The far field approximation of the Rayleigh-Sommerfeld propagation is used. Just for paraxial wave the far field is the Fourier Transform of the waist of the wave. In general it is the Fourier Transform plus a coordinate transformation. If a propagation between two far field points is performs it is assumed that the SphericalPhaseRadius information is equal to the distance from the waist.

public static ComplexAmplitude FarFieldPropagation(ComplexAmplitude ca, double distance, Complex n, double accuracyFactor, bool automaticOutputFieldSizeShape, double outputFieldSizeFactor, VectorD outputFieldFieldSize, BasicParameter.eApertureShape outputFieldShape, double outputFieldBorderWidth, bool automaticOutputFieldSampling, double outputFieldSamplingFactor, int outputFieldEmbedFrameWidth, SamplingParameters outputFieldSamplingParameters, out bool areNumericalErrors, InterpolationMethod interpolationMethod, FarFieldPropagationMode farFieldPropagationMode, bool isParaxialApproximation, SpreadSheetObjectUsedIn usedIn, CancellationToken? cancellationToken = null)

Parameters

ca ComplexAmplitude

ComplexAmplitude to propagate.

distance double

Propagation distance.

n Complex

Complex refractive index of media in which propagation is applied.

accuracyFactor double

The accuracy factor. A larger factor leads to more accurate results but to higher computational effort.

automaticOutputFieldSizeShape bool

If true the output field size, shape and border width are determined by VirtualLab automatically. Otherwise the values can be specified using the outputFieldSize, outputFieldShape and outputFieldBorderWidth parameters.

outputFieldSizeFactor double

In case of automaticOutputFieldSizeShape VirtualLab estimates the correct size of the propagated field. The resulting value is multiplied by this factor.

outputFieldFieldSize VectorD

The diameter of the output field in meters. The diameter is measured before the beginning of the border decay of amplitude.

outputFieldShape BasicParameter.eApertureShape

The shape of the field.

outputFieldBorderWidth double

The width of the borders of the field relative to the field diameter. The border width is measured between the begin of the amplitude decay and the zero position of the field.

automaticOutputFieldSampling bool

Enables automatic determination of the required array size and number of sampling points of the output field to minimize numerical errors. Additionally the user may use the outputFieldSamplingFactor to additionally increase or reduce the number of sampling points. The array size of the output field will be calculated from the estimation of the field size multiplied by the outputFieldSizeFactor plus the outputFieldBorderWidth multiplied by the field size plus the embedFrameWidth multiplied by the sampling distance. If automaticOutputFieldSampling is false the outputFieldSamplingParameters will be used.

outputFieldSamplingFactor double

If automaticOutputFieldSampling is true VirtualLab estimates the number of sampling points of the output field and multiplies the value by outputFieldSamplingFactor.

outputFieldEmbedFrameWidth int

If automaticOutputFieldSampling is false additionally a frame with dark pixels (amplitude equals zero) around the field can be added. This embed frame is required since the continuous field distribution can be reconstructed using a sinc interpolation. This interpolation will introduce small sized loops that are larger than the numerical field size. To take this side loops at least partially into account during the interpolation this embed frame is required. The extension of this frame in sampling points can be specified by this parameter.

outputFieldSamplingParameters SamplingParameters

The sampling parameters of the output field. Normally these sampling parameters should be equal to the inputFieldSamplingParameters but the use may change it to any other value.

areNumericalErrors bool

Returns true if the user defined settings of the numerical accuracy parameter may caused numerical errors during the propagation. This is typically the case if numericalAccuracyFactor is smaller than one.

interpolationMethod InterpolationMethod

A coordinate transform is performed during the propagation. To do this an interpolation is necessary. This parameters specifies the used point wise interpolation method.

farFieldPropagationMode FarFieldPropagationMode

The far field propagation mode tells the function if a propagation from the waist to the far field or vice versa should be performed.

isParaxialApproximation bool

If true the far field propagation will be calculated in non-paraxial approximation (Fraunhofer propagation).

usedIn SpreadSheetObjectUsedIn

TODO

cancellationToken CancellationToken?

Optional token for cooperative task cancellation.

Returns

ComplexAmplitude

Result of operation.

FarFieldPropagation(HarmonicFieldsSet, double, double, bool, double, VectorD, eApertureShape, double, bool, double, int, SamplingParameters, out bool, InterpolationMethod, FarFieldPropagationMode, bool, SpreadSheetObjectUsedIn)

Performs a far field propagation without paraxial approximation. The far field approximation of the Rayleigh-Sommerfeld propagation is used. Just for paraxial wave the far field is the Fourier Transform of the waist of the wave. In general it is the Fourier Transform plus a coordinate transformation. If a propagation between two far field points is performs it is assumed that the SphericalPhaseRadius information is equal to the distance from the waist.

public static HarmonicFieldsSet FarFieldPropagation(HarmonicFieldsSet hfs, double distance, double accuracyFactor, bool automaticOutputFieldSizeShape, double outputFieldSizeFactor, VectorD outputFieldFieldSize, BasicParameter.eApertureShape outputFieldShape, double outputFieldBorderWidth, bool automaticOutputFieldSampling, double outputFieldSamplingFactor, int outputFieldEmbedFrameWidth, SamplingParameters outputFieldSamplingParameters, out bool areNumericalErrors, InterpolationMethod interpolationMethod, FarFieldPropagationMode farFieldPropagationMode, bool isParaxialApproximation, SpreadSheetObjectUsedIn usedIn)

Parameters

hfs HarmonicFieldsSet

\markAsCode{HarmonicFieldsSet} to propagate.

distance double

Propagation distance.

accuracyFactor double

The accuracy factor. A larger factor leads to more accurate results but to higher computational effort.

automaticOutputFieldSizeShape bool

If true the output field size, shape and border width are determined by VirtualLab automatically. Otherwise the values can be specified using the outputFieldSize, outputFieldShape and outputFieldBorderWidth parameters.

outputFieldSizeFactor double

In case of automaticOutputFieldSizeShape VirtualLab estimates the correct size of the propagated field. The resulting value is multiplied by this factor.

outputFieldFieldSize VectorD

The diameter of the output field in meters. The diameter is measured before the beginning of the border decay of amplitude.

outputFieldShape BasicParameter.eApertureShape

The shape of the field.

outputFieldBorderWidth double

The width of the borders of the field relative to the field diameter. The border width is measured between the begin of the amplitude decay and the zero position of the field.

automaticOutputFieldSampling bool

Enables automatic determination of the required array size and number of sampling points of the output field to minimize numerical errors. Additionally the user may use the outputFieldSamplingFactor to additionally increase or reduce the number of sampling points. The array size of the output field will be calculated from the estimation of the field size multiplied by the outputFieldSizeFactor plus the outputFieldBorderWidth multiplied by the field size plus the embedFrameWidth multiplied by the sampling distance. If automaticOutputFieldSampling is false the outputFieldSamplingParameters will be used.

outputFieldSamplingFactor double

If automaticOutputFieldSampling is true VirtualLab estimates the number of sampling points of the output field and multiplies the value by outputFieldSamplingFactor.

outputFieldEmbedFrameWidth int

If automaticOutputFieldSampling is false additionally a frame with dark pixels (amplitude equals zero) around the field can be added. This embed frame is required since the continuous field distribution can be reconstructed using a sinc interpolation. This interpolation will introduce small sized loops that are larger than the numerical field size. To take this side loops at least partially into account during the interpolation this embed frame is required. The extension of this frame in sampling points can be specified by this parameter.

outputFieldSamplingParameters SamplingParameters

The sampling parameters of the output field. Normally these sampling parameters should be equal to the inputFieldSamplingParameters but the use may change it to any other value.

areNumericalErrors bool

Returns true if the user defined settings of the numerical accuracy parameter may caused numerical errors during the propagation. This is typically the case if numericalAccuracyFactor is smaller than one.

interpolationMethod InterpolationMethod

A coordinate transform is performed during the propagation. To do this an interpolation is necessary. This parameters specifies the used point wise interpolation method.

farFieldPropagationMode FarFieldPropagationMode

The far field propagation mode tells the function if a propagation from the waist to the far field or vice versa should be performed.

isParaxialApproximation bool

If true the far field propagation will be calculated in non-paraxial approximation (Fraunhofer propagation).

usedIn SpreadSheetObjectUsedIn

Obsolete parameter.

Returns

HarmonicFieldsSet

Result of operation.

Frt(ComplexAmplitude, double, bool, double, VectorD)

Propagates given ComplexAmplitude by the specified distance by computing the Fresnel transform. The function can interpolate the complex amplitude by sinc-interpolation to avoid numerical errors. If a spherical phase factor is present the function tries to perform a Fresnel Propagation to the waist by a distance -SphericalPhaseRadius and a Fresnel Propagation by a distance SphericalPhaseRadius + distance to reduce numerical errors.

public static ComplexAmplitude Frt(ComplexAmplitude ca, double distance, bool automaticInputFieldSampling, double accuracyFactor, VectorD inputFieldSamplingDistance)

Parameters

ca ComplexAmplitude

ComplexAmplitude to be propagated.

distance double

Propagation distance in meters.

automaticInputFieldSampling bool

Enables automatic determination of the required array size and number of sampling points of the input field to minimize numerical errors. Additionally the user may use the accuracyFactor to additionally increase or reduce the number of sampling points and array size. If automaticInputFieldSampling is false the inputFieldSamplingParameters will be used to modify the sampling parameters of the input field before the propagation.

accuracyFactor double

The accuracy factor used in case of automatic input field sampling.

inputFieldSamplingDistance VectorD

The function modifies the sampling parameters of the input field before the propagation to the values specified here. This parameter allows to modify the input field sampling distance to user defined values. To get an estimation for input field sampling parameters please use the GetSpwSamplingParameters function.

Returns

ComplexAmplitude

Result of operation.

Frt(ComplexAmplitude, double, Complex, bool, double, VectorD, bool, double, VectorD, eApertureShape, double, bool, double, int, SamplingParameters, out bool, CancellationToken?)

Propagates the given ComplexAmplitude by the specified distance by computing the Fresnel propagation. The function modifies the sampling distance of the input field specified in the inputFieldSamplingDistance parameter before the propagation in order to reduce numerical errors. The modification can be done by user or automatically Additionally the user may specify the output field sampling parameters and the field size, shape and border width of the output field. If a spherical phase factor is present the function tries to perform a Fresnel Propagation to the waist by a distance \(-SphericalPhaseRadius\) and a Fresnel Propagation by a distance \(SphericalPhaseRadius + distance\) to reduce numerical errors.

public static ComplexAmplitude Frt(ComplexAmplitude ca, double distance, Complex n, bool automaticInputFieldSampling, double inputFieldSamplingFactor, VectorD inputFieldSamplingDistance, bool automaticOutputFieldSizeShape, double outputFieldSizeFactor, VectorD outputFieldFieldSize, BasicParameter.eApertureShape outputFieldShape, double outputFieldBorderWidth, bool automaticOutputFieldSampling, double outputFieldSamplingFactor, int outputFieldEmbedFrameWidth, SamplingParameters outputFieldSamplingParameters, out bool areNumericalErrors, CancellationToken? cancellationToken = null)

Parameters

ca ComplexAmplitude

The field to propagate.

distance double

The propagation distance.

n Complex

The refractive index of the homogeneous medium in that the field propagates.

automaticInputFieldSampling bool

Enables automatic determination of the required number of sampling points and sampling distance of the input field to minimize numerical errors. Additionally the user may use the inputFieldSamplingFactor to additionally increase or reduce the number of sampling points per array size. If automaticInputFieldSampling is false the inputFieldSamplingDistance will be used to modify the sampling parameters of the input field before the propagation.

inputFieldSamplingFactor double

In case of automaticInputFieldSampling VirtualLab estimates the required number of sampling points per array size to minimize numerical errors. The resulting estimation of the number of sampling points will be multiplied by this factor while the array size is kept constant.

inputFieldSamplingDistance VectorD

The function modifies the sampling distance of the input field before the propagation to the value specified here. This parameter allows to modify the input field sampling distance to user defined values. To get an estimation for input field sampling distance please use the GetFrtSamplingParameters function.

automaticOutputFieldSizeShape bool

If true the output field size, shape and border width are determined by VirtualLab automatically. Otherwise the values can be specified using the outputFieldSize, outputFieldShape and outputFieldBorderWidth parameters.

outputFieldSizeFactor double

In case of automaticOutputFieldSizeShape VirtualLab estimates the correct size of the propagated field. The resulting value is multiplied by this factor.

outputFieldFieldSize VectorD

The diameter of the output field in meters. The diameter is measured before the beginning of the border decay of amplitude.

outputFieldShape BasicParameter.eApertureShape

The shape of the field.

outputFieldBorderWidth double

The width of the borders of the field relative to the field diameter. The border width is measured between the begin of the amplitude decay and the zero position of the field.

automaticOutputFieldSampling bool

Enables automatic determination of the required array size and number of sampling points of the output field to minimize numerical errors. Additionally the user may use the outputFieldSamplingFactor to additionally increase or reduce the number of sampling points. The array size of the output field will be calculated from the estimation of the field size multiplied by the outputFieldSizeFactor plus the outputFieldBorderWidth multiplied by the field size plus the embedFrameWidth multiplid by the sampling distance. If automaticOutputFieldSampling is false the outputFieldSamplingParameters will be used.

outputFieldSamplingFactor double

If automaticOutputFieldSampling is true VirtualLab estimates the number of sampling points of the output field and multiplies the value by outputFieldSamplingFactor.

outputFieldEmbedFrameWidth int

If automaticOutputFieldSampling is false additionally a frame with dark pixels (amplitude equals zero) around the field can be added. This embed frame is required since the continuous field distribution can be reconstructed using a sinc interpolation. This interpolation will introduce small sized loops that are larger than the numerical field size. To take this side loops at least partially into account during the interpolation this embed frame is required. The extension of this frame in sampling points can be specified by this parameter.

outputFieldSamplingParameters SamplingParameters

The sampling parameters of the output field. Normally these sampling parameters should be equal to the inputFieldSamplingParameters but the use may change it to any other value.

areNumericalErrors bool

True if the user defined settings of the input field sampling parameters may caused numerical errors during the propagation. This parameter is just set if automaticInputFieldSampling is false.

cancellationToken CancellationToken?

Optional token for cooperative task cancellation.

Returns

ComplexAmplitude

The propagated field.

Frt(ComplexAmplitude, double, Complex, double, out bool)

Propagates given ComplexAmplitude by the specified distance by computing the Fresnel transform. The function can interpolate the complex amplitude by sinc-interpolation to avoid numerical errors. If a spherical phase factor is present the function tries to perform a Fresnel Propagation to the waist by a distance -SphericalPhaseRadius and a Fresnel Propagation by a distance SphericalPhaseRadius + distance to reduce numerical errors.

public static ComplexAmplitude Frt(ComplexAmplitude ca, double distance, Complex n, double accuracyFactor, out bool areNumericalErrors)

Parameters

ca ComplexAmplitude

ComplexAmplitude to be propagated.

distance double

Propagation distance in meters.

n Complex

Complex refractive index of media in which propagation is applied.

accuracyFactor double

VirtualLab estimates and modifies the number of sampling points of the input field before the propagation in order to reduce numerical errors. The estimated number of sampling points is multiplied by this factor to to increase or decrease numerical accuracy.

areNumericalErrors bool

True if numerical errors may appear in the propagated field. This warning appears if samplingFactor is smaller than one.

Returns

ComplexAmplitude

Result of operation.

Frt(ComplexAmplitude, double, Complex, VectorD, double, out bool, CancellationToken?)

Propagates given ComplexAmplitude by the specified distance by computing the Fresnel transform. The function can interpolate the complex amplitude by sinc-interpolation to avoid numerical errors. If a spherical phase factor is present the function tries to perform a Fresnel Propagation to the waist by a distance -SphericalPhaseRadius and a Fresnel Propagation by a distance SphericalPhaseRadius + distance to reduce numerical errors. The desired output field size of the propagated field must be specified by the user.

public static ComplexAmplitude Frt(ComplexAmplitude ca, double distance, Complex n, VectorD outputFieldSize, double accuracyFactor, out bool areNumericalErrors, CancellationToken? cancellationToken = null)

Parameters

ca ComplexAmplitude

ComplexAmplitude to be propagated.

distance double

Propagation distance in meters.

n Complex

Complex refractive index of media in which propagation is applied.

outputFieldSize VectorD

The diameter of the output field of the propagation. It should be large enough to contain at least 99% of the power of the output field. the output field diameter is used to control the simulation accuracy of the propagation.

accuracyFactor double

VirtualLab estimates and modifies the number of sampling points of the input field before the propagation in order to reduce numerical errors. The estimated number of sampling points is multiplied by this factor to to increase or decrease numerical accuracy.

areNumericalErrors bool

True if numerical errors may appear in the propagated field. This warning appears if samplingFactor is smaller than one.

cancellationToken CancellationToken?

Optional token for cooperative task cancellation.

Returns

ComplexAmplitude

Result of operation.

GetFarFieldPropagationArraySize(ComplexAmplitude, double, Complex, FarFieldPropagationMode, bool)

Calculates the optimal sampling distance and number of sampling points of the propagated field. The minimum number of sampling points per output plane diameter is 20 × 20.

public static VectorD GetFarFieldPropagationArraySize(ComplexAmplitude ca, double distance, Complex n, FarFieldPropagationMode farFieldPropagationMode, bool isParaxialApproximation)

Parameters

ca ComplexAmplitude

ComplexAmplitude to propagate.

distance double

Propagation distance.

n Complex

Complex refractive index of media in which propagation is applied.

farFieldPropagationMode FarFieldPropagationMode

The far field propagation mode tells the function if a propagation from the waist to the far field or vice versa should be performed.

isParaxialApproximation bool

If true the far field propagation will be calculated in paraxial approximation (Fraunhofer propagation).

Returns

VectorD

The sampling distance and the number of sampling points of the propagated field.

GetFarFieldPropagationSamplingDistance(ComplexAmplitude, double, Complex, FarFieldPropagationMode)

Calculates the optimal sampling distance of the propagated field. The minimum number of sampling points per output plane diameter is 20 × 20.

public static VectorD GetFarFieldPropagationSamplingDistance(ComplexAmplitude ca, double distance, Complex n, FarFieldPropagationMode farFieldPropagationMode)

Parameters

ca ComplexAmplitude

ComplexAmplitude to propagate.

distance double

Propagation distance.

n Complex

Complex refractive index of media in which propagation is applied.

farFieldPropagationMode FarFieldPropagationMode

The far field propagation mode tells the function if a propagation from the waist to the far field or vice versa should be performed.

Returns

VectorD

The sampling distance of the propagated field.

GetFarFieldPropagationSamplingDistance(ComplexAmplitude, double, Complex, FarFieldPropagationMode, bool)

Calculates the optimal sampling distance of the propagated field. The minimum number of sampling points per output plane diameter is 20 x 20.

public static VectorD GetFarFieldPropagationSamplingDistance(ComplexAmplitude ca, double distance, Complex n, FarFieldPropagationMode farFieldPropagationMode, bool isParaxialApproximation)

Parameters

ca ComplexAmplitude

ComplexAmplitude to propagate.

distance double

Propagation distance.

n Complex

Complex refractive index of media in which propagation is applied.

farFieldPropagationMode FarFieldPropagationMode

The far field propagation mode tells the function if a propagation from the waist to the far field or vice versa should be performed.

isParaxialApproximation bool

If true the far field propagation will be calculated in paraxial approximation (Fraunhofer propagation).

Returns

VectorD

The sampling distance of the propagated field.

GetFarFieldPropagationSamplingParameters(ComplexAmplitude, double, Complex, FarFieldPropagationMode, bool)

Return the output field sampling parameters of the non-paraxial far field propagation.

public static SamplingParameters GetFarFieldPropagationSamplingParameters(ComplexAmplitude ca, double distance, Complex n, FarFieldPropagationMode farFieldPropagationMode, bool isParaxialApproximation)

Parameters

ca ComplexAmplitude

The complex amplitude to propagate.

distance double

Propagation distance.

n Complex

The refractive index of the medium containing the wave.

farFieldPropagationMode FarFieldPropagationMode

The far field propagation mode tells the function if a propagation from the waist to the far field or vice versa should be performed.

isParaxialApproximation bool

If true the far field propagation will be calculated in paraxial approximation (Fraunhofer propagation).

Returns

SamplingParameters

The sampling parameters of the output field.

GetFarFieldPropagationSamplingParameters(ComplexAmplitude, double, Complex, VectorD, FarFieldPropagationMode)

Calculates the optimal sampling distance and number of sampling points of the propagated field. The minimum number of sampling points per output plane diameter is 20 x 20.

public static SamplingParameters GetFarFieldPropagationSamplingParameters(ComplexAmplitude ca, double distance, Complex n, VectorD diameterOutputField, FarFieldPropagationMode farFieldPropagationMode)

Parameters

ca ComplexAmplitude

ComplexAmplitude to propagate.

distance double

Propagation distance.

n Complex

Complex refractive index of media in which propagation is applied.

diameterOutputField VectorD

The diameter of the field in the output plane.

farFieldPropagationMode FarFieldPropagationMode

The far field propagation mode tells the function if a propagation from the waist to the far field or vice versa should be performed.

Returns

SamplingParameters

The sampling distance and the number of sampling points of the propagated field.

GetFarFieldPropagationSamplingParameters(ComplexAmplitude, double, Complex, VectorD, FarFieldPropagationMode, bool)

Calculates the optimal sampling distance and number of sampling points of the propagated field. The minimum number of sampling points per output plane diameter is 20 × 20.

public static SamplingParameters GetFarFieldPropagationSamplingParameters(ComplexAmplitude ca, double distance, Complex n, VectorD diameterOutputField, FarFieldPropagationMode farFieldPropagationMode, bool isParaxialApproximation)

Parameters

ca ComplexAmplitude

ComplexAmplitude to propagate.

distance double

Propagation distance.

n Complex

Complex refractive index of media in which propagation is applied.

diameterOutputField VectorD

The diameter of the field in the output plane.

farFieldPropagationMode FarFieldPropagationMode

The far field propagation mode tells the function if a propagation from the waist to the far field or vice versa should be performed.

isParaxialApproximation bool

If true the far field propagation will be calculated in paraxial approximation (Fraunhofer propagation).

Returns

SamplingParameters

The sampling distance and the number of sampling points of the propagated field.

GetFrtInputFieldSamplingParametersFromOutputFieldSize(ComplexAmplitude, double, Complex, VectorD, out bool)

Estimates the sampling parameters of the field to propagate so that the output field generated by the Fresnel transform will have the diameter as specified by the outputFieldSize parameter. In order to have small numerical errors of the simulation result the outputFieldSize should be so large that the most of the power (typically >99.99%) are included in this area. If a smaller output field size will be selected significant numerical errors may appear. The propagation can be done in a one step or two step process. In case of a one step propagation the propagation is directly done from the plane containing the complex amplitude into the target plane. The two step process tries to propagate back in the source plane of the spherical phase and to perform a second propagation step into the target plane. The two step process can be used if a spherical phase in present and if the required computer memory will be smaller as in case of a one step process. If the returned input field sampling parameters differ from the sampling parameters of the ComplexAmplitude to propagate an interpolation is required. The two step requires probably a further interpolation after the first interpolation step.

public static SamplingParameters GetFrtInputFieldSamplingParametersFromOutputFieldSize(ComplexAmplitude ca, double distance, Complex n, VectorD outputFieldSize, out bool useBackToWaist)

Parameters

ca ComplexAmplitude

Complex Amplitude to propagate by Fresnel transform.

distance double

Propagation distance of the Fresnel transform.

n Complex

Refractive index of the medium containing the complex amplitude.

outputFieldSize VectorD

Desired diameter of the propagated field (output field). Please take into account that this parameter should give an good estimation of the physical field size of the propagated field.

useBackToWaist bool

If true a two step propagation should be used (see above)

Returns

SamplingParameters

The sampling parameters of the field to propagated. If these sampling parameters differ from the parameters of the ca an interpolation must be done before the start of the Fresnel transform propagation.

GetFrtInputFieldSamplingParametersFromOutputFieldSize(SamplingParameters, bool, double, double, double, Complex, VectorD, double, out bool, out SamplingParameters, out SamplingParameters)

Estimates the sampling parameters of the field to propagate so that the output field generated by the Fresnel transform will have the diameter as specified by the outputFieldSize parameter. In order to have small numerical errors of the simulation result the outputFieldSize should be so large that the most of the power (typically >99.99%) are included in this area. If a smaller output field size will be selected significant numerical errors may appear. The propagation can be done in a one step or two step process. In case of a one step propagation the propagation is directly done from the plane containing the complex amplitude into the target plane. The two step process tries to propagate back in the source plane of the spherical phase and to perform a second propagation step into the target plane. The two step process can be used if a spherical phase in present and if the required computer memory will be smaller as in case of a one step process. If the returned input field sampling parameters differ from the sampling parameters of the ComplexAmplitude to propagate an interpolation is required. The two step requires probably a further interpolation after the first interpolation step.

public static void GetFrtInputFieldSamplingParametersFromOutputFieldSize(SamplingParameters fieldSamplingParameters, bool hasSphericalPhase, double sphericalPhaseRadius, double wavelength, double distance, Complex n, VectorD outputFieldSize, double accuracyFactor, out bool perform2StepPropagation, out SamplingParameters samplingParametersStep1, out SamplingParameters samplingParametersStep2)

Parameters

fieldSamplingParameters SamplingParameters

The sampling parameters of the complex amplitude to propagate.

hasSphericalPhase bool

Indicates if the complex amplitude to propagate contains a spherical phase radius.

sphericalPhaseRadius double

The spherical phase radius of the complex amplitude to propagate.

wavelength double

The wavelength of the complex amplitude to propagate.

distance double

The propagation distance. This means the distance from the plane containing the complex amplitude to propagate to the target plane.

n Complex

The complex refractive index of the homogeneous medium containing the complex amplitude to propagate.

outputFieldSize VectorD

The desired diameter of the output field. The output field size should by huge enough so that it will contain more than 99% of the power of the field. Otherwise numerical errors may appear.

accuracyFactor double

The accuracy factor is just used for the two step propagation (see above). For the back propagation into the source plane of the spherical phase the field size in this plane must be estimated. The estimated field size will be multiplied by this accuracy factor.

perform2StepPropagation bool

If true a two step propagation should be used (see above).

samplingParametersStep1 SamplingParameters

The required sampling parameters of the complex amplitude of the first propagation step. The complex amplitude to propagate must be interpolated to this sampling parameters before starting the first propagation step.

samplingParametersStep2 SamplingParameters

The required sampling parameters of the complex amplitude of the second propagation step. The resulting complex amplitude after the first propagation step must be interpolated to this sampling parameters before starting the second step. If perform2StepPropagation is false no second propagation step is required and null will be returned.

GetFrtSamplingParameters(ComplexAmplitude, double, Complex)

Calculates the sampling parameters for the Fresnel Propagation to avoid numerical errors during the propagation. The function can decrease the sampling distance and increase the number of sampling points.

public static SamplingParameters GetFrtSamplingParameters(ComplexAmplitude ca, double distance, Complex n)

Parameters

ca ComplexAmplitude

Complex amplitude to propagate.

distance double

Propagation distance.

n Complex

Refractive index of the homogeneous medium.

Returns

SamplingParameters

The calculated sampling parameters.

GetFrtSamplingParameters(ComplexAmplitude, double, Complex, double)

Calculates the sampling parameters for the Fresnel Propagation to avoid numerical errors during the propagation. The function can decrease the sampling distance and increase the number of sampling points.

public static SamplingParameters GetFrtSamplingParameters(ComplexAmplitude ca, double distance, Complex n, double samplingFactor)

Parameters

ca ComplexAmplitude

Complex amplitude to propagate.

distance double

Propagation distance.

n Complex

Refractive index of the homogeneous medium.

samplingFactor double

VirtualLab estimates and modifies the number of sampling points and sampling distance of the input field before the propagation in order to reduce numerical errors. The estimated number of sampling points is multiplied by this factor to to increase or decrease numerical accuracy.

Returns

SamplingParameters

Sampling parameters.

GetRayleighSommerfeldConvolutionSamplingParameters(ComplexAmplitude, double, Complex)

Calculates the sampling parameters for the Rayleigh-Sommerfeld Convolution propagation to avoid numerical errors during the propagation. The function can decrease the sampling distance and increase the number of sampling points. The function takes into account possible spherical phase factors.

public static SamplingParameters GetRayleighSommerfeldConvolutionSamplingParameters(ComplexAmplitude ca, double distance, Complex n)

Parameters

ca ComplexAmplitude

Complex amplitude to propagate.

distance double

Propagation distance.

n Complex

Refractive index of the homogeneous medium.

Returns

SamplingParameters

Sampling parameters.

GetRayleighSommerfeldConvolutionSamplingParameters(ComplexAmplitude, double, Complex, double)

Calculates the sampling parameters for the Rayleigh-Sommerfeld Convolution propagation to avoid numerical errors during the propagation. The function can decrease the sampling distance and increase the number of sampling points. The function takes into account possible spherical phase factors.

public static SamplingParameters GetRayleighSommerfeldConvolutionSamplingParameters(ComplexAmplitude ca, double distance, Complex n, double accuracyFactor)

Parameters

ca ComplexAmplitude

Complex amplitude to propagate.

distance double

Propagation distance.

n Complex

Refractive index of the homogeneous medium.

accuracyFactor double

VirtualLab estimates the numerical parameters of the input field to propagate in order to reduce numerical errors. The estimated number of sampling points is multiplied by this factor to to increase or decrease numerical accuracy.

Returns

SamplingParameters

Sampling parameters.

GetRayleighSommerfeldSummationSamplingDistance(ComplexAmplitude, double, Complex)

Calculates the optimal sampling distance of the propagated field.

public static VectorD GetRayleighSommerfeldSummationSamplingDistance(ComplexAmplitude ca, double distance, Complex n)

Parameters

ca ComplexAmplitude

\markAsCode{ComplexAmplitude} to propagate.

distance double

Propagation distance.

n Complex

Complex refractive index of media in which propagation is applied.

Returns

VectorD

Result of operation.

GetSpwInputFieldSamplingParameters(ComplexAmplitude, double, Complex, double)

Calculates the sampling parameters of the input field to propagate by the spectrum of plane waves propagation to avoid numerical errors during the propagation. The function can increase the number of sampling points and can decrease the sampling distance in case of a present spherical phase factor. The sampling parameters return the width (sampling points multiplied by sampling distance divided by 2) of the wave after the Spectrum of Plane Waves propagation. If the width of the returned sampling parameters is larger than the width of the field object embed the field before the propagation. If the width of the sampling parameters is smaller than the width of the field object first propagate the field and then extract the necessary sampling points.

public static SamplingParameters GetSpwInputFieldSamplingParameters(ComplexAmplitude ca, double distance, Complex n, double accuracyFactor)

Parameters

ca ComplexAmplitude

Complex amplitude component to propagate. Has to be a harmonic field component.

distance double

Propagation distance.

n Complex

Refractive index of the homogeneous medium.

accuracyFactor double

The accuracy factor.

Returns

SamplingParameters

Sampling parameters.

GetSpwInputFieldSamplingParametersFromOutputFieldSize(ComplexAmplitude, Complex, VectorD, double)

Estimates the sampling parameters of the field to propagate so that the output field generated by the Spectrum of Plane Waves propagation will have the diameter as specified by the outputFieldSize parameter. In order to have small numerical errors of the simulation result the outputFieldSize should be so large that the most of the power (typically >99.99%) are included in this area. If a smaller output field size will be selected significant numerical errors may appear. If the returned input field sampling parameters differ from the sampling parameters Complex Amplitude to propagate an interpolation is required.

public static SamplingParameters GetSpwInputFieldSamplingParametersFromOutputFieldSize(ComplexAmplitude ca, Complex n, VectorD outputFieldSize, double accuracyFactor)

Parameters

ca ComplexAmplitude

Complex Amplitude to propagate by Spectrum of Plane Waves propagation.

n Complex

Refractive index of the medium containing the complex amplitude.

outputFieldSize VectorD

Desired diameter of the propagated field (output field). Please take into account that this parameter should give an good estimation of the physical field size of the propagated field.

accuracyFactor double

Increasing this factor to values larger than one will lead to more accurate simulation results during Spectrum of Plane Waves propagation on the cost of memory and computational time. This parameter has just an effect if a spherical phase radius is set.

Returns

SamplingParameters

The sampling parameters of the field to propagated. If these sampling parameters differ from the parameters of the ca an interpolation must be done before the start of the Spectrum of Plane Waves propagation.

GetSpwOutputFieldSamplingParameters(ComplexAmplitude, double, Complex, double)

Calculates the sampling parameters of the output field for the spectrum of plane waves propagation to avoid numerical errors during the propagation. The function can increase the number of sampling points and can decrease the sampling distance in case of a present spherical phase factor. The sampling parameters return the width (sampling points multiplied by sampling distance divided by 2) of the wave after the Spectrum of Plane Waves propagation. Is the width of the returned sampling parameters larger than the width of the ca object embed the field before the propagation. Is the width of the sampling parameters smaller than the width of the field object first propagate the field and then extract the necessary sampling points.

public static SamplingParameters GetSpwOutputFieldSamplingParameters(ComplexAmplitude ca, double distance, Complex n, double accuracyFactor)

Parameters

ca ComplexAmplitude

Complex amplitude component to propagate. Has to be a harmonic field component.

distance double

Propagation distance.

n Complex

Refractive index of the homogeneous medium.

accuracyFactor double

The accuracy factor.

Returns

SamplingParameters

Sampling parameters.

RayleighSommerfeldConvolution(ComplexAmplitude, double, Complex, bool, double, VectorD, bool, double, VectorD, eApertureShape, double, bool, double, int, SamplingParameters, out bool, CancellationToken?)

Propagates the given ComplexAmplitude by the specified distance by a convolution of the complex amplitude and the propagation core (Rayleigh-Sommerfeld integral). The convolution is calculated in the frequency domain. The function can interpolate the complex amplitude by sinc-interpolation to avoid numerical errors.

public static ComplexAmplitude RayleighSommerfeldConvolution(ComplexAmplitude ca, double distance, Complex n, bool automaticInputFieldSampling, double accuracyFactor, VectorD inputFieldSamplingDistance, bool automaticOutputFieldSizeShape, double outputFieldSizeFactor, VectorD outputFieldFieldSize, BasicParameter.eApertureShape outputFieldShape, double outputFieldBorderWidth, bool automaticOutputFieldSampling, double outputFieldSamplingFactor, int outputFieldEmbedFrameWidth, SamplingParameters outputFieldSamplingParameters, out bool areNumericalErrors, CancellationToken? cancellationToken = null)

Parameters

ca ComplexAmplitude

ComplexAmplitude to be propagated.

distance double

Propagation distance in meters.

n Complex

Complex refractive index of media in which propagation is applied.

automaticInputFieldSampling bool

if set to true [automatic input field sampling].

accuracyFactor double

The accuracy factor. A larger factor leads to more accurate results but to higher computational effort.

inputFieldSamplingDistance VectorD

The input field sampling distance.

automaticOutputFieldSizeShape bool

If true the output field size, shape and border width are determined by VirtualLab automatically. Otherwise the values can be specified using the outputFieldSize, outputFieldShape and outputFieldBorderWidth parameters.

outputFieldSizeFactor double

In case of automaticOutputFieldSizeShape VirtualLab estimates the correct size of the propagated field. The resulting value is multiplied by this factor.

outputFieldFieldSize VectorD

The diameter of the output field in meters. The diameter is measured before the beginning of the border decay of amplitude.

outputFieldShape BasicParameter.eApertureShape

The shape of the field.

outputFieldBorderWidth double

The width of the borders of the field relative to the field diameter. The border width is measured between the begin of the amplitude decay and the zero position of the field.

automaticOutputFieldSampling bool

Enables automatic determination of the required array size and number of sampling points of the output field to minimize numerical errors. Additionally the user may use the outputFieldSamplingFactor to additionally increase or reduce the number of sampling points. The array size of the output field will be calculated from the estimation of the field size multiplied by the outputFieldSizeFactor plus the outputFieldBorderWidth multiplied by the field size plus the embedFrameWidth multiplid by the sampling distance. If automaticOutputFieldSampling is false the outputFieldSamplingParameters will be used.

outputFieldSamplingFactor double

If automaticOutputFieldSampling is true VirtualLab estimates the number of sampling points of the output field and multiplies the value by outputFieldSamplingFactor.

outputFieldEmbedFrameWidth int

If automaticOutputFieldSampling is false additionally a frame with dark pixels (amplitude equals zero) around the field can be added. This embed frame is required since the continuous field distribution can be reconstructed using a sinc interpolation. This interpolation will introduce small sized loops that are larger than the numerical field size. To take this side loops at least partially into account during the interpolation this embed frame is required. The extension of this frame in sampling points can be specified by this parameter.

outputFieldSamplingParameters SamplingParameters

The sampling parameters of the output field. Normally these sampling parameters should be equal to the inputFieldSamplingParameters but the use may change it to any other value.

areNumericalErrors bool

Returns true if the user defined settings of the numerical accuracy parameter may caused numerical errors during the propagation. This is typically the case if numericalAccuracyFactor is smaller than one.

cancellationToken CancellationToken?

Optional token for cooperative task cancellation.

Returns

ComplexAmplitude

Result of operation.

RayleighSommerfeldSummation(ComplexAmplitude, VectorD, double, bool, double, SamplingParameters, bool, double, VectorD, eApertureShape, double, bool, double, int, SamplingParameters, Complex, out bool, CancellationToken?)

Propagates the given ComplexAmplitude by the specified distance by a convolution of the complex amplitude and the propagation core (Rayleigh-Sommerfeld integral). The convolution is calculated in the frequency domain. The function ignores present SphericalPhaseRadius. Because of this additional numerical errors may occur during the propagation. Use areSamplingProblems to check for numerical errors before propagating.

public static ComplexAmplitude RayleighSommerfeldSummation(ComplexAmplitude ca, VectorD resultLateralOffset, double distance, bool automaticInputFieldSampling, double accuracyFactor, SamplingParameters inputFieldSamplingParameters, bool automaticOutputFieldSizeShape, double outputFieldSizeFactor, VectorD outputFieldFieldSize, BasicParameter.eApertureShape outputFieldShape, double outputFieldBorderWidth, bool automaticOutputFieldSampling, double outputFieldSamplingFactor, int outputFieldEmbedFrameWidth, SamplingParameters outputFieldSamplingParameters, Complex n, out bool areSamplingProblems, CancellationToken? cancellationToken = null)

Parameters

ca ComplexAmplitude

ComplexAmplitude to propagate.

resultLateralOffset VectorD

Lateral offset of propagated field.

distance double

Propagation distance.

automaticInputFieldSampling bool

if set to true automatic input field sampling is used.

accuracyFactor double

The accuracy factor.

inputFieldSamplingParameters SamplingParameters

The input field sampling parameters.

automaticOutputFieldSizeShape bool

If true the output field size, shape and border width are determined by VirtualLab automatically. Otherwise the values can be specified using the outputFieldSize, outputFieldShape and outputFieldBorderWidth parameters.

outputFieldSizeFactor double

In case of automaticOutputFieldSizeShape VirtualLab estimates the correct size of the propagated field. The resulting value is multiplied by this factor.

outputFieldFieldSize VectorD

The diameter of the output field in meters. The diameter is measured before the beginning of the border decay of amplitude.

outputFieldShape BasicParameter.eApertureShape

The shape of the field.

outputFieldBorderWidth double

The width of the borders of the field relative to the field diameter. The border width is measured between the begin of the amplitude decay and the zero position of the field.

automaticOutputFieldSampling bool

Enables automatic determination of the required array size and number of sampling points of the output field to minimize numerical errors. Additionally the user may use the outputFieldSamplingFactor to additionally increase or reduce the number of sampling points. The array size of the output field will be calculated from the estimation of the field size multiplied by the outputFieldSizeFactor plus the outputFieldBorderWidth multiplied by the field size plus the embedFrameWidth multiplid by the sampling distance. If automaticOutputFieldSampling is false the outputFieldSamplingParameters will be used.

outputFieldSamplingFactor double

If automaticOutputFieldSampling is true VirtualLab estimates the number of sampling points of the output field and multiplies the value by outputFieldSamplingFactor.

outputFieldEmbedFrameWidth int

If automaticOutputFieldSampling is false additionally a frame with dark pixels (amplitude equals zero) around the field can be added. This embed frame is required since the continuous field distribution can be reconstructed using a sinc interpolation. This interpolation will introduce small sized loops that are larger than the numerical field size. To take this side loops at least partially into account during the interpolation this embed frame is required. The extension of this frame in sampling points can be specified by this parameter.

outputFieldSamplingParameters SamplingParameters

The sampling parameters of the output field. Normally these sampling parameters should be equal to the inputFieldSamplingParameters but the use may change it to any other value.

n Complex

Complex refractive index of media in which propagation is applied.

areSamplingProblems bool

Out parameter indicating if sampling problems can occur in the propagated field.

cancellationToken CancellationToken?

Optional token for cooperative task cancellation.

Returns

ComplexAmplitude

Result of operation.

Spw(ComplexAmplitude, double, bool, double, SamplingParameters)

Propagates the given ComplexAmplitude by the specified distance by computing the Angular Spectrum of Plane Waves. The function can increase the number of sampling points to avoid numerical errors. The minimum embedding of the complex amplitude is determined by the VirtualLabAPI.Core.Common.Globals.SamplingFactor.

public static ComplexAmplitude Spw(ComplexAmplitude ca, double distance, bool automaticInputFieldSampling, double accuracyFactor, SamplingParameters inputFieldSamplingParameters)

Parameters

ca ComplexAmplitude

ComplexAmplitude to be propagated.

distance double

Propagation distance in meters.

automaticInputFieldSampling bool

Enables automatic determination of the required array size and number of sampling points of the input field to minimize numerical errors. Additionally the user may use the accuracyFactor to additionally increase or reduce the number of sampling points and array size. If automaticInputFieldSampling is false the inputFieldSamplingParameters will be used to modify the sampling parameters of the input field before the propagation.

accuracyFactor double

The accuracy factor used in case of automatic input field sampling.

inputFieldSamplingParameters SamplingParameters

The function modifies the sampling parameters of the input field before the propagation to the values specified here. This parameter allows to modify the input field sampling parameters to user defined values. To get an estimation for input field sampling parameters please use the GetSpwSamplingParameters function.

Returns

ComplexAmplitude

Result of operation.

Spw(ComplexAmplitude, double, Complex, bool, double, SamplingParameters, bool, double, VectorD, eApertureShape, double, bool, double, int, SamplingParameters, out bool, CancellationToken?)

Propagates the given ComplexAmplitude by the specified distance by computing the Angular Spectrum of Plane Waves. The function modifies the sampling parameters of the input field specified in the inputFieldSamplingParameters parameter before the propagation in order to reduce numerical errors. The modification can be done by user or automatically Additionally the user may specify the output field sampling parameters and the field size, shape and border width of the output field.

public static ComplexAmplitude Spw(ComplexAmplitude ca, double distance, Complex n, bool automaticInputFieldSampling, double accuracyFactor, SamplingParameters inputFieldSamplingParameters, bool automaticOutputFieldSizeShape, double outputFieldSizeFactor, VectorD outputFieldFieldSize, BasicParameter.eApertureShape outputFieldShape, double outputFieldBorderWidth, bool automaticOutputFieldSampling, double outputFieldSamplingFactor, int outputFieldEmbedFrameWidth, SamplingParameters outputFieldSamplingParameters, out bool areNumericalErrors, CancellationToken? cancellationToken = null)

Parameters

ca ComplexAmplitude

The field to propagate.

distance double

The propagation distance.

n Complex

The refractive index of the homogeneous medium in that the field propagates.

automaticInputFieldSampling bool

Enables automatic determination of the required array size and number of sampling points of the input field to minimize numerical errors. Additionally the user may use the inputFieldSamplingFactor and inputFieldArraySizeFactor to additionally increase or reduce the number of sampling points and array size. If automaticInputFieldSampling is false the inputFieldSamplingParameters will be used to modify the sampling parameters of the input field before the propagation.

accuracyFactor double

The accuracy factor.

inputFieldSamplingParameters SamplingParameters

The function modifies the sampling parameters of the input field before the propagation to the values specified here. This parameter allows to modify the input field sampling parameters to user defined values. To get an estimation for input field sampling parameters please use the GetSpwSamplingParameters function.

automaticOutputFieldSizeShape bool

If true the output field size, shape and border width are determined by VirtualLab automatically. Otherwise the values can be specified using the outputFieldSize, outputFieldShape and outputFieldBorderWidth parameters.

outputFieldSizeFactor double

In case of automaticOutputFieldSizeShape VirtualLab estimates the correct size of the propagated field. The resulting value is multiplied by this factor.

outputFieldFieldSize VectorD

The diameter of the output field in meters. The diameter is measured before the beginning of the border decay of amplitude.

outputFieldShape BasicParameter.eApertureShape

The shape of the field.

outputFieldBorderWidth double

The width of the borders of the field relative to the field diameter. The border width is measured between the begin of the amplitude decay and the zero position of the field.

automaticOutputFieldSampling bool

Enables automatic determination of the required array size and number of sampling points of the output field to minimize numerical errors. Additionally the user may use the outputFieldSamplingFactor to additionally increase or reduce the number of sampling points. The array size of the output field will be calculated from the estimation of the field size multiplied by the outputFieldSizeFactor plus the outputFieldBorderWidth multiplied by the field size plus the embedFrameWidth multiplid by the sampling distance. If automaticOutputFieldSampling is false the outputFieldSamplingParameters will be used.

outputFieldSamplingFactor double

If automaticOutputFieldSampling is true VirtualLab estimates the number of sampling points of the output field and multiplies the value by outputFieldSamplingFactor.

outputFieldEmbedFrameWidth int

If automaticOutputFieldSampling is false additionally a frame with dark pixels (amplitude equals zero) around the field can be added. This embed frame is required since the continuous field distribution can be reconstructed using a sinc interpolation. This interpolation will introduce small sized loops that are larger than the numerical field size. To take this side loops at least partially into account during the interpolation this embed frame is required. The extension of this frame in sampling points can be specified by this parameter.

outputFieldSamplingParameters SamplingParameters

The sampling parameters of the output field. Normally these sampling parameters should be equal to the inputFieldSamplingParameters but the use may change it to any other value.

areNumericalErrors bool

True if the user defined settings of the input field sampling parameters may caused numerical errors during the propagation. This parameter is just set if automaticInputFieldSampling is false.

cancellationToken CancellationToken?

Optional token for cooperative task cancellation.

Returns

ComplexAmplitude

The propagated field.

Spw(ComplexAmplitude, double, Complex, double, CancellationToken, out bool)

Propagates the given ComplexAmplitude by the specified distance by computing the Angular Spectrum of Plane Waves. The function can increase the number of sampling points to avoid numerical errors. The minimum embedding of the complex amplitude is determined by VirtualLabAPI.Core.Common.Globals.SamplingFactor..

public static ComplexAmplitude Spw(ComplexAmplitude ca, double distance, Complex n, double accuracyFactor, CancellationToken cancellationToken, out bool areNumericalErrors)

Parameters

ca ComplexAmplitude

ComplexAmplitude to be propagated.

distance double

Propagation distance in meters.

n Complex

Complex refractive index of media in which propagation is applied.

accuracyFactor double

VirtualLab estimates and modifies array size and number of sampling points of the input field before the propagation in order to reduce numerical errors. The estimated number of sampling points and the estimated array size is multiplied by this factor to increase or decrease numerical accuracy.

cancellationToken CancellationToken

Token for cooperative task cancellation.

areNumericalErrors bool

True if numerical errors may appear in the propagated field. This warning appears if arraySizeFactor or SamplingFactor is smaller than one.

Returns

ComplexAmplitude

Result of operation.