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-cursesprovides 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.
3 maintainers
Metadata
3 maintainers
Release files for fdsreader 1.14.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| fdsreader-1.14.0.tar.gz | 1.3 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| fdsreader-1.14.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.5 MB
Release files / fdsreader-1.14.0.tar.gz
| Download URL | fdsreader-1.14.0.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5bfa99a4ea73890ea26ef7277720690bed682260470676b3c2bd66eb63266d76
|
|
BLAKE2b-256 checksum How to use checksums |
7eed6a64e75bf06d22ef5019415274aa9c12ce3333360402ddbcd6c1ae0fcdc5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logRelease files / fdsreader-1.14.0-py3-none-any.whl
| Download URL | fdsreader-1.14.0-py3-none-any.whl |
|---|---|
| Size | 153.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8272daf41e9edee7ff3851a06ec8b25828e6f39a14ad7152484872ff76aad6bd
|
|
BLAKE2b-256 checksum How to use checksums |
4791173c0b4db108d9616e6e9cace0d935d385b2061b3713ad46b5e1a741372b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency log
