gnome ===== .. py:module:: gnome .. autoapi-nested-parse:: __init__.py for the gnome package import various names, and provides: initialize_console_log(level='debug') set up the logger to dump to console. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/gnome/array_types/index /autoapi/gnome/basic_types/index /autoapi/gnome/constants/index /autoapi/gnome/cy_gnome/index /autoapi/gnome/environment/index /autoapi/gnome/exceptions/index /autoapi/gnome/gnomeobject/index /autoapi/gnome/maps/index /autoapi/gnome/model/index /autoapi/gnome/movers/index /autoapi/gnome/multi_model_broadcast/index /autoapi/gnome/ops/index /autoapi/gnome/outputters/index /autoapi/gnome/persist/index /autoapi/gnome/scripting/index /autoapi/gnome/spill_container/index /autoapi/gnome/spills/index /autoapi/gnome/tamoc/index /autoapi/gnome/utilities/index /autoapi/gnome/weatherers/index Attributes ---------- .. autoapisummary:: gnome.here Classes ------- .. autoapisummary:: gnome.GnomeId gnome.AddLogger Functions --------- .. autoapisummary:: gnome.check_dependency_versions gnome.initialize_log gnome.initialize_console_log Package Contents ---------------- .. py:class:: GnomeId(name=None, _appearance=None, *args, **kwargs) Bases: :py:obj:`AddLogger` A class for assigning a unique ID for an object .. py:attribute:: make_default_refs :value: True .. py:attribute:: RTOL :value: 1e-05 .. py:attribute:: ATOL :value: 1e-38 .. py:attribute:: array_types .. py:property:: all_array_types Returns all the array types required by this object If this object contains or is composed of other gnome objects (Spill->Substance->Initializers for example) then override this function to ensure all array types get presented at the top level. See ``Spill`` for an example .. py:property:: id Override this method for more exotic forms of identification. :return: a unique ID assigned during construction .. py:property:: obj_type .. py:property:: name define as property in base class so all objects will have a name by default .. py:method:: gather_ref_as(src, refs) Gathers refs from single or collection of GnomeId objects. :param src: GnomeId object or collection of GnomeId :param refs: dictionary of str->list of GnomeId :returns {'ref1': [list of GnomeId], 'ref2 : [list of GnomeId], ...} .. py:method:: validate_refs(refs=['wind', 'water', 'waves']) level is the logging level to use for messages. Default is 'warning' but if called from prepare_for_model_run, we want to use error and raise exception. .. py:method:: validate() All pygnome objects should be able to validate themselves. Many py_gnome objects reference other objects like wind, water, waves. These may not be defined when object is created so they can be None at construction time; however, they should reference valid objects when running in the model. If make_default_refs is True, then object is valid because the model will set these up at runtime. To raise an exception for missing references at runtime, directly call validate_refs(level='error') 'wind', 'water', 'waves' attributes also have special meaning. An object containing this attribute references the corresponding object. Logs warnings: :returns: a tuple of length two containing: (a list of messages that were logged, isvalid bool) If any references are missing and make_default_refs is False, object is not valid .. note: validate() only logs warnings since it designed to be used to validate before running model. To log these as errors during model run, invoke validate_refs() directly. .. py:method:: new_from_dict(dict_) :classmethod: creates a new object from dictionary This is base implementation and can be over-ridden by classes using this mixin .. py:method:: to_dict(json_=None) Returns a dictionary representation of this object. Uses the schema to determine which attributes are put into the dictionary. No extra processing is done to each attribute. They are presented as is. The ``json_`` parameter is ignored in this base class. 'save' is passed in when the schema is saving the object. This allows an override of this function to do any custom stuff necessary to prepare for saving. .. py:method:: update_from_dict(dict_, refs=None) .. py:method:: update(*args, **kwargs) .. py:method:: serialize(options={}) Returns a json serialization of this object ("webapi" mode only) .. py:method:: deserialize(json_, refs=None) :classmethod: classmethod takes json structure as input, deserializes it using a colander schema then invokes the new_from_dict method to create an instance of the object described by the json schema. We also need to accept sparse json objects, in which case we will not treat them, but just send them back. .. py:method:: save(saveloc='.', refs=None, overwrite=True) Save object state as json to user specified saveloc :param saveloc: A directory, file path, open zipfile.ZipFile, or None. If a directory, it will place the zip file there, overwriting if specified. If a file path, it will write the file there as follows: If the file does not exist, it will create the zip archive there. If the saveloc is a zip file or ``zipfile.Zipfile`` object and overwrite is False, it will append there. Otherwise, it will overwrite the file if allowed. If set to None, this function will instead return an open ``zipfile.Zipfile`` object linked to a temporary file. The zip file will be named [object.name].zip if a directory is specified :param refs: dictionary of references to objects :param overwrite: If True, overwrites the file at the saveloc :returns (obj_json, saveloc, refs): ``obj_json`` is the json that is written to this object's file in the zipfile. For example if saving a Model named Model1, obj_json will contain the contents of the Model1.json in the save file. ``saveloc`` will be the string path passed in EXCEPT if None was passed in. In this case, it will be an open ``zipfile.ZipFile`` based on a temporary file. ``refs`` will be a dict containing all the objects that were saved in the save file, keyed by object id. It will also contain the reference to the object that called ``.save`` itself. .. py:method:: load(saveloc='.', filename=None, refs=None) :classmethod: Load an instance of this class from an archive or folder :param saveloc: Can be an open zipfile.ZipFile archive, a folder, or a filename. If it is an open zipfile or folder, it must contain a .json file that describes an instance of this object type. If 'filename' is not specified, it will load the first instance of this object discovered. If a filename, it must be a zip archive or a json file describing an object of this type. :param filename: If saveloc is an open zipfile or folder, this indicates the name of the file to be loaded. If saveloc is a filename, this parameter is ignored. :param refs: A dictionary of id -> object instances that will be used to complete references, if available. .. py:class:: AddLogger(*args, **kwargs) Bases: :py:obj:`object` Mixin for including a logger .. py:property:: logger define attribute '_log'. If it doesn't exist, define it here. This is so we don't have to add it to all PyGnome classes - this property makes the logger available to each object. - default log_level is INFO .. py:data:: here :value: None .. py:function:: check_dependency_versions() Checks the versions of the following libraries: These are checked, as they are maintained by NOAA ERD, so may be installed from source, rather than managed by conda, etc. :: gridded oillibrary nucos py_gd adios_db If the version is not at least as current as what's defined here a warning is displayed .. py:function:: initialize_log(config, logfile=None) helper function to initialize a log - done by the application using PyGnome config can be a file containing json or it can be a Python dict :param config: logging configuration as a json file or config dict it needs to be in the dict config format used by ``logging.dictConfig``: https://docs.python.org/2/library/logging.config.html#logging-config-dictschema :param logfile=None: optional name of file to log to .. py:function:: initialize_console_log(level='debug') Initializes the logger to simply log everything to the console (stdout) Likely what you want for scripting use :param level='debug': the level you want your log to show. options are, in order of importance: "debug", "info", "warning", "error", "critical" You will only get the logging messages at or above the level you set.