Edit on GitHub

Terminology

The ClimateMachine documentation uses terminology from several disciplines. Below are some definitions of some of these terms. Please let us know via a github issue if there are other terms that are unclear or confusing to you.

Software terms

  • Driver file: a julia script which (a) specifies which BalanceLaw is being used, (b) specifies changes to the default version of that model, (c) specifies initial and boundary conditions, (d) specifies numerical details related to timestep, grid, and frequency of output, and (e) runs the integration. Examples can be found in tutorials and experiments.
  • Source file: a julia file containing code involved in implementing the choices made in a driver file. This is where the numerical methods related to solving the equations (e.g. the ODE time steppers, or the creation of the grid) are defined. Users typically only interact with functions defined in source code within a driver file by using arguments to those functions, unless they wish to develop the source code itself.
  • Kernel: Functions which are launched on the compute device (i.e., the CPU or GPU) and run with an array of workitems or threads. ClimateMachine.jl uses KernelAbstractions.jl as its kernel language.
  • Callback: Functions executed by the ODE integrator after each time step; see solve!. This allows the ability to inject custom behavior into the ODE integrators, such as diagnostic output, visualization, and apply filtering to the numerical solution. Several convenience functions exists specifying callback frequency: number of simulation steps, every X simulation time, and every X wall clock seconds. The callback mechanism is inspired by the callback mechanism of DifferentialEquations.jl.

Numerics

  • Balance Law: The system of PDEs being solved, expressed in a particular form amenable to DG methods. Please see the how-to-guide or the API.
  • Courant number: The ratio of the distance sound waves, diffusion, and other physical processes in your model travel or carry information in a timestep, relative to the resolution of your spatial discretization. This can typically be written in terms of physical constants, the grid size, and the time step, and is used for determining stability of ODE time steppers.
  • CFL limit: A maximum value for the Courant number in order to guarantee convergence to the true solution. Given a spatial discretization, this determines the maximum timestep that can be used. The value of the CFL limit depends on the ODE solving algorithm used.

Physics

  • Diurnal variation: A periodic variation in Earth processes driven by the rotation of the Earth. Examples include heating of the Earth's surface due to solar radiation, or the semi-diurnal tidal cycle.
  • Shortwave radiation: This refers to solar radiation, with intensity peaking in the visible part of the spectrum.
  • Longwave radiation: This refers to the emitted infrared radiation of the Earth surface or atmosphere.
  • Advection/advective flux: Advection is movement of some material/quantity by the bulk velocity of a fluid. In the BalanceLaw language, the advective flux of a prognostic variable is a first order flux.
  • Diffusion/diffusive flux: Diffusion describes a process in which a material or quantity is moved, or approximated as moved, due to random motion of particles. More generally, a diffusive flux is one generated by a gradient in concentration, temperature, or another quantity. A diffusive flux is a second order flux in the BalanceLaw framework.
  • Hyperdiffusion: an explicit higher-order flux term representing horizontal diffusion. The ClimateMachine hyperdiffusive flux uses a fourth-order derivative, but it is included in a second order flux. It enforces the flow of enstrophy absorption at the smallest resolution, and models dissipation effects.

Documentation

  • APIs: This section details the parts of the source code that are visible to users wanting to run models and explains how to interact with and call them. API stands for application programming interface; from Wikipedia, "It defines the kinds of calls or requests that can be made, how to make them, the data formats that should be used, the conventions to follow, etc."
  • Tutorials: Driver files with concrete examples showing how to run simple land, ocean, and atmosphere models, or how to use certain numerical functions.
  • Experiments: Driver files with more complex models. These could be considered the starting point for research; they are not a part of the docs as they are constantly being updated.
  • How-to-guide: Code and explanations for components used in models.