Introduction
=============

gtrace is a python package to trace the propagation of Gaussian beams among optical components such as mirrors and lenses. The features of gtrace include:

 * Automatically track the Gaussian beam propagation, i.e. q-parameter change, using the ABCD matrix method.
 * Reflection and refraction at interface surfaces are properly treated.
 * Automatically track the optical distance traveled by a beam through dielectric media.
 * Sequential or non-sequential trace modes are available.
 * Exporting the results to DXF files

The main motivation behind the development of gtrace was to help the design of the optical layout for the `KAGRA <http://gwcenter.icrr.u-tokyo.ac.jp/en/>`_ interferometer. The task is not so trivial because we had to satisfy many constraints at the same time. Manually placing mirrors on a CAD and adjusting the distances between the mirrors and their orientations was not an option. We needed a way to automatically adjust the optical layout with a computer to satisfy our requirements. In order to do this, we needed a tool to represent an optical layout convenient for computer processings. gtrace represents mirrors and beams as class objects in python. Then the propagation of the beams can be treated as interactions between the beams and the mirrors. This way, we can automate the optimization of the KAGRA optical layout.

The main ingredients of gtrace are mirrors and beams. A mirror is represented as an instance of :py:class:`Mirror <gtrace.optcomp.Mirror>` class. You place mirrors in a 2D plane. You can set various properties of a mirror such as size, curvature, reflectivities, wedge angle etc. Then you launch a beam, an instance of :py:class:`GaussianBeam<gtrace.beam.GaussianBeam>` class, from a certain point in the 2D plane. As the beam hits mirrors, it is divided into several sub-beams, such as reflections and deflected beams. These newly generated beam objects are available to you for further propagation. In the non-sequential mode, these sub-beams are automatically propagated until one of the termination conditions is satisfied. The termination conditions include, not hitting any mirror, power is below a certain threshold and so on. At the end of the propagation, you will have a collection of beam objects generated by the collision with the mirrors. You can export the mirrors and the beams into a DXF file. 

gtrace is at this moment limited to 2D optical layouts. This limitation might be lifted in the future.

.. .. math:: \int^{\infty}_{-1} e^{i\omega t} dt


