---

Manage your BOUT++ runs through python

Overview

BOUT Runners is a package to manage and orchestrate your BOUT++ runs. More specifically it's a tool:

• That automatically makes your project
• Where you can override default parameters, and parameters found in BOUT.inp
• Where you can submit a single run, or even a chain of runs either locally, or to a cluster
• That automatically stores parameters and other metadata in a database (inspired by sacred)
• Logs the entire process

Read the full documentation at ReadTheDocs

Getting Started

The simplest way to use BOUT Runners is by executing the following script in the root of your project directory (usually where your Makefile resides). In this example we are using BOUT-dev/examples/conduction as the root

from bout_runners.runner.bout_runner import BoutRunner
BoutRunner().run()

The metadata from all the runs from this project can be found by executing

from bout_runners.metadata.status_checker import StatusChecker
status_checker = StatusChecker()
status_checker.check_and_update_status()
from bout_runners.metadata.metadata_reader import MetadataReader
metadata_reader = MetadataReader()
metadata = metadata_reader.get_all_metadata()

The metadata variable is a DataFrame, and contains the following table

	run.id	run.latest_status	run.name	run.start_time	run.stop_time	run.submitted_time	all_boundaries.evolve_bndry	conduction.chi	file_modification.bout_git_sha	file_modification.bout_lib_modified	file_modification.project_executable_modified	file_modification.project_git_sha	file_modification.project_makefile_modified	global.append	global.async_send	global.datadir	global.dump_format	global.dump_on_restart	global.incintshear	global.mxg	global.myg	global.non_uniform	global.nout	global.optionfile	global.periodicx	global.restart	global.restart_format	global.settingsfile	global.stopcheck	global.timestep	global.twistshift	global.wall_limit	global.zmax	global.zmin	input.transform_from_field_aligned	mesh.calcparallelslices_on_communicate	mesh.dy	mesh.extrapolate_x	mesh.extrapolate_y	mesh.ixseps1	mesh.ixseps2	mesh.maxregionblocksize	mesh.nx	mesh.ny	mesh.nz	mesh.paralleltransform	mesh.staggergrids	mesh.symmetricglobalx	mesh.symmetricglobaly	mesh.type	mesh_ddz.fft_filter	output.enabled	output.floats	output.flush	output.flushfrequency	output.guards	output.init_missing	output.openclose	output.parallel	output.shiftinput	output.shiftoutput	restart.enabled	restart.floats	restart.flush	restart.flushfrequency	restart.guards	restart.init_missing	restart.openclose	restart.parallel	restart.shiftinput	restart.shiftoutput	solver.adams_moulton	solver.atol	solver.cvode_max_order	solver.cvode_stability_limit_detection	solver.diagnose	solver.func_iter	solver.is_nonsplit_model_diffusive	solver.max_timestep	solver.maxl	solver.min_timestep	solver.mms	solver.mms_initialise	solver.monitor_timestep	solver.mxorder	solver.mxstep	solver.nout	solver.output_step	solver.rtol	solver.start_timestep	solver.type	solver.use_jacobian	solver.use_precon	solver.use_vector_abstol	split.number_of_nodes	split.number_of_processors	split.processors_per_node	system_info.machine	system_info.node	system_info.processor	system_info.release	system_info.system	system_info.version	t.bndry_all	t.evolve_bndry	t.function	t.scale
0	1	complete	2020-06-09_07-14-39_981268	2020-06-09 07:14:53	2020-06-09 07:14:56	2020-06-09 07:14:52.943486	0	1.0	22c888152e49003c34723a2638504aabc25d87ba	2020-02-03 20:03:02.000000	2020-06-09 07:14:39.631118	22c888152e49003c34723a2638504aabc25d87ba	2020-02-03 19:48:41.000000	0	0	/root/bout-dev/examples/conduction/settings_run	nc	1	0	0	2	1	0	bout.inp	0	0	nc	bout.settings	0	0.1	0	-1	1	0	1	1	0.2	0	0	-1	-1	64	1	100	1	identity	0	1	1	bout	0	1	0	1	1	1	0	1	0	0	0	1	0	1	1	1	0	1	0	0	0	0	1e-12	-1	0	0	0	1	-1	5	-1	0	0	0	-1	500	0	0.1	1e-05	-1	cvode	0	0	0	1	1	1	x86_64	0f17950a0dcc		4.19.76-linuxkit	Linux	#1 SMP Tue May 26 11:42:35 UTC 2020	dirichlet_o4(0.0)	0	gauss(y-pi, 0.2)	1.0

Prerequisites

• Python (versions above 3.6 are supported)
• BOUT++, which can installed as stated in the manual, or by using bout_install

Installing

The package can be installed from pip

pip install bout-runners

Or from source

python setup.py install

After installation you can optionally call

bout_runners_config

in order to setup the path to your BOUT++ installation and to configure other parameters like logging.

Running the tests

The test suite can be executed through pytest or through codecov pytest-cov. Installation through

pip install pytest

or

pip install codecov pytest-cov

and run with

pytest

or

pytest --cov=./

respectively

Contributing

Please read CONTRIBUTING.rst for details about how to contribute.

Authors

• Michael Løiten - Initial work

See also the list of contributors who participated in this project.

License

This project is licensed under the GNU LESSER GENERAL PUBLIC LICENSE - see the LICENSE file for details

Acknowledgments

• The BOUT++ team for fast and accurate response on the BOUT++ issue tracker and slack-channel