CHANGES.txt

V3.4.0, January 2024 -- 
   . Updated the Fortran subroutine for solving the cubic roots in
     math_funcs.f95. For single-phase fluids with one real root, the original
     function was finding a false root. A new root-finding code is from the
     Public Domain Aeronautical Software (PDAS) site. The Python version of the
     equations of state, which used the root module in Scipy did not have the
     same issue. All of the original test cases still pass with the this
     function update as it only effects very specific cases close to a phase
     boundary.
   . Edited the discrete bubble model `equilibrium` method for cases where the 
     input masses included some components with zero mass. In that case, the
     equilibrium does not always converge on the correct single-phase (e.g., a
     liquid might be returned when a gas is the correct answer).  The new 
	 method removes the zero-mass components, computes the equilibrium, and then 
	 puts the zero-mass components back into the mixture with zero mass.  The 
	 original test cases all also pass with this minor stabilitiy fix.
   . Moved the unit conversions in the `chemical_properties` module out of the 
     `load_data` function and into a new `convert_units` function. Also,
     updated the names of the units to include '()': e.g., 'mm/l' --> '(mm/l)'.
   . Updated the documentation in the `chemical_properties` module for the
	 separated `comvert_units` function. Also, adjusted the unit conversion 
	 search so that all cataloged units have '()' around the main units. This 
	 allows the unit search to be complete.  Also, added a unit conversion from 
	 kPa to Pa.
   . Added some additional printed messages to the `psf` models.  When the 
     particle size exceeds the maximum stable size, the code alerts the user
     and reports the original and updated d_50 values.
V3.3.0, September 2023 --
   . Created a new method of the bent plume model `Model` class that prints the 
     mass flux of particles leaving the plume and entering the water column.
   . Added the ability for particles to save their diameter during plume
	 simulations. These are saved at the `dispersed_phases.Particle` level as
	 well as within the bent plume model `LagElement.update` method. This will 
	 help ensure during post processing that the user knows the actual sizes 
	 that were used during a simulation.
   . Added a flag `tracked` to each bent plume model `particle` that records 
     whether or not a single bubble model simulation was run for that particle.
   . Added the ability for the user to specify a pressure to the particle 
     breakup models that differs from the ambient pressure. This may happen
	 during a phase change where the pressure has to lie on the saturation 
     curve.  nBe aware that `tamoc` plume simulations will still use the 
     ambient pressure to compute particle sizes. Hence, any particles created 
     with a non-equilibriump pressure will need to be adjusted to equilibrium 
     before use in a `tamoc` plume simulation. Also added better handling of 
	 single-phase cases by the particlesize model `Model` object. 
   . Removed some of the screen printing from the particle size models.  These 
	 messages used to alert the user when a predicted particle size was larger
	 than the maximum stable particle size and the distribution was being   
	 adjusted.  The adjustment still occurs. These statements were left over 
	 from an older testing session.
   . Added a method to the stratified plume model `Model` object to report the 
     particle size distribution at any simulation output level.  Also added a 
	 method to report the intrusion fluxes at each intrusion layer.
V3.2.0, August 2023 -- 
   . Added new methods to the bent plume model `Model` class and stratified
     plume model `Model` class to save derived model output. The state space
     arrays for each of these models do not contain many of the simulation
     variables of interest (e.g., plume width, velocity, temperature,
     concentration). During simulation, these are computed by the `LagElement`
     class in the bent plume model and the `InnerPlume` and `OuterPlume`
     classes in the stratified plume model. The models previously only had
     methods to write the state-space data to files. Two new methods were added
     to each model. The `get_derived_variables` methods compute several derived
     variables of interest at each output level, organize these results into
     arrays, and return the data together with lists of strings describing the
     data in each column of the output arrays. The `save_derived_variables`
     methods get the data from the `get_derived_variables` and then write
     files, using the string lists of variables names to create annoted file
     headers. This would allow model simulation data to be manipulated easily
     outside of TAMOC or Python.
   . Updated the test files to be compatible with the `C_pen` and `C_pen_T` 
     variables that were added to the `dbm` module and the `dbm_f` / `dbm_p`
     libraries.  
V3.1.0, August 2023 -- 
   . Figured out how to suppress the numpy warning that occur due to 1.) 
     equilibrium flash calculations during the search for roots, 2.) the ODE
     solvers that are designed to stop when an intrusion forms.  These are now
     supressed globally in `__init__.py` at the top-level directory of TAMOC.
     These can be enabled by setting the global variable `DEBUG` to `True`.  
   . Updated the `BaseProfile` object of the `ambient` module to include 
     stabilization of the ambient density profile by default.  The user may 
     turn this off by passing the optional argument `stabilize_profile` as 
     `False` to the `ambient.Profile` instantiation call.
   . Moved the call to convert units in the `ambient.BaseProfile` object to 
     the top of the initialization commands.  Previously, if pressure was not
     provided, the method would try to compute pressure using the raw input
     data.  Unless this data was in meters, Kelvin, and psu, this would fail.
     Now it is possible to have user-supplied units that differ from TAMOC base
     units and still let the `ambient.BaseProfile` compute the pressure.
   . Added new tests of for the `ambient` module to make sure it is possible
     to provide non-standard units of profile data to the `BaseProfile` 
     object and still compute the correct pressure profile.
   . Updated the particle tracking using the single bubble model in the 
     `Particle` class of the bent plume model so that it does not try to track
     particles that have fully dissolved.  For particles that have dissolved, 
     the tracking algorithm will print the particle diameter (np.nan) and 
     the existing composition (which should have mass below the threshold 
     fraction for track of the initial mass).
   . Updated how TAMOC converts integers to floats to be compatible with recent
     numpy releases.  
   . Updated the `matplotlib` calls to the axis `grid` function to remove the
     outdated parameter `b`.  This used to be a boolean that would set whether
     the grid is visible or not.  Now, the grid is automatically visible always
     when the `grid` method is called.
   . Updated the bent plume model plot all variables method to correctly 
     skip far-field particles that are not tracked.
   . Added unit conversions to the `chemical_properties` module.
   . Updated the discrete bubble model (`dbm` module) to allow the user to 
     provide the Peneloux shift parameter through the chemical property 
     parameters `C_pen` and `C_pen_T`.  See equation 5.9 in Pedersen et al. 
     (2015).  These parameters are also passed to the `dbm_f` module (both 
     the Fortran and the pure-Python versions).  `C_pen` set to zero indicates
     that the original functions based on Lin and Duan (2005) should be used
     to estimate the Peneloux shift parameters.  This is the preferred method
     unless the psuedo-component property data have been strongly fitted to 
     measured data resulting in Peneloux parameters outside the normal expected
     range (e.g., `C_pen` values from -0.4 to 1.2).
   . Update the discrete bubble model to prevent dividing by zero when 
     normalizing the user-provided `delta_groups` parameter.
   . Updated the `seawater.pH` function so that the user-provided guess for
     the pH is used in the search for the true value.  The previous code 
     allowed the user to provide this input but used a hard-coded value of 
     pH = 9 in the root-finding search.
V3.0.0, January 2023 --
   . Updated the `dbm` module to include a new mixed-phase fluid particle that 
     includes gas and liquid phase in a single bubble/droplet.  The algorithm 
     follows the approach in Gros et al. (2017; 2020).  The new mixed-fluid 
     phase is invoked using fp_type = 2.  Note that for this particle type, 
     an equilibrium calculation is conducted for each call to a `dbm` module
     property method.  Equilibrium calculations can be computationally 
     expensive.  This is minimized by keeping track of the last set of 
     partition coefficients and initializing each equilibrium calculation with
     an initial guess using the previous calculation's partition coefficients.
   . Updated the multiphase-phase plume initial conditions (`dispersed_phases.
     zfe_volume_flux`) to that large discharges can be accurately handled.  In
     some cases, the Wuest et al. (1992) initial condition converges on initial
     void fractions greater than 1.  This occurs when there is inadequate 
     entrainment of ambient fluis within the zone of flow establishment to meet
     the conditions assumed by Wuest et al. (1992), namely, the dilute plume
     assumption is violated here.  This can happen for very large discharges,
     as for some spills from subsea CO2 sequestration pipelines.  In this case,
     the new method computes a new orifice diameter that can meet the criteria
     of an initial void fraction less than or equal to 1.  The result is 
     reported to the user so that they know a different orifice diameter was 
     used than was chosen.  This change did not affect previous simulations of
     subsea oil well blowouts, which has consistently reported initial void 
     fractions between 0 and 1.
   . Added a method to compute far-field intrusion layer concentration for 
     the bent plume model following solutions for wastewater outfall plumes.  
     This new method is `get_intrusion_concentration` and solves the analytical
     solution for a continuous plane source initialized with the data at the
     end of the plume simulation.  This method allows for non-uniform
     turbulent diffusivities that are fitted to the Okubo diagram.  See the 
     documentation for references.  Because this algorithm is adapted from 
     those used for wastewater outfall plumes, coastal settings are most 
     appropriate for its use.
   . Found an error in the `psf.log_normal` method in which the volume fraction
     within each bin of the size distribution was incorrectly evaluated.  
     Updated this method so that the error does not occur.  Previous versions 
     of the model would have returned a size distribution with a lower d50
     than requested by the function call.
   . Miscellaneous bug fixes and updates to make model behavior more intuitive:
     + Updated `dbm` module so that user can provide binary interaction 
       coefficient data.  Error crept in as the method to read data from the 
       model ./data/ directory was added in version 2.4.0 in which user data 
       would always be treated as zeros.
     + Updated the `dbm` module equilibrium calculation so that initial guesses
       for the partition coefficient that include np.nan values would be 
       interpreted as invalid.  This is needed with the new fp_type = 2, mixed-
       phase fluid particles that remember their previous equilibrium 
       solutions which sometimes converge on np.nan.
     + Fixed an error in the Python-only version of the `dbm_p` functions in
       which the binary interaction coefficients where computed incorrectly 
       (see line 1185 in which aTk[i] has been revised to aTk[j] to match the
       Fortran versions of this library).
     + Added several new options for variables that can be read by the 
       `chemical_properties.load_data` method.  Because some of these variable
       names may include characters from other variable names, the unit
       conversion tests were made more specific, checking for the whole unit
       name (e.g., deg F) instead of for a single character (e.g., F).  This
       removed ambiguity as to which unit conversion should be conducted, but
       also requires the user to select units that are fully included in the
       conversion database.
     + Updated the `blowout.particles` method so that the user can specify a 
       hydrate formation time other than zero (zero remains the default).  This
       gives the user more flexibility in using this method to initialize 
       particles for a TAMOC plume simulation.
     + Updated the `dbm_utilities` method to initialize oils with information
       from the new NOAA `adios_db` package.  This module retains the ability
       to interact with the NOAA `oil_library`, but that module is no longer
       supported by NOAA.  The new `adios_db` library separates data from 
       derived quantities; hence, changing the API to the property data.
     + Updated the `dispersed_phases.hydrate_formation_time` method so that a
       particle above the hydrate stability zone will be automatically 
       considered dirty (e.g., t_hyd = 0).  The previous version returned 
       t_hyd = np.inf, but this value is not handled by other TAMOC algorithms.
       If clean particles are desired, the `hydrate_formation_time` method 
       should not be used.
     + Updated the `dispersed_phases.zfe_volume_flux` method to allow more
       flexible definition of the release depth (including single-value float
       or array-like vector position data).
     + In the bent plume model, when particles are tracked outside the plume, 
       particles that remained in the intrusion layer are tracked differently
       than particles that exit due to cross-flow or trapping.  These particles
       did not previously report where they exited the plume.  New code was 
       inserted in the `simulate` method to record this information as they 
       exit the intrusion layer.
     + Updated the method names for some of the new methods to compute far-
       field concentration in the bent plume model.  The `get_intrusion_
       initial_condition` replaces the `get_intrusion_concentration` method. 
       A new `get_intrusion_concentration` method solves for the far-field
       intrusion layer concentration (see above).  
     + Added additional information to the set of returned variables for the
       `get_intrusion_initial_conditions` method, including the depth, width, 
       and height.  The width and height calculations follow Socolofsky et al. 
       (2011), which is based on Akar and Jirka (1995).  Sometimes these 
       empirical equations lead to plumes that are thicker than their width.
       The method tries to respect geometries that are consistent with the 
       bent plume model plume simulation.
     + Removed the parameter `Et` from the far-field concentration algorithms
       in the bent plume model.  Replaced this parameter with a fit to the
       Okubo diagram so that turbulent diffusivity of the spreading bubbles
       or droplets depends on diffusion time and is not strictly constant.
     + Added warning messages in the `psf` module so that when a particle 
       size calculation exceeds the maximum stable particle size and the 
       model adjusts the distribution down following the SINTEF d95 method, 
       a message is echoed to the screen.  
     + Also added messages to the `psf` module to report the maximum stable
       particle size when it is calculated.
     + Updated the Grace et al. maximum bubble size computation in the `psf`
       module with a different initial guess of the exponential growth rate
       so that the algorithm converges properly over a wider range of possible
       values.
     + Updated the test files so that they are compatible with the changes to 
       the particle size models (e.g., the updated log-normal distribution
       method and the update the Grace et al. search for the maximum stable
       bubble size).
V2.4.0, September 2022 --
   . Updated the bent_plume_model with post-processing capability to compute
     dissolved concentrations. These methods follow those used by Socolofsky
     and Gros in the NASEM Dispersants Committee Report, Appendix E.
   . Updated the ambient module to correctly initiate a Profile object from 
     xarray data. 
   . Changed the way the binary interaction coefficient data can up passed to
     the dbm module. Previous methods using user-defined data still work. The
     new method also includes loading the Privat and Jaubert coefficients from
     the data directory so that these are more easily used.
   . Added a new equation of state in the seawater module for density at very
     high temperatures. This was needed to allow simulation of submarine black
     smokers.
   . Added a new example in the ./bin/sbm directory for simulating a single CO2
     bubble rising in the ocean water column. Also added a new method in the
     seawater module to compute the pH given the dissolved inorganic carbon
     (DIC) and the temperature.
   . Other minor updates to fix typos in axis labels and fix any identified 
     bugs.
V2.3.1, July 2022 --
   . Updated the bent_plume_model module so that the Model class now includes
     several useful post-processing methods. These allow the user to compute
     several diagnostics of the model output that one may normally want to
     know. These include:
     + Model.report_psds: reports the bubble and droplet size distribution data
       (diameter and volume fraction) at requested model steps within the
       near-field plume solution or at given water depths in the Lagrangian
       particle tracking phase of model simulation.
     + Model.report_mass_fluxes: this method computes the particulate mass
       fluxes at any point along the solution trajectory for any list of
       compounds in the simulated mixture. This method does not interpolate, but
       rather reports output at actual model computed points. The user can
       obtain data from the near-field plume or the Lagrangian particle tracking
       phase of transport (if it exists). Output include the particle fluxes at
       the selected point and the difference between these fluxes and the
       initial fluxes at the start of the release.
     + Model.report_surfacing_fluxes: this method computes the mass flux
       reaching the sea surface for particles and for the plume, if it
       surfaces, and also tracks the time that each particle reaches the
       surface. This method relies on Model.report_mass_fluxes to compute the
       mass.
     + Model.plot_psds: plot the bubble and droplet size distributions within
       the near-field plume and the Lagrangian particle tracking phases of
       plume transport.
     + Model.plot_fractions_dissolved: plots the fraction of each component
       that dissolves into the ocean water column in different stages of
       transport, either the near-field plume, the far-field particle tracking,
       or the whole simulation.
     + Model.plot_mass_balance: plots the time history of the mass balance,
       tracking material in the ocean water column, on the sea surface, and
       biodegraded.
V2.3.0, April 2022 --
   . Found some new features added since switching to Python 3 that are not
     backward-compatible with Python 2. While these will not always be
     supported, these were fixed in this version so that TAMOC remains fully
     compatible with Python 2.
   . Updated all tests so that they are compatible with the current versions
     of each module.
   . Created a Python-only version of the Fortran codes so that a Fortran
     compiler is not required. This new module is dbm_p.py, and is distributed
     in the ./src directory of TAMOC. The TAMOC modules first try to import the
     compiled Fortran code (dbm_f), and if that fails, they then import this new
     module. The new module passed all the same tests as the dbm_f library as of
     this release.
V2.2.0, February 2022 --
   . Updated the ambient.py module to use xarray Datasets as the primary
     container for storing and manipulating ambient Profile data. The user
     can still initialize ambient.Profile objects from netCDF files or
     Datasets or from numpy arrays, as in past versions of TAMOC. In these
     cases, the input data are converted to xarray Datasets and stored as
     such in the Profile object. The user can also now initialize an
     ambient.Profile object directly from an xarray.Dataset.
   . Updated the ambient.Profile class to allow instantiation of an object
     with just depth, temperature, and salinity. In this case, the __init__()
     function recognizes that pressure data are missing, calculates the data,
     and adds them to the Profile object.
   . Updated the ambient.Profile class with several new functions, building
     on the abilities of xarray. These include: (a) support for multiple
     times in the profile data, though only data for one time are available
     for any given TAMOC simulation, (b) a method to compute the
     concentrations of atmospheric gases and add them to the profile dataset,
     (c) a method to compute the density and add this to the dataset, (d)
     and, new plotting methods, utilizing the xarray interface to
     matplotlib.pyplot.
   . Updated all of the examples in the ./bin/ambient directory to
     demonstrate the new capabilities of the xarray version of the ambient
     module.
   . Updated all of the tests to pass with the current version of TAMOC,
     including all tests for the new version of the ambient module.
   . Updated the tests so that they will create the ./tamoc/test/output
     directory if it does not exist so that fresh installations will not fail.
   . Redesigned the TAMOC documentation with a new template. Updated the
     documentation so that the current code docstrings are included in the
     docs.   
   . Updated some errors in the docstrings of the various modules so that
     they compiled properly with Sphinx.
   . Added a new function to the dbm_utilities module to read in property
     data as formatted for the RPS SIMAP program, then convert the data to a
     normal dbm.FluidMixture or dbm.FluidParticle object. Note that only
     relatively light pseudo-components are included so that the density
     estimation from the dbm module is not quite right.
V2.1.0, December 2021 --
   . TAMOC has been fully tested on Windows 10 using Python 3.8 under
     Miniconda environments. These instructions have been updated in the
     readme.rst documentation file.
   . Chemical property data have been updated with a few error corrections.
   . The blowout.py module has been updated with enhanced flexibility, in 
     particular, allowing simulations of pure gas-phase plumes.   
V2.0.0, March 2020 --
   . TAMOC is now updated to be fully Python 3 compatible.  Compatibility 
     with Python 2.7 is still retained.  Going forward, Python 3 functionality
     will be ensured, but compatibility with Python 2 will no longer be 
     ensured.  
   . Added a new BaseProfile object to the ambient.py module so that ambient
     Profile objects can be created without using netCDF files.  This new
     object is inherited by the original Profile object.  All previous 
     behavior is retained.  Profiles can now be created using netCDF, using
     numpy arrays, or using lists.  
   . Added the capability for an ambient.Profile object to be created without
     data.  In this case, the world-ocean average profile is used.  This data
     is distributed with TAMOC.
   . Created a new module particle_size_models.py which also uses psf.py
     for its function base.  These modules replace the sintef.py module and
     include particle size models from SINTEF, RPS ASA, and from Wang et al. 
     (for bubbles only).
   . Created a new blowout.py module which defines a new Blowout object.  
     This object facilitates much of the work needed to set up a blowout 
     simulation using the bent_plume_model.  Once the object is created, 
     simulations can be run immediately.  Model settings can also be easily
     changed and the simulations re-run.
   . Created a new module dbm_utilities.py which makes setting up discrete
     bubble models for blowout simulations much simpler.  This module is 
     particularly used by the new blowout.py module.
   . Update all of the test cases so that they should now all pass on any
     machine.  Some warnings are thrown, but these are normal parts of the 
     model and can be ignored.
   . Updated all test and ./bin examples to be compatible with Python 3 and 
     to include the new modules.
   . Updated the documentation to be up-to-date with the current version of
     the model.
V1.2.1, December 2018 --
   . Updated passing of NetCDF objects to Numpy to avoid problems with 
     masked-array compatibility.  
   . Updated the Fortran code in ./src/dbm_phys.f95 in the subroutine
     xfer_kumar_hartland() so that the Reynolds number, Schmidt number, and
     Peclet numbers are computed before they are used.
V1.2.0, December 2017 -- 
   . Added biodegradation to the fate processes in the model.  
V1.1.1, November 2017 --
   . Updated the way interp1d is used inside the ambient.get_values command
     for scalar input.  The model assumed a row vector would be created, but
     a column is returned.  In newer versions of numpy, this seems to create
     a problem.  Used .transpose() to switch column into a row.
   . Updated some of the examples in the ./bin directory so that they only 
     read data from the ./tamoc/data directory which comes with tamoc.  In 
     some of the examples, I was using data in ./test/output, but this data
     may not exist if the user has not run any of the tests yet.  
   . Updates all of the test cases to be compatible with the small changes
     in the dbm module that were included in version 1.1.0.  All test cases
V1.1.0, October 2017 --
   . Updated particles_from_mb0 in the stratified plume model to pass the
     variable t_hyd to dispersed_phases.PlumeParticle.
   . Updated the interpolation call for the inner plume in the 
     stratified_plume_model.py to account for cases where the present 
     integration step is outside the available ambient data.  This fix uses
     the built-in 'extrapolate' method, which is available in Scipy 0.17.0
     and higher.
   . Fixed an error in the documentation for the bent plume model so that 
     all examples are compatible with the present version of the code.
   . Updated dbm.py to be compatible with newer versions of Scipy.
   . Fixed an error in the test_sbm.py in which a required output file is 
     created with a double .txt extension.
   . Updated the discrete bubble model so that fp_type is always an integer
     since it is used as an index to arrays.
V1.0.0, October 2015 -- 
   . Finalized all validation cases and tested model for release as version
     1.0.0.  
V0.1.17, October 2015 --
   . Updated the K_salt values for O2, N2, and Ar with data from Weiss (1970).
   . Changed the way simulation results are saved to the netCDF format files
     so that whether or not the user provided external chemical properties 
     data and whether or not the user provided the delta_groups variable, the
     save/load commands figure out what was done and do the right things.  In
     past versions, the user had to tell the load command what the user_data
     and delta_groups variables were.  This is no longer required.
   . Updated the bent plume model save_sim and load_sim methods so that if
     the particles are tracked in the farfield, the tracking solutions are
     saved.
   . Updated the save_txt methods for all models so that they are called 
     the same way and to ensure that all data in the state space is reported
     properly in the header files.
   . Updated all ./bin examples to ensure they are compatible with the present
     model version.
   . Changed the criteria for convergence for the stratified plume model.  
     Added a check for the trap heights, peel heights, intrusion layer flux, 
     and inner plume volume flux at the base of each peeling region.  Kept
     all of the former criteria on maximum flow rates and momentum fluxes.
     Removed the criteria that the volume flux at the top of the plume should
     match between simulations; this is replaced by the volume flux checkes
     for each peel.  The new criteria seem to be consistent with previous 
     versions (i.e., equally stringent), but more stable--these criteria are
     now fixed to plume features and not fixed depths.
   . Updated the bent plume model so that currents can come from any direction
     and can change direction during a simulation.  This allows the model to 
     accept velocity profiles with three-dimensional currents.  Add the 
     currents to the ambient profile object as 'ua', 'va', and 'wa'; note 
     that z is positive down so that upwelling is a negative vertical 
     velocity.
   . Updated the test cases of the bent plume model so that the tests are 
     comprehensive.  Previous test files had a place-holder for the bent
     plume model, but without any tests.  
   . Replaced the from numpy.testing import * command with more specific 
     imports that only grab the functions used.  These commands were in the 
     test files and invoked the nosetester.py test.  The edit makes it so 
     that the nosetester.py test is no longer executed when importing from 
     numpy.testing. 
   . Updated the p_fac calculation for the bent plume model Particle object
     to give the best match with the experimental data in crossflows.
   . Updated the initial guess for the Kvsi method for the discrete bubble
     model hydrate stability calculation to work better at lower pressure.
V0.1.16, September 2015 --
   . Fixed the way the model keeps track of particles that exit the plume.  
     The solution from the previous version of the model is not changed, but
     the way the flag is handled was updated so that there will be no 
     conflicts in post-processing the solution using the LagElement.update()
     method.
   . Updated the bent plume model so that it stops at the second neutral 
     buoyancy level for a stratified case.
   . Updated the dbm.equilibrium calculation so that the method works even if
     first several elements of the mass vector has zero mass.
   . Updated the dbm.equil_MM function so that it is much faster if 
     successive_substitution is finding single-phase tendency without 
     converging:  stability analysis is initiated sooner, which solves the 
     issue.  
   . Added a new parameter to the dbm.FluidMixture and dbm.FluidParticle 
     object creator called sigma_correction which can specify the value of
     the interface tension from a measurement divided by the value of the 
     interface tension given by the default model.  This capability is 
     recommended for use by the interface tension equation developer to 
     adjust the model for measured data when available.
V0.1.15, August 2015 -- 
   . Changed the way the bent plume model tracks the particles inside the 
     plume.  Previous versions did the particle tracking outside the main 
     integration loop.  This has two problems:  1.) the adaptive step solver
     used in the main integration does not know when particles leave the 
     plume, so there can be a big integration step near where particles 
     leave even though this should be a small step (solution is to set a 
     reasonably small value of dt_max, but this defeats the benefit of the
     adaptive step solver).  2.) this reduces the accuracy of the particle
     tracking since it is not down inside the RK adaptive step solver and
     can only rely on plume solutions at two final time steps.  The new 
     version of the model does all particle tracking inside the main 
     integration loop.  Particle time and position relative to the plume 
     centerline in local plume coordinates (unit vector direction l,n,m in 
     Lee and Cheung (1990)) are added to the plume state space.  The old
     outputs tp and sp are removed from the model.  Conversion of the 
     state space solution to x,y,z Cartesian coordinates is handled by the
     LagElement object.  This new method has a smooth transition when 
     particles leave the plume.
   . Solutions for tp and sp have been removed from the bent plume model 
     as discussed above.  These are now available through the LagElement
     object as a translation from the plume state space.
   . The entrainment function for forced entrainment was adapted to prevent
     errors in large crossflow.  If the integration step (ds) compared to the 
     plume width is small (ds/b < 1.e-9), we neglect the expansion and 
     curvature corrections to the forced entrainment.  Otherwise, the 
     entrainment will go to infinity unrealistically due to numerical problems
     in estimating db/ds from two model solution points.
   . Changed the bent plume model state space to have total particle mass 
     in the Lagrangian element (M_p = m * nbe) instead of mass flux.  This
     is more consistent with typical Lagrangian plume models.
   . Changed the bent plume model state space variable for concentration of
     dissolved-phase tracers to be total mass of tracer in the element 
     instead of the concentration times mass (C*M) typically used.  Salinity
     and passive tracer are still modeled in the old way (psu*M, C*M).  This
     new formulation makes it much easier to add the dissolving particle
     mass to the dissolved phase inside the Lagrangian element.
   . Updated where the buoyant force reduction factor (p_fac) is calculated.
     p_fac accounts for the fact that the buoyant force from the bubbles
     decreases as the particles start to drift out of the plume.  This is
     now with the new particle tracking.  Older versions had errors due to 
     the phase shift between the current model solution and the particle 
     tracking, which was conducted outside the main integration loop.  The 
     new method has consistent tracking so that phase errors do not give the 
     wrong p_fac.
   . Updated the hydrate formation time with refined calibration values and
     ensuring that the formation time cannot be negative.  Also, note that 
     if hydrate_formation_time is used and the bubble starts above the 
     hydrate stability zone, clean bubble mass and heat transfer will be 
     assumed throughout the model simulation.
   . Updated chemical_properties.py to make it compatible with older versions
     of Python.  
V0.1.14, July, 2015 -- 
   . Changed the stratified plume model inner plume entrainment coefficient 
     to match that in the bent plume model.  The bent plume model had a more
     sophisticated treatment of the shear entrainment that matches approaches
     in single-phase flow, allowing the entrainment coefficient to depend on
     the local plume Froude number.  This was facilitated by moving the 
     function to compute the shear entrainment from lmp.py to 
     dispersed_phases.shear_entrainment.  The function is then called as 
     needed by the bent plume and stratified plume models.
   . Checked the stratified plume model validation against data in Socolofsky
     and Adams (2003, 2005).  Verified that the new entrainment model is 
     acceptable and that the performance matches that in Socolofsky et al. 
     (2008).  Also, verified that the present treatment of gamma_i and gamma_o
     in the stratified plume model (which matches what was used in 
     Socolofsky et al. (2008), but not the equation written in the text) is
     the optimal usage.  Hence, the stratified plume model is fully validated
     to match or exceep performance of the model in Socolofsky et al. (2008).
   . Checked the bent plume model validation against data in Milgram (1983)
     The no crossflow cases in Milgram perform well. Also, verified that the
     stratified plume model and bent plume model give equal results for the
     quiescent, unstratified cases in Milgram. The only model deviations are
     for results very close to the diffuser in the z/D space defined by
     Bombardelli et al. (2007), and since the diffuser geometry is unknown,
     these deviations are accepted.
   . Checked the bent plume model validation against data in Socolofsky and
     Adams (2002).  This showed that the crossflow separation height was
     over-predicted by the model.  This is because the full buoyancy of the 
     bubbles is exerted on the plume until they reach the plume edge.  To 
     solve this, we now reduce the bubble buoyancy by a factor 1 - lp/b, 
     where lp is the distance from the centerline of the plume to the 
     bubbles and b is the plume half-width.  Tried other forumlations, 
     including (1 - lp/b)^2 and exp(-lp**3/b**2), and the simple linear 
     model gave the best match to data in Socolofsky and Adams (2002).  
   . Included the particle age and position as an attribute of the bent plume
     model `Model` object.  
   . To compute the buoyant force of the bubbles with the new crossflow 
     factor, had to add sp (particle position) to the LagElement.update
     function.  This required sp to be passed to `lmp.calculate` and used
     in the `lmp.derivs` functions.  This will cause any old code to fail that
     tries to update the `LagElement` object without passing sp.  Since sp is
     an attribute of the bent plume model `Model` object, though, it will be
     easy to edit old code to have this added.  This only effects user-defined
     post-processing:  All old codes will still run to obtain the solution 
     and to plot it using the built-in plot_state_space or plot_all_variables
     functions.
   . Updated `lmp.calculate` with the `lmp.correct_temperature` function so
     that the particle temperatures are stored correctly.  The 
     correct_temperature function was distributed with previous versions of
     the model, but was not implemented in the `lmp.calculate` function so 
     that it was ineffective.  It is now turned on. \
   . Edited the initial conditions file for the bent plume model in 
     `lmp.bent_plume_ic` so that Q = Qj instead of Q = Qj + Qp since the 
     momentum equation assumes the void fraction is small.  With this change, 
     the initial half-width of a bent plume model simulation matches the 
     radius of the diffuser; moreover, the simulation result from the bent
     plume model is nearly identical to the result from the stratified plume
     model in quiescent, unstratified conditions.
V0.1.13, June, 2015 --
   . Updated the numerical solution for the bent plume model so that the 
     temperature is stored correctly once heat transfer is turned off.
   . Added the particle age (t_p) to the state space of the stratified plume
     model.
   . Added the hydrate formation time `t_hyd` to the 
     `dispersed_phases.SingleParticle` object and implemented the model from
     Jun et al. (2015) that the slip velocity and heat and mass transfer 
     should be for clean bubbles for t < t_hyd and for dirty bubbles 
     otherwise.  This also makes the particle age `t` and input to 
     `dispersed_phases.SingleParticle.properties`.  Because the 
     `SingleParticle` object is inherited by the stratified plume model 
     and the bent plume model particle objects, they also have this same
     behavior.  Added the correct coding to pass the computed particle
     ages in all of the relevant `update` methods.  Hence, `t_hyd` must 
     be set when creating a particle object and then the Jun et al. (2015)
     model is implemented automatically.  Set `t_hyd = 0.` to have the 
     dirty bubble solution or `t_hyd = np.inf` to have the clean bubble
     solution over the whole simulation period.
   . Added the method `dispersed_phases.hydrate_formation_time` to compute
     the hydrate formation time following the algorithm in Jun et al. (2015).
     Pass that formation time to the particle object at creation to use the
     hydrate skin model.  See `./bin/sbm/seep_bubble.py` for an example.  
     Implementation would follow the same process for the stratified plume
     model or the bent plume model.
V0.1.12, June 23, 2015 --
   . Replaced the methods to compute gas-liquid equilibrium with more stable
     and robust methods from Michelsen and Mollerup (2007).  For cases in the
     two-phase region, far away from the phase boundary, the new methods give
     identical results to previous versions of the model.  As the two-phase
     mixture approaches the phase boundary, the new methods prevent troubles
     associated with converging on the gas-liquid partitioning.  Outside the
     two-phase region, the new methods also give the same results as before, 
     but using far fewer iterations.
   . Replaced the methods to compute viscosity with equations from Pedersen
     et al. (2014).  These methods are less expensive (an equilibrium 
     calculation is not required) and give reasonable results for light oils
     and for gases.
   . Updated the dbm.py classes so that clean and dirty bubbles are handled
     consistently throughout.  Also, edited the dbm_phys.f95 file so that 
     spherical and ellipsoidal bubbles and droplets are handled separately 
     in all cases.  For clean bubbles, three mass transfer methods are 
     provided for spherical or ellipsoidal particles:  Kumar and Hartland, 
     Clift et al., and Johnson et al.  For clean gas bubbles, the greater of 
     Clift et al. or Johnson et al. is returned; for clean liquid droplets, 
     Kumar and Hartland is used.  For dirty bubbles or droplets, we follow
     Clift et al.
   . Updated the seawater equations of state with more accurate methods for
     air/water surface tension and thermal conductivity from Sharqawy (2010).  
     The new method for thermal conductivity reports the value in W/(mK);
     whereas, previous versions of TAMOC used m/s, which is obtained by 
     k / (rho * cp).  To preserve the model equations, the rho * cp term 
     has been corrected in dbm.py so that beta (the heat transfer coefficient)
     still has units of m/s.
   . Add the Setschenow constant to ChemData.csv and updated 
     chemical_properties.py so that any columns added to ChemData.csv are 
     automatically read into the properties database.  They are not auto-
     matically added to the dbm objects, though, since Python requires all
     variables to be created explicitly.  Updated the dbm.py to use the data
     for K_salt from ChemData.csv if available or to estimate the value from
     Jonas's correlation equation.  The final K_salt is passed to the fortran
     files when computing the solubility.  
   . Updated the dbm objects with a flag called `air` to allow the user to 
     specify that the working fluid is not a hydrocarbon.  In that case, all
     of the methods work equally well as for hydrocarbon mixtures except for
     the interfacial tension.  When `air` is false (default value), the 
     correlation for hydrocarbons is used; otherwise, the air-seawater 
     surface tension is returned.
   . Added mass transfer equations for Re < 1.0 using Clift et al. (1978)
     equation 3-49.
V0.1.11, June 2015 --
   . Corrected the units for computing Vb in dbm.py for the Tyn & Calus 
     method.
   . Updated the parameters lambda_2 and epsilon in the stratified plume model
     to match the values in Socolofs et al. (2008) for the best validation to
     the available data.
   . Added a few more known values to the ./data/ChemData.csv file.
V0.1.10, March, 2015 --
   . Corrected the values for Vb in the ./data/ChemData.csv file.  These 
     values are used to get a temperature-dependent diffusivity needed to 
     compute the mass transfer coefficient for dissolution.  The values in 
     version 0.1.9 were at standard conditions; whereas, the equations need
     the molar volume at the boiling point.  Results from the model for 
     light gases now agree much better with the old values using the B and dE
     method.  
   . Updated test cases to pass with corrected diffusivity and mass transfer
     coefficient.  
V0.1.9, February, 2015 --
   . Updated the equations of state with several small improvements to make 
     the code more flexible (requiring fewer inputs or more readily available
     data), more accurate (small updates based on better parameterizations),
     and more complete (clean and dirty bubbles, most all simplifying 
     assumptions removed, and all parameter values included with the model).
     These updates were suggested by Jonas Gros, ETH Lausanne, Switzerland, 
     through his and Sam Arey's collaboration with the model.  Many thanks to
     them for helping improve the chemistry simulations in the model.
   . Added ./bin/ambient_append.py as an example of how to add new profile 
     data to an existing ambient.Profile object.  
   . Fixed several problems in the bent plume model.  Particle objects update
     correctly now in the LagElement class, the initial conditions no longer
     overwrite the initial particle mass flux, updated the particle tracking 
     to know where the surface is located and not to track particles that 
     never leave the plume, and fixed a mistake in local_coords where dt was
     used instead of the correct value ds.
   . Realized that in the bent plume model, dt is the travel time for the 
     entrained water, so the dissolution and heat transfer equations for 
     particles were wrong.  Solved this problem by passing dtp / ds from 
     the previous timestep to the derivs function.  This appears to work.  
     Also, added particle age to the tracking routine.
   . Fixed the computation of the buoyant force of the bubbles in the bent
     plume model for a multiphase plume.  Previous computation left out the
     mass of the displaced water, which significantly under-predicted the 
     buoyant force.  The current version of the model gives nearly identical
     results to the stratified plume model in quiescent, unstratified 
     conditions, with differences stemming from the fact that a Lagrangian 
     model cannot accurately incorporate the lambda_1 and lambda_2 spreading
     rates.
   . Fixed the seawater equation for viscosity (T is in deg C, not K).
   . Added clean particle empirical equations for slip velocity, mass 
     transfer, and heat transfer based on equations in Clift et al. (1978)
     and Johnson et al. (1969).  This is implemented in the dbm.py module; 
     the default returned values are for dirty particles (e.g., no change
     from previous model releases).
   . Changed the equation used to compute the diffusivity in the dbm.py
     module.  The new equation is from Hayduk and Laudie (1974) and 
     depends on the viscosity of the continuous phase and the molar volume 
     of the dispersed phase components at their boiling points.  These 
     values are more readily available than the parameters needed by the 
     previous equation for diffusivity.  This makes the model more flexible
     to handle a wide array of compounds.
   . Added new property to the dbm.py module:  viscosity.  These equations are
     generally true for gas and liquid hydrocarbons.  Other immiscible
     liquids would likely have large errors (e.g., water is off by three 
     order of magnitude).  This is needed for the clean particle mass 
     transfer equations; otherwise, it is not used by the model.
   . Made the commands in the chemical_properties.py module into a function
     so that they can be called with different ChemData.csv files.  Updated 
     dbm.py to use the new function to automatically load the ChemData.csv
     file that comes with TAMOC in the ./tamoc/data directory.  Also, added
     the capability in dbm.py for the user to supply an alternate database
     from another directory.  This new database will overwrite the data from
     the ./tamoc/data directory if the same component is present in both;
     otherwise, the new data is appended to create a larger database.  This
     is particularly useful when the user needs to use a pseudocomponent 
     model for a particular oil.
   . Added the capability to compute the temperature-dependent binary 
     interaction coefficients following Jaubert et al. 2005.  Two new files
     were added to the ./data directory:  Aij and Bij contain the group
     contribution method coefficients for the matrices A an B in the 
     Jaubert et al. 2005 paper.  To use this method, the user must supply
     a new input to the dbm object initializer called `delta_groups`, which
     gives the fraction of each group contained in each compound in the 
     mixture.  
v0.1.8, December, 12, 2014 --
   . Added the capability for the params.Scale object to print out the 
     solution to the empirical model equations and to save the results to 
     the hard drive.
   . Upgraded the entrainment calculation so that the shear entrainment is 
     never a large negative value (see Figure 13 in Jirka, 2004, for details).
   . Finalized the entrainment model with the corrected shear entrainment
     and correct asymptotic behavior
   . Fixed a bug where particle tracking stopped too early for some particles
     in the bent plume model.
   . Added bent plume model sample scripts in ./bin/bpm for a bubble plume
     (bpm_example.py) and for a blowout (bpm_blowout.py).
v0.1.7, November 17, 2014 --
   . Added capability to track particles outside of the plume during a 
     bent_plume_model simulation using the single_bubble_model
   . Fixed a bug where a particle outside the plume would continue to dissolve
     and add dissolved mass to the plume.
v0.1.6, November 7, 2014 --
   . Added new module bent_plume_model to simulate a single- or multiphase 
     plume in a crossflow.  The single-phase version is based on Lee and 
     Cheung (1990).  The multiphase version updates that model with the 
     multiphase dynamics as implemented in the stratified_plume_model.  The
     dispersed phase is tracked using an analytical function; particles leave
     the plume when they move outside the plume half-width.
   . Added new module dispersed_phases to handle all Particle objects within
     the TAMOC modeling suite.  This moves the single_bubble_model.Particle
     and stratified_plume_model.Particle object into the new module.  Also, 
     moved particle-related helper functions (e.g., particle_from_Q) to the
     new module.  This centralizes all particle dynamics to a single module.
     The new version of the model is fully backward compatible with the 
     original ./bin example files.  Because the unit tests directly access
     module objects and methods that the user would not normally address, 
     the ./test files have been updated slightly to point at the new locations
     of the dispersed_phases objects and functions.
   . Consolidated the save/load functions for particles into the 
     dispersed_phases module.  The save and load methods for the 
     single_bubble_model were poorly done.  These have been upgraded to match
     the methods used in the stratified_plume_model.  As a result, the new
     load_sim function is not compatible with output from the 
     single_bubble_model from previous versions of the TAMOC suite.
   . Added three-dimensional position to the single_bubble_model and the 
     capability for the bubble to be transported by a three-dimensional
     ambient current.  These changes are fully backward-compatible with the
     ./bin examples.  The dimensions of the state space changed, and the 
     appropriate changes had to be included in the ./test unit tests that 
     check individual members of the state space.
   . Renamed the numerical solutions to the stratified_plume_model and the 
     bent_plume_model from simp.py to smp.py and from limp.py to lmp.py.
   . Added a new module model_share.py that contains functionality shared by
     all models and not already available in an appropriate location.  For 
     this release, the model_share module writes the header to the netCDF 
     output files and loads an ambient.Profile object based on information
     read from the netCDF output file.
   . Updated the documentation for the new model structure and included 
     documentation of the full modeling suite.
v0.1.5, March 12, 2014 --
   . Changed the bubble force in the inner plume object for the stratified 
     plume model with bubbles dissolve.  The original code has a weak bubble 
     force with the bubble density is set to the plume density and the bubble
     buoyancy is with respect to the ambient density.  A new if-statement
     replaces "if self.fb[i] == 0." with if the current particle density is
     equal to the local water density, then self.fb and self.xi are both 
     zero.  This is inserted on line 1199.  All test cases still pass.
   . Changed sintef.rosin_rammler() function so that when the size 
     distribution becomes larger than the maximum stable particle size no
     mass is lost by the distribution truncation.  Added else statement on 
     line 334.
v0.1.4, March 12, 2014 --
   . Created the new test cases test_sintef and test_params.
   . Added examples for using the sintef and params modules to the ./bin 
     directories.
   . Updated the documentation with the complete distribution.
   . Modified the simp.outer_cpic() so that if the predicted flux in the outer
     plume is actually upward, the outer plume is not considered to be viable.
     Also, verified that the outer plume is not valid if the volume flux is
     NaN.  Added "or" statements on line 963::
        if dQdz > 0 or Q > 0 or np.isnan(Q):
   . Added a new stop criteria for the simp.calculate() function so that if
     the progress stops, the current integration ends: 
        if z[-1] == z[-2]:
           stop = True
     added to lines 354-355.
   . Modified the way the independent variable is stored in the calculate()
     function of the single_bubble_model.py and simp.py to make it compatible
     with the most recent version of numpy in the Enthough Canopy 
     distribution.
   . Changed the number of required significant figures in the tests for 
     the top of the solution vector in test.spm.py (made it less strict of a
     test). Because of the adaptive step-size solver and the very large 
     integration distances, small changes in the way updated numerical 
     packages work can result in differences in the solution in the third 
     and fourth significant figure.  Rather than update the test solution 
     to match updated numpy/Python packages, the original test solution is
     retained with the two significant figure threshold for passing.
v0.1.3, February 25, 2014 -- 
   . Updated the test cases for test_ambient, test_dbm_object, test_dbm,
     test_sbm, and test_spm to reflect the other changes in this update.
   . Replaced delDiss (the dissolution of species j summed over all particles) 
     on line 144 with a new variable delDiss_p (the dissolution of species j 
     summed over a single particle) in the heat transfer equation for each 
     individual particle.  The old version double-counts heat loss from the  
     particle as a result of dissolution when more than one particle in the 
     solution is dissolving.
   . Changed simp.py line 130ff so that yp[idx] is used (the dissolution of
     species j for particle i) instead of delDiss[j] (the dissolution of
     species j summed over all particles).  The old version double-counts
     heat of solution when more than one particle in the solution is 
     dissolving.
   . Added temperature as an output from the sbm.particle.update method so 
     that temperature is consistently handled throughout the simulation.
   . Updated the ambient.extend_profile_deeper method so that the correct
     pressure is computed for the extended region of the profile.
   . Fixed a bug in the Fortran files so that the Peng-Robinson equation of 
     state module can always find the correct, non-negative minimum and 
     maximum roots.  Previously, the minimum root was assumed to be less than
     1.0, which caused spurious behavior at extreme conditions.
   . Fixed a bug in simp.py to make sure the temperature is always modeled 
     correctly.
   . Added the Rosin-Rammler distribution to the SINTEF module.
   . Added hydrate dissolution reduction factor as a function of hydrate 
     stability for the mass transfer method of the FluidParticle object in 
     dbm.py.
   . Added a hydrate stability zone calculation to the FluidMixture object
     in dbm.py.
   . Updated model save functions so that when variables are defined as None
     their assumed values are saved.
   . Removed stop criteria based on the maximum number of calculation steps 
     in both the single bubble model and stratified plume model so that the 
     models always runs to completion.  This means if an error occurs, they
     may get stuck in a loop trying to get past a numerical obstacle, but the
     alternative is that the model stops for the wrong reasons.  This was
     previously part of the model to aid during development.  
   . Added new module sintef.py to compute the initial bubble and droplet 
     size distribution using the SINTEF model.
v0.1.2, September 19, 2013 --
   . Moved octant import to the functions that require it.  
   . Added `from copy import copy` to `single_bubble_model.py`
   . Added test for insoluble particles to ./test/test_sbm.py
   . Changed tests for ./test/test_spm.py to avoid instability in outer plume 
     initial conditions and to reduce the number of iterations for the full 
     plume simulations.  This was required since different versions of numpy
     and scipy were getter slightly different results after multiple 
     iterations:  not for the overall solution, but very small errors in 
     heights lead to measureable differences in output at identical heights.
     This is a result of the adaptive time step stiff solver and iteration.
v0.1.1, September 11, 2013 -- 
   . Updated the `spm_test.py` file with a complete test suite.
   . Added a plotting method for the complete suite of model variables in the
     Stratified Plume Model.
   . Updated the documentation with a few missing functions.
   . Includes the following bug fixes:
      . Fixed plotting methods in the single bubble model and stratified plume
        model when an inert particle (which has one component) clashed with 
        the modeled dissolved concentrations (which has zero components).
      . Set the temperature of the fluid surrounding a particle in the inner 
        plume equal to the temperature of the inner plume (once heat transfer
        is complete).  Previously, this was set equal to the ambient 
        temperature.
      . Changed the temperature correction in the `simp` module to reflect
        the temperature of the inner plume instead of the ambient temperature
        when heat transfer is complete.
v0.1.0, August 20, 2013 -- 
   Initial release including the stratified plume model.  Also includes:
      . Fixed pressure correction for Henry's coefficients to be based on 
        the total pressure at depth instead of the partial pressure of each
        species.
      . Changed the `ambient.Profile` object so that it removes any 
        unstable parts of the density profile.  
      . Small changes to the single bubble model so that both the single
        bubble model and the stratified plume model have parallel 
        programming architecture and behavior.  
v0.0.3, July 31, 2013 -- 
   Initial release including the ambient module and single bubble model
v0.0.2, July 8, 2013 -- 
   Initial release including the discrete bubble model
v0.0.1, July 1, 2013 -- 
   Development beta testing