Photon Arrays

class galsim.PhotonArray(N, x=None, y=None, flux=None, dxdz=None, dydz=None, wavelength=None, pupil_u=None, pupil_v=None, time=None)

The PhotonArray class encapsulates the concept of a collection of photons incident on a detector.

A PhotonArray object is not typically constructed directly by the user. Rather, it is typically constructed as the return value of the GSObject.shoot method. At this point, the photons only have x,y,flux values.

Then there are a number of Photon Operators, which perform various modifications to the photons such as giving them wavelengths (WavelengthSampler or inclination angles (FRatioAngles) or move them around according to the effect of differential chromatic refraction (DCR; PhotonDCR).

One could also add functionality to remove some photons due to fringing or vignetting, but these are not yet implemented.

A PhotonArray instance has the following attributes, each of which is a numpy array:

Attributes:

• x – The incidence x position of the photons in image coordinates (pixels), typically measured at the top of the detector.

• y – The incidence y position of the photons in image coordinates (pixels), typically measured at the top of the detector.

• flux – The flux of the photons in units of photons. Typically, these are all 1, but see the note below for reasons some photons might have flux != 1.

• dxdz – The tangent of the inclination angles in the x direction. Note that we define the +z direction as towards towards the dielectric medium of the detector and -z as towards vacuum; consequently, a photon with increasing x in time has positive dxdz.

• dydz – The tangent of the inclination angles in the y direction. Note that we define the +z direction as towards towards the dielectric medium of the detector and -z as towards vacuum; consequently, a photon with increasing y in time has positive dydz.

• wavelength The wavelength of the photons (in nm)

• pupil_u – Horizontal location of photon as it intersected the entrance pupil plane (meters).

• pupil_v – Vertical location of photon as it intersected the entrance pupil plane (meters).

• time – Time stamp for photon impacting the pupil plane (seconds).

Unlike most GalSim objects (but like Image), PhotonArrays are mutable. It is permissible to write values to the above attributes with code like:

>>> photon_array.x += numpy.random.random(1000) * 0.01
>>> photon_array.flux *= 20.
>>> photon_array.wavelength = sed.sampleWavelength(photonarray.size(), bandpass)
etc.

All of these will update the existing numpy arrays being used by the photon_array instance.

Note

Normal photons have flux=1, but we allow for “fat” photons that combine the effect of several photons at once for efficiency. Also, some profiles need to use negative flux photons to properly implement photon shooting (e.g. InterpolatedImage, which uses negative flux photons to get the interpolation correct). Finally, when we “remove” photons, for better efficiency, we actually just set the flux to 0 rather than recreate new numpy arrays.

The initialization constructs a PhotonArray to hold N photons, but does not set the values of anything yet. The constructor allocates space for the x,y,flux arrays, since those are always needed. The other arrays are only allocated on demand if the user accesses these attributes.

Parameters:

• N – The number of photons to store in this PhotonArray. This value cannot be changed.

• x – Optionally, the initial x values. [default: None]

• y – Optionally, the initial y values. [default: None]

• flux – Optionally, the initial flux values. [default: None]

• dxdz – Optionally, the initial dxdz values. [default: None]

• dydz – Optionally, the initial dydz values. [default: None]

• wavelength – Optionally, the initial wavelength values (in nm). [default: None]

• pupil_u – Optionally, the initial pupil_u values. [default: None]

• pupil_v – Optionally, the initial pupil_v values. [default: None]

• time – Optionally, the initial time values. [default: None]

addTo(image)

Add flux of photons to an image by binning into pixels.

Photons in this PhotonArray are binned into the pixels of the input Image and their flux summed into the pixels. The Image is assumed to represent surface brightness, so photons’ fluxes are divided by image pixel area. Photons past the edges of the image are discarded.

Parameters:

image – The Image to which the photons’ flux will be added.

Returns:

the total flux of photons the landed inside the image bounds.

allocateAngles()

Allocate memory for the incidence angles, dxdz and dydz.

allocatePupil()

Allocate the memory for the pupil coordinates, pupil_u and pupil_v.

allocateTimes()

Allocate the memory for the time stamps, time.

allocateWavelengths()

Allocate the memory for the wavelength array.

assignAt(istart, rhs)

Assign the contents of another PhotonArray to this one starting at istart.

Parameters:

• istart – The first index at which to insert new values.

• rhs – The other PhotonArray from which to get the values.

classmethod concatenate(photon_arrays)

Create a single PhotonArray from a list of multiple PhotonArrays.

The size of the created PhotonArray will be the sum of the sizes of the given arrays, and the values will be concatenations of the values in each.

Note

The optional value arrays (e.g. dxdz, wavelength, etc.) must be given in all the given photon_arrays or in none of them. This is not checked.

Parameters:

photon_arrays – A list of PhotonArray objects to be concatenated.

convolve(rhs, rng=None)

Convolve this PhotonArray with another.

..note:

If both self and rhs have wavelengths, angles, pupil coordinates or times assigned,
then the values from the first array (i.e. self) take precedence.

copyFrom(rhs, target_indices=slice(None, None, None), source_indices=slice(None, None, None), do_xy=True, do_flux=True, do_other=True)

Copy some contents of another PhotonArray to some elements of this one.

Specifically each element of rhs[source_indices] is mapped to self[target_indices]. The values s1 and s2 may be slices, list of indices, or anything else that is a valid key for a numpy array.

Parameters:

• rhs – The PhotonArray from which to get values.

• target_indices – The indices at which to assign values in the current PhotonArray (self). [default: slice(None)]

• source_indices – The indices from which to get values from the PhotonArray, rhs. [default: slice(None)]

• do_xy – Whether to include copying the x and y arrays. [default: True]

• do_flux – Whether to include copying the flux array. [default: True]

• do_other – Whether to include copying the other arrays (angles, wavelength, pupil positions, time). [default: True]

property dxdz

dx/dz.

Type:

The tangent of the inclination angles in the x direction

property dydz

dy/dz.

Type:

The tangent of the inclination angles in the y direction

property flux

The flux of the photons.

classmethod fromArrays(x, y, flux, dxdz=None, dydz=None, wavelength=None, pupil_u=None, pupil_v=None, time=None, is_corr=False)

Create a PhotonArray from pre-allocated numpy arrays without any copying.

The normal PhotonArray constructor always allocates new arrays and copies any provided initial values into those new arrays. This class method, by constrast, constructs a PhotonArray that references existing numpy arrays, so that any PhotonOps or photon shooting of GSObjects applied to the resulting PhotonArray will also be reflected in the original arrays.

Note that the input arrays must all be the same length, have dtype float64 and be c_contiguous.

Parameters:

• x – X values.

• y – X values.

• flux – Flux values.

• dxdz – Optionally, the initial dxdz values. [default: None]

• dydz – Optionally, the initial dydz values. [default: None]

• wavelength – Optionally, the initial wavelength values (in nm). [default: None]

• pupil_u – Optionally, the initial pupil_u values (in m). [default: None]

• pupil_v – Optionally, the initial pupil_v values (in m). [default: None]

• time – Optionally, the initial time values (in s). [default: None]

• is_corr – Whether or not the photons are correlated. [default: False]

getTotalFlux()

Return the total flux of all the photons.

hasAllocatedAngles()

Returns whether the arrays for the incidence angles dxdz and dydz have been allocated.

hasAllocatedPupil()

Returns whether the arrays for the pupil coordinates pupil_u and pupil_v have been allocated.

hasAllocatedTimes()

Returns whether the array for the time stamps time has been allocated.

hasAllocatedWavelengths()

Returns whether the wavelength array has been allocated.

isCorrelated()

Returns whether the photons are correlated

classmethod makeFromImage(image, max_flux=1.0, rng=None)

Turn an existing Image into a PhotonArray that would accumulate into this image.

The flux in each non-zero pixel will be turned into 1 or more photons with random positions within the pixel bounds. The max_flux parameter (which defaults to 1) sets an upper limit for the absolute value of the flux of any photon. Pixels with abs values > maxFlux will spawn multiple photons.

Parameters:

• image – The image to turn into a PhotonArray

• max_flux – The maximum flux value to use for any output photon [default: 1]

• rng – A BaseDeviate to use for the random number generation [default: None]

Returns:

a PhotonArray

property pupil_u

Horizontal location of photon as it intersected the entrance pupil plane.

property pupil_v

Vertical location of photon as it intersected the entrance pupil plane.

classmethod read(file_name)

Create a PhotonArray, reading the photon data from a FITS file.

The file being read in is not arbitrary. It is expected to be a file that was written out with the PhotonArray.write method.:

>>> photons.write('photons.fits')
>>> photons2 = galsim.PhotonArray.read('photons.fits')

Parameters:

file_name – The file name of the input FITS file.

scaleFlux(scale)

Rescale the photon fluxes by the given factor.

Parameter:

scale: The factor by which to scale the fluxes.

scaleXY(scale)

Scale the photon positions (x and y) by the given factor.

Parameter:

scale: The factor by which to scale the positions.

setCorrelated(is_corr=True)

Set whether the photons are correlated

setTotalFlux(flux)

Rescale the photon fluxes to achieve the given total flux.

Parameter:

flux: The target flux

size()

Return the size of the photon array. Equivalent to len(self).

property time

Time stamp of when photon encounters the pupil plane.

property wavelength

The wavelength of the photons (in nm).

write(file_name)

Write a PhotonArray to a FITS file.

The output file will be a FITS binary table with a row for each photon in the PhotonArray. Columns will include ‘id’ (sequential from 1 to nphotons), ‘x’, ‘y’, and ‘flux’. Additionally, the columns ‘dxdz’, ‘dydz’, and ‘wavelength’ will be included if they are set for this PhotonArray object.

The file can be read back in with the classmethod PhotonArray.read:

>>> photons.write('photons.fits')
>>> photons2 = galsim.PhotonArray.read('photons.fits')

Parameters:

file_name – The file name of the output FITS file.

property x

The incidence x position in image coordinates (pixels), typically at the top of the detector.

property y

The incidence y position in image coordinates (pixels), typically at the top of the detector.