search

CHLNDDEV / OceanMesh2D

A two-dimensional triangular mesh generator with pre- and post-processing utilities written in pure MATLAB (no toolboxes required) designed specifically to build models that solve shallow-water equations or wave equations in a coastal environment (ADCIRC, FVCOM, WaveWatch3, SWAN, SCHISM, Telemac, etc.).
https://github.com/sponsors/krober10nd
GNU General Public License v3.0
178 stars 64 forks source link
coastal-modelling geophysics meshes multiscale-simulation open-source shallow-water-equations

readme

OceanMesh2D

Precise distance-based two-dimensional automated mesh generation toolbox intended for coastal ocean/shallow water flow models

[!NOTE] This is the default and recommended PROJECTION branch. Please use it unless you otherwise require legacy (MASTER branch) or the absolute newest features (DEV branch).

[!WARNING] The boundary of the meshing domain must be a polygon (first point equals the last and non-self intersecting) but it does not need to be simplified. Read the user guide for more information about the inputs.

Table of contents

OceanMesh2D is a set of user-friendly MATLAB functions to generate two-dimensional (2D) unstructured meshes for coastal ocean circulation problems. These meshes are based on a variety of feature driven geometric and bathymetric mesh size functions, which are generated according to user-defined parameters. Mesh generation is achieved through a force-balance algorithm combined with a number of topological improvement strategies aimed at improving the worst case triangle quality. The software embeds the mesh generation process into an object-orientated framework that contains pre- and post-processing workflows, which makes mesh generation flexible, reproducible, and script-able.

Getting help

[!TIP] PLEASE READ THE USER GUIDE! A recent pdf of the user guide is located in this branch. For a continually updated version click here (wait for compilation and then click download PDF)

Besides posting issues with the code on Github, you can also ask questions via our Slack channel here.

Note: If the slack link invite isn't working, please send either one of us and an email and we'll fix it. By default, the invite link expires every 30 days.

Otherwise please reach out to either Dr. William Pringle (wpringle@anl.gov) or Dr. Keith Roberts (keithrbt0@gmail.com) with questions or concerns or feel free to start an Issue in the issues tab above.

Contributing

All contributions are welcome!

To contribute to the software:

  1. Fork the repository.
  2. Clone the forked repository, add your contributions and push the changes to your fork.
  3. Create a Pull request

Before creating the pull request, make sure that the examples pass...

Some things that will increase the chance that your pull request is accepted:

Code framework

OceanMesh2D consists of four standalone classes that are called in sequence. It requires no paid toolboxes to build meshes and has been tested to work with a trial version of MATLAB.

OceanMesh2D::
├── geodata -- process geospatial data.
├── edgefx  -- build mesh size functions.
├── meshgen -- generate mesh based on mesh size functions and boundaries.
└── msh     -- store, write, read, inspect, and visualize meshes and their
               axuillary components for numerical simulation.

Starting Out

  1. Clone or download and unzip the current repository.

  2. Run the setup.sh bash script or setup.bat batch script to download the required m_map package and the base datasets:

    • GSHHG global shoreline
    • SRTM15_PLUS global topobathy DEM

  3. Create or modify startup.m file located under your home folder by executing command in MATLAB:

      edit(fullfile(userpath,'startup.m'))

    And add the line:

      run(<PATH_TO_OCEANMESH2D>/setup_oceanmesh2d.m)

    Replace <PATH_TO_OCEANMESH2D> with the folder name where you cloned/unzipped the repository.

  4. Restart MATLAB to get paths added.

Additional data required for some of the following examples must be downloaded manually from here. Specifically, Examples 2, 3, 4, 5 and 5b require additional datasets from the google drive folder while base datasets are sufficient for the other examples.

Featured in  ┌── Examples/Example_1_NZ.m   -- A simple mesh around South Island
             |                                New Zealand that uses GSHHS shoreline.
user guide   ├── Examples/Example_2_NY.m   -- A high-resolution mesh around
             |                                the New York/Manhattan area that uses a DEM
             |                                created from LiDAR data.
             └── Examples/Example_3_ECGC.m -- Builds a mesh for the western North Atlantic
                                              with a local high-resolution nest around New York

Featured in         ┌── Examples/Example_4_PRVI.m -- Builds a mesh for the western North Atlantic
                    |                                with three high-resolution nests around
Geoscientific Model |                                Puerto Rico and US Virgin Islands
                    ├── Examples/Example_5_JBAY.m -- An extremely high-fidelity (15-m) mesh from
Development paper[1]|                                LiDAR data around Jamaica Bay with CFL-limiting.
                    └── Examples/Example_6_GBAY.m -- An example of the polyline/thalweg mesh size
                                                     function along the Houston Ship Channel.

See Testing to test OceanMesh2D on your system.

Testing

To ensure the software is fully functional on your system before building some crazy meshes it is strongly recommended to run the tests (RunTests.m) in the Tests/ directory.

We test all pull requests using this test suite on a local host before accepting. For substantial pull requests we will also test the Examples from the Examples/ directory.

References!

If you make use of OceanMesh2D please include a reference to [1], and to any of [2]-[5] if pertinent (latex .bib file). We would also appreciate using our logo in a presentation featuring OceanMesh2D.


[1] - Roberts, K. J., Pringle, W. J., and Westerink, J. J., 2019.
      OceanMesh2D 1.0: MATLAB-based software for two-dimensional unstructured mesh generation in coastal ocean modeling,
      Geosci. Model Dev. (GMD), https://doi.org/10.5194/gmd-12-1847-2019.
[2] - Roberts, K. J., Pringle, W. J, 2018.
      OceanMesh2D: User guide - Precise distance-based two-dimensional automated mesh generation toolbox intended for coastal
      ocean/shallow water. https://doi.org/10.13140/RG.2.2.21840.61446/2.
[3] - Roberts, Keith J. Unstructured Mesh Generation and Dynamic Load Balancing for Coastal Ocean Hydrodynamic Simulation, 2019.
      PhD Thesis, University of Notre Dame. https://curate.nd.edu/show/4q77fr0022c.
[4] - Roberts, Keith J., Pringle W.J., Westerink J. J. Contreras, M.T., Wirasaet, D., 2019.
      On the automatic and a priori design of unstructured mesh resolution for coastal ocean circulation models,
      Ocean Modelling, 144, 101509. https://doi.org/10.1016/j.ocemod.2019.101509.
[5] - Pringle, W. J., Wirasaet, D., Roberts, K. J., and Westerink, J. J., 2021.
      Global Storm Tide Modeling with ADCIRC v55: Unstructured Mesh Design and Performance,
      Geoscientific Model Development, 14(2), 1125-1145. https://doi.org/10.5194/gmd-14-1125-2021.

In addition, best practice when using software in a scientific publication is to cite the permanent doi corresponding to the version used (e.g., for reproducibility). All our releases are archived at the following Zenodo repository doi link.

Authors (202X). CHLNDDEV/OceanMesh2D: OceanMesh2D VX.X. Zenodo. https://doi.org/10.5281/zenodo.1341384

Please fill in the version (VX.X), author list and year corresponding to the version used.

We would also like to acknowledge various scripts and algorithms from mesh2d included in OceanMesh2D that have been developed by @dengwirda. Please also see JIGSAW-GEO:

[i] - Engwirda, D., 2017.
      JIGSAW-GEO (1.0): Locally orthogonal staggered unstructured grid generation for general circulation modelling on the sphere.
      Geoscientific Model Development, 10(6), 2117–2140. https://doi.org/10.5194/gmd-10-2117-2017.

GALLERY:

Jiangchao Qiu from his publication.

       

Changelog

The format is based on Keep a Changelog

Unreleased (on current HEAD of the Projection branch)

Fixed

[6.0.0] - 2024-02-28

Added

[5.0.0] - 2021-07-29

Added

[4.0.0] - 2021-03-14

Added

Changed

Fixed

[3.3.0] - 2020-12-21

Fixed

Added

Changed