From 5e6eef8b46e828f23a02c11ddc1a1da8ba37de8c Mon Sep 17 00:00:00 2001 From: Philip W Jones Date: Thu, 2 Jul 2026 10:23:06 -0700 Subject: [PATCH] adds error check to IOStream for FileFreq options When append mode is used, the FileFreq options must be supplied but an error check was missing to detect this case User documentation was also revised to note the requirement and some instructions for handling a special case. --- components/omega/doc/userGuide/IOStreams.md | 20 +++++++++++++------- components/omega/src/infra/IOStream.cpp | 9 +++++++++ 2 files changed, 22 insertions(+), 7 deletions(-) diff --git a/components/omega/doc/userGuide/IOStreams.md b/components/omega/doc/userGuide/IOStreams.md index 87318bc81f2b..8c0c396d8c3c 100644 --- a/components/omega/doc/userGuide/IOStreams.md +++ b/components/omega/doc/userGuide/IOStreams.md @@ -95,9 +95,14 @@ a template can be: if the file already exists. Acceptable options are: - Fail if you want the code to exit with an error - Replace if you want to replace the existing file with the new file - - Append if you want to append (eg multiple time slices) to the existing - file. When re-running an interval, this will also over-write existing + - Append if you want to write multiple time slices to a file. When + re-running an existing time interval, this will also over-write existing slices corresponding to the simulation time if they exist in the file. + For this option, both FileFreq and FileFreqUnits must be supplied to + determine how many frames or time slices are to be written per file. + In the special case (eg testing) where all slices are to be written + to a single file, choose a frequency option longer than the simulation + duration. - **FileFormat:** An optional field that can be used if the file has a format incompatible with the default IO format. If not supplied, the stream will use the default format. @@ -121,16 +126,17 @@ a template can be: - Hours for a frequency every Freq hours (*not* Freq times per hour) - Minutes for a frequency every Freq minutes (*not* Freq times per minute) - Seconds for a frequency every Freq seconds (*not* Freq times per seconds) -- **FileFreq:** An optional entry for including multiple time slices in a - single file (only supported for output presently) +- **FileFreq:** An entry determining the frequency of file writes when + including multiple time slices in a single file. This is only required if the + IfExists append option is used and is only supported for output presently. - **FileFreqUnits:** A field that, combined with the integer frequency, determines the frequency of new files when multiple time slices are included in a file. The file frequency must be less than or equal to the data frequency. Acceptable values include all of the frequency values listed above except the one-time values (eg OnStartup/Shutdown or AtTime). - The filename template should reflect the frequency and the time used for - the file will correspond to the template at the time the file is first - opened. + The filename template should reflect the file frequency. The time used for + the filename will correspond to the template at the time the file is first + opened (ie the beginning of the file frequency interval). - **UseStartEnd:** A required entry that is true or false and is used if the I/O is desired only within a certain time interval. An example might be for specifying high-frequency output within a certain period of a simulation. diff --git a/components/omega/src/infra/IOStream.cpp b/components/omega/src/infra/IOStream.cpp index 95e082480ae9..a30e5da3e64f 100644 --- a/components/omega/src/infra/IOStream.cpp +++ b/components/omega/src/infra/IOStream.cpp @@ -574,6 +574,15 @@ void IOStream::create(const std::string &StreamName, //< [in] name of stream "stream {} ", StreamName); } + } else { // neither FileFreq variables are found + // Make sure the file frequency variables are present for append mode + if (NewStream->ExistAction == IO::IfExists::Append) + ABORT_ERROR( + "Error creating stream {}: FileFreq and FileFreqUnits must be " + "supplied if the append option is used for IfExists \n" + "Choose a very large file frequency if all time slices are " + "to be written to a single file (eg for testing)", + StreamName); } // Create and attach alarm for file frequency if needed