Writing sequences - ad3ller/oskar GitHub Wiki

Building sequence files to perform experiments.


Editor.vi

simple sequence writing

The editor provides an easy way to read/ write json files containing sequences (.jsq). Each sequence contains an array, every element of which is a cluster that, in the simplest case, contains a comment field and the VAR_array, e.g.

VAR array:

Name Value
VAR1 10
VAR2 20
VAR3?OPT1 78
VAR3?OPT2 65

Comment:

a useful comment

To execute this sequence line would require 3 VAR vi's to be running and listening for VAR1, VAR2, and VAR3. The VAR3 vi would have to be able to interpret the options OPT1 and OPT2. Every element of the seq must be written by hand, therefore Editor.vi is only really useful for writing very simple seqs, or for editing/ viewing existing .osq files.

Modder.vi

advanced sequence writing

Modder.vi is designed to write a series of instructions for the sequencer, based on all possible permutations of n different variables each with m different values. The program works by performing a string replace on place-holder TAGs written into a template sequence, with values from each row of the permutations array.

oskar

To write a sequence, first create a template on the Sequence tab. The first column should contain the actual names of any VARs which are to be distributed by the sequencer, and the second column should contain the temporary TAG(s) or constant values. The TAG can be any string, so long as it is unique within the XML version of the template sequence. For example, run Modder.vi and create the template SEQ:

Name Value
FOO bar

Now navigate to the Permutations tab. Fill in a line of the Build Arrays list, setting the field TAG to bar. All values you wish to replace bar in the template can be manually entered into the Values array, or alternatively, you can populate this array automatically using the function f(x).

For example, set f(x) to x+1; Steps to 3; change the Format string to integer (%d), then press Build Array. Notice that the Permutations table now contains 1, 2 and 3 in the first column. Even if you automatically populate the Values array, you can manually add/ remove/ randomise elements afterwards. Press Make. This will fill the Output Seqs array on the Sequence tab, with each element having the template TAG replaced by a value from the permutations array.

The power of Modder.vi is evident when using more than one TAG. To see this, create another TAG and watch how the permutations table populates. Reorder lets you randomly order the individual arrays used to make the permutations, or alternatively the final permutation array. This can be useful to scramble any effect of drift with your experiment, which might be misleading if the variables follow a linear series. Keep track of how many permutations exist using the sizes indicator; be aware this will increase very quickly as new TAGs are created!

oskar

It is not necessary to have a TAG for every VAR as you can write other VARs into the template sequence with their values set to constants. Also, TAGS can be shared between any number of VARs and can appear as a function if encased between $math and $. e.g.

Name Value
ALPHA bar
BETA $math bar * 2$

For the example above, Make will replace the value for BETA with double that assigned to ALPHA. This can be used to automatically change two variables in a correlated way.

Once a satisfactory output sequence has been made, it can be saved to a sequence file that can be read by the sequencer.


Warning - avoid very short TAGs (e.g. `x') as these are unlikely to be unique within the template XML. A simple system that modifies the name of the VAR it will be used with can be helpful, e.g.

Name Value
HV XHV

Nb. Scan.vi is a simplified version of Modder.vi, which works with just a single variable for 1-dimensional scans.

Inject.vi, Append.vi, and Combine.vi

Adding lines to sequences

Modder.vi offers a very powerful way to build sequences but it is only capable of producing rectangular permutations of the TAGs given it. Sometimes it is convenient to make an occasional measurement with a certain set of values, e.g., to periodically measure a background during a scan. This cannot be done with Modder.vi directly, however, Inject.vi can be used instead to add lines to .osq files at specified positions.

Load a sequence by pressing the file button on the Open path control. This will populate the SEQs array. Next, write the line you want to inject into this array in the Injection field and fill in the Positions array with the indexes for where you wish the lines to go. Now press Inject. Scroll through SEQs to check it worked. Save as a new .osq file (or overwrite the original).

To concatenate one sequence onto the back of another use Append.vi, which is operated in a similar manner to Inject.vi. Use Open to load files into the left-hand SEQ. Pressing `Append' copies the lines in the left-side SEQs to the right, or appends them to those already there. Repeat as many times as needed to build your sequence.

For more advanced options with merging multiple sequences use Combine.vi. This vi takes a list of sequence files and joins together the lines from each, with the option of repeating the individual files within the output sequence. With shuffle enabled all of the lines are randomised before the output is saved.

Filter.vi

Removing lines from sequences

Filter.vi provides another way to adjust the permutations generated by Modder.vi, by dropping lines according to simple logic functions.

For instance, if you want to vary the bias applied to two electrodes (E1, E2) you can simply use Modder.vi to create a sequence file using two TAGs varied over the desired ranges. This will generate a 2d array of EVERY possible combination of voltages, however, some of the permutations may not be useful, e.g., if E1 one must always be higher than E2 for electrons to reach a detector. In this case, load the full .osq built by Modder.vi into Filter.vi and apply a filter that retains only the useful permutations, e.g., where E1 > E2, then save the output as a new sequence file.

Review.vi

Inspect the distribution of VAR values

Review.vi allows you to plot the values of VARs saved in a sequence file. It shows the parameter space that your sequence will cover during a measurement.

Load a file and select the name of the VAR that you wish to study. This will plot the VAR's values within the sequence line-by-line, but also ordered. The program will also display the max and min values, the number of unique values, and the average interval.

oskar