TAMOC - Texas A&M Oilspill Calculator

TAMOC is a Python package with Fortran extension modules that provides various functionality for simulating a subsea oil spill. This includes methods to compute equations of state of gas and oil, dissolution, transport of single bubbles and/or droplets, and simulations of blowout plumes, including the development of subsurface intrusions, and estimation of initial bubble/droplet size distributions from source flow conditions.

For typical usage, please see the ./bin directory of the source distribution for various example scripts.

Version 3.4.0: Updated the root-finding method in the Fortran math_funcs module

so that it always finds the correct roots. Updated the dbm module equilibrium method so that it returns the correct fluid phase when there are non-zero components in the mixture. Moved the unit conversion in the chemical_properties module into a separate function so that they can be used anywhere they are needed.

Version 3.3.0: Added a few new post-processing tools to the bent plume and

stratified plume models and updated the particle size model tools so that the user can specify a non-equilibrium pressure.

Version 3.2.0: Added the ability to save derived variables (e.g., plume width,

trajectory, concentration, etc.) from the bent plume model and stratified plume model. Each of these modules have the new methods get_derived_variables and save_derived_variables in their Model class objects. Updated the test files to be compatible with the C_pen and C_pen_T variables added to the dbm module.

Version 3.1.0: Added the ability for the user to provide values of the

Peneloux volume shift parameter to the dbm module classes. The input parameters are C_pen and C_pen_T, which relate to the temperature-dependent Peneloux shift model in equation 5.9 in Pedersen et al. (2015). Supplying C_pen equal to zero uses the original model based on Lin and Duan (2005). The original model is preferred unless the pseudo-component property data have been strongly fitted so that Peneloux shift parameters are outside the expected range of -0.4 to 1.2 are required. Minor fixes to prevent errors when non-standard units are used as input to the ambient module and several updates to make the code compatible with recent releases of numpy and matplotlib.

Version 3.0.0: Added the capability to have mixed-phase particles of gas and

liquid fused together. Updated the initial conditions methods for pure multi-phase plumes so that a void fraction between 0 and 1 is enforced. This may result in a different orifice diameter being used than specified by the user, but ensures the dilute plume assumption is not violated. This new capability becomes important when simulating accidental spills from subsea CO2 sequestration pipelines in which very large quantities of CO2 may be released through a small orifice. Other model updates improve intuition of using the model.

Version 2.4.0: Added additional post-processing methods to the bent plume

model to extract dissolved-phase concentration maps. Also made it easier to use the Privat and Jaubert binary interaction coefficients and updated the seawater module with a density equation for very hot seawater and a function to compute pH.

Version 2.3.1: Added new post-processing methods to the bent plume model

module to track mass balances and plot particle size distributions.

Version 2.3.0: Added a new module to replace the Fortran codes that are used

by the dbm module. Now, a Fortran compiler is not required to install and run TAMOC.

Version 2.2.0: Updated the ambient module so that it is not based on and

compatible with xarray Dataset objects, updated all tests to pass with the latest version of TAMOC, revised the documentation with a new template and organization, and updated some of the source docstrings to compile with Sphinx.

Version 2.1.0: Updated the readme file with instructions for modern version

of Windows. Updated the model with various improvements, including some additional chemical property data, additional functionality in the blowout.py module. Small, additional bug fixes.

Version 2.0.0: Updated the complete model system for compatibility with both

Python 2.7 and Python 3.8+. Updated the ambient.Profile object so that netCDF files do not have to be used and including the ability to create a default profile using the world-ocean average data now distributed with the model. Created new modules for particle size distributions and for simulating a blowout, including a new Blowout object. Created a new modules containing utility functions for manipulating data related to the ambient and dbm modules.

Version 1.2.1: Corrected minor errors in translating between NetCDF objects

and Numpy arrays to avoid a masked-array error and updated the dbm_phys.f95 function for the mass transfer rate by Kumar and Hartland so that the Reynolds number is defined before it is used.

Version 1.2.0: Added biodegradation to the fate processes considered in the

discrete bubble model (DBM).

Version 1.1.1: Updated the ambient module interpolation method to be

compatible with newer versions of numpy, updated a few of the ./bin examples to only read data provided with TAMOC, and updated all test cases to be compatible with slight changes in the dbm module that were done in Version 1.1.0.

Version 1.1.0: Updated various modules to be compatible with Anaconda

Python, including Scipy version 0.17.0 and higher. Fixed a couple bugs in the test cases where output files are not created correctly. Updated the documentation with some missing new variables.

Version 1.0.0: Finalized the validation cases and tested the model for

release. This is the first non-beta version of the model, and is the version for which journal publications have been prepared. Most of the changes going forward are expected to be new capabilities and improvements in the user interface: the model solutions are not expected to change appreciably.

Beta versions of the model:

Version 0.1.17: Updated the modeling suite so that all of the save/load

functions are consistent with the present model variables and attributes. Modified the bent plume model so that ambient currents can come from any direction (three- dimensional). Added a new test file for the bent plume model. Changed the convergence criteria for the stratified plume model.

Version 0.1.16: Updated the bent plume model so that post processing is

fully consistent with the simulation results. Also, added the capability for the bent plume model to stop at the neutral buoyancy level in the intrusion for a stratified case. Updated the equilibrium calculations in the dbm module so that it does not crash when the first few elements of the mixture disappear (go to zero) and to speed up the calculation when successive substitution indicates the mixture may be single phase, but is slowly converging: stability analysis is initiated early, which greatly improves performance for difficult cases.

Version 0.1.15: Moved the particle tracking in the bent plume model inside

the main integration loop, which then removes tp and sp from the model attributes and includes then in the model state space instead. Updated the bent plume model state space so that particle mass is the state variables instead of particle mass flux and so that the dissovled phase constituents are modeled as total mass in the Lagrangian element instead of concentration times mass of the element. Made a small update to the hydrate formation time equations.

Version 0.1.14: Updated several aspects of the calibration after comparing

to available data in Milgram (1983), Jirka (2004), Socolofsky and Adams (2002, 2003, 2005), Socolofs et al. (2008), and Socolofsky et al. (2013). The most significant change is an updated shear entrainment coefficient for the stratified plume model. Also, added a buoyant force reduction as bubbles drift away from the centerline in a crossflow.

Version 0.1.13: Updated the temperature output for the bent plume model so

that the correct temperature is saved when heat transfer ends. Added the particle time to the state space of the stratified plume model and added the hydrate formation model of Jun et al. (2015) to the particle objects in the dispersed phases module. The hydrate formation time is set at the start of a simulation and is properly implemented for all three simulation modules in the TAMOC suite. To compute the hydrate formation time using the equations from Jun et al. (2015), use the function dispersed_phases.hydrate_formation_time.

Version 0.1.12: Replaced methods for equilibrium and viscosity with better

algorithms. Fixed small inconsistencies in the dbm.py module for clean bubbles, and updated the seawater equations of state with better methods for heat capacity and air/water surface tension. Updated values for the Setschenow constant in ./data/ChemData.csv, and added a mass transfer equation for Re < 1.

Version 0.1.11: Replaced some of the -9999 values in the ./data/ChemData.csv

file with literature values and updated the units of the calcualtion of Vb in dbm.py when data are not available. Also, updated the parameter values for the stratified plume model with the values recommended in Socolofsky et al. (2008).

Version 0.1.10: Updated the values for Vb in the ./data/ChemData.csv file

with their correct values. Improves computation of diffusivity and mass transfer over Version 0.1.9, and gives results similar to Version 0.1.8 and older that used a different method to estimate diffusivity.

Version 0.1.9: Made several minor changes to the equations of state per the

guidance of Jonas Gros. These changes make the model much more robust for hydrocarbon mixtures. The updates are minor in that the results do not change markedly for the test cases already in previous versions of the model. However, the changes provide major advantages for more difficult cases, not demonstrated in the simple ./bin examples.

Version 0.1.8: Added print capability to the params.py module and upgraded

the shear entrainment model in the bent_plume_model.py to the entrainment equations in Jirka 2004.

Version 0.1.7: Added the capability for the bent_plume_model.py to continue

to track particles outside the plume using the single_bubble_model.py. Fixed a bug where particles outside the plume continued to dissolve and add mass to the bent_plume_model.

Version 0.1.6: Added a new simulation module for plumes in crossflow: the

bent_plume_model.py. Refactored some of the code for the original model suite to make it more general and to reuse it in the bent_plume_model. Added example files and unit tests for the new modules, and updated the documentation to reflect all model changes.

Version 0.1.5: Fixed a small bug in the way the bubble force is handled

after the particle dissolves. Fixed a bug to retain mass conservation for a bubble size distribution using the sintef.rosin_rammler() function.

Version 0.1.4: Added script for the the sintef and params modules to the

./bin examples directory and the /test unit tests. Improved the stability of the model by added a few new checks during and before calculation. Updated the unit tests to make them more platform and numpy-version independent.

Version 0.1.3: Removed some of the debugging catches in the iteration so that

solutions always fully converge and fixed a few bugs. See CHANGES.txt for full details. Added the sintef.py module for computing initial bubble/droplet size distributions.

Version 0.1.2: Refined the test suite for compatibility with multiple

versions of numpy and scipy. Corrected a few more minor bugs.

Version 0.1.1: Full modeling suite with small bug fixes and complete test

suite..

Version 0.1.0: First full modeling suite release, including the stratified

plume module.

Version 0.0.3: Updated to include the single bubble model and the ambient

module for handling ambient CTD data. Includes input and output using netCDF files and a complete set of tests in ./tamoc/test

Version 0.0.2: First model release, including the discrete bubble model

(dmb.py)

Version 0.0.1: Initial template of files using setup.py

Requirements

This package requires:

• Python 2.3 or higher and is now compatible with both Python 2.7 and Python 3.8+. Python 2 compatibility is will no longer be ensured. Please move to Python 3 if you have not already done so.
• Numpy version 1.16 or higher
• Scipy version 1.2.0 or higher
• The Python netCDF4 package
• The Python xarray package
• To use the Fortran versions of the equations of state, a modern Fortran compiler is required. Otherwise, the Python version of these codes will be used.
• To view plots of the model output, TAMOC uses the matplotlib package

Code development and testing for this package was conducted in the Mac OS X environment, Version 10.13.6 through 10.14.6. The Python environments were created using miniconda. The Python 3 environment used Python 3.8.2; the Python 2 environment used Python 2.7.15. All scripts are tested in iPython with the --pylab flag.

Fortran files are written in modern Fortran style and are fully compatible with gfortran 4.6.2 20111019 (prerelease). They have been compiled and tested by the author using f2py Version 2.

Quick Start

For the best and most complete information, please see the documentation web pages in the ./doc/ directory of the TAMOC repository. A step-by-step installation guide is included in the Getting Started rubric of the documentation. A brief summary that may still work is provided below.

• Edit setup.cfg to select the appropriate C/C++ and Fortran compilers
• For a normal install, run 'python setup.py build' followed by 'python setup.py install' (with sudo if necessary). To install using a local install directory in develop mode, use: 'python setup.py develop'.
• To skip the Fortran extension library and install a Python-only version of tamoc, use the --python-only flag in the install command, e.g., 'python setup.py develop --python-only'.
• Test the installation by opening a Python session and executing import tamoc from the Python prompt. Be sure that you are not in the same directory as the setup.py file so that Python will look for tamoc in the main Python package repository on your system.
• To run all the tests, execute 'pytest -v --pyargs tamoc' from a command prompt outside of the TAMOC package. If pytest is not installed, follow the instructions here: http://pytest.org/latest/getting-started.html. The TAMOC tests write files to test the storage and recovery methods of the model modules. If these tests fail with write permission errors, you may try 'sudo pytest -v --pyargs tamoc'.

Platforms

Windows

The following method has been tested for installation on Windows 10 using Miniconda environments.

• Create a new Conda environment for Python 3. This has been tested up to Python version 3.8.8. Install the required dependencies using:

  conda install numpy scipy matplotlib netCDF4 pytest

  Also install the free GNU fortran compiler using:

  conda install -c conda-forge fortran-compiler

  Note that this fortran compiler requires that the following, free software also be installed on the Windows box: Microsoft Visual C++ 14.0 or greater. You can obtain this with the Microsoft C++ Built Tools at: https://visualstudio.microsoft.com/visual-cpp-build-tools/.

• Download the TAMOC source files. Activate your conda environment, and in the ./tamoc directory at a command prompt try:

  python setup.py install <--python-only>

  Alternatively, you can install a development version with:

  python setup.py develop <--python-only>

  where the flag '--python-only' is optional

• Change directly to a directory outside of your TAMOC source files. Check the TAMOC package installation by running the following command at a command prompt:

  pytest -v --pyargs tamoc

Mac OS X / Unix

The following method has been tested for installation on Mac OS X 10.7.

• Install a complete Python distribution that includes Python, Numpy, and Scipy with versions compatible with the above list. Testing has been completed by the author using a 32-bit and 64-bit Python installations. The Python distribution will have to be compatible with your C/C++ and Fortran compiler.
• Install the free XCode app in order to provide C/C++ compiler capability. Be sure to install the command-line tools.
• Download and install the gfortran binary. See, http://gcc.gnu.org/wiki/GFortranBinaries
• Follow the steps in the Quick Start section above to complete installation.