Debian Codegraph @

texmf-dist/doc/latex/optikz/optikz_doc.tex

raw
1 %% optikz version 1.1.0
2 %% Copyright (C) 2025 Martin Beyer
3 %
4 % This work may be distributed and/or modified under the
5 % conditions of the LaTeX Project Public License, either version 1.3
6 % of this license or any later version.
7 % The latest version of this license is in
8 % http://www.latex-project.org/lppl.txt
9 % and version 1.3 or later is part of all distributions of LaTeX
10 % version 2005/12/01 or later.
11 %
12 % This work has the LPPL maintenance status `maintained'.
13 %
14 % The Current Maintainer of this work is Martin Beyer.
15 %
16 % This work consists of the files optikz.sty optikz_doc.tex and
17 % the optikz_doc_code folder which contains all examples used in the documentation
18
19 \documentclass[fontsize=12pt,rgb]{scrartcl}
20 \usepackage{optikz}
21 \usepackage{graphicx}
22 \usepackage{siunitx}
23 \usepackage[font=small]{caption}
24 \usepackage{fourier}
25 \usepackage{hyperref}
26 \usepackage{multicol}
27 \usepackage[a4paper, left=2.5cm, right=2.5cm, top=2.5cm, bottom=3cm]{geometry}
28 \usepackage{listings}
29 \usepackage{amsmath}
30
31 % Define custom colors
32 \definecolor{codebg}{rgb}{0.97,0.97,0.97}
33 \definecolor{keywordcolor}{rgb}{0.1,0.1,0.8}
34 \definecolor{commentcolor}{rgb}{0.4,0.4,0.4}
35 \definecolor{stringcolor}{rgb}{0.0,0.5,0.0}
36 \definecolor{identifiercolor}{rgb}{0.4, 0.0, 0.4}
37
38 % Configure listings for LaTeX code
39 \lstdefinestyle{latexstyle}{
40 backgroundcolor=\color{codebg},
41 basicstyle=\ttfamily\small,
42 keywordstyle=\color{keywordcolor}\bfseries,
43 stringstyle=\color{stringcolor},
44 commentstyle=\color{commentcolor}\itshape,
45 identifierstyle=\color{identifiercolor},
46 numbers=left,
47 numberstyle=\tiny\color{gray},
48 numbersep=8pt,
49 showstringspaces=false,
50 breaklines=true,
51 frame=single,
52 tabsize=2,
53 escapeinside={(*@}{@*)},
54 language=[LaTeX]TeX
55 }
56
57 \lstset{style=latexstyle}
58 \definecolor{Gruen}{cmyk}{1,0.1,0.7,0.5}
59 \setlength{\parindent}{0pt}
60
61
62 \usetikzlibrary{external}
63 % \tikzexternalize[prefix=optikz_doc_figures/] % activate!
64
65 \newcommand{\inputtikz}[1]{%
66 \tikzsetnextfilename{#1}%
67 \input{optikz_doc_code/#1.tex}%
68 }
69
70
71 \begin{document}
72
73 \newcommand{\HRule}{\rule{\linewidth}{0.5mm}}
74 \begin{titlepage}
75 \center
76 \HRule \\[0.4cm]
77 { \Huge The \texttt{Optikz} Package}\\[0.15cm]
78 \HRule \\[0.5cm]
79 \textsc{\Large Martin Beyer}\\[0.35cm]
80 \textsc{February 16th, 2026, Version 1.1.0}\\[0.35cm]
81 \vfill
82 \inputtikz{example_CPA_system}
83 \vfill
84 \begin{multicols}{2}
85 \tableofcontents
86 \end{multicols}
87 \end{titlepage}
88
89
90 \section{Introduction}
91 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.
92
93 The code relies on the \texttt{TikZ} package which is automatically loaded when calling this package.
94 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.
95
96
97 \section{Tutorial}
98 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.
99
100 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:
101
102 \begin{lstlisting}
103 \documentclass{article}
104 \usepackage{optikz}
105 \begin{document}
106 \begin{tikzpicture}
107 ...
108 \end{tikzpicture}
109 \end{document}
110 \end{lstlisting}
111
112 First he adds a mirror to his setup. He notices that the \verb!\mirror! command has several optional arguments. They are as follows:
113 \begin{itemize}
114 \item \texttt{angle}: Defines the angle to the $x$-axis.
115 \item \texttt{width}: Defines the width or diameter (standard value: 1) of the mirror.
116 \item \texttt{thickness}: Defines the thickness (standard value: 1) of the mirror.
117 \item \texttt{color}: Changes the color of the mirror.
118 \item \texttt{shift}: shifts the anchor point along the surface of the mirror (standard value: 0).
119 \end{itemize}
120 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.
121 \begin{figure}[htp]
122 \centering
123 \inputtikz{tutorial_delay_stage}
124 \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.}
125 \end{figure}
126
127 \lstinputlisting{optikz_doc_code/tutorial_delay_stage.tex}
128
129 \newpage
130 \section{Documentation}
131
132 \subsection{Colors}
133 Optikz defines several colors, which are used for the various optical components, they are defined as follows:
134 \begin{lstlisting}
135 \definecolor{optikzblue}{rgb}{0.56,0.663,0.723}
136 \definecolor{optikzred}{rgb}{0.7,0.2,0.2}
137 \definecolor{optikzyellow}{rgb}{1,0.86,0}
138 \end{lstlisting}
139
140 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
141 \begin{lstlisting}
142 \redefinecolor{optikzblue}{0.1,0.1,0.1}
143 \end{lstlisting}
144 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:
145 \begin{lstlisting}
146 \resetcolor{optikzblue}
147 \end{lstlisting}
148
149 \subsection{Rays and beams}
150 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.
151 \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:
152
153 \begin{figure}[htp]
154 \centering
155 \inputtikz{doc_ray_direction}
156 \caption{Draw a simple ray with TikZ.}
157 \end{figure}
158 \lstinputlisting{optikz_doc_code/doc_ray_direction.tex}
159
160 The custom node \verb!\laserdir! has some options we can utilize:
161 \begin{lstlisting}
162 node[laserdir, pos=0.5, xscale=1, color=black]{\laserdir}
163 \end{lstlisting}
164 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.
165
166 \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:
167 \begin{lstlisting}
168 \drawrainbow[width start=0.8,
169 width end=0.8,
170 opacity=0.7]
171 {pos M1}
172 {pos M2}
173 {angle M1}
174 {angle M2}
175
176 \drawbeam[width start=0.8,
177 width end=0.8,
178 fill color=optikzred,
179 draw color=black,
180 opacity=0.7]
181 {pos M1}
182 {pos M2}
183 {angle M1}
184 {angle M2}
185 \end{lstlisting}
186 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}.
187 \begin{figure}[htp]
188 \centering
189 \inputtikz{doc_beam}
190 \caption{Drawing of a rainbow beam (left) and normal beam (right).}
191 \label{fig:doc_beam}
192 \end{figure}
193 \lstinputlisting{optikz_doc_code/doc_beam.tex}
194
195 \clearpage
196 \subsection{Optical elements}
197 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}.
198 \paragraph{Definition} Every optical elements is defined by this command structure:
199
200 \begin{lstlisting}
201 % standard command
202 \command[<optional paramer>=value] at (x,y);
203
204 % specifying the coordinates via a TikZ-coordinate
205 \coordinate (P1) at (x,y);
206 \command[<optional paramer>=value] at (P1);
207 \end{lstlisting}
208
209 \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.
210
211 \begin{lstlisting}
212 % Calculate the half angle of the triangle ABC
213 \optikzanglethreepoints{A}{B}{C}{\varname}
214
215 % Calculate the angle of the vector AB with the x-axis
216 \optikzangletwopoints{A}{B}{\varname}
217 \end{lstlisting}
218
219
220 \begin{figure}[htp]
221 \centering
222 \inputtikz{doc_calc_angle_example}
223 \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}.}
224 \label{fig:doc_calc_angle_example}
225 \end{figure}
226
227 \lstinputlisting{optikz_doc_code/doc_calc_angle_example.tex}
228
229 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.
230
231 \begin{figure}[htp]
232 \centering
233 \inputtikz{doc_optical_elements}
234 \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.}
235 \label{fig:optical_elements}
236 \vspace{-3cm}
237 \end{figure}
238
239
240 \newpage
241 \subsection{Optical devices}
242
243 The optical devices follow the same command structure as the optical elements
244 \begin{lstlisting}
245 % standard command
246 \command[<optional paramer>=value] at (x,y);
247
248 % specifying the coordinates via a TikZ-coordinate
249 \coordinate (P1) at (x,y);
250 \command[<optional paramer>=value] at (P1);
251 \end{lstlisting}
252 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.
253
254 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}.
255
256 \begin{figure}[htp]
257 \centering
258 \inputtikz{doc_Pockels_cell_shift}
259 \caption{Usage of the \texttt{shift} parameter in the \texttt{$\backslash$pockelscell} command.}
260 \label{fig:Pockels_cell}
261 \end{figure}
262
263 \lstinputlisting{optikz_doc_code/doc_Pockels_cell_shift.tex}
264
265 \begin{figure}[htp]
266 \centering
267 \inputtikz{doc_optical_devices}
268 \caption{Different devices of an optical setup.}
269 % \label{}
270 \end{figure}
271
272 \newpage
273 \subsection{Optional arguments}\label{sec:Optional_arguments}
274 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
275
276 \subsubsection{Angle}
277 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.
278
279 \begin{figure}[htp]
280 \centering
281 \inputtikz{doc_angle}
282 \caption{Demonstration of the angle argument.}
283 \end{figure}
284
285 \subsubsection{Width}
286 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.
287
288 \begin{figure}[htp]
289 \centering
290 \inputtikz{doc_width}
291 \caption{Demonstration of the width argument.}
292 \end{figure}
293
294 \newpage
295 \subsubsection{Thickness and strip}
296 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.
297
298 \begin{figure}[htp]
299 \centering
300 \inputtikz{doc_thickness}
301 \caption{Demonstration of the \texttt{thickness} and \texttt{strip} argument. The Arguments don't apply for the beamsplitter crystal and the parabola.}
302 \end{figure}
303
304 \subsubsection{Color}
305 The \verb!color! (standard value \verb!optikzblue!) argument can be applied to every optical element.
306
307 \begin{figure}[htp]
308 \centering
309 \inputtikz{doc_color}
310 \caption{Demonstration of the \texttt{color} argument.}
311 \end{figure}
312
313 \newpage
314 \subsubsection{Shift}
315 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.
316
317 \begin{figure}[htp]
318 \centering
319 \inputtikz{doc_shift}
320 \caption{Demonstration of the \texttt{shift} command. Since the \texttt{pockelscell} is the only device affected by \texttt{shift}, it is included here.}
321 \end{figure}
322
323 \subsubsection{Name}
324 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:
325 \begin{lstlisting}
326 \objective[name={\scriptsize objective}] at (x,y);
327 \spectrometer[name={spectro\\meter}] at (x,y);
328 \end{lstlisting}
329
330 \begin{figure}[htp]
331 \centering
332 \inputtikz{doc_name}
333 \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.}
334 \end{figure}
335
336
337 \subsubsection{Radius}
338 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.
339
340 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
341 \begin{align}
342 R_\text{eff} = R_\text{standard} \cdot \texttt{width} = \SI{1.462}{\cm}\cdot \texttt{width},
343 \end{align}
344 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.
345 \begin{figure}[htp]
346 \centering
347 \inputtikz{doc_radius}
348 \caption{Demonstration of the \texttt{radius} argument.}
349 \label{fig:doc_radius}
350 \end{figure}
351
352 \subsubsection{Wedge}
353 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:
354
355 \begin{figure}[htp]
356 \centering
357 \inputtikz{doc_wedge}
358 \caption{Demonstration of the \texttt{wedge} argument. In order to obtain mirrored wedges, the \texttt{wedge} argument receives its negative value.}
359 \end{figure}
360
361 \subsubsection{Grating: Grooves}
362 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.
363
364 \begin{figure}[htp]
365 \centering
366 \inputtikz{doc_grating_groove}
367 \caption{Demonstration of the \texttt{wedge} argument. In order to obtain mirrored wedges, the \texttt{wedge} argument receives its negative value.}
368 \end{figure}
369
370 \newpage
371 \subsection{Special optical elements}
372 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.
373
374 \begin{figure}[htp]
375 \centering
376 \inputtikz{doc_optical_elements_special}
377 \caption{List of the different special optical elements.}
378 % \label{fig:my_label}
379 \end{figure}
380
381 \newpage
382 \section{Examples}
383
384 \subsection{Butterfly amplifier}
385 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}.
386
387 \begin{figure}[htp]
388 \centering
389 \inputtikz{example_butterfly}
390 \caption{Butterfly amplifier}
391 \label{fig:butterfly}
392 \end{figure}
393
394 \lstinputlisting{optikz_doc_code/example_butterfly.tex}
395
396 \subsection{Regenerative amplifier}
397 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}.
398
399 \begin{figure}[htp]
400 \centering
401 \inputtikz{example_regenerative_amplifier}
402 \caption{Schematic layout of a typical regenerative amplifier.}
403 \label{fig:regenerative_amplifier}
404 \end{figure}
405
406 \lstinputlisting{optikz_doc_code/example_regenerative_amplifier.tex}
407
408 \newpage
409 \subsection{CPA system}
410 A full chirped pulse amplification (CPA) system is shown here, which is also displayed on the first page of this documentation.
411
412 \begin{figure}[htp]
413 \centering
414 \inputtikz{example_CPA_system}
415 \caption{Schematic layout of a CPA amplifier.}
416 \label{fig:CPA_amplifier}
417 \end{figure}
418
419 \lstinputlisting{optikz_doc_code/example_CPA_system.tex}
420
421 \tikzexternaldisable
422
423
424
425 \end{document}