Simulation Output
Introduction
The Simulation output is intended to store the ship’s motion during the simulation. Data is stored in 2 tables:
- Time series table: Contains timeseries data relating to ships moving (e.g position, speed, heading).
- Static info table: Contains static data about each ship (e.g length, width, IMO number).
Format
As the number of data-points generated can be large, the simulation output is stored in Apache Arrow tables. These store data in a binary format, providing a good compromise between serialization speed and file size. The tables are named as follows:
- Time series table:
time_series.arrow. - Static info table:
ship_static.arrow.
The arrow tables are serialized to a file using Interprocess Communication (IPC). There are 2 formats of IPC:
-
IPC File Format
-
IPC Streaming Format
Tables are to be written in the IPC File Format. There exist several libraries in different programming languages (C, C++, C#, Java, JavaScript, Julia, MATLAB, Python, R, Ruby, Rust), which can write data into an IPC file.
Compression
Apache Arrow supports a range of compression formats (SNAPPY, GZIP, BROTLI, LZ4, ZSTD). However, as compression is not available for all implementations (such as JavaScript), it’s recommended not to use any compression on the Arrow Table itself, but rather apply DEFLATE compression on the zip file, if necessary.
Units
Unless otherwise specified, SI and SI-derived units shall be used.
When using degrees, absolute bearings shall be used where possible.
Versioning
The version can be specified in the table metadata.
Time series Arrow Table
The following columns have been defined. Additional columns are allowed.
| Column Name | Mapped Arrow Type | Description | required | Unit |
|---|---|---|---|---|
| id | UInt32 | An id uniquely identifies a ship. | true | |
| timeStamp1 | Timestamp (nanoseconds) | Timestamp stored in nanoseconds (“us”). Use nanoseconds to avoid casting issues. Time Zone can be omitted or be UTC+00:00. | true | us |
| lat1 | Float64 | WGS-84 latitude encoded in decimal form. | true | WGS-84 decimal degrees |
| lon1 | Float64 | WGS-84 longitude encoded in decimal form. | true | WGS-84 decimal degrees |
| sog1 | Float32 | Speed over ground in meters per second. | true | knots |
| cog1 | Float32 | Course over ground (COG) (absolute bearing). | true | Degrees |
| heading1 | Float32 | Heading of ship’s bow (absolute bearing). | true | Degrees |
| rot1 | Float32 | Rate of turn of the ship. | false | Degrees per second |
| navStatus3 | UInt8 | AIS Navigational status (1-15). | false | |
| surgeAcc4 | Float32 | Vessel Acceleration (surge motion) | false | ms-2 |
| swayAcc4 | Float32 | Vessel Acceleration (sway motion) | false | ms-2 |
| heaveAcc4 | Float32 | Vessel Acceleration (heave motion) | false | ms-2 |
| rollAcc4 | Float32 | Vessel Rotational Acceleration (roll) | false | rad/s-2 |
| pitchAcc4 | Float32 | Vessel Rotational Acceleration (pitch) | false | rad/s-2 |
| yawAcc4 | Float32 | Vessel Rotational Acceleration (yaw) | false | rad/s-2 |
1 Column names originating from ISO 19848:2024.
2 Column names defined by DNV.
3 Defined in ITU-R M.1371-5 § 3.1.
4 not yet implemented, to be considered later.
Additional fields may be added to the table. If possible, column names shall be aligned with ISO 19848:2024.
It is recommended to sort the table first by id, then timeStamp for maximum compatibility.
Static Info Arrow Table
The following columns have been defined. Additional columns are allowed.
| Column Name | Mapped Arrow Type | Used in AIS | Description | Unit |
|---|---|---|---|---|
| id | UInt32 | false | An id uniquely identifies a ship. | |
| mmsi | UInt32 | true | Maritime mobile service identity. | |
| imo | UInt32 | true | International Maritime Organization number. | |
| callsign | Utf-8 | true | Ship callsign. | |
| name | Utf-8 | true | Ship name. | |
| stationType1 | UInt8 | true | Type of AIS Station (Class A, Class B, AtoN, etc.) | |
| shipType2 | UInt8 | true | ||
| cargoType2 | UInt8 | true | ||
| width | Float32 | true | Ship width. | meters |
| length | Float32 | true | Ship length. | meters |
| draught | Float32 | true | Maximum present static draught. | meters |
| typeOfPositionFixingDevice3 | UInt8 | true | Type of electronic position fixing device. | |
| destination5 | Utf-8 | true | The current ship destination. e.g. “Oslo”. | |
| eta5 | Timestamp (nanoseconds) | true | Estimated time of arrival at the destination. | us |
| a4 | Float32 | true | Reference point for reported position and overall dimensions of ship (a). | meters |
| b4 | Float32 | true | Reference point for reported position and overall dimensions of ship (b). | meters |
| c4 | Float32 | true | Reference point for reported position and overall dimensions of ship (c). | meters |
| d4 | Float32 | true | Reference point for reported position and overall dimensions of ship (d). | meters |
| ownShip | Boolean | false | If the given ship is the own ship. |
1 Defined in ITU-R M.1371-5 § 3.21.
2 Defined in ITU-R M.1371-5 § 3.3.2.
3 Defined in ITU-R M.1371-5 § 3.3.
4 Defined in ITU-R M.1371-5 § 3.3.3.
5 Technically not time-series data but changes infrequently. Not currently a focus and hence kept as static data.
Additional fields may be added to the table. If possible, column names shall be aligned with ISO 19848:2024.