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.6are supported) -
BOUT++, which can installed as stated in the manual, or by usingbout_install
Installing
The package can be installed from pip
pip install bout-runnersOr from source
python setup.py installAfter installation you can optionally call
bout_runners_configin 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 pytestor
pip install codecov pytest-covand run with
pytestor
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
