Parallel

class marxs.simulator.Parallel(**kwargs)[source] [edit on github]

Bases: BaseContainer

A container for several identical optical elements.

This object describes a set of similar elements that operate in parallel, meaning that each photon will only interact with one of them (although that is not enforced by the current implementation). Examples for such an optical element would be the ACIS-I CCD detector on Chandra, that consists for four CCD chips or the HETGS gratings that are made up of many individual grating facets.

The Parallel class requires a description of the individual components and a list of their positions. This class has build-in support to simulate uncertainties in the manufacturing process. After generation, individual positions can be adjusted by hand by editing the elem_pos. Also, additional misalingments for each element can be introduced by editing elem_uncertainty. This attribute holds a list of affine transformation matrices. The global position and rotation of the combined element can be changed with uncertainty, e.g. the represent the reproducibility of inserting the gratings into the beam for separate observations or the positioning of detectors on a detector wheel. The uncertainty is expressed as an affine transformation matrix.

All uncertainty matrices should only consist of translation and rotations and all uncertainties should be relatively small.

After any of the attributes elem_pos, elem_uncertainty or uncertainty is changed, generate_elements needs to be called to regenerate the positions of the individual elements using

  • the global position of Parallel.pos4d

  • the position of each element Parallel.elem_pos relative to the global position

  • the global uncertainty uncertainty.

  • the uncertainty for individual facets.

This mechanism can be used to estimate the influence of manufacturing uncertainties. First, run a simulation with optimal position, then change the values, regenerate the facets and rerun the simulation. Comparing the results will allow you to estimate the effect of the manufacturing misalignment.

The order in which all the transformations are applied to the facet is chosen such that all rotations are done around the center of the individual element or the whole structure respectively. “Uncertainty” rotations are always done after all other rotations are accounted for.

Parameters:
elem_classclass

Class of the individual elements

elem_argsdict

Dictionary of keyword arguments that are used to initialize the individual arguments. This can contain position related keywords as listed in pos4d; those will be applied to each element (e.g. set the zoom for each of them). Usually, the same arguments will be applied to all facets. In the special case that the value of a dictionary entry is a list with the same length as elem_pos, one value of this list will be used for each element. This makes it possible to specify e.g. different grating constants for individual facets. (Note that this has to be a list. Other python types like tuple or np.array that behave like lists in some contexts are not allowed here to avoid ambiguities.)

elem_poslist of arrays or dictionary of lists

Gives the position of the individual elements in the local coordinate system of the Parallel object. This can either be a list of (4,4) np.arrays or a dictionary with entries of pos4d or position, orientation and zoom as explained in Coordinate system where each entry in the dictionary is a list of values ((3,3) matrices for orientation, (3,) vectors for position etc.). Sub-classes of Parallel can implement a method calculate_elempos to determine the position of their elements automatically. In this case, they should set elem_pos=None.

id_num_offsetint

ID numbers of generated elements start at this number.

Examples

In this example we build up a detector made up of four CCDs. Each CCD is 10 mm * 10 mm large and has a pixel size of 0.01 mm. The CCDs are set in a square with small spaces in between.

>>> from marxs.simulator import Parallel
>>> from marxs.optics import FlatDetector as CCD
>>> detect = Parallel(elem_class=CCD, elem_args={'pixsize': 0.01, 'zoom': 5},
...                   elem_pos={'position': [[0, -10.1, -10.1],[0, .1, -10.1],[0, -10.1, .1],[0, .1, .1]]},
...                   id_col='CCD_ID')

A column that notes which CCD was hit by each photon will be added to the photon table when it is processed by photons = detect(photons). The name of this colum will be “CCD_ID”. (If the id_col argument is not passed, the name will be the generic “element”.)

Define a new MARXS element.

Attributes Summary

id_col

String that names an id column for output.

pos4d

uncertainty

Uncertainty of pos4d.

Methods Summary

generate_elements()

Initialize all optical elements.

move_center(change4d)

Move the relative origin of the coordinate system.

Attributes Documentation

id_col = 'element'

String that names an id column for output.

Set this to a string to add an automatic numbering to the output. This is especially useful if there are several identical optical components that are used in parallel, e.g. there are four identical CCDs. Setting id_col = "CCD_ID" and passing an id_num=1, 2, 3, 4 keyword respectively to each CCD will add a column CCD_ID with a value of 1,2,3, or 4 for each photon hitting one of those CCDs.

Currently, this will not work with all optical elements.

pos4d
uncertainty = array([[1., 0., 0., 0.],        [0., 1., 0., 0.],        [0., 0., 1., 0.],        [0., 0., 0., 1.]])

Uncertainty of pos4d.

The global position and rotation of the combined element can be changed with uncertainty, e.g. the represent the reproducibility of inserting the gratings into the beam for separate observations or the positioning of detectors on a detector wheel. The uncertainty is expressed as an affine transformation matrix.

Methods Documentation

generate_elements()[source] [edit on github]

Initialize all optical elements.

After any of the elem_pos, elem_uncertainty or uncertainty attributes has changed, generate_elements needs to be called to regenerate the positions of the individual elements using

  • the global position of Parallel.pos4d

  • the position of each element Parallel.elem_pos relative to the global position

  • the global uncertainty uncertainty.

  • the uncertainty for individual facets.

move_center(change4d)[source] [edit on github]

Move the relative origin of the coordinate system.

Individual element positions in elem_pos are relative to the global pos4d of this object. This function changes the pos4d and adjusts the elem_pos accordingly, so that the elements still have the same position in global coordinates.

This function is useful when studying uncertainties. The attribute uncertainty can be used to apply the same change to all elements. Any rotation will be applied around the reference position contained in pos4d. Use this function to change that reference position.

Parameters:
change4dnp.array of shape (4,4)

Homogeneous coordinate transformation matrix