BinarySearch
Statement Step in Step Configuration Wizard
A BinarySearch statement uses a loop variable to search over a continuous interval by selecting the middle element in the interval, thus progressively closing in on a sought value. For every pass, a user-defined condition is evaluated, the interval is reduced and, depending on whether the search condition is met or not, the lower or upper interval is selected as the current interval for the next pass. When the search condition is met, the loop variable value corresponding to the current pass is stored.
When the values interval becomes smaller than a user-defined resolution value, the BinarySearch operation completes executing the current iteration and then ends.
The BinarySearch statement can be configured to return the loop variable Best value (the loop variable that corresponds to the last pass when the condition was met) or the Last value (the loop variable that corresponds to the pass when the domain value was reduced below the resolution value, causing the command execution to complete).
Given an IxExplorer session that sends traffic to a network device, let us assume that we want to run a test across a frameRate values interval and determine the first frameRate value that generates a non-zero frameLoss value.
In such a case we could use a BinarySearch step that uses a frameRate loop variable within the given domain as min and max values and the Best option configured as step return value.
Inside the BinarySearch step, we would then use GetStat statements for retrieving the frameLoss value into a fL variable and configure the step's associated condition to test for a zero fL value.To add a BinarySeach statement step:
While in the Script Steps pane, add a step by choosing the Actions > Add step... command. Select a BinarySearch step type, click thebutton to validate the selection, and specify the following parameters:
- Run Type: A BinarySearch step can only be executed sequentially (Sequential).
- Delay: A delay specifying by how much step start is delayed. A delay value is automatically set when the step is added using the Capture functionality.
- Timeout: A period of time after which the step execution is considered to have timed out.
- Ignore step: When this option is selected, the step is skipped at execution time. Selecting this option is equivalent to right-clicking a step in the Script Steps table and choosing the Exclude command from the context menu that appears.
- Description: An optional step description can be associated with a step.
Click Next.
Define the Conditional Execution settings as explained below.Conditional Execution settings enable you to define the system conditions a script step execution is monitored for. When such a predefined condition occurs a step error or a step timeout an user-defined procedure is executed and an additional action is performed. For example, on encountering a step error, you could enforce the execution of a cleanup procedure and then terminate the script.
To monitor the step for a predefined Timeout or Error condition, select the corresponding condition, then define the associated procedure local or shared (external) by clicking the
control of the Procedure field and selecting a procedure from the the drop-down pane that appears.
For the selected procedure you can view its defined arguments by clicking the
control of the Input Arguments field, which displays a cascading table-format pane containing the argument list. To specify the actual runtime argument(s) enter the desired values in the Current Value field(s).
Configure an additional action by clicking into additional actions column and selecting either of the following options:
- Continue: After performing the specified procedure, the script execution continues.
- Exit Test: After performing the specified procedure, the script execution is terminated.
Click Next.
Whenever the step execution is monitored for predefined events, an
icon is displayed in the step's corresponding Events selected column entry. For information on turning on the displaying of the Events selected column refer to Customizing the Script Steps Table Layout.
Define the looping parameters as follows:
- Assign to variable: The loop variable, whose current value for each pass is computed using the following formula:
loop_var = loop_var +/- (max min) * backoff
- Exit value of loop index: The loop variable value at loop exit time, which can be configured as either of the following:
- Best: The loop variable value that corresponds to the last pass when the search condition was met (the search condition evaluated to `true').
- Last: The loop variable value that corresponds to the last executed pass, which corresponds to the pass when the domain value was reduced below the resolution value.
- Initial value: The initial value assigned to the loop variable.
- Minimum value, Maximum value:The minimum and maximum domain value respectively. These values get updated for every pass of the binary search operation.
- Resolution: When the difference between the minimum and maximum values falls below the resolution value, the search operation ends.
- Backoff: This is a measure of the interval convergence and has the following implications on the binary search operation behavior:
For backoff values higher than 0.5, the current loop variable value is more to the right, with the effect that the search operation converges more rapidly to the right of the interval.
For backoff values lower than 0.5, the current loop variable value is more to the left of the interval.
For a typical binary search operation, this value is 0.5.
In the Expression Builder GUI define the looping condition by double-clicking in turn the desired Tcl commands and operators, and TestComposer variables. For detailed information on using the Expression Builder and creating Tcl expressions refer to Using the Composer Expression Builder.Click Next.
Verify the step summary information and revert to a previous configuration step if needed. Click Finish.The BinarySearch and SearchCondition statements are added to the steps list. For compound control statements, such as this, the closing pair EndBinarySearch statement is also added.
Example:
BinarySeach frameRate in (10 100 100 0.1)
Configure FrameRateSet ports="1.1.1" streamno="1"
rate="$frameRate" rateMode=streamRateModePercentRate
Transmit Start ports=1.1.1""
fL Get Stat ports="1.1.2" stats=frameLoss
SearchCondition $fL == 0
EndBinarySearchA single BinarySearch statement can be run on multiple chassis ports at once, in which case each of the Maximum, Minimum, Initial, Resolution, and Back-off parameters needs defined as a numeric list of values, one per port.
The sample command below illustrates the case of the BinarySearch statement that is run on 2 ports:
BinarySearch frameRate in ({100 70} {0 0} {100 70}
{0.1 0.2} {0.5 0.5})
...
SearchCondition "[expr $fL1 == 0] [expr $fL2 == 0]"
EndBinarySearch
When running the BinarySearch command on multiple ports, the following behavior applies:
All lists must have the same number of parameters.
The command returns a list of values which can be assigned to a simple TestComposer variable.
The search continues as long as any of the search intervals is larger than its corresponding resolution value. The search completes when all search intervals have been reduced below their corresponding resolution values.