# Historian

## Introduction

Built into SysCAD is a historian that records time-stamped values for any variable specified by the user. The primary use of the SysCAD historian is in the Trend Window. The main method of adding tags to be recorded in the SysCAD historian is through the Trend Window.

The historian data is stored in a binary file. The historian performs data compression on incoming data to optimise disk space usage and data access speed. Values in the historian are recorded in SI units. Once data is stored in the historian, it will remain there until the historian file is deleted. If SysCAD Marshal is used, the tags listed in the driver slot configuration file may be recorded.

The time stamp for data in the historian will be the SysCAD simulation date and time. The SysCAD Time does not equal the real present time. The zero reference point for SysCAD Simulation time is 0:00:00.0 hours on 1/1/1970 and this is the initial value for a new project. For a dynamic project the time stamp associated with data (trends) is meaningful, however for a steady state project time is incremented by one second for every iteration (the historian time stamp values are meaningless). In steady state projects historian trends of data for tags represent changes in values as the project converges for a single solve and changes in values between different scenario runs.

Notes:

1. We recommend using the Archive Reporter to obtain historical data from a Dynamic SysCAD project, rather than generating Historian reports. The Archiver has significantly greater functionality for flexible and accurate reporting. For example user may specify time intervals, change variables, totalisers, etc when using the Archive Reporter. The Archiver efficiently generates the report tables while the dynamic model is running.
2. The user must specify which tags will be sent to the Historian - it does not automatically record all of the tags in a project.
3. For a dynamic model the user can provide a list of tags that should be recorded in the historian in a text file on Dynamic page for Solver Settings.

## Setting up

The historian parameters are set in the Project Settings dialog box. It can be obtained by selecting the Edit - Project Settings - historian tab page:

 On: Historian on or off. This must be on for tag values to be recorded. Name: The name xxx of the historian (maximum 8 characters) used as a file name. Two files xxx.hed (historian description) and xxx.cat (historian catalogue) will be created in the project folder to manage the historian. Size: Historical data is saved in binary data files, the size of these files may be set. The size must be a multiple of 64K. Force value count: The number set here determines when tag values must be stored in the historian. The count refers to number of iterations. Once the maximum number of iteration have be completed, values will be saved to the historian file regardless of when they were last changed or the current data compression algorithm. Estimated number of slots: You may place the maximum number of historian tags/slots you expect to record. This is used to help optimise historian performance. Scenario name: The name xxx of the current scenario (maximum 8 characters). This is the first part of the filename used for storing historical data. The binary data files are numbered as they are created xxx.001, xxx.002, ... xxx.009, xxx.00a, xxx.00b, ... xxx.00z, xxx.010, etc. The current version of SysCAD does not support multiple scenarios, but it is envisioned that scenarios may be changed at will to view different result sets. No. of historian files (or blocks): The number of files that are allowed in the data folder before action is taken on the oldest file. The action taken depends on the Permanent historian option. If this is not checked then the oldest binary data file is deleted. Data Folder: This is the folder where the binary data files xxx.001 must be saved. The default is in the project folder. Permanent historian: Check this option to activate archiving of binary data files. If a permanent history is required (ie want to archive or catalogue binary data files) then instead of deleting the oldest file, an attempt to move them to the specified catalogue folder is made. The success or failure of this operation is shown in the message window. This situation occurs when the number of files exceeds that specified by 'No. of historian files' field. Catalogue Folder: This is used as an archive (or catalogue) folder. An example being removable optical drive. No. of extra files (or blocks): When a permanent historian is switched on, a number greater then zero is required in this field. This is the number of files above that specified in the 'No. of historian files' field that are allowed to exist in the data folder. If more files than the sum of these two fields exist, the oldest are deleted. This provides a buffer for SysCAD to move files to the specified catalogue drive and/or folder. Moves fail when media is not in the drive specified, there is insufficient disk space or the file that needs to be moved is currently being accessed by a historian query. Ensure a reasonable number is specified so that sufficient time is given to take action such as preparing disk space on the catalogue drive/folder. Use Tolerance Tick box: Generally, the historian records when it detects a change of value in the variable. The tolerance boxes will allow the user to specify how often the historian must record data, thus filtering out small changes and only record when a significant change is made.

## Restart or Delete Historian

Two commonly used buttons on the Historian tab page of Project Settings are Restart and Delete:

• Restart button: This will delete all the historical tag values but will retain the list of tags that are recorded in the data historian.
• Delete button: This will delete all the historical tag values AND it will delete the list of tags that are recorded in the data historian.

The historian can be set to restart automatically every time a project is started after a full stop. This option is on the Start Options tab of the Project Solver Settings window - see Solver Set up for Dynamic Projects.

## Accessing historical data

The historian data can be accessed in four ways:

You may browse up and down the recorded history. See the section on Excel Trend Reports for more details.
You can request data to be returned to a file by entering a number of parameters in the Query Dialog Box, which generates a request to the historian.
3. Excel Report:
You can obtain historical information in an Excel spreadsheet using the Automation reporting functionality. See the section on Excel Trend Reports for more details.
4. Dynamic Data Exchange:
Using a DDE client such as a spreadsheet package, you can access SysCAD historical data. See the section on Data Sharing for more information.

Historical SysCAD data can be accessed across a network. All the user needs to do is ensure that the SysCAD server is running correctly with a configured historian. See the section on Data Sharing.

## Filtering

Filtering is especially useful in a Real Time SysCAD project. Each iteration the current tag value is placed through the historian filter for that tag. As a tag value has to be filtered EVERY iteration, do not use filtering lightly, it does use processing time. Un-filtered tags are only passed to the historian when their values change. Two filters are currently available; they may be applied singularly or together (cascaded).

### Window Filter

This filter is applied first. Its result is a type of moving average. The user may set the length of the window, the number of points, where each point is an iteration. Every iteration SysCAD discards the oldest point and adds the current value (or new value if one arrives) to the end. SysCAD then calculates the average value. The maximum length or count for a window filter is 100.

### First Order Filter

This filter is applied second. Its function is to apply a first order decay to a step change. You may enter three parameters, the Period (P), Tau ($\tau$) and Delta ($\delta$).

A value Alpha ($\alpha$) is calculated:

if P > 0 and $\tau \ge$ P then $\alpha = \frac {P} {\tau}$ Else $\alpha = 1$

Each iteration, if $\alpha \lt 1$, the current value (X) may be altered using the previous value (Y) as follows:

if $\left | X - Y \right | \lt \delta$ then $X = \alpha X + (1-\alpha) \times Y$

## Data Compression

Data compression is especially useful but not essential in a Real Time SysCAD project. Each time a value changes (or every iteration if the tag is filtered), the SysCAD historian will decide whether to record the value or ignore the change based on the data compression algorithm chosen. Data compression is applied after filtering using the adjusted filtered value (if there was any filtering). The effect of the data compression is to ignore small insignificant changes in values recorded, and only record major changes in the trend. Two data compression algorithms are currently available.

### Boxcar Algorithm

This algorithm has one parameter, Delta. After each change in a tag's value, a time-weighted average is calculated. If the difference between this average and the previous stored value is greater than Delta then that time-weighted average is recorded in the historian. Each time a value is recorded the current time weighted average is cleared.

This algorithm is the same as the Boxcar algorithm but an attempt at automatically adjusting Delta to a realistic value is made. The parameters are DeltaLo, DeltaHi, NoRec, NoNotRec and Change.

A value Delta is calculated by SysCAD, this starts at a value halfway between DeltaLo and DeltaHi. Delta is adjusted up or down by the parameter Change. The value of Delta will not exceed the range set by DeltaLo and DeltaHi. If the change in a value exceeds Delta for NoRec consecutive iterations, Delta is adjusted upward by change. If the change in a value does not exceed Delta for NoNotRec iterations, Delta is adjusted downward by Change.

For example values of 3 for NoRec and 20 for NoNotRec may be used. Like the Boxcar, a time-weighted average is used.

## Changing recording parameters

Recording parameters may be altered in the Trend Window.

If the source of the tag is from SysCAD Marshal, the options must be altered in the related slot configuration file. Various selections can be made to choose a specific set of tags with common properties.

## Recording statistics

These will indicate how often a tag value is recorded and can be used to fine tune filters and data compression algorithms. Values that are recorded frequently or very seldom indicate that the boxcar delta parameters need to be changed.

This is available in the Options - General - Project tab page.

You can enter a filename to which statistics will be sent when the Fetch button is pressed. The file may be viewed in a spreadsheet. The column titles indicate what each column and statistic represents. The statistics are generated over the time specified in the No. of iterations box. Pressing the Reset button can reset this.

## Troubleshooting

Occasionally SysCAD variable tags would change upon new version release. These tags would normally be changed during project upgrade. If one of these old tags were used by the historian, you may get a warning message in the message window such as

 Historian Tag 'xxxxx.xxxxx' should be changed to 'xxxxx.yyyyy'


These tags can often be found on the Trend page if they are being used.

• If the tag cannot be found, and you would like to remove the message, then the easiest way would be to delete and restart the Historian. You will need to re-select tags to add to the historian.