Back to simulacrum reference index: https://confluence.slac.stanford.edu/x/hak7Eg
Scope of this guide
This guide will teach you how to look up PVs that you may want to write into your own simulacrum services.
You will learn how to look up lattices on the tao_shell.py command line to help you pick out the essential PVs that should be included in your simulacrum service.
How to read this guide
Bullet points will walk you through a step-by-step guide in the instructions section.
Green text means you should be typing it into your terminal/file as the bullet point specifies. E.g., source ENV
Since some commands will be specific to your computer, text in arrow brackets will describe fields where you have to supply your own customization. E.g., <your name here>
Background
If you already know how tao_shell.py works, skip ahead to the Instructions section.
Here at SLAC, simulacrum is not just a tool for mathematical modelling. We also try to model the structure and flow of data, as it appears on the real machine. Therefore, before you dive into the code, you should ask yourself: what instrument am I trying to model? What attributes make this instrument interesting to model? Make a list of attributes that this instrument will need to read or write. Let's name a few attributes we would need for a klystron:
- Desired phase (operator input)
- Phase (model output)
- ENLD (MeV analog of the amplitude)
- Desired amplitude (operator input)
- Amplitude (model output)
This list of attributes will help you write the first class in your simulacrum service: the PVGroup.
Fig. 1: The first six lines of the KlystronPV class from klystron_service.py.
Don't feel like you need to be able to write Fig. 1 yet! I suggest you begin there when you start writing your own simulacrum service, but we're not there yet. I include this prelude because I want you to think about the variables you might want to model while you're playing with tao_shell.py.
If you're not familiar with the operating system, or even the machine you're modelling, you can find out a little by looking in lclshome: "Accessing lclshome" (https://confluence.slac.stanford.edu/x/dP2REg). This is a very dense way to figure out what your machine reads and writes. However, in some situations, it can be a good resource to "check your PV". lclshome tends to become oversaturated with PVs, so try to find a control panel that relates specifically to the part of the instrument that interests you. Once you're there, simply click with your mouse scroll wheel on a particular field to get the PV name for that field. However, looking at Fig. 2, we see that this is cumbersome and involves sifting through way more PVs than we'll ever need. If only there were a better way to figure out what attributes "matter" to our model....
Fig. 2: After ten minutes of clicking through lclshome, I found the PV "KLYS:LI25:11:PHAS", confirming that the name for the phase PV of any klystron will be ":PHAS". This is pretty pointless unless you know what to look for. Most of the other fields are irrelevant for our model.
Unless you're an operator, you probably don't know how to do this the long way. While tao_shell may not give you the exact names of the PVs in the control system, sometimes you just want to know the kinds of things that are important to our model. Tao's list of device attributes can be your tool to help narrow down the endless list of device PVs to what actually matters!
Instructions
If you don't want to click through lclshome, don't worry. Most of the interesting (i.e., easily-modelled) variables can be found using tao_shell.py. I highly recommend following along with your own terminal if you aren't very familiar with the device you want to model, and you need some guidance on what variables you should consider "important" when you go about writing your service. If you followed my article "Acquiring a Simulacrum Directory" (link), you will find tao_shell.py under simulacrum/util/tao_shell.py
NOTE: tao attributes are not the same thing as PVs. It is not the same data format. Simulacrum services use EPICS PVs to control tao attributes, but there is not a 1:1 equivalence connecting every EPICS PV to a tao attribute. Tao attributes constitute a smaller list of variables and can help you narrow down the PVs you want to model. If you're looking for the exact name of a PV to model, you have to go through lclshome or contact an operator for help.
As a simulacrum development intern, I check tao_shell.py all the time to see what variables will be readily accessible to the model. It's much easier to model a variable if it already exists as a tao attribute because the physics of that attribute is already calculated by the accelerator model. It also tracks some constants like the location and dimensions of your device. Variables that don't come up in your tao_shell.py search will need their logic and physics hard-coded into your service itself.
To run tao_shell.py, you will need to set up your fresh terminal like so:
- ssh mcc-simul
- bash
- cd <your simulacrum directory>
- source ENV #we need this to run python3. If you use python, you will get the error "ImportError: No module named util_tao"
- python3 util/tao_shell.py
You will know you are successful when you see a ">>" input bar:
Fig. 3: Started tao_shell.py successfully.
Now we can search for instruments and their attributes! This will involve the tao "show" command. I will summarize the notes from the official tao manual, pages 19-23 (link).
- The two major commands are show element and show lattice
- These can also be written as show ele and show lat
- show ele and show lat will only display devices that are included in the beampath for your currently active model service. For setting up your model service, check out the article "How to Set up Simulacrum" (link).
- show ele lets you look up the attributes of a single device using its element name
- show lat creates a table of devices attributes based on keyword or element name
Those last two bullet points require explanation. Usually, if you're looking for a specific element, you run a broad show lat command, then pick a single device out of that list to run a show ele command. I'll use klystrons as an example. I have no idea what keyword I need to search for a klystron, so I will make use of the * and % symbols.
If you don't know the element name or the keyword for your device, you can try looking up your device on the Oracle database: "Looking up Devices" (https://confluence.slac.stanford.edu/x/tvqREg).
- show lat * gives a very, very long list of all the devices that tao recognizes in your beamline. If you have no idea where to start looking, use this command to browse through devices until you think you've found If you're looking for a specific klystron, for instance, you don't need to find the correct klystron, only a klystron. Once you find a single klystron, you will be able to narrow your search results.
Fig. 4: The first devices that show up in the lattice for the CU_HXR beamline. The 2nd column ("name") displays the element name. The 3rd column "key" displays the keyword for that type of device.
- show lat <element name>* will help you get a list of devices if you know the element names of your devices or want to guess. For instance, in Fig. 5, I was able to guess correctly that beam position monitors (BPMs) would likely have BPM in their element name.
Fig. 5: The first BPMs that show up in our element name search.
- show lat <keyword>::* will give you all the devices of a certain keyword type. This is helpful if your device does not have a single standardized element name. For instance, in Fig. 6., I happened to know that all undulator go by the keyword "Wiggler".
Fig. 6: Getting a list of undulators based on the keyword "Wiggler"
- The asterisk isn't the only option for adding logic to your search result. The asterisk stands for "all", so putting it at the end of the search tells the system to look for all devices in that category. Additionally, the symbol "%" can be used in the middle of a search command as a stand-in for any character.
Fig. 7: Here, I use the "%" symbol to find every 1A klystron in sector 20 through 29
- Now that you have a list of devices, you can pick one out to analyze. This is where we use the show ele <element name> command. The element name is always the second column in the output of a show lat command. Show ele will output a lot of information, but most of the time we're only worried about the attributes.
- Don't panic! There are a lot of attributes here, but you'll probably only end up using a handful of them in your model. In the background section of this article, I talk more about narrowing down this list. Before you start writing all these attributes into your simulacrum service, think: what does my modeled instrument need to read or write in order to be useful. A machine may only need a handful of attributes to be useful!
Fig. 8: The attribute table of klystron 22 1A, as given by a show ele command
- Finally, let's say you want a neat lattice showing multiple devices, but you want more than the default attributes to be shown. Looking at the attributes named in the show ele gives us the syntax we need to select attributes. show lat -attribute <attribute> <your search criteria here>
Fig. 9: A custom attribute lattice for all the klystrons in sector 22. Adding custom attributes has removed the twiss parameters (beta, phi a, eta, orbit, etc.) from the lattice output, leaving us with the default parameters (s and L) and our custom ones. From right to left: machine index # in the tao database, element name, keyword, location in the linac (meters), length of the instrument (meters), control system name, whether the device is on or off, and the gradient at that device. Notice how I was able to select multiple attributes to be shown (is_on and gradient).
- There are more ways to customize your show lattice command. Likely, the only ones that might interest you are -attribute <attribute> (see above), -no_label_lines (for creating an output format without the header labels), -lords (shows machines that control multiple other machines), and -no_slaves (removes the smallest division of machines that are often trivial. Slaves are denoted by a "#" in their element name, and can bug your code if you include them in your simulacrum service).
Fig. 10: How to format your show lattice command. Taken from page 20 of the tao manual (link).
Now, you should have all the tools you need to investigate how data are currently organized for the device you want to model. To supplement this, you should also get in touch with the SLAC colleagues whose research focuses on changes in your device. Sometimes, there is high demand to model a particular PV behavior, and people will be interested in simulacrum services that include that PV behavior. Now that you know which PVs you want, it's a good time to look at a dissection of one particular simulacrum service. The next chapter will walk you through the basic structure of the sc_rf.py so you can start copying and pasting the framework for your own service. "Dissecting a Simulacrum Service" (https://confluence.slac.stanford.edu/x/Lrs7Eg). Don't worry about understanding every bit of syntax in there yet. You will learn a lot by copying + pasting from existing services until something doesn't behave the way you want it to. That article will also include examples of putter functions, which you will read about in "Simulating PVs 1: caget and caput" (https://confluence.slac.stanford.edu/x/y6k7Eg) as well as "Simulating PVs 2: putter functions" (https://confluence.slac.stanford.edu/x/2daREg).
Find more simulacrum documentation on the reference guide. https://confluence.slac.stanford.edu/x/hak7Eg