gusto.physics package

Submodules

gusto.physics.boundary_and_turbulence module

Objects to describe physics parametrisations for the boundary layer, such as drag and turbulence.

class gusto.physics.boundary_and_turbulence.BoundaryLayerMixing(equation, field_name, parameters=None)

Bases: PhysicsParametrisation

A simple boundary layer mixing scheme. This acts like a vertical diffusion, using an interior penalty method.

Parameters:

• equation (PrognosticEquationSet) – the model’s equation.

• field_name (str) – name of the field to apply the diffusion to.

• ibp (IntegrateByParts, optional) – how many times to integrate the term by parts. Defaults to IntegrateByParts.ONCE.

• parameters (BoundaryLayerParameters) – configuration object giving the parameters for boundary and surface level schemes. Defaults to None, in which case default values are used.

evaluate(x_in, dt)

Evaluates the source term generated by the physics. This only recovers the density field.

Parameters:

• x_in – (:class: ‘Function’): the (mixed) field to be evolved.

• dt – (:class: ‘Constant’): the timestep, which can be the time interval for the scheme.

class gusto.physics.boundary_and_turbulence.StaticAdjustment(equation, theta_variable='theta_vd')

Bases: PhysicsParametrisation

A scheme to provide static adjustment, by sorting the potential temperature values in a column so that they are increasing with height.

Parameters:

• equation (PrognosticEquationSet) – the model’s equation.

• theta_variable (str, optional) – which theta variable to sort the profile for. Valid options are “theta” or “theta_vd”. Defaults to “theta_vd”.

evaluate(x_in, dt)

Evaluates the source term generated by the physics. This does nothing if the implicit formulation is not used.

Parameters:

• x_in – (:class: ‘Function’): the (mixed) field to be evolved.

• dt – (:class: ‘Constant’): the timestep, which can be the time interval for the scheme.

class gusto.physics.boundary_and_turbulence.SuppressVerticalWind(equation, spin_up_period)

Bases: PhysicsParametrisation

Suppresses the model’s vertical wind, reducing it to zero. This is used for instance in a model’s spin up period.

Parameters:

• equation (PrognosticEquationSet) – the model’s equation.

• spin_up_period (ufl.Constant) – this parametrisation is applied while the time is less than this – corresponding to a spin up period.

evaluate(x_in, dt)

Evaluates the source term generated by the physics. This does nothing if the implicit formulation is not used.

Parameters:

• x_in – (:class: ‘Function’): the (mixed) field to be evolved.

• dt – (:class: ‘Constant’): the timestep, which can be the time interval for the scheme.

class gusto.physics.boundary_and_turbulence.SurfaceFluxes(equation, T_surface_expr, vapour_name=None, implicit_formulation=False, parameters=None)

Bases: PhysicsParametrisation

Prescribed surface temperature and moisture fluxes, to be used in aquaplanet simulations as Sea Surface Temperature fluxes. This formulation is taken from the DCMIP (2016) test case document.

These can be used either with an in-built implicit formulation, or with a generic time discretisation.

Written to assume that dry density is unchanged by the parametrisation.

Parameters:

• equation (PrognosticEquationSet) – the model’s equation.

• T_surface_expr (ufl.Expr) – the surface temperature.

• vapour_name (str, optional) – name of the water vapour variable. Defaults to None, in which case no moisture fluxes are applied.

• implicit_formulation (bool, optional) – whether the scheme is already put into a Backwards Euler formulation (which allows this scheme to actually be used with a Forwards Euler or other explicit time discretisation). Otherwise, this is formulated more generally and can be used with any time stepper. Defaults to False.

• parameters (BoundaryLayerParameters) – configuration object giving the parameters for boundary and surface level schemes. Defaults to None, in which case default values are used.

evaluate(x_in, dt)

Evaluates the source term generated by the physics. This does nothing if the implicit formulation is not used.

Parameters:

• x_in – (:class: ‘Function’): the (mixed) field to be evolved.

• dt – (:class: ‘Constant’): the timestep, which can be the time interval for the scheme.

class gusto.physics.boundary_and_turbulence.WindDrag(equation, implicit_formulation=False, parameters=None)

Bases: PhysicsParametrisation

A simple surface wind drag scheme. This formulation is taken from the DCMIP (2016) test case document.

These can be used either with an in-built implicit formulation, or with a generic time discretisation.

Parameters:

• equation (PrognosticEquationSet) – the model’s equation.

• implicit_formulation (bool, optional) – whether the scheme is already put into a Backwards Euler formulation (which allows this scheme to actually be used with a Forwards Euler or other explicit time discretisation). Otherwise, this is formulated more generally and can be used with any time stepper. Defaults to False.

• parameters (BoundaryLayerParameters) – configuration object giving the parameters for boundary and surface level schemes. Defaults to None, in which case default values are used.

evaluate(x_in, dt)

Evaluates the source term generated by the physics. This does nothing if the implicit formulation is not used.

Parameters:

• x_in – (:class: ‘Function’): the (mixed) field to be evolved.

• dt – (:class: ‘Constant’): the timestep, which can be the time interval for the scheme.

gusto.physics.chemistry module

Objects describe chemical conversion and reaction processes.

class gusto.physics.chemistry.TerminatorToy(equation, k1=1, k2=1, species1_name='X', species2_name='X2')

Bases: PhysicsParametrisation

Setup the Terminator Toy chemistry interaction as specified in ‘The terminator toy chemistry test …’ Lauritzen et. al. (2014).

The coupled equations for the two species are given by:

D/Dt (X) = 2Kx D/Dt (X2) = -Kx

where Kx = k1*X2 - k2*(X**2)

Parameters:

• ( (equation) – class: ‘PrognosticEquationSet’): the model’s equation

• k1 (float, optional) – Reaction rate for species 1 (X). Defaults to a constant 1 over the domain.

• k2 (float, optional) – Reaction rate for species 2 (X2). Defaults to a constant 1 over the domain.

• species1_name (str, optional) – Name of the first interacting species. Defaults to ‘X’.

• species2_name (str, optional) – Name of the second interacting species. Defaults to ‘X2’.

evaluate(x_in, dt)

Evaluates the source/sink for the coalescence process.

Parameters:

• x_in (Function) – the (mixed) field to be evolved.

• dt (Constant) – the time interval for the scheme.

gusto.physics.microphysics module

Defines microphysics routines to parametrise moist processes for the compressible Euler equations.

class gusto.physics.microphysics.AdvectedMoments(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enumerator describing the moments in the raindrop size distribution.

This stores enumerators for the number of moments used to describe the size distribution curve of raindrops. This can be used for deciding which moments to advect in a precipitation scheme.

M0 = 0

M3 = 1

class gusto.physics.microphysics.Coalescence(equation, cloud_name='cloud_water', rain_name='rain', accretion=True, accumulation=True)

Bases: PhysicsParametrisation

Represents the coalescence of cloud droplets to form rain droplets.

Coalescence is the process of forming rain droplets from cloud droplets. This scheme performs that process, using two parts: accretion, which is independent of the rain concentration, and auto-accumulation, which is accelerated by the existence of rain. These parametrisations come from Klemp and Wilhelmson (1978). The rate of change is limited to prevent production of negative moisture values.

This is only implemented for mixing ratio variables.

Parameters:

• equation (PrognosticEquationSet) – the model’s equation.

• cloud_name (str, optional) – name of the cloud variable. Defaults to ‘cloud_water’.

• rain_name (str, optional) – name of the rain variable. Defaults to ‘rain’.

• accretion (bool, optional) – whether to include the accretion process in the parametrisation. Defaults to True.

• accumulation (bool, optional) – whether to include the accumulation process in the parametrisation. Defaults to True.

evaluate(x_in, dt)

Evaluates the source/sink for the coalescence process.

Parameters:

• x_in (Function) – the (mixed) field to be evolved.

• dt (Constant) – the time interval for the scheme.

class gusto.physics.microphysics.EvaporationOfRain(equation, rain_name='rain', vapour_name='water_vapour', latent_heat=True)

Bases: PhysicsParametrisation

Represents the evaporation of rain into water vapour.

This describes the evaporation of rain into water vapour, with the associated latent heat change. This parametrisation comes from Klemp and Wilhelmson (1978). The rate of change is limited to prevent production of negative moisture values.

This is only implemented for mixing ratio variables, and when the prognostic is the virtual dry potential temperature.

Parameters:

• equation (PrognosticEquationSet) – the model’s equation.

• cloud_name (str, optional) – name of the rain variable. Defaults to ‘rain’.

• vapour_name (str, optional) – name of the water vapour variable. Defaults to ‘water_vapour’.

• latent_heat (bool, optional) – whether to have latent heat exchange feeding back from the phase change. Defaults to True.

Raises:

NotImplementedError – currently this is only implemented for the CompressibleEulerEquations.

evaluate(x_in, dt)

Applies the process to evaporate rain droplets.

Parameters:

• x_in (Function) – the (mixed) field to be evolved.

• dt (Constant) – the time interval for the scheme.

class gusto.physics.microphysics.Fallout(equation, rain_name, domain, transport_method, moments=AdvectedMoments.M3)

Bases: PhysicsParametrisation

Represents the fallout process of hydrometeors.

Precipitation is described by downwards transport of tracer species. This process determines the precipitation velocity from the AdvectedMoments enumerator, which either: (a) sets a terminal velocity of 5 m/s (b) determines a rainfall size distribution based on a Gamma distribution, as in Paluch (1979). The droplets are based on the mean mass of the rain droplets (aka a single-moment scheme).

Outflow boundary conditions are applied to the transport, so the rain will flow out of the bottom of the domain.

This is currently only implemented for “rain” in the compressible Euler equation set. This variable must be a mixing ratio, It is only implemented for Cartesian geometry.

Parameters:

• equation (PrognosticEquationSet) – the model’s equation.

• rain_name (str, optional) – name of the rain variable. Defaults to ‘rain’.

• domain (Domain) – the model’s domain object, containing the mesh and the compatible function spaces.

• transport_method (TransportMethod) – the spatial method used for transporting the rain.

• moments (int, optional) – an AdvectedMoments enumerator, representing the number of moments of the size distribution of raindrops to be transported. Defaults to AdvectedMoments.M3.

evaluate(x_in, dt)

Evaluates the source/sink corresponding to the fallout process.

Parameters:

• x_in (Function) – the (mixed) field to be evolved.

• dt (Constant) – the time interval for the scheme.

class gusto.physics.microphysics.SaturationAdjustment(equation, vapour_name='water_vapour', cloud_name='cloud_water', latent_heat=True, parameters=None)

Bases: PhysicsParametrisation

Represents the phase change between water vapour and cloud liquid.

This class computes updates to water vapour, cloud liquid and (virtual dry) potential temperature, representing the action of condensation of water vapour and/or evaporation of cloud liquid, with the associated latent heat change. The parametrisation follows the saturation adjustment used in Bryan and Fritsch (2002).

Currently this is only implemented for use with mixing ratio variables, and with “theta” assumed to be the virtual dry potential temperature. Latent heating effects are always assumed, and the total mixing ratio is conserved. A filter is applied to prevent generation of negative mixing ratios.

Parameters:

• equation (PrognosticEquationSet) – the model’s equation.

• vapour_name (str, optional) – name of the water vapour variable. Defaults to ‘water_vapour’.

• cloud_name (str, optional) – name of the cloud water variable. Defaults to ‘cloud_water’.

• latent_heat (bool, optional) – whether to have latent heat exchange feeding back from the phase change. Defaults to True.

• parameters (Configuration, optional) – parameters containing the values of gas constants. Defaults to None, in which case the parameters are obtained from the equation.

Raises:

NotImplementedError – currently this is only implemented for the CompressibleEulerEquations.

evaluate(x_in, dt)

Evaluates the source/sink for the saturation adjustment process.

Parameters:

• x_in (Function) – the (mixed) field to be evolved.

• dt (Constant) – the time interval for the scheme.

gusto.physics.physics_parametrisation module

Defines objects to perform parametrisations of physical processes, or “physics”.

“PhysicsParametrisation” schemes are routines to compute updates to prognostic fields that represent the action of non-fluid processes, or those fluid processes that are unresolved. This module contains a set of these processes in the form of classes with “evaluate” methods.

class gusto.physics.physics_parametrisation.PhysicsParametrisation(equation, label_name, parameters=None)

Bases: object

Base class for the parametrisation of physical processes for Gusto.

Parameters:

• equation (PrognosticEquationSet) – the model’s equation.

• label_name (str) – name of physics scheme, to be passed to its label.

• parameters (Configuration, optional) – parameters containing the values of gas constants. Defaults to None, in which case the parameters are obtained from the equation.

abstract evaluate()

Computes the value of physics source and sink terms.

class gusto.physics.physics_parametrisation.SourceSink(equation, variable_name, rate_expression, time_varying=False, method='interpolate')

Bases: PhysicsParametrisation

The source or sink of some variable, described through a UFL expression.

A scheme representing the general source or sink of a variable, described through a UFL expression. The expression should be for the rate of change of the variable. It is intended that the source/sink is independent of the prognostic variables.

The expression can also be a time-varying expression. In which case a function should be provided, taking a Constant as an argument (to represent the time.)

Parameters:

• equation (PrognosticEquationSet) – the model’s equation.

• variable_name (str) – the name of the variable

• rate_expression (ufl.Expr or func) – an expression giving the rate of change of the variable. If a time-varying expression is needed, this should be a function taking a single argument representing the time. Then the time_varying argument must be set to True.

• time_varying (bool, optional) – whether the source/sink expression varies with time. Defaults to False.

• method (str, optional) – the method to use to evaluate the expression for the source. Valid options are ‘interpolate’ or ‘project’. Default is ‘interpolate’.

evaluate(x_in, dt)

Evalutes the source term generated by the physics.

Parameters:

• x_in – (Function): the (mixed) field to be evolved. Unused.

• dt – (Constant): the timestep, which can be the time interval for the scheme. Unused.

gusto.physics.shallow_water_microphysics module

Defines microphysics routines to be used with the moist shallow water equations.

class gusto.physics.shallow_water_microphysics.InstantRain(equation, saturation_curve, time_varying_saturation=False, vapour_name='water_vapour', rain_name=None, gamma_r=1, convective_feedback=False, beta1=None, tau=None, parameters=None)

Bases: PhysicsParametrisation

The process of converting vapour above the saturation curve to rain.

A scheme to move vapour directly to rain. If convective feedback is true then this process feeds back directly on the height equation. If rain is accumulating then excess vapour is being tracked and stored as rain; otherwise converted vapour is not recorded. The process can happen over the timestep dt or over a specified time interval tau.

Parameters:

• equation (PrognosticEquationSet) – the model’s equation.

• saturation_curve (ufl.Expr or func) – the curve above which excess moisture is converted to rain. Is either prescribed or dependent on a prognostic field.

• time_varying_saturation (bool, optional) – set this to True if the saturation curve is changing in time. Defaults to False.

• vapour_name (str, optional) – name of the water vapour variable. Defaults to “water_vapour”.

• rain_name (str, optional) – name of the rain variable. Defaults to None.

• gamma_r (float, optional) – Fraction of vapour above the threshold which is converted to rain. Defaults to one, in which case all vapour above the threshold is converted.

• convective_feedback (bool, optional) – True if the conversion of vapour affects the height equation. Defaults to False.

• beta1 (float, optional) – Condensation proportionality constant, used if convection causes a response in the height equation. Defaults to None, but must be specified if convective_feedback is True.

• tau (float, optional) – Timescale for condensation. Defaults to None, in which case the timestep dt is used.

• parameters (Configuration, optional) – parameters containing the values of gas constants. Defaults to None, in which case the parameters are obtained from the equation.

evaluate(x_in, dt)

Evalutes the source term generated by the physics.

Computes the physics contributions (loss of vapour, accumulation of rain and loss of height due to convection) at each timestep.

Parameters:

• x_in – (:class: ‘Function’): the (mixed) field to be evolved.

• dt – (:class: ‘Constant’): the timestep, which can be the time interval for the scheme.

class gusto.physics.shallow_water_microphysics.SWSaturationAdjustment(equation, saturation_curve, time_varying_saturation=False, vapour_name='water_vapour', cloud_name='cloud_water', convective_feedback=False, beta1=None, thermal_feedback=False, beta2=None, gamma_v=1, time_varying_gamma_v=False, tau=None, parameters=None)

Bases: PhysicsParametrisation

Represents the process of adjusting water vapour and cloud water according to a saturation function, via condensation and evaporation processes.

This physics scheme follows that of Zerroukat and Allen (2015).

Parameters:

• equation (PrognosticEquationSet) – the model’s equation

• saturation_curve (ufl.Expr or func) – the curve which dictates when phase changes occur. In a saturated atmosphere vapour above the saturation curve becomes cloud, and if the atmosphere is sub-saturated and there is cloud present cloud will become vapour until the saturation curve is reached. The saturation curve is either prescribed or dependent on a prognostic field.

• time_varying_saturation (bool, optional) – set this to True if the saturation curve is changing in time. Defaults to False.

• vapour_name (str, optional) – name of the water vapour variable. Defaults to ‘water_vapour’.

• cloud_name (str, optional) – name of the cloud variable. Defaults to ‘cloud_water’.

• convective_feedback (bool, optional) – True if the conversion of vapour affects the height equation. Defaults to False.

• beta1 (float, optional) – Condensation proportionality constant for height feedback, used if convection causes a response in the height equation. Defaults to None, but must be specified if convective_feedback is True.

• thermal_feedback (bool, optional) – True if moist conversions affect the buoyancy equation. Defaults to False.

• beta2 (float, optional) – Condensation proportionality constant for thermal feedback. Defaults to None, but must be specified if thermal_feedback is True. This is equivalent to the L_v parameter in Zerroukat and Allen (2015).

• or (gamma_v (ufl expression) – class: function): The proportion of moist species that is converted when a conversion between vapour and cloud is taking place. Defaults to one, in which case the full amount of species to bring vapour to the saturation curve will undergo a conversion. Converting only a fraction avoids a two-timestep oscillation between vapour and cloud when saturation is tempertature/height-dependent.

• time_varying_gamma_v (bool, optional) – set this to True if the fraction of moist species converted changes in time (if gamma_v is temperature/height-dependent).

• tau (float, optional) – Timescale for condensation and evaporation. Defaults to None, in which case the timestep dt is used.

• parameters (Configuration, optional) – parameters containing the values of constants. Defaults to None, in which case the parameters are obtained from the equation.

evaluate(x_in, dt)

Evaluates the source term generated by the physics.

Computes the phyiscs contributions to water vapour and cloud water at each timestep.

Parameters:

• x_in – (:class: ‘Function’): the (mixed) field to be evolved.

• dt – (:class: ‘Constant’): the timestep, which can be the time interval for the scheme.

Module contents