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.

Overview of BOUT++ control flow

Fig. 21 Overview of BOUT++ control flow during initialisation (red), and running (blue)#

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.

Relationships used in calculating the RHS function

Fig. 22 Relationship between important classes and functions used in calculating the RHS function#

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

    • field2d.cxx implements the Field2D class. 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.

    • field3d.cxx implements the Field3D class, 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.

    • field_data.cxx Implements some functions in the FieldData class. This is a mainly pure virtual interface class which is inherited by Field2D and Field3D.

    • fieldperp.cxx implements a FieldPerp class 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 like Grad, Div and Curl, and uses a combination of field differential operators (in difops.cxx) and metric tensor components (in Mesh).

    • vector2d.cxx implements the Vector2D class, which uses a Field2D object for each of its 3 components. Overloads operators to supply things like dot and cross products.

    • vector3d.cxx implements Vector3D by using a Field3D object for each component.

    • where.cxx supplies functions for choosing between values based on selection criteria.

  • invert

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

  • invert / laplace

  • invert / parderiv

  • lapack_routines.cxx supplies an

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

  • mesh

    • boundary_factory.cxx creates boundary condition operators which can then be applied to fields. Described in section Boundary factory.

    • boundary_region.cxx implements a way to describe and iterate over boundary regions. Created by the mesh, and then used by boundary conditions. See section Boundary regions for more details.

    • boundary_standard.cxx implements some standard boundary operations and modifiers such as Neumann and Dirichlet.

    • difops.cxx is a collection of differential operators on scalar fields. It uses the differential methods in derivs.cxx and the metric tensor components in Mesh to compute operators.

    • interpolation.cxx contains functions for interpolating fields

    • mesh.cxx is the base class for the Mesh object. Contains routines useful for all Mesh implementations.

    • impls

  • physics

  • solver

    • solver.cxx is the interface for all solvers

    • impls

      • cvode

      • ida

        • ida.cxx is the implementation which interfaces with the SUNDIALS IDA library

        • ida.hxx

      • petsc

      • pvode

        • pvode.cxx interfaces with the 1998 (pre-SUNDIALS) version of PVODE (which became CVODE).

        • pvode.hxx

  • sys