Installation and Usage

• 1: Installation
• 2: Usage
• 3: Writing config file
• 3.1: OpticalChainList
• 3.2: SourceProperties
• 3.3: DetectorOptions
• 3.4: AnalysisOptions

1 - Installation

The code is split into two Python packages:

• AttosecondRayTracing-core that provides the ARTcore module. It contains the actual ray-tracing code, the definitions of the mirrors, sources and detectors.
• AttosecondRayTracing that provides the ART module and requires AttosecondRayTracing-core as a dependency. It contains the plotting and visualisation functions as well as the analsysis functions. It’s the most user-facing part of the codebase.

Unless you really only need the functionality of AttosecondRayTracing-core, we recommend installing AttosecondRayTracing that will pull in the required dependencies.

Basic installation

Using pip

If installing using pip, we recommend installing the dependencies in a virtual environment, for instance using

python -m venv <new_virtual_environment_folder>

This lets you install and use the software without interfering with the system installation of Python.

The installation of the package itself couldn’t be easier:

pip install AttosecondRayTracing

Using Anaconda

Just as with pip, we recommend using a separate virtual environment to install and use ART. TODO actual installation instructions.

Developper installation

If you want to contribute to the development of ART or simply want to modify something for your own needs, you can directly download the source code from the github page.

For instance:

git clone https://github.com/mightymightys/AttosecondRaytracing.git

Contributing

We appreciate any contributions to the code. The best way to do so is by making pull requests on Github.

2 - Usage

Before starting, we strongly recommend checking out the conventions we use in ART.

The entry point into the program is the main() function found in the ARTmain.py file. It has five arguments, one of which is optional:

• OpticalChainList: An OpticalChainList object containing all the optical elements to be simulated with their positions as well as a list of initial source rays.
• SourceProperties: A dict of the properties of the source that will be used for the light simulation
• DetectorOptions: A dict describing the position of the light ray detector or the parameters allowing it to be auto-positionned.
• AnalysisOptions: A dict specifying which plots to display and their options.
• save_file_name (optional): A file name for saving the raw data to be analysed later.

Thus, running the program requires constructing these objects and calling main(). There are two ways to do so:

• Construct them in a script or in an interactive shell or IPython notebook and call the function.
• Run the ARTmain.py file as a program and pass a config file as its first argument.

Using a configuration file

In practice, the config file is simply a Python script similar to what one would write using the first way. The main difference is that it doesn’t contain a call to the main() function.

Indeed, running ARTmain.py as a standalone program with a config file simply loads the file as a module and checks for the presence of attributes with the same names as the arguments of main().

Thus, to write a config file, you simply have to create variables with the same names as the arguments of main().

Running directly

Same as with using a config file, you need to create the arguments for the main() function. Calling it will run the program as well as return the raw data for further analysis.

3 - Writing config file

Whether using a config file or passing the arguments directly to main(), we need to build the objects to be passed to the program. These pages are a quick description of each parameter and how to build them.

3.1 - OpticalChainList

Explanation

The first argument of main() is OpticalChainList, a complete description of the optical setup that needs to be simulated. This includes the absolute positions and orientations of all the optical elements apart from the detector.

Positionning these elements in 3D space by hand would be unnecessarily complicated. Instead, a utility function OEPlacement() has been written to allow you to automatically position these elements, provided you specify the distances between them and the incidence angle on each element.

To position these elements, a prealignment is performed, much like with an alignment laser in real life. A single ray (the central ray within the actual light source) is cast and the Optical Elements are successively positionned in the path of that ray at the specified distance and incidence angle. A reflected ray is then calculated and the algorithm uses it to add the next Optical Element.

It’s perfectly possible to modify the alignment after this prealignment procedure. See for instance here .

Using OEPlacement()

To use OEPlacement() we logically need:

• A Python list of mirrors or masks to be positionned
• A source of light to be used for prealignment (a virtual HeNe laser) described by a dict (see SourceProperties )
• A list of distances between optics. The first value is the distance between source and first optic.
• A list of incidence angles of the central ray on the optical elements.

3.2 - SourceProperties

Running the simulation requires describing the light source. The properties that need to be defined are the following:

• "DeltaFT": This is not actually a property of the light source. Indeed, in the simulation, all photons are considered to be emitted simultaneously in an infinitely short burst. This parameter is actually an analysis parameter, used to check whether the light rays after the optical system have a short enough temporal spread.
• "Wavelength": Similarly to DeltaFT, this is actually an analysis parameter that is used as a reference for the spatial spread of the light rays after the optical system. It can however be used in the future to make wavelength-dependent optics such as gratings.
• "Divergence": This is an actual propertany of the light source: it’s the half-angle of the cone of light emitted by the source as illustrated below.
• "SourceSize": Again, a property of the light source. It’s the diameter of the light source (considered to be a disc). If the light source is a point source, it should be set to 0.
• "NumberRays": The number of rays that the light source will cast and that will be used for the simulation.

Below we provide an example of a 5mm wide source of 80nm light with a 50mrad total divergence, casting 1000 rays and compared in the end to an Airy cylinder of 0.5 femtoseconds.

SourceProperties = {
    'Divergence' : 50e-3/2,
    'SourceSize' : 5,
    'Wavelength' : 80e-6,
    'DeltaFT'    : 0.5,
    'NumberRays' : 1000
}

3.3 - DetectorOptions

The detector is a virtual plane of infinite size which plays the role of a CCD. It can be positionned manually by specifying the position of a point on the detector and its normal vector. However, in the case of ART it made sense to make the positionning of the detector part of the main functionality of the code. Thus, the main() function accepts the DetectorOptions argument. This object allows the code to automatically position the virtual detection plane in the optimal spot. It’s a Python dictionnary with the following possible attributes:

• "ReflectionNumber": This is the number of the optic after the which the detector will be positionned. In most cases that would be the final optic in the setup and we commonly use the Python shorthand for the index of the last element: -1
• "ManualDetector": Setting this to True would disable the automatic positionning of the detector and you would have to also specify "DetectorCentre" and "DetectorNormal" to position it.
• "AutoDetectorDistance": If set to True, the algorithm will automatically optimize the detector position based on the "OptFor", "MaxRaystoConsider" and "IntensityWeighted" options.
• "DistanceDetector": If "AutoDetectorDistance" is True, it will be the starting point for the optimisation. Otherwise, this will be the distance of the detector from the last optical element.

DetectorOptions = {
    'ReflectionNumber' : -1,
    'ManualDetector' : False,
    'DistanceDetector' : 76 ,
    'AutoDetectorDistance' : True,
    'OptFor' : "intensity"
}

3.4 - AnalysisOptions

DefaultAnalysisOptions = {
    "verbose": True,  # print intermediate results and info in the console?
    "plot_Render": False,  # render optical elements and rays, and how many rays to render?
    "maxRaysToRender": 150,
    "DrawAiryAndFourier": True,  # Draw Airy spot and Fourier-limited duration in the following plots?
    "plot_SpotDiagram": False,  # produce an interactive spot diagram without color coding the spots?
    "plot_DelaySpotDiagram": False,  # produce an interactive spot diagram with ray delays color coded?
    "plot_IntensitySpotDiagram": False,  # produce an interactive spot diagram with ray intensities color coded?
    "plot_IncidenceSpotDiagram": False,  # produce an interactive spot diagram with ray incidence angles color coded?
    "plot_DelayGraph": False,  # produce an interactive spot diagram with delays in 3rd dimension?
    "plot_IntensityGraph": False,  # produce an interactive spot diagram with delays in 3rd dimension and ray intensities color coded?
    "plot_IncidenceGraph": False,  # produce an interactive spot diagram with delays in 3rd dimension and ray incidence angles color coded?
    "plot_DelayMirrorProjection": False,  # produce a plot of the ray delays at the detector projected onto the mirror surface?
    "plot_IntensityMirrorProjection": False,  # produce a plot of the ray intensities at the detector projected onto the mirror surface?
    "plot_IncidenceMirrorProjection": False,  # produce a plot of the ray incidence angles at the detector projected onto the mirror surface?
    "save_results": True,  # save the simulation results to disk, to analyse later
    "OEPointsToRender": 2000,
    "OEPointsScale": 0.5,
}