Scope of this guide

This will teach you how to run simulacrum using the files you downloaded in Acquiring a Simulacrum Directory.

You will learn how to customize your model service with the beamline and jitter, as well as how to select the machine services you're going to run.


How to read this guide

Bullet points will walk you through a step-by-step guide.

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>


Instructions


Now that you have the essential files, you can start from a fresh fastx terminal.

  • Refresh your fastx token for the day.
    • kinit
    • <your fastx password here>
    • If you're new to fastx, this confirms that you are still logged in. The fastx token expires every 24 hours by default.
  • ssh mcc-simul
    • You will get a block of text if you're connected. That's a good thing!


  • Get set up with your virtual environment
    • bash
    • cd <your simulacrum directory here>
    • source ENV


  1. Make sure you are running python 3. All the following instructions will assume so.
  2. Install bmad by running conda install -c conda-forge bmad
  3. Get the LCLS-lattice by running git clone git@github.com:slaclab/lcls-lattice.git
  4. Add the line export LCLS_LATTICE=[path to your LCLS-lattice repo] to your ~/.bashrc or ~/.profile (whichever your system uses)
  5. Get the simulacrum repo by running git clone git@github.com:slaclab/simulacrum.git
  6. Add the line export PYTHONPATH="${PYTHONPATH}:[path to your simulacrum repo]" to your ~/.bashrc or ~/.profile (whichever your system uses)
  7. cd into the simulacrum repo and run python model_service/model_service.py sc_hxr installing missing modules as you go (it's a bit of a whack a mole situation)
    1. Every ModuleNotFoundError should be accompanied by a pip install [missing module] or conda install if you're using a conda environment


  • Almost there! Now we'll start up the model service in the background. Think of this as the "beamline service", and can simulate a beam in the absence of any other services.
    • Pick the beamline  you're modeling: lcls_classic, cu_hxr, cu_spec, cu_sxr, sc_hxr, and sc_sxr. Consult your supervisor if you don't know which beamline you're working with.
    • python3 model_service/model_service.py <your beamline here> &
    • You may need to press Enter after a few moments to get your command line back.
    • The & at the end is what allows it to run in the background while you do other things with your terminal.
    • If you get an error message that the address is already in use, it means a model service is already running on your desktop and you need to terminate it.


  • If you want to quit your current model service and run a different one, open up your background processes
    • ps -ef | grep <your fastx username here>
    • kill <the leftmost serial number corresponding to your model service>
    • If the model service persists, try kill -9 <serial number>
      • To kill the model service in the figure below, I would default to kill -9 161890


  • You can also add jitter to your model service. (Currently bugged...) This adds an element of "noise" to your data for every tick. This is more CPU-intensive
    • python3 model_service/model_service.py <your beamline here> --enable-jitter &


  • Now that the model service is running, we can run our own simulacrum services.
    • Your first instinct may be to turn on every service that you have in your files, in order to get a "complete" model running. In fact, you only need to run the services that you are trying to read/write to.
    • Ex: You're tasked with adding the PV "color" to the magnet service, so that the magnets can now report what color the beam is, for science! You want to see if your changes work, so you launch the model service and the magnet service to try it out.
    • Ex: You're modelling a brand-new machine called a doodad, and you have written a doodad_service.py for simulacrum. The doodad is supposed to knock the beam out of alignment. To see how much it deflects the beam, you start the model service, the BPM service, and the doodad service. You plan to turn on a doodad upstream of a specific BPM and then ask the BPM to report the beam's position.
    • python3 <your desired service here> & to turn on another service in the background.
    • Just like the model service, you will need to go into ps -ef | grep <your fastx username here> and kill the serial number in order to stop these background services.


Now that your services are running, you're probably thinking "I don't see anything...". You'll need caget and caput commands to read and write to simulacrum! To find out, see the article on Simulating PVs 1: caget and caput

  • No labels