%% optikz version 1.1.0 
%% Copyright (C) 2025 Martin Beyer
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
% 
% The Current Maintainer of this work is Martin Beyer.
%
% This work consists of the files optikz.sty optikz_doc.tex and 
% the optikz_doc_code folder which contains all examples used in the documentation

\documentclass[fontsize=12pt,rgb]{scrartcl}
\usepackage{optikz}
\usepackage{graphicx}
\usepackage{siunitx}
\usepackage[font=small]{caption}
\usepackage{fourier}
\usepackage{hyperref}
\usepackage{multicol}
\usepackage[a4paper, left=2.5cm, right=2.5cm, top=2.5cm, bottom=3cm]{geometry}
\usepackage{listings}
\usepackage{amsmath}

% Define custom colors
\definecolor{codebg}{rgb}{0.97,0.97,0.97}
\definecolor{keywordcolor}{rgb}{0.1,0.1,0.8}
\definecolor{commentcolor}{rgb}{0.4,0.4,0.4}
\definecolor{stringcolor}{rgb}{0.0,0.5,0.0}
\definecolor{identifiercolor}{rgb}{0.4, 0.0, 0.4}

% Configure listings for LaTeX code
\lstdefinestyle{latexstyle}{
  backgroundcolor=\color{codebg},
  basicstyle=\ttfamily\small,
  keywordstyle=\color{keywordcolor}\bfseries,
  stringstyle=\color{stringcolor},
  commentstyle=\color{commentcolor}\itshape,
  identifierstyle=\color{identifiercolor},
  numbers=left,
  numberstyle=\tiny\color{gray},
  numbersep=8pt,
  showstringspaces=false,
  breaklines=true,
  frame=single,
  tabsize=2,
  escapeinside={(*@}{@*)},
  language=[LaTeX]TeX
}

\lstset{style=latexstyle}
\definecolor{Gruen}{cmyk}{1,0.1,0.7,0.5}
\setlength{\parindent}{0pt}


\usetikzlibrary{external}
% \tikzexternalize[prefix=optikz_doc_figures/] % activate!
 
\newcommand{\inputtikz}[1]{%
  \tikzsetnextfilename{#1}%
  \input{optikz_doc_code/#1.tex}%
}


\begin{document}

\newcommand{\HRule}{\rule{\linewidth}{0.5mm}}
\begin{titlepage}
  \center
  \HRule \\[0.4cm]
  { \Huge The \texttt{Optikz} Package}\\[0.15cm]
  \HRule \\[0.5cm]
  \textsc{\Large Martin Beyer}\\[0.35cm]
  \textsc{February 16th, 2026,  Version 1.1.0}\\[0.35cm]
  \vfill
  \inputtikz{example_CPA_system}
  \vfill
  \begin{multicols}{2}
    \tableofcontents
\end{multicols}
\end{titlepage}


\section{Introduction}
Welcome to the documentation of Optikz, a ``\LaTeX{} package'' used for creating pictures of optical laser setups using Tikz. The design of the optical components is heavily inspired by the ``\href{https://www.gwoptics.org/ComponentLibrary/}{\texttt{Components library}}'' of Alexander Franzen.

The code relies on the \texttt{TikZ} package which is automatically loaded when calling this package. 
This project was initially conceptuated for creating schematic drawings in my Bachelor thesis in 2020. Since then I refined my code and decided to write a small documentation about it.


\section{Tutorial}
Karl\footnote{The paragraph is inspired by the Tutorial of the TIKZ documentation by Till Tantau} is a laser physicist at a research institute. He used to create the graphics of his laser setups with programs like Gimp or Inkscape. While his graphics were acceptable, drawing them was often a lengthy and tedious process. Also, when he wanted to change anything in his graphics, he had to reopen his graphics program and export every single image again. When he wanted to include text into his graphics, it always seemed to be a bit off compared to font size of his \LaTeX \; project. Therefore, he decided to draw his graphics using Tikz. However, creating nice drawings of mirrors, lenses and measurement devices seemed way too complicated. Karl's colleague was not satisfied with the results of his graphics, so he told Karl about a small package to help him with his problem.

With this package called Optikz, Karl can now draw all optical elements of his desire without having to worry about their graphical design. He starts by opening a Tikz environment:

\begin{lstlisting}
\documentclass{article}
\usepackage{optikz}
\begin{document}
    \begin{tikzpicture}
        ...
    \end{tikzpicture}
\end{document}
\end{lstlisting}

First he adds a mirror to his setup. He notices that the \verb!\mirror! command has several optional arguments. They are as follows:
\begin{itemize}
    \item \texttt{angle}: Defines the angle to the $x$-axis.
    \item \texttt{width}: Defines the width or diameter (standard value: 1) of the mirror.
    \item \texttt{thickness}: Defines the thickness (standard value: 1) of the mirror.
    \item \texttt{color}: Changes the color of the mirror.
    \item \texttt{shift}: shifts the anchor point along the surface of the mirror (standard value: 0).
\end{itemize}
Karl now starts with a simple drawing of a delay stage with two colored, off-centered mirrors. He notices that he can either specify the coordinates of the mirrors directly or define the coordinates first using tikz and draw the mirrors at the coordinate positions. 
\begin{figure}[htp]
    \centering
    \inputtikz{tutorial_delay_stage}
    \caption{Drawing of a simple delay stage. It is advised to define a coordinate for every optical element, this binds the laser beam position to the mirror positions, such that changes of the mirror positions can be made easily.}
\end{figure}

\lstinputlisting{optikz_doc_code/tutorial_delay_stage.tex}

\newpage
\section{Documentation}

\subsection{Colors}
Optikz defines several colors, which are used for the various optical components, they are defined as follows:
\begin{lstlisting}
\definecolor{optikzblue}{rgb}{0.56,0.663,0.723}
\definecolor{optikzred}{rgb}{0.7,0.2,0.2}
\definecolor{optikzyellow}{rgb}{1,0.86,0}
\end{lstlisting}

Generally, the color of every single component can be changed by using the \texttt{$\backslash$color} argument when creating the optical component. Note that \texttt{optikzblue} is the standard color used in the \texttt{$\backslash$color} argument. If you want to change the colorscheme of Optikz, you can do that by redefining the colors. This is done with 
\begin{lstlisting}
\redefinecolor{optikzblue}{0.1,0.1,0.1}
\end{lstlisting}
where the second argument is the \texttt{rgb} value of the color. If you ever want to roll back to the standard colors you can do that with:
\begin{lstlisting}
\resetcolor{optikzblue}
\end{lstlisting}

\subsection{Rays and beams}
In an optical system, we often represent the path of the laser beam with a simple line and a little arrow to indicate the directionality. However, sometimes we also want to indicate the size of the beam as well, especially for beam lines with higher power or optical stretchers with gratings or prisms. 
\paragraph{Rays} The drawing of a laser ray is quite simple. We just use the standard TikZ \verb!\draw! function to visualize a ray in our system. We can draw an arrow to indicate the direction of the beam in the following way: 

\begin{figure}[htp]
  \centering
  \inputtikz{doc_ray_direction}
  \caption{Draw a simple ray with TikZ.}
\end{figure}
\lstinputlisting{optikz_doc_code/doc_ray_direction.tex}

The custom node \verb!\laserdir! has some options we can utilize:
\begin{lstlisting}
node[laserdir, pos=0.5, xscale=1, color=black]{\laserdir}
\end{lstlisting}
With \verb!pos! we can change the position along the line segment, \verb!xscale = {-1,1}! changes the direction of the arrow and \verb!color! changes the color of the arrowhead.

\paragraph{Beams} Furthermore, we can also draw beams and even indicate wavelength splitting e.g. in an optical stretcher. For a beam we need the anchor points of the mirrors for each segment, their angle and and some optional parameters (beam size, color). Both beam types are defined as follows:
\begin{lstlisting}
\drawrainbow[width start=0.8,
             width end=0.8,
             opacity=0.7]
            {pos M1}
            {pos M2}
            {angle M1}
            {angle M2}
            
\drawbeam[width start=0.8,
          width end=0.8,
          fill color=optikzred,
          draw color=black,
          opacity=0.7]
         {pos M1}
         {pos M2}
         {angle M1}
         {angle M2}
\end{lstlisting}
Notice that \verb!drawbeam! has two additional optional arguments to specify the fill and border color of the beam. The opacity of the beam is set to \SI{70}{\percent} to visualize overlapping parts. Then, we can draw a picture as shown in figure~\ref{fig:doc_beam}.
\begin{figure}[htp]
  \centering
  \inputtikz{doc_beam}
  \caption{Drawing of a rainbow beam (left) and normal beam (right).}
  \label{fig:doc_beam}
\end{figure}
\lstinputlisting{optikz_doc_code/doc_beam.tex}

\clearpage
\subsection{Optical elements}
Most optical elements follow the same command structure as for a TikZ-Node. The only mandatory argument for each component is it's $(x,y)$ position. This can be passed by stating the coordinate directly or by passing a TikZ-coordinate. The optional arguments are passed with their respective keywords in a square bracket after the command. A complete list of all optional arguments can be found in section~\ref{sec:Optional_arguments}.
\paragraph{Definition} Every optical elements is defined by this command structure:

\begin{lstlisting}
% standard command
\command[<optional paramer>=value] at (x,y); 

% specifying the coordinates via a TikZ-coordinate
\coordinate (P1) at (x,y);
\command[<optional paramer>=value] at (P1); 
\end{lstlisting}

\paragraph{Positioning} Due to the law of reflection, the angle of a reflective optical element is given by the position of the previous and next element. Therefore, we can use \verb!\optikzanglethreepoints! to determine the angle in reference to the input and output beam direction. Furthermore, we can use \verb!\optikzangletwopoints! determine the angle of an optical element which is aligned on a beam bath between two points A and B.

\begin{lstlisting}
% Calculate the half angle of the triangle ABC 
\optikzanglethreepoints{A}{B}{C}{\varname}

% Calculate the angle of the vector AB with the x-axis
\optikzangletwopoints{A}{B}{\varname}
\end{lstlisting}


\begin{figure}[htp]
  \centering
  \inputtikz{doc_calc_angle_example}
  \caption{Left: Automatic calculation of the angle of three mirrors based only on the mirror positions by using \texttt{optikzanglethreepoints}.  Right: Automatic positioning of optical elements along a line defined by two points by using \texttt{optikzangletwopoints}.}
  \label{fig:doc_calc_angle_example}
\end{figure}

\lstinputlisting{optikz_doc_code/doc_calc_angle_example.tex}

A comprehensive list of all optical elements (lenses, splitters, mirrors, gratings) is given in Figure~\ref{fig:optical_elements}. Note that not all optional arguments are shown in this figure, as some elements like \texttt{$\backslash$splitter} have additional arguments like \texttt{shift} or \texttt{wedge} which enables further customization of the element. 

\begin{figure}[htp]
  \centering
  \inputtikz{doc_optical_elements}
  \caption{Different optical elements with a demonstration of their various optional arguments. The black arrow indicates the position of the anchor point. For reflective optics, the anchor point is on the surface, whereas for concave and convex lenses the anchor point is the center of the lens.}
  \label{fig:optical_elements}
  \vspace{-3cm}
\end{figure}


\newpage
\subsection{Optical devices}

The optical devices follow the same command structure as the optical elements
\begin{lstlisting}
  % standard command
  \command[<optional paramer>=value] at (x,y); 
  
  % specifying the coordinates via a TikZ-coordinate
  \coordinate (P1) at (x,y);
  \command[<optional paramer>=value] at (P1); 
\end{lstlisting}
The difference is that they add some other optional arguments like \verb!name! which is used to place a node with a text into the optical device. Furthermore, some elements have a redefined color like \verb!optikzred! or \verb!optikzyellow!. The color can still be accessed and changed using the \verb!color! argument.

The \verb!\pockelscell! is the only device which utilizes the \verb!shift! parameter. Usually, the housing of Pockels cell's is rather asymmetric, which can be realized easily as shown in figure~\ref{fig:Pockels_cell}.

\begin{figure}[htp]
    \centering
    \inputtikz{doc_Pockels_cell_shift}
    \caption{Usage of the \texttt{shift} parameter in the \texttt{$\backslash$pockelscell} command.}
    \label{fig:Pockels_cell}
\end{figure}
 
\lstinputlisting{optikz_doc_code/doc_Pockels_cell_shift.tex}
 
\begin{figure}[htp]
  \centering
  \inputtikz{doc_optical_devices}
  \caption{Different devices of an optical setup.}
  % \label{}
\end{figure}

\newpage
\subsection{Optional arguments}\label{sec:Optional_arguments}
In the following we want to discuss all optional arguments that can be set for the optical elements and devices. The discussion is done for the optical elements, but most of them apply similarly to the 

\subsubsection{Angle}
The \verb!angle! (standard value 0) argument is used for every single device and rotates the element around the anchor point in anti-clockwise direction.

\begin{figure}[htp]
    \centering
    \inputtikz{doc_angle}
    \caption{Demonstration of the angle argument.}
\end{figure}

\subsubsection{Width}
The \verb!width! (standard value 1) argument is used for every single device. It determines the width of the element perpendicular to the laser direction and is a multiplicative scaling factor. 

\begin{figure}[htp]
    \centering
    \inputtikz{doc_width}
    \caption{Demonstration of the width argument.}
\end{figure}

\newpage
\subsubsection{Thickness and strip}
The \verb!thickness! (standard value 1) argument controls the thickness of the optical element along the beam axis as a scalable factor. The \verb!strip! (standard value 1) argument scales the thickness of the black strip for the mirrors and the grating.

\begin{figure}[htp]
    \centering
    \inputtikz{doc_thickness}
    \caption{Demonstration of the \texttt{thickness} and \texttt{strip} argument. The Arguments don't apply for the beamsplitter crystal and the parabola.}
\end{figure}

\subsubsection{Color}
The \verb!color! (standard value \verb!optikzblue!) argument can be applied to every optical element. 

\begin{figure}[htp]
    \centering
    \inputtikz{doc_color}
    \caption{Demonstration of the \texttt{color} argument.}
\end{figure}

\newpage
\subsubsection{Shift}
The \verb!shift! (standard value 0) argument does only act on elements with a \emph{planar} surface. This is partly due to my lazyness to calculate the anchor point for a shift on a curved surface for every possible angle, but also not necessary. The reasons is that the lowest aberrations occur in the center of the optical element like a lens, thus it's rarely needed to place a lens off-centered into the optical setup.

\begin{figure}[htp]
    \centering
    \inputtikz{doc_shift}
    \caption{Demonstration of the \texttt{shift} command. Since the \texttt{pockelscell} is the only device affected by \texttt{shift}, it is included here.}
\end{figure}

\subsubsection{Name}
The \verb!name! (standard value \{ \}) argument does only act on certain devices large enough to support text inside them. The text is placed in the center of the device and rotates along its axis. Furthermore, the text is rotated such that it is never placed upside down. It is also possible to wrap the text in curly braces to change its fontsize or use $\backslash\backslash$ for a line break:
\begin{lstlisting}
\objective[name={\scriptsize objective}] at (x,y);
\spectrometer[name={spectro\\meter}] at (x,y);
\end{lstlisting}

\begin{figure}[htp]
    \centering
    \inputtikz{doc_name}
    \caption{Demonstration of the \texttt{name} argument. If the \texttt{angle} of the device is larger than \SI{90}{\degree}, the text is rotated by \SI{180}{\degree} for better reading.}
\end{figure}


\subsubsection{Radius}
The \verb!radius! (standard value 1.462) argument acts only on optical elements with a curved surface (e.g. curved mirrors and lenses). The numerical value was chosen for backwards compatability. It is given as the radius of a mirror with an opening angle of \SI{40}{\degree} and a width of \SI{1}{\cm}. Note that the radius should always be larger than half of the width, as otherwise the mirror cannot be constructed.

On the bottom of Figure~\ref{fig:doc_radius} we can see that the radius of curvature changes naturally (even if \verb!radius! is not passed as an argument) for larger widths of the mirror. The effective radius is then 
\begin{align}
    R_\text{eff} = R_\text{standard} \cdot \texttt{width} = \SI{1.462}{\cm}\cdot \texttt{width},
\end{align}
which conserves the $f$-number of the optical element. Using a value of \verb!radius! other than the standard value forces the radius to the specified value and overrides the scaling behaviour.
\begin{figure}[htp]
    \centering
    \inputtikz{doc_radius}
    \caption{Demonstration of the \texttt{radius} argument.}
    \label{fig:doc_radius}
\end{figure}

\subsubsection{Wedge}
The \verb!wedge! (standard value 0) argument does only act on the \verb!\splitter! command. It enlarges/reduces the thickness at the top/bottom by a scalable factor of the thickness. The value of \verb!wedge! should lie between $-1\le \texttt{wedge} \le 1$. We can create wedges in the following way:

\begin{figure}[htp]
    \centering
    \inputtikz{doc_wedge}
    \caption{Demonstration of the \texttt{wedge} argument. In order to obtain mirrored wedges, the \texttt{wedge} argument receives its negative value.}
\end{figure}

\subsubsection{Grating: Grooves}
The grating possesses two additional arguments to control the number and thickness of the grooves. The \verb!grooves! (standard value 7) argument should be an integer and indicates the number of grooves in a grating. The \verb!groovethickness! argument controls the thickness of the grooves.  

\begin{figure}[htp]
    \centering
    \inputtikz{doc_grating_groove}
    \caption{Demonstration of the \texttt{wedge} argument. In order to obtain mirrored wedges, the \texttt{wedge} argument receives its negative value.}
\end{figure}

\newpage
\subsection{Special optical elements}
There are some elements that are also defined as specific devices. However, all of them are special cases of the previously mentioned general commands. The following figure lists all special devices with their respective definitions. You can still access all parameters, just the standard value of different parameters was changed.

\begin{figure}[htp]
    \centering
    \inputtikz{doc_optical_elements_special}
    \caption{List of the different special optical elements.}
    % \label{fig:my_label}
\end{figure}

\newpage
\section{Examples}

\subsection{Butterfly amplifier}
The butterfly setup is the most simple variant of a multi-pass amplifier realized by several plane mirrors redirecting the beam. An example is shown in figure \ref{fig:butterfly}. 

\begin{figure}[htp]
    \centering
    \inputtikz{example_butterfly}
    \caption{Butterfly amplifier}
    \label{fig:butterfly}
\end{figure}

\lstinputlisting{optikz_doc_code/example_butterfly.tex}

\subsection{Regenerative amplifier}
A typical regenerative amplifier is realized by a ring cavity, where the input- and output- coupling is done via TFP's and a Pockels cell. An example is shown in figure \ref{fig:regenerative_amplifier}. 

\begin{figure}[htp]
    \centering
    \inputtikz{example_regenerative_amplifier}
    \caption{Schematic layout of a typical regenerative amplifier.}
    \label{fig:regenerative_amplifier}
\end{figure}

\lstinputlisting{optikz_doc_code/example_regenerative_amplifier.tex}

\newpage
\subsection{CPA system}
A full chirped pulse amplification (CPA) system is shown here, which is also displayed on the first page of this documentation.

\begin{figure}[htp]
    \centering
    \inputtikz{example_CPA_system}
    \caption{Schematic layout of a CPA amplifier.}
    \label{fig:CPA_amplifier}
\end{figure}

\lstinputlisting{optikz_doc_code/example_CPA_system.tex}

\tikzexternaldisable



\end{document}