Physical Optics Methods

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

Functions
	PyPO.System.System.removeField (self, fieldName)
	Remove a PO field from system.
	PyPO.System.System.removeCurrent (self, currentName)
	Remove a PO current from system.
	PyPO.System.System.removeScalarField (self, fieldName)
	Remove a scalar PO field from system.
	PyPO.System.System.readCustomBeam (self, name_beam, name_source, comp, lam, normalise=True, scale=1)
	Read a custom beam from disk into the system.
	PyPO.System.System.runPO (self, runPODict)
	Instantiate a PO propagation.
	PyPO.System.System.mergeBeams (self, *beams, obj="fields", merged_name="combined")
	Merge multiple beams that are defined on the same surface.
	PyPO.System.System.createGaussian (self, gaussDict, name_surface)
	Create a vectorial Gaussian beam.
	PyPO.System.System.createScalarGaussian (self, gaussDict, name_surface)
	Create a scalar Gaussian beam.
	PyPO.System.System.calcSpillover (self, name_field, comp, aperDict)
	Calculate spillover efficiency of a beam defined on a surface.
	PyPO.System.System.calcTaper (self, name_field, comp, aperDict=None)
	Calculate taper efficiency of a beam defined on a surface.
	PyPO.System.System.calcXpol (self, name_field, comp_co, comp_cr)
	Calculate cross-polar efficiency of a field defined on a surface.
	PyPO.System.System.fitGaussAbs (self, name_field, comp, thres=None, mode=Modes.LIN, full_output=False, ratio=1)
	Fit a Gaussian profile to the amplitude of a field component and adds the result to scalar field in system.
	PyPO.System.System.calcMainBeam (self, name_field, comp, thres=None, mode=Modes.LIN)
	Calculate main-beam efficiency of a beam pattern.
	PyPO.System.System.calcBeamCuts (self, name_field, comp, phi=0, center=True, align=True, norm=False, transform=False, mode=Modes.dB)
	Calculate cross sections of a beam pattern.
	PyPO.System.System.calcHPBW (self, name_field, comp, interp=50, center=False, align=False)
	Calculate half-power beamwidth.
	PyPO.System.System.createPointSource (self, PSDict, name_surface)
	Generate point-source PO fields and currents.
	PyPO.System.System.createUniformSource (self, UDict, name_surface)
	Generate uniform PO fields and currents.
	PyPO.System.System.createPointSourceScalar (self, PSDict, name_surface)
	Generate point-source scalar PO field.
	PyPO.System.System.createUniformSourceScalar (self, UDict, name_surface)
	Generate scalar uniform PO fields and currents.
	PyPO.System.System.interpBeam (self, name, gridsize_new, obj_t="fields")
	Interpolate a PO beam.
	PyPO.System.System.autoConverge (self, source_field, name_target, tol=1e-2, add=10, patch_size=1/9, max_iter=1000)
	Calculate gridsize for which calculation converges.

Detailed Description

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

Function Documentation

autoConverge()

PyPO.System.System.autoConverge	(		self,
			source_field,
			name_target,
			tol = 1e-2,
			add = 10,
			patch_size = 1/9,
			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()

PyPO.System.System.calcBeamCuts	(		self,
			name_field,
			comp,
			phi = 0,
			center = True,
			align = True,
			norm = False,
			transform = False,
			mode = Modes.dB )

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.
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.
mode	Return beamcuts in linear or decibel values. Instance of Modes enum object.

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()

PyPO.System.System.calcHPBW	(		self,
			name_field,
			comp,
			interp = 50,
			center = False,
			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.
interp	Interpolation factor for finding the HPBW. Defaults to 50.
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()

PyPO.System.System.calcMainBeam	(		self,
			name_field,
			comp,
			thres = None,
			mode = Modes.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.
mode	Fit to amplitude in decibels, linear or logarithmically.

Returns

eff Main-beam efficiency.

calcSpillover()

PyPO.System.System.calcSpillover	(		self,
			name_field,
			comp,
			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()

PyPO.System.System.calcTaper	(		self,
			name_field,
			comp,
			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()

PyPO.System.System.calcXpol	(		self,
			name_field,
			comp_co,
			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()

PyPO.System.System.createGaussian	(		self,
			gaussDict,
			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()

PyPO.System.System.createPointSource	(		self,
			PSDict,
			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()

PyPO.System.System.createPointSourceScalar	(		self,
			PSDict,
			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()

PyPO.System.System.createScalarGaussian	(		self,
			gaussDict,
			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()

PyPO.System.System.createUniformSource	(		self,
			UDict,
			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()

PyPO.System.System.createUniformSourceScalar	(		self,
			UDict,
			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()

PyPO.System.System.fitGaussAbs	(		self,
			name_field,
			comp,
			thres = None,
			mode = Modes.LIN,
			full_output = False,
			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.
mode	Fit to amplitude in decibels, linear or logarithmically. Instance of Modes enum object.
full_output	Return fitted parameters and standard deviations.

Returns

popt Fitted beam parameters.

perr Standard deviation of fitted parameters.

interpBeam()

PyPO.System.System.interpBeam	(		self,
			name,
			gridsize_new,
			obj_t = "fields" )

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()

PyPO.System.System.mergeBeams	(		self,
		*	beams,
			obj = "fields",
			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()

PyPO.System.System.readCustomBeam	(		self,
			name_beam,
			name_source,
			comp,
			lam,
			normalise = True,
			scale = 1 )

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.

See also

setCustomBeamPath

removeCurrent()

PyPO.System.System.removeCurrent	(		self,
			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()

PyPO.System.System.removeField	(		self,
			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()

PyPO.System.System.removeScalarField	(		self,
			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()

PyPO.System.System.runPO	(		self,
			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