Rules and Logic

Rule Templates

Insight Rule Templates are designed to perform specific analytic calculations (in programming terms, think of a function). These will generate insights, and calculated Trend Logs; many will generate both. The rule template includes both a logic flow and settings. To be used, working rules need to be created that apply the specific building inputs to the analytics.

Logic Builder

A logic builder is a powerful tool that provides an interactive method of creating complex mathematical algorithms which can be used for manipulating your BAS data and presenting the data in insights, charts, reports, and dashboards. Users drag and drop different logic block functions and select the sources of data to be manipulated. The output data, which are often insights and calculated trend logs, can then be used in reports, charts, or be sent out as alerts if certain trigger points are met.

  • VERSATILE

The same logic built to produce an insight alert can be used to create charts and reports. This flexibility allows you to import a logic template from the community library, modify it to meet your requirements, and begin receiving insight alerts, viewing charts, and sending out reports. However, the choice is yours if you want to begin building your logic from scratch.

  • POWERFUL

From simple unit conversion to data normalization and aggregation and all the way to more complex mathematical calculations, our logic builder is equipped with a variety of logic blocks to keep you busy. Busy not trying to figure out ‘how’ to implement your ideas but rather ‘what’ else you can do with it.

The Logic Builder can be broken down into two levels: (1) the Logic Flow, and (2) the Logic Blocks.

  1. Logic Flow – Logic flows are visual representations of mathematical equations that allow data manipulation.
  2. Logic Block – component of a logic flow that does a small processing step, analogous to a line in programming. Some blocks are:
    • Input Block (to get data from Trend Log)
    • Multiple expression (to calculate)
    • Calculated Trend Log Block (output as Trend Log)

Actions

Dragging Logic Blocks into the canvas

This feature allows users to add a variety of Logic Blocks to their Logic Builder canvas.

Editing and Previewing a Logic Block

In order to perform either of these actions, a Logic Block must be present in the Logic Builder canvas. The edit feature allows the user to make changes to their Logic Blocks. The edit feature allows actions that range from simply changing the Logic Block’s name to completely determining its function.
The preview feature allows the user to preview the processed data currently present in their selected Logic Block.

Connecting One Block to Another

Connecting Logic Blocks together allows the user to determine the order in which the Logic Flow is carried out. A Logic Block may have an input and/or an output.

Controls

Zooming

The view can be modified by zooming in and out.

The navigator allows the user to view their entire canvas in a simplified view, and to quickly navigate through their entire canvas. This feature is especially useful when a Logic Flow becomes large, complex, and difficult to keep track of.

Select Logic Flow Feature

This feature is the ability to remove the current Logic Flow and import an already existing Logic Flow.

Settings

These configuration details are on 2 pages. Page 1 you see initially when creating/viewing/editing a template. Page 2 follows the logic flow page. Page 1

  1. Description/Method: Describes the analytics and is presented when you are choosing the template
  2. Diagnosis / Recommended Action: Appears with the Insight message to help you act on the information
  3. Message: This is the default output used for each working rule (can be customized for each working rule)
  4. Insight Type: This categorizes all the insights generated by this template.

Page 2 These control some details regarding how much data to analyze and insight triggering details.

  1. Aggregation Interval: This is rarely used, but must be set. It can be used to control the timescale to use for some aggregation blocks.
  2. Date Range: When running the rule, use this amount of data.
  3. Trigger Type: This controls when we expect an Insight to trigger based on the data output by the Trigger Block.
    • Active High: The Insight will be triggered whenever the value of the Trigger Block is non-zero.
    • Rising Edge: The Insight will trigger only as the value of the Trigger Block changes from zero to non-zero.
    • Falling Edge: The Insight will trigger only as the value of the Trigger Block changes from non-zero to zero.
    • Rising and Falling Edge: The Insight will trigger when the value of the Trigger Block changes from zero to non-zero, as well as when the value changes from non-zero to zero.
  4. Trigger Block: The block used to trigger the insight. This is triggering on the output from the block.

Working Rules

A working rule is a method to apply the analytics to your specific Trend Logs in the building.

Example

Here is an example :

  • Template: “Check if Set Point is Static”
  • Logic flow:
  • Description/Method: The rule examines a set point during occupancy hours (Occ) and determines how many times it was changed. If the weekly count is less than the threshold, an insight is generated.
  • Aggregation Interval: Monthly => not used
  • Date Range: Current Month to Date => This will calculate and recalculate all insights and CTL from the start of the month until today
  • Trigger Type: Active High => this will generate an insight every time the setpoint is static
  • Trigger Block: [TRIGGER BLOCK] 1 if count less than the threshold. Zero otherwise. => This is the name of the logic block used by the trigger type above, to determine if there is an insight generated.

Logic Blocks

Logic Blocks are the individual processing blocks of a Logic Flow. There are three types of Logic Blocks:

  • Input Blocks – Add Trend Log or Constant data as an input to a Rule
  • Function Blocks – Perform mathematical and logical operations on Logic Flow data
  • Output Blocks – Output Logic Flow data as a CTL

List of Logic Blocks

You can view details on every Logic Block from the List of Logic Blocks.

You can find the Expression Syntax used in the Logic Blocks below.

Edit

The output of the Logic Block can be configured by clicking the k_edit Edit button. The TL block has two parameters:

  • Name: used purely for identification purposes. Detailed naming of Logic Blocks throughout the Logic Rule makes it easier to follow and understand the underlying logic as well as make corrections.
    • Note that for TL inputs, the name will be visible outside of the Logic Flow, such as when viewing a Rule Template or when adding a new Rule Template. The name should be clear enough to be able to choose a Trend Log to associate with the input simply based on the names of both.
  • Trend Log: the source of information. A Trend Log from any device within the building can be linked to the logic block by searching by either name or reference and clicking on the desired option in the list.
    • Note that you can also use Calculated Trend Logs created in Kaizen’s Insights tab as input into the “Real Trend Log Data” Logic Block.

Preview

The output of the Logic Block for any date range can be previewed by clicking the k_view Preview button.

  • Date Range: Used to specify the beginning and end dates for the data being previewed
  • Aggregation Interval: This parameter is used by the TL Data block, but remains synonymous with all of the other Logic Blocks.
    • Note that nothing in the Preview menu changes the functionality of the Logic Block (both when editing the Logic Flow and in a rule).

Expression Syntax

Every Logic Block which contains the phrase “expression” is a customizable block that runs information past a user function. By changing this information, specific logic series blocks can be used to perform a multitude of tasks. This section covers the proper syntax for expressions, as well as common functions and best practices. This applies to:

  • Multiple expression
  • Filter
  • Binary Filter

The Name identifies the block according to any appropriate naming convention.

The Expression performs a user-defined mathematical expression to each data point in the data series.

The variable name in the mathematical expression depends on the series used.

Variables: a,b,c,d, etc all cases with multiple inputs and variables, the first logic series-connected corresponds to an a. For example, the first series connected to a Multiple Expression block will be represented as the character “a” in the actual expression. The order of connections can be found underneath the logic block, ranked from top to bottom.

There is a separate block for defining input constants. This is part of the Input Data Logic Block and gives you the flexibility to change the values per working rule. By using an Input Data Logic Block, motor size or voltage can be changed per working rule.

Mathematical Operators

Within the expressions, the following mathematical operators are supported:

  1. * multiplication
  2. / division
  3. ^ exponentiation
  4. % modulus (remainder: e.g. 7 % 3 = 1 as 7/3 =2 with remainder of 1)
  5. + addition
  6. – subtraction

There are multiple functions (defined below), which can be used within written expressions as well. Expressions can also be grouped using parentheses.
For example: if (inrange(x, 0, 10), x, 0) uses both if() and inrange() functions.

Math Function Expansion Effect Example
SIN(arg) Sine Calculate the sine on each element of the data series. Arg is in radians. SIN(a) where a = 1 returns 0.8414
COS(arg) Cosine Calculate the cosine on each element of the data series. Arg is in radians. COS(a) where a = 1 returns 0.5403
TAN(arg) Tangent Calculate the tangent on each element of the data series. Arg is in radians. TAN(a) where a =1 returns 1.557
ROUND(arg) Round Round each element of the data to the nearest whole number. ROUND(a) where a= 11223.3 returns 11223 or where a = 11223.5 returns 11224
CEIL(arg) Ceiling Increase each element of the data up to the next whole number. CEIL(a) where a = 11223.3 returns 11224
FLOOR(arg) Floor Decrease each element of the data down to the next whole number. FLOOR(a) where a = 11223.5 returns 11223
ABS(arg) Absolute Calculate the absolute value on each element of the data series. ABS(a) where a= -11223.4 returns 11223.4
SQRT(arg) Square Root Calculate the square root on each element of the data series. SQRT(a) where a = 4 returns 2 or where a < 0 returns “Not a number”
       
MAX(arg1, arg2) Maximum Determine the maximum of arg1 and arg2. MAX(a, b) where a=1 and b =2 returns 2
MIN(arg1,arg2) Minimum Determine the minimum of arg1 and arg2. MIN(a, b) where a=1 and b=2 returns 1

Logical Operators

There are a number of logical operations that can be used to return Boolean ‘true’ and ‘false’ values. This is useful to create conditional statements. When a function evaluates to true, it outputs a value of 1. When a function evaluates to false, it outputs a value of 0.True/False values can be passed into other logic blocks. While it’s best practice to use a 1 as true and 0 as false, please note that all values that are not 0 are evaluated as true. This includes negative values: ‘-1’ will be evaluated as true.

Logical Function Expansion Effect Example
IF(expr, arg1, arg2) If condition Returns arg1 when expr evaluates to true, otherwise returns arg2. IF( GT(a,b), 50, 100) where a =2 and b =1 returns 50 or where a =1 and b =2 returns 100
       
EQ(arg1, arg2) Equal Returns 1 when arg1 is equal to arg2 EQ(a, b) where a =11223.3 and b = 11223.3 returns 1 else returns 0
NE(arg1, arg2) Not Equal Returns 1 when arg1 is not equal to arg2 NE(a, b) where a= 11223.3 and b = 11223.4 returns 1 or where a= 11223.3 and b = 11223.3 returns 0
       
NOT(arg) Not Returns 1 when arg is false. NOT(a) where a = 0 returns 1 else returns 0
AND(arg1, arg2) And Returns 1 when (arg1* arg2) != 0 . AND(a, b) where a and/or b = 0 returns 0 or where a != 0 and b != 0 returns 1. See AND truth table below.
OR(arg1, arg2) Or Returns 1 when arg1 != 0 or arg2 != 0 OR(a,b) where a = 0 and b= 0 returns 0 or else returns 1. See OR truth table below.
       
GT(arg1, arg2) Greater Than Returns 1 when arg1 is strictly greater than arg2 GT(a, b) where a = 2 and b =1 returns 1 or where a=1 and b=2 returns 0
GTE(arg1, arg2) Greater Than or Equal to Returns 1 when arg1 is greater than or equal to arg2 GTE(a,b) where a =2 and b < = 2 returns 1
       
LT(arg1, arg2) Less Than Returns 1 when arg1 is strictly less than arg2 LT(a, b) where a = 1 and b =2 returns 1 or where a=2 and b=1 returns 0
LTE(arg1, arg2) Less Than or Equal to Returns 1 when arg1 is less than or equal to arg2 LTE(a,b) where a =2 and b > = 2 returns 1
INRANGE(arg, min, max) Within Range Returns 1 when arg lies within the inclusive range (min, max) INRANGE( a, 50, 100) where a= 75 returns 1 or where a = 25 returns 0

Best Practices

Due to the nature of logic flows, there are some techniques necessary to know to achieve a high versatility with them. If one wants to compare two different trend logs/logic series, they must be aggregated or normalized to the same interval. All data points on a logic series have a time for which they were recorded. These are called timestamps. In order to perform a mathematical expression on two data points, they must be from the same time. As recorded trend logs are not necessarily aligned, it is necessary to aggregate or normalize them.

Execution of Working Rules

Kaizen provides the capability to create logic rules for fault detection diagnostics, integrity checks, and energy analysis. Logic rules are implemented through Rule Templates an d Working Rules. These rules can be used to trigger Insights and/or generate Calculated Trend Logs (CTLs).For Insights based on Trend Logs, you will need to enter the following settings before enabling a Rule Template:

  • Aggregation Interval – This setting will only affect your insights/CTLs if the aggregate blocks within your logic flow are set up as Requests. The date range you select under “Aggregation Interval” will be used to perform specific calculations (average, sum, etc) as defined in your Aggregate Block.
  • Date Range – defines which range of data will be used when running the working rule. Within one logic flow, you can perform calculations on an hourly basis and average these results over a week. In order to get an accurate result each week, at least one week of data need to be computed. For example, if your insight is based on a monthly average, we advise that you select 2 months (last month to the current month to date) to properly perform the calculation. Depending on this period and the set-up of your logic rule, you could end up with a wrong or partial result. In the case of a weekly aggregation, the result of this aggregation will be partial if you are running the working rule on the “previous day” selection under Date Range. The weekly aggregation will be done on data only from the previous day. Moreover, if you store this result in a CTL, the weekly value will be replaced every day by a new value of the previous day.
  • First Execution (or after modification): all the working rules related to the rule template will be computed using the maximum date range available for the inputs. Insights older than two years will not be generated.
  • Dependency: A Calculated Trend Log could be used as an input for a working rule. If the logic flow used to compute this CTL has been changed, all the dependent working rules will be recomputed the next time using the maximum date range available. Your data will therefore always be up to date with the modifications you have made to your working rules.

Specific Case for CTL Used as Virtual Meters

While creating a virtual meter, you will now (Kaizen version 2.1.8 and above) use the accumulating functionality of the CTL block. This functionality replaces the accumulating expression block. This block will be able to handle gaps in the samples but has a known limitation, it is not able to recompute automatically the data after a CopperCube was offline for an extended period of time. This extended period of time has to be larger than the date range selected in the rule template setting for the limitation to appear. In order to update the data stored in the CTL, you can either contact the CopperTree Customer Solutions team or save the logic flow related to the rule template. This will trigger a complete recomputation of the data for all the dependent working rules.