Cycle: Realtime Cycle Averaging

Note: this document does not refer to the latest version of the Cycle language. Please refer to Cycle V2.0 for the latest documentation.

Contents

    0: Introduction
    1: Definitions
       1.1: Triggers
       1.2: Regions
       1.3: Averages
       1.4: Rate
       1.5: Discard
    2: Implementations
    3: Invocation

0: Introduction

Cycle is a little language useful for performing calculations relative to instrument operating cycles. Its primary function is to average data over specified regions. Regions are defined relative to specific Triggers, and Triggers can be defined based on any data available in the data stream.

Cycle is implemented as a preprocessor for TMC. It has a fairly small command set, but any non-Cycle commands are passed through to the output file. This allows arbitrarily complex TMC or C operations to be performed using the averages calculated by Cycle.

1: Definitions

A Cycle program contains definitions for Triggers, Regions and Averages. A Rate must also be specified. The usable products are TMC variables which represent averages of specific input values over the specified regions.

1.1: Triggers

To define a Region, we must first specify a Trigger. The Trigger will define a reference point in time against which the limits of the Regions will be measured.

A Trigger is specified by name and with a "start condition" and an options "prestart condition": 

        Trigger <NAME>
        Start <CONDITION>
        Prestart <CONDITION>
The <CONDITION>s are any TMC logical expression. If no Prestart condition is specified, the logical negation of the Start condition is used. The Trigger becomes valid after the Prestart condition is met (evaluates to be true) when the Start condition is met. For example, in the definition: 
        Trigger CycleA
        Start (DStt0 & 4) != 0
in order for Trigger CycleA to become valid, first the condition !((DStt0 & 4) != 0) must be met, then the condition (DStt0 & 4) != 0 must be met.

1.2: Regions

Once a Trigger is defined, we can define a Region. Regions are defined relative to the most recently defined Trigger. They are specified with a name and two times: 
        Region <REGION_NAME> <SECONDS> <SECONDS>
The two <SECONDS> represent the time after the Trigger of the start and end of the region, respectively. These must both be non-negative real numbers measured in seconds. (SNAFU allows regions to be defined prior to the trigger, but realtime constraints make this extremely difficult here.) For example: 
        Region FG 0.25 1.625
Defines a Region named "FG" beginning 0.25 seconds after the Trigger and ending 1.625 seconds after the Trigger. For reasons that will become apparent shortly, Region names are best kept short.

1.3: Averages

Now that we have a Region defined, we can specify what to average over that region: 
        Average <REGION_NAME> <var> [ <var> ... ]
For each variable specified, an average is calculated for every occurance within the specified Region. The result is stored in a new variable named by combining the variable's name with the Region's name. For example: 
        Average FG DetA DetB
will average DetA and DetB over the Region FG and define outputs DetA_FG and DetB_FG which represent the respective averages over that region.

By default, averaging will be performed on unconverted data. There are two ways to change this. The first is to explicitly specify which variables should be converted before averaging: 

        Average FG DetA convert(DetB)
In this case DetA will be averaged as raw data and DetB will be converted before being averaged. The derived average for convert(DetB) is designated as DetB_cvt_FG in order to distinguish it from a raw average.

The other approach is to simply specify that all averages should use converted data using the convert_on keyword. In this case, the _cvt suffix is not used and DetB_FG represents the average of converted data. It is possible to switch between these two modes by alternately specifying convert_on and convert_off.

1.4: Rate

One additional detail is required in a Cycle program; you must specify the rate at which the region limits will be tested. This is usually the rate of your highest-rate data. (I wish TMC had an automatic way to determine this, but it doesn't at this time -N). 
        Rate <rate>
For example: 
        Rate 8 Hz

1.4: Discard

It is sometimes convenient to throw out certain data values prior to averaging. This can be done using the syntax: 
        Discard <var> [ <var> ... ] unless <condition>
Another approach may be introduced soon.

2: Implementations

Once all your definitions are in place, you can begin writing expressions using the derived averages. One approach is to simply define the averages in a .cyc file, then reference them in other files. Alternatively, you can carry out your entire calculation within the .cyc file, producing a single composite output such as mixing ratio. Either way, you could reference the resulting values in other files to either display, extract or even make algorithmic decisions.

One very useful feature is that multiple Regions can be defined with the same name relative to different Triggers. This would be used, for example, when an instrument has different cycle lengths which can be determined by a status value at the beginning of the cycle: 

        Trigger Long
        Start (DStt0 & 1) && SolSW == 1
        Region FG 0.25 7.75
        Region BG 8.25 15.75

        Trigger Short
        Start (DStt0 & 1) && SolSW == 2
        Region FG 0.25 3.75
        Region BG 4.25 7.75

        Average FG DetA DetB
        Average BG DetA DetB

        TM typdef double Diff_t;
        Diff_t DiffA, DiffB;
        
        { DiffA = DetA_FG - DetA_BG;
          validate DiffA; }
        { DiffB = DetB_FG - DetB_BG;
          validate DiffB; }
In this example, the difference of the foreground and background averages are calculated for both the short cycle and the long cycle.

3: Invocation

Within the ARP/DAS/appgen environment, Cycle program files have names ending in ".cyc". appgen handles the invocation of the Cycle preprocessor automatically. This is certainly the recommended method of invocation.

Return to Manuals Guide

last updated: Fri May 7 15:14:06 2004 webmaster@huarp.harvard.edu
Copyright 2004 by the President and Fellows of Harvard College