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
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.
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'.
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
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.