write_to_file command

Purpose

Prints a text string which may contain variables to a file.

Note

This command is supported by Aspherix GPU.

Syntax

write_to_file keyword value

Keywords	Description
string	obligatory; text string to print with variable names and/or command IDs
file	obligatory; name of the output file
id	user-assigned name for the command call
title	text to print as 1st line of the output file
write_every_time	time interval for data output units: [time]; default: write_output_timestep
terminal	available options: `yes` and `no` print / do not print the string to screen and logfile default: `no`
mode	available options: `new` and `append` overwrite / append data to outputfile if pre-existent default: `new`

Examples

write_to_file string "${dt} ${fx1} ${y1} ${z1}" title "# particle positions" file part1_pos.txt
write_to_file write_every_time 0.001 string "${dt} ${result}" terminal yes file global_data.dat mode new
write_to_file string "${myVars}" title "# output from several simulations" file cumulated_output.dat mode append
write_to_file string "id_time id_steady[1] id_steady[2] id_steady[3] id_steady[4] id_steady[5] id_steady[6]" file steadystate_output.txt

Description

Print a text to a file every time interval during a simulation run. If the write_output_timestep is set, this value is used as default time interval and can be overwritten by setting a value for the write_every_time keyword. The text, defined by the keyword string, can be used for diagnostic purposes or as a debugging tool to monitor some quantity during a run. The text string must be a single argument, so it should be enclosed in double quotes if it is more than one word. If it contains variables it must be enclosed in double quotes to ensure they are not evaluated when the input script line is read, but will instead be evaluated each time the string is printed.

The equal-style variables are commonly printed by this command. They are evaluated afresh each timestep that the print line is output and can be used to calculate formulas involving mathematical operations, particle properties, group properties, thermodynamic properties, global values calculated by a calculate command or references to other variables.

The string can also contain command IDs in the form

"id_ID1 ... id_command-IDn"

or, in case of vector quantities,

"id_command-ID[1] ... id_command-ID[N]"
"id_command-ID[1][1] ... id_command-ID[N][N]"

where the keyword id_ must always precede the command ID. In this way, the scalar and vector quantities generated by the command can be printed to file. The time can be always exported using the special entry id_time. As an example, let us consider the following snippet of Aspherix(R) input script:

residence_time_region check_every_time 0.1 add_region tracereg
write_to_file string "id_time id_residence_time_region[1] id_residence_time_region[2]" file output.txt

where the residence_time_region command computes a per-particle vector where the first component contains the residence time in the simulation domain (id_residence_time_region[1]) and the second the residence time in the region tracereg (id_residence_time_region[2]). The write_to_file command is capable to extract automatically this information from the command ID and to print them to file without the need to define intermediate variables.

The title keyword is used to specify the string that will be printed as the first line of the output file. If the title keyword is not present, then no title line will be printed. The file keyword is used to define the name of the output file. If the optional keyword id is used, a custom ID is set for the command. The command can then be referenced by other commands.

The keyword mode can be used with the value new to overwrite the output file, if it already exists. If append is used, then the text is appended to the output file, if it already exists, or created if it does not exist. If the terminal keyword is set to yes, the text is printed also to screen and logfile.

Warning

Make sure to set the mode to append if you want to use this command in a restarted simulation. new will always overwrite any existing output file.

In some cases, it may be desirable to generate the list of quantities to be printed depending on other simulation input. To do so, write the IDs of the quantities to a variable of type string, and use the following approach:

# myVals could als be generated somewhere in the input script
variable myVals string "id_time ${myVar1} ${myVar2}"
variable quote string "'"

write_to_file string ${quote}${myVals}${quote} file my_output_file.txt [...]

Additional information

None

Restrictions