-
class
GenericOutputWriter¶
GenericOutputWriter¶
-
class
GenericOutputWriter(model, name=None, add_id=True, save_first_timestep=False, save_last_timestep=True, output_dir=None, times_iter=None, verbose=False)[source]¶ Bases:
objectBase class for all new style output writers or converted old style output writers.
The derived class defines when output occurs via an iterator and what is actually produced. This base class handles the interfacing with the model loop.
At minimum, derived classes must define run_one_step for generating the actual output and must provide an iterator of output times via either the constructor or register_times_iter. Calling register_output_filepath from the derived class allows for some optional file management features.
See constructor for more details.
-
__init__(model, name=None, add_id=True, save_first_timestep=False, save_last_timestep=True, output_dir=None, times_iter=None, verbose=False)[source]¶ Base class for all new style output writers.
- Parameters
model (terrainbento ErosionModel instance) –
name (string, optional) – The name of the output writer used for identifying the writer and generating file names. Defaults to “output-writer” or “output-writer-id{id}” depending on add_id argument.
add_id (bool, optional) – Indicates whether the output writer ID number should be appended to the name using the format “-id{id}”. Useful if there are multiple output writers of the same type with non-unique names. Defaults to True.
save_first_timestep (bool, optional) – Indicates that the first output time must be at time zero regardless of whether or not the output time iterator generates zero. Defaults to False.
save_last_timestep (bool, optional) – Indicates that the last output time must be at the clock stop time regardless of whether or not the output time iterator would normally generate the stop time. Defaults to True.
output_dir (string, optional) – Directory where output files will be saved. Default value is None, which creates an ‘output’ directory in the current directory.
times_iter (iterator of floats, optional) – The user can provide an iterator of floats representing output times here instead of registering one later using register_times_iter. The user must ensure that the times implied by times_iter align with the model timesteps used by the Clock. If a timestep is skipped a warning is raised and if more than five timesteps are skipped an error is raised.
- Returns
GenericOutputWriter
- Return type
Examples
GenericOutputWriter is a base class that should not be run by itself. Please see the terrainbento tutorial for output examples.
-
advance_iter()[source]¶ Public-facing function for advancing the output times iterator.
The advancing iterator accounts for forced saving on the first/last steps and accounts for short sequences where the generated times are smaller than the previous value.
Warnings are thrown when a time between zero and the stop time is skipped and a RecursionError is thrown if too many values are skipped (default is 5 skips max).
-
delete_output_files(only_extension=None)[source]¶ Delete output files generated by this writer that have been registered. Primarily for testing cleanup.
- Parameters
only_extension (string, optional) – Specify what type of files to delete. Defaults to None, which will delete all file types generated by this writer that have been registered.
-
property
filename_prefix¶ Generate a filename prefix based on the model prefix, writer’s name, and model time. e.g. model-prefix_ow-name_time-0000000001.0
-
get_output_filepaths(only_extension=None)[source]¶ Get a list of all output files created by this writer that have been registered.
- Parameters
only_extension (string, optional) – Specify what type of files to return. Defaults to None, which will return all file types generated by this writer that have been registered.
- Returns
filepaths – List of filepath strings that match extension requirements and were registered.
- Return type
list of strings
-
property
id¶ The output writer’s unique id number.
-
is_file_registered(filepath)[source]¶ Check if an output filepath has already been registered with this writer.
- Parameters
filepath (string) – Filepath to check.
- Returns
is_registered – True means that the file is already registered. False means file is not registered yet.
- Return type
-
property
model¶ The model reference.
-
property
name¶ The output writer’s name.
-
property
next_output_time¶ Return when this object is next supposed to write output. Does NOT advance the iterator.
-
property
output_dir¶ Output directory
-
property
output_filepaths¶ Return a list of all output filepaths that have been written by this writer and registered with register_output_filepath.
-
property
prev_output_time¶ Returns the previous valid output time. Does not change after the time iterator is exhausted.
-
register_output_filepath(filepath)[source]¶ Register the filepath to a newly created file.
Does not throw any errors or warnings if the file is already registered or exists. (Should it? User could be intentionally overwriting a file.)
NOTE: Old style output writers do not have the ability to register files. Therefore file registering/management can’t be a required feature.
- Parameters
filepath (string) – Filepath to a new file that will be registered.
-
register_times_iter(times_iter)[source]¶ Function for registering an iterator of output times.
The inheriting class must call this function or provide the iterator to the constructor (which then calls this function). This function does not check the values in the iterator, but advance_iter will.
- Parameters
times_iter (iterator of floats) – An iterator of floats representing model times when the output writer should create output. The iterator values should be monotonically increasing and non-negative, but there is some flexibility in advance_iter to skip bad values.
-
