# Code layout¶

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. 21 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 main thing bout_solve does is to add these variables to the solver.

The process of running a timestep is shown in blue in Fig. 21: 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. 22 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.

## Directories¶

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 impls.

include/foo.hxx
src/.../foo.cxx
src/.../foo_factory.hxx
src/.../foo_factory.cxx
src/.../impls/one/one.hxx
src/.../impls/one/one.cxx


where 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 subdirectories of impls. Components which follow this pattern include fileio formats, invert/laplace and invert/parderiv inversion codes, mesh, and solver.

The current source code files are:

• bout++.cxx: Main file which initialises, runs and finalises BOUT++. Currently contains a main function, though this is being removed shortly.

• field

• fileio

• invert

• fft_fftw.cxx implements the fft.hxx interface by calling the Fastest Fourier Transform in the West (FFTW) library.

• invert / laplace

• invert_laplace.cxx uses Fourier

decomposition in $$z$$ combined with tri- and band-diagonal solvers in $$x$$ to solve Laplacian problems.

• impls

• serial_tri

• serial_band

• spt

• invert / parderiv

• invert_parderiv.cxx inverts a problem involving only parallel $$y$$ derivatives. Intended for use in some preconditioners.

• impls

• cyclic

• lapack_routines.cxx supplies an

interface to the LAPACK linear solvers, which are used by the invert_laplace routines.

• mesh

• physics

• solver

• sys

• boutcomm.cxx

• boutexception.cxx is an exception class which are used for error handling

• derivs.cxx contains basic derivative methods such as upwinding, central difference and WENO methods. These are then used by difops.cxx. Details are given in section Differential operators.

• 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.