Introduction ============= .. contents:: Heritage and purpose -------------------- *BETR-Research* is a framework to model the fate- and transport of semivolatile organic chemicals in the environment. It is written around a re-implementation of the well known *Berkeley-Trent global contaminant fate model* (`BETR-Global `_) by `Matt MacLeod `_ that has been used in `various scientific studies `_. The original implementation of BETR-Global takes the form of a Microsoft Excel macro written in Visual Basic and this implementation is referred to as *BETR-VBA* here. *BETR-VBA* it works without any installation procedure on Microsoft Windows computers with MS Office installed, and only there. Its user interface (Excel) is familiar to many people and it produces nicely formatted output. *BETR-Research* on the other hand is implemented in Python, is platform independent, has a command-line user interface, and the formatting and analysis of the output is largely left to the user. It runs about 20 times faster than *BETR-VBA*. It has been successfully :doc:`validated ` against *BETR-VBA* and yields identical results. A design criterion of *BETR-Research* was its usability in a research context. It should be easy to modify and extend the model to explore new research questions. It is simple to use the model inside a batch script, for example to simulate many different chemicals or parameterizations. The output is directly available in Python data structures to facilitate post-processing, for example for sensitivity analysis and visualization. It is designed to be modular, yet consciously forgoes object-oriented techniques in favor of a simple code structure that is hopefully comprehensible to anyone familiar with a procedural programming language like Fortran, C, or BASIC. Next to the re-implementation of BETR-Global, *BETR-Research* is a framework to define completely new models, with arbitrary regions, compartments and transport processes. This framework can for example be used as a teaching tool to have students implement a simple model and experiment with it. Structure of BETR-Global -------------------------- This section briefly describes the BETR-Global model as implemented in the *BETR-Research* framework. More information can be found on the `BETR-VBA website `_. .. _spatial_grid: Spatial discretization `````````````````````` BETR-Global's world is discretized on a 15° x 15° grid. The grid cells are numbered from 1 to 288: .. figure:: images/BETRGRID.png :align: center :alt: BETR-grid The spatial discretization of BETR-Global into 288 regions. Compartments ```````````` Each region can contain up to 7 homogeneous compartments. Compartments can contain sub-compartments which are in equilibrium among each other. For example there are aerosols in the lower air compartment, biota and suspended particles in the oceans and air, water and solids in the soil compartment. .. figure:: images/Compartments.png :align: center :alt: The compartments of BETR-GLobal Compartments of BETR-Global A particular compartment in a particular regions is called a *cell* here. The contaminant fugacities in the cells are the model's the state-variables. Mathematical formulation ```````````````````````` Degradation of chemicals in cells and transport of chemicals between compartments are modelled as first-order processes. The transport equation for convective-dispersive tranport in water and air is discretised in space. The spatial derivatives are approximated using two-point upwind differencing to yield a system of ordinary differential equations that describe the mass-balance of chemical in the global environment. Environmental conditions are assumed to be constant during each month of the year. The whole model can then be expressed as a system of first order linear ordinary differential equations with piecewise constant coeffcients: .. math:: \frac{d\mathbf{m}}{dt}=A_m\mathbf{m} + \mathbf{q}\ \ \ \ \ \ (1) where **f** is the vector of contaminant masses in all cells, *A* :subscript:`m` is a square matrix containing the mass rate-constants of transport/degradation during month m, and **q** is the emission vector. To calculate a (pseudo) steady-state solution, environmental conditions are assumed constant throughout the year and the solution just involves inverting *A*: .. math:: \mathbf{m}_\mathrm{ss} = -A^{-1}\mathbf{q}\ \ \ \ \ \ (2) Numerical Integration of (1) yields the dynamic solution. The actual scientific core of the model is contained in the calculation of the elements of *A*. The ultimate reference are the process descriptions in the module processes.py. General concepts about fugacity based modelling are nicely explained in [MACKAY2001]_.