gnome
¶
__init__.py for the gnome package
import various names, and provides:
initialize_console_log(level=’debug’)
set up the logger to dump to console.
Subpackages¶
gnome.cy_gnome
gnome.environment
gnome.environment.environment
gnome.environment.environment_objects
gnome.environment.grid
gnome.environment.gridcur
gnome.environment.gridded_objects_base
gnome.environment.names
gnome.environment.running_average
gnome.environment.tide
gnome.environment.timeseries_objects_base
gnome.environment.water
gnome.environment.waves
gnome.environment.wind
gnome.maps
gnome.movers
gnome.ops
gnome.outputters
gnome.outputters.animated_gif
gnome.outputters.binary
gnome.outputters.build_icons
gnome.outputters.geo_json
gnome.outputters.image
gnome.outputters.json
gnome.outputters.kmz
gnome.outputters.kmz_templates
gnome.outputters.memory_outputter
gnome.outputters.netcdf
gnome.outputters.oil_budget
gnome.outputters.outputter
gnome.outputters.renderer
gnome.outputters.shape
gnome.outputters.weathering
gnome.persist
gnome.scripting
gnome.spills
gnome.spills.sample_oils
gnome.spills.sample_oils.oil_4
gnome.spills.sample_oils.oil_6
gnome.spills.sample_oils.oil_ans_mp
gnome.spills.sample_oils.oil_bahia
gnome.spills.sample_oils.oil_benzene
gnome.spills.sample_oils.oil_crude
gnome.spills.sample_oils.oil_diesel
gnome.spills.sample_oils.oil_gas
gnome.spills.sample_oils.oil_jetfuels
gnome.spills.gnome_oil
gnome.spills.initializers
gnome.spills.le
gnome.spills.release
gnome.spills.spill
gnome.spills.substance
gnome.tamoc
gnome.utilities
gnome.utilities.file_tools
gnome.utilities.geometry
gnome.utilities.graphs
gnome.utilities.weathering
gnome.utilities.weathering.adios2
gnome.utilities.weathering.banerjee_huibers
gnome.utilities.weathering.delvigne_sweeney
gnome.utilities.weathering.ding_farmer
gnome.utilities.weathering.huibers_lehr
gnome.utilities.weathering.lee_huibers
gnome.utilities.weathering.lehr_simecek
gnome.utilities.weathering.monahan
gnome.utilities.weathering.overstreet
gnome.utilities.weathering.pierson_moskowitz
gnome.utilities.weathering.riazi
gnome.utilities.weathering.spill_area
gnome.utilities.weathering.stokes
gnome.utilities.weathering.zhao_toba
gnome.utilities.appearance
gnome.utilities.cache
gnome.utilities.colormaps
gnome.utilities.compute_fraction
gnome.utilities.convert
gnome.utilities.distributions
gnome.utilities.images2gif
gnome.utilities.inf_datetime
gnome.utilities.map_canvas
gnome.utilities.orderedcollection
gnome.utilities.plume
gnome.utilities.profiledeco
gnome.utilities.projections
gnome.utilities.rand
gnome.utilities.remote_data
gnome.utilities.save_updater
gnome.utilities.schema_decorator
gnome.utilities.serializable_demo_objects
gnome.utilities.surface_concentration
gnome.utilities.time_utils
gnome.utilities.timeseries
gnome.utilities.transforms
gnome.weatherers
Submodules¶
Package Contents¶
Classes¶
A class for assigning a unique ID for an object |
|
Mixin for including a logger |
Functions¶
Checks the versions of the following libraries: |
|
|
helper function to initialize a log - done by the application using PyGnome |
|
Initializes the logger to simply log everything to the console (stdout) |
|
convenience function to get all valid units accepted by nucos |
Attributes¶
- class gnome.GnomeId(name=None, _appearance=None, *args, **kwargs)¶
Bases:
AddLogger
A class for assigning a unique ID for an object
- 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
- property id¶
Override this method for more exotic forms of identification.
- Returns:
a unique ID assigned during construction
- property obj_type¶
- property name¶
define as property in base class so all objects will have a name by default
- property _warn_pre¶
standard text prepended to warning messages - not required for logging used by validate to prepend to message since it also returns a list of messages that were logged
- _id¶
- make_default_refs = True¶
- _name¶
- RTOL = 1e-05¶
- ATOL = 1e-38¶
- __create_new_id()¶
Override this method for more exotic forms of identification.
Used only for deep copy. Used to make a new object which is a copy of the original.
- __deepcopy__(memo)¶
The deepcopy implementation
We need this, as we don’t want the id of spill object and logger object copied, but do want everything else.
Got the method from:
Despite what that thread says for __copy__, the built-in deepcopy() ends up using recursion
- __copy__()¶
might as well have copy, too.
- 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], …}
- _attach_default_refs(ref_dict)¶
!!!IMPORTANT!!! If this object requires default references (self._req_refs exists), this function will use the name of the references as keys into a reference dictionary to get a list of satisfactory references (objects that have obj._ref_as == self._req_refs). It will then attach the first object in the reference list to that attribute on this object.
This behavior can be overridden if the object needs more specific attachment behavior than simply ‘first in line’
In addition, this function SHOULD BE EXTENDED if this object should provide default references to any contained child objects. When doing so, please be careful to respect already existing references. The reference attachment system should only act if the requested reference ‘is None’ when the function is invoked. See Model._attach_default_refs() for an example.
- 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.
- 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
- classmethod new_from_dict(dict_)¶
creates a new object from dictionary
This is base implementation and can be over-ridden by classes using this mixin
- 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.
- update_from_dict(dict_, refs=None)¶
- update(*args, **kwargs)¶
- static _attr_changed(current_value, received_value)¶
Checks if an attribute passed back in a
dict_
from client has changed. Returns True if changed, else False
- _check_type(other)¶
check basic type equality
- __eq__(other)¶
- __eq__(other)¶
Since this class is designed as a mixin with one objective being to save _state of the object, then recreate a new object with the same _state.
Defines a base implementation of __eq__ so an object before persistence can be compared with a new object created after it is persisted. It can be overridden by the class with which it is mixed.
It looks at attributes defined in self._state and checks that the values match
- It uses allclose() check for floats and numpy arrays, to avoid floating point
tolerances: set to: RTOL=1e-05, ATOL=1e-08
- Parameters:
other – another GnomeObject used for comparison in obj1 == other
NOTE: super is not used.
- _diff(other, fail_early=False)¶
Returns a list of differences between this GnomeObject and another GnomeObject
- Parameters:
other – other object to compare to.
fail_early=False – If true, it will return on the first error
- __ne__(other)¶
Return self!=value.
- serialize(options={})¶
Returns a json serialization of this object (“webapi” mode only)
- classmethod deserialize(json_, refs=None)¶
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.
- save(saveloc='.', refs=None, overwrite=True)¶
Save object state as json to user specified saveloc
- Parameters:
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 specifiedrefs – dictionary of references to objects
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 openzipfile.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.
- classmethod load(saveloc='.', filename=None, refs=None)¶
Load an instance of this class from an archive or folder
- Parameters:
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.
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.
refs – A dictionary of id -> object instances that will be used to complete references, if available.
- class gnome.AddLogger(*args, **kwargs)¶
Bases:
object
Mixin for including a logger
- 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
- property _pid¶
returns os.getpid() as a string. Since we have multiple models, each running in its own process that is managed by multi_model_broadcast module, each debug log messages starts with os.getpid(). This function just returns a string that the gnome object can append to - don’t want to keep typing this everywhere.
- _log¶
- gnome.__version__ = '1.1.7'¶
- gnome.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
- gnome.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
- Parameters:
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-dictschemalogfile=None – optional name of file to log to
- gnome.initialize_console_log(level='debug')¶
Initializes the logger to simply log everything to the console (stdout)
Likely what you want for scripting use
- Parameters:
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.
- gnome._valid_units(unit_name)¶
convenience function to get all valid units accepted by nucos