Pyclaw Input/Output Package

Pyclaw supports the following input and output formats:

  • ASCII - ASCII file I/O, supports traditional clawpack format files
  • HDF5 - HDF5 file I/O
  • NetCDF - NetCDF file I/O, support for NetCDF3 and NetCDF4 files

Each module contains two main routines read_<format> and write_<format> which Solution can call with the appropriate <format>. In order to create a new file I/O extension the calling signature must match

read_<format>(solution,frame,path,file_prefix,write_aux,options)
where the the inputs are
Input:
  • solution - (Solution) Pyclaw object to be output
  • frame - (int) Frame number
  • path - (string) Root path
  • file_prefix - (string) Prefix for the file name.
  • write_aux - (bool) Boolean controlling whether the associated auxiliary array should be written out.
  • options - (dict) Optional argument dictionary

and

write_<format>(solution,frame,path,file_prefix,write_aux,options)
where the inputs are
Input:
  • solution - (Solution) Pyclaw object to be output
  • frame - (int) Frame number
  • path - (string) Root path
  • file_prefix - (string) Prefix for the file name.
  • write_aux - (bool) Boolean controlling whether the associated auxiliary array should be written out.
  • options - (dict) Optional argument dictionary.

Note that both allow for an options dictionary that is format specific and should be documented thoroughly. For examples of this usage, see the HDF5 and NetCDF modules.

HDF5 and NetCDF support require installed libraries in order to work, please see the respective modules for details on how to obtain and install the libraries needed.

Note

Pyclaw automatically detects the availability of HDF5 and NetCDF file support and will warn you if you try and use them without the proper libraries.

pyclaw.io.ascii

Routines for reading and writing an ascii output file

clawpack.pyclaw.fileio.ascii.read(solution, frame, path='./', file_prefix='fort', read_aux=False, options={})

Read in a frame of ascii formatted files, and enter the data into the solution object.

This routine reads the ascii formatted files corresponding to the classic clawpack format ‘fort.txxxx’, ‘fort.qxxxx’, and ‘fort.axxxx’ or ‘fort.aux’ Note that the fort prefix can be changed.

Input:
  • solution - (Solution) Solution object to read the data into.
  • frame - (int) Frame number to be read in
  • path - (string) Path to the current directory of the file
  • file_prefix - (string) Prefix of the files to be read in. default = 'fort'
  • read_aux (bool) Whether or not an auxillary file will try to be read in. default = False
  • options - (dict) Dictionary of optional arguments dependent on the format being read in. default = {}
clawpack.pyclaw.fileio.ascii.read_array(f, state, num_var)

Read in an array from an ASCII output file f.

The variable q here may in fact refer to q or to aux.

This routine supports the possibility that the values q[:,i,j,k] (for a fixed i,j,k) have been split over multiple lines, because some packages write just 4 values per line. For Clawpack 6.0, we plan to make all packages write q[:,i,j,k] on a single line. This routine can then be simplified.

clawpack.pyclaw.fileio.ascii.read_patch_header(f, num_dim)

Read header describing the next patch

Input:
  • f - (file) Handle to open file
  • num_dim - (int) Number of dimensions
Output:
  • patch - (clawpack.pyclaw.geometry.Patch) Initialized patch represented by the header data.
clawpack.pyclaw.fileio.ascii.read_t(frame, path='./', file_prefix='fort')

Read only the fort.t file and return the data

Input:
  • frame - (int) Frame number to be read in
  • path - (string) Path to the current directory of the file
  • file_prefix - (string) Prefix of the files to be read in. default = 'fort'
Output:
  • (list) List of output variables
  • t - (int) Time of frame
  • num_eqn - (int) Number of equations in the frame
  • nstates - (int) Number of states
  • num_aux - (int) Auxillary value in the frame
  • num_dim - (int) Number of dimensions in q and aux
clawpack.pyclaw.fileio.ascii.write(solution, frame, path, file_prefix='fort', write_aux=False, options={}, write_p=False)

Write out ascii data file

Write out an ascii file formatted identical to the fortran clawpack files including writing out fort.t, fort.q, and fort.aux if necessary. Note that there are some parameters that assumed to be the same for every patch in this format which is not necessarily true for the actual data objects. Make sure that if you use this output format that all of you patchs share the appropriate values of num_dim, num_eqn, num_aux, and t. Only supports up to 3 dimensions.

Input:
  • solution - (Solution) Pyclaw object to be output.
  • frame - (int) Frame number
  • path - (string) Root path
  • file_prefix - (string) Prefix for the file name. default = 'fort'
  • write_aux - (bool) Boolean controlling whether the associated auxiliary array should be written out. default = False
  • options - (dict) Dictionary of optional arguments dependent on the format being written. default = {}
clawpack.pyclaw.fileio.ascii.write_array(f, patch, q)

Write a single array to output file f as ASCII text.

The variable q here may in fact refer to q or to aux.

pyclaw.io.hdf5

System Message: WARNING/2 (/var/folders/_s/dx0xgftn3_x04rdx0_w5nq7w0000gn/T/tmpMRaGiysphinxcontrib_versioning/81762a5aeb2c1e99f790ffb21192324b5b0e341c/doc/pyclaw/io.rst, line 79)

autodoc: failed to import module u’clawpack.pyclaw.fileio.hdf5’; the following exception was raised: Traceback (most recent call last): File “/usr/local/Cellar/python/2.7.12_2/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/sphinx/ext/autodoc.py”, line 551, in import_object __import__(self.modname) File “/Users/rjl/git/clawpack/clawpack/pyclaw/fileio/hdf5.py”, line 42, in <module> raise Exception(error_msg) Exception: Could not import h5py or PyTables, please install either h5py or PyTables. See the doc_string for more information.

pyclaw.io.netcdf

Routines for reading and writing a NetCDF output file

Routines for reading and writing a NetCDF output file via either

These interfaces are very similar so if a different module needs to be used, it can more than likely be inserted with a minimal of effort.

This module will first try to import the netcdf4-python module which is based on the compiled libraries and failing that will attempt to import the pure python interface pupynere which requires no libraries.

To install the netCDF 4 library, please see:
http://www.unidata.ucar.edu/software/netcdf/
Authors:Kyle T. Mandli (2009-02-17) Initial version
clawpack.pyclaw.fileio.netcdf.read(solution, frame, path='./', file_prefix='claw', read_aux=True, options={})

Read in a NetCDF data files into solution

Input:
  • solution - (Solution) Pyclaw object to be output
  • frame - (int) Frame number
  • path - (string) Root path
  • file_prefix - (string) Prefix for the file name. default = 'claw'
  • write_aux - (bool) Boolean controlling whether the associated auxiliary array should be written out. default = False
  • options - (dict) Optional argument dictionary, unused for reading.
clawpack.pyclaw.fileio.netcdf.write(solution, frame, path, file_prefix='claw', write_aux=False, options={}, write_p=False)

Write out a NetCDF data file representation of solution

Input:
  • solution - (Solution) Pyclaw object to be output
  • frame - (int) Frame number
  • path - (string) Root path
  • file_prefix - (string) Prefix for the file name. default = 'claw'
  • write_aux - (bool) Boolean controlling whether the associated auxiliary array should be written out. default = False
  • options - (dict) Optional argument dictionary, see NetCDF Option Table
Key Value
description Dictionary of key/value pairs that will be attached to the root group as attributes, i.e. {‘time’:3}
format Can be one of the following netCDF flavors: NETCDF3_CLASSIC, NETCDF3_64BIT, NETCDF4_CLASSIC, and NETCDF4 default = NETCDF4
clobber if True (Default), file will be overwritten, if False an exception will be raised
zlib if True, data assigned to the Variable instance is compressed on disk. default = False
complevel the level of zlib compression to use (1 is the fastest, but poorest compression, 9 is the slowest but best compression). Ignored if zlib=False. default = 6
shuffle if True, the HDF5 shuffle filter is applied to improve compression. Ignored if zlib=False. default = True
fletcher32 if True (default False), the Fletcher32 checksum algorithm is used for error detection.
contiguous if True (default False), the variable data is stored contiguously on disk. Setting to True for a variable with an unlimited dimension will trigger an error. default = False
chunksizes Can be used to specify the HDF5 chunksizes for each dimension of the variable. A detailed discussion of HDF chunking and I/O performance is available here. Basically, you want the chunk size for each dimension to match as closely as possible the size of the data block that users will read from the file. chunksizes cannot be set if contiguous=True.
least_significant_digit If specified, variable data will be truncated (quantized). In conjunction with zlib=True this produces ‘lossy’, but significantly more efficient compression. For example, if least_significant_digit=1, data will be quantized using around (scale*data)/scale, where scale = 2**bits, and bits is determined so that a precision of 0.1 is retained (in this case bits=4). default = None, or no quantization.
endian Can be used to control whether the data is stored in little or big endian format on disk. Possible values are little, big or native (default). The library will automatically handle endian conversions when the data is read, but if the data is always going to be read on a computer with the opposite format as the one used to create the file, there may be some performance advantage to be gained by setting the endian-ness.
fill_value If specified, the default netCDF _FillValue (the value that the variable gets filled with before any data is written to it) is replaced with this value. If fill_value is set to False, then the variable is not pre-filled.

Note

The zlib, complevel, shuffle, fletcher32, contiguous, chunksizes and endian keywords are silently ignored for netCDF 3 files that do not use HDF5.