SAVE_ITEM

SAVE_ITEM defines scalar and 3D vector fields for which MESHFREE generates and writes graphical post-processing output files (ENSIGHT6, ERFHDF5, and other supported visualization formats configured via SAVE_format). It controls which physical or derived quantities are available for visualization in external tools and can be used both inside and outside begin_save{ environments. SAVE_ITEM does not affect restart data or monitor output. For monitor quantities written to separate files, see SAVE_MONITOR_ITEM and SAVE_BE_MONITOR_ITEM. For available output formats and options, see SAVE_format.

Syntax

Scalar items: Vector items: The arguments ScalarExpression, xVectorExpression, yVectorExpression, and zVectorExpression are defined as regular RightHandSideExpression.

Description and Usage

By default, SAVE_ITEM statements are defined in the global section of USER_common_variables.dat and are then available to all save environments (i.e., all configured graphical output formats). MESHFREE evaluates the specified expressions at each save step and writes them to the corresponding output files. Alternatively, SAVE_ITEM can be placed inside a begin_save{ block; in this case, the SAVE_ITEM is local to that particular save environment and is written only to the corresponding output. A global SAVE_ITEM is written to all save environments unless %ChooseSaveEnvironment% is used to restrict it to a subset of explicitly named environments. The %ChooseSaveEnvironment% option is intended only for SAVE_ITEM defined in the global scope (outside any begin_save{ block). For SAVE_ITEM inside begin_save{ environments, the save environment is defined by the surrounding block and %ChooseSaveEnvironment% must not be used. Using %ChooseSaveEnvironment% inside a begin_save{ environment is not supported and may lead to undefined behavior during MESHFREE execution. Uniqueness of description texts Each description text used in SAVE_ITEM ("ScalarDescriptionText" or "VectorDescriptionText") must be unique within each output data set. In this context, an output data set is defined by a particular save environment together with its active SAVE_format, SAVE_path and SAVE_file settings; all items that are written to the same output data set must therefore have distinct description texts. Description texts may be reused in different save environments if these environments write to different output data sets. For each output data set, all SAVE_ITEM that contribute to this output (including globally defined SAVE_ITEM that are active there implicitly or via %ChooseSaveEnvironment%) must together provide unique description texts. MESHFREE enforces this requirement; if a description text occurs more than once for a given output data set (for example due to overlapping global and environment-local SAVE_ITEM, or due to multiple global SAVE_ITEM with the same text), the configuration is considered invalid and MESHFREE terminates with an error that reports the conflicting definitions. Selecting save environments for global SAVE_ITEM To restrict a globally defined SAVE_ITEM to certain save environments, append the %ChooseSaveEnvironment% keyword followed by one or more save-environment acronyms: The acronyms $save_env_1$, $save_env_2$, ... must refer to save environments that are actually defined via begin_save{ blocks. MESHFREE currently supports up to 10 save environments / output formats. If an acronym expands to an index outside the allowed range of save environments (e.g. larger than the maximum number of supported save environments), MESHFREE terminates immediately with an error. If an acronym does not match any defined save environment (i.e., the acronym is not defined at all), it is ignored. If all acronyms given to %ChooseSaveEnvironment% are ignored (i.e., none of them matches a defined save environment and no out-of-range error occurred), the corresponding SAVE_ITEM is not written to any output and MESHFREE issues a warning in this case. Passing arbitrary or manually constructed values instead of valid save-environment acronyms is not supported and may lead to undefined behavior during MESHFREE execution. Notes and limitations

• Trailing ASCII control characters of the description texts (for example trailing line breaks or other control characters at the end of "ScalarDescriptionText" or "VectorDescriptionText") are truncated when writing the output.
• Description texts must be unique for each effective output (see "Uniqueness of description texts"). Input files that cause duplicate description texts within a single output are no longer supported and now cause an error during input processing.
• The %ChooseSaveEnvironment% option is only intended for SAVE_ITEM defined in the global scope. For SAVE_ITEM inside begin_save{ environments, the save environment is defined by the surrounding block and %ChooseSaveEnvironment% must not be used.
• The %ChooseSaveEnvironment% option is currently defined only for SAVE_ITEM and SAVE_BE_ITEM. Other SAVE-related constructs do not support this option at the moment. For boundary-element output, SAVE_BE_ITEM uses the same syntax to restrict items to specific save environments; see SAVE_BE_ITEM for details.

Examples