eisgenerator 2.1.x
eis::Model Class Reference

The main class of eisgenerator representing an equivalent circuit model. More...

#include <model.h>

Public Member Functions

 Model (const std::string &str, size_t paramSweepCount=100, bool defaultToRange=true)
 Constructor.
 Model (const Model &in)
Model & operator= (const Model &in)
size_t setParamSweepCountClosestTotal (size_t totalCount)
 Adjusts the sweep count so that the total of spectra that need to be generated in the parameter sweep is close to the given value.
DataPoint execute (fvalue omaga, size_t index=0)
 Gets the impedance at the given frequency.
std::vector< DataPoint > executeSweep (const Range &omega, size_t index=0)
 Executes a frequency sweep along the given range.
std::vector< DataPoint > executeSweep (const std::vector< fvalue > &omega, size_t index=0)
 Executes a frequency sweep with the given omega values.
std::vector< std::vector< DataPoint > > executeSweeps (const Range &omega, const std::vector< size_t > &indecies, bool parallel=false)
 Executes a frequency and parameter sweep at the given parameter indecies.
std::vector< std::vector< DataPoint > > executeSweeps (const std::vector< fvalue > &omega, const std::vector< size_t > &indecies, bool parallel=false)
 Executes a frequency and parameter sweep at the given parameter indecies.
std::vector< std::vector< DataPoint > > executeAllSweeps (const Range &omega)
 Executes a frequency sweep with the given omega values for each parameter combination in the applied parameter sweep.
std::string getModelStr () const
 Returns the model string corresponding to this model object, without embedded parameters.
std::string getModelStrWithParam (size_t index)
 Returns the model string corresponding to this model object, with embedded parameters.
std::string getModelStrWithParam () const
 Returns the model string corresponding to this model object, with embedded parameters.
std::string getModelStrWithParamAndCount () const
 Like getModelStrWithParam(), but each swept range also carries its step count.
size_t getUuid () const
 Returns a unique id.
std::vector< Componant * > getFlatComponants (Componant *model=nullptr)
 Returns a vector of pointers to the circuit elements in this model.
Componant * getModelRoot () const
 Returns the root of the circuit element tree.
std::vector< fvalue > getFlatParameters ()
 Gets the values of the parameters of the circuit elements at the current parameter sweep step.
std::vector< Range > getFlatParameterRanges ()
 Gets the ranges of the parameters of the circuit elements.
std::vector< Range > getDefaultParameters ()
 Gets the default ranges of the parameters of each type of circuit element used in the model.
std::vector< std::string > getParameterNames ()
 Gets the names of all the parameters in this model.
size_t getParameterCount ()
 Gets the total number of parameters used by all the circuit elements in this model.
bool compile ()
 This function compiles the model into native vectorized code for faster execution.
void dropCompiled ()
 This function drops the compiled object code, reverting to graph execution.
bool isReady ()
 This member determines if the model is in a state ready to execute.
void resolveSteps (int64_t index)
 This member resolves the parameters of all circuit elements at the given parameter sweep step.
size_t getRequiredStepsForSweeps ()
 Gets the total number of parameter sweep steps for the applied sweep.
bool isParamSweep ()
 Checks if the model is a sweep (i.e.
bool hasDefaultedParameters ()
 Checks if the model string is fully parameterized.
std::string getCode ()
 Compiles this model into efficient c++ code corresponding to the circuit of this model.
std::string getTorchScript ()
 Compiles this model into TorchScript.
std::string getCompiledFunctionName () const
 Gets the function name in the code for this model.
std::vector< size_t > getRecommendedParamIndices (eis::Range omegaRange, double distance, bool threaded=false)
 Gets a set of indecies that together create a iso-difference set of spectra.
bool allElementsContribute (eis::Range omegaRange, fvalue threashold=0.01)
 Attempts to check if all elements contribute to the result.
bool hasSeriesDifference (eis::Range omegaRange, fvalue threashold=0.1)
 Checks if all elements in series with one another dont have too similar impedance.
std::vector< ParameterPermutation > getEquivalentParameterPermutations (eis::Range omegaRange, fvalue tolerance=1e-3, size_t limit=4096, size_t sweepIndex=0)
 Lists the other assignments of this model's parameters that give the same spectrum.

Static Public Member Functions

static void removeSeriesResitance (std::string &model)
 Removes the series reistance from a model string (if any).

Detailed Description

The main class of eisgenerator representing an equivalent circuit model.

Examples
compileing.cpp, simple.cpp, and torchscript.cpp.

Constructor & Destructor Documentation

◆ Model()

eis::Model::Model ( const std::string & str,
size_t paramSweepCount = 100,
bool defaultToRange = true )

Constructor.

Exceptions
parse_errrorIf the model string or its parameters include invalid syntax.
Parameters
strThe model string to create a model object for.
paramSweepCountOptionally the number of sweep point to use for parameter sweeps.
defaultToRangeOptionally a bool that if true, circuit elements not given in str are defaulted to a range instead of a fixed value.

References Model().

Referenced by Model().

Member Function Documentation

◆ allElementsContribute()

bool eis::Model::allElementsContribute ( eis::Range omegaRange,
fvalue threashold = 0.01 )

Attempts to check if all elements contribute to the result.

Parameters
threasholdcontribution ratio below which the contribution is considered irrelivant
omegaRangerange of frequencies to consider
Returns
True if all Contribute false otherwise

◆ compile()

bool eis::Model::compile ( )

This function compiles the model into native vectorized code for faster execution.

This function compiles a shared-object for this model that is then loaded by eisgenerator to speed up execution of this model by a factor of 10 or more by employing vectorization and avoiding function calls.

This function is slow, but results are cached for the lifetime of process linked to libeisgenerator so that a circuit has to be compiled only once and can then be used by any number of Model objects.

This function is only implemented on UNIX, on other platforms this function will always return false. This function also requires that GCC be available in PATH.

Returns
true if compile was successful, false otherwise.
Examples
compileing.cpp.

◆ execute()

DataPoint eis::Model::execute ( fvalue omaga,
size_t index = 0 )

Gets the impedance at the given frequency.

This method calls resolveSteps.

Parameters
omegaThe frequency in rad/s to calculate the impedance at.
indexAn optional index to the parameter sweep step at which to calculate the impedance.
Returns
A DataPoint struct containing the result.
Examples
simple.cpp.

◆ executeAllSweeps()

std::vector< std::vector< DataPoint > > eis::Model::executeAllSweeps ( const Range & omega)

Executes a frequency sweep with the given omega values for each parameter combination in the applied parameter sweep.

This method calls resolveSteps.

Parameters
omegaThe range along which to execute a frequency sweep.
Returns
A vector of vectors of DataPoint structs containing the impedance at every frequency in the sweep with every parameter combination.
Examples
compileing.cpp.

◆ executeSweep() [1/2]

std::vector< DataPoint > eis::Model::executeSweep ( const Range & omega,
size_t index = 0 )

Executes a frequency sweep along the given range.

This method calls resolveSteps.

Parameters
omegaThe range along which to execute a frequency sweep.
indexAn optional index to the parameter sweep step at which to calculate the impedance.
Returns
A vector of DataPoint structs containing the impedance at every frequency in the sweep.
Examples
simple.cpp.

◆ executeSweep() [2/2]

std::vector< DataPoint > eis::Model::executeSweep ( const std::vector< fvalue > & omega,
size_t index = 0 )

Executes a frequency sweep with the given omega values.

Parameters
omegaA vector of frequencies in rad/s to calculate the impedance at.
indexAn optional index to the parameter sweep step at which to calculate the impedance.
Returns
A vector of DataPoint structs containing the impedance at every frequency in the sweep.

◆ executeSweeps() [1/2]

std::vector< std::vector< DataPoint > > eis::Model::executeSweeps ( const Range & omega,
const std::vector< size_t > & indecies,
bool parallel = false )

Executes a frequency and parameter sweep at the given parameter indecies.

Parameters
omegaThe range along which to execute the frequency sweep.
indeciesthe parameter indecies to include in the sweep
parallelif this is set to true, the parameter sweep is executed in parallel
Returns
A vector of vectors of DataPoint structs containing the impedance at every frequency sweep and parameter index.

◆ executeSweeps() [2/2]

std::vector< std::vector< DataPoint > > eis::Model::executeSweeps ( const std::vector< fvalue > & omega,
const std::vector< size_t > & indecies,
bool parallel = false )

Executes a frequency and parameter sweep at the given parameter indecies.

Parameters
omegaA vector of frequencies in rad/s to calculate the impedance at.
indeciesthe parameter indecies to include in the sweep
parallelif this is set to true, the parameter sweep is executed in parallel
Returns
A vector of vectors of DataPoint structs containing the impedance at every frequency sweep and parameter index.

◆ getCode()

std::string eis::Model::getCode ( )

Compiles this model into efficient c++ code corresponding to the circuit of this model.

Returns
The code or an empty string if compilation was unsuccessfully.
Examples
compileing.cpp.

◆ getCompiledFunctionName()

std::string eis::Model::getCompiledFunctionName ( ) const

Gets the function name in the code for this model.

Returns
The function name in the code for this model.
Examples
torchscript.cpp.

◆ getDefaultParameters()

std::vector< Range > eis::Model::getDefaultParameters ( )

Gets the default ranges of the parameters of each type of circuit element used in the model.

Returns
The default ranges of the parameters of each type of circuit element used in the model.

◆ getEquivalentParameterPermutations()

std::vector< ParameterPermutation > eis::Model::getEquivalentParameterPermutations ( eis::Range omegaRange,
fvalue tolerance = 1e-3,
size_t limit = 4096,
size_t sweepIndex = 0 )

Lists the other assignments of this model's parameters that give the same spectrum.

Because series and parallel are commutative and associative, values can often be moved between the parameter slots of a model string without changing the spectrum: "r{100}c{1e-6}-r{333}c{1e-9}" and "r{333}c{1e-9}-r{100}c{1e-6}" are the same circuit. This reports exactly those, and only those - swapping two elements that keep their own values, like "r{100}c{1e-6}" for "c{1e-6}r{100}", is a relabelling of the topology and is not returned.

Elements of different types are included when one can stand in for the other, so a CPE whose exponent is 1 exchanges with a capacitor, at 0.5 with a Warburg and at 0 with a resistor. Nested groups are flattened first, so "r{1}-(r{2}-r{3})" reports all six orderings of the three resistances rather than just the inner pair.

Interchangeability is decided by fitting each element's parameters to the other's impedance curve over a probe grid taken from omegaRange and requiring the residual to stay under tolerance, then confirming every reported permutation against the spectrum of the whole circuit. Cost is a few dozen circuit evaluations, independent of the size of any parameter sweep.

Transmission line elements (t, o) are never matched to anything but their own type: with four parameters they approximate many curves over a finite window, and an equivalence that only holds on the probe grid would be a false positive.

Parameters
omegaRangeFrequencies to probe and verify against.
toleranceRelative residual below which two elements count as interchangeable.
limitMaximum number of candidate permutations to examine, the model string cost grows factorially with the size of a symmetric group.
sweepIndexThe parameter sweep step to take the values from.
Returns
The equivalent assignments, excluding the model's own, empty if there are none.

◆ getFlatComponants()

std::vector< Componant * > eis::Model::getFlatComponants ( Componant * model = nullptr)

Returns a vector of pointers to the circuit elements in this model.

The pointers can only be assumed to be valid until the next non-const member call to this model object.

Parameters
modelFor internal use only.
Returns
A vector of the circuit elements in the model.

◆ getFlatParameterRanges()

std::vector< Range > eis::Model::getFlatParameterRanges ( )

Gets the ranges of the parameters of the circuit elements.

Returns
The ranges of the parameters of the circuit elements.

◆ getFlatParameters()

std::vector< fvalue > eis::Model::getFlatParameters ( )

Gets the values of the parameters of the circuit elements at the current parameter sweep step.

Returns
The values of the parameters of the circuit elements at the current parameter sweep step.
Examples
torchscript.cpp.

◆ getModelRoot()

Componant * eis::Model::getModelRoot ( ) const

Returns the root of the circuit element tree.

Serial and Parallel are themselves Componants, so this together with getFlatComponants() gives access to the whole tree. The pointer can only be assumed to be valid until the next non-const member call to this model object.

Returns
The root element, or nullptr if the model is not ready.

◆ getModelStr()

std::string eis::Model::getModelStr ( ) const

Returns the model string corresponding to this model object, without embedded parameters.

Returns
The model string corresponding to this model object, without embedded parameters.
Examples
compileing.cpp.

◆ getModelStrWithParam() [1/2]

std::string eis::Model::getModelStrWithParam ( ) const

Returns the model string corresponding to this model object, with embedded parameters.

Yhe parameter sweep index of the last call to resolveSteps or 0 is used.

Returns
the model string corresponding to this model object, with embedded parameters

◆ getModelStrWithParam() [2/2]

std::string eis::Model::getModelStrWithParam ( size_t index)

Returns the model string corresponding to this model object, with embedded parameters.

This method calls resolveSteps.

Parameters
indexThe parameter sweep index for which to embed the parameters.
Returns
The model string corresponding to this model object, with embedded parameters.
Examples
compileing.cpp, and simple.cpp.

◆ getModelStrWithParamAndCount()

std::string eis::Model::getModelStrWithParamAndCount ( ) const

Like getModelStrWithParam(), but each swept range also carries its step count.

Ranges are printed as start~endL:count so that the string can be parsed back and reproduces the same parameter sweep instead of falling back to the constructor's sweep count.

Returns
the model string corresponding to this model object, with embedded ranges and counts.

◆ getParameterCount()

size_t eis::Model::getParameterCount ( )

Gets the total number of parameters used by all the circuit elements in this model.

Returns
The total number of parameters.

◆ getParameterNames()

std::vector< std::string > eis::Model::getParameterNames ( )

Gets the names of all the parameters in this model.

Returns
The names of all the parameters in this model.

◆ getRecommendedParamIndices()

std::vector< size_t > eis::Model::getRecommendedParamIndices ( eis::Range omegaRange,
double distance,
bool threaded = false )

Gets a set of indecies that together create a iso-difference set of spectra.

Note: this function generates a signifcant fraction of the number of spectra in the models range use getRequiredStepsForSweeps for an estimate of the complexity. It is strongly recommended to call compile() before using this function.

Parameters
threadedif this is set to true eisgenerator will spawn nproc number of threads to service this request.
distancethe target distance between subisquent spectra relative to eis::eisDistance.
Returns
A vector of indecies corresponding to the iso-difference spectras.

◆ getRequiredStepsForSweeps()

size_t eis::Model::getRequiredStepsForSweeps ( )

Gets the total number of parameter sweep steps for the applied sweep.

Returns
The total number of parameter sweep steps for the applied sweep.

◆ getTorchScript()

std::string eis::Model::getTorchScript ( )

Compiles this model into TorchScript.

Can be compiled to GPU kernel bytecode by torch::jit::compile.

Returns
The TorchScript code or an empty string if compilation was unsuccessful.
Examples
torchscript.cpp.

◆ getUuid()

size_t eis::Model::getUuid ( ) const

Returns a unique id.

This id is only unique for the given circuit description string, not for this object as sutch.

Returns
The uid.

◆ hasDefaultedParameters()

bool eis::Model::hasDefaultedParameters ( )

Checks if the model string is fully parameterized.

A model is fully parameterized when every circuit element carries a value (or a range) for every one of its parameters, e.g. "r{100}c{1e-6}" or "r{1~100L:3}". A model that is missing a value for any parameter, e.g. "r{100}c" or a CPE given only one of its two parameters "p{1e-5}", is not fully parameterized and had to fall back to defaults.

Returns
True if at least one parameter was defaulted, false if the model is fully parameterized.

◆ hasSeriesDifference()

bool eis::Model::hasSeriesDifference ( eis::Range omegaRange,
fvalue threashold = 0.1 )

Checks if all elements in series with one another dont have too similar impedance.

Parameters
threasholdcontribution ratio below which the contribution is considered irrelivant
omegaRangerange of frequencies to consider
Returns
True if all series have a difference false otherwise.

◆ isParamSweep()

bool eis::Model::isParamSweep ( )

Checks if the model is a sweep (i.e.

has at least one parameter with a range).

Returns
True if the model contains a parameter sweep, false otherwise.

◆ isReady()

bool eis::Model::isReady ( )

This member determines if the model is in a state ready to execute.

Returns
True if the model is ready for the execute family of methods.

◆ removeSeriesResitance()

void eis::Model::removeSeriesResitance ( std::string & model)
static

Removes the series reistance from a model string (if any).

Parameters
modelthe model string from wich to remove the seires resitance

◆ resolveSteps()

void eis::Model::resolveSteps ( int64_t index)

This member resolves the parameters of all circuit elements at the given parameter sweep step.

Parameters
indexThe index to the sweep step to resolve to.
Examples
torchscript.cpp.

◆ setParamSweepCountClosestTotal()

size_t eis::Model::setParamSweepCountClosestTotal ( size_t totalCount)

Adjusts the sweep count so that the total of spectra that need to be generated in the parameter sweep is close to the given value.

Parameters
totalCountThe total number of spectra to target.
Returns
The number of spectra that will be generated by a parameter sweep after calling this function, should be close to, but may not be exactly, totalCount.