fdsreader

Fast and easy-to-use Python reader for Fire Dynamics Simulator (FDS) output.

fdsreader reads the binary and CSV files an FDS simulation writes and hands you the data as NumPy arrays. Point it at a simulation directory and every output is available as a Python object, loaded only when you first access it. Data from multi-mesh simulations can be merged into one global array. For a quick look without writing any plotting code, there is an explorer for Jupyter and the terminal.

Installation

pip install fdsreader

The Jupyter explorer needs a plotting stack, which is an optional extra: pip install "fdsreader[notebook]". Its command line counterpart needs nothing beyond numpy and is always installed.

fdsreader needs Python 3.10 or newer and reads output of FDS 6.7.5 and later; it is tested against the latest FDS release. For complex geometry (&GEOM) from FDS 6.10 or newer, use fdsreader 1.12.1 or later. Details are in the compatibility table; if something does not read correctly, please open an issue.

Quickstart

import fdsreader as fds

sim = fds.Simulation("./my_simulation")  # the directory containing the .smv file
print(sim)                               # what the simulation wrote

# Temperature slice closest to x = 0, merged over all meshes into one array
slc = sim.slices.filter_by_quantity("TEMPERATURE").get_nearest(x=0)
temperature = slc.to_global()            # shape (time, ...)
step = slc.get_nearest_timestep(30.0)
print(slc.times[step], temperature[step].max())

# Time series: devices by their ID from the input file, and the heat release rate
time = sim.devices["Time"].data
hgl_temp = sim.devices["HGL Temp"].data
hrr = sim.hrr["HRR"]

Step-by-step example notebooks for every data type are in the documentation and in examples/; the full API is in the documentation.

Explorer

fdsreader.explorer looks at a simulation without writing plotting code for it: a time bar driving a 2D slice, and any number of device or HRR quantities plotted against time. In Jupyter that is an interactive widget; in a terminal you can either explore it interactively or draw a single view and exit.

In Jupyter

from fdsreader.explorer import explore

explorer = explore()

That renders the whole interface — a directory browser, the time bar, the slice on the left and the curves on the right. Browse to a case and press Load simulation.

explore("./sample_data")            # skip the browser and load this case
explore(start_dir="/data/cases")    # open the browser somewhere specific
explore(interactive_canvas=False)   # static images instead of ipympl canvases
explore(caching=True)               # allow the .pickle cache (writable data only)

explore() returns the explorer, so the simulation and the current selection stay available in later cells:

sim = explorer.sim
explorer.current_time               # where the time bar is, in seconds
explorer.selection                  # the curves currently ticked
explorer.field.frame(400)           # the slice on screen, at time step 400

ipympl is optional; with it each plot gains a toolbar to zoom, pan and save. If the plots come up as Failed to load model class 'MPLCanvasModel', its browser-side extension is not loading — pass interactive_canvas=False.

In a terminal

The command line front end needs nothing but numpy, so it works over SSH on a machine with no plotting stack and no browser.

-i opens a full-screen interactive view, where the slice and the curves are chosen from lists rather than named on the command line:

fdsreader-explorer-cli ./sample_data -i

Key	Action
← → or h l	step through time
page up / page down	ten steps
home / end	first / last step
space	play, pause
+ -	play speed
f	pick the slice from a list
c	pick the curves from a list (space ticks, enter accepts)
[ ]	previous / next slice
g / s	colour scale over the whole run / this step
?	help
q	quit

Without -i it draws one view and exits, which is what you want in a script:

fdsreader-explorer-cli ./sample_data                        # what is in it
fdsreader-explorer-cli ./sample_data --list                 # slices and curves by name
fdsreader-explorer-cli ./sample_data --slice 0 --time 4.4   # draw a slice
fdsreader-explorer-cli ./sample_data --curve TC_1 --curve HRR
fdsreader-explorer-cli ./sample_data --json                 # for scripting

TEMPERATURE [C] — x = 0 m  #0   ·   t = 4.401 s (step 630 of 749)

  10.00 |
        |
   8.82 |
        |
        |
        |          ...
        |        .....
   5.88 |       .....
        |      ...:...
        |       .....
        |        ....
        |        ...
   2.94 |       .:..
        |       -.
        |       -:-.
        |       .-*:
        |        +%+.
   0.00 |        +#:
        +------------------
         -2.5           2.5   y [m]
         scale 20 … 1412   ramp ' .:-=+*#%@'   grid 18x18

--save FILE writes the current view as an image or an animation instead (.png/.pdf/.svg/.gif/.mp4, needs matplotlib).

Notes

• The interactive terminal view uses curses, which is in the standard library everywhere except Windows; there, pip install windows-curses provides it.
• Slices are read one time step at a time, so stepping through a long run costs a few hundred kilobytes rather than loading the whole series into memory.

Documentation

The documentation covers every data type, the settings (lazy loading, caching, error handling) and the full API.

Citing

If fdsreader helps your research, please cite it via its Zenodo DOI 10.5281/zenodo.6783225. GitHub's "Cite this repository" button gives you the reference in BibTeX or APA.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md for the development setup and how to run the tests.

Authors and maintainers

fdsreader is developed at Forschungszentrum Jülich, IAS-7 and maintained by Jan Vogelsang, Marc Fehr, Tristan Hehnen and Lukas Arnold. For all authors see CITATION.cff.

fdsreader is licensed under the LGPLv3.