BOUT++ is organised into classes and groups of functions which operate on them: It’s not purely object-oriented, but takes advantage of many of C++’s object-oriented features.
Fig. 20 shows the most important parts of BOUT++ and how they fit together.
The initialisation process is shown in red: basic information is first
read from the grid file (e.g. size of the grid, topology etc.), then
the user-supplied initialisation code is called. This code can read
other variables from the grid, and makes at least one call to
PhysicsModel::bout_solve() to specify a variable to be evolved. The
bout_solve does is to add
these variables to the solver.
The process of running a timestep is shown in blue in
Fig. 20: The main loop calls the solver, which in turn
calls PVODE. To evolve the system PVODE makes calls to the RHS
function inside solver. This moves data between PVODE and BOUT++, and
calls the user-supplied
PhysicsModel::rhs() code to calculate
time-derivatives. Much of the work calculating time-derivatives
involves differential operators.
Calculation of the
RHS function, and handling of
data in BOUT++ involves many different
components. Fig. 21 shows (most) of the classes and
functions involved, and the relationships between them. Some thought
was put into how this should be organised, but it has also changed
over time, so some parts could be cleaner.
The source code for the core of BOUT++ is divided into include files
(which can be used in physics models) in
bout++/include, and source
code and low-level includes in
bout++/src. Many parts of the code
are defined by their interface, and can have multiple different
implementations. An example is the time-integration solvers: many
different implementations are available, some of which use external
libraries, but all have the same interface and can be used
interchangeably. This is reflected in the directory structure inside
bout++/src. A common pattern is to store individual implementations
of an interface in a subdirectory called
include/foo.hxx src/.../foo.cxx src/.../foo_factory.hxx src/.../foo_factory.cxx src/.../impls/one/one.hxx src/.../impls/one/one.cxx
foo.hxx defines the interface,
foo.cxx implements common
functions used in several implementations.
foo_factory creates new
implementations, and is the only file which includes all the
implementations. Individual implementations are stored in their own
impls. Components which follow this pattern
The current source code files are:
Field2Dclass. This is a scalar field which varies only in \(x\) and \(y\) and is used for things like metric tensor components and initial profiles. It supplies lots of overloaded operators and functions on these objects.
Field3Dclass, which varies in \(x\), \(y\) and \(z\). Since these handle a lot more memory than Field2D objects, the memory management is more complicated and includes reference counting. See section Memory management for more details.
Implements some functions in the
FieldDataclass. This is a mainly pure virtual interface class which is inherited by
FieldPerpclass to store slices perpendicular to the magnetic field i.e. they are a function of \(x\) and \(z\) only. This is mainly used for Laplacian inversion routines, and needs to be integrated with the other fields better.
- initialprofiles.cxx routines to set the initial values of fields when a simulation first starts. Reads settings from the option file based on the name of the variable.
- vecops.cxx a
collection of function to operate on vectors. Contains things
Curl, and uses a combination of field differential operators (in difops.cxx) and metric tensor components (in
Vector2Dclass, which uses a
Field2Dobject for each of its 3 components. Overloads operators to supply things like dot and cross products.
Vector3Dby using a
Field3Dobject for each component.
- where.cxx supplies functions for choosing between values based on selection criteria.
- field2d.cxx implements the
invert / laplace
invert / parderiv
- lapack_routines.cxx supplies an
interface to the LAPACK linear solvers, which are used by the
boundary_standard.cxx implements some standard boundary operations and modifiers such as
interpolation.cxx contains functions for interpolating fields
boutexception.cxx is an exception class which are used for error handling
msg_stack.cxx is part of the error handling system. It maintains a stack of messages which can be pushed onto the stack at the start of a function, then removed (popped) at the end. If an error occurs or a segmentation fault is caught then this stack is printed out and can help to find errors.
options.cxx provides an interface to the BOUT.inp option file and the command-line options.
stencils.cxx contains methods to operate on stencils which are used by differential methods.
utils.cxx contains miscellaneous small useful routines such as allocating and freeing arrays.