docs/print.html

<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
    <head>
        <!-- Book generated using mdBook -->
        <meta charset="UTF-8">
        <title>polsim Documentation</title>
        <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
        <meta name="description" content="">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta name="theme-color" content="#ffffff" />

        <link rel="shortcut icon" href="favicon.png">
        <link rel="stylesheet" href="css/variables.css">
        <link rel="stylesheet" href="css/general.css">
        <link rel="stylesheet" href="css/chrome.css">
        <link rel="stylesheet" href="css/print.css" media="print">

        <!-- Fonts -->
        <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
        <link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
        <link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">

        <!-- Highlight.js Stylesheets -->
        <link rel="stylesheet" href="highlight.css">
        <link rel="stylesheet" href="tomorrow-night.css">
        <link rel="stylesheet" href="ayu-highlight.css">

        <!-- Custom theme stylesheets -->
        

        
        <!-- MathJax -->
        <script async type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
        
    </head>
    <body class="light">
        <!-- Provide site root to javascript -->
        <script type="text/javascript">
            var path_to_root = "";
            var default_theme = "light";
        </script>

        <!-- Work around some values being stored in localStorage wrapped in quotes -->
        <script type="text/javascript">
            try {
                var theme = localStorage.getItem('mdbook-theme');
                var sidebar = localStorage.getItem('mdbook-sidebar');

                if (theme.startsWith('"') && theme.endsWith('"')) {
                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
                }

                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
                }
            } catch (e) { }
        </script>

        <!-- Set the theme before any content is loaded, prevents flash -->
        <script type="text/javascript">
            var theme;
            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { } 
            if (theme === null || theme === undefined) { theme = default_theme; }
            document.body.className = theme;
            document.querySelector('html').className = theme + ' js';
        </script>

        <!-- Hide / unhide sidebar before it is displayed -->
        <script type="text/javascript">
            var html = document.querySelector('html');
            var sidebar = 'hidden';
            if (document.body.clientWidth >= 1080) {
                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                sidebar = sidebar || 'visible';
            }
            html.classList.remove('sidebar-visible');
            html.classList.add("sidebar-" + sidebar);
        </script>

        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
            <ol class="chapter"><li><a href="polsim.html"><strong aria-hidden="true">1.</strong> polsim</a></li><li><a href="installation.html"><strong aria-hidden="true">2.</strong> Installation</a></li><li><a href="usage.html"><strong aria-hidden="true">3.</strong> Usage</a></li><li><a href="simulations.html"><strong aria-hidden="true">4.</strong> Simulations</a></li><li><ol class="section"><li><a href="format.html"><strong aria-hidden="true">4.1.</strong> File Format</a></li><li><a href="beams.html"><strong aria-hidden="true">4.2.</strong> Beams</a></li><li><ol class="section"><li><a href="beams/linear.html"><strong aria-hidden="true">4.2.1.</strong> Linearly Polarized</a></li><li><a href="beams/circular.html"><strong aria-hidden="true">4.2.2.</strong> Circularly Polarized</a></li><li><a href="beams/elliptical.html"><strong aria-hidden="true">4.2.3.</strong> Elliptically Polarized</a></li></ol></li><li><a href="elements.html"><strong aria-hidden="true">4.3.</strong> Elements</a></li><li><ol class="section"><li><a href="elements/polarizer.html"><strong aria-hidden="true">4.3.1.</strong> Polarizer</a></li><li><a href="elements/rotator.html"><strong aria-hidden="true">4.3.2.</strong> Rotator</a></li><li><a href="elements/retarder.html"><strong aria-hidden="true">4.3.3.</strong> Retarder</a></li><li><a href="elements/qwp.html"><strong aria-hidden="true">4.3.4.</strong> Quarter-Wave Plate</a></li><li><a href="elements/hwp.html"><strong aria-hidden="true">4.3.5.</strong> Half-Wave Plate</a></li></ol></li></ol></li><li><a href="examples.html"><strong aria-hidden="true">5.</strong> Examples</a></li><li><ol class="section"><li><a href="examples/one_polarizer.html"><strong aria-hidden="true">5.1.</strong> One Polarizer</a></li><li><a href="examples/crossed_polarizers.html"><strong aria-hidden="true">5.2.</strong> Crossed Polarizers</a></li><li><a href="examples/circular_polarizer.html"><strong aria-hidden="true">5.3.</strong> Circular Polarizer</a></li></ol></li><li><a href="reference.html"><strong aria-hidden="true">6.</strong> Quick Reference</a></li><li><a href="conventions.html"><strong aria-hidden="true">7.</strong> Conventions</a></li></ol>
        </nav>

        <div id="page-wrapper" class="page-wrapper">

            <div class="page">
                
                <div id="menu-bar" class="menu-bar">
                    <div id="menu-bar-sticky-container">
                        <div class="left-buttons">
                            <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                                <i class="fa fa-bars"></i>
                            </button>
                            <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
                                <i class="fa fa-paint-brush"></i>
                            </button>
                            <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
                                <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
                                <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                                <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
                                <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                                <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                            </ul>
                            
                            <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
                                <i class="fa fa-search"></i>
                            </button>
                            
                        </div>

                        <h1 class="menu-title">polsim Documentation</h1> 

                        <div class="right-buttons">
                            <a href="print.html" title="Print this book" aria-label="Print this book">
                                <i id="print-button" class="fa fa-print"></i>
                            </a>
                            
                        </div>
                    </div>
                </div>

                
                <div id="search-wrapper" class="hidden">
                    <form id="searchbar-outer" class="searchbar-outer">
                        <input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
                    </form>
                    <div id="searchresults-outer" class="searchresults-outer hidden">
                        <div id="searchresults-header" class="searchresults-header"></div>
                        <ul id="searchresults">
                        </ul>
                    </div>
                </div>
                

                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
                <script type="text/javascript">
                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
                    });
                </script>

                <div id="content" class="content">
                    <main>
                        <a class="header" href="#polsim" id="polsim"><h1>polsim</h1></a>
<p><strong>polsim</strong> is a command line tool for quickly doing polarization simulations with <a href="https://en.wikipedia.org/wiki/Jones_calculus">Jones calculus</a>. Jones calculus allows you to compute the effect of a sequence of optical elements (polarizers, wave plates, etc) on if the initial state (intensity and polarization) is known. A beam is represented as a vector with two elements (x- and y-components), and an optical element is represented as a 2x2 matrix that operates on the beam/vector. <code>polsim</code> makes life easy by letting you skip the tedious work of multiplying the matrices together by hand.</p>
<a class="header" href="#elevator-pitch" id="elevator-pitch"><h2>Elevator Pitch</h2></a>
<p>Would you rather look up this matrix,</p>
<p>\[
\begin{bmatrix}
\cos^{2}\left(\theta\right) + e^{i\varphi} \sin^{2}\left(\theta\right) &amp; \sin\left(\theta\right)\cos\left(\theta\right) - e^{i\varphi} \sin\left(\theta\right)\cos\left(\theta\right) \\
\sin\left(\theta\right)\cos\left(\theta\right) - e^{i\varphi} \sin\left(\theta\right)\cos\left(\theta\right) &amp; \sin^{2}\left(\theta\right) + e^{i\varphi} \cos^{2}\left(\theta\right) \\
\end{bmatrix}
\]</p>
<p>then plug in \(\theta = \pi/4\) and \(\varphi = \pi/2\), or would you rather write <em>this</em>?</p>
<pre><code class="language-toml">[[elements]]
element_type = &quot;retarder&quot;
phase = 1.57  # pi/2
phase_units = &quot;radians&quot;
angle = 45.0
angle_units = &quot;degrees&quot;
</code></pre>
<a class="header" href="#simulation-library" id="simulation-library"><h2>Simulation Library</h2></a>
<p><code>polsim</code> is really just a pretty face for the simulation library I wrote, which can be found <a href="https://github.com/zmitchell/polarization">here</a>. If you think you've found a bug in the simulation results, you should create an issue on <a href="https://github.com/zmitchell/polarization/issues">Github</a>. The simulation library is tested very thoroughly for correctness, but it's entirely possible that something slipped through the cracks!</p>
<p>If you want to do more complicated simulations (e.g. sweep the angle of a polarizer from 0 degrees to 10 degrees in 0.1 degree increments) you'll have to use the simulation library directly. I hope that you can do that directly from <code>polsim</code> one day, but I don't see myself having the time to work on it any time soon.</p>
<a class="header" href="#legalese" id="legalese"><h2>Legalese</h2></a>
<p>Licensed under either of</p>
<ul>
<li>Apache License, Version 2.0, (<a href="https://github.com/zmitchell/polsim/blob/master/LICENSE-APACHE">LICENSE-APACHE</a> or http://www.apache.org/licenses/LICENSE-2.0)</li>
<li>MIT license (<a href="https://github.com/zmitchell/polsim/blob/master/LICENSE-MIT">LICENSE-MIT</a> or http://opensource.org/licenses/MIT)</li>
</ul>
<p>at your option.</p>
<a class="header" href="#contribution" id="contribution"><h3>Contribution</h3></a>
<p>Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the Apache-2.0
license, shall be dual licensed as above, without any additional terms or
conditions.</p>
<a class="header" href="#installation" id="installation"><h1>Installation</h1></a>
<p>The first step is to head to the <a href="https://github.com/zmitchell/polsim/releases">GitHub repository</a> and download the latest release for your operating system. <code>polsim</code> is only available for 64-bit operating systems because it's 2019. Here is what the filename will look like for each supported operating system:</p>
<ul>
<li>Windows: <code>polsim-&lt;version&gt;-x86_64-pc-windows-msvc.zip</code></li>
<li>macOS: <code>polsim-&lt;version&gt;-x86_64-apple-darwin.tar.gz</code></li>
<li>Linux: <code>polsim-&lt;version&gt;-x86_64-unknown-linux-gnu.tar.gz</code></li>
</ul>
<p>The next step is to extract the archive you just downloaded and put the executable file somewhere. For Windows, the executable will be called <code>polsim.exe</code>, and for macOS and Linux the executable will be called <code>polsim</code>. <code>polsim</code> doesn't need to be put anywhere special, so you can put it wherever you want.</p>
<p><code>polsim</code> is a command line program, so you'll be using a shell (<code>cmd.exe</code> on Windows, Terminal on macOS, etc) to interact with it. Your shell needs to know where to find <code>polsim</code> in order to use it, so you have two options:</p>
<ul>
<li>Put <code>polsim</code> in a directory, then avigate to this directory each time you want to use <code>polsim</code>.</li>
<li>Put <code>polsim</code> in a directory, then add that directory to your shell's <code>PATH</code> so you can use <code>polsim</code> from any directory.</li>
</ul>
<p>The second option is more convenient (in my opinion), so it's the recommended option. If you need help adding a directory to your shell's <code>PATH</code>, here are some guides for each supported operating system:</p>
<ul>
<li><a href="https://helpdeskgeek.com/windows-10/add-windows-path-environment-variable/">Windows</a></li>
<li><a href="http://osxdaily.com/2014/08/14/add-new-path-to-path-command-line/">macOS</a></li>
<li><a href="https://www.techrepublic.com/article/how-to-add-directories-to-your-path-in-linux/">Linux</a></li>
</ul>
<a class="header" href="#usage" id="usage"><h1>Usage</h1></a>
<blockquote>
<p>Note: This section assumes that you've already installed <code>polsim</code>. If you haven't installed <code>polsim</code>, you can find instructions in the <a href="installation.html">Installation</a> section.</p>
</blockquote>
<blockquote>
<p>Note: Some of what follows will be things that you type into a shell/terminal. This will be <code>cmd.exe</code> on Windows, <code>Terminal.app</code> on macOS, or your terminal of choice on Linux. The parts that you type into a terminal will appear like this:</p>
<pre><code>$ some commands to execute
</code></pre>
<p>In these parts the <code>$</code> just indicates the prompt in your shell, so you don't need to type the <code>$</code> character. Some instructions will contain text in <code>&lt;angle brackets&gt;</code>. The text in angle brackets will be a placeholder for something that you need to supply e.g. a filename or a path to a directory.</p>
</blockquote>
<a class="header" href="#your-first-simulation" id="your-first-simulation"><h2>Your first simulation</h2></a>
<p>Let's get things started with an example. Put the following text into a file called <code>simulation.toml</code> and save it somewhere.</p>
<pre><code class="language-toml"># simulation.toml
[beam]
polarization = &quot;linear&quot;
angle = 90
angle_units = &quot;degrees&quot;

[[elements]]
element_type = &quot;polarizer&quot;
angle = 45
angle_units = &quot;degrees&quot;
</code></pre>
<p>Next, open up your shell and navigate to the directory in which you saved <code>simulation.toml</code>.</p>
<pre><code>
$ cd &lt;path to the directory&gt;
</code></pre>
<p>Now we're going to tell <code>polsim</code> to run a simulation with this file.</p>
<pre><code>$ polsim simulation.toml
</code></pre>
<p>When you run it you should see the following output:</p>
<pre><code>$ polsim simulation.toml
intensity: 5.00000e-1
x_mag: 5.00000e-1
x_phase: 0.00000e0
y_mag: 5.00000e-1
y_phase: 0.00000e0
</code></pre>
<p>You've just run your first simulation! Let's dig in and see what this output is telling us.</p>
<a class="header" href="#interpreting-the-results" id="interpreting-the-results"><h2>Interpreting the results</h2></a>
<p>What you see at the end of a simulation is a summary of the beam after it has passed through all of the elements that you defined in your optical system. The report includes the intensity of the beam as well as the magnitude and phase of both components of the complex polarization vector.</p>
<pre><code>intensity: 5.00000e-1
</code></pre>
<p>All beams in <code>polsim</code> start with an intensity of 1. We see here that the intensity is 0.5, which tells us that the beam has half the intensity that it started out with.</p>
<pre><code>x_mag: 5.00000e-1
x_phase: 0.00000e0
</code></pre>
<p>The components of an electric field are, in general, complex. It's typically easier to reason about the components of the electric field in terms of magnitude and phase rather than the real and imaginary parts. What you see here as <code>x_mag</code> and <code>x_phase</code> can be written mathematically as:</p>
<p>\(E_x = r e^{i\varphi} = x\_mag\,e^{i\,x\_phase}\)</p>
<p>The same idea applies to <code>y_mag</code> and <code>y_phase</code>, obviouslly.</p>
<p>Another thing to notice is that the x- and y-components are not normalized to 1, they are normalized such that <code>x_mag^2 + y_mag^2 = intensity</code>.</p>
<a class="header" href="#troubleshooting" id="troubleshooting"><h2>Troubleshooting</h2></a>
<p>We haven't discussed how to write your own simulations yet, so don't worry too much about understanding exactly what the simulation file says. For now, just try to follow along and get a sense for how <code>polsim</code> will try to help you out when you make mistakes. Don't worry though, we'll talk about the nitty gritty details of how to make your own simulations soon enough.</p>
<p>Let's see what happens when you make an error in your simulation file. We're going to delete the last line of <code>simulation.toml</code> and see what <code>polsim</code> has to say about that. Copy and paste the following text into a file called <code>has_error.toml</code>, then save it.</p>
<pre><code class="language-toml"># has_error.toml
[beam]
polarization = &quot;linear&quot;
angle = 90
angle_units = &quot;degrees&quot;

[[elements]]
element_type = &quot;polarizer&quot;
angle = 45
</code></pre>
<p>Now we're going to (try to) run a simulation with this file.</p>
<pre><code>$ polsim has_error.toml
error: invalid system definition
caused by: invalid element definition
caused by: invalid polarizer definition
caused by: invalid angle definition
caused by: missing parameter in definition: 'angle_units'
</code></pre>
<p>That's a lot of output, but if you read it from the top down it will help you pinpoint where the error came from. Let's break it down line by line.</p>
<pre><code>error: invalid system definition
</code></pre>
<p>This says that there was an error in the definition of our simulation. In other words, there's something wrong with what we typed into <code>has_error.toml</code>, but we don't quite know what just yet.</p>
<pre><code>caused by: invalid element definition
</code></pre>
<p>Now we know that there's something wrong with one of the elements that we defined. We still don't know which one is the source of the problem though.</p>
<pre><code>caused by: invalid polarizer definition
</code></pre>
<p>Aha, now we're getting somewhere. This line tells us that there's an issue with a polarizer. Our simulation only has one polarizer, so that's enough to tell us which element is the problem. If your simulation has more than one of the same type of element, you'll have to do a bit more sleuthing to figure out which one it is. What's wrong with the definition of our polarizer?</p>
<pre><code>caused by: invalid angle definition
</code></pre>
<p>Something seems to be wrong with the definition of the angle of the polarizer. Let's see what's up.</p>
<pre><code>caused by: missing parameter in definition: 'angle_units'
</code></pre>
<p>This is the source of the problem. Every angle that you define needs two pieces: <code>angle</code> and <code>angle_units</code>. Our problematic simulation file, <code>has_error.toml</code>, left out the <code>angle_units</code> for the definition of our polarizer.</p>
<p>Most error messages that you receive should be helpful in pinpointing your error. If you get an error message that sounds like gibberish, feel free to post an issue on the <a href="https://github.com/zmitchell/polsim/issues">GitHub repository</a>.</p>
<a class="header" href="#simulations" id="simulations"><h1>Simulations</h1></a>
<p>At this point hopefully you have a vague idea of how to run a simulation, but you probably have no idea how to define your own simulations.</p>
<p>The whole process starts by defining an optical system consisting of a beam and some elements that the beam will pass through. You define this system in a file with the <code>.toml</code> extension. This file format is called TOML. It's just a plain text file, so you can use any text editor you want, just make sure to save the file with the <code>.toml</code> extension. TOML has its own rules for how to write things, but I'll teach you everything you need to know.</p>
<p>Read on to learn how to define your own simulations!</p>
<a class="header" href="#file-format" id="file-format"><h1>File format</h1></a>
<p>An optical system is defined by both a beam and a sequence of optical elements that the beam will pass through. If you run a simulation without defining a beam or without defining your elements, you will get an error explaining what you're missing. Here's the general outline of what the simulation file looks like:</p>
<pre><code class="language-toml">[beam]
# beam definition goes here

[[elements]]
# the first element goes here

[[elements]]
# the second element goes here

...
</code></pre>
<p>The simulation file uses a format called TOML, which stands for Tom's Obvious, Minimal Language. I'll explain everything you need to know in this guide, but if you want to read more about TOML, you can do so at the <a href="https://github.com/toml-lang/toml">TOML GitHub repository</a>.</p>
<p>There are two main sections of the simulation file. The first section is the part marked by the <code>[beam]</code> heading. The second section is marked by one or more <code>[[elements]]</code> headings. The <code>[beam]</code> heading marks the definition of the beam that you want to start your simulation with. Each <code>[[elements]]</code> heading defines an element in the optical system. The specifics about what is needed to define a beam or an element will be discussed in later sections of this guide.</p>
<p>Just to give you a taste of what a definition looks like, here is the definition of a linearly polarized beam with a polarization vector at 45 degrees measured from the +x-axis:</p>
<pre><code class="language-toml">[beam]
polarization = &quot;linear&quot;
angle = 45
angle_units = &quot;degrees&quot;
</code></pre>
<p>The definitions of beams and elements are written out in key-value pairs in the form <code>key = value</code>.</p>
<p>The rule here is that numbers can be written in just about any way you want. For example, <code>2</code>, <code>2.0</code>, <code>-2</code>, and <code>2.0e-3</code> are all valid numbers. On the other hand, you can't write mathematical expressions. For example, let's say you want to set a beam at an angle of 45 degrees. It is completely valid to write <code>angle = 45</code>, but it is not valid to write <code>angle = 30 + 15</code> even though <code>30 + 15</code> is obviously equal to <code>45</code>. In short, just stick to a single number, and everything should work just fine. There are also values that are not numbers. These values must be enclosed in double quotes e.g. <code>&quot;linear&quot;</code>.</p>
<p>Read on to see how to define beams and elements.</p>
<a class="header" href="#beams" id="beams"><h1>Beams</h1></a>
<p>The section for defining a beam is marked by <code>[beam]</code>. Notice that there's only <strong>one</strong> set of braces around <code>[beam]</code> as opposed to <strong>two</strong> set of braces around <code>[[elements]]</code>. In TOML we say that <code>[beam]</code> is a table, and <code>[[elements]]</code> is an array (a list of values, in this case a list of elements).</p>
<p>The <code>[beam]</code> table can take a few different key-value pairs depending on how you want to define your beam. When you really get down to it, you're just defining the x- and y-components of the polarization, but that's overly tedious for most cases. To make life easier for you, I've provided you with some shortcuts for linearly and circularly polarized beams. You can, however, still define the beam in terms of the x- and y-components of the polarization if you really want to.</p>
<p>One important thing to mention before we move on is that no matter how you define your beam, it's initial intensity will always be 1.</p>
<p>The next few sections will describe how to define beams with different types of polarization.</p>
<a class="header" href="#linearly-polarized" id="linearly-polarized"><h1>Linearly Polarized</h1></a>
<p>Let's start out by defining a linearly polarized beam with horizontal polarization. Here is the whole definition:</p>
<pre><code class="language-toml">[beam]
polarization = &quot;linear&quot;
angle = 0
angle_units = &quot;degrees&quot;
</code></pre>
<p>That's not so bad, is it?</p>
<p>The first key is <code>polarization</code>. Every beam definition needs a <code>polarization</code> key because it tells the simulation what other keys to expect in the beam definition. For example, it doesn't make sense to specify the angle of a circularly polarized beam, so you aren't asked for <code>angle</code> or <code>angle_units</code> when <code>polarization = &quot;circular&quot;</code>. We're getting ahead of ourselves though, so let's get back to our linearly polarized beam.</p>
<p>The definition of a linearly polarized beam just needs an angle to describe the orientation of the polarization vector. An angle is defined with two keys: <code>angle</code> and <code>angle_units</code>. The <code>angle</code> key takes the actual value of the angle, and the <code>angle_units</code> key specifies the units in which <code>angle</code> is given. The <code>angle_units</code> key can take the following values:</p>
<ul>
<li><code>&quot;degrees&quot;</code></li>
<li><code>&quot;radians&quot;</code></li>
</ul>
<p>Every angle definition requires you to specify the units. This might seem tedious, but there are good reasons for this choice. Sometimes it's more convenient or more natural to express an angle in degrees or in radians, so you are free to mix and match which units you use for the various angles that you specify in your simulation file. However, since you have the freedom to mix and match the units, you also have the freedom to mix them up by mistake. Making you be explicit about the units prevents mistakes. This is science after all, it's supposed to be correct!</p>
<a class="header" href="#circularly-polarized" id="circularly-polarized"><h1>Circularly Polarized</h1></a>
<p>The definition of a circularly polarized beam is even simpler than that of a linearly polarized beam:</p>
<pre><code class="language-toml">[beam]
polarization = &quot;circular&quot;
handedness = &quot;right&quot;
</code></pre>
<p>A circularly polarized beam is defined by its handedness i.e. which direction the polarization vector rotates as the beam propagates (clockwise or counter-clockwise). The convention for the &quot;handedness&quot; of a circularly polarized beam is defined by the &quot;right-hand rule&quot;, that is, a beam is &quot;right&quot; handed if the polarization vector appears to rotate clockwise as the beam travels away from you.</p>
<p>The <code>handedness</code> key can take the following values:</p>
<ul>
<li><code>&quot;left&quot;</code></li>
<li><code>&quot;right&quot;</code></li>
</ul>
<p>If you know someone who has a hand that isn't a right or left hand, please let me know.</p>
<a class="header" href="#elliptically-polarized" id="elliptically-polarized"><h1>Elliptically Polarized</h1></a>
<p>If you want to define an arbitrary beam, you can do so with the <code>&quot;elliptical&quot;</code> polarization type. For this beam definition there are no shortcuts, you have to specify everything yourself.</p>
<pre><code class="language-toml">[beam]
polarization = &quot;elliptical&quot;
x_mag = 1.0
y_mag = 1.0
x_phase = 0.0
y_phase = 3.141
phase_units = &quot;radians&quot;
</code></pre>
<p>The <code>x_mag</code> and <code>y_mag</code> keys are the magnitudes of the x- and y-components of the polarization. The <code>x_phase</code>, <code>y_phase</code>, and <code>phase_units</code> keys specify the phases of the components. In <code>polsim</code> phases are just like angles. The phases are even specified with the same units as angles.</p>
<p>This is the one exception to the &quot;specify the units of every angle&quot; rule. Both <code>x_phase</code> and <code>y_phase</code> must have the same units. I don't know why you would define <code>x_phase</code> with one set of units and <code>y_phase</code> with another set of units, so I'm just not going to let you do that.</p>
<p>The last thing to mention is that the intensity of the beam will be 1 no matter what magnitudes you provide in <code>x_mag</code> and <code>y_mag</code>. This was mentioned earlier, but it's worth repeating to avoid any potential confusion. You can still provide magnitudes that are larger than 1 (I even did that in the example above), and it can even be convenient to do so, just don't be surprised if your intensity is never larger than 1!</p>
<p>If you supply magnitudes larger than 1, they will just be normalized so that the intensity is 1. Let's walk through what happens in the example given above. First, the intensity is calculated from the provided magnitudes:</p>
<pre><code>x_mag^2 + y_mag^2 = initial_intensity
1 + 1 = 2
initial_intensity = 2
</code></pre>
<p>Then each magnitude is divided by the square root of this initial intensity. This is more or less the same thing as dividing both sides of the above equation by <code>initial_intensity</code>.</p>
<pre><code>normed_x_mag = x_mag / sqrt(initial_intensity)
normed_y_mag = y_mag / sqrt(initial_intensity)
normed_x_mag = 1 / sqrt(2) = 0.707
normed_y_mag = 1 / sqrt(2) = 0.707
</code></pre>
<p>Now the intensity will be 1 when computed from the normalized components:</p>
<pre><code>normed_x_mag^2 + normed_y_mag^2 = intensity
(0.707^2) + (0.707^2) = intensity
0.5 + 0.5 = intensity
1 = intensity
</code></pre>
<a class="header" href="#elements" id="elements"><h1>Elements</h1></a>
<p>Recall that you specify the elements of the optical system with one or more sections that start with <code>[[elements]]</code>. In TOML we say that each <code>[[foo]]</code> defines an item in an array (list) called <code>foo</code>. In our case we're defining the items (optical elements) in an array called <code>elements</code>. The order in which you define the elements is the order in which the beam will travel through the elements. This makes a big difference in your simulation!</p>
<p>Much like the definition of a beam, the definition of an element is written out using key-value pairs. Different elements will require different key-value pairs in their definition, but they will all have an <code>element_type</code> key. The list of possible element types is as follows:</p>
<ul>
<li>polarizer: <code>&quot;polarizer&quot;</code></li>
<li>polarization rotator: <code>&quot;rotator&quot;</code></li>
<li>retarder: <code>&quot;retarder&quot;</code></li>
<li>quarter-wave plate: <code>&quot;qwp&quot;</code></li>
<li>half-wave plate: <code>&quot;hwp&quot;</code></li>
</ul>
<p>Several elements require an angle as part of their definition, but an angle can mean different things in the context of different optical elements. I'll point out the differences for each element, but it's importat to keep track of what each angle means. The way that you define an angle for an element is exactly the same way that you define an angle for a beam (e.g. with <code>angle</code> and <code>angle_units</code>). The same goes for <code>phase</code> and <code>phase_units</code>.</p>
<p>Let's look at how you define each element type.</p>
<a class="header" href="#polarizer" id="polarizer"><h1>Polarizer</h1></a>
<p>A polarizer is an optical element that only lets polarization of a certian orientation pass through. Think about it like this:</p>
<blockquote>
<p>You have a wall full of toasters and a bunch of bread. You want to make some toast, so you throw some bread at your toaster-wall. The only slices of bread that make it into a toaster are the slices of bread that are lined up with the slots on the top of a toaster.</p>
</blockquote>
<p>It's the same thing with light and a polarizer. Exactly the same.</p>
<p>The definition of a polarizer just needs an angle. The angle in this case is the orientation of the polarization that the polarizer will let through. Here's an example:</p>
<pre><code class="language-toml">[[elements]]
element_type = &quot;polarizer&quot;
angle = 45
angle_units = &quot;degrees&quot;
</code></pre>
<p>This definition corresponds to an ideal linear polarizer that makes a 45 degree angle with the +x-axis.</p>
<a class="header" href="#polarization-rotator" id="polarization-rotator"><h1>Polarization Rotator</h1></a>
<p>A polarization rotator is pretty much what it says on the tin: it rotates the polarization of a beam.</p>
<p>The definition of a polarization rotator needs an angle, but in this case the angle isn't the orientation of the element. The angle specified here is the angle by which the polarization will be rotated. The convention is that positive angles correspond to rotating the polarization counter-clockwise.</p>
<p>Here's an example of an element that rotates the polarization of a beam by 90 degrees:</p>
<pre><code class="language-toml">[[elements]]
element_type = &quot;rotator&quot;
angle = 90.0
angle_units = &quot;degrees&quot;
</code></pre>
<a class="header" href="#retarder" id="retarder"><h1>Retarder</h1></a>
<p>A retarder is an optical element that introduces a phase difference between two perpendicular components of a beam's polarization. We say that the phase of one of the components has been retarded relative to the other, hence the name &quot;retarder&quot;. The polarization component perpendicular to the &quot;fast&quot; axis of the retarder will lag behind the other component by some fixed phase specific to the particular retarder.</p>
<p>A retarder is more complicated than the other elements we've discussed here, so I'll direct you to the wonderful <a href="https://www.rp-photonics.com/waveplates.html">RP Photonics Encyclopedia</a> to learn more about how a retarder works under the hood.</p>
<p>The effect that the retarder has on the beam depends on two things:</p>
<ol>
<li>The orientation of the beam's polarization relative to the orientation of the retarder's &quot;fast&quot; axis.</li>
<li>The phase delay introduced by the retarder.</li>
</ol>
<p>In your retarder definition you'll have to specify both the orientation of the element and the phase delay introduced by the element. A phase is really just an angle, so the definition of a phase works exactly the same way as a definition of an angle. They even use the same units!</p>
<pre><code class="language-toml">[[elements]]
element_type = &quot;retarder&quot;
angle = 45
angle_units = &quot;degrees&quot;
phase = 1.5705
phase_units = &quot;radians&quot;
</code></pre>
<a class="header" href="#quarter-wave-plate" id="quarter-wave-plate"><h1>Quarter-Wave Plate</h1></a>
<p>If you fix the phase delay introduced by a retarder to <code>pi/2</code>, or one quarter of a wavelength, you get a quarter-wave plate. This kind of element is used to convert between linear and circular polarization.</p>
<p>The definition of a quarter-wave plate only needs an angle since the phase is a fixed value.</p>
<pre><code class="language-toml">[[elements]]
element_type = &quot;qwp&quot;
angle = 45
angle_units = &quot;degrees&quot;
</code></pre>
<a class="header" href="#half-wave-plate" id="half-wave-plate"><h1>Half-Wave Plate</h1></a>
<p>A half-wave plate (HWP) is just like a QWP with a different. This type of element is often used to rotate the polarization of a beam.</p>
<p>Just like a quarter-wave plate, you only need to specify an angle in your definition since the phase is a fixed value.</p>
<pre><code class="language-toml">[[elements]]
element_type = &quot;hwp&quot;
angle = 45.0
angle_units = &quot;degrees&quot;
</code></pre>
<a class="header" href="#examples" id="examples"><h1>Examples</h1></a>
<p>The next few sections contain complete simulation definitions that you can just copy and paste into a simulation file. You can use these to make sure you have everything installed properly, or just to tinker with.</p>
<p>Read on to see some examples!</p>
<a class="header" href="#one-polarizer" id="one-polarizer"><h1>One Polarizer</h1></a>
<p>Let's say I have a linearly polarized beam with vertical polarization. I want to pass that polarization through a polarizer oriented at 45 degrees. Here's what that looks like:</p>
<pre><code class="language-toml">[beam]
polarization = &quot;linear&quot;
angle = 90
angle_units = &quot;degrees&quot;

[[elements]]
element_type = &quot;polarizer&quot;
angle = 45
angle_units = &quot;degrees&quot;
</code></pre>
<p>Here's what the output looks like:</p>
<pre><code>$ polsim one_polarizer.toml
intensity: 5.00000e-1
x_mag: 5.00000e-1
x_phase: 0.00000e0
y_mag: 5.00000e-1
y_phase: 0.00000e0
</code></pre>
<p>You can see that the intensity is 0.5, which is half of the original intensity since all beams start with an intensity of 1. We can verify that this is correct using <a href="https://en.wikipedia.org/wiki/Polarizer#Malus&#x27;s_law_and_other_properties">Malus's Law</a>. Malus's Law says that a beam's intensity after it passes through a polarizer depends on the angle between them:</p>
<p>\( I = I_0 \cos^{2}\left(\theta\right)\)</p>
<p>Since the angle between the polarizer and the beam's polarization is 45 degrees, \( I = 0.5 I_0 \).</p>
<a class="header" href="#crossed-polarizers" id="crossed-polarizers"><h1>Crossed Polarizers</h1></a>
<p>If I orient two polarizers perpendicular to one another, no beam will be able to pass through. Here's what that looks like:</p>
<pre><code class="language-toml">[beam]
polarization = &quot;linear&quot;
angle = 45
angle_units = &quot;degrees&quot;

[[elements]]
element_type = &quot;polarizer&quot;
angle = 0
angle_units = &quot;degrees&quot;

[[elements]]
element_type = &quot;polarizer&quot;
angle = 90
angle_units = &quot;degrees&quot;
</code></pre>
<p>The orientation of the beam is completely arbitrary in this situation, so I just chose 45 degrees. Here's what the output looks like:</p>
<pre><code>$ polsim crossed_polarizers.toml
intensity: 1.87470e-33
x_mag: 2.65123e-33
x_phase: 0.00000e0
y_mag: 4.32978e-17
y_phase: 0.00000e0
</code></pre>
<p>Since computers can't represent numbers with infinite precision, you're likely to see something weird like this if your numbers are close to zero. We're all physicists here, so we know that anything as small as <code>1e-17</code> or <code>1e-33</code> is basically zero anyway when compared to 1 (the intensity of the original beam).</p>
<p>We can use Malus's Law again (see the previous example) to verify that this is correct. The beam will have polarization at 0 degrees after it passes through the first polarizer. The second polarizer is at 90 degrees, meaning that the angle between the beam and the second polarizer is also 90 degrees. The cosine of 90 degrees is zero, so no light (ideally) passes through the second polarizer.</p>
<a class="header" href="#circular-polarizer" id="circular-polarizer"><h1>Circular Polarizer</h1></a>
<p>If you have a linearly polarized beam you can convert it into a circularly polarized beam with a polarizer and a QWP. Here's what that looks like:</p>
<pre><code class="language-toml">[beam]
polarization = &quot;linear&quot;
angle = 90
angle_units = &quot;degrees&quot;

[[elements]]
element_type = &quot;polarizer&quot;
angle = 45
angle_units = &quot;degrees&quot;

[[elements]]
element_type = &quot;qwp&quot;
angle = 0
angle_units = &quot;degrees&quot;
</code></pre>
<p>The key here is that the QWP and the polarizer need to be at 45 degrees relative to on another. If this angle is off, you'll end up with elliptical polarization. Here's what the output looks like:</p>
<pre><code>$ polsim circular_polarizer.toml
intensity: 5.00000e-1
x_mag: 5.00000e-1
x_phase: 0.00000e0
y_mag: 5.00000e-1
y_phase: 1.57080e0
</code></pre>
<p>If you go back through the previous two examples, you'll see that the phases (<code>x_phase</code> and <code>y_phase</code>) are zero for both examples. This time, however, <code>y_phase</code> is not zero, it's <code>pi/2</code>! That tells us that there is a delay between the x- and y-components.</p>
<a class="header" href="#quick-reference" id="quick-reference"><h1>Quick Reference</h1></a>
<blockquote>
<p>Note: In the definitions that follow, text in <code>&lt;angle brackets&gt;</code> are placeholders for values that you must supply.</p>
</blockquote>
<a class="header" href="#file-format-1" id="file-format-1"><h3>File Format</h3></a>
<pre><code class="language-toml">[beam]
# beam definition goes here
polarization = &lt;polarization&gt;
&lt;polarization-specific keys&gt;

[[elements]]
&lt;element definition&gt;

[[elements]]
&lt;element definition&gt;

...
</code></pre>
<a class="header" href="#angles" id="angles"><h2>Angles</h2></a>
<ul>
<li><code>angle</code>
<ul>
<li>Takes an integer or floating point number.</li>
</ul>
</li>
<li><code>angle_units</code>
<ul>
<li><code>&quot;degrees&quot;</code></li>
<li><code>&quot;radians&quot;</code></li>
</ul>
</li>
</ul>
<p>Example:</p>
<pre><code class="language-toml">angle = 0
angle_units = &quot;degrees&quot;
</code></pre>
<a class="header" href="#phase" id="phase"><h2>Phase</h2></a>
<p>Phases are really just angles, so they follow exactly the same rules as angles.</p>
<ul>
<li><code>phase</code>
<ul>
<li>Takes an integer or floating point number.</li>
</ul>
</li>
<li><code>phase_units</code>
<ul>
<li><code>&quot;degrees&quot;</code></li>
<li><code>&quot;radians&quot;</code></li>
</ul>
</li>
</ul>
<p>Example:</p>
<pre><code class="language-toml">phase = 3.141
phase_units = &quot;radians&quot;
</code></pre>
<a class="header" href="#handedness" id="handedness"><h2>Handedness</h2></a>
<ul>
<li><code>handedness</code>
<ul>
<li><code>&quot;left&quot;</code></li>
<li><code>&quot;right&quot;</code></li>
</ul>
</li>
</ul>
<p>Example:</p>
<pre><code class="language-toml">[beam]
polarization = &quot;circular&quot;
handedness = &quot;left&quot;
</code></pre>
<a class="header" href="#polarization" id="polarization"><h2>Polarization</h2></a>
<ul>
<li><code>polarization</code>
<ul>
<li><code>&quot;linear&quot;</code></li>
<li><code>&quot;circular&quot;</code></li>
<li><code>&quot;elliptical&quot;</code></li>
</ul>
</li>
</ul>
<p>Example:</p>
<pre><code class="language-toml">[beam]
polarization = &quot;circular&quot;
handedness = &quot;left&quot;
</code></pre>
<a class="header" href="#beams-1" id="beams-1"><h2>Beams</h2></a>
<a class="header" href="#linearly-polarized-1" id="linearly-polarized-1"><h3>Linearly Polarized</h3></a>
<pre><code class="language-toml">[beam]
polarization = &quot;linear&quot;
angle = &lt;number&gt;
angle_units = &lt;angle units&gt;
</code></pre>
<p>Example:</p>
<pre><code class="language-toml">[beam]
polarization = &quot;linear&quot;
angle = 0
angle_units = &quot;degrees&quot;
</code></pre>
<a class="header" href="#circularly-polarized-1" id="circularly-polarized-1"><h3>Circularly Polarized</h3></a>
<pre><code class="language-toml">[beam]
polarization = &quot;circular&quot;
handedness = &lt;handedness&gt;
</code></pre>
<p>Example:</p>
<pre><code class="language-toml">[beam]
polarization = &quot;circular&quot;
handedness = &quot;left&quot;
</code></pre>
<a class="header" href="#elliptically-polarized-1" id="elliptically-polarized-1"><h3>Elliptically Polarized</h3></a>
<pre><code class="language-toml">[beam]
polarization = &quot;elliptical&quot;
x_mag = &lt;number&gt;
x_phase = &lt;number&gt;
y_mag = &lt;number&gt;
y_phase = &lt;number&gt;
phase_units = &lt;angle units&gt;
</code></pre>
<p>Example:</p>
<pre><code class="language-toml">[beam]
polarization = &quot;elliptical&quot;
x_mag = 1
x_phase = 0
y_mag = 1
y_phase = 3.141
phase_units = &quot;radians&quot;
</code></pre>
<a class="header" href="#element-types" id="element-types"><h2>Element Types</h2></a>
<ul>
<li><code>element_type</code>
<ul>
<li><code>&quot;polarizer&quot;</code></li>
<li><code>&quot;retarder&quot;</code></li>
<li><code>&quot;rotator&quot;</code></li>
<li><code>&quot;qwp&quot;</code></li>
<li><code>&quot;hwp&quot;</code></li>
</ul>
</li>
</ul>
<p>Example:</p>
<pre><code class="language-toml">[[elements]]
element_type = &quot;polarizer&quot;
angle = 0
angle_units = &quot;degrees&quot;
</code></pre>
<a class="header" href="#elements-1" id="elements-1"><h2>Elements</h2></a>
<a class="header" href="#polarizer-1" id="polarizer-1"><h3>Polarizer</h3></a>
<pre><code class="language-toml">[[elements]]
element_type = &quot;polarizer&quot;
angle = &lt;number&gt;
angle_units = &lt;angle units&gt;
</code></pre>
<p>Example:</p>
<pre><code class="language-toml">[[elements]]
element_type = &quot;polarizer&quot;
angle = 0
angle_units = &quot;degrees&quot;
</code></pre>
<a class="header" href="#polarization-rotator-1" id="polarization-rotator-1"><h3>Polarization Rotator</h3></a>
<pre><code class="language-toml">[[elements]]
element_type = &quot;rotator&quot;
angle = &lt;number&gt;
angle_units = &lt;angle units&gt;
</code></pre>
<p>Example:</p>
<pre><code class="language-toml">[[elements]]
element_type = &quot;rotator&quot;
angle = 45
angle_units = &quot;degrees&quot;
</code></pre>
<a class="header" href="#retarder-1" id="retarder-1"><h3>Retarder</h3></a>
<pre><code class="language-toml">[[elements]]
element_type = &quot;retarder&quot;
angle = &lt;number&gt;
angle_units = &lt;angle units&gt;
phase = &lt;number&gt;
phase_units = &lt;phase units&gt;
</code></pre>
<p>Example:</p>
<pre><code class="language-toml">[[elements]]
element_type = &quot;retarder&quot;
angle = 45
angle_units = &quot;degrees&quot;
phase = 3.141
phase_units = &quot;radians&quot;
</code></pre>
<a class="header" href="#quarter-wave-plate-1" id="quarter-wave-plate-1"><h3>Quarter-Wave Plate</h3></a>
<pre><code class="language-toml">[[elements]]
element_type = &quot;qwp&quot;
angle = &lt;number&gt;
angle_units = &lt;angle units&gt;
</code></pre>
<p>Example:</p>
<pre><code class="language-toml">[[elements]]
element_type = &quot;qwp&quot;
angle = 45
angle_units = &quot;degrees&quot;
</code></pre>
<a class="header" href="#half-wave-plate-1" id="half-wave-plate-1"><h3>Half-Wave Plate</h3></a>
<pre><code class="language-toml">[[elements]]
element_type = &quot;hwp&quot;
angle = &lt;number&gt;
angle_units = &lt;angle units&gt;
</code></pre>
<p>Example:</p>
<pre><code class="language-toml">[[elements]]
element_type = &quot;hwp&quot;
angle = 45
angle_units = &quot;degrees&quot;
</code></pre>
<a class="header" href="#conventions" id="conventions"><h1>Conventions</h1></a>
<a class="header" href="#definitions" id="definitions"><h2>Definitions</h2></a>
<a class="header" href="#polarization-orientation" id="polarization-orientation"><h3>Polarization Orientation</h3></a>
<p>Throughout this documentation you might see me say that the orientation of a beam is 45 degrees. There's a number of different ways to interpret this, so let's spell out exactly what I mean.</p>
<ul>
<li>The beam is traveling away from me.</li>
<li>The +x-axis is pointed to the right, and corresponds to an angle of zero.</li>
<li>All other angles are measured counter-clockwise from the +x-axis.</li>
</ul>
<p>For example, if I say that a beam has an orientation of 90 degrees, that means that it is oriented along the +y-axis. In actuallity, the polarization of a beam is a line that extends out to infinity in both directions, so the polarization in the previous example would extend along both the +y- and -y-axes.</p>
<a class="header" href="#handedness-1" id="handedness-1"><h3>Handedness</h3></a>
<p>The handedness of a circularly polarized beam is defined using the right-hand rule. If the beam is traveling away from you, the polarization vector of a &quot;right&quot;-hand circularly polarized beam will rotate clockwise in the plane of the polarization.</p>
<a class="header" href="#reports" id="reports"><h2>Reports</h2></a>
<a class="header" href="#relative-phases" id="relative-phases"><h2>Relative Phases</h2></a>
<p>The output of <code>polsim</code> will follow the conventions of Jones calculus with regards to relative phases. This means that the phase of the x-component will be factored out from both the x- and y-components, leaving the x-component as a real number, and potentially leaving the y-component with some phase relative to the x-component.</p>
<a class="header" href="#intensities" id="intensities"><h2>Intensities</h2></a>
<p>All beams start with an intensity of 1. If the output of your simulation shows <code>intensity: 5.00000e-1</code>, that means that the intensity of the beam at the end of the simulation is half of the original intensity.</p>
<a class="header" href="#phases" id="phases"><h2>Phases</h2></a>
<p>The phases that you see at the end of a simulation are always in radians.</p>

                    </main>

                    <nav class="nav-wrapper" aria-label="Page navigation">
                        <!-- Mobile navigation buttons -->
                        

                        

                        <div style="clear: both"></div>
                    </nav>
                </div>
            </div>

            <nav class="nav-wide-wrapper" aria-label="Page navigation">
                

                
            </nav>

        </div>

        

        

        

        
        <script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
        <script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
        <script src="searcher.js" type="text/javascript" charset="utf-8"></script>
        

        <script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
        <script src="highlight.js" type="text/javascript" charset="utf-8"></script>
        <script src="book.js" type="text/javascript" charset="utf-8"></script>

        <!-- Custom JS scripts -->
        

        
        
        <script type="text/javascript">
        window.addEventListener('load', function() {
            MathJax.Hub.Register.StartupHook('End', function() {
                window.setTimeout(window.print, 100);
            });
        });
        </script>
        
        

    </body>
</html>