Dataset: Source code, license, example input and visualization files for LTRANS v.2b, a particle tracking model that runs with the Regional Ocean Modeling System (ROMS)

From http://northweb.hpl.umces.edu/LTRANS.htm. CHECK FOR UPDATES. NEWER VERSION MAY BE AVAILABLE.

PDF of original LTRANS_v.2b website [2016-09-14]

LTRANS v.2b Model Description

The Larval TRANSport Lagrangian model (LTRANS v.2b) is an off-line particle-tracking model that runs with the stored predictions of a 3D hydrodynamic model, specifically the Regional Ocean Modeling System (ROMS). Although LTRANS was built to simulate oyster larvae, it can easily be adapted to simulate passive particles and other planktonic organisms. LTRANS v.2 is written in Fortran 90 and is designed to track the trajectories of particles in three dimensions. It includes a 4th order Runge-Kutta scheme for particle advection and a random displacement model for vertical turbulent particle motion. Reflective boundary conditions, larval behavior, and settlement routines are also included. A brief description of the LTRANS particle-tracking model can be found here (68 KB .pdf). For more information on LTRANS and the application of LTRANS to oyster larvae transport, see a summary web page with animations, the publications North et al. (2008, 2011), and the LTRANS v.2 User's Guide. Please cite North et al. (2011) when referring to LTRANS v.2b. The updates that were made for LTRANS v.2b are listed here. 

The Lagrangian TRANSport (LTRANS v.2b) model is based upon LTRANS v.1 (formerly the Larval TRANSport Lagrangian model). Ian Mitchell made the bug fixes in LTRANS v.2b. Zachary Schlag completed signigicant updates to the code in LTRANS v.2 with input from Elizabeth North, Chris Sherwood, and Scott Peckham. LTRANS v.1 was built by Elizabeth North and Zachary Schlag of University of Maryland Center for Environmental Science Horn Point Laboratory. Funding was provided by the National Science Foundation Biological and Physical Oceanography Programs**, Maryland Department of Natural Resources, NOAA Chesapeake Bay Studies, NOAA Maryland Sea Grant College Program, and NOAA-funded UMCP Advanced Study Institute for the Environment.

A beta version of LTRANS v2b which uses predictions from the circulation model ADCIRC is available here.

LTRANS Code

LTRANS v.2b Open Source Code. We would appreciate knowing who is using LTRANS. If you would like to share this information with us, please send us your name, contact information, and a brief description of how you plan to use LTRANS to enorth@umces.edu. To refer to LTRANS in a peer-reviewed publication, please cite the publication(s) listed in the Description section above.

LTRANSv2b_License.txt

License file. This license was based on the ROMS license. Please note that this license applies to all sections of LTRANS v.2b except those listed in the 'External Dependencies and Programs' section below.

LTRANS_v2b.zip

LTRANS v.2b Code. This zip file contains the LTRANS code, license, and User's Guide. Section II of the LTRANS v.2 User's Guide contains instructions for setting up and running LTRANS v.2b in Linux and Windows environments. Before using LTRANS v.2b, please read the External Dependencies and Programs section below. This version of LTRANS is parameterized to run with the input files that are available in the LTRANS v.2b Example Input Files section below. This section also contains a tar ball with this code and the example input files.

 

External Dependencies and Programs. LTRANS v.2b requires NetCDF libraries and uses the following programs to calculate random numbers (Mersenne Twister) and fit tension splines (TSPACK). Because LTRANS v.2 reads-in ROMS-generated NetCDF (.nc) files, it requires that the appropriate NetCDF libraries be installed on your computer (see files and links below). Also, please note that although the Mersenne Twister and TSPACK programs are included in the LTRANS v.2b in the Random_module.f90 and Tension_module.f90, respectively, they do not share the same license file as LTRANS v.2b. Please review and respect their permissions (links and instructions provided below).

VF-NetCDF.zip	Windows Visual Fortran NetCDF libraries. These NetCDF files that are compatible with Visual Fortran were downloaded from the Unidata NetCDF Binaries Website for LTRANS v.1. The NetCDF 90 files were downloaded from Building the F90 API for Windows for the Intel ifort compilerwebsite. The VF-NetCDF.zip folder contains README.txt that describes where to place the enclosed files. If these files do not work, you may have to download updated versions or build your own by following the instructions at the UCAR Unidata NetCDF website.
NetCDF website	Linux NetCDF libraries. Linux users will likely have to build their own Fortran 90 libraries using the source code/binaries that are available on the UCAR Unidata NetCDF website.
mt19937ar.f	Mersenne Twister random number generator. This program was recoded into F90 and included in the Random_module.f90 in LTRANS. See the Mersenne Twister Home Page for more information about this open source program. If you plan to use this program in LTRANS, please send an email to: m-mat @ math.sci.hiroshima-u.ac.jp (remove space) to inform the developers as a courtesy.
TSPACK website	TSPACK: tension spline curve-fitting package. This program (ACM TOMS Algorithm 716) was created by Robert J. Renka and is used in LTRANS as part of the water column profile interpolation technique. The original TSPACK code can be found at the link to the left and is copyrighted by the Association for Computing Machinery (ACM). With the permission of Dr. Renka and ACM, TSPACK was modified for use in LTRANS by removing unused code and call variables and updating it to Fortran 90. The modified version of TSPACK is included in the LTRANS source code in the Tension Spline Module (tension_module.f90). If you would like to use LTRANS with the modified TSPACK software, please read and respect the ACM Software Copyright and License Agreement. For noncommercial use, ACM grants "a royalty-free, nonexclusive right to execute, copy, modify and distribute both the binary and source code solely for academic, research and other similar noncommercial uses" subject to the conditions noted in the license agreement. Note that if you plan commercial use of LTRANS with the modified TSPACK software, you must contact ACM at permissions@acm.org to arrange an appropriate license. It may require payment of a license fee for commerical use.

 

LTRANS v.2b Example Input Files. These files can be used to test LTRANS v.2b. They include examples of particle location and habitat polygon input files (.csv) and ROMS grid and history files (.nc) that are needed to run LTRANS v.2b. Many thanks to Wen Long for sharing the ROMS .nc files. The LTRANS v.2b code above is configured to run with these input files. Note: please download the tar (LTRANSv2.tgz) history files (clippped_macroms_his_*.nc) files between the hours of 5 pm and 6 am Eastern Standard Time because of their large size.

Initial_particle_locations.csv End_polygons.csv End_holes.csv	Initial particle locations and habitat polygon input files needed for initializing LTRANS. The habitat polygon input files (End_polygons.csv and End_holes.csv) are only required when the settlement module is turned on.
baymouth_grid_macroms.nc	ROMS grid (for LTRANS v.2b input). Clipped from MACROMS 2009 simulation of the Middle Atlantic Bight (implemented by Wen Long).  .
clipped_macroms_his_0003.nc clipped_macroms_his_0004.nc clipped_macroms_his_0005.nc	ROMS predictions (for LTRANS v.2b input). Files are ~777 MB each. Clipped from MACROMS 2009 simulation of the Middle Atlantic Bight (implemented by Wen Long).
LTRANSv2b.tgz	This tar ball (1 GB) contains the LTRANS code as well as all example input files and the User's Guide. Use the included makefile to compile and then run LTRANS.exe on your Linux machine. DOWNLOAD AFTER WORKING HOURS (Eastern Standard Time) PLEASE!!

 

LTRANS v.2b Utilities. The following programs were developed to run LTRANS v.2 or visualize LTRANS v.2 model output. Unless specified otherwise within the program code, these open source programs are considered part of LTRANS and fall under the LTRANS license. Many thanks to LTRANS users who have made these contributions! If you would like to share a LTRANS utility or your modifications/additions to LTRANS source code, please send them toenorth@umces.edu.

LTRANSv2_viz.BA	Surfer/Scripter code for visualizing LTRANS v.2b output developed by E. W. North. The .BAS file is the program and associated .bln files are needed to visualize the location of bottom habiat.Here is an example animation (MB) of LTRANS v.2 model output made with Surfer using the code and example input files provided above. Surfer is a Windows program for contouring and 3D surface mapping. Scripter is an object oriented scripting language (Active X Automation) that comes with, and automates, Surfer. Information on Surfer is available here and a free demo is available here. Please note that the demo version will not allow export so it is likely that you will not be able to use the demo version to create .gif files for animations.
OceanView in R	OceanView, created by Dr. Karline Soetaert, is a set of R functions for visualizing 2-D and 3-D oceanographic data and model output. The package is on the official R site:http://cran.r-project.org/web/packages/OceanView. There is also a short manual with snapshots of the visualization functions, some of which use LTRANS output as examples:http://cran.r-project.org/web/packages/OceanView/vignettes/OceanView.pdf.
plot_results.m	MATLAB code for visualizing LTRANS v.2b output. Here is Matlab M-file which was designed by Yong Kim for LTRANS v.1 and adapted for LTRANS v.2b by Elizabeth North. It makes a 3D plot of the model bathymetry (from .nc input grid file) and particle locations from LTRANS v.2b .csv output files. Here is an example animation (MB) of LTRANS v.2b model output made with MATLAB.

 

LTRANS v.2 User's Guide and v.2b Updates 
Please send comments or suggestions regarding the User's Guide to enorth@umces.edu. They will be posted on the list of known LTRANS v.2 bugs and solutions. Also, here is a document that provides a (not elegant) solution to errors (Particle not in v (or u) element or particle jumped over v (or u) element) that can result from single-grid width channels in the hydrodynamic model domain (link). 

Mitchell, I. 2013. Updates in LTRANS v.2b. University of Maryland Center for Environmental Science, Horn Point Laboratory. Cambridge, MD. 2 pp. (93 KB .pdf)

Schlag, Z. R., and E. W. North. 2012. Lagrangian TRANSport model (LTRANS v.2) User’s Guide. University of Maryland Center for Environmental Science, Horn Point Laboratory. Cambridge, MD. 183 pp. (1.7 MB .pdf)

Discussion Forum
If you would like to report bugs and solutions, please e-mail them to Elizabeth North (enorth@umces.edu) and they will be added to this list. There is also a discussion forum topic in the ROMS/TOMS Ocean Modeling Discussion Forum under ROMS/TOMS Applications > User Applications > LTRANS. Here is the link to the topic. If you have questions about LTRANS, please post them at this site and Elizabeth North or other LTRANS Users will answer them.

LTRANS Publications

North, E. W., E. E. Adams, S. Schlag, C. R. Sherwood, R. He, S. Socolofsky. 2011. Simulating oil droplet dispersal from the Deepwater Horizon spill with a Lagrangian approach. AGU Book Series: Monitoring and Modeling the Deepwater Horizon Oil Spill: A Record Breaking Enterprise (request .pdf).

North, E. W., R. R. Hood, S.-Y. Chao, and L. P. Sanford. 2006. Using a random displacement model to simulate turbulent particle motion in a baroclinic frontal zone: a new implementation scheme and model performance tests. Journal of Marine Systems 60: 365-380 (request .pdf).

North, E. W., Z. Schlag, R. R. Hood, L. Zhong, M. Li, and T. Gross. 2006. Modeling dispersal of Crassostrea ariakensis oyster larvae in Chesapeake Bay. Final Report to Maryland Department of Natural Resources, July 31, 2006. 55 p. (request .pdf)

North, E. W., Z. Schlag, R. R. Hood, M. Li, L. Zhong, T. Gross, and V. S. Kennedy. 2008. Vertical swimming behavior influences the dispersal of simulated oyster larvae in a coupled particle-tracking and hydrodynamic model of Chesapeake Bay. Marine Ecology Progress Series 359: 99-115 (request .pdf).

Schlag, Z. R., and E. W. North. 2012. Lagrangian TRANSport model (LTRANS v.2) User’s Guide. University of Maryland Center for Environmental Science, Horn Point Laboratory. Cambridge, MD. 183 pp. (1.7 MB .pdf)

Schlag, Z., E. W. North, and K. Smith. 2008. Larval TRANSport Lagrangian model (LTRANS) User’s Guide. University of Maryland Center for Environmental Science, Horn Point Laboratory. Cambridge, MD. 146 pp. (739 KB .pdf)