CIF 3

Trajectory data output

The trajectory data (values of the variables as time progresses), calculated by the ode solver, can be written to a file, using the trajectory data output component.

Enable the Trajectory data option (Output: Trajectory data category) to enable writing the trajectory data to a file.

By default, the file to which to write the trajectory data, is the name of the input specification file, with .trajdata added to it. Using the Trajectory data file option (Output: Trajectory data category), a different file can be specified. The value of the option is the absolute or relative local file system path to use for the trajectory data file.

Filtering

Variable time is always included in the trajectory data file. The following additional variables (officially ‘state objects’) are included by default:

  • The state variables, which includes the discrete variables and the continuous variables.
  • The derivatives of the continuous variables. This does not include the derivative of variable time.
  • The algebraic variables.

Only variables of type bool, int (with or without ranges), or real are included.

Using the Trajectory data filters option (Output: Trajectory data category), the state objects can be filtered. The Trajectory data filters option only has effect if trajectory data output is enabled, using the Trajectory data option.

As value for the option, comma separated filters should be supplied. Each filter specifies one or more state objects. The absolute names of the objects are used. That is, for an automaton a, with a variable x, the absolute name of the variable object is a.x. If CIF 3 textual syntax keyword are used as names for events (such as plant), then they must be escaped in .cif files ($plant). For filters however, all escape characters ($) in the names are ignored. The * character can be used as wildcard, to indicate zero or more characters. If a filter doesn’t match any of the state objects of the CIF model (after filtering them for supported types etc), a warning is printed to the console. A warning is also printed if the entire state is filtered out.

By default, filters include matching state objects. Filters may however be preceded by a - character, turning them into exclusion filters, which exclude matching states objects rather than including them. Filters are processed in the order they are specified, allowing for alternating additions and removals. If a filter does not result in the addition/removal of any state objects to/from the filter result, a warning is printed to the console.

As an example, option value a.*,-a.b*,a.bc* consists of three filters: a.*, -a.b*, and a.bc*. The first filter indicates that state objects whose absolute names start with a. are to be included. The second filter indicates that from those matching state objects, the state objects whose absolute names start with a.b* are to be excluded. To that result, the third filter adds those state objects whose absolute names start with a.bc*. For instance, if a specification contains state objects time, a.a, a.b a.bb, a.bc, a.b.c, a.bc, a.bcc, and a.bcd, the result of the three filters is that the following state objects are displayed: a.a, a.bc, a.bc, a.bcc, and a.bcd.

The default option value (filter) is *.

Output

The variables are sorted alphabetically, based on their absolute names. The only exception is variable time, which is always listed first.

For variables with a boolean type, value false is represented by 0, and value true is represented by 1.

For each time transition, the trajectories of the variables are printed to the trajectory data file. The first line is a comment, and contains the names of the variables. Each of the subsequent lines contain the values of the variables for a specific value of variable time. The exact times for which the values are printed to the trajectory data file, is determined by the ODE solver integrator, and can be influenced using the integration options, as well as the fixed output step size option.

An example of a trajectory data file, for a single time transition:

# time controller.n tank.V tank.V' tank.Qi tank.Qo
0.0 0 10.0 -3.1622776601683795 0.0 3.1622776601683795
0.08763429266802605 0 9.7247959763441 -3.1184605138343664 0.0 3.1184605138343664
0.587634292668026 0 8.228065719426915 -2.868460513834366 0.0 2.868460513834366
1.087634292668026 0 6.8563354625097315 -2.618460513834366 0.0 2.618460513834366
1.587634292668026 0 5.609605205592543 -2.3684605138343646 0.0 2.3684605138343646
2.0876342926680262 0 4.487874948675351 -2.1184605138343624 0.0 2.1184605138343624
2.5876342926680262 0 3.491144691758149 -1.8684605138343569 0.0 1.8684605138343569
3.0876342926680262 0 2.619414434840913 -1.618460513834339 0.0 1.618460513834339
3.496128195593086 0 1.9999999999999958 -1.4142135623730936 0.0 1.4142135623730936

Prettifying

To make the output in the trajectory data file easier to read, the output can be prettified. If prettifying is enabled, then after the simulation ends, the trajectory data file is read, prettified, and rewritten. A fixed width is then used for each column (each variable), with a fixed column separation. After prettification, the above trajectory data file looks like this:

# time                controller.n   tank.V               tank.V'               tank.Qi   tank.Qo
0.0                   0              10.0                 -3.1622776601683795   0.0       3.1622776601683795
0.08763429266802605   0              9.7247959763441      -3.1184605138343664   0.0       3.1184605138343664
0.587634292668026     0              8.228065719426915    -2.868460513834366    0.0       2.868460513834366
1.087634292668026     0              6.8563354625097315   -2.618460513834366    0.0       2.618460513834366
1.587634292668026     0              5.609605205592543    -2.3684605138343646   0.0       2.3684605138343646
2.0876342926680262    0              4.487874948675351    -2.1184605138343624   0.0       2.1184605138343624
2.5876342926680262    0              3.491144691758149    -1.8684605138343569   0.0       1.8684605138343569
3.0876342926680262    0              2.619414434840913    -1.618460513834339    0.0       1.618460513834339
3.496128195593086     0              1.9999999999999958   -1.4142135623730936   0.0       1.4142135623730936

By default, the trajectory data output is prettified using a column separation of three spaces. This can be changed using the Trajectory data separation amount option (Output: Trajectory data category). Using this option, prettification can be disabled, or a different number of spaces can be used between the columns.

Undo/reset

It is possible to go back in time, by undoing one or more transitions, or by resetting the simulation. However, once a time transition is taken, trajectory data is written to the output file. The simulator does not remove data for time points that are then suddenly in the future. If simulation continues after the undo or reset, new data may be written at the end of the trajectory, for the same time points that were already present earlier in the data file. As such, the data contained in the trajectory data file, may no longer be useful after an undo or reset, if simulation continues afterwards.