TSV Files (Time Series)

The TSV format for time series in VICUS Districts: where TSV files are used (building demand, ground temperature, results) and how the format is structured (tab, header, units)

Overview

TSV (Tab-Separated Values) is the simple text format that VICUS Districts uses to exchange time series. It serves both as an input format – for example to read a building demand or a ground temperature from a file – and as an output format for simulation results. A TSV file is plain text and can be opened and edited in any text editor as well as in any spreadsheet application (Excel, LibreOffice).

Where TSV files are used

As input (referencing a time series from a file):

  • Building demand from file – the heating, cooling or domestic hot water demand of a consumer as a time series (see Building demands, mode Custom time series from file).
  • Heat exchange with the ground or the surroundings – a temperature time series from a file (see Heat exchange types).
  • Schedules and set-point time series of plants – e.g. prescribed supply temperatures of an energy plant.

These files are read only at simulation time. Changes to the file therefore take effect without re-importing the time series – only the file path is stored in the project.

As output (results):

  • Simulation results in text format – one file per result quantity following the pattern <network name>.<quantity>.tsv. TSV is the text-based alternative to the more compact binary format .btf; you choose between them when defining the outputs.
  • Exporting tables and charts – chart data of the line charts, the bill of materials and the result summary can be saved as TSV.

Structure of the format

A TSV file is organized as a table:

  • Separator: a tab between the columns (hence the name).
  • Header line: the first line contains a name and the unit in square brackets for each column, e.g. Time [h] or Qdot [W].
  • First column = time axis: monotonically increasing time values. The permitted time units are [s], [h] and [d].
  • Further columns = data: each with its own unit in the header. The units are converted automatically to the internally required unit on reading (e.g. [W] ↔ [kW]).
  • Decimal separator: a period (.), not a comma.
  • Empty rows are skipped.

Example of a demand file with a time and a power column:

Time [h]	HeatingDemand [W]
0	6717.01
1	5563.95
2	5396.58

Selecting a column

If a file contains several data columns, choose the desired one under Select the column in the data file when referencing it. Name and unit of each column are shown; columns with an unknown unit are grayed out and cannot be selected. A small preview displays the chosen time series as a chart, so you can check the file and column before the simulation.

Interpolation and repetition

Between the data points the values are interpolated linearly. If the time series covers a shorter period than the simulation, it is repeated cyclically – a daily or annual profile thus continues automatically.

File path and placeholders

The path to the TSV file can be given relative to the project using placeholders such as ${Project Directory}. This keeps the project portable and lets the file travel with a project package.

Practical tip:

The easiest way to create a demand file is in a spreadsheet and save it as Text (tab-separated). Watch out for two details that otherwise break the import: a period as the decimal separator instead of a comma (in a German-locale Excel you may need to adjust the regional setting or use find-and-replace) and the unit in square brackets in every header cell. For custom time series from values, the Copy header for import button provides the correctly formatted header ready to use.

Stay up to date

New features, tutorials and updates delivered to your inbox.