MatrixGroup

class raytracing.MatrixGroup(elements=None, label='')

Bases: Matrix

MatrixGroup: A group of Matrix(), allowing the combination of several elements to be treated as a whole, or treated explicitly as a sequence when needed.

Parameters:

elements (list of elements) – A list of ABCD matrices in the imaging path
label (string) – the label for the imaging path (Optional)

append(matrix)

This function adds an element at the end of the path.

Parameters:: matrix (object of matrix class) – This parameter can be an element defined ABCD matrix like Lens, Space,…
Returns:: matrix – The new appended matrix with the input matrix at the end
Return type:: object of matrix class

Examples

>>> from raytracing import *
>>> # define an empty matrix group
>>> matGrp=MatrixGroup()
>>> matGrp.append(Space(d=10)) # add a matrix of space (d=10)
>>> matGrp.append(Lens(f=10)) # add a matrix of a lens (f=10)
>>> matGrp.append(Space(d=10)) # add a matrix of space (d=10)
>>> print(matGrp) # print to see the output ABCD matrix
|  0.000   10.000 |
|                 |
| -0.100    0.000 |
f=10.000

flipOrientation(): Flip the orientation (forward-backward) of this group of elements. Each element is also flipped individually.

hasFiniteApertureDiameter(): True if ImagingPath has at least one element of finite diameter

insert(index: int, element: Matrix)

This function is used to insert a matrix at a specific index.

Parameters:

index (int) – Index where the matrix is inserted.
element (Matrix) – Matrix object to insert. Can be a single matrix or multiple matrices within a group.

Examples

Let’s insert a 2f system in front of another 2f system to build a 4f system

>>> from raytracing import *
>>> initialGroup = MatrixGroup([Space(10), Lens(10), Space(10)])
>>> print(f"Initial 2f is imaging? {initialGroup.isImaging}")
Initial 2f is imaging? False

>>> initialGroup.insert(0, MatrixGroup([Space(15), Lens(15), Space(15)]))
>>> print(f"Final 4f is imaging? {initialGroup.isImaging}")
Final 4f is imaging? True

Let’s insert an aperture between two 2f systems with infinite diameters >>> from raytracing import * >>> system = MatrixGroup([Space(10), Lens(10), Space(10), Space(10), Lens(10), Space(10)]) >>> print(f”Has finite diameter? {system.hasFiniteApertureDiameter()}”) Has finite diameter? False

>>> system.insert(3, Aperture(50))
>>> print(f"Has finite diameter? {system.hasFiniteApertureDiameter()}")
Has finite diameter? True

See also

raytracing.MatrixGroup.append

intermediateConjugates()

This function calculates the position and the magnification of the conjugate planes.

Returns:: planes – The list of position and magnification of conjugate planes
Return type:: List

Examples

The first index is the position of the conjugate plane and the second index is the magnification

>>> from raytracing import *
>>> # define the elements in the optical path
>>> Lens1=Lens(f=10,label='Lens1') # lens f=10
>>> Spc1=Space(d=30,label='Space1') # space d=10
>>> Lens2=Lens(f=20,label='Lens2') # lens f=20
>>> matGrp=MatrixGroup(elements=[Lens1,Spc1,Lens2]) # make a matrix group of the created elements
>>> # print to see the transfer matrices of the space and the lens
>>> print(matGrp.intermediateConjugates())
[[90.0, -2.0]]

property largestDiameter: Largest finite diameter in all elements

load(filePath, append=False)

A MatrixGroup saved with save() can be loaded using this function.

Parameters:

filePath (str or PathLike or file-like object) – A path, or a Python file-like object, or possibly some backend-dependent object. Must be provided in OS-dependent format.
append (bool) – If True, the loaded elements will be appended to the current list of elements.

pop(index: int)

This function is used to remove a matrix at a specific index.

Parameters:: index (int) – Index where the matrix is removed.
Returns:: poppedElement – The removed matrix.
Return type:: Matrix

Examples

Let’s remove an aperture from a 4f system: >>> from raytracing import * >>> system = MatrixGroup([Space(10), Lens(10), Space(10), Space(10), Lens(10), Space(10), Aperture(100)]) >>> print(f”Has finite diameter? {system.hasFiniteApertureDiameter()}”) Has finite diameter? True

>>> aperture = system.pop(-1) # Removes the last element
>>> print(f"Has finite diameter? {system.hasFiniteApertureDiameter()}")
Has finite diameter? False

save(filePath: str)

A MatrixGroup can be saved using this function and loaded with load()

Parameters:: filePath (str or PathLike or file-like object) – A path, or a Python file-like object, or possibly some backend-dependent object. Must be provided in OS-dependent format.

trace(inputRay)

Trace the input ray from first element until after the last element, indicating if the ray was blocked or not.

Parameters:: inputRay (object of ray class) – A ray with height y and angle theta
Returns:: rayTrace – Returns a ray trace (i.e. [Ray()]) starting with inputRay, followed by the ray after each element.
Return type:: object of ray class

Notes

If an element is composed of sub-elements, the ray will also be traced in several steps. If any element blocks the ray, it will be indicated.

transferMatrices()

The list of Matrix() that corresponds to the propagation through this element (or group). For a Matrix(), it simply returns a list with a single element [self]. For a MatrixGroup(), it returns the transferMatrices for each individual element and appends them to a list for this group.

Returns:: transferMatrices – The transfer matrix for each element in the matrix group
Return type:: List of matrices

Examples

>>> from raytracing import *
>>> # define the elements in the optical path
>>> Spc1=Space(d=10,label='Space1') # space d=10
>>> Lens1=Lens(f=10,label='Lens1') # lens f=10
>>> matGrp=MatrixGroup(elements=[Spc1,Lens1]) # make a matrix group of the created elements
>>> # print to see the transfer matrices of the space and the lens
>>> print(matGrp.transferMatrices()[0])
|  1.000   10.000 |
|                 |
|  0.000    1.000 |
f = +inf (afocal)
>>> print(matGrp.transferMatrices()[1])
|  1.000    0.000 |
|                 |
| -0.100    1.000 |
f=10.000

transferMatrix(upTo=inf)

The transfer matrix between front edge and distance=upTo

Parameters:: upTo (float) – The axial distance from the front edge of the first element (default=+Inf)
Returns:: transferMatrix – The transfer matrix from the front edge of the first element to the distance upTo
Return type:: object of matrix class

Examples

>>> from raytracing import *
>>> # define the elements in the optical path
>>> Spc1=Space(d=10,label='Space1') # space d=10
>>> Len=Lens(f=10,label='Lens') # lens f=10
>>> Spc2=Space(d=10,label='Space2') # space d=10
>>> matGrp=MatrixGroup(elements=[Spc1,Len,Spc2]) # make a matrix group of the created elements
>>> print(matGrp.transferMatrix(upTo=15)) # print to see the transfer matrix in distance=15
|  0.500   10.000 |
|                 |
| -0.100    0.000 |
f=10.000

Notes

If “upTo” falls inside an element of finite length, then it will request from that element a “partial” transfer matrix for a fraction of the length. It is up to the Matrix() or MatrixGroup() to define such partial transfer matrix when possible. Quite simply, Space() defines a partial matrix as Space(d=upTo).

When using this transfer matrix, any information related to rays that have been blocked is lost: apertures are not part of the ray formalism. To find out if a ray has been blocked, you must use trace().

Methods

`__init__`([elements, label])
`append`(matrix)	This function adds an element at the end of the path.
`flipOrientation`()	Flip the orientation (forward-backward) of this group of elements.
`hasFiniteApertureDiameter`()	True if ImagingPath has at least one element of finite diameter
`insert`(index, element)	This function is used to insert a matrix at a specific index.
`intermediateConjugates`()	This function calculates the position and the magnification of the conjugate planes.
`load`(filePath[, append])	A MatrixGroup saved with save() can be loaded using this function.
`pop`(index)	This function is used to remove a matrix at a specific index.
`save`(filePath)	A MatrixGroup can be saved using this function and loaded with load()
`trace`(inputRay)	Trace the input ray from first element until after the last element, indicating if the ray was blocked or not.
`transferMatrices`()	The list of Matrix() that corresponds to the propagation through this element (or group).
`transferMatrix`([upTo])	The transfer matrix between front edge and distance=upTo

Inherited Methods

`backFocalLength`()	The focal lengths measured from the back vertex.
`backwardConjugate`()	With an image at the back edge of the element, where is the object ? Distance before the element by which a ray must travel to reach the conjugate plane at the back of the element.
`display`()
`displayHalfHeight`()	A reasonable height for display purposes for an element, whether it is infinite or not.
`effectiveFocalLengths`()	The effective focal lengths calculated from the power (C) of the matrix.
`focalDistances`()	This is the synonym of effectiveFocalLengths()
`focusPositions`(z)	Positions of both focal points on either side of the element.
`forwardConjugate`()	With an object at the front edge of the element, where is the image? Distance after the element by which a ray must travel to reach the conjugate plane of the front of the element.
`fromFocusToFocus`()	A simple method to obtain a MatrixGroup that includes all three matrices to travel from the front focus, through the lens, and then to the back focus.
`fromStruct`(theStruct)
`frontFocalLength`()	The focal lengths measured from the front vertex.
`magnification`()	The magnification of the element
`mul_beam`(rightSideBeam)	This function calculates the multiplication of a coherent beam with complex radius of curvature q by an ABCD matrix.
`mul_matrix`(rightSideMatrix)	This function is used to combine two elements into a single matrix.
`mul_ray`(rightSideRay)	This function does the multiplication of a ray by a matrix.
`opticalInvariant`(ray1, ray2[, z])	The optical invariant is a quantity that is conserved for any two rays in the system.
`pointsOfInterest`(z)	Any points of interest for this matrix (focal points, principal planes etc...)
`principalPlanePositions`(z)	Positions of the input and output principal planes.
`profileFromRayTraces`(rayTraces[, z])
`toStruct`()
`traceMany`(inputRays[, useOpenCL])	This function trace each ray from a group of rays from front edge of element to the back edge.
`traceManyNative`(inputRays)	This function trace each ray from a group of rays from front edge of element to the back edge.
`traceManyOpenCL`(inputRays)	This function trace each ray from a group of rays from front edge of element to the back edge.
`traceManyThrough`(inputRays[, progress, ...])	This function trace each ray from a list or a Rays() distribution from front edge of element to the back edge.
`traceManyThroughInParallel`(inputRays[, ...])	This is an advanced technique to gain from parallel computation: it is the same as traceManyThrough(), but splits this call in several other parallel processes using the multiprocessing module, which is os-independent.
`traceThrough`(inputRay)	Contrary to trace(), this only returns the last ray.

Attributes

`Struct`
`determinant`	The determinant of the ABCD matrix is always frontIndex/backIndex, which is often 1.0.
`forwardSurfaces`	A list of surfaces that represents the element for drawing purposes
`hasPower`	If True, then there is a non-null focal length because C!=0.
`isIdentity`
`isImaging`	If B=0, then the matrix represents that transfer from a conjugate plane to another (i.e. object at the front edge and image at the back edge).
`largestDiameter`	Largest finite diameter in all elements
`surfaces`