astrovascpy.PetscBinaryIO

PetscBinaryIO

COPIED FROM PETSC Library -> $PETSC_DIR/lib/petsc/bin (along with get_conf function)

Since PetscBinaryIO is not part of the PETSC core library, but rather a showcase Python script, we decided to copy it here, and avoid setup tricks like: export PYTHONPATH=$PETSC_DIR/lib/petsc/bin:$PYTHONPATH Provides

  1. PETSc-named objects Vec, Mat, and IS that inherit numpy.ndarray

  2. A class to read and write these objects from PETSc binary files.

The standard usage of this module should look like:
>>> import PetscBinaryIO
>>> io = PetscBinaryIO.PetscBinaryIO()
>>> objects = io.readBinaryFile('file.dat')
or
>>> import PetscBinaryIO
>>> import numpy
>>> vec = numpy.array([1., 2., 3.]).view(PetscBinaryIO.Vec)
>>> io = PetscBinaryIO.PetscBinaryIO()
>>> io.writeBinaryFile('file.dat', [vec,])

See also PetscBinaryIO.__doc__ and methods therein.

Functions

decorate_with_conf(f)

Decorates methods to take kwargs for precisions.

get_conf()

Parses various PETSc configuration/include files to get data types.

update_wrapper_with_doc(wrapper, wrapped)

Similar to functools.update_wrapper, but also gets the wrapper's __doc__ string

wraps_with_doc(wrapped)

Similar to functools.wraps, but also gets the wrapper's __doc__ string

Classes

IS

IS represented as 1D numpy array

MatDense(data[, dtype, copy])

Mat represented as 2D numpy array

MatSparse([iterable])

Mat represented as CSR tuple ((M, N), (rowindices, col, val))

PetscBinaryIO([precision, indices, ...])

Reader/Writer class for PETSc binary files.

Vec

Vec represented as 1D numpy array

Exceptions

DoneWithFile

exception astrovascpy.PetscBinaryIO.DoneWithFile

Bases: Exception

class astrovascpy.PetscBinaryIO.IS

Bases: ndarray

IS represented as 1D numpy array

The best way to instantiate this class for use with writeBinaryFile() is through the numpy “view” method:

an_is = numpy.array([3,4,5]).view(IS)

class astrovascpy.PetscBinaryIO.MatDense(data, dtype=None, copy=True)

Bases: matrix

Mat represented as 2D numpy array

The best way to instantiate this class for use with writeBinaryFile() is through the numpy view method:

mat = numpy.array([[1,0],[0,1]]).view(Mat)

class astrovascpy.PetscBinaryIO.MatSparse(iterable=(), /)

Bases: tuple

Mat represented as CSR tuple ((M, N), (rowindices, col, val))

This should be instantiated from a tuple:

mat = MatSparse( ((M,N), (rowindices,col,val)) )

class astrovascpy.PetscBinaryIO.PetscBinaryIO(precision=None, indices=None, complexscalars=None)

Bases: object

Reader/Writer class for PETSc binary files.

Note that by default, precisions for both scalars and indices, as well as complex scalars, are picked up from the PETSC_DIR/PETSC_ARCH configuration as set by environmental variables.

Alternatively, defaults can be overridden at class instantiation, or for a given method call.

readBinaryFile(fid, mattype='sparse')

Reads a PETSc binary file, returning a tuple of the contained objects.

objects = self.readBinaryFile(fid, **kwargs)

Input:

fid : either file name or handle to an open binary file.

Output:

objects : tuple of objects representing the data in numpy arrays.

Optional:
mattype :

‘sparse’: Return matrices as raw CSR: (M, N), (row, col, val). ‘dense’: Return matrices as MxN numpy arrays. ‘scipy.sparse’: Return matrices as scipy.sparse objects.

Additional kwargs:

precision: ‘single’, ‘double’, ‘longlong’ for scalars indices: ‘32bit’, ‘64bit’ integer size complexscalars: True/False

Note these are set in order of preference:

  1. kwargs if given here

  2. PetscBinaryIO class __init__ arguments

  3. PETSC_DIR/PETSC_ARCH defaults

readIS(fh)

Reads a PETSc Index Set from binary file handle. Additional kwargs:

precision: ‘single’, ‘double’, ‘longlong’ for scalars indices: ‘32bit’, ‘64bit’ integer size complexscalars: True/False

Note these are set in order of preference:

  1. kwargs if given here

  2. PetscBinaryIO class __init__ arguments

  3. PETSC_DIR/PETSC_ARCH defaults

readMat(fh, mattype='sparse')

Reads a PETSc Mat from binary file handle.

optional mattype: ‘sparse” or ‘dense’

See also: readMatSparse, readMatDense

Additional kwargs:

precision: ‘single’, ‘double’, ‘longlong’ for scalars indices: ‘32bit’, ‘64bit’ integer size complexscalars: True/False

Note these are set in order of preference:

  1. kwargs if given here

  2. PetscBinaryIO class __init__ arguments

  3. PETSC_DIR/PETSC_ARCH defaults

readMatDense(fh)

Reads a PETSc Mat, returning a dense representation of the data. Additional kwargs:

precision: ‘single’, ‘double’, ‘longlong’ for scalars indices: ‘32bit’, ‘64bit’ integer size complexscalars: True/False

Note these are set in order of preference:

  1. kwargs if given here

  2. PetscBinaryIO class __init__ arguments

  3. PETSC_DIR/PETSC_ARCH defaults

readMatSciPy(fh)
Additional kwargs:

precision: ‘single’, ‘double’, ‘longlong’ for scalars indices: ‘32bit’, ‘64bit’ integer size complexscalars: True/False

Note these are set in order of preference:

  1. kwargs if given here

  2. PetscBinaryIO class __init__ arguments

  3. PETSC_DIR/PETSC_ARCH defaults

readMatSparse(fh)

Reads a PETSc Mat, returning a sparse representation of the data.

(M,N), (I,J,V) = readMatSparse(fid)

Input:

fid : file handle to open binary file.

Output:

M,N : matrix size I,J : arrays of row and column for each nonzero V: nonzero value

Additional kwargs:

precision: ‘single’, ‘double’, ‘longlong’ for scalars indices: ‘32bit’, ‘64bit’ integer size complexscalars: True/False

Note these are set in order of preference:

  1. kwargs if given here

  2. PetscBinaryIO class __init__ arguments

  3. PETSC_DIR/PETSC_ARCH defaults

readVec(fh)

Reads a PETSc Vec from a binary file handle, returning just the data. Additional kwargs:

precision: ‘single’, ‘double’, ‘longlong’ for scalars indices: ‘32bit’, ‘64bit’ integer size complexscalars: True/False

Note these are set in order of preference:

  1. kwargs if given here

  2. PetscBinaryIO class __init__ arguments

  3. PETSC_DIR/PETSC_ARCH defaults

writeBinaryFile(fid, objects)

Writes a PETSc binary file containing the objects given.

readBinaryFile(fid, objects)

Input:

fid : either file handle to an open binary file, or filename. objects : list of objects representing the data in numpy arrays,

which must be of type Vec, IS, MatSparse, or MatSciPy.

Additional kwargs:

precision: ‘single’, ‘double’, ‘longlong’ for scalars indices: ‘32bit’, ‘64bit’ integer size complexscalars: True/False

Note these are set in order of preference:

  1. kwargs if given here

  2. PetscBinaryIO class __init__ arguments

  3. PETSC_DIR/PETSC_ARCH defaults

writeIS(fh, anis)

Writes a PETSc IS to binary file handle. Additional kwargs:

precision: ‘single’, ‘double’, ‘longlong’ for scalars indices: ‘32bit’, ‘64bit’ integer size complexscalars: True/False

Note these are set in order of preference:

  1. kwargs if given here

  2. PetscBinaryIO class __init__ arguments

  3. PETSC_DIR/PETSC_ARCH defaults

writeMatSciPy(fh, mat)
Additional kwargs:

precision: ‘single’, ‘double’, ‘longlong’ for scalars indices: ‘32bit’, ‘64bit’ integer size complexscalars: True/False

Note these are set in order of preference:

  1. kwargs if given here

  2. PetscBinaryIO class __init__ arguments

  3. PETSC_DIR/PETSC_ARCH defaults

writeMatSparse(fh, mat)

Writes a Mat into a PETSc binary file handle Additional kwargs:

precision: ‘single’, ‘double’, ‘longlong’ for scalars indices: ‘32bit’, ‘64bit’ integer size complexscalars: True/False

Note these are set in order of preference:

  1. kwargs if given here

  2. PetscBinaryIO class __init__ arguments

  3. PETSC_DIR/PETSC_ARCH defaults

writeVec(fh, vec)

Writes a PETSc Vec to a binary file handle. Additional kwargs:

precision: ‘single’, ‘double’, ‘longlong’ for scalars indices: ‘32bit’, ‘64bit’ integer size complexscalars: True/False

Note these are set in order of preference:

  1. kwargs if given here

  2. PetscBinaryIO class __init__ arguments

  3. PETSC_DIR/PETSC_ARCH defaults

class astrovascpy.PetscBinaryIO.Vec

Bases: ndarray

Vec represented as 1D numpy array

The best way to instantiate this class for use with writeBinaryFile() is through the numpy view method:

vec = numpy.array([1,2,3]).view(Vec)

astrovascpy.PetscBinaryIO.decorate_with_conf(f)

Decorates methods to take kwargs for precisions.

astrovascpy.PetscBinaryIO.get_conf()

Parses various PETSc configuration/include files to get data types.

precision, indices, complexscalars = get_conf()

Output:

precision: ‘single’, ‘double’, ‘longlong’ indicates precision of PetscScalar indices: ‘32’, ‘64’ indicates bit-size of PetscInt complex: True/False indicates whether PetscScalar is complex or not.

astrovascpy.PetscBinaryIO.update_wrapper_with_doc(wrapper, wrapped)

Similar to functools.update_wrapper, but also gets the wrapper’s __doc__ string

astrovascpy.PetscBinaryIO.wraps_with_doc(wrapped)

Similar to functools.wraps, but also gets the wrapper’s __doc__ string