polsim is a command line tool for quickly doing polarization simulations with Jones calculus. 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. polsim makes life easy by letting you skip the tedious work of multiplying the matrices together by hand.

Would you rather look up this matrix,

\[ \begin{bmatrix} \cos^{2}\left(\theta\right) + e^{i\varphi} \sin^{2}\left(\theta\right) & \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) & \sin^{2}\left(\theta\right) + e^{i\varphi} \cos^{2}\left(\theta\right) \\ \end{bmatrix} \]

then plug in \(\theta = \pi/4\) and \(\varphi = \pi/2\), or would you rather write this?

[[elements]]
element_type = "retarder"
phase = 1.57  # pi/2
phase_units = "radians"
angle = 45.0
angle_units = "degrees"

polsim is really just a pretty face for the simulation library I wrote, which can be found here. If you think you've found a bug in the simulation results, you should create an issue on Github. The simulation library is tested very thoroughly for correctness, but it's entirely possible that something slipped through the cracks!

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 polsim one day, but I don't see myself having the time to work on it any time soon.

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

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.

The first step is to head to the GitHub repository and download the latest release for your operating system. polsim 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:

• Windows: polsim-<version>-x86_64-pc-windows-msvc.zip
• macOS: polsim-<version>-x86_64-apple-darwin.tar.gz
• Linux: polsim-<version>-x86_64-unknown-linux-gnu.tar.gz

The next step is to extract the archive you just downloaded and put the executable file somewhere. For Windows, the executable will be called polsim.exe, and for macOS and Linux the executable will be called polsim. polsim doesn't need to be put anywhere special, so you can put it wherever you want.

polsim is a command line program, so you'll be using a shell (cmd.exe on Windows, Terminal on macOS, etc) to interact with it. Your shell needs to know where to find polsim in order to use it, so you have two options:

• Put polsim in a directory, then avigate to this directory each time you want to use polsim.
• Put polsim in a directory, then add that directory to your shell's PATH so you can use polsim from any directory.

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 PATH, here are some guides for each supported operating system:

• Windows
• macOS
• Linux

Note: This section assumes that you've already installed polsim. If you haven't installed polsim, you can find instructions in the Installation section.

Note: Some of what follows will be things that you type into a shell/terminal. This will be cmd.exe on Windows, Terminal.app on macOS, or your terminal of choice on Linux. The parts that you type into a terminal will appear like this:

$ some commands to execute

In these parts the $ just indicates the prompt in your shell, so you don't need to type the $ character. Some instructions will contain text in <angle brackets>. 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.

Let's get things started with an example. Put the following text into a file called simulation.toml and save it somewhere.

# simulation.toml
[beam]
polarization = "linear"
angle = 90
angle_units = "degrees"

[[elements]]
element_type = "polarizer"
angle = 45
angle_units = "degrees"

Next, open up your shell and navigate to the directory in which you saved simulation.toml.

$ cd <path to the directory>

Now we're going to tell polsim to run a simulation with this file.

$ polsim simulation.toml

When you run it you should see the following output:

$ 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

You've just run your first simulation! Let's dig in and see what this output is telling us.

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.

intensity: 5.00000e-1

All beams in polsim 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.

x_mag: 5.00000e-1
x_phase: 0.00000e0

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 x_mag and x_phase can be written mathematically as:

\(E_x = r e^{i\varphi} = x\_mag\,e^{i\,x\_phase}\)

The same idea applies to y_mag and y_phase, obviouslly.

Another thing to notice is that the x- and y-components are not normalized to 1, they are normalized such that x_mag^2 + y_mag^2 = intensity.

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 polsim 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.

Let's see what happens when you make an error in your simulation file. We're going to delete the last line of simulation.toml and see what polsim has to say about that. Copy and paste the following text into a file called has_error.toml, then save it.

# has_error.toml
[beam]
polarization = "linear"
angle = 90
angle_units = "degrees"

[[elements]]
element_type = "polarizer"
angle = 45

Now we're going to (try to) run a simulation with this file.

$ 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'

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.

error: invalid system definition

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 has_error.toml, but we don't quite know what just yet.

caused by: invalid element definition

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.

caused by: invalid polarizer definition

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?

caused by: invalid angle definition

Something seems to be wrong with the definition of the angle of the polarizer. Let's see what's up.

caused by: missing parameter in definition: 'angle_units'

This is the source of the problem. Every angle that you define needs two pieces: angle and angle_units. Our problematic simulation file, has_error.toml, left out the angle_units for the definition of our polarizer.

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 GitHub repository.

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.

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 .toml 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 .toml extension. TOML has its own rules for how to write things, but I'll teach you everything you need to know.

Read on to learn how to define your own simulations!

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:

[beam]
# beam definition goes here

[[elements]]
# the first element goes here

[[elements]]
# the second element goes here

...

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 TOML GitHub repository.

There are two main sections of the simulation file. The first section is the part marked by the [beam] heading. The second section is marked by one or more [[elements]] headings. The [beam] heading marks the definition of the beam that you want to start your simulation with. Each [[elements]] 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.

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:

[beam]
polarization = "linear"
angle = 45
angle_units = "degrees"

The definitions of beams and elements are written out in key-value pairs in the form key = value.

The rule here is that numbers can be written in just about any way you want. For example, 2, 2.0, -2, and 2.0e-3 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 angle = 45, but it is not valid to write angle = 30 + 15 even though 30 + 15 is obviously equal to 45. 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. "linear".

Read on to see how to define beams and elements.

The section for defining a beam is marked by [beam]. Notice that there's only one set of braces around [beam] as opposed to two set of braces around [[elements]]. In TOML we say that [beam] is a table, and [[elements]] is an array (a list of values, in this case a list of elements).

The [beam] 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.

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.

The next few sections will describe how to define beams with different types of polarization.

Let's start out by defining a linearly polarized beam with horizontal polarization. Here is the whole definition:

[beam]
polarization = "linear"
angle = 0
angle_units = "degrees"

That's not so bad, is it?

The first key is polarization. Every beam definition needs a polarization 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 angle or angle_units when polarization = "circular". We're getting ahead of ourselves though, so let's get back to our linearly polarized beam.

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: angle and angle_units. The angle key takes the actual value of the angle, and the angle_units key specifies the units in which angle is given. The angle_units key can take the following values:

• "degrees"
• "radians"

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!

The definition of a circularly polarized beam is even simpler than that of a linearly polarized beam:

[beam]
polarization = "circular"
handedness = "right"

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 "handedness" of a circularly polarized beam is defined by the "right-hand rule", that is, a beam is "right" handed if the polarization vector appears to rotate clockwise as the beam travels away from you.

The handedness key can take the following values:

• "left"
• "right"

If you know someone who has a hand that isn't a right or left hand, please let me know.

If you want to define an arbitrary beam, you can do so with the "elliptical" polarization type. For this beam definition there are no shortcuts, you have to specify everything yourself.

[beam]
polarization = "elliptical"
x_mag = 1.0
y_mag = 1.0
x_phase = 0.0
y_phase = 3.141
phase_units = "radians"

The x_mag and y_mag keys are the magnitudes of the x- and y-components of the polarization. The x_phase, y_phase, and phase_units keys specify the phases of the components. In polsim phases are just like angles. The phases are even specified with the same units as angles.

This is the one exception to the "specify the units of every angle" rule. Both x_phase and y_phase must have the same units. I don't know why you would define x_phase with one set of units and y_phase with another set of units, so I'm just not going to let you do that.

The last thing to mention is that the intensity of the beam will be 1 no matter what magnitudes you provide in x_mag and y_mag. 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!

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:

x_mag^2 + y_mag^2 = initial_intensity
1 + 1 = 2
initial_intensity = 2

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 initial_intensity.

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

Now the intensity will be 1 when computed from the normalized components:

normed_x_mag^2 + normed_y_mag^2 = intensity
(0.707^2) + (0.707^2) = intensity
0.5 + 0.5 = intensity
1 = intensity

Recall that you specify the elements of the optical system with one or more sections that start with [[elements]]. In TOML we say that each [[foo]] defines an item in an array (list) called foo. In our case we're defining the items (optical elements) in an array called elements. 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!

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 element_type key. The list of possible element types is as follows:

• polarizer: "polarizer"
• polarization rotator: "rotator"
• retarder: "retarder"
• quarter-wave plate: "qwp"
• half-wave plate: "hwp"

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 angle and angle_units). The same goes for phase and phase_units.

Let's look at how you define each element type.

A polarizer is an optical element that only lets polarization of a certian orientation pass through. Think about it like this:

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.

It's the same thing with light and a polarizer. Exactly the same.

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:

[[elements]]
element_type = "polarizer"
angle = 45
angle_units = "degrees"

This definition corresponds to an ideal linear polarizer that makes a 45 degree angle with the +x-axis.

A polarization rotator is pretty much what it says on the tin: it rotates the polarization of a beam.

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.

Here's an example of an element that rotates the polarization of a beam by 90 degrees:

[[elements]]
element_type = "rotator"
angle = 90.0
angle_units = "degrees"

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 "retarder". The polarization component perpendicular to the "fast" axis of the retarder will lag behind the other component by some fixed phase specific to the particular retarder.

A retarder is more complicated than the other elements we've discussed here, so I'll direct you to the wonderful RP Photonics Encyclopedia to learn more about how a retarder works under the hood.

The effect that the retarder has on the beam depends on two things:

1. The orientation of the beam's polarization relative to the orientation of the retarder's "fast" axis.
2. The phase delay introduced by the retarder.

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!

[[elements]]
element_type = "retarder"
angle = 45
angle_units = "degrees"
phase = 1.5705
phase_units = "radians"

If you fix the phase delay introduced by a retarder to pi/2, 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.

The definition of a quarter-wave plate only needs an angle since the phase is a fixed value.

[[elements]]
element_type = "qwp"
angle = 45
angle_units = "degrees"

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.

Just like a quarter-wave plate, you only need to specify an angle in your definition since the phase is a fixed value.

[[elements]]
element_type = "hwp"
angle = 45.0
angle_units = "degrees"

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.

Read on to see some examples!

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:

[beam]
polarization = "linear"
angle = 90
angle_units = "degrees"

[[elements]]
element_type = "polarizer"
angle = 45
angle_units = "degrees"

Here's what the output looks like:

$ 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

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 Malus's Law. Malus's Law says that a beam's intensity after it passes through a polarizer depends on the angle between them:

\( I = I_0 \cos^{2}\left(\theta\right)\)

Since the angle between the polarizer and the beam's polarization is 45 degrees, \( I = 0.5 I_0 \).

If I orient two polarizers perpendicular to one another, no beam will be able to pass through. Here's what that looks like:

[beam]
polarization = "linear"
angle = 45
angle_units = "degrees"

[[elements]]
element_type = "polarizer"
angle = 0
angle_units = "degrees"

[[elements]]
element_type = "polarizer"
angle = 90
angle_units = "degrees"

The orientation of the beam is completely arbitrary in this situation, so I just chose 45 degrees. Here's what the output looks like:

$ 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

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 1e-17 or 1e-33 is basically zero anyway when compared to 1 (the intensity of the original beam).

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.

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:

[beam]
polarization = "linear"
angle = 90
angle_units = "degrees"

[[elements]]
element_type = "polarizer"
angle = 45
angle_units = "degrees"

[[elements]]
element_type = "qwp"
angle = 0
angle_units = "degrees"

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:

$ 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

If you go back through the previous two examples, you'll see that the phases (x_phase and y_phase) are zero for both examples. This time, however, y_phase is not zero, it's pi/2! That tells us that there is a delay between the x- and y-components.

Note: In the definitions that follow, text in <angle brackets> are placeholders for values that you must supply.

[beam]
# beam definition goes here
polarization = <polarization>
<polarization-specific keys>

[[elements]]
<element definition>

[[elements]]
<element definition>

...

• angle
  • Takes an integer or floating point number.
• angle_units
  • "degrees"
  • "radians"

Example:

angle = 0
angle_units = "degrees"

Phases are really just angles, so they follow exactly the same rules as angles.

• phase
  • Takes an integer or floating point number.
• phase_units
  • "degrees"
  • "radians"

Example:

phase = 3.141
phase_units = "radians"

• handedness
  • "left"
  • "right"

Example:

[beam]
polarization = "circular"
handedness = "left"

• polarization
  • "linear"
  • "circular"
  • "elliptical"

Example:

[beam]
polarization = "circular"
handedness = "left"

[beam]
polarization = "linear"
angle = <number>
angle_units = <angle units>

Example:

[beam]
polarization = "linear"
angle = 0
angle_units = "degrees"

[beam]
polarization = "circular"
handedness = <handedness>

Example:

[beam]
polarization = "circular"
handedness = "left"

[beam]
polarization = "elliptical"
x_mag = <number>
x_phase = <number>
y_mag = <number>
y_phase = <number>
phase_units = <angle units>

Example:

[beam]
polarization = "elliptical"
x_mag = 1
x_phase = 0
y_mag = 1
y_phase = 3.141
phase_units = "radians"

• element_type
  • "polarizer"
  • "retarder"
  • "rotator"
  • "qwp"
  • "hwp"

Example:

[[elements]]
element_type = "polarizer"
angle = 0
angle_units = "degrees"

[[elements]]
element_type = "polarizer"
angle = <number>
angle_units = <angle units>

Example:

[[elements]]
element_type = "polarizer"
angle = 0
angle_units = "degrees"

[[elements]]
element_type = "rotator"
angle = <number>
angle_units = <angle units>

Example:

[[elements]]
element_type = "rotator"
angle = 45
angle_units = "degrees"

[[elements]]
element_type = "retarder"
angle = <number>
angle_units = <angle units>
phase = <number>
phase_units = <phase units>

Example:

[[elements]]
element_type = "retarder"
angle = 45
angle_units = "degrees"
phase = 3.141
phase_units = "radians"

[[elements]]
element_type = "qwp"
angle = <number>
angle_units = <angle units>

Example:

[[elements]]
element_type = "qwp"
angle = 45
angle_units = "degrees"

[[elements]]
element_type = "hwp"
angle = <number>
angle_units = <angle units>

Example:

[[elements]]
element_type = "hwp"
angle = 45
angle_units = "degrees"

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.

• The beam is traveling away from me.
• The +x-axis is pointed to the right, and corresponds to an angle of zero.
• All other angles are measured counter-clockwise from the +x-axis.

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.

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 "right"-hand circularly polarized beam will rotate clockwise in the plane of the polarization.

The output of polsim 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.

All beams start with an intensity of 1. If the output of your simulation shows intensity: 5.00000e-1, that means that the intensity of the beam at the end of the simulation is half of the original intensity.

The phases that you see at the end of a simulation are always in radians.