|
|
""" |
|
|
Module to read / write Fortran unformatted sequential files. |
|
|
|
|
|
This is in the spirit of code written by Neil Martinsen-Burrell and Joe Zuntz. |
|
|
|
|
|
""" |
|
|
import warnings |
|
|
import numpy as np |
|
|
|
|
|
__all__ = ['FortranFile', 'FortranEOFError', 'FortranFormattingError'] |
|
|
|
|
|
|
|
|
class FortranEOFError(TypeError, OSError): |
|
|
"""Indicates that the file ended properly. |
|
|
|
|
|
This error descends from TypeError because the code used to raise |
|
|
TypeError (and this was the only way to know that the file had |
|
|
ended) so users might have ``except TypeError:``. |
|
|
|
|
|
""" |
|
|
pass |
|
|
|
|
|
|
|
|
class FortranFormattingError(TypeError, OSError): |
|
|
"""Indicates that the file ended mid-record. |
|
|
|
|
|
Descends from TypeError for backward compatibility. |
|
|
|
|
|
""" |
|
|
pass |
|
|
|
|
|
|
|
|
class FortranFile: |
|
|
""" |
|
|
A file object for unformatted sequential files from Fortran code. |
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
filename : file or str |
|
|
Open file object or filename. |
|
|
mode : {'r', 'w'}, optional |
|
|
Read-write mode, default is 'r'. |
|
|
header_dtype : dtype, optional |
|
|
Data type of the header. Size and endianness must match the input/output file. |
|
|
|
|
|
Notes |
|
|
----- |
|
|
These files are broken up into records of unspecified types. The size of |
|
|
each record is given at the start (although the size of this header is not |
|
|
standard) and the data is written onto disk without any formatting. Fortran |
|
|
compilers supporting the BACKSPACE statement will write a second copy of |
|
|
the size to facilitate backwards seeking. |
|
|
|
|
|
This class only supports files written with both sizes for the record. |
|
|
It also does not support the subrecords used in Intel and gfortran compilers |
|
|
for records which are greater than 2GB with a 4-byte header. |
|
|
|
|
|
An example of an unformatted sequential file in Fortran would be written as:: |
|
|
|
|
|
OPEN(1, FILE=myfilename, FORM='unformatted') |
|
|
|
|
|
WRITE(1) myvariable |
|
|
|
|
|
Since this is a non-standard file format, whose contents depend on the |
|
|
compiler and the endianness of the machine, caution is advised. Files from |
|
|
gfortran 4.8.0 and gfortran 4.1.2 on x86_64 are known to work. |
|
|
|
|
|
Consider using Fortran direct-access files or files from the newer Stream |
|
|
I/O, which can be easily read by `numpy.fromfile`. |
|
|
|
|
|
Examples |
|
|
-------- |
|
|
To create an unformatted sequential Fortran file: |
|
|
|
|
|
>>> from scipy.io import FortranFile |
|
|
>>> import numpy as np |
|
|
>>> f = FortranFile('test.unf', 'w') |
|
|
>>> f.write_record(np.array([1,2,3,4,5], dtype=np.int32)) |
|
|
>>> f.write_record(np.linspace(0,1,20).reshape((5,4)).T) |
|
|
>>> f.close() |
|
|
|
|
|
To read this file: |
|
|
|
|
|
>>> f = FortranFile('test.unf', 'r') |
|
|
>>> print(f.read_ints(np.int32)) |
|
|
[1 2 3 4 5] |
|
|
>>> print(f.read_reals(float).reshape((5,4), order="F")) |
|
|
[[0. 0.05263158 0.10526316 0.15789474] |
|
|
[0.21052632 0.26315789 0.31578947 0.36842105] |
|
|
[0.42105263 0.47368421 0.52631579 0.57894737] |
|
|
[0.63157895 0.68421053 0.73684211 0.78947368] |
|
|
[0.84210526 0.89473684 0.94736842 1. ]] |
|
|
>>> f.close() |
|
|
|
|
|
Or, in Fortran:: |
|
|
|
|
|
integer :: a(5), i |
|
|
double precision :: b(5,4) |
|
|
open(1, file='test.unf', form='unformatted') |
|
|
read(1) a |
|
|
read(1) b |
|
|
close(1) |
|
|
write(*,*) a |
|
|
do i = 1, 5 |
|
|
write(*,*) b(i,:) |
|
|
end do |
|
|
|
|
|
""" |
|
|
def __init__(self, filename, mode='r', header_dtype=np.uint32): |
|
|
if header_dtype is None: |
|
|
raise ValueError('Must specify dtype') |
|
|
|
|
|
header_dtype = np.dtype(header_dtype) |
|
|
if header_dtype.kind != 'u': |
|
|
warnings.warn("Given a dtype which is not unsigned.", stacklevel=2) |
|
|
|
|
|
if mode not in 'rw' or len(mode) != 1: |
|
|
raise ValueError('mode must be either r or w') |
|
|
|
|
|
if hasattr(filename, 'seek'): |
|
|
self._fp = filename |
|
|
else: |
|
|
self._fp = open(filename, f'{mode}b') |
|
|
|
|
|
self._header_dtype = header_dtype |
|
|
|
|
|
def _read_size(self, eof_ok=False): |
|
|
n = self._header_dtype.itemsize |
|
|
b = self._fp.read(n) |
|
|
if (not b) and eof_ok: |
|
|
raise FortranEOFError("End of file occurred at end of record") |
|
|
elif len(b) < n: |
|
|
raise FortranFormattingError( |
|
|
"End of file in the middle of the record size") |
|
|
return int(np.frombuffer(b, dtype=self._header_dtype, count=1)[0]) |
|
|
|
|
|
def write_record(self, *items): |
|
|
""" |
|
|
Write a record (including sizes) to the file. |
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
*items : array_like |
|
|
The data arrays to write. |
|
|
|
|
|
Notes |
|
|
----- |
|
|
Writes data items to a file:: |
|
|
|
|
|
write_record(a.T, b.T, c.T, ...) |
|
|
|
|
|
write(1) a, b, c, ... |
|
|
|
|
|
Note that data in multidimensional arrays is written in |
|
|
row-major order --- to make them read correctly by Fortran |
|
|
programs, you need to transpose the arrays yourself when |
|
|
writing them. |
|
|
|
|
|
""" |
|
|
items = tuple(np.asarray(item) for item in items) |
|
|
total_size = sum(item.nbytes for item in items) |
|
|
|
|
|
nb = np.array([total_size], dtype=self._header_dtype) |
|
|
|
|
|
nb.tofile(self._fp) |
|
|
for item in items: |
|
|
item.tofile(self._fp) |
|
|
nb.tofile(self._fp) |
|
|
|
|
|
def read_record(self, *dtypes, **kwargs): |
|
|
""" |
|
|
Reads a record of a given type from the file. |
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
*dtypes : dtypes, optional |
|
|
Data type(s) specifying the size and endianness of the data. |
|
|
|
|
|
Returns |
|
|
------- |
|
|
data : ndarray |
|
|
A 1-D array object. |
|
|
|
|
|
Raises |
|
|
------ |
|
|
FortranEOFError |
|
|
To signal that no further records are available |
|
|
FortranFormattingError |
|
|
To signal that the end of the file was encountered |
|
|
part-way through a record |
|
|
|
|
|
Notes |
|
|
----- |
|
|
If the record contains a multidimensional array, you can specify |
|
|
the size in the dtype. For example:: |
|
|
|
|
|
INTEGER var(5,4) |
|
|
|
|
|
can be read with:: |
|
|
|
|
|
read_record('(4,5)i4').T |
|
|
|
|
|
Note that this function does **not** assume the file data is in Fortran |
|
|
column major order, so you need to (i) swap the order of dimensions |
|
|
when reading and (ii) transpose the resulting array. |
|
|
|
|
|
Alternatively, you can read the data as a 1-D array and handle the |
|
|
ordering yourself. For example:: |
|
|
|
|
|
read_record('i4').reshape(5, 4, order='F') |
|
|
|
|
|
For records that contain several variables or mixed types (as opposed |
|
|
to single scalar or array types), give them as separate arguments:: |
|
|
|
|
|
double precision :: a |
|
|
integer :: b |
|
|
write(1) a, b |
|
|
|
|
|
record = f.read_record('<f4', '<i4') |
|
|
a = record[0] # first number |
|
|
b = record[1] # second number |
|
|
|
|
|
and if any of the variables are arrays, the shape can be specified as |
|
|
the third item in the relevant dtype:: |
|
|
|
|
|
double precision :: a |
|
|
integer :: b(3,4) |
|
|
write(1) a, b |
|
|
|
|
|
record = f.read_record('<f4', np.dtype(('<i4', (4, 3)))) |
|
|
a = record[0] |
|
|
b = record[1].T |
|
|
|
|
|
NumPy also supports a short syntax for this kind of type:: |
|
|
|
|
|
record = f.read_record('<f4', '(3,3)<i4') |
|
|
|
|
|
See Also |
|
|
-------- |
|
|
read_reals |
|
|
read_ints |
|
|
|
|
|
""" |
|
|
dtype = kwargs.pop('dtype', None) |
|
|
if kwargs: |
|
|
raise ValueError(f"Unknown keyword arguments {tuple(kwargs.keys())}") |
|
|
|
|
|
if dtype is not None: |
|
|
dtypes = dtypes + (dtype,) |
|
|
elif not dtypes: |
|
|
raise ValueError('Must specify at least one dtype') |
|
|
|
|
|
first_size = self._read_size(eof_ok=True) |
|
|
|
|
|
dtypes = tuple(np.dtype(dtype) for dtype in dtypes) |
|
|
block_size = sum(dtype.itemsize for dtype in dtypes) |
|
|
|
|
|
num_blocks, remainder = divmod(first_size, block_size) |
|
|
if remainder != 0: |
|
|
raise ValueError(f'Size obtained ({first_size}) is not a multiple of the ' |
|
|
f'dtypes given ({block_size}).') |
|
|
|
|
|
if len(dtypes) != 1 and first_size != block_size: |
|
|
|
|
|
|
|
|
|
|
|
raise ValueError(f'Size obtained ({first_size}) does not match with the ' |
|
|
f'expected size ({block_size}) of multi-item record') |
|
|
|
|
|
data = [] |
|
|
for dtype in dtypes: |
|
|
r = np.fromfile(self._fp, dtype=dtype, count=num_blocks) |
|
|
if len(r) != num_blocks: |
|
|
raise FortranFormattingError( |
|
|
"End of file in the middle of a record") |
|
|
if dtype.shape != (): |
|
|
|
|
|
if num_blocks == 1: |
|
|
assert r.shape == (1,) + dtype.shape |
|
|
r = r[0] |
|
|
|
|
|
data.append(r) |
|
|
|
|
|
second_size = self._read_size() |
|
|
if first_size != second_size: |
|
|
raise ValueError('Sizes do not agree in the header and footer for ' |
|
|
'this record - check header dtype') |
|
|
|
|
|
|
|
|
if len(dtypes) == 1: |
|
|
return data[0] |
|
|
else: |
|
|
return tuple(data) |
|
|
|
|
|
def read_ints(self, dtype='i4'): |
|
|
""" |
|
|
Reads a record of a given type from the file, defaulting to an integer |
|
|
type (``INTEGER*4`` in Fortran). |
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
dtype : dtype, optional |
|
|
Data type specifying the size and endianness of the data. |
|
|
|
|
|
Returns |
|
|
------- |
|
|
data : ndarray |
|
|
A 1-D array object. |
|
|
|
|
|
See Also |
|
|
-------- |
|
|
read_reals |
|
|
read_record |
|
|
|
|
|
""" |
|
|
return self.read_record(dtype) |
|
|
|
|
|
def read_reals(self, dtype='f8'): |
|
|
""" |
|
|
Reads a record of a given type from the file, defaulting to a floating |
|
|
point number (``real*8`` in Fortran). |
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
dtype : dtype, optional |
|
|
Data type specifying the size and endianness of the data. |
|
|
|
|
|
Returns |
|
|
------- |
|
|
data : ndarray |
|
|
A 1-D array object. |
|
|
|
|
|
See Also |
|
|
-------- |
|
|
read_ints |
|
|
read_record |
|
|
|
|
|
""" |
|
|
return self.read_record(dtype) |
|
|
|
|
|
def close(self): |
|
|
""" |
|
|
Closes the file. It is unsupported to call any other methods off this |
|
|
object after closing it. Note that this class supports the 'with' |
|
|
statement in modern versions of Python, to call this automatically |
|
|
|
|
|
""" |
|
|
self._fp.close() |
|
|
|
|
|
def __enter__(self): |
|
|
return self |
|
|
|
|
|
def __exit__(self, type, value, tb): |
|
|
self.close() |
|
|
|
