gadopt 2.0.0__tar.gz

gadopt-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 G-ADOPT Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gadopt-2.0.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.1
+Name: gadopt
+Version: 2.0.0
+Summary: A computational platform for inverse geodynamics
+Author: G-ADOPT Contributors
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+This repository contains material and examples relating to the G-Adopt Platform, a computational platform for inverse geodynamics, being developed and maintained by researchers from the Research School of Earth Sciences at the Australian National University. It builds on a recent surge in accessible observational datasets and advances in inversion methods using sophisticated adjoint techniques that provide a mechanism for fusing these observations with dynamics, physics and chemistry.
+
+G-ADOPT is supported and funded by the Australian Research Data Commons (ARDC), with additional partner contributions from AuScope, the NCI and Geosciences Australia.
+
+At this stage, the repository contains material associated with Davies et al. 2021 -- Geoscientific Model Development -- "Automating Finite Element Methods for Geodynamics via Firedrake". The examples and test cases presented in this paper can be found in the Davies_etal_GMD_2021 directory.
+
+Additional material will be added as the project develops.

gadopt-2.0.0/README.md

@@ -0,0 +1,7 @@
+This repository contains material and examples relating to the G-Adopt Platform, a computational platform for inverse geodynamics, being developed and maintained by researchers from the Research School of Earth Sciences at the Australian National University. It builds on a recent surge in accessible observational datasets and advances in inversion methods using sophisticated adjoint techniques that provide a mechanism for fusing these observations with dynamics, physics and chemistry.
+
+G-ADOPT is supported and funded by the Australian Research Data Commons (ARDC), with additional partner contributions from AuScope, the NCI and Geosciences Australia.
+
+At this stage, the repository contains material associated with Davies et al. 2021 -- Geoscientific Model Development -- "Automating Finite Element Methods for Geodynamics via Firedrake". The examples and test cases presented in this paper can be found in the Davies_etal_GMD_2021 directory.
+
+Additional material will be added as the project develops.

gadopt-2.0.0/gadopt/__init__.py

@@ -0,0 +1,13 @@
+from firedrake import *
+from .time_stepper import CrankNicolsonRK, ImplicitMidpoint
+from .limiter import VertexBasedP1DGLimiter
+from .utility import log, ParameterLog, TimestepAdaptor, LayerAveraging, timer_decorator
+from .diagnostics import GeodynamicalDiagnostics
+from .momentum_equation import StokesEquations
+from .scalar_equation import EnergyEquation
+from .stokes_integrators import StokesSolver, create_stokes_nullspace
+from .energy_solver import EnergySolver
+from .approximations import BoussinesqApproximation, ExtendedBoussinesqApproximation, AnelasticLiquidApproximation, TruncatedAnelasticLiquidApproximation
+
+from firedrake.petsc import PETSc
+PETSc.Sys.popErrorHandler()

gadopt-2.0.0/gadopt/approximations.py

@@ -0,0 +1,210 @@
+import abc
+from firedrake import sym, grad, inner, div, Identity
+from .utility import ensure_constant, vertical_component
+
+
+class BaseApproximation:
+    """
+    Base class to provide expressions in (Navier?)-Stokes + energy equations
+
+    Basic assumption is that we are solving (to be extended when needed)
+
+    div(dev_stress) + grad p + buoyancy(T, p) * khat = 0
+
+    div(rho_continuity * u) = 0
+
+    rhocp DT/Dt + linearized_energy_sink(u) * T = div(kappa*grad(Tbar + T)) + energy_source(u)
+
+    where the following are provided by Approximation methods:
+
+    linearized_energy_sink(u) = 0 (BA/EBA) or Di*rhobar*alphabar*w (ALA)
+    kappa() is diffusivity or conductivity depending on rhocp()
+    Tbar (property) is 0 or reference temperature profile (ALA)
+    compressible (property) False or True
+    if compressible then dev_stess=mu*[sym(grad(u)-2/3 div(u()]
+    if not compressible then dev_stress=mu*sym(grad(u)) and rho_continuity is assumed to be 1
+    """
+    @property
+    @abc.abstractmethod
+    def compressible(self):
+        "Whether approximation is compressible (True/False)"
+        pass
+
+    @abc.abstractmethod
+    def buoyancy(self, p, T):
+        "UFL expression for buoyancy (momentum source in gravity direction)"
+        pass
+
+    @abc.abstractmethod
+    def rho_continuity(self):
+        "UFL expression for density in mass continuity equation (=1 for incompressible"
+        pass
+
+    @abc.abstractmethod
+    def rhocp(self):
+        "UFL expression expression for coefficient in front of DT/dt in energy eequation"
+        pass
+
+    @abc.abstractmethod
+    def kappa(self):
+        "UFL expression for diffusivity/conductivity"
+        pass
+
+    @property
+    @abc.abstractmethod
+    def Tbar(self):
+        "Reference temperature profile"
+        pass
+
+    @abc.abstractmethod
+    def linearized_energy_sink(self, u):
+        "UFL expression for (temperature dependent) sink terms in energy equation."
+        pass
+
+    @abc.abstractmethod
+    def energy_source(self, u):
+        "UFL expression for any other terms (not dependent on T or u) in energy equation"
+        pass
+
+
+class BoussinesqApproximation(BaseApproximation):
+    """Boussinesq approximation:
+
+    Small density variation linear in Temperature only, only taken into account in buoyancy term.
+    All references rho, cp, alpha are constant and typically incorporated in Ra
+    Viscosous dissipation is neglected (Di << 1)."""
+    compressible = False
+
+    def __init__(self, Ra, kappa=1, g=1, rho=1, alpha=1):
+        """
+        :arg Ra:   Rayleigh number
+        :arg kappa, g, rho, alpha:  Diffusivity, gravitational acceleration, reference density and thermal expansion coefficient
+                                    Normally kept at 1 when non-dimensionalised."""
+        self.Ra = ensure_constant(Ra)
+        self._kappa = ensure_constant(kappa)
+        self.g = ensure_constant(g)
+        self.rho = ensure_constant(rho)
+        self.alpha = ensure_constant(alpha)
+
+    def buoyancy(self, p, T):
+        return self.Ra * self.g * self.alpha * self.rho * T
+
+    def rho_continuity(self):
+        return 1
+
+    def rhocp(self):
+        return 1
+
+    def kappa(self):
+        return self._kappa
+
+    Tbar = 0
+
+    def linearized_energy_sink(self, u):
+        return 0
+
+    def energy_source(self, u):
+        return 0
+
+
+class ExtendedBoussinesqApproximation(BoussinesqApproximation):
+    """
+    Extended Boussinesq
+
+    As Boussinesq but includes viscous dissipation and work against gravity (both scaled with Di)."""
+    compressible = False
+
+    def __init__(self, Ra, Di, mu=1, H=None, cartesian=True, **kwargs):
+        """
+        :arg Ra: Rayleigh number
+        :arg Di: Dissipation number
+        :arg mu: Viscosity used in viscous dissipation
+        :arg H:  Volumetric heat production
+        :arg cartesian:  True: gravity points in negative z-direction, False: gravity points radially inward
+        :arg kappa, g, rho, alpha:  Diffusivity, gravitational acceleration, reference density and thermal expansion coefficient
+                                    Normally kept at 1 when non-dimensionalised."""
+
+        super().__init__(Ra, **kwargs)
+        self.Di = Di
+        self.mu = mu
+        self.H = H
+        self.cartesian = cartesian
+
+    def viscous_dissipation(self, u):
+        stress = 2 * self.mu * sym(grad(u))
+        if self.compressible:  # (used in AnelasticLiquidApproximations below)
+            stress -= 2/3 * self.mu * div(u) * Identity(u.ufl_shape[0])
+        phi = inner(stress, grad(u))
+        return phi * self.Di / self.Ra
+
+    def work_against_gravity(self, u, T):
+        w = vertical_component(u, self.cartesian)
+        return self.Di * self.alpha * self.rho * self.g * w * T
+
+    def linearized_energy_sink(self, u):
+        return self.work_against_gravity(u, 1)
+
+    def energy_source(self, u):
+        source = self.viscous_dissipation(u)
+        if self.H:
+            source += self.H * self.rho
+
+        return source
+
+
+class TruncatedAnelasticLiquidApproximation(ExtendedBoussinesqApproximation):
+    """
+    Truncated Anelastic Liquid Approximation
+
+    Compressible approximation. Excludes linear dependence of density on pressure (chi)"""
+    compressible = True
+
+    def __init__(self, Ra, Di,
+                 Tbar=0, chi=1, cp=1,
+                 gamma0=1, cp0=1, cv0=1,
+                 **kwargs):
+        """
+        :arg Ra:   Rayleigh number
+        :arg Di:   Dissipation number
+        Reference values that may be depth-dependent (default to 1 if not supplied):
+        :arg rho:  reference density
+        :arg alpha: reference thermal expansion coefficient
+        :arg Tbar: reference temperature. In the diffusion term we use Tbar + T (i.e. T is the pertubartion) - default 0
+        :arg chi:  reference isothermal compressibility
+        :arg cp:   reference specific heat at constant pressure
+        :arg mu:   Viscosity used in viscous dissipation
+        :arg H:    Volumetric heat production - default 0
+        :arg cartesian:  True: gravity points in negative z-direction, False: gravity points radially inward
+        :arg kappa, g:  Diffusivity, gravitational acceleration
+        Constant coefficients in pressure dependent buoyancy term::w
+        :arg gamma0:   Gruneisen number
+        :arg cp0, cv0: specific heat at constant pressure and volume reference for entire Mantle (all references above may be depth-dependent)."""
+        super().__init__(Ra, Di, **kwargs)
+        self.Tbar = Tbar
+        # Equation of State:
+        self.chi = chi
+        self.cp = cp
+        assert 'g' not in kwargs
+        self.gamma0, self.cp0, self.cv0 = gamma0, cp0, cv0
+
+    def rho_continuity(self):
+        return self.rho
+
+    def rhocp(self):
+        return self.rho * self.cp
+
+    def linearized_energy_sink(self, u):
+        w = vertical_component(u, self.cartesian)
+        return self.Di * self.rho * self.alpha * w
+
+
+class AnelasticLiquidApproximation(TruncatedAnelasticLiquidApproximation):
+    """
+    Anelastic Liquid Approximation
+
+    Compressible approximation. Includes linear dependence of density on pressure (chi)"""
+
+    def buoyancy(self, p, T):
+        pressure_part = -self.Di * self.cp0 / self.cv0 / self.gamma0 * self.g * self.rho * self.chi * p
+        temperature_part = super().buoyancy(p, T)
+        return pressure_part + temperature_part

gadopt-2.0.0/gadopt/diagnostics.py

@@ -0,0 +1,40 @@
+import firedrake
+from firedrake import assemble, Constant, sqrt, dot, grad, FacetNormal
+from .utility import CombinedSurfaceMeasure
+
+
+def domain_volume(mesh):
+    return assemble(Constant(1)*firedrake.dx(domain=mesh))
+
+
+class GeodynamicalDiagnostics:
+
+    def __init__(self, u, p, T, bottom_id, top_id, degree=4):
+        mesh = u.ufl_domain()
+        self.domain_volume = domain_volume(mesh)
+        self.u = u
+        self.p = p
+        self.T = T
+        self.dx = firedrake.dx(degree=degree)
+        if T.function_space().extruded:
+            ds = CombinedSurfaceMeasure(mesh, degree)
+        else:
+            ds = firedrake.ds(mesh)
+        self.ds_t = ds(top_id)
+        self.ds_b = ds(bottom_id)
+        self.n = FacetNormal(mesh)
+
+    def u_rms(self):
+        return sqrt(assemble(dot(self.u, self.u) * self.dx)) * sqrt(1./self.domain_volume)
+
+    def u_rms_top(self):
+        return sqrt(assemble(dot(self.u, self.u) * self.ds_t))
+
+    def Nu_top(self):
+        return -1 * assemble(dot(grad(self.T), self.n) * self.ds_t) * (1./assemble(Constant(1) * self.ds_t))
+
+    def Nu_bottom(self):
+        return assemble(dot(grad(self.T), self.n) * self.ds_b) * (1./assemble(Constant(1) * self.ds_b))
+
+    def T_avg(self):
+        return assemble(self.T * self.dx) / self.domain_volume

gadopt-2.0.0/gadopt/energy_solver.py

@@ -0,0 +1,91 @@
+from firedrake import DirichletBC, Function
+from .scalar_equation import EnergyEquation
+from .utility import is_continuous, ensure_constant
+from .utility import log_level, INFO, DEBUG
+
+iterative_energy_solver_parameters = {
+    "mat_type": "aij",
+    "snes_type": "ksponly",
+    "ksp_type": "gmres",
+    "ksp_rtol": 1e-5,
+    "pc_type": "sor",
+}
+
+direct_energy_solver_parameters = {
+    "mat_type": "aij",
+    "snes_type": "ksponly",
+    "ksp_type": "preonly",
+    "pc_type": "lu",
+    "pc_factor_mat_solver_type": "mumps",
+}
+
+
+class EnergySolver:
+    def __init__(self, T, u, approximation,
+                 delta_t, timestepper, bcs=None, solver_parameters=None):
+        self.T = T
+        self.Q = T.function_space()
+        self.mesh = self.Q.mesh()
+        self.delta_t = delta_t
+        rhocp = approximation.rhocp()
+        self.eq = EnergyEquation(self.Q, self.Q, rhocp=rhocp)
+        self.fields = {
+            'diffusivity': ensure_constant(approximation.kappa()),
+            'reference_for_diffusion': approximation.Tbar,
+            'source': approximation.energy_source(u),
+            'velocity': u,
+            'advective_velocity_scaling': rhocp
+        }
+        sink = approximation.linearized_energy_sink(u)
+        if sink:
+            self.fields['absorption_coefficient'] = sink
+
+        if solver_parameters is None:
+            if self.mesh.topological_dimension() == 2:
+                self.solver_parameters = direct_energy_solver_parameters.copy()
+                if INFO >= log_level:
+                    # not really "informative", but at least we get a 1-line message saying we've passed the energy solve
+                    self.solver_parameters['ksp_converged_reason'] = None
+            else:
+                self.solver_parameters = iterative_energy_solver_parameters.copy()
+                if DEBUG >= log_level:
+                    self.solver_parameters['ksp_monitor'] = None
+                elif INFO >= log_level:
+                    self.solver_parameters['ksp_converged_reason'] = None
+        else:
+            self.solver_parameters = solver_parameters
+        apply_strongly = is_continuous(T)
+        self.strong_bcs = []
+        self.weak_bcs = {}
+        bcs = bcs or {}
+        for id, bc in bcs.items():
+            weak_bc = {}
+            for type, value in bc.items():
+                if type == 'T':
+                    if apply_strongly:
+                        self.strong_bcs.append(DirichletBC(self.Q, value, id))
+                    else:
+                        weak_bc['q'] = value
+                else:
+                    weak_bc[type] = value
+            self.weak_bcs[id] = weak_bc
+
+        self.timestepper = timestepper
+        self.T_old = Function(self.Q)
+        # solver is setup only last minute
+        # so people can overwrite parameters we've setup here
+        self._solver_setup = False
+
+    def setup_solver(self):
+        """Setup timestepper and associated solver"""
+        self.ts = self.timestepper(self.eq, self.T, self.fields, self.delta_t,
+                                   bnd_conditions=self.weak_bcs, solution_old=self.T_old,
+                                   strong_bcs=self.strong_bcs,
+                                   solver_parameters=self.solver_parameters)
+        self._solver_setup = True
+
+    def solve(self):
+        if not self._solver_setup:
+            self.setup_solver()
+        t = 0  # not used atm
+        self.ts.advance(t)

gadopt-2.0.0/gadopt/equations.py

@@ -0,0 +1,88 @@
+from abc import ABC, abstractmethod
+import firedrake
+from .utility import CombinedSurfaceMeasure
+
+
+class BaseEquation(ABC):
+    """An equation class that can produce the UFL for the registered terms."""
+
+    """This should be a list of BaseTerm sub-classes that form the terms of the equation."""
+    terms = []
+
+    def __init__(self, test_space, trial_space, quad_degree=None, **kwargs):
+        """
+        :arg test_space: the test functionspace
+        :arg trial_space: The trial functionspace
+        test and trial space are only used to determine the the discretisation that's used (ufl_element)
+        not what test and trial functions are actually used (these are provided seperately in residual())
+        :arg quad_degree: quadrature degree, default is 2*p+1 where p is the polynomial degree of trial_space
+        any further keywords arguments are passed on to the individual terms
+        """
+        self.test_space = test_space
+        self.trial_space = trial_space
+        self.mesh = trial_space.mesh()
+
+        p = trial_space.ufl_element().degree()
+        if isinstance(p, int):
+            # isotropic element
+            if quad_degree is None:
+                quad_degree = 2*p + 1
+        else:
+            # tensorproduct element
+            p_h, p_v = p
+            if quad_degree is None:
+                quad_degree = 2*max(p_h, p_v) + 1
+
+        if trial_space.extruded:
+            # extruded mesh: create surface measures that treat the bottom and top boundaries the same as lateral boundaries
+            # so that ds or dS integrates over both horizontal and vertical boundaries
+            # and we can also use "bottom" and "top" as surface ids, e.g. ds("top")
+            self.ds = CombinedSurfaceMeasure(self.mesh, quad_degree)
+            self.dS = firedrake.dS_v(domain=self.mesh, degree=quad_degree) + firedrake.dS_h(domain=self.mesh, degree=quad_degree)
+        else:
+            self.ds = firedrake.ds(domain=self.mesh, degree=quad_degree)
+            self.dS = firedrake.dS(domain=self.mesh, degree=quad_degree)
+
+        self.dx = firedrake.dx(domain=self.mesh, degree=quad_degree)
+
+        # self._terms stores the actual instances of the BaseTerm-classes in self.terms
+        self._terms = []
+        for TermClass in self.terms:
+            self._terms.append(TermClass(test_space, trial_space, self.dx, self.ds, self.dS, **kwargs))
+
+    def mass_term(self, test, trial):
+        r"""Return the UFL for the mass term \int test * trial * dx typically used in the time term."""
+        return firedrake.inner(test, trial) * self.dx
+
+    def residual(self, test, trial, trial_lagged=None, fields=None, bcs=None):
+        """Return the UFL for all terms (except the time derivative)."""
+        if trial_lagged is None:
+            trial_lagged = trial
+        if fields is None:
+            fields = {}
+        if bcs is None:
+            bcs = {}
+        F = 0
+        for term in self._terms:
+            F += term.residual(test, trial, trial_lagged, fields, bcs)
+
+        return F
+
+
+class BaseTerm(ABC):
+    """A term in an equation, that can produce the UFL expression for its contribution to the FEM residual."""
+    def __init__(self, test_space, trial_space, dx, ds, dS, **kwargs):
+        self.test_space = test_space
+        self.trial_space = trial_space
+        self.dx = dx
+        self.ds = ds
+        self.dS = dS
+        self.mesh = test_space.mesh()
+        self.dim = self.mesh.geometric_dimension()
+        self.n = firedrake.FacetNormal(self.mesh)
+        self.term_kwargs = kwargs
+
+    @abstractmethod
+    def residual(self, test, trial, trial_lagged, fields):
+        """Return the UFL for this term"""
+        pass