This package is certainly in its early stages. We hope that others will find it useful, but it unlikely this package will do everything you want it to out of the box (though this is of course the goal). Moreover, at this stage, any results obtained using it should be corroborated with some other source.
If you intend to use it, feel free to send an email to the package maintainers (jwake@umich.edu) with any questions or concerns.
Because the intended audience of this package is small, it is unlikely we will
add it to a repository like PyPi. This package may either be used in a virtual
environment (recommended) or installed. For the former, a script has been
included to do this for you (assuming standard packages like venv and pip3 are
already installed); simply run source activate_venv.sh. The latter can be
done for a user-specific (PEP370) install pip3 install path/to/mevlib or a
system-wide install sudo -H pip3 install path/to/mevlib.
To generate a Matlab lookup tables:
~ $ source activate_venv.sh ~ $ cd examples/ ~ $ mevtable --rate example_file.sbl mat
After doing so one will find mevtable_rates.mat in the current working
directory containing lookup table data.
This package can produce four different lookuptables:
rate- A table mapping temperature to N_g \times N rate matrices (assumes infinite Biot number)
biotrate- A table mapping temperature to N_g \times N rate matrices (assumes infinite Biot number) TODO not yet implemented
ints- A table mapping Thiele moduli to single stage effectiveness factors (\lambda \mapsto \eta)
biotints- A table mapping a Thiele modulus and a Biot number to a single stage effectiveness factor TODO not yet implemented
diag- A table mapping temperatures to diagonalizations without left eigenvectors (temperature to N + (N + 1) N_g scalars)
fulldiag- A table mapping temperatures to diagonalizations with left eigenvectors (temperature to N + (N + 1) N_g scalars)
An implementation in a CFD code would consist of either: a rate table
(where we must have \psi = 1) or
- One of
fulldiagdiagand a means of computing R^{-1} online- a means of computing the entire diagonalization online
- and one of
intsorbiotints- a means of computing single stage effectiveness factors online
For some irreversible, cascading reactions R^{-1} may be very easy to compute, making its inclusion in a lookup table suboptimal. For simple shapes (e.g.~spheres) maintaining a table of single stage effectiveness factors is entirely unnecessary. For small numbers of species (e.g.~2 gaseous and 1 solid) in complex geometries it is likely optimal to do diagonalization online but use a table for single stage effectiveness factors.
We hope that including the easiest to use option (a single rate table) in
addition to the ability to mix and match for a particular application will
increase the usefulness of this package.
At present only one input file format is supported. An example is provided in
examples/example_file.sbl.
All numbers are little-endian. The format descriptions below impose the limit of 8 ascii characters for a species name, 128 gaseous and solid species, and a maximum lookup table size of 32768. (The single-stage effectiveness factor has a 4 byte table length so we mostly stay aligned to 32 bit words.)
For rate files:
| Element | Size (bytes) | Data Type | ||
|---|---|---|---|---|
| Magic Number | 6 | literal | 0x3ccf89cc873e |
|
| Array Ordering | 1 | 'F' or 'C' (ascii) | only 'F' implemented | |
| Version | 1 | integer | only 0x01 so far |
|
| Number of Gases N_g | 1 | integer | ||
| Number of Solids N_s | 1 | integer | ||
| Size of Lookup Table M | 2 | integer | ||
| Repeat N = N_g + N_s times | Species Identifier | 8 | ascii | |
| Repeat N = N_g + N_s times | Molecular Weight | 8 | double | |
| Repeat M times | Temperature | 8 | double | |
| Repeat M times | Rate Matrix | 8 N N_g | doubles |
For ints files:
| Element | Size (bytes) | Data Type | ||
|---|---|---|---|---|
| Magic Number | 6 | literal | 0xe288ab756456 |
|
| Array Ordering | 1 | 'F' or 'C' (ascii) | only 'F' implemented | |
| Version | 1 | integer | only 0x01 so far |
|
| Number of Theile Moduli M | 4 | integer | ||
| Repeat M times | Theile Modulus | 8 | double | |
| Repeat M times | Single-Step Effectiveness Factor | 8 | double |
For diag files:
| Element | Size (bytes) | Data Type | ||
|---|---|---|---|---|
| Magic Number | 6 | literal | 0x42523d52ce9b |
|
| Array Ordering | 1 | 'F' or 'C' (ascii) | only 'F' implemented | |
| Version | 1 | integer | only 0x01 so far |
|
| Number of Gases N_g | 1 | integer | ||
| Number of Solids N_s | 1 | integer | ||
| Size of Lookup Table M | 2 | integer | ||
| Repeat N = N_g + N_s times | Species Identifier | 8 | ascii | |
| Repeat N = N_g + N_s times | Molecular Weight | 8 | double | |
| Repeat M times | Temperature | 8 | double | |
| Repeat M times | \bar{\mathbf{D}} / L^2 | 8 N | doubles | |
| Eigenvalues | 8 N_g | doubles | ||
| R | 8 N_g^2 | doubles | fortran order | |
| B_s R | 8 N_s N_g | doubles | fortran order |
For fulldiag files:
| Element | Size (bytes) | Data Type | ||
|---|---|---|---|---|
| Magic Number | 6 | literal | 0x525e7b2d317d |
|
| Array Ordering | 1 | 'F' or 'C' (ascii) | only 'F' implemented | |
| Version | 1 | integer | only 0x01 so far |
|
| Number of Gases N_g | 1 | integer | ||
| Number of Solids N_s | 1 | integer | ||
| Size of Lookup Table M | 2 | integer | ||
| Repeat N = N_g + N_s times | Species Identifier | 8 | ascii | |
| Repeat N = N_g + N_s times | Molecular Weight | 8 | double | |
| Repeat M times | Temperature | 8 | double | |
| Repeat M times | \bar{\mathbf{D}} / L^2 | 8 N | doubles | |
| Eigenvalues | 8 N_g | doubles | ||
| R | 8 N_g^2 | doubles | fortran order | |
| B_s R | 8 N_s N_g | doubles | fortran order | |
| R^{-1} | 8 N_g^2 | doubles | fortran order |
To make this package easier to use, some output formats generate code that can be called from a containing simulation without any complex dependencies or data files. These are generated by using f03 and f90 as output formats. f90 generates a data type MEVData containing the lookup table and a collection of related functions whereas f03 generates an class. These modules contain mevdata_getmev, mevdata_init, and mevdata_destroy. The initialization and destruction functions have no imput arguments (other than the data structure). mevdata_getmev requires a vector of free stream concentrations and a temperature.
When referred to as a Python package mevlib is written in all lowercase to be consistent with Python conventions. As a project it is referred to as MEVlib. For example, 'Effectiveness factors were computed with MEVlib.' and 'The mevlib package is not available on PyPi.' are both correct.
Docstrings are a work in progress; reshuffling some code among modules may be required to make module groupings make more sense.
All files in this project should adhere to PEP8 except:
- W391 (avoids confusion with W292 on different text editors)
- E306 (avoids awkward spacing and is better than violating E731)
- E302 and E305 (two lines are used to denote different logical groupings of functions and classes)
- migrate verification cases to new format
- write better documentation / tutorial
- add tests (pytest/tox, use pytest-cov)
- add and sign versions
- ensure docstring coverage
- several of the scripts in "scripts" are actually tests, make these into tests and move them into the tests directory
- many scripts should maybe be "examples"
- the options.py file referenced by scripts is kinda wonky
- make sure this file obeys rst syntax
This library/tool was written by John Wakefield (jwake@umich.edu) in collaboration with Aaron Lattanzi, Brennan Pecha, Peter Ciesielski, and Jesse Capacelatro.
For imformation on citing this paper contact jwake@umich.edu.
This software package was developed based upon funding from the Alliance for Sustainable Energy, LLC, Managing and Operating Contractor for the National Renewable Energy Laboratory for the U.S. Department of Energy.