batread 1.0

Read BATSRUS output and related Tecplot ASCII .dat and binary .plt datasets

The batread project is a Python library for reading SWMF/BATSRUS output and related Tecplot ASCII .dat and binary .plt datasets. The project also includes a use case in the form of a quicklook command, bat-quick, for visualising two-dimensional SWMF/BATSRUS output.

Installation

After cloning this repository, the project may be installed with pip in the regular way:

cd <project>
pip install .

This installs the reader functionality only. To use the quicklook plotting command, install the graphics extra:

pip install .[graphics]

Python code to access file data

This code reads a dataset named <file> and stores the dataset variable named Rho [g/cm^3] in a local variable named density_g_cm3.

from batread.dataset import Dataset
ds = Dataset.from_file('<file>')
print(ds)
density_g_cm3 = ds('Rho [g/cm^3]')

Running the quicklook command

A simple 'quicklook' shell command is included which permits plotting of two-dimensional slices of the SWMF/BATSRUS results. Irregularly gridded data is accepted. The quicklook command uses the plot function in basicplot.py but this may be extended by the user.

The quicklook command requires the graphics extra:

pip install .[graphics]

To create a quicklook .png file from the included file examples/x=0_var_2_n00000000.plt run

cd examples
bat-quick x=0_var_2_n00000000.plt

This will create a file named ql-x-0-var-2-n00000000-plt-rho-g-cm-3.png; the name comprises the prefix ql, the file name, and the name of the plotted variable. Non-alphanumeric characters are normalised to dashes in the output file name.

A wildcard pattern may be used; in this case one .png file is created for each file matching the wildcard pattern:

bat-quick x*.plt

Development and testing

To install the project in editable mode and enable testing do

cd <project>
pip install --editable .[tests]

Now it is possible to run the test suite by typing

pytest