diff --git a/manual/sphinx/user_docs/running_bout.rst b/manual/sphinx/user_docs/running_bout.rst index 74fa686722..60a481d439 100644 --- a/manual/sphinx/user_docs/running_bout.rst +++ b/manual/sphinx/user_docs/running_bout.rst @@ -82,7 +82,7 @@ run, and produce a bunch of files in the ``data/`` subdirectory. if needed. In some cases the options used have documentation, with a brief explanation of how they are used. In most cases the type the option is used as (e.g. ``int``, ``BoutReal`` or ``bool``) is given. - + - ``BOUT.restart.*.nc`` are the restart files for the last time point. Currently each processor saves its own state in a separate file, but there is experimental support for parallel I/O. For the settings, see @@ -111,17 +111,21 @@ To see some of the other command-line options try "-h":: and see the section on options (:ref:`sec-options`). To analyse the output of the simulation, cd into the ``data`` -subdirectory and start python or IDL (skip to :ref:`Using IDL ` for IDL). +subdirectory and start Python. Analysing the output Using python ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. note:: We now recommend using `xBOUT + ` to analyse BOUT++ + simulations. + In order to analyse the output of the simulation using Python, you will first need to have set up python to use the BOUT++ libraries ``boutdata`` and ``boututils``; see section :ref:`sec-config-python` for how to do this. The analysis routines have some requirements such as SciPy; see section -:ref:`sec-python-requirements` for details. +:ref:`sec-python-requirements` for details. To print a list of variables in the output files, one way is to use the ``DataFile`` class. This is a wrapper around the various NetCDF and HDF5 libraries for python: @@ -152,66 +156,6 @@ The first index of the array passed to ``showdata`` is assumed to be time, amd t indices are plotted. In this example we pass a 2D array ``[t,y]``, so ``showdata`` will animate a line plot. -.. _sec-intro-using-idl: - -Analysing the output using IDL -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First, list the variables in one of the data files: - -.. code-block:: idl - - IDL> print, file_list("BOUT.dmp.0.nc") - iteration MXSUB MYSUB MXG MYG MZ NXPE NYPE BOUT_VERSION t_array ZMAX ZMIN T - -All of these except ’\ ``T``\ ’ are in all output files, and they -contain information about the layout of the mesh so that the data can be -put in the correct place. The most useful variable is ’\ ``t_array``\ ’ -which is a 1D array of simulation output times. To read this, we can use -the ``collect`` function: - -.. code-block:: idl - - IDL> time = collect(var="t_array") - IDL> print, time - 1.10000 1.20000 1.30000 1.40000 1.50000 ... - -The number of variables in an output file depends on the model being -solved, which in this case consists of a single scalar field -’\ ``T``\ ’. To read this into IDL, again use ``collect``: - -.. code-block:: idl - - IDL> T = collect(var="T") - IDL> help, T - T FLOAT = Array[5, 64, 1, 20] - -This is a 4D variable, arranged as ``[x, y, z, t]``. The :math:`x` -direction has 5 points, consisting of 2 points either side for the -boundaries and one point in the middle which is evolving. This case is -only solving a 1D problem in :math:`y` with 64 points so to display an -animation of this - -.. code-block:: idl - - IDL> showdata, T[2,*,0,*] - -which selects the only evolving :math:`x` point, all :math:`y`, the only -:math:`z` point, and all time points. If given 3D variables, showdata -will display an animated surface - -.. code-block:: idl - - IDL> showdata, T[*,*,0,*] - -and to make this a coloured contour plot - -.. code-block:: idl - - IDL> showdata, T[*,*,0,*], /cont - -The equivalent commands in Python are as follows. - .. _sec-run-nls: Natural language support @@ -301,153 +245,149 @@ over this see if there are any important warnings or errors. Each processor outputs its own log file ``BOUT.log.#`` and the log from processor 0 is also sent to the screen. This output may look a little different if it’s out of date, but the general layout will probably be -the same. +the same. The exact order that options are printed in may also vary +between versions and models. First comes the introductory blurb:: - BOUT++ version 1.0 - Revision: c8794400adc256480f72c651dcf186fb6ea1da49 - MD5 checksum: 8419adb752f9c23b90eb50ea2261963c - Code compiled on May 11 2011 at 18:22:37 + BOUT++ version 4.4.0 + Revision: 7cfbc6890a82cb6b3b6c81870d8a8fca723de542 + Code compiled on Dec 7 2021 at 15:14:05 B.Dudson (University of York), M.Umansky (LLNL) 2007 Based on BOUT by Xueqiao Xu, 1999 -The version number (1.0 here) gets increased occasionally after some +The version number (4.4.0 here) gets increased occasionally after some major feature has been added. To help match simulations to code -versions, the Git revision of the core BOUT++ code and the date and time -it was compiled is recorded. Because code could be modified from the -revision, an MD5 checksum of all the code is also calculated. This -information makes it possible to verify precisely which version of the -code was used for any given run. +versions, the Git revision of the core BOUT++ code and the date and +time it was compiled is recorded. This information makes it possible +to verify precisely which version of the code was used for any given +run. + +The processor number comes next:: + + Processor number: 0 of 1 + +This will always be processor number ’0’ on screen as only the output +from processor ’0’ is sent to the terminal. + +The process ID (pid) is also printed:: + + pid: 17835 + +which is useful for distinguishing multiple simulations running at the +same time and, for example, to stop one run if it starts misbehaving. Next comes the compile-time options, which depend on how BOUT++ was configured (see :ref:`sec-compile-bout`):: Compile-time options: - Checking enabled, level 2 - Signal handling enabled - netCDF support enabled - Parallel NetCDF support disabled + Checking enabled, level 2 + Signal handling enabled + netCDF support enabled + Parallel NetCDF support disabled + OpenMP parallelisation disabled + Compiled with flags : "-Wall -Wextra ..." This says that some run-time checking of values is enabled, that the code will try to catch segmentation faults to print a useful error, that -NetCDF files are supported, but that the parallel flavour isn’t. +NetCDF files are supported, but that the parallel flavour isn’t. The +compilation flags are printed, which can be useful for checking if a +run was built with optimisation or debugging enabled. These flags can +be quite long, so we've truncated them in the snippet above. -The processor number comes next:: +The complete command line is printed (excluding any MPI options):: - Processor number: 0 of 1 + Command line options for this run : ./conduction nout=1 -This will always be processor number ’0’ on screen as only the output -from processor ’0’ is sent to the terminal. After this the core BOUT++ -code reads some options:: - - Option /nout = 50 (data/BOUT.inp) - Option /timestep = 100 (data/BOUT.inp) - Option /grid = slab.6b5.r1.cdl (data/BOUT.inp) - Option /dump_float = true (default) - Option /non_uniform = false (data/BOUT.inp) - Option /restart = false (default) - Option /append = false (default) - Option /dump_format = nc (data/BOUT.inp) - Option /StaggerGrids = false (default) +After this the core BOUT++ code reads some options:: + + Reading options file data/BOUT.inp + Option nout = 100 (data/BOUT.inp) overwritten with: + nout = 1 (Command line) + Writing options to file data/BOUT.settings + + Getting grid data from options + Option mesh:type = bout (default) + Option mesh:StaggerGrids = 0 (default) + Option mesh:maxregionblocksize = 64 (default) + Option mesh:calcParallelSlices_on_communicate = 1 (default) + Option mesh:ddz:fft_filter = 0 (default) + Option mesh:symmetricGlobalX = 1 (default) + Option mesh:symmetricglobaly = true (data/BOUT.inp) This lists each option and the value it has been assigned. For every option the source of the value being used is also given. If a value had been given on the command line then ``(command line)`` would appear after the option.:: - Setting X differencing methods - First : Second order central (C2) - Second : Second order central (C2) - Upwind : Third order WENO (W3) - Flux : Split into upwind and central (SPLIT) - Setting Y differencing methods - First : Fourth order central (C4) - Second : Fourth order central (C4) - Upwind : Third order WENO (W3) - Flux : Split into upwind and central (SPLIT) - Setting Z differencing methods - First : FFT (FFT) - Second : FFT (FFT) - Upwind : Third order WENO (W3) - Flux : Split into upwind and central (SPLIT) - -This is a list of the differential methods for each direction. These are -set in the BOUT.inp file (``[ddx]``, ``[ddy]`` and ``[ddz]`` sections), -but can be overridden for individual operators. For each direction, -numerical methods can be specified for first and second central -difference terms, upwinding terms of the form -:math:`{{\frac{\partial f}{\partial t}}} = {{\boldsymbol{v}}}\cdot\nabla f`, -and flux terms of the form -:math:`{{\frac{\partial f}{\partial t}}} = \nabla\cdot({{\boldsymbol{v}}}f)`. -By default the flux terms are just split into a central and an upwinding -term. - -In brackets are the code used to specify the method in BOUT.inp. A list -of available methods is given in :ref:`sec-diffmethod`.:: - - Setting grid format - Option /grid_format = (default) - Using NetCDF format for file 'slab.6b5.r1.cdl' + Option mesh:ddx:first = c2 (data/BOUT.inp) + Option mesh:ddx:second = c2 (data/BOUT.inp) + Option mesh:ddx:upwind = w3 (data/BOUT.inp) + Option mesh:ddy:first = c2 (data/BOUT.inp) + Option mesh:ddy:second = c2 (data/BOUT.inp) + Option mesh:ddy:upwind = w3 (data/BOUT.inp) + Option mesh:ddz:first = fft (data/BOUT.inp) + Option mesh:ddz:second = fft (data/BOUT.inp) + Option mesh:ddz:upwind = w3 (data/BOUT.inp) + +This is a list of the differential methods for each direction. These +are set in the BOUT.inp file (``[mesh:ddx]``, ``[mesh:ddy]`` and +``[mesh:ddz]`` sections), but can be overridden for individual +operators. For each direction, numerical methods can be specified for +first and second central difference terms, upwinding terms of the form +:math:`{{\frac{\partial f}{\partial t}}} = +{{\boldsymbol{v}}}\cdot\nabla f`, and flux terms of the form +:math:`{{\frac{\partial f}{\partial t}}} = +\nabla\cdot({{\boldsymbol{v}}}f)`. By default the flux terms are just +split into a central and an upwinding term. A list of available +methods is given in :ref:`sec-diffmethod`.:: + Loading mesh - Grid size: 10 by 64 - Option /mxg = 2 (data/BOUT.inp) - Option /myg = 2 (data/BOUT.inp) - Option /NXPE = 1 (default) - Option /mz = 65 (data/BOUT.inp) - Option /twistshift = false (data/BOUT.inp) - Option /TwistOrder = 0 (default) - Option /ShiftOrder = 0 (default) - Option /shiftxderivs = false (data/BOUT.inp) - Option /IncIntShear = false (default) - Option /BoundaryOnCell = false (default) - Option /StaggerGrids = false (default) - Option /periodicX = false (default) - Option /async_send = false (default) - Option /zmin = 0 (data/BOUT.inp) - Option /zmax = 0.0028505 (data/BOUT.inp):: - - WARNING: Number of inner y points 'ny_inner' not found. Setting to 32 - -Optional quantities (such as ``ny_inner`` in this case) which are not + Option input:transform_from_field_aligned = 1 (default) + Option mesh:nx = 1 (data/BOUT.inp) + Option mesh:ny = 100 (data/BOUT.inp) + Option mesh:nz = 1 (data/BOUT.inp) + Read nz from input grid file + Grid size: 1 x 100 x 1 + Variable 'MXG' not in mesh options. Setting to 0 + Option mxg = 0 (data/BOUT.inp) + Variable 'MYG' not in mesh options. Setting to 0 + Option MYG = 2 (default) + Guard cells (x,y,z): 0, 2, 0 + Option mesh:ixseps1 = -1 (data/BOUT.inp) + Option mesh:ixseps2 = -1 (data/BOUT.inp) + +Optional quantities (such as ``MXG/MYG`` in this case) which are not specified are given a default (best-guess) value, and a warning is printed.:: - EQUILIBRIUM IS SINGLE NULL (SND) - MYPE_IN_CORE = 0 - DXS = 0, DIN = -1. DOUT = -1 - UXS = 0, UIN = -1. UOUT = -1 - XIN = -1, XOUT = -1 - Twist-shift: + EQUILIBRIUM IS SINGLE NULL (SND) + MYPE_IN_CORE = 0 + DXS = 0, DIN = -1. DOUT = -1 + UXS = 0, UIN = -1. UOUT = -1 + XIN = -1, XOUT = -1 + Twist-shift: At this point, BOUT++ reads the grid file, and works out the topology of the grid, and connections between processors. BOUT++ then tries to read the metric coefficients from the grid file:: - WARNING: Could not read 'g11' from grid. Setting to 1.000000e+00 - WARNING: Could not read 'g22' from grid. Setting to 1.000000e+00 - WARNING: Could not read 'g33' from grid. Setting to 1.000000e+00 - WARNING: Could not read 'g12' from grid. Setting to 0.000000e+00 - WARNING: Could not read 'g13' from grid. Setting to 0.000000e+00 - WARNING: Could not read 'g23' from grid. Setting to 0.000000e+00 + Variable 'g11' not in mesh options. Setting to 1.000000e+00 + Variable 'g22' not in mesh options. Setting to 1.000000e+00 + Variable 'g33' not in mesh options. Setting to 1.000000e+00 + Variable 'g12' not in mesh options. Setting to 0.000000e+00 + Variable 'g13' not in mesh options. Setting to 0.000000e+00 + Variable 'g23' not in mesh options. Setting to 0.000000e+00 These warnings are printed because the coefficients have not been specified in the grid file, and so the metric tensor is set to the -default identity matrix.:: - - WARNING: Could not read 'zShift' from grid. Setting to 0.000000e+00 - WARNING: Z shift for radial derivatives not found +default identity matrix. For this particular example we don't need to +do anything special in the direction parallel to the magnetic field, +so we set the parallel transform to be the identity (see +:ref:`sec-parallel-transforms`):: -To get radial derivatives, the quasi-ballooning coordinate method is -used . The upshot of this is that to get radial derivatives, -interpolation in Z is needed. This should also always be set to FFT.:: - - WARNING: Twist-shift angle 'ShiftAngle' not found. Setting from zShift - Option /twistshift_pf = false (default):: - - Maximum error in diagonal inversion is 0.000000e+00 - Maximum error in off-diagonal inversion is 0.000000e+00 + Option mesh:paralleltransform = identity (default) If only the contravariant components (``g11`` etc.) of the metric tensor are specified, the covariant components (``g_11`` etc.) are calculated @@ -456,85 +396,79 @@ calculated by calculating :math:`g_{ij}g^{jk}` as a check. Since no metrics were specified in the input, the metric tensor was set to the identity matrix, making inversion easy and the error tiny.:: - WARNING: Could not read 'J' from grid. Setting to 0.000000e+00 - WARNING: Jacobian 'J' not found. Calculating from metric tensor:: - - Maximum difference in Bxy is 1.444077e-02 + Variable 'J' not in mesh options. Setting to 0.000000e+00 + WARNING: Jacobian 'J' not found. Calculating from metric tensor + Variable 'Bxy' not in mesh options. Setting to 0.000000e+00 + WARNING: Magnitude of B field 'Bxy' not found. Calculating from metric tensor Calculating differential geometry terms - Communicating connection terms - Boundary regions in this processor: core, sol, target, target, - done:: + Communicating connection terms + Boundary regions in this processor: upper_target, lower_target, + Constructing default regions - Setting file formats - Using NetCDF format for file 'data/BOUT.dmp.0.nc' - -The laplacian inversion code is initialised, and prints out the options -used.:: +The Laplacian inversion (see :ref:`sec-laplacian`) code is +initialised, and prints out the options used.:: Initialising Laplacian inversion routines - Option comms/async = true (default) - Option laplace/filter = 0.2 (default) - Option laplace/low_mem = false (default) - Option laplace/use_pdd = false (default) - Option laplace/all_terms = false (default) - Option laplace/laplace_nonuniform = false (default) - Using serial algorithm - Option laplace/max_mode = 26 (default) + Option phiboussinesq:async = 1 (default) + Option phiboussinesq:filter = 0 (default) + Option phiboussinesq:maxmode = 128 (default) + Option phiboussinesq:low_mem = 0 (default) + Option phiboussinesq:nonuniform = 1 (default) + Option phiboussinesq:all_terms = 1 (default) + Option phiboussinesq:flags = 0 (delta_1/BOUT.inp) After this comes the physics module-specific output:: Initialising physics module - Option solver/type = (default) - . - . - . + Option solver:type = cvode (default) -This typically lists the options used, and useful/important -normalisation factors etc. +This typically lists the options used, useful/important normalisation +factors, and so on. Finally, once the physics module has been initialised, and the current values loaded, the solver can be started:: Initialising solver - Option /archive = -1 (default) - Option /dump_format = nc (data/BOUT.inp) - Option /restart_format = nc (default) - Using NetCDF format for file 'nc':: + Option datadir = delta_1 () + Option dump_format = nc (default) + Option restart_format = nc (default) + Using NetCDF4 format for file 'delta_1/BOUT.restart.nc' - Initialising PVODE solver - Boundary region inner X - Boundary region outer X - 3d fields = 2, 2d fields = 0 neq=84992, local_N=84992 + Constructing default regions + Boundary region inner X + Boundary region outer X + 3d fields = 2, 2d fields = 0 neq=100, local_N=100 This last line gives the number of equations being evolved (in this case -84992), and the number of these on this processor (here 84992).:: - - Option solver/mudq = 16 (default) - Option solver/mldq = 16 (default) - Option solver/mukeep = 0 (default) - Option solver/mlkeep = 0 (default) +100), and the number of these on this processor (here 100).:: The absolute and relative tolerances come next:: - Option solver/atol = 1e-10 (data/BOUT.inp) - Option solver/rtol = 1e-05 (data/BOUT.inp):: + Option solver:atol = 1e-12 (default) + Option solver:rtol = 1e-05 (default) - Option solver/use_precon = false (default) - Option solver/precon_dimens = 50 (default) - Option solver/precon_tol = 0.0001 (default) - Option solver/mxstep = 500 (default):: +This next option specifies the maximum number of internal timesteps +that CVODE will take between outputs.:: - Option fft/fft_measure = false (default) + Option solver:mxstep = 500 (default) -This next option specifies the maximum number of internal timesteps -which CVODE will take between outputs.:: +After (almost!) all of the options are read in, the simulation proper +starts:: - Option fft/fft_measure = false (default) Running simulation - Run started at : Wed May 11 18:23:20 2011 + Run ID: 332467c7-1210-401a-b44c-f8a3a3415827 + + Run started at : Tue 07 Dec 2021 17:50:39 GMT + +The ``Run ID`` here is a `universally unique identifier +` (UUID) +which is a random 128-bit label unique to this current +simulation. This makes it easier to identify all of the associated +outputs of a simulation, and record the data for future reference. - Option /wall_limit = -1 (default) +A few more options may appear between these last progress messages and +the per-timestep output discussed in the next section. Per-timestep output ------------------- @@ -586,47 +520,36 @@ of the command, for example:: Equivalently, put “restart=true” near the top of the BOUT.inp input file. Note that this will overwrite the existing data in the -“BOUT.dmp.\*.nc” files. If you want to append to them instead then add +``BOUT.dmp.\*.nc`` files. If you want to append to them instead then add the keyword append to the command, for example:: $ mpirun -np 2 ./conduction restart append -or also put “append=true” near the top of the BOUT.inp input file. +or also put ``append=true`` near the top of the BOUT.inp input file. When restarting simulations BOUT++ will by default output the initial state, unless appending to existing data files when it will not output until the first timestep is completed. To override this behaviour, you -can specify the option dump\_on\_restart manually. If dump\_on\_restart +can specify the option ``dump_on_restart`` manually. If ``dump_on_restart`` is true then the initial state will always be written out, if false then -it never will be (regardless of the values of restart and append). - -If you need to restart from a different point in your simulation, or the -BOUT.restart files become corrupted, you can either use archived restart -files, or create new restart files. Archived restart files have names -like “BOUT.restart\_0020.#.nc”, and are written every 20 outputs by -default. To change this, set “archive” in the BOUT.inp file. To use -these files, they must be renamed to “BOUT.restart.#.nc”. A useful tool -to do this is “rename”:: - - $ rename 's/_0020//' *.nc - -will strip out “\_0020” from any file names ending in “.nc”. +it never will be (regardless of the values of ``restart`` and ``append``). -If you don’t have archived restarts, or want to start from a different -time-point, there are Python routines for creating new restart files. If -your PYTHONPATH environment variable is set up (see -:ref:`sec-configanalysis`) then you can use the -``boutdata.restart.create`` function in -``tools/pylib/boutdata/restart.py``: +If you need to restart from a different point in your simulation, or +the ``BOUT.restart`` files become corrupted, you can use `xBOUT +` to create new restart files +from any time-point in your output files. Use the `.to_restart() +` +method: .. code-block:: pycon - >>> from boutdata.restart import create - >>> create(final=10, path='data', output='.') + >>> import xbout + >>> df = xbout.open_boutdataset("data/BOUT.dmp.*.nc") + >>> df.bout.to_restart(tind=10) -The above will take time point 10 from the BOUT.dmp.\* files in the -“data” directory. For each one, it will output a BOUT.restart file in -the output directory “.”. +The above will take time point 10 from the ``BOUT.dmp.*.nc`` files in +the ``data`` directory. For each one, it will output a +``BOUT.restart.*.nc`` file in the output directory ``.``. Stopping simulations -------------------- diff --git a/src/solver/solver.cxx b/src/solver/solver.cxx index 8d035ee2de..79e0c20bd1 100644 --- a/src/solver/solver.cxx +++ b/src/solver/solver.cxx @@ -423,7 +423,8 @@ void Solver::constraint(Vector3D& v, Vector3D& C_v, std::string name) { **************************************************************************/ int Solver::solve(int NOUT, BoutReal TIMESTEP) { - + output_progress.write(_("Initialising solver\n")); + Options& globaloptions = Options::root(); // Default from global options if (NOUT < 0) { @@ -586,8 +587,6 @@ int Solver::init(int UNUSED(nout), BoutReal UNUSED(tstep)) { if (initialised) throw BoutException(_("ERROR: Solver is already initialised\n")); - output_progress.write(_("Initialising solver\n")); - NPES = BoutComm::size(); MYPE = BoutComm::rank();