|
eisgenerator 1.0.x
|
eisgenerator is a C++ shared library (libeisgenerator.so) and CLI application that allows one to generate EIS spectra with high performance. The target application is generating test and example datasets for machine learning applications. eisgenerator's development and target platform is GNU/Linux, but besides a c++20 compiler and libstd++ it has no dependencies and should compile on nigh any platform. eisgenerator also has python bindings, described here, but note that using these erases a lot of the performance benefit of using this library. For information on how to build this library please look at the Readme.
For an example on how to use this library see the example tab above, for API documentation start here:
For a description on how the model description string used by this library see Model Format.
libeisgenerator incorporates three execution models to choose from depending on your workloads requirements:
Upon invocation of eis::Model::Model the model string is parsed into a tree of objects. In the default tree execution the model parameters and frequencies are passed down the tree with the help of the virtual function tables of the the objects in question (black arrows). The results are then passed up the tree (blue arrows), see figure below:
This execution model has the advantage of very low latency at the expense of throughput. It is most optimal if few impedances are to be calculated. This execution model will be chosen by default. This execution model is always chosen by the single data point eis::Model::execute variant.
In compiled execution eis::Model::compile generates a c++ function containing an implementation of the equivalent circuit. This code is then compiled by GCC and loaded and cached by libeisgenerator. Subsequent calls to eis::Model::compile will then use the cached object. Once a model has been compiled any, subsequent use of the execute family of methods will use the compiled object instead of tree execution. This results in a speedup of greater than 10x from the reduction in virtual function call overhead and the usage of auto-vectorization.
This execution model is the most performant option when evaluation of many impedances is desired and execution is to be performed on a CPU. This execution model is only available on UNIX and UNIX-like platforms providing dlopen() and fork().
The final execution model generates a TorchScript for the equivalent circuit which can be compiled using torch::jit::compile into a graph of torch/rocBLAS/cuBLAS GPU kernels for GPU execution. This provides the highest possible performance. Due to the high latency associated with executing GPU kernels this method should only be expected to outperform compiled execution if a total of 10^8 or more data points are required and only performs well when a large batch of these data points is required at a time. This version is also highly advantageous when calculating impedance spectra as part of a larger system requiring GPU execution as in this case expensive device->host->device copies are avoided. Through Torch AutoGrad this version also provides automatic derivatives, making it useful where integration into machine-learning backward passes is required. Due to deficiencies in the windows port of Torch this version massively underperforms on Microsoft Windows and another platform should be used. Due to MiOpen not being available on Microsoft Windows this method is unable to perform GPU execution on this platform on AMD hardware, the CPU fallback used in this case is slower than tree execution.
eisgenerator is licensed to you under the Gnu Lesser General Public License Version 3.0. All files part of eisgenerator are thus to be treated as LGPL-3.0 unless otherwise noted in the file.
1.10.0