jwallwork23 / adapt_utils

Mesh adaptation utilities for coastal ocean modelling in Firedrake and Thetis.

Mesh Adaptation and Adjoint Methods for Coastal Ocean Modelling in Firedrake

In this code, adjoint methods and mesh adaptation are applied to solving a variety of 2D coastal ocean modelling problems using the coastal, estuarine and ocean modelling solvers provided by Thetis. Thetis is built upon the Firedrake project, which enables the efficient solution of FEM problems in Python by automatic generation of PETSc code.

Currently supported model components:

• Shallow water equations (i.e. depth-averaged hydrodynamics);
• Passive tracer transport (both non-conservative and conservative options available);
• Sediment transport;
• Exner equation.

Anisotropic mesh adaptation based on Riemannian metric fields is achieved using PRAgMaTIc. This code provides a wide range of utilities for metric-based adaptation, including Hessian recovery, metric combination, Lp normalisation and (isotropic and anisotropic) goal-oriented error estimators and metrics. Monitor-based r-adaptation methods based on solutions of Monge-Ampere type equations is also supported, as well as limited Lagrangian FEM functionality.

Continuous adjoint solvers are provided for shallow water and advection-diffusion problems. The discrete adjoint code dolfin-adjoint can also be used to generate adjoint solutions for more general problems.

This is research of the Applied Modelling and Computation Group (AMCG) at Imperial College London.

Publications

Listed below are publications which use adapt_utils, along with the corresponding code versions and the test cases considered in those works. BibTeX formatted references are also available in docs/publications.bib. The specific versions of Firedrake and Thetis used for each publication are also shown below and can be downloaded from the corresponding links. To install a specific version of Firedrake, please follow the instructions here.

• J. G. Wallwork, N. Barral, D. A. Ham, M. D. Piggott, 'Anisotropic Goal-Oriented Mesh Adaptation in Firedrake', In: 28th International Meshing Roundtable, pp.83-100, (2020).

  • Paper: .
  • Code:
    • adapt_utils: (v1.0).
    • Firedrake: .
  • Test cases:
    • steady/test_cases/point_discharge2d (Section 5.3);
    • steady/test_cases/point_discharge3d (Section 5.4).

• J. G. Wallwork, N. Barral, S. C. Kramer, D. A. Ham, M. D. Piggott, 'Goal-Oriented Error Estimation and Mesh Adaptation for Shallow Water Modelling', Springer Nature Applied Sciences, volume 2, pp.1053--1063 (2020).

  • Paper: DOI: 10.1007/s42452-020-2745-9.
  • Code:
    • adapt_utils: (v1.3).
    • Firedrake: .
    • Thetis: .
  • Test case:
    • steady/test_cases/turbine_array (Section 4).

• M. C. A. Clare, J. G. Wallwork, S. C. Kramer, H. Weller, C. J. Cotter, M. D. Piggott, 'Multi-scale hydro-morphodynamic modelling using mesh movement methods', Submitted to International Journal on Geomathematics.

  • Preprint: DOI: 10.31223/osf.io/tpqvy.
  • Code:
    • adapt_utils .
    • Firedrake: .
    • Thetis: .
  • Test cases: unsteady/test_cases/trench_1d (Section 4.1); unsteady/test_cases/trench_slant (Section 4.1); unsteady/test_cases/beach_slope (Section 4.2); unsteady/test_cases/tsunami_bump (Section 4.3). For the versions in the paper use hydro_morpho_paper branch.

• J. G. Wallwork, N. Barral, D. A. Ham, M. D. Piggott, 'Goal-Oriented Error Estimation and Mesh Adaptation for Tracer Transport Modelling', Submitted to Computer Aided Design (2021).

  • Preprint: DOI: 10.31223/X56021.
  • Code:
    • adapt_utils: (adapt_utils_20210126).
    • Firedrake: .
    • Thetis: .
  • Test cases: steady/test_cases/point_discharge2d (Section 4.2), steady/test_cases/point_discharge3d (Section 4.3), unsteady/test_cases/idealised_desalination (Section 5.1).

• J. G. Wallwork, 'Mesh Adaptation and Adjoint Methods for Finite Element Coastal Ocean Modelling', PhD thesis, Imperial College London (2021).

  • Code:
    • adapt_utils: (adapt_utils_20210415).
    • Firedrake: .
    • Thetis: .
  • Test cases:
    • test/interp (Sections 2.8 and 3.4);
    • steady/test_cases/point_discharge2d (Sections 2.7, 3.6, 7.3 and 7.5);
    • case_studies/tohoku/inversion/1d (Section 4.4);
    • case_studies/tohoku/inversion/okada (Sections 4.4 and 4.5);
    • test/adapt (Sections 5.8 and 6.4);
    • unsteady/test_cases/bubble_shear (Sections 5.8 and 6.1);
    • unsteady/test_cases/trench_1d (Section 6.5);
    • steady/test_cases/turbine_array (Sections 7.3 and 7.5);
    • steady/test_cases/idealised_desalination (Section 7.7);
    • case_studies/tohoku/hazard (Section 7.8).

User instructions

• Clone this repository and make it accessible to the $PYTHONPATH environment variable.
• Set the $SOFTWARE environment variable to where you would like your PETSc and Firedrake installations to exist.
• Copy the contents of the install directory into $SOFTWARE and enter that directory.
• Install Firedrake:
  • For an installation with Pragmatic, call source install_petsc.sh and then source install_firedrake.sh, modifying these scripts, if desired.
  • For an installation without Pragmatic, call source install_firedrake_no_adapt.sh.
  • If installing on a fresh Ubuntu OS then you will need to call source install_compilers.sh beforehand.
• Test your installation by calling make test_all from the root directory.
• Once you have a working Firedrake installation, get to grips with adapt_utils by looking at the test cases in steady/test_cases and unsteady/test_cases, as well as the notebooks hosted here.

For feedback, comments and questions, please email [e-mail] or [e-mail] (for feedback related to Clare et al.).