This section contains a list of public PyPO methods which are used for performing physical optics related tasks. More...

Functions
def	PyPO.System.System.removeField (self, str fieldName)
	Remove a PO field from system. More...

def	PyPO.System.System.removeCurrent (self, str currentName)
	Remove a PO current from system. More...

def	PyPO.System.System.removeScalarField (self, str fieldName)
	Remove a scalar PO field from system. More...

def	PyPO.System.System.readCustomBeam (self, str name_beam, str name_source, FieldComponents comp, float lam, bool normalise=True, float scale=1, str outname=None)
	Read a custom beam from disk into the system. More...

def	PyPO.System.System.runPO (self, dict runPODict)
	Instantiate a PO propagation. More...

def	PyPO.System.System.mergeBeams (self, *str beams, Objects obj=Objects.FIELD, str merged_name="combined")
	Merge multiple beams that are defined on the same surface. More...

def	PyPO.System.System.createGaussian (self, dict gaussDict, str name_surface)
	Create a vectorial Gaussian beam. More...

def	PyPO.System.System.createScalarGaussian (self, dict gaussDict, str name_surface)
	Create a scalar Gaussian beam. More...

float	PyPO.System.System.calcSpillover (self, str name_field, FieldComponents comp, dict aperDict)
	Calculate spillover efficiency of a beam defined on a surface. More...

float	PyPO.System.System.calcTaper (self, str name_field, FieldComponents comp, dict aperDict=None)
	Calculate taper efficiency of a beam defined on a surface. More...

float	PyPO.System.System.calcXpol (self, str name_field, FieldComponents comp_co, FieldComponents comp_cr)
	Calculate cross-polar efficiency of a field defined on a surface. More...

np.ndarray	PyPO.System.System.fitGaussAbs (self, str name_field, FieldComponents comp, float thres=None, Scales scale=Scales.LIN, bool full_output=False, float ratio=1)
	Fit a Gaussian profile to the amplitude of a field component and adds the result to scalar field in system. More...

float	PyPO.System.System.calcMainBeam (self, str name_field, FieldComponents comp, float thres=None, Scales scale=Scales.LIN)
	Calculate main-beam efficiency of a beam pattern. More...

tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]	PyPO.System.System.calcBeamCuts (self, str name_field, FieldComponents comp, int interp=1001, float phi=0, bool center=True, bool align=True, FieldComponents norm=FieldComponents.NONE, bool transform=False, Scales scale=Scales.dB, bool full_output=False)
	Calculate cross sections of a beam pattern. More...

tuple[float, float]	PyPO.System.System.calcHPBW (self, str name_field, FieldComponents comp, bool center=False, float align=False)
	Calculate half-power beamwidth. More...

def	PyPO.System.System.createPointSource (self, dict PSDict, str name_surface)
	Generate point-source PO fields and currents. More...

def	PyPO.System.System.createUniformSource (self, dict UDict, str name_surface)
	Generate uniform PO fields and currents. More...

def	PyPO.System.System.createPointSourceScalar (self, dict PSDict, str name_surface)
	Generate point-source scalar PO field. More...

def	PyPO.System.System.createUniformSourceScalar (self, dict UDict, str name_surface)
	Generate scalar uniform PO fields and currents. More...

def	PyPO.System.System.interpBeam (self, str name, int gridsize_new, Objects obj=Objects.FIELD)
	Interpolate a PO beam. More...

int	PyPO.System.System.autoConverge (self, str source_field, str name_target, float tol=1e-2, int add=10, float patch_size=1/9, int max_iter=1000)
	Calculate gridsize for which calculation converges. More...

Detailed Description

This section contains a list of public PyPO methods which are used for performing physical optics related tasks.

Function Documentation

◆ autoConverge()

int PyPO.System.System.autoConverge	(		self,
		str	source_field,
		str	name_target,
		float	tol = `1e-2`,
		int	add = `10`,
		float	patch_size = `1/9`,
		int	max_iter = `1000`
	)

Calculate gridsize for which calculation converges.

This function calculates the gridsize for a target surface in order to obtain a convergent solution. First, a small patch is selected from the middle of the target surface and given a starting gridsize. The brightest component of the source distribution is then selected and copied into a PO scalarfield object. The scalarfield is propagated to the target patch and the total incident power is calculated. Then, the propagation is performed again but now the gridsize of the patch is smaller. The power is calculated again and compared with the previous result. If this result is smaller than the given tolerance, the new gridsize is accepted as the converged gridsize. If not, another iteration is started. If the maximal number of iterations is exceeded, PyPO will throw an error and stop.

Parameters

source_field	Name of field to use for auto convergence. Should be the field that is to be propagated.
name_target	Name of target surface.
tol	Tolerance for specifying when convergence has been reached.
add	Increment in gridsize for each iteration.
patch_size	Factor for reducing size of target in order to save time. Should be smaller than 1.
max_iter	Maximum number of iterations before auto convergence errors.

Returns: gridsize Gridsize, scaled to full target, for which solution converged.

◆ calcBeamCuts()

tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray] PyPO.System.System.calcBeamCuts	(		self,
		str	name_field,
		FieldComponents	comp,
		int	interp = `1001`,
		float	phi = `0`,
		bool	center = `True`,
		bool	align = `True`,
		FieldComponents	norm = `FieldComponents.NONE`,
		bool	transform = `False`,
		Scales	scale = `Scales.dB`,
		bool	full_output = `False`
	)

Calculate cross sections of a beam pattern.

This method calculates cross sections along the cardinal planes of the beam pattern. The cardinal planes here are defined to lie along the semi-major and semi-minor axes of the beam pattern. It does this by first finding the center and position angle of the beam pattern. Then, it creates a snapshot of the current configuration and translates and rotates the beam pattern so that the cardinal planes are oriented along the x- and y-axes. It is also possible to not do this and instead directly calculate the cross sections along the x- and y-axes as-is.

Parameters

name_field	Name of field object.
comp	Component of field object. Instance of FieldComponents enum object.
interp	Number of points in x and y strip. Defaults to 1001.
phi	Manual rotation of cuts w.r.t. to the x-y cardinal planes.
center	Whether to center the cardinal planes on the peak of the beam pattern.
align	Whether to align the cardinal planes to the beam pattern minor and major axes.
norm	Which component to normalise to. Defaults to comp.
transform	Transform surface on which beam is defined. If False, will evaluate beam cuts as if surface is in restframe.
scale	Return beamcuts in linear or decibel values. Instance of Scales enum object.
full_output	Return x-y coordinates of H and E cuts, instead of just distance to center.

Returns: x_cut Beam cross section along the E-plane.; y_cut Beam cross section along the H-plane.; x_strip Co-ordinate values for x_cut.; y_strip Co-ordinate values for y_cut.

◆ calcHPBW()

tuple [float, float] PyPO.System.System.calcHPBW	(		self,
		str	name_field,
		FieldComponents	comp,
		bool	center = `False`,
		float	align = `False`
	)

Calculate half-power beamwidth.

This is done by directly evaluating the -3 dB points along both cardinal planes of the beam pattern. Then, the distance between antipodal half-power points is calculated on an interpolation of the supplied PO field.

Parameters

name_field	Name of field object.
comp	Component of field object. Instance of FieldComponents enum object.
center	Whether to center the beam cuts on amplitude center. Use only if beam has well defined amplitude center.
align	Whether to take beam cuts along cardinal planes rotated by the position angle.

Returns: HPBW_E Half-power beamwidth along E-plane in units of surface of beam.; HPBW_H Half-power beamwidth along H-plane in units of surface of beam.

◆ calcMainBeam()

float PyPO.System.System.calcMainBeam	(		self,
		str	name_field,
		FieldComponents	comp,
		float	thres = `None`,
		Scales	scale = `Scales.LIN`
	)

Calculate main-beam efficiency of a beam pattern.

The main-beam efficiency is calculated by fitting a Gaussian amplitude profile to the central lobe. This might reuire fine-tuning the "thres" parameter, or changing the space in whcih to fit by supplying the "mode" parameter. Then, the efficiency is defined as the fraction of power in the Gaussian w.r.t. the full pattern. Designed for far-field beam patterns, but also applicable to regular fields. Note that since this method uses the fitGaussAbs() method, the result is quite sensitive to initial conditions and should therefore be (iteratively) checked for robustness.

Parameters

name_field	Name of field object.
comp	Component of field object. Instance of FieldComponents enum object.
thres	Threshold to fit to, in decibels.
scale	Fit to amplitude in decibels, linear or logarithmic scale.

Returns: eff Main-beam efficiency.

◆ calcSpillover()

float PyPO.System.System.calcSpillover	(		self,
		str	name_field,
		FieldComponents	comp,
		dict	aperDict
	)

Calculate spillover efficiency of a beam defined on a surface.

The method calculates the spillover using the fraction of the beam that illuminates the region defined in aperDict versus the total beam.

Parameters

name_field	Name of the PO field.
comp	Component of field to calculate spillover of. Instance of FieldComponents enum object.
aperDict	An aperDict dictionary containing the parameters for defining the spillover aperture.

Returns: spill The spillover efficiency.

See also: aperDict

◆ calcTaper()

float PyPO.System.System.calcTaper	(		self,
		str	name_field,
		FieldComponents	comp,
		dict	aperDict = `None`
	)

Calculate taper efficiency of a beam defined on a surface.

The method calculates the taper efficiency using the fraction of the beam that illuminates the region defined in aperDict versus the total beam. If aperDict is not given, it will calculate the taper efficiency on the entire beam.

Parameters

name_field	Name of the PO field.
comp	Component of field to calculate taper efficiency of. Instance of FieldComponents enum object.
aperDict	An aperDict dictionary containing the parameters for defining the taper aperture. Defaults to None.

Returns: taper The taper efficiency.

See also: aperDict

◆ calcXpol()

float PyPO.System.System.calcXpol	(		self,
		str	name_field,
		FieldComponents	comp_co,
		FieldComponents	comp_cr
	)

Calculate cross-polar efficiency of a field defined on a surface.

The cross-polar efficiency is described as the ratio of power in the cross-polar component versus the co-polar component. The cross-polar efficiency is calculated over the entire field extent.

Parameters

name_field	Name of the PO field.
comp_co	Co-polar component of field. Instance of FieldComponents enum object.
comp_cr	Cross-polar component of field. Instance of FieldComponents enum object.

Returns: crp The cross-polar efficiency.

◆ createGaussian()

def PyPO.System.System.createGaussian	(		self,
		dict	gaussDict,
		str	name_surface
	)

Create a vectorial Gaussian beam.

This method creates a general, potentially astigmatic, vectorial Gaussian beam. The beam is evaluated with the focus at z = 0. The surface on which the beam is calculated, defined by "name_source", does not have to lie in or be parallel to the xy-plane. Instead, the Gaussian beam is evaluated on the surface as-is, evaluating the Gaussian beam at the xyz-points on the surface. Still, the focus is at z = 0. If one wishes to displace the focal point, the PO fields and currents need to be translated after generating the Gaussian beam.

Parameters

gaussDict	A GDict containing parameters for the Gaussian beam.
name_surface	Name of plane on which to define Gaussian.

See also: GDict

◆ createPointSource()

def PyPO.System.System.createPointSource	(		self,
		dict	PSDict,
		str	name_surface
	)

Generate point-source PO fields and currents.

The point source is generated in the center of the source surface given by "name_surface". It is generally a good idea to make this source surface as small as possible, in order to create a "nice" point source. If this is too big, the resulting PO field more closely resembles a uniformly illuminated square. The H-field is set to 0.

Parameters

PSDict	A PSDict dictionary, containing parameters for the point source.
name_surface	Name of surface on which to define the point-source.

See also: PSDict

◆ createPointSourceScalar()

def PyPO.System.System.createPointSourceScalar	(		self,
		dict	PSDict,
		str	name_surface
	)

Generate point-source scalar PO field.

The point source is generated in the center of the source surface given by "name_surface". It is generally a good idea to make this source surface as small as possible, in order to create a "nice" point source. If this is too big, the resulting PO field more closely resembles a uniformly illuminated square. The H-field is set to 0.

Parameters

PSDict	A PSDict dictionary, containing parameters for the point source.
name_surface	Name of surface on which to define the point-source.

See also: PSDict

◆ createScalarGaussian()

def PyPO.System.System.createScalarGaussian	(		self,
		dict	gaussDict,
		str	name_surface
	)

Create a scalar Gaussian beam.

This method creates a general, potentially astigmatic, scalar Gaussian beam. The beam is evaluated with the focus at z = 0. The surface on which the beam is calculated, defined by "name_source", does not have to lie in or be parallel to the xy-plane. Instead, the Gaussian beam is evaluated on the surface as-is, evaluating the Gaussian beam at the xyz-points on the surface. Still, the focus is at z = 0. If one wishes to displace the focal point, the PO scalarfield needs to be translated after generating the Gaussian beam.

Parameters

gaussDict	A GDict containing parameters for the Gaussian beam.
name_surface	Name of plane on which to define Gaussian.

See also: SGDict

◆ createUniformSource()

def PyPO.System.System.createUniformSource	(		self,
		dict	UDict,
		str	name_surface
	)

Generate uniform PO fields and currents.

The uniform field is generated by defining a PO field on the source surface and setting all values to the amplitude specified in the input dictionary. The H-field is set to 0.

Parameters

UDict	A UDict dictionary, containing parameters for the uniform pattern.
name_surface	Name of surface on which to define the uniform pattern.

See also: PSDict

◆ createUniformSourceScalar()

def PyPO.System.System.createUniformSourceScalar	(		self,
		dict	UDict,
		str	name_surface
	)

Generate scalar uniform PO fields and currents.

The uniform field is generated by defining a PO field on the source surface and setting all values to the amplitude specified in the input dictionary. The H-field is set to 0.

Parameters

UDict	A UDict dictionary, containing parameters for the uniform pattern.
name_surface	Name of surface on which to define the uniform pattern.

See also: UDict

◆ fitGaussAbs()

np.ndarray PyPO.System.System.fitGaussAbs	(		self,
		str	name_field,
		FieldComponents	comp,
		float	thres = `None`,
		Scales	scale = `Scales.LIN`,
		bool	full_output = `False`,
		float	ratio = `1`
	)

Fit a Gaussian profile to the amplitude of a field component and adds the result to scalar field in system.

The resultant Gaussian fit cannot be propagated using vectorial means, but can be propagated using scalar propagation. Note that this method is very sensitive to initial conditions, especially when the beam pattern to which to fit the Gaussian has multiple maxima or is generally ill-described by a Gaussian. In the latter case, the method may fail altogether.

Parameters

name_field	Name of field object.
comp	Component of field object. Instance of FieldComponents enum object.
thres	Threshold to fit to, in decibels.
scale	Fit to amplitude in decibels, linear or logarithmic scale. Instance of Scales enum object.
full_output	Return fitted parameters and standard deviations.
ratio	Allowed maximal ratio of fit to actual beam. If "None", will just attempt to fit the Gaussian to supplied pattern. If given, will only accept a fit if the ratio of integrated power in the fitted Gaussian to the supplied beam pattern is less than or equal to the given value. Defaults to 1.

    @returns popt Fitted beam parameters.
    @returns perr Standard deviation of fitted parameters.

◆ interpBeam()

def PyPO.System.System.interpBeam	(		self,
		str	name,
		int	gridsize_new,
		Objects	obj = `Objects.FIELD`
	)

Interpolate a PO beam.

Only for beams defined on planar surfaces.

Can interpolate PO fields and currents separately. Results are stored in a new PO fields/currents object with the original name appended by 'interp'. Also, a new plane will be created with the updated gridsize and name appended by 'interp'.

Parameters

name	Name of beam to be interpolated.
gridsize_new	New gridsizes for interpolation.
obj	Whether to interpolate currents or fields.

◆ mergeBeams()

def PyPO.System.System.mergeBeams	(		self,
		*str	beams,
		Objects	obj = `Objects.FIELD`,
		str	merged_name = `"combined"`
	)

Merge multiple beams that are defined on the same surface.

The beams to be merged are first checked to see if they are all defined on the same surface. Then, a new PO field or current is defined in the internal dictionary with the new name.

Parameters

beams	Fields or currents objects to merge.
obj	Whether the beams are PO fields or currents.
merged_name	Name of merged object.

◆ readCustomBeam()

def PyPO.System.System.readCustomBeam	(		self,
		str	name_beam,
		str	name_source,
		FieldComponents	comp,
		float	lam,
		bool	normalise = `True`,
		float	scale = `1`,
		str	outname = `None`
	)

Read a custom beam from disk into the system.

The system will look in the customBeamPath, which defaults to the current working directory and can be set with the setCustomBeamPath() method. Note that the custom beam pattern needs to contain a real and imaginary part, and that these need to be stored in separate .txt files, stored as such: r<name_beam>.txt and i<name_beam>.txt, where 'r' and 'i' refer to the real and imaginary part, respectively. If the beam pattern is a component of the E-field, the currents will be calculated assuming a PMC surface. If, on the other hand, the beam pattern is a component of the H-field, the currents will be calculated assuming a PEC surface.

Parameters

name_beam	Name of the beam (without the 'r' or 'i' prefixes or '.txt' suffix).
name_source	Name of source surface on which to define the beam.
comp	Polarisation component of beam. Instance of FieldComponents enum object.
lam	Wavelength of beam, in mm.
normalise	Whether or not to normalise beam to its maximum amplitude.
scale	Scale factor for beam. Defaults to 1.
outname	Name of field/current objects written to system. Defaults to name_beam

See also: setCustomBeamPath

◆ removeCurrent()

def PyPO.System.System.removeCurrent	(		self,
		str	currentName
	)

Remove a PO current from system.

This method takes the name of an internally stored PO current object and removes it from the internal dictionary.

Parameters

curentName Name of current to be removed.

◆ removeField()

def PyPO.System.System.removeField	(		self,
		str	fieldName
	)

Remove a PO field from system.

This method takes the name of an internally stored PO field object and removes it from the internal dictionary.

Parameters

fieldName Name of field to be removed.

◆ removeScalarField()

def PyPO.System.System.removeScalarField	(		self,
		str	fieldName
	)

Remove a scalar PO field from system.

This method takes the name of an internally stored PO scalarfield object and removes it from the internal dictionary.

Parameters

fieldName Name of scalar field to be removed.

◆ runPO()

def PyPO.System.System.runPO	(		self,
		dict	runPODict
	)

Instantiate a PO propagation.

Stores desired output in the internal fields and/or internal currents dictionary. If the 'EHP' mode is selected, the reflected Poynting frame is stored in the internal frame dictionary.

Parameters

PODict Dictionary containing the PO propagation instructions.

See also: PODict

Functions

Detailed Description

Function Documentation

◆ autoConverge()

◆ calcBeamCuts()

◆ calcHPBW()

◆ calcMainBeam()

◆ calcSpillover()

◆ calcTaper()

◆ calcXpol()

◆ createGaussian()

◆ createPointSource()

◆ createPointSourceScalar()

◆ createScalarGaussian()

◆ createUniformSource()

◆ createUniformSourceScalar()

◆ fitGaussAbs()

◆ interpBeam()

◆ mergeBeams()

◆ readCustomBeam()

◆ removeCurrent()

◆ removeField()

◆ removeScalarField()

◆ runPO()