This is an HTML version of the readme that is found alongside the Python script that I mentioned in the forward that was intended to help students learn about simulating ions by looking at source code. To download a .zip file containing a PDF version of this readme as well as the “ion_simulation_script.py” and the “electrodes.png” files, click the button below:
The Ion Simulator Script is written in a programming language called Python. Python is a free, general purpose programming language and is used to work with web servers, make games, automate tasks, control robots, and is used by many scientists, including mass spectrometrists, to analyze their data. Python does not come with many programming libraries by default. Programming libraries are collections of code imported into a programming project that add additional functionality to the program. For instance, the “NumPy” library (also referred to as the “numpy” or “np” library) is a Python library that works with numbers (Numerical Python) and adds matrix math and linear algebra algorithms to Python. A “distribution” of Python called Anaconda comes with a lot of libraries for scientists, including NumPy. I recommend installing the Anaconda distribution of Python from:
On the Anaconda download webpage, click “Download.” The browser should automatically scroll to the bottom of the page and present options for downloading Anaconda for Win-dows, MacOS, and Linux in both 64-bit and 32-bit versions. Unless you are working on a very old computer (>10 years old), you likely have a 64-bit operating system and should use the 64-bit option for the installer. Choose whichever operating system you are using (Windows, MacOS or Linux). Note: Continuum (the company that makes Anaconda) sells distributions of Anaconda to companies. As you are not a company, you are free to install Anaconda without paying. Everything needed for running the Ion Simulator Script is free.
Wait until the Anaconda installer has downloaded and click the installer to install it. Go through the install guide and use the default settings. Anaconda should begin installing. This might take a few minutes.
When Anaconda has finished installing, you should be able to open the “Anaconda Navigator”. Windows users can open the Anaconda Navigator by clicking on the “start” icon and typing “Anaconda” which should show the Navigator. Open the Anaconda Navigator which should look like:
Although Anaconda comes with many libraries, including NumPy and Matplotlib (a library we will be using for generating plots), it does not come with the “OpenCV” library that provides some very useful image processing functions. In order to install the “OpenCV”, please launch either the “CMD.exe” prompt or the “Powershell” prompt from the Anaconda Navigator. If you are using Linux or MacOS, there might be a different set of launchers, one of which should be something like “Terminal” or “Command Line”. The window you should see should look something like (although the background color might be different):
To test if things are working correctly, consider typing:
into the prompt. You should see a read back that is something like “Python 3.8.5” or Python followed by a slightly different number. This shows that Python is understood as a command. To install OpenCV, type:
pip install opencv-python
This should install the OpenCV library.
Now that the OpenCV library is installed, close the terminal window and go to the Anaconda Navigator. One of the launchers should be for “Spyder”, which is an integrated development environment for Python. Launch Spyder.
You should see a window with a few sub-sections open. Close any popups that open until you see a screen that looks like:
The colors might be “light” themed instead of “dark” themed as they are in this image.
The left side of Spyder lets you look at a Python file (like the “ion_simulator_script.py” file). Open that file in Spyder by clicking on “File” in the top-left corner, and then clicking on “Open” in the File submenu. Navigate to wherever you extracted the zip folder that this readme is in and select the “ion_simulator_script.py” file. The file should load and you should see a new tab on the left with lots of colored text.
Now that Spyder should be properly configured, you should be able to run the Ion Simulation Script by either clicking the green “run” triangle in the top-left side of the menu bar, or by pressing “F5” on your keyboard. In either case, you should see an output in the “console” (bottom-right) pane of the Spyder program and your window state should look something like:
You may or may not see a plot appear. If you look at the output of the console in the bottom-right pane, you should see “Simulation completed successfully!”. If you do, then everything worked! However, Spyder uses “Interactive” Python, or IPython, consoles. Although they can be very nice, these consoles prevent popout plots. To enable popout plotting (to better see the results of our simulations), consider clicking on the “Console” part of the Spyder program (the bottom-right pane) and typing in the prompt:
You should see some response such as “Using matplotlib backend: Qt5Agg”. If you re-run the script, there should be a popup window that appears. The popup window might be hidden behind other windows, so check the taskbar to see if there is a new icon that might be the popup window. In the popup window you should see two plots (you should be able to resize the popup window for better viewing):
The left plot shows the image “electrodes.png” the right plot shows the electrical fields generated by the electrodes and the “ion_simulation_script.py”. The positive electric fields on the right are red or reddish in color. The negative electric fields on the right are blue or blueish in color.
There are some lines that start in the lower-center of both plots. These lines continue to the top of the image. These lines are the paths of ions of different mass-to-charge (m/z) values. Each line is a different ion that flew from the bottom-center. The ions stop flying if they reach a boundary of the simulation, such as an edge or one of the electrodes.
The icons for the popout window allow for some interactions with the plots. You can zoom in on the plots by clicking on the magnifying glass icon and then dragging a box you might like to zoom into somewhere on the plot. You can also edit some of the image parameters by clicking on the icon that shows an upwards-trending line. For instance, you can change the color of the lines that are plotted or even change the colormap for the electric fields:
Here, I have zoomed in on the central electrode in the left plot and changed the colormap of the electric field map.
Now that we’ve run our first simulation, we can edit the electrodes to see how it affects the simulation! First, we could try adding a green electrode at the top of the screen to see what might happen. The electrodes are just colors in the “electrodes.png” file. Open this image up in your favorite image editor (I will use Microsoft Paint) and add a horizontal green bar at the top (make sure it is pure green, just like the strip at the bottom of the “electrodes.png” file!):
Now that the green electrode has been added, save the edited “electrodes.png” file (I generally use the shortcut “ctrl-s” or “cmd-s” as it makes editing faster). Make sure to save it in the same location and with the same name. Now running the ion simulation code we see:
The green electrode repelled the ions away and they scattered in different directions!
Since we are simulating positive ions, we could increase the voltage on the red electrode and try to repel them earlier. To do that, we can go to the “ion_simulation_script.py” source code on the “Modify Me!” section between lines 64 and 100.
The red electrode is defined to be RGB(255, 0, 0). The voltage value for is electrode is 80 volts. What happens if we change it to 150 volts? Let’s try it and find out!
Most of the ions didn’t make it through and were repelled!
Now that we know how to edit electrodes and how to remove them, let’s try to add a completely new electrode! First we need to pick a color: I’ll pick black color by going to Microsoft Paint’s “Edit Colors” menu and choosing a value of RGB(0, 0, 0):
Then I’ll draw something in black. Here is my electrode:
It’s in the center of the red electrodes. I’ll make it negative and try to attract the ions into it, so they won’t be deflected away anymore. I’ll try making it -300 volts! So I’ll go to the ion_simulator_script and define a black color, using my RGB values and add the “black_electrode” to the dictionary:
Now let’s fly the ions and see if they’re attracted:
It looks like it worked!
We can, of course, delete all these electrodes and try something completely different. Try it out!
Now that we know how to alter the script a little bit to change electrodes and how to change electrodes in Paint, we might want to dive a bit deeper into reading the script and figuring out how it works. The script should (hopefully) be self-explanatory, however, knowing some things up front might help.
Three single quotes at the top begin a documentation string or docstring. Docstrings are usually present at the start of files or the beginnings of functions to document what the file or function does. In this case, the docstring just provides a notice about the Ion Simulation Script’s authors and attributions. The docstring closes like it opens, with three single quotes (double quotes can also be used, but then the docstring must start and end with three double quotes). Docstrings are not code, but documentation. Python has another type of documentation, or “comments”. The next type is on line 5. This is a line comment and begins with a pound-sign or hashmark. This type of comment is generally about the code that follows it. Multiple lines of a single comment all need to start with a “#”. A “#” tells the Python interpreter (a program that reads the script file one line at a time, much like a person does, but then goes and runs the program, one line at a time) to ignore whatever comes after on that line.
Although learning Python is not needed for understanding the script, understanding a few key words and concepts might be helpful:
Although this list is not comprehensive of Python, (or even comprehensive for the Ion Simulator Script), understanding how the concepts work should make reading the code easier and improve understanding.
After reading the Ion Simulation Script source code, you should be ready to answer some questions or think about things such as: