BOUT++

.______     ______    __    __  .___________.
|   _  \   /  __  \  |  |  |  | |           |  _     _
|  |_)  | |  |  |  | |  |  |  | `---|  |----`_| |_ _| |_
|   _  <  |  |  |  | |  |  |  |     |  |    |_   _|_   _|
|  |_)  | |  `--'  | |  `--'  |     |  |      |_|   |_|
|______/   \______/   \______/      |__|

BOUT++ is a framework for writing fluid and plasma simulations in curvilinear geometry. It is intended to be quite modular, with a variety of numerical methods and time-integration solvers available. BOUT++ is primarily designed and tested with reduced plasma fluid models in mind, but it can evolve any number of equations, with equations appearing in a readable form.

For example, the following set of equations for magnetohydrodynamics (MHD):

can be written simply as:

ddt(rho) = -V_dot_Grad(v, rho) - rho*Div(v);
ddt(p)   = -V_dot_Grad(v, p) - g*p*Div(v);
ddt(v)   = -V_dot_Grad(v, v) + (cross(Curl(B),B) - Grad(p))/rho;
ddt(B)   = Curl(cross(v,B));

The full code for this example can be found in the orszag-tang example.

Jointly developed by University of York (UK), LLNL, CCFE, DCU, DTU, and other international partners.

Homepage found at http://boutproject.github.io/

Table of Contents

• Requirements
• Usage and installation
• Terms of use
• Overview of files
• Contributing
• License

Requirements

BOUT++ needs the following:

• A C++11 compiler (GCC must be at least 4.9)
• MPI
• Either NetCDF or HDF5

Note that some of the tests require NetCDF rather than HDF5

BOUT++ has the following optional dependencies:

• FFTW3 (strongly recommended!)
• OpenMP
• PETSc
• SLEPc
• ARKODE
• IDA
• CVODE
• MUMPS
• LAPACK
• Score-p (for performance diagnostics)

Usage and installation

Please see the users manual

Terms of use

BOUT++ is released under the LGPL, but since BOUT++ is a scientific code we also ask that you show professional courtesy when using this code:

1. Since you are benefiting from work on BOUT++, we ask that you submit any improvements you make to the code to us by submitting a pull request to this repository
2. If you use BOUT++ results in a paper or professional publication, we ask that you send your results to one of the BOUT++ authors first so that we can check them. It is understood that in most cases if one or more of the BOUT++ team are involved in preparing results then they should appear as co-authors.
3. If you use BOUT++ in your work, please help ensure that all the authors get the credit they deserve by citing BOUT++, preferably using the DOI of the version you used. See the file CITATION.cff for details. In addition, you may also cite either of the two main papers: B. Dudson et al, Comp. Phys. Comm. 2009, and B. Dudson et al, Phys. of Plasmas 2016

You can convert the CITATION.cff file into a Bibtex file as follows:

pip3 install --user cffconvert
cffconvert -if CITATION.cff -f bibtex -of CITATION.bib

Overview of files

This directory contains

• bin Files for setting the BOUT++ configuration

• examples Example models and test codes

• externalpackages External packages needed for installing BOUT++

• include Header files used in BOUT++

• manual Manuals and documentation (also doxygen documentation)

• src The main code directory

• CITATION Contains the paper citation for BOUT++

• LICENSE LGPL license

• LICENSE.GPL GPL license

• tools Tools for helping with analysis, mesh generation, and data managment

  • archiving Routines for managing input/output files e.g. compressing data, converting formats, and managing runs

  • cyl_and_helimak_grids IDL codes for generating cylindrical and helimak grids

  • eigensolver Matlab routines for solving eigenmodes

  • idllib Analysis codes in IDL. Add this to your IDL_PATH environment variable

  • line_tracing IDL routines for line tracing of field lines

  • line_tracing_v2 Newer version of the IDL routines for line tracing of field lines

  • mathematicalib Library for post processing using Mathematica

  • matlablib Library for post processing using MATLAB

  • numlib Numerical IDL routines

  • octave Routines for post processing using octave

  • plasmalib IDL routines for calculation of plasma parameters

  • pdb2idl Library to read Portable Data Binary (PDB) files into IDL

  • pylib Analysis codes in Python

    • boutdata Routines to simplify accessing BOUT++ output
    • boututils Some useful routines for accessing and plotting data
    • bout_runners A python wrapper to submit several runs at once (either on a normal computer, or through a PBS system)
    • post_bout Routines for post processing in BOUT++

  • slab IDL routine for grid generation of a slab

  • tokamak_grids Code to generate input grids for tokamak equilibria

    • gridgen Grid generator in IDL. Hypnotoad GUI for converting G-EQDSK files into a flux-aligned orthogonal grid.
    • elite Convert ELITE .eqin files into an intermediate binary file
    • gato Convert DSKGATO files into intermediate binary format
    • all Convert the intermediate binary file into BOUT++ input grid
    • coils Routines for calculating the field due to external RMP coils and adding to existing equilibria
    • cyclone Generate cyclone test cases (concentric circle "equilibrium" for local flux-surface calculations)
    • py_gridgen Translation" into python of the corresponding IDL routines in the folder gridgen
    • shifted_circle Produce shifted cirle equilibria input grids

Contributing

See CONTRIBUTING.md.

License

Copyright 2010 B.D.Dudson, S.Farley, M.V.Umansky, X.Q.Xu

BOUT++ is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

BOUT++ is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

A copy of the LGPL license is in LICENSE. Since this is based on (and refers to) the GPL, this is included in LICENSE.GPL.

Some of the autoconf macros under m4 are licensed under GPLv3. These are not necessary to either build or run BOUT++, but are used in the creation of configure from configure.ac, and are provided as a courtesy to developers. You are free to substitute them with other autoconf macros that provide equivalent functionality.

BOUT++ links by default with some GPL licensed libraries. Thus if you compile BOUT++ with any of them, BOUT++ will automatically be licensed as GPL. Thus if you want to use BOUT++ with GPL non-compatible code, make sure to compile without GPLed code.