Using the PropagationController

Top  Previous  Next

As an introduction to the present section, users should review the previous overview section on setting up Fresnel propagations.

PropagationController is a library subsystem that defines the Fresnel propagation mesh, in addition to several other propagation-related parameters.  Every LightLike system should contain at least one PropagationController for outgoing waves, and at least one for incoming waves (if the respective waves are present). However, some commonly-used library systems that specify atmospheric turbulence already contain two PropagationControllers (one for each direction).  The prime example is AtmoPath, which is a composite system consisting of GeneralAtmosphere and two PropagationControllers.  Therefore, it may be unnecessary for the user to explicitly add PropagationControllers to the overall system.  If the options provided in AtmoPath or analogous modules are sufficient for the user's purposes, then no extra controllers are required.

If a PropagationController is explicitly inserted, it can be placed anywhere along the path between the source and sensor to which it should apply.  A situation that always requires explicit insertion of a PropagationController is a test system that has zero total propagation distance, and therefore contains no AtmoPath or analogous module.  Such a system will usually be a test system used to investigate the behavior of a portion of a full propagation system.  Multiple controllers in a system are also allowed:  this is explained further in a later subsection.

Parameters of PropagationController

The picture below shows the interface of PropagationController.  As we see from the single input and output, one PropagationController applies to one LightLike (possibly containing numerous separate waves) traveling in one direction, either incoming or outgoing.  We now discuss some of the parameters that must be set.


targetGrid:  this parameter is set by using a LightLike library function that defines meshes.  The user should change only the (nxy,dxy) symbols that are arguments of the function:  these define the dimension and spacing of the propagation mesh. General considerations and restrictions regarding LightLike meshes are explained elsewhere.  As usual in LightLike when setting parameter values, (nxy,dxy) can be replaced by numerical values right here or the symbols can be elevated (promoted) up the hierarchy.  The argument syntax (nxy,dxy)may be replaced by  (nx,ny,dx,dy) if the user wishes to use an asymmetric mesh.  However, it is important to remember that a "long" mesh dimension is NOT required merely because there is transverse motion in the simulation (the implications of transverse motion for propagation and phase-screen meshes were discussed previously).

x{y}ReferenceFocus:  these parameters allow selection of a planar or spherical reference wave for the Fresnel propagation operations.  Each Focus is a directed distance in meters.  Infinity focus, which is specified to the code by setting Focus=0.0, specifies a planar reference wave.  The subject of reference waves is discussed in more detail in the User Guide section on optical propagators and on the selection of propagation parameters.

oneTimeSpatialFilter, spatialFilter, absorbingBoundary:  these are advanced options that can be used to specify certain anti-aliasing or wrap-around measures in the Fresnel propagation FFT calculations.  A few further remarks on these subjects may be found in the User Guide section on selection of propagation parameters.  The NullFilter() settings shown in the above picture disables these options.  User desiring further details of the available settings should contact TimeLike Systems.

pointSourceModel:  this setting only pertains to the operation of LightLike's PointSource (and derivative) source modules.  The discrete numerical modeling of propagation from a point source poses special problems, and the general issues are discussed in a separate section.  In brief, LightLike offers two methods of modeling point sources, and the desired method is selected by setting the value of the pointSourceModel parameter.  For most purposes, we recommend the setting DEFAULT_PSM, as shown in the above illustration (note that PSM = Point Source Model).  This selects back-propagation method of modeling the point source.  If DEFAULT_PSM is used, then the associated parameters superApDiameter and edgeSigma also come into play.

superApDiameter:  the diameter, in meters, of the "super-aperture" used in the back-propagation method of modeling point sources (pointSourceModel = DEFAULT_PSM).  The super-aperture diameter should be somewhat larger than the diameter of the actual receiver aperture.  There is no exact rule, but a factor of 1.5 is typically satisfactory.

edgeSigma: a roll-off width parameter, in meters, that modifies the "super-aperture" used in the back-propagation method of modeling point sources.  A non-zero Gaussian rolloff is added to the radius of the uniform-amplitude region that is back-propagated to form the "point" source.  There is no exact rule, but a typical setting would be edgeSigma =  several times the propagation mesh spacing.

speckleModel:  this setting only pertains to the operation of the rough-surface reflector modules, such as CoherentTarget, IncoherentReflector, and PartiallyCoherentReflector.  The discrete numerical modeling of propagation from an optically-rough reflector poses special problems, and the general issues are discussed in a separate section.  The setting options for speckleModel are: (a) DEFAULT_SM,  (b) DELTA_CORRELATED_SM.  We recommend the option DEFAULT_SM (note that SM = Speckle Model):  this setting applies a super-aperture back-propagation concept to the wave propagated from a rough reflector.  This means that the parameters superApDiameter and edgeSigma are also relevant to light emanating from rough reflectors, if DEFAULT_SM is selected.

useDispersion:  this setting, whose allowed values are true or false, determines whether a wavelength dispersion model will be applied to the atmospheric propagation.  The true setting is only applicable if at least two different wavelengths are present in the simulation system.  If dispersion is applied, then nominal propagation axes will be appropriately "bent" so that beams of different colors sample slightly different portions of the atmospheric turbulence screens.  The path "bending" is done relative to one of the system wavelengths, which the user specifies as the nominalWavelength

nominalWavelength:  see the useDispersion parameter.


Use of multiple PropagationControllers

For reasons of convenience or user preference in building systems, it is allowed for a LightLike system to contain more than one PropagationController (counting the ones inside AtmoPath or analogous modules) for a given direction of propagation.  If there are multiple controllers for a given direction, then the one closest (downstream) to a source overrides the settings in the others.  Sometimes redundant controllers are inserted simply as a matter of user preference, but it might also happen that one wants to use different meshes or other settings to propagate different sources.  The following figure gives an example:


In the model shown above, propagation from pointsource and pointsource2 is controlled by the PropagationController inside AtmoPath, but propagation from pointsource3 is controlled by the extra explicitly inserted PropagationController.  All this follows from the rule "controller closest (downstream) to the source".