Historian
Navigation: User Guide ➔ 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, providing a plot of how tags converge in a Steady State project or how tags change over time for a Dynamic project. 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.
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:
- The Historian is NOT intended as a database for "historical data" reporting purposes. It provides visual trend line reporting for user while working with a SysCAD project.
- The Archive Reporter should be used to obtain historical data for reporting for a Dynamic SysCAD project. 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.
- The user must specify which tags will be sent to the Historian - it does not automatically record all of the tags in a project.
- 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 / Data files name: |
The name xxx of the current data block files (maximum 8 characters). This is the first part of the filename used for storing historical data (in event block files). 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. |
| 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 (i.e. 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 an external USB 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. |
| 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:
- SysCAD Trend Window:
- You may browse up and down the recorded history. See the section on Excel Trend Reports for more details.
- SysCAD Historian Query:
- 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.
- 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.
Filtering
Filtering is rarely required as the Archive Reporter is now used for reporting. Before the Archiver, it was 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, only use this when required. 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 ([math]\displaystyle{ \tau }[/math]) and Delta ([math]\displaystyle{ \delta }[/math]).
A value Alpha ([math]\displaystyle{ \alpha }[/math]) is calculated:
- if P > 0 and [math]\displaystyle{ \tau \ge }[/math] P then [math]\displaystyle{ \alpha = \frac {P} {\tau} }[/math] Else [math]\displaystyle{ \alpha = 1 }[/math]
Each iteration, if [math]\displaystyle{ \alpha \lt 1 }[/math], the current value (X) may be altered using the previous value (Y) as follows:
- if [math]\displaystyle{ \left | X - Y \right | \lt \delta }[/math] then [math]\displaystyle{ X = \alpha X + (1-\alpha) \times Y }[/math]
Data Compression
Data Compression is rarely required as the Archive Reporter is now used for reporting. Before the Archiver, Data compression is 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.
Adaptive Boxcar Algorithm
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.
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.