The long awaited ROMS/TOMS 3.0 is finally released. The structure of the code has changed substantially. This version includes all the adjoint-based algorithms. From now on, ROMS will only be distributed via Subversion (svn). For more details check the following
link. Notice that the user needs to checkout the trunk directory since it contains the lattest version of the code with all bug fixes.
The tagged versions (tags directory) are frozen in time and will never be corrected. 
Please check ROMS repository bug track wiki regularly.In the next few days we are planning to update documentation and give you more information about the capabilities and usage of ROMS/TOMS 3.0.
Many thanks to all ROMS developers, beta testers and ONR and NSF funding agencies for making this possible. Special thanks to the ROMS adjoint group (Arango, Cornuelle, Di Lorenzo, Miller, Moore, and Powell) for their hard work over the last few years. It took us five years to get to this point. Very special thanks to John Warner and Kate Hedstrom for their help and hard work. We have been working tirelessly for the last three months to consolidate our versions into the official 3.0 release.
ROMS/TOMS is now an open source code and licensed under the
following conditions. Notice that the above link also includes some recommendations on how to shared ROMS applications with others. We encourage you to use Method A. The new structure facilitates the sharing of applications without the need to give the source code but the application configuration and input files. We are planning to release some of our private, realistic, complex applications in the near future. This serves as an example of sharing aplications and configuring very complex realistic applications.
The new version has very complex adjoint-based algorithms and requires some expertise. Please visit the developers
blog for technical information.We will continue building this technical information. It is possible that in the future we will include web-based tutorials about how to use these algorithms.
There is still a lot of room for improvement, and new developments will be released in the near future.
What is New:
- The code structrure was redesigned to remove the need for the user to change any of the files located in the ROMS root directory. Recall that any change to the ROMS kernel will affect and break the tangent linear, representer, and adjoint models. For more details, please check the following developers blog link.
- The new version has the following directory tree structure:
Code: Select all
trunk/ Main trunk directory /Atmosphere/ Atmosphere models root directory /COAMPS COAMPS root directory (empty) /WRF WRF root directory (empty) /Compilers/ make configuration files /Data/ Input data root directory /ROMS/ ROMS data root directory /CDL ROMS Metadata design /Forcing Input test cases forcing NetCDF files /Grid Input test cases grid NetCDF files /Initial Input test cases initial conditions NetCDF files /Lib/ External libraries /ARPACK Arpack eigenvalue problem solver library /MCT Modeling Coupling Tool library /MCT_WRF Modeling Coupling Tool library, WRF umbrella /Master Main standalone and coupling programs /ROMS/ ROMS root directory /Adjoint Adjoint model /Bin Executable scripts /Drivers Computational drivers /External Standard input scripts /Functionals Analytical expression header files /Include Test cases configuration header files /Modules Declaration modules /Nonlinear Nonlinear model /Obsolete Discontinued files /Programs Support programs /SeaIce Sea-ice model (empty) /Representer Representer model /Tangent Tangent linear model /Utility Generic utility files License_ROMS.text Open source license Version SVN Version information /User/ ROMS User interface root directory /External User standard input scripts /Functionals User analytical expresions templates /Include User application header files /WAVES/ Waves models root directory /SWAN SWAN root directory /External SWAN input data and standard input files /Src SWAN model - Currently, we have the following ROMS/TOMS computational drivers in directory ROMS/Drivers:
Notice that we have several incremental 4DVAR drivers. The difference between all them is the conjugate gradient used. The file is4dvar_ocean_old.h (IS4DVAR_OLD) uses a very simple conjugate gradient algorithm (descent.F). This driver is now obsolete and we keep it for comparisons and historical reasons. The is4dvar_ocean.h and is4dvar_ocean_lanczos.h drivers uses cgradient.h and cgradient_lanczos.h, respectively. Both drivers can be used for a particular application. For more information, please check the following developers blog link.Code: Select all
convolution.h Adjoint solution spatial convolution driver correlation.h Background-error correlation driver nl_ocean.h Nonlinear model driver tl_ocean.h Tangent linear model driver rp_ocean.h Representer tangent linear model driver ad_ocean.h Adjoint model driver adsen_ocean.h Adjoint sensitivity analysis driver afte_ocean.h Adjoint finite time eigenmodes driver fte_ocean.h Finite time eigenmodes driver fsv_ocean.h Forcing singular vectors driver grad_ocean.h Tangent linear and adjoint models gradient test tlcheck_ocean.h Tangent linear model linearization test pert_ocean.h Tangent linear and adjoint models sanity tet test picard_ocean.h Picard test for representers tangent linear model op_ocean.h Optimal perturbations driver optobs_ocean.h Optimal observations driver symmetry.h Representer matrix symmetry test driver s4dvar_ocean.h Strong constraint 4DVAR assimilation drivers (obsolete) so_semi_ocean.h Stochastic optimals driver, semi-norm is4dvar_*.h Strong constraint, incremental 4DVAR assimilation drivers w4dpsas_ocean.h Weak constraint 4D-PSAS assimilation driver w4dvar_ocean.h Weak constraint 4DVAR representers assimilation driver
The driver s4dvar_ocean.h is now obsolete and broken. This was our first attempt to strong constraint 4DVAR. We abandom this strategy because it didn't converged in realistic applications. This is the full 4DVAR algorithm. Nowadays, everybody uses the incremental approach because it is more efficient and has better convergence. However, we keep this driver in case that we want to revisit it in the future.
We are still fine tunning the weak constraint 4DVAR drivers w4dpsas_ocean.h and w4dvar_ocean.h. There are some convergence issues that we are addressing. Currently, we are working on a Lacnzos-based conjugate gradient algorithm. We will update these algorithms in the near future
- All the released algorithms work in parallel.
The nonlinear model (NLM), perturbation tangent linear model (TLM), and finite amplitude tangent linear representer model (RPM) run in both shared-memory and distributed-memory paradigms. However because of it is construction, the adjoint model (ADM) runs only in distributed-memory. The ADM violates shared-memory collision rules. ROMS adjoint is exact and it is hand-coded from the discrete algorithm line-by-line. Several of the algorithms listed above uses both TLM and ADM at the same time. This implies that you will be only able to run in distributed-memory. The RPM model is only used in weak constraint 4DVAR with uses the inderect representer approach.
The adjoint model requires special adjoint communication routines in distributed-memory that involve summation of the solution in the ghost points. This implies that we not longer can get identical adjoint solutions in serial versus parallel. The parallel solution is subject to round off - WET_DRY: algorithms to account for the wetting and drying have been added to the model. Regions that are assigned rho mask values of 0 are always dry. Regions that are assinged rho mask values of 1 are allowed to become wet or dry, depending on the water level. Users need to provide a minimum critial depth, DCRIT, in the ocean.in file. Default value is 0.10 m. When the water level decreases beflow DCRIT, transport is prevented out of that computational cell. Water is always allowed to flow into any cell. On output, the array wetdry_masking provides a time history of the wet and dry areas.
- Simulating WAves Nearshore (SWAN) surface wave model v4041AB is distributed with this release. SWAN is a fully featured spectral wave model used to simulate wind-wave growth in coastal oceans. We have provided the capability to concurrently run ROMS and SWAN to allow dynamic interaction of surface waves and currents. Information is exchanged at user defined time intervals via the use of the Model Coupling Toolkit (MCT). See INLET_TEST as distributed example that uses this feature.
- MCT v2.0 is distributed with the release package to provide a consistent distribution package. Users can download MCT directly from its source web page , however we can only support the use of v2.0 that has been proven to work with this release. Detailed description of the coupling is described in:
Warner, J.C., N. Perlin, and E. Skyllingstad, 2007: Using the Model Coupling Toolkit to couple earth system models, Environmental Modelling and Software, submitted. - Nearshore wave driven (radiation stress) momentum terms. This is activated with the NEARSHORE_MELLOR CPP option, and follows the formulation as described in:
Mellor, G. L., 2003: The three-dimensional current and surface wave equations, J. Phys. Oceanog., 33, 1978-1989.
All the currents in ROMS are in Eulerian formulation A more complete description of the wave-current interaction formulation in ROMS are contained in the following manuscripts:
Warner, J.C., C.R.Sherwood, R.P. Signell, C.K. Harris, and H.G. Arango, 2006: Development of a three-dimensional, regional, coupled wave, current, and sediment-transport model, Computers and Geosciences, submitted.
Haas, K.H., and J.C. Warner, 2007: Comparing a quasi3D to a full 3D nearshore circulation model: Shorecirc and ROMS, in preparation. - Sediment Bedload transport: Two formulations have been added based on either the Meyer-Peter Mueller (MPM) or the Soulsby /Damgaard formulations. The MPM method needs bottom stress from currents or combined waves and currents. The Soulsby/Damgaard method requires input of wave direction and magnitudes. The wave information can be provided from analytical, a NetCDF forcing file, or a coupled application.
- Sediment Bed slope: accounts for the local gradients in the sea floor on the transport of sediment due to bed load. This feature is currently automatically activated if the user activates either of the bed load formulations.
- Sediment Morphology: allows dynamic feedback of changing sea floor elevation to the hydrodynamic model. The output variable bath will be time dependent.
- Surface flux of turbulent kinetic energy due to wave breaking. There are two formulations that have been added to account for increased flux of turbulence due to surface wave breaking. Both methods require the use of the GLS two equation turbulence closure model.
The first formulation is based on surface wind stress to estimate a flux of tke. This method is activated using the CRAIG_BANNER CPP option, based on the formulation Craig and Banner (1994, J. Phys. Oceanogr., 24, 2546). This method requires a surface flux parameter CRGBAN_CW, provided by the user in the ocean.in file. The default value is 100. The method also requires an estimate of the surface roughness that can be obtained using CHARNOK CPP option. The user needs to provide a roughness scale parameter, CHARNOK_ALPHA, also entered in the ocean.in file. Default value is 1400.
The second formulation is based on nearshore studies and uses the wave energy dissipation as an estimate for surface flux of turbulent kinetic energy. The user needs to activate the TKE_WAVEDISS CPP option. The method requires a surface flux scale parameter SZ_ALPHA that relates the percent of total wave dissipation available for surface flux, default value is 0.25 provided in ocean.in. Also the method requires an estimate of roughness height, activated with ZOS_HSIG to use the significant wave height to estimate the surface roughness. The user also needs to provide a scale factor for the wave height, ZOS_HSIG_ALPHA in ocean.in, default is 0.5. More description of the implementation of these methods into ROMS can be found in:
S. Carniel, J. Chiggiato, M. Sclavo, R.P. Signell, and J.C. Warner, 2007: Upper layer velocity modeling in the ocean: recent applications and challenges, in preparation. - SHOREFACE: Application to demonstrate wave driven flows for an along-shore uniform planar sloping beach. Forcing is from a netcdf file containing output from a spectral wave model. The application uses the NEARSHORE_MELLOR option to drive a 3D nearshore flow circulation.
- INLET_TEST: Application to demonstrate dynamic wave-ocean model coupling. This application activates SWAN_COUPLING and NEARSHORE_MELLOR to simulate flow at an idealized inlet.
- TEST_HEAD: Application to demonstrate dynamic wave-ocean model coupling. This application activates SWAN_COUPLING and NEARSHORE_MELLOR to simulate flow past an idealized tidal headland.