Merge branch 'develop'

conda_requirements.txt

@@ -2,15 +2,18 @@
 #  this covers py_gnome and the oil_library
 #  This should be the minimal conda install
 #  install with:
-#  conda install --file conda_requirements.txt
+#    conda install --file conda_requirements.txt
+#
+#  or create an environmemnt:
+#    conda create -n gnome --file conda_requirements.txt
 # These packages would all be in one of the following channels:
 # defaults
 # conda-forge
 # NOAA-ORR-ERD
 
 python=2.7.*
 setuptools>=23.0
-numpy=1.13.*
+numpy>=1.13.*
 scipy>=0.18.*
 gsw=3.0.3
 psutil>=4.3
@@ -20,22 +23,27 @@ six>=1.10
 geojson>=1.3
 repoze.lru>=0.6
 colander>=1.2
-sqlalchemy>=0.7.6
-zope.interface>=4.1
-zope.sqlalchemy>=0.7.6
-gdal=2.1.3
-netCDF4=1.3.1
-awesome-slugify>=1.6
+
+tblib>=1.3.*  # needed for child process exception handling.
+
+gdal=2.*
+netCDF4 # it should find one compatible with gdal
+awesome-slugify>=1.6.5
 regex>=2014.12
 unidecode>=0.04.19
 pyshp=1.2.10
 gridded=0.0.9
 
 # NOAA maintained packages
-unit_conversion=2.5.*
+unit_conversion=2.6.*
 cell_tree2d>=0.3.*
 py_gd=0.1.* # libgd should get brought in automatically
 
+# needed for OilLibrary
+SQLAlchemy>=1.0.13
+zope.sqlalchemy>=0.7.7
+zope.interface>=4.1
+
 # required for building
 cython=0.24.*
 

py_gnome/documentation/conf.py

@@ -32,7 +32,8 @@
               'sphinx.ext.coverage',
 #              'sphinx.ext.imgmath',
               'sphinx.ext.mathjax',
-              'sphinx.ext.viewcode'
+              'sphinx.ext.viewcode',
+              'sphinx.ext.autosectionlabel',
               ]
 
 # to make autodoc include __init__:

py_gnome/documentation/scripting/outputters.rst

@@ -89,11 +89,54 @@ KMZ Output
 
 To save particle information into a KMZ file that can be read by Google Earth (and other applications), we use the KMZ outputter::
 
+    from gnome.outputters import KMZOutput
     model.outputters += KMZOutput('gnome_results.kmz',
                                   output_timestep=timedelta(hours=6))
 
 The KMZ contains a kml file with layers for each output timestep, unceratain and certain elements, ans beached and floating elements, along with icons to render the elements.
 
 See :class:`gnome.outputters.KMZOutput` for the full documentation
 
+Shapefile Output
+----------------
+
+Weathering Data Output
+----------------------
+
+Bulk oil budget properties (e.g. percent of total oil volume evaporated) are computed and stored in addition to the individual particle 
+data. These data are available through a specialized Outputter named WeatheringOutput. To save this information to a file::
+
+    from gnome.outputters import WeatheringOutput
+    model.outputters += WeatheringOutput('MyOutputDir')
+    
+Alternatively, if you want to view specific weathering information during the model run::
+
+    from gnome.outputters import WeatheringOutput
+    model.outputters += WeatheringOutput()
+    
+    for step in model:
+        print "Percent evaporated is:"
+        print step['WeatheringOutput']['evaporated']/step['WeatheringOutput']['amount_released'] * 100
+
+
+Note: if you are running the model with a conservative or non-weathering substance, this will result in an 
+error as the WeatheringOutput will not contain any evaporation data. Depending on how you have set
+up your model (spill substance, weatherers), WeatheringOutput may contain any or all of:
+
+ * amount_released
+ * avg_density
+ * avg_viscosity
+ * beached
+ * dissolution
+ * evaporated
+ * floating
+ * natural_dispersion
+ * non_weathering
+ * off_maps
+ * sedimentation
+ * time_stamp
+ * water_content
+
+
+
 

py_gnome/documentation/scripting/scripting_intro.rst

@@ -72,14 +72,41 @@ be the same as those specified when we created the map object. The default is to
     renderer = Renderer(output_timestep=timedelta(hours=6),map_BB=((-145,48), (-145,49), (-143,49), (-143,48)))
                         
     model.outputters += renderer
+    
+Step through the model and view data
+------------------------------------
 
-Run the model
--------------
-The model can be run by stepping through individual timesteps (e.g. if we want to see results along the way) or we
-can do a full run::
+Once the model is all set up, we are ready to run the simulation. Sometimes we want to do this iteratively step-by-step to view data 
+along the way without outputting to a file. There are some helper utilities to extract data associated with the particles. This data 
+includes properties such as mass, age, and position; or weathering information such as the mass of oil evaporated (if the simulation has 
+specified an oil type rather than a conservative substance as in this example).
+
+For example, if we want to extract the particle positions as a function of time, we can use the :func:`gnome.model.get_spill_property`
+convenience function, as shown below::
+    
+    x=[]
+    y=[]
+    for step in model:
+        positions = model.get_spill_property('positions')
+        x.append(positions[:,0])
+        y.append(positions[:,1])
+        
+To see a list of properties associated with particles use::
+
+    model.list_spill_properties()
+    
+Note, this list may increase after the first time step as arrays are initialized.
+
+Run the model to completion
+---------------------------
+Alternatively, to just run the model for the entire duration use::
 
     model.full_run()
+    
+Results will be written to files based on the outputters added to the model.
 
+
+
 View the results
 ----------------
 The renderer that we added generated png images every 6 hours. Since we did not specify an output directory for these images, 

py_gnome/documentation/scripting/weatherers.rst

@@ -74,4 +74,27 @@ explicitly required but is needed by the Waves object. Adding on to our example
     waves = Waves(wind)
     water = Water(temperature=300.0, salinity=35.0) #temperature in Kelvin, salinity in psu
     model.weatherers += Evaporation(wind=wind,water=water)
-    model.weatherers += NaturalDispersion()
+    model.weatherers += NaturalDispersion
+    
+    
+Dissolution
+-----------
+
+Emulsification
+--------------
+
+Biodegradation
+--------------
+
+Viewing Bulk Weathering Data
+----------------------------
+
+Since the total oil volume spilled is divided among multiple particles, bulk oil budget properties
+(e.g. percent of oil volume evaporated) are computed and stored in addition to the individual particle 
+data. These data are available through a specialized Outputter named WeatheringOutput, 
+see :ref:`Weathering Data Output`
+
+
+
+
+

py_gnome/gnome/__init__.py

@@ -1,6 +1,5 @@
 """
-__init__.py for the gnome package
-
+    __init__.py for the gnome package
 """
 from itertools import chain
 
@@ -18,7 +17,7 @@
 # from gnomeobject import init_obj_log
 
 # using a PEP 404 compliant version name
-__version__ = '0.6.0'
+__version__ = '0.6.1'
 
 
 # a few imports so that the basic stuff is there
@@ -35,78 +34,32 @@ def check_dependency_versions():
     a warning is displayed
     """
     libs = [('gridded', '0.0.9'),
-            ('oil_library', '1.0.6'),
-            ('unit_conversion', '2.5.5')]
+            ('oil_library', '1.0.7'),
+            ('unit_conversion', '2.6.0')]
 
     for name, version in libs:
         # import the lib:
         try:
             module = importlib.import_module(name)
         except ImportError:
-            print ("ERROR: The {} package, version >= {} needs to be installed".
-                   format(name, version))
+            print ('ERROR: The {} package, version >= {} needs to be installed'
+                   .format(name, version))
             sys.exit(1)
         if module.__version__ < version:
-            w = ('Version {0} of {1} package is reported, but actual version in module is {2}'.
-                 format(version, name, module.__version__))
+            w = ('Version {0} of {1} package is reported, '
+                 'but actual version in module is {2}'
+                 .format(version, name, module.__version__))
             warnings.warn(w)
 
 
-# ## maybe too complex that required...
-# def check_dependency_versions():
-#     '''
-#     Checks the versions of the following libraries:
-#         gridded
-#         oillibrary
-#         unit_conversion
-#     If the version is not at least as current as what's in the conda_requirements file,
-#     a warning is displayed
-#     '''
-#     def get_version(package):
-#         package = package.lower()
-#         return next((p.version for p in pkg_resources.working_set
-#                      if p.project_name.lower() == package), "No match")
-
-#     libs = [('gridded', '>=', '0.0.9'),
-#             ('oil-library', '>=', '1.0.6'),
-#             ('unit-conversion', '>=', '2.5.5')]
-# #     condafiledir = os.path.relpath(__file__).split(__file__.split('\\')[-3])[0]
-# #     condafile = os.path.join(condafiledir, 'conda_requirements.txt')
-# #     with open(condafile, 'r') as conda_reqs:
-# #         for line in conda_reqs.readlines():
-#     for req in libs:
-#         criteria = None
-#         req_name, cmp_str, reqd_ver = req
-#         if '>' in cmp_str:
-#             criteria = (lambda a, b: a >= b) if '=' in cmp_str else (lambda a, b: a > b)
-#         elif '<' in cmp_str:
-#             criteria = (lambda a, b: a <= b) if '=' in cmp_str else (lambda a, b: a < b)
-#         else:
-#             criteria = (lambda a, b: a == b)
-#         inst_ver = get_version(req_name)
-
-#         try:
-#             module_ver = importlib.import_module(req_name.replace('-', '_')).__version__
-#         except ImportError:
-#             print "ERROR: The {} package, version {} {} needs to be installed".format(*req)
-#             sys.exit(1)
-
-#         if not criteria(inst_ver, reqd_ver):
-#             if criteria(module_ver, reqd_ver):
-#                 w = 'Version {0} of {1} package is reported, but actual version in module is {2}'.format(inst_ver, req_name, module_ver)
-#                 warnings.warn(w)
-#             else:
-#                 w = 'Version {0} of {1} package is installed in environment, {2}{3} required'.format(inst_ver, req_name, cmp_str, reqd_ver)
-#                 warnings.warn(w)
-
-
 def 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``:
+                   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
@@ -159,12 +112,12 @@ def _valid_units(unit_name):
 # we have a sort of chicken-egg situation here.  The above functions need
 # to be defined before we can import these modules.
 check_dependency_versions()
+
 from . import (map,
-                environment,
-                model,
-#                 multi_model_broadcast,
-                spill_container,
-                spill,
-                movers,
-                outputters
-)
+               environment,
+               model,
+               # multi_model_broadcast,
+               spill_container,
+               spill,
+               movers,
+               outputters)

py_gnome/gnome/basic_types.py

@@ -16,6 +16,14 @@
 # pull everything from the cython code
 from cy_gnome.cy_basic_types import *
 
+
+# in lib_gnome, the coordinate systems used (r-theta, uv, etc)
+# are called ts_format, which is not a very descriptive name.
+# the word 'format' can mean a lot of different things depending on
+# what we are talking about.  So we try to be a bit more specific here.
+coord_systems = ts_format
+
+
 # Here we customize what a numpy 'long' type is....
 # We do this because numpy does different things with a long
 # that can mismatch what Cython does with the numpy ctypes.
@@ -58,7 +66,7 @@
 # Define enums that are independent of C++ here so we
 # don't have to recompile code
 
-wind_datasource = enum(undefined=0, file=1, manual=2, nws=3, buoy=4)
+wind_datasources = enum(undefined=0, file=1, manual=2, nws=3, buoy=4)
 
 # Define an enum for weathering status. The numpy array will contain np.uint8
 # datatype. Can still define 2 more flags as 2**6, 2**7

py_gnome/gnome/cy_gnome/cy_basic_types.pyx

@@ -14,7 +14,6 @@ def enum(**enums):
            x.a = 1, x.b = 2, x.c = 3
            x._attr = ['a','b','c'], x._int = [ 1, 2, 3]
 
-    Just found a clever way to do enums in python
     - Returns a new type called Enum whose attributes are given by the input
       in 'enums'
     - also append two more attributes called:
@@ -29,6 +28,7 @@ def enum(**enums):
 
     return type('Enum', (), enums)
 
+
 """
 LE Status as an enum type
 """