Archive Reporter

From SysCAD Documentation
Jump to navigation Jump to search

Navigation: User Guide ➔ Reports ➔ Archive Reporter

Archive Reporter Archive Editor Archive (sac) File Text Format

Related Links: Planning Example Project, Tailings Dam Example Project, Waste Handling with Batch Digestion Example Project


Introduction

The Archive Reporter is used with Dynamic projects to report data directly to a database, CSV or text file while a project is running. This has some similarities with the SysCAD Historian, however the archiver has significantly greater functionality so the use of the historian for reporting is not recommended.

The user specifies how many tables of data are required (maximum is 500), the frequency of reporting (each table may be reported at a user specified time) and the tags that are reported in each table. These settings are recorded in a text file by the Archive Editor. The maximum number of Fields (including Time Fields) in a Table is 2000 (for DB-SQLITE .db3 format) and 3000 (for csv format).

Please also note that this file is loaded (or reloaded) from the Project Settings Archive tab page, as shown in the sections below.

Archive Configuration

To use the Archiver:

  • Go to Edit - Project Settings;
  • The dialogue box shown below will be displayed;
  • Go to the Archive page and tick the 'On' box.
  • The SysCAD Archive Configuration (.sac) file will be created;
  • Click on the 'Edit' button to edit the Archive.sac file.

Project Settings-Archive.jpg

The Settings are explained in the table below:

Setting / Tick Box Description

Archive Reporter Configuration

On The user must tick this box to enable the Archive Reporter.
Name This will be the name of the Archive Reporter file. The default name is Archive.sac and it is automatically created in the project folder when the user ticks the 'On' box. Users can choose to have a different file name but only one sac file can be used per project.
Browse The user may browse for an alternative Archive file using this button.

Press the Edit button to launch the Archive Editor.

Pressing the Reload button loads the Archive.sac file into SysCAD, which will check the file and display messages in the Messages window.

System Settings

The Settings are explained in the table below:

Setting / Tick Box Description

Time Fields

Date and Time Every table will contain a column with the simulation time and date for the reported values. The format for this column will be Date:Time
Date Only Every table will contain a column with the simulation date for the reported values.
Time Only Every table will contain a column with the simulation time for the reported values.
Elapsed as HMS Every table will contain a column with the elapsed simulation time for the reported values. The format for this column will be hh:mm:ss
Elapsed Time Unless the user selects 'Off', every table will contain a column with the elapsed simulation time for the reported values. The format for this column will be a single value, and will display the total elapsed time as seconds, minutes, hours or days, depending on the user selection.

System Tables

Message Log If the user ticks this box, all simulation messages will be written to a log file in the Archive folder.
Event Log If the user ticks this box, all Events will be written to a log file in the Archive folder.
Standard Fields
These tick boxes determine what information is written to the Message Log file.
Source The source of the message will be logged.
Tag The unit tag that is source of the message will be logged.
Command All SysCAD commands will be logged, e.g. 'Stop', 'Run', etc.
Type The type of message will be logged, i.e. Error, Warning, etc.
Message Messages will be displayed. If this is not ticked, then only Errors and Warnings will be logged.
ID No The ID of the message will be logged.
Iteration The Iteration of the message will be logged.
Call No The Call number for the message will be logged.
Sequence No The Sequence number of the message will be logged.

Reporting Options

Field Option Description
On If On = 1, the table will be created. If On = 0, the table will not be created.
Name The name of the table (for DB formats) or name of the file for csv/txt file formats.
Format DB-SQLITE Data will be saved in Archive.db3 SQ Lite database in the project folder (Maximum fields per table is 2000)
DB-MSACCESS Data will be saved in Archive.mdb Microsoft Access database in the project folder
CSV Data will be saved in a CSV file (Maximum fields per table is 3000)
TXT Data will be saved in a Text (txt) file
Clear Rewind Clear archive file on next run.
False Add to existing archive file on next run. This can be overridden by other settings on the Solver Setting - Scenario page such as the RestartArchive option.

Note: Each table can only have one format but within the same archive file, different tables can have different formats

CSV and TXT File Options

If the Format chosen is CSV or TXT, then the following options are relevant.

Field Description
Path The path and folder name for storing CSV & TXT files (usually with the Project)
SigDigits The number of significant digits for the tags that are reported to CSV & TXT files. Recommendation is 16. Accepted range is 2-17.

Period and Offset

The Period and Offset for reporting can be specified. This is not required if the user specifies a Trigger, but note that both Periods and Triggers can be used for the same table.

Field Description
Period Time frequency for reporting fields, where time zero is at start.
Note 1: The period is relative to midnight, not the simulation start time.
Note 2: If the period is not divisible by 24 hours, the reporting will not be at the same time each day.
Offset Time offset within the specified period. This affects when the first set of data is recorded.
Note: The offset is relative to midnight, not the simulation start time.

Notes:

  • Use Period for reporting at fixed time intervals, OR use Triggers for reporting at irregular time intervals (ie report specified fields based on trigger logic).
  • If one or more Triggers are used, a period & offset is not relevant or required.
  • If no triggers or period are specified then the table will not accumulate data.
  • Note that period and offset are relative to midnight. If your start time is not on a reporting period relative to midnight AND you want to report relative to the start time, then you need to specify an offset to achieve this. For example, if you want to report every 24 hours and the start time is 8:00am, then the offset should be 8 hours.

Trigger Options

The user may specify one or more Triggers that will cause the values in the table to be reported. There can be any number of triggers. If the conditions of any of the triggers are met, then the fields will be reported.

The triggers are numbered and include three terms as described below, a description, a SysCAD tag and the Trigger Test.

Term Option Description
Description A description of the trigger
SysCADTag Any valid SysCAD tag. May have conversions.
TriggerTest Rise = Value The trigger will be true if the value has increased by more than the specified amount since the last recorded value. The last recorded value will either be the first value or the value when the trigger was last true.
StepRise = Value The trigger will be true if the value has increased by more than the specified amount since the last step.
Fall = Value The trigger will be true if the value has decreased by more than the specified amount since the last recorded value. The last recorded value will either be the first value or the value when the trigger was last true.
StepFall = Value The trigger will be true if the value has decreased by more than the specified amount since the last step.
Delta = Value The trigger will be true if the value has changed by more than the specified amount since the last recorded value. The last recorded value will either be the first value or the value when the trigger was last true.
StepDelta = Value The trigger will be true if the value has changed by more than the specified amount since the last step.

where = Value = Test value used to see where there are sudden changes.

Notes:

  • Use Period for reporting at fixed time intervals, OR use Triggers for reporting at irregular time intervals (ie report specified fields based on trigger logic).
  • If one or more Triggers are used, a period & offset is not relevant or required.
  • If no triggers or period are specified then the table will not accumulate data.

Field Options

The user may specify one or more fields in the table to be reported.

The fields are numbered and include five terms as described below, a field name, a SysCAD tag, a function, measure point and first point options.

Term Option Description
FieldName Report column or field name. Should not contain characters: '.,[]
SysCADTag Any valid SysCAD tag. May have conversions.
Function Current/Cur Returns the current value.
CurrentDiff/CurDiff Returns the difference between current value and the current value at the end of the previous reporting period.
Minimum/Min Returns the minimum value for the chosen period.
Maximum/Max Returns the maximum value for the chosen period.
Average/Avg Returns the average value for the chosen period.
AverageTotal/AvgTtl Returns the average value since the beginning of the run.
Sum Returns the total of the reported tag for the report period. Note: The SysCAD tag MUST be on a per second basis (eg P_1.Qm (t/s)).
SumTotal/SumTtl Returns the total of the reported tag since the beginning of the run. Note: The SysCAD tag MUST be on a per second basis (eg P_1.Qm (t/s)).
ReportTime Returns the number of seconds for the report period. This will be equal to the number of steps in the report period multiplied by the timestep. Any valid SysCAD tag can be specified.
SimulationTime Returns the number of seconds since the beginning of the run. This will be equal to the total number of steps since the beginning of the run multiplied by the timestep. Any valid SysCAD tag can be specified.
Time(operator,value,[timeunit]) Returns the amount of time in the report period that the reported tag meets the condition specified using operator and value. Valid operators are <, <=, ==, <>, >= and >. Value can be any number. Timeunit is optional (default is seconds), options are s, m, h or d.
TimeTotal(operator,value,[timeunit])
/TimeTtl(operator,value,[timeunit])
Returns the amount of time since the beginning of the run that the reported tag meets the condition specified using operator and value. Valid operators are <, <=, ==, <>, >= and >. Value can be any number. Timeunit is optional (default is seconds), options are s, m, h or d.
TimeInRange(low operator,low value,high operator,high value,[timeunit]) Returns the amount of time in the report period that the reported tag is within the range specified. Valid low operators are > and >=. Valid high operators are < and <=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
TimeInRangeTotal(low operator,low value,high operator,high value,[timeunit]) Returns the amount of time since the beginning of the run that the reported tag is within the range specified. Valid low operators are > and >=. Valid high operators are < and <=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
TimeOutRange(low operator,low value,high operator,high value,[timeunit]) Returns the amount of time in the report period that the reported tag is outside the range specified. Valid low operators are < and <=. Valid high operators are > and >=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
TimeOutRangeTotal(low operator,low value,high operator,high value,[timeunit]) Returns the amount of time since the beginning of the run that the reported tag is outside the range specified. Valid low operators are < and <=. Valid high operators are > and >=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
Count/Cnt Returns the number of recorded values for the report period. This will be equal to the number of steps in the report period. Any valid SysCAD tag can be specified.
ChangeCount/ChgCnt Returns the number of times the reported tag changed by more than 0.001 (in SI Units) during the report period.
String/Str Returns the current value of a string. Note: the SysCAD tag must be a string.
MeasurePt StartPt The value of the SysCAD tag at the beginning of a step.
EndPt The value of the SysCAD tag at the end of a step.
MidPt The value of the SysCAD tag halfway through the step.
FirstPoint IgnoreFirst Ignores the first value at the start of the run. i.e if the first value for the tank is 0 and it goes to 29 at the end of the first step, 29 will be recorded as the first value if the IgnoreFirst option is used.
UseFirst Use the first value at the start of the run.

Archive Options

To see the Archive Options dialog box, go to Tools\Archive Options.

The Archive Options dialog box shows the tables that have been created and their frequency of data recording. The following dialog box is generated using the example described above.

Archive Options.png Archive Options2.png

Example Archive Enabled Projects

A few example projects with Archive enabled are included with the standard install. These include: