File Reading

Mostly when reading files you’ll be interacting with the wrapper functions directly in the pyharm.io namespace, documented here.

Intelligent input/output functions. This module tries to use one of several different file “filters” or loaders, based on the file name and contents.

pyharm.io.file_reader(fname, **kwargs)

Return an XFile object (“filter”) which can read/write the given filename. This guesses based on filename, mostly, or very basic file contents. You can override it by just constructing a filter of your desired type. :param fname: A filename (or HDF5 file handle)

Note that you can use this more easily through the FluidDump object

pyharm.io.get_dump_time(fname)

Quickly get just the simulation time represented in the dump file. For cutting on time without loading everything

pyharm.io.get_fnames(path, prefer_iharm3d=False)

Return what should be the list of fluid dump files in a directory ‘path’, while trying to avoid extraneous files caught in normal globs (e.g., grid.h5, other runs/filetypes)

pyharm.io.read_hdr(fname)

Get just the header/params embedded in a simulation file.

pyharm.io.read_log(fname)

Read a file containing a history or log of fluxes & other scalars over time.

File Filters

Behind the general/auto-dispatch functions in pyharm.io, pyharm uses “filter” classes representing each file with a consistent interface. The interface itself is documented below, followed by examples for KHARMA and iharm3d files, which have some additional functionality.

Note that while this is left to each filter to decide, the designed & fastest option is to read (nearly) nothing at object creation, reading variables only when they requested with pyharm.io.interface.read_var(), and caching them for future calls. In addition, read_var should support returning only a slice of a file, either by reading just the necessary slice (preferable) or by slicing the output array before returning it.

class pyharm.io.interface.DumpFile

This interface provides the list of functions to implement for new file filters for pyharm. A good base set of variables would be to provide something logical for the HARM primitive variables RHO, UU, U1, U2, U3, B1, B2, B3. The provided index_of() function returns the expected indices 1-8 for these variables – e.g. from most HARM-like output, read_var returns prims[:,:,:,index_of(var)] in most cases.

The constructor must initialize a dictionary member self.params, containing at least enough members to initialize a Grid object (see Grid constructor docstring), as well as any single-scalar properties which the analysis or plotting code will need to access (e.g. fluid gamma, BH spin, times & timesteps, etc). Usually this is done via a member function self.read_params, which may be called on its own in future

classmethod get_dump_time(fname)

Quickly get just the simulation time represented in the dump file. For cutting on time without loading everything.

read_var(var, slice=None)

Read a variable ‘var’ from the file as a numpy array. Optionally read ghost zones if specified, or read only a slice ‘slice’ of the values from the file. Returns ‘None’ if the variable doesn’t exist in the file.

Read KHARMA output files and logs. Pretty much supports any Parthenon code and nearly supports AMR. Contains much index math.

class pyharm.io.kharma.KHARMAFile(filename, ghost_zones=False, params=None)

File filter for KHARMA files

classmethod get_dump_time(fname)

Quickly get just the simulation time represented in the dump file. For cutting on time without loading everything

kharma_standardize(var)

Standardize the names we’re asked for, so we cache only one copy

read_var(var, astype=None, slc=(), fail_if_not_found=True)

Read a variable ‘var’ from the file as a numpy array. Optionally read ghost zones if specified, or read only a slice ‘slice’ of the values from the file. Returns ‘None’ if the variable doesn’t exist in the file.

Functions for reading and writing iharm3d/Illinois HDF format files, as well as iharm3d’s log files.

class pyharm.io.iharm3d.Iharm3DFile(filename, ghost_zones=False, params=None)

File filter class for Illinois HDF5 format dump files, from iharm3d, ebhlight, pyharm, or converted from KHARMA output or potentially more exotic formats. Usually used through file-agnostic interface: see file_reader and the FluidDump class for details.

classmethod get_dump_time(fname)

Quickly get just the simulation time represented in the dump file. For cutting on time without loading everything.

read_params(**kwargs)

Read the file header and per-dump parameters (t, dt, etc)

read_var(var, slc=(), **kwargs)

Read a variable ‘var’ from the file as a numpy array. Optionally read ghost zones if specified, or read only a slice ‘slice’ of the values from the file. Returns ‘None’ if the variable doesn’t exist in the file.

pyharm.io.iharm3d.read_log(logfname)

Read an iharm3d-format log.out file into a dictionary

pyharm.io.iharm3d.write_dump(dump, fname, astype=<class 'numpy.float32'>, ghost_zones=False)

Write the data in FluidDump ‘dump’ to file ‘fname’ in iharm3d/Illinois HDF format.

Additional Utilities

Finally, there are separate modules for dealing with the iharm3d header format and for “gridfiles” containing zone locations and metric values, as both are quite common to encounter/read/write on their own.

Functions for reading and writing the ‘header/’ portion of iharm3d/Illinois HDF files. Lots of writing and validation tools, hence splitting from the filter and restart file classes.

pyharm.io.iharm3d_header.dict_to_hdf5(wdict, h5grp)

Write nested dictionaries of Python values to HDF5 groups nested within the group/file h5grp If a filename is specified, automatically opens/closes the file.

pyharm.io.iharm3d_header.hdf5_to_dict(h5grp)

Recursively load group contents into nested dictionaries. Used to load analysis output while keeping shapes straight.

pyharm.io.iharm3d_header.read_hdr(grp)

Read an iharm3d/Illinois HDF header. :parameter params: Dictionary of parameters to update. Otherwise, read_hdr will create an empty one

pyharm.io.iharm3d_header.write_hdr(params, outf)

Write a valid iharm3d/Illinois HDF header

Write “grid” files specifying geometry for e.g. visualization programs.

pyharm.io.gridfile.write_grid(G, fname='grid.h5', astype=<class 'numpy.float32'>)

Dump a file containing grid zones. This will primarily be of archival use soon – see grid.py, coordinates.py for a good way of reconstructing all common grids on the fly.

pyharm.io.gridfile.write_vis_grid(G, outfname='grid.h5')

Write a Grid object G to a bhlight-format grid file. Generally used for visualization with VisIt, to take advantage of XDMF and scripting from ebhlight.