Running experimental TMS software

This page outlines the steps needed to run the TMS (Telescope Metrology System) experimental software developed during the summer and fall of 2020, and spring of 2021.

Description

The current (circa summer and fall 2020, and Spring & Summer 2021) TMS software system is a collection of command-line programs and scripts. It allows taking TMS raw measurements and then it calculates the appropriate corrections taking into consideration various TCS and LBC instruments parameters. The final correction can then be sent to the TCS to be applied. There are various modes and configurations to run the TMS software collection and this page explains them and details the steps to do that.

As a note, this is a temporary setup for TMS operation. We are in the process of redesigning the entire TMS software system, which will be better in many ways.

TMS Strategies for LBC Observing

There are three different strategies for how to use TMS to improve your LBC observing: prepositioning M1 to shorten your initial collimation time; extending the interval before running FPIA again; extending a single FPIA to cover many positions in the sky. As of April 2022, all three of these modes are working with reasonable reliability, and have been used on-sky for science observations.

Using TMS to pre-position M1 to shorten your initial collimation

Prepositioning the optics can be a significant savings of time at the start of LBC observation, but using a reference from a previous night may not always give perfect collimation. The idea is to get close, so that FPIA has very little work to do. Beware that the pre-positioning will not work if the TMS collimators have been realigned since the previous reference. The basic sequence is:
  • have someone turn on the TMS Etalon laser (when no infrared instruments are working)
  • copy 4 reference files from a previous night (instructions below)
    • Do NOT take a new reference offset.
  • start the active TMS loop (instructions below) This can be with the dome closed, or in bright twilight before sky flats.
  • preset to your collimation field (as normal, after flats)
    • allow time for TMS to make one or two corrections at the elevation position of your target
  • Stop ^C your active TMS loop
  • run your initial FPIA (as normal) - DOFPIA should be sufficient, as the large coma that requires DOHYBRID should have been taken care of.
  • set a new TMS reference offset (instructions below) if your FPIA gave a good result

Using TMS to extend the time between running FPIA

This is the simplest and most standard mode of running TMS with LBCs. The basic sequence is:
  • have someone turn on the TMS Etalon laser (when no infrared instruments are working)
  • preset to your collimation field (as normal)
  • run FPIA (as normal)
  • set a TMS reference offset (instructions below)
  • start the active TMS loop (instructions below, note that TMS will not apply a correction when the primary is in the extrafocal position.)
  • copoint and observe as normal, except you need to do FPIA less often.
  • if you decide to run FPIA again, then you must stop ^C your active TMS loop (at least by the time FPIA finishes).
  • after a new FPIA collimation, you MUST set a new TMS reference offset (or TMS will remove the corrections that FPIA just put in).

TMS measures the distance between the primary mirror and the LBC hub. TMS software also measures backplate-faceplate temperature of the primary mirror to estimate the change in focus since the time of the reference offset (if that reference offset was from today). TMS does not yet predict Z11/Z22 spherical aberration that may be needed on the primary (we are working on it), but it does tolerate any Z11/Z22 that you may apply.

Using TMS to extend a single FPIA to multiple positions on the sky

This is particularly useful for flux standards, or for nights with poor seeing (where you want decent collimation, but do not need the absolute best collimation). If active TMS is already running, the basic sequence is:
  • preset to your new field (as normal)
  • allow time for TMS to make one or two corrections at the elevation position of your target (TMS is faster than running FPIA, but is not infinitely fast. This probably takes 1-1.5 minutes.)
    • We recognize that staring at the PSFGUI or at LBTplot to learn when TMS applied corrections is inconvenient. We've created watch_tms_left.py and watch_tms_right.py to tail the TMS log files and show you when new corrections happened.
  • copoint, and continue with your observations

Prerequisites

In order to run the TMS software, you will need the following items:
  1. Have access to the machine "robs.mountain.lbto.org" as user "telescope"
  2. Have both (or one of the) LBCs authorized and in beam (depending on which side you use).
  3. Have the primary mirror in a "collimated" position.
  4. Have the Etalon multiline TCP server turned on.
  5. Have the Etalon laser on and ready.
  6. Know that scripts live in /lbt/lbto/supportscripts/MetrologySupport/

TMS Modes (Active or Passive)

There are two different modes you can run the TMS software and each mode has a few more options. They all have their own convenience shortcut script associated. When you decided to run a particular mode/option, then you should invoke the corresponding script (more on the steps in later sections, this section explains the modes and their scripts).

  • Active Loop mode, this is the normal mode that calculates and sends the corrections continuously (every 20-30 sec) to the telescope.
    1. Bino: running TMS on both sides, use the script tms_loop.pl
    2. SX: running TMS on SX (left) side, use the script tms_loop_left.pl or tms_loop.pl -s 0
    3. DX: running TMS on DX (right) side, use the script tms_loop_right.pl or tms_loop.pl -s 1
  • Passive Loop mode, this mode does not send corrections to the telescope, but otherwise runs continuously and keeps calculating TMS corrections.
    1. Bino: running TMS passively on both sides, use the script tms_loop_passive.pl or tms_loop.pl -p
    2. SX: running passive TMS on SX (left) side, use the script tms_loop_left_passive.pl or tms_loop.pl -s 0 -p
    3. DX: running passive TMS on DX (right) side, use the script tms_loop_right_passive.pl or tms_loop.pl -s 1 -p

Currently all modes require that the real measurement data from the Etalon software match the reference vector's channel information (e.g., if the reference vector has nine channels, then all subsequent vectors require the same nine channels to be present). Otherwise they will refuse to proceed to the pose calculation step. It is possible to use the drop option to specifically disable particular channels in the reference vector. See the later sections on information regarding this option.

Running a Particular Mode

The following steps are needed to run the TMS software in a particular mode. Note that you can only run one mode at a time. Please do not launch multiple instances of the TMS software.

  1. Check to see that you have met all the prerequisites.
  2. Login to the machine "robs.mountain.lbto.org." You can do either of the following:
    • On a Linux/Unix system, open a terminal window and type the following command and press enter: ssh telescope@robs.mountain.lbto.org If you are asked to enter passwords, then please contact LBTO IT for help. Normally you should be able to login without a password from most LBTO machines.
    • If you are using Windows system, or prefer a remote desktop, then you can login using a remote desktop application such as "x2go." Please configure your remote desktop for the machine "robs.mountain.lbto.org" and user "telescope" and desktop "MATE". Note if you are outside of the LBTO network, then you may need to turn on VPN before being able to make connections to the machine "robs.mountain.lbto.org"
    • The TMS software will run as other users, and will run on other mountain workstations. Using telescope@robs minimizes your risk of file permission problems, and is recommended.
  3. Enter the following command and press enter (if you use remote desktop to login to "robs.mountain.lbto.org", then please open a terminal window first): cd /lbt/lbto/supportscripts/MetrologySupport
  4. Once you've done FPIA enter the following command and press enter: ./lbc_set_tms_offset.py -s 2 This step sets a reference pose for the TMS system on both sides. It will output some text in the terminal window and will typically take around 30 seconds to complete. This can happen after FPIA has finished, or after your science OB is running, but should not be done while the telescope is slewing to the scince field. If you have failure reported in this step, then please repeat it multiple times. If there is still failure, then you won't be able to continue. Please contact software support for help. The "-s 2" option is for Bino TMS. Use "-s 0" for SX TMS, and "-s 1" for DX TMS.
  5. Running loop mode:
    1. Then enter the following command and press enter: ./[mode_script] Where [mode_script] is the name of the script given in the previous section. When running, it will output lots of texts in the terminal window and will run forever (for example to run the DX TMS active mode script, you will enter: ./tms_loop_right.pl). If you see errors, then you can let it run for a while and see if it will correct itself. If not, then please proceed to the next step and contact software support for help.
    2. Press Ctrl-C (both the "Control" and "C" keys together) to stop the program. If it does not respond, then please press "Ctrl-C" multiple times.

In any mode, the screen outputs should give you ample information on what it is doing.

Note if you want to make a new reference pose (e.g., after an active optics cycle) and you are running in loop mode, then you will need to stop the program first by executing step 2 in the loop mode section, and then repeat loop mode steps 1 and 2.

Also note if running in any of the loop modes, you will need to keep your terminal window and remain logged in robs.mountain.lbto.org to keep the TMS software running. If you close your terminal window and/or logout of robs.mountain.lbto.org, then the TMS software running in the terminal will be terminated. See the next section for how to run the software in detached mode so you can close your terminal window and logout.

Reusing a Previous TMS Reference Position

If you have run TMS software previously and would like to start your current session based on a previous reference position, you can also do so (although in a slightly cumbersome way). First of all, you will need to identify the reference position you want to use. This is typically the last reference position on one of your previous TMS runs. When you identify the date, you will then go to your TMS data collection on that night (typically =/home/telescope/TMS_logs/yyymmdd/ and find these files:
  • Reference position files for left side (SX):
    • telescope_left_tmsoffset.dat
    • tms_sx_ref.dat
  • Reference position files for right side (DX):
    • telescope_right_tmsoffset.dat
    • tms_dx_ref.dat

The files tms_*_ref.dat are the references leg lengths used by tms.py, and the files telescope+*_tmsoffset.dat are the reference pose positions used by lbc_tms.py . (Note that these files are user specific in name and/or permissions.)

There are basically two reference position files for each TMS side. When you find them, copy them to the /tmp directory on robs.mountain.lbto.org. And then when you start your TMS session, remember that you DO NOT need to run the reference step anymore (e.g., step 4 from the guidelines above). Then everything else is just the same as before. Of course, you can also reuse the reference position just for one side. To do so, just copy the files for the side you want to /tmp, and then remember to skip the reference step for the side you want the ref position to be reused. E.g., if you want to reuse the SX side ref position, then copy telescope_left_tmsoffset.dat and tms_sx_ref.dat from the date of your choice to /tmp. And then run the reference step for the DX side only (e.g., lbc_set_tms_offset.py -s 1).

Additional flags for engineering tests

We've added (20220610) more command line flags to lbc_tms.py to disable various checks for testing purposes. Not every check has a flag yet, but we are moving in that direction.
  • Corrections will be sent regardless of extrafocal position. -x
  • Corrections will be sent regardless of LBC Shutter state. -o
  • Corrections will be sent regardless of elevation on-source. -e
  • Don't care which instrument is authorized. -a
  • Don't send any corrections (passive mode) -p

These flags can also be appended to the tms_loop.pl command. e.g. tms_loop.pl -s 0 -o to use left side only and ignore LBC shutter.

  • Also tms_loop.pl --mcp both to enable channel drop correction for both sides
  • or --mcp sx and --mcp dx for single side

Running in Detached Loop Mode

If you are running in any of the loop modes, then sometimes you may run the TMS software for long time, and you may wish to close your terminal window and logout of the machine robs.mountain.lbto.org and come back later when it is time to stop the program and collect data. By default the steps given in the previous section runs the TMS software attached to the lauching terminal window. There are various ways you can use to detach the TMS process from the terminal window. If you have a preferred way to do that, then use your own way (for example, you can use the "screen" utility). Otherwise, here we will give a method that uses the "nohup" utility.

The "nohup" utility is a standard UNIX and POSIX to ignore the hangup signal, thereby allowing you to essentially detach your program from its terminal window. "nohup" stands for no hang up. To launch the TMS loop with "nohup," replace step 5 in the previous section with this command:
nohup ./[mode_script] > [path]/[screen] 2>&1 &
The [mode_script] is the name of the TMS script given previously; the [path] part is a standard UNIX path name, the [screen] part is a file name you wish to use to store the screen output from the TMS program. By default "nohup" will use "nohup.out" for [screen] and will use the directory from where you launched the TMS software as [path]. We do not typically want to use the default behavior (since the "supportscripts" directory is automatically synced to github) and therefore you should specify the [path] and [screen] parts.

For example, if you want to lauch the TMS active bino mode detached and redirect the screen output to the "/tmp/screen.out" file, then you will do this in step 5:
nohup ./tms_loop.pl > /tmp/screen.out 2>&1 &

After this, you should be able to close your terminal window and logout of the machine robs.mountain.lbto.org. When you come back later to robs.mountain.lbto.org, you cannot use "Ctrl-C" to stop the TMS program since you lost the original terminal window and the TMS process became detached. Instead you will need to find out the process ID (PID) of the running TMS software and then kill it using the PID. Do the following steps:
  1. Open a terminal window and run the following command: ps -A | grep tms
  2. Depending on the result of this command: a If the command returns nothing, then the TMS software has already been terminated. You do not need to do anything. a If the command shows a single line starts with a number, then you will run the command: kill -9 [PID] to stop the TMS process, where "[PID]" is the first number you saw from the previous command (for example: kill -9 6728 where "6728" is the PID of the reported TMS process ID). a If the command shows multiple lines, then that means you have multiple TMS processes running. This normally should not occur. You can of course run the "kill" command to stop each of them. When in doubts, you can consult the software team for help.

Plots

If you run LBTplot while observing with LBC, you will see three new (in Oct 2021) plot buttons.

sxTMS and dxTMS are rather busy plots that show what TMS is doing. These only work if LBTplot is running on the same machine as TMS (usually robs), because they read log data files from /tmp/.

Things that look more like discreet points (diamonds or squares) are the (active or passive) TMS corrections (Group Rotation), and things that look more like continuous lines (many dots close together) are from PSF telemetry (Instrument Offsets, and Mode3 Pointing).

Back-F plots the backplate-faceplate temperature of the mirrors converted to a focus correction. The value of the Z4 correction is relative to the beginning of the plot. TMS uses the routine that makes this plot to apply the focus correction since the last reference was set (different than the timescale of your plot).

Collecting Data on TMS

When you are done with running the TMS software, you should copy the data files produced during the run for later analysis and study. These data files are being placed in the "/tmp" directory and therefore are not guaranteed to always be there. Since Oct 2021, this is automatically handled by the automated Daily Transfer Service.

Manual Transfer (deprecated)

Therefore you should copy the data immediately after you finish running the TMS software. There are multiple files being written to the "/tmp" directory that are TMS related. You can use the wildcard expression: "/tmp/*tms*" to move/copy all of them. After you have copied these files, you should probably delete them from the '/tmp' directory so that next time when you run the software, you will get a fresh copy of them (in case the old ones are still there). Here is an example on how to copy the data to your destination:

cp -p /tmp/*tms* /home/telescope/TMS_logs/[yyyymmdd]

In the above example, [dyyymmdd] is a subdirectory for the present UT date on the machine robs.mountain.lbto.org. If you want to copy the files to your own machine, then you need to be on the LBTO VPN, and do the following command (assuming you are running Linux or Mac OS):

scp telescope@robs.mountain.lbto.org:/tmp/*tms* [dst]

Here we use the secure copy utility (scp) to copy the files from the machine "robs.mountain.lbto.org" to your own machine (in [dst]). If you use Windows PC, then you can perhaps use a standalone scp program to do this. A good one is the PuTTY client.

Daily Data Transfer Service

Currently an automatic data transfer service is set up on the machine robs.mountain.lbto.org. The service runs each day at 8:00AM Tucson time (or 15:00 UTC). It basically tries to search for all the TMS related files in the /tmp directory. And if it finds any, it will attempt to transfer them to the location: /home/telescope/TMS_logs/d, where d is a new directory created by the transfer service. d is usually named using the current UT date (e.g., 20211015).

If for any reason, d already exists inside /home/telescope/TMS_logs, then the transfer service will attempt to look inside of it and try to figure out if there are any files inside that are equivalent to the ones in the /tmp directory. It will skip transferring these files. If for any reason, a file f in /tmp also appears in existing d directory, and that the two versions of f (the one in /tmp and the one in d) have different contents, then the transfer service will attempt to transfer f to d with a new name. The new name is typically f.v2 (however if that is taken, then it will try f.v2.v2, etc. until the name is unique inside d). This renaming transfer of f also applies to the case when f inside d is not readable to the transfer service (e.g., perhaps due to permission issues).

If for any reason, d already exists inside /home/telescope/TMS_logs, and it is entirely not accessible to the transfer service (e.g., due to permission issues), then the transfer service will attempt to transfer everything to d.v2 (likewise, if d.v2 is already taken, it will try d.v2.v2 etc. until the name is unique).

So in short, the transfer service will never attempt to overwrite any files already inside /home/telescope/TMS_logs. Also the service is a transfer service, meaning after it is done, the original files inside /tmp will be removed. This is to give the next TMS run a fresh start. If for some reason, you wish to reuse a previous TMS reference position, then you will have to manually pick the ones you like to use, and then place the necessary files back into the /tmp directory before your TMS run. Please see the section on running TMS with a previous reference position for details.

Lastly, the location /home/telescope/TMS_logs is perhaps just marginally safer than /tmp. The long term storage of any data on robs.mountain.lbto.org is not guaranteed. Therefore you should still try to back up your TMS data somewhere else whenever you have the chance.

Extracting Data

The data you collected (as described in the previous section) are in a condensed form. They may not be immediately useful to you. There is a utility program you can use to extract and reformat the data as CSV files that will be much simpler to process and analyze. The most important data files you collected will be tms_<left|right>_<timestamp>_telescope.txt (which contains the final TMS correction vectors sent or intended to be sent to the telescope) and tms_tcp.log (which contains all the information from the Etalon multiline server as well as local pose calculation related information). The extraction utility program is tms_extract.py located under the same TMS directory /lbt/lbto/supportscripts/MetrologySupport on robs.mountain.lbto.org. It will accept these two types of input files.

It is simple to use. There are two main options: '-t' for extracting "tms_tcp.log" type information; and '-c' for extracting TMS final corrections contained within "tms_<left|right>_<timestamp>_telescope.txt". And an optional option '-o' lets you specify a string to be used as the prefix for all the output files. We will give some examples how you can use it.

/lbt/lbto/supportscripts/MetrologySupport/tms_extract.py -t /path1/tms_tcp.log /path2/tms_tcp.log -o tms
/lbt/lbto/supportscripts/MetrologySupport/tms_extract.py -c tms_right_20201109_telescope.txt tms_right_20201030_telescope.txt
/lbt/lbto/supportscripts/MetrologySupport/tms_extract.py -c tms_right_20201109_telescope.txt tms_right_20201030_telescope.txt -t tms_tcp.log -o tms.test

The '-o' option is optional and it accepts an arbitrary string. If specified, the string is used as the prefix of the output files. For example if '-o tms' is given, then the output files will be named as "tms.raw", "tms.correction" and so on. If not specified, then the output file names will be automatically prefixed with 'tms.<b>-<e>' where '<b>' is the timestamp of the first record and '<e>' is the timestamp of the last record in the files given. An example of the automatically generated file name could be: "tms.20201109.200423.104043-20201110.120402.763123.raw". The auto-generated names tend to be quite long and verbose. So if you don't like them, then you should supply the '-o' option and name them yourself.

Both options '-t' and '-c' take a list of corresponding files (can be one as well). As shown you can also use either option alone. The "tms_tcp.log" files contain full timestamp with every record inside so you can actually rename the input files however you like. But the "tms_<left|right>_<timestamp>_telescope.txt" files only contain partial timestamps inside and with the rest of the timestamps encoded in their names (e.g., "tms_right_20201030_telescope.txt"). The extraction program will need both types of timestamps to properly sort the data and so do not remove the timestamps in the file name, or the utility program will complain about that and refuse to proceed. Also please do not remove the original "left" or "right" strings embedded in the file names as they indicate the side channel group that they represent. All supplied input files will be read and all valid data contained inside will be collected and sorted on the timestamps. The order of files on the command line does not matter since the program will do the sorting itself.

The '-t' option generates the following files (assuming with '-o tms' option):
  • tms.raw: the raw channel measurement length from the Etalon multiline server.
  • tms.etalon: the Etalon corrected channel length data.
  • tms.ciddor: our own corrected channel length data (with LBT weather telemetry).
  • tms.pose.sx and tms.pose.dx: the calculated pose data (i.e., x,y,z,rx,ry,rz). Depending on which TMS side you use, you may only get one of these, or both.
  • tms.stdev: the calculated standard deviation on each channel. The standard deviation is currently calculated on three most recent channel measurements at each given timestamp. The unit is in micron.
  • tms.stdev.filter: the channel filtering based on standard deviation for each vector. Basically if a channel's value is 0, then it is not filtered; if instead a channel has 1, then it is being filtered because of exceeding the standard deviation threshold. For convenience, the first data row in the file is a summation of each column (i.e., how many times each channel has been filtered by standard deviation).
  • tms.stdev.filter.sx and tms.stdev.filter.dx: these are side specific standard deviation filtering results. They only record all the pose calculation channels on each side when they are not all filtered out. Basically if all pose channels on a side are filtered out, then perhaps it is due to errors in the eTalon software, or intended large mirror movement. And when no pose channels are filtered out, then it is basically not interesting to look at them. So these files give an idea of the stability of all the pose channels. Basically the more a channel is filtered out (the first row number), then the less stable it is. You can also use these information to decide whether or not to manually disable certain channels.
  • tms.drop: the intentional exclusion of particular channels. If a channel in a vector is 0, then it is not excluded intentionally; if a channel has value 1 in its vector, then it is being dropped intentionally. For convenience the first data row in the file calculates the summation of each column (i.e., total excluded times for each channel).
  • tms.ref.sx and tms.ref.dx: these are timestamps when a reference is made. You can cross reference these timestamps in other files to find out informations on the references (e.g., reference the tms.raw file to find out the raw values and the tms.pose.sx and tms.pose.dx to find out the reference pose calculated).
  • tms.weather.lbt: the LBT weather telemetry we used.

The '-c' option generates the following files (assuming the '-o tms' prefix option given as well as that you supplied correction data from both sides):
  • tms.correction.sx and tms.correction.dx: the final TMS correction vectors computed (the ones actually sent to the telescope).
  • tms.thermalz4.sx and tms.thermalz4.dx: the thermal Z4 compensation on the primary mirrors (in mm unit).

All of these generated files are CSV style data with a timestamp followed by corresponding data items (the first line is a CSV header that explains the names of each field). If there are any data items that are not valid or present, then 'none' will be displayed in these files. Notice if a particular file is empty, then that is because there is no information related.

If you wish to do the extraction on your own machine, then you can copy the "tms_extract.py" and the "config.py" files to your own machine (and put them in the same directory). You will need a recent Python 3 environment installed to be able to run it (recommended to be at least Python 3.6). Other than the standard Python 3 environment, it does not depend on anything else.

Selecting Specific Channels in the Reference Vector

You can use the "drop" option to select certain specific channels to use in a reference vector. This effectively limit the entire TMS system to run on only these selected channels (remember the reference vectors sets the usable channels, if a normal vector has less channels than the reference vector, it will be rejected and no pose will be calculated, but if a normal vector has more channels than the reference vector, then those surplus channels will be ignored in the pose calculation).

To do so, you will need to edit the script lbc_set_tms_offset.py. Open this file and find the line (currently line 287) that looks exactly like:

#tmspy += '--drop 8:1,11:1,22:1'

First remove the starting "#" character (to uncomment the line so that it takes effect). And then change the "--drop ..." string to disable the channels you want. The part "8:1" means channel 8 will be disabled. If you have multiple channels to disable, then place additional ones there separated by a comma "," (no space in-between the components). For example, if you want to disable channel 5 and 23, then it will look like this:

tmspy += '--drop 5:1,23:1'

Remember to put back the "#" character at the start of the line if you don't want to use this feature. A safe way is to perhaps duplicate the line and make your changes in the new line:

#tmspy += '--drop 8:1,11:1,22:1'

tmspy += '--drop 5:1,23:1' # duplicate the line and make your changes, remove it when no longer needed

You can simply delete your line when you no longer want this feature. In this way, the original line is always there and always the same.

Changing the Standard Deviation Based Filtering Parameters

The current standard deviation based filtering system has been configured to use a five micron threshold, and a population of three vectors (i.e., standard deviation is computed on three successive measured vectors). Both of these can be reconfigured. To reconfigure them, you need to edit all the scripts you use (i.e., the offset script lbc_set_tms_offset.py and the loop script you use, for example, tms_loop.pl). Open them in your favorite editor and search for the following strings:

--stdevpop 3 --stdevbnd 5

The '--stdevpop 3' option controls the population size and the '--stdevbnd 5' option sets the filtering threshold (microns). Change them to a different value (a positive integer). Be careful and do not change anything else (especially the quotation marks).

Dealing with missing channels

Occasionally a TMS measurement vector will have some data missing, due to hardware failure or some other glitches. A typical TMS measurement vector is composed of (c,v) pairs, where "c" is an integer denoting a specific channel number, and "v" is a floating point number representing the measured value for the associated channel. The reference vector determines the channel set composition for all the subsequent measurements until a new reference is made. During this period of time, if any particular TMS vector does not contain any channels present in the reference vector, then it is an incomplete vector. An incomplete TMS vector can still pass all sanity checks and be useful.

For example, suppose the reference vector looks like: [(1,v1), (2,v2), (3,v3)]. Then we say the reference channel set is {1, 2, 3} since that's all the channels that the reference vector contains. Given a new vector u: [(1,u1), (2,u2), (3,u3)], we say it is a complete vector since the reference channel set is a subset of u's channel set. If u is [(0,u0), (1,u1), (2,u2), (3,u3)], then it is still a complete vector, with the pair (0,u0) being redundant (and not contributing to any calculation). If u is [(0,u0), (2,u2), (3,u3)], then it is an incomplete TMS vector with missing channels compared to the reference channel set (missing channel 1).

By default, the TMS software rejects any incomplete TMS vector, i.e., aborting the subsequent calculations once an incomplete TMS vector is detected and a new cycle is then restarted. The TMS software also has an operational mode that can reuse any valid incomplete TMS vector (a valid but incomplete vector is a TMS vector that is incomplete but nonetheless passes all other sanity checks). Here's a brief and informal description of how the pose of an incomplete but valid vector is calculated:
  • let v be an incoming vector that is valid but incomplete.
  • let u be a complete and valid vector in history that is closest in time to v.
  • let w be a vector constructed out of u with all v's missing channels removed.
  • let P(x) be the pose of any TMS vector "x", with the Jacobian matrix suitably configured for "x".
  • then the final pose for v is: P(v) - P(w) + P(u)

Here is a simple example, suppose we have:
  • a reference vector: r: [(1,r1),(2,r2),(3,r3)]
  • an incomplete vector v we just received: [(1,v1),(3,v3)] (missing channel 2).
  • we search backwards in time from v's timestamp for the first vector u that is complete: [(1,u1),(2,u2),(3,u3)]
  • then we construct a new vector w based on u matching v's channels: [(1,u1),(3,u3)]
  • finally we calculate the pose of v to be: P(v) - P(w) + P(u)

You can turn on such processing for either side or both sides. To turn them on, you need to edit all the scripts you use (e.g., the loop script you use, for example, tms_loop.pl or tms_loop_left.pl etc). Open them in your favorite editor and search for the following strings:

--mcp none

You should change the option 'none' to 'both' if you want to turn this feature on for both sides; or 'sx' to turn it on only for the SX side; or 'dx' for the DX side only.
Topic revision: r35 - 13 Jun 2022, JohnHill
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback