Mesh Creation for SWASH

A Python package that automatically transforms SWASH (Simulating WAves till SHore) input files from cartesian coordinates to unstructured meshes using gmsh. The mesh generation is adaptive, with refinement proportional to water depth --- finest resolution near the shoreline and coarsest at maximum depth. Breakwaters (identified by porosity ≠ 1) automatically receive the finest resolution.

Features

• Adaptive mesh refinement: Automatically creates finer mesh near shorelines and breakwaters
• Depth-based sizing: Mesh resolution varies from fine (shallow water) to coarse (deep water)
• Gauge support: Optional refinement around specified gauge positions
• SWASH compatibility: Exports meshes in Triangle format (.node, .ele, .edge files)
• Boundary tagging: Automatic boundary numbering (West=1, North=2, East=3, South=4)
• Interpolation options: Linear, quadratic, or cubic interpolation for mesh size variation

Installation

Using uv (recommended)

uv add git+https://github.com/Lab-MAREE/swash-mesh-creation

Using pip

pip install https://github.com/Lab-MAREE/swash-mesh-creation

Usage

The package provides a command-line interface with two main commands:

1. Create Mesh

Generate an unstructured mesh from SWASH input files:

# Basic usage
swash-mesh create /path/to/swash/directory

# With custom mesh parameters
swash-mesh create /path/to/swash/directory \
  --lc-fine 5.0 \
  --lc-coarse 100.0 \
  --interpolation 2

# Short alias
sm c /path/to/swash/directory -f 5.0 -c 100.0 -i 2

Parameters:

• swash_dir: Directory containing SWASH input files
• --lc-fine/-f: Mesh size at coastline (default: 5.0)
• --lc-coarse/-c: Mesh size at deepest part (default: 100.0)
• --interpolation/-i: Interpolation order (1=linear, 2=quadratic, 3=cubic, default: 1)

2. Apply Mesh

Apply the generated mesh to SWASH input files:

# Apply mesh to SWASH configuration
swash-mesh apply /path/to/swash/directory

# Short alias
sm a /path/to/swash/directory

3. Visualization

The generated mesh can be visualized with:

gmsh mesh.msh

Required Files

The SWASH directory must contain:

For mesh creation:

• INPUT: SWASH input file with simulation parameters
• bathymetry.txt: 2D array of bathymetry values
• porosity.txt (optional): Porosity values for breakwater detection

For mesh application:

• All files from mesh creation, plus:
• mesh.msh: Node coordinates and connectivity generated by gmsh
• mesh.node: Node coordinates and boundary markers in the triangle format
• mesh.ele: Element connectivity in the triangle format

Output Files

The mesh creation process generates:

• mesh.msh: Node coordinates and connectivity generated by gmsh
• mesh.node: Node coordinates and boundary markers in the triangle format
• mesh.ele: Element connectivity in the triangle format
• Various visualization files (if enabled)

How It Works

1. Bathymetry Analysis: Reads bathymetry data and identifies shoreline boundaries
2. Breakwater Detection: Identifies areas with porosity ≠ 1 as breakwaters
3. Distance Field Creation: Computes distance fields from shorelines and gauges
4. Adaptive Refinement: Applies depth-based mesh sizing with specified interpolation
5. Mesh Generation: Uses gmsh to create the unstructured triangular mesh
6. Format Conversion: Exports to Triangle format for SWASH compatibility
7. Interpolation: Maps bathymetry values to mesh nodes using RBF interpolation

Development

Setting up development environment

# Install with development dependencies
uv sync --group dev

# Run code quality tools
uv run black .          # Format code
uv run isort .          # Sort imports
uv run ty check         # Type checking
uv run ruff check       # Linting

Dependencies

Core dependencies:

• gmsh (≥4.14.0): Mesh generation engine
• numpy (≥2.3.1): Numerical operations
• scipy (≥1.16.0): Interpolation algorithms and .mat reading
• typer (≥0.16.0): CLI framework
• plotly (≥6.2.0): Visualization
• tqdm (≥4.67.1): Progress bars

Future Work

• Adapt this package to use parameters given as function or cli arguments instead of reading the SWASH input file so it's usable with any program
• Refine the detections of breakwaters so it's more robust than simply the proxy of porosity
• Use the shorelines as boundaries in the mesh generation to completely remove land surfaces rather than making the mesh larger at those locations