:py:mod:`gnome.outputters.outputter` ==================================== .. py:module:: gnome.outputters.outputter .. autoapi-nested-parse:: outputters.py module to define classes for GNOME output: - base class - saving to netcdf - saving to other formats ? Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: gnome.outputters.outputter.Outputter gnome.outputters.outputter.OutputterFilenameMixin .. py:class:: Outputter(cache=None, on=True, output_timestep=None, output_zero_step=True, output_last_step=True, output_single_step=False, output_start_time=None, output_dir=None, surface_conc=None, *args, **kwargs) Bases: :py:obj:`gnome.gnomeobject.GnomeId` Base class for all outputters Since this outputter doesn't do anything, it'll never be used as part of a gnome model. As such, it should never need to be serialized Sets attributes for outputters, like output_timestep, cache, etc. :param cache: sets the cache object from which to read data. The model will automatically set this parameter. :param output_timestep=None: If ``None`` output will be written every model time step. If set, then output is written every output_timestep starting from the model start time. If the output_timestep is less than the model timestep, an Warning will be raised at runtime. :type output_timestep: timedelta object :param output_zero_step=True: If True then output for initial step (showing initial release conditions) is written regardless of ``output_timestep`` or ``output_single_step`` :type output_zero_step: bool :param output_last_step=True: If True then output for final step is written regardless of ``output_timestep`` or ``output_single_step``. This is potentially an extra output, if not aligned with ``output_timestep``. :type output_last_step: bool :param output_single_step=False: If ``True`` then output is written for only one step, the output_start_time, regardless of ``output_timestep``. ``output_zero_step`` and ``output_last_step`` are still respected, set these to False if you want only one time step. :type output_single_step: boolean :param output_start_time=None: Time to start outputting restults. If None it is set to the model start time :type output_start_time: datetime object :param output_dir=None: Directory to dump output in, if it needs to do this. :type output_dir: PathLike :param surface_conc=None: Compute surface concentration Any non-empty string will compute (and output) the surface concentration. The contents of the string determine the algorithm used. "kde" is currently the only available option. :type surface_conc: str or None .. py:property:: output_timestep .. py:property:: middle_of_run .. py:attribute:: _schema .. py:attribute:: _surf_conc_computed :value: False .. py:method:: prepare_for_model_run(model_start_time=None, spills=None, model_time_step=None, map=None, **kwargs) This method gets called by the model at the beginning of a new run. Do what you need to do to prepare. :param model_start_time: (Required) start time of the model run. NetCDF time units calculated with respect to this time. :type model_start_time: datetime.datetime object :param spills: (Required) model.spills object (SpillContainerPair) :type spills: gnome.spill_container.SpillContainerPair object :param model_time_step: time step of the model -- used to set timespans for some outputters :type model_time_step: float seconds Optional argument - in case cache needs to be updated :param cache=None: Sets the cache object to be used for the data. If None, it will use the one already set up. :type cache: As defined in cache module (gnome.utilities.cache). Currently only ElementCache is defined/used. also added ``**kwargs`` since a derived class like NetCDFOutput could require additional variables. .. note:: base class doesn't use model_start_time or spills, but multiple outputters need spills and netcdf needs model_start_time, so just set them here .. py:method:: prepare_for_model_step(time_step, model_time) This method gets called by the model at the beginning of each time step Do what you need to do to prepare for a new model step base class method checks to see if data for model_time should be output Set self._write_step flag to true if:: model_time < self._dt_since_lastoutput <= model_time + time_step It also updates the _dt_since_lastoutput internal variable if the data from this step will be written to output :param time_step: time step in seconds :param model_time: current model time as datetime object .. note:: The write_output() method will be called after the Model calls model_step_is_done(). Let's set the _write_step flag here and update the _dt_since_lastoutput variable .. py:method:: model_step_is_done() This method gets called by the model when after everything else is done in a time step. Put any code need for clean-up, etc. The write_output method is called by Model after all processing. .. py:method:: post_model_run() Override this method if a derived class needs to perform any actions after a model run is complete (StopIteration triggered) .. py:method:: write_output(step_num, islast_step=False) called by the model at the end of each time step This is the last operation after model_step_is_done() :param step_num: the model step number you want rendered. :type step_num: int :param islast_step: default is False. Flag that indicates that step_num is last step. If 'output_last_step' is True then this is written out :type islast_step: bool .. py:method:: clean_output_files() Cleans out the output dir This should be implemented by subclasses that dump files. Each outputter type dumps different types of files, and this should only clear out those. See the OutputterFilenameMixin for a simple example. .. py:method:: rewind() Called by model.rewind() Reset variables set during prepare_for_model_run() to init conditions Make sure all child classes call parent rewind() first! .. py:method:: write_output_post_run(*, model_start_time, model_time_step, num_time_steps, **kwargs) If the model has already been run and the data is cached, then use this function to write output. In this case, num_time_steps is known so pass it into this function. :param model_start_time: (Required) start time of the model run. NetCDF time units calculated with respect to this time. :type model_start_time: datetime.datetime object :param num_time_steps: (Required) total number of time steps for the run. Currently this is known and fixed. :type num_time_steps: int Optional argument - depending on the outputter, the following may be required. For instance, the 'spills' are required by NetCDFOutput, GeoJson, but not Renderer in prepare_for_model_run(). The ``**kwargs`` here are those required by prepare_for_model_run() for an outputter :param cache=None: Sets the cache object to be used for the data. If None, it will use the one already set up. :type cache: As defined in cache module (gnome.utilities.cache). Currently only ElementCache is defined/used. :param uncertain: is there uncertain data to write. Used by NetCDFOutput to setup attributes for uncertain data file :type uncertain: bool :param spills: SpillContainerPair object containing spill information Used by both the NetCDFOutput and by GeoJson to obtain spill_id from spill_num :type spills: This is the Model's spills attribute which refers to the SpillContainerPair object Follows the iteration in Model().step() for each step_num .. py:method:: _check_filename(filename) basic checks to make sure the filename is valid .. py:method:: _check_is_dir(filename) split this out - causes problems for shape and most outputters dont need it .. py:method:: _file_exists_error(file_) invoked by prepare_for_model_run. If file already exists, it will raise this error. Do this in prepare_for_model_run, because user may want to define the model and run it in batch mode. This will allow netcdf_outputter to be created, but the first time it tries to write this file, it will check and raise an error if file exists .. py:class:: OutputterFilenameMixin(filename, *args, **kwargs) Bases: :py:obj:`object` mixin for outputter that output to a single file .. py:property:: filename .. py:method:: clean_output_files() deletes output files that may be around called by prepare_for_model_run here in case it needs to be called from elsewhere