From a45d4935d45eba8e760f1963e660966c76754edc Mon Sep 17 00:00:00 2001 From: Carl Philipp Klemm <philipp@uvos.xyz> Date: Fri, 19 Jan 2024 15:10:06 +0100 Subject: [PATCH] impove documentation --- README.md | 2 -- doc/libeisdrt.doxygen.in | 12 +++++----- eisdrt/eigendrt.h | 33 +++++++++++++------------- eisdrt/eisdrt.h | 51 ++++++++++++++++++++-------------------- eisdrt/eistorchdrt.h | 28 ++++++++++++++++++++++ eisdrt/torchdrt.h | 22 ++++++++--------- eisdrt/types.h | 4 ++-- 7 files changed, 90 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index 0c80065..f90aff7 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,3 @@ -[comment]: \page README Readme - # libeisdrt _libeisdrt_ is a c++ shared library to compute Distribution of Relaxation Times using Tikhonov regularization. diff --git a/doc/libeisdrt.doxygen.in b/doc/libeisdrt.doxygen.in index aca2abc..a023884 100644 --- a/doc/libeisdrt.doxygen.in +++ b/doc/libeisdrt.doxygen.in @@ -259,7 +259,7 @@ ALIASES = # members will be omitted, etc. # The default value is: NO. -OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_FOR_C = NO # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or # Python sources only. Doxygen will then generate output that is more tailored @@ -941,7 +941,7 @@ EXCLUDE_SYMBOLS = # that contain example code fragments that are included (see the \include # command). -EXAMPLE_PATH = @CMAKE_CURRENT_SOURCE_DIR@/doc/ +EXAMPLE_PATH = @CMAKE_CURRENT_SOURCE_DIR@/examples # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and @@ -961,7 +961,7 @@ EXAMPLE_RECURSIVE = NO # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = +IMAGE_PATH = @CMAKE_CURRENT_SOURCE_DIR@/doc/ # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program @@ -1782,7 +1782,7 @@ LATEX_OUTPUT = latex # the output language. # This tag requires that the tag GENERATE_LATEX is set to YES. -LATEX_CMD_NAME = latex +LATEX_CMD_NAME = pdflatex # The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate # index for LaTeX. @@ -1898,7 +1898,7 @@ PDF_HYPERLINKS = NO # The default value is: YES. # This tag requires that the tag GENERATE_LATEX is set to YES. -USE_PDFLATEX = NO +USE_PDFLATEX = YES # If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode # command to the generated LaTeX files. This will instruct LaTeX to keep running @@ -2289,7 +2289,7 @@ HIDE_UNDOC_RELATIONS = YES # set to NO # The default value is: NO. -HAVE_DOT = NO +HAVE_DOT = YES # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed # to run in parallel. When set to 0 doxygen will base this on the number of diff --git a/eisdrt/eigendrt.h b/eisdrt/eigendrt.h index c112de3..147087c 100644 --- a/eisdrt/eigendrt.h +++ b/eisdrt/eigendrt.h @@ -23,22 +23,23 @@ #include "types.h" /** -API for use with Eigen applications +* API for use with Eigen applications * @defgroup EIGENAPI Eigen API -* calculates drts with Eigen datatypes +* +* Calculates drts with Eigen datatypes. * @{ */ /** - * @brief calculate the drt using Eigen datatypes + * @brief Calculates the drt using Eigen datatypes. * - * @tparam fv precision to be used, either double or float - * @param impedanceSpectra vector with the complex impedances of your experiment - * @param omegaTensor vector with the omega values that the impedances where measured at - * @param fm a fit metrics struct where this function returns information on the fit acquired - * @param fp a struct with fit parameters - * @param rSeries an optional parameter where the series resistance is stored - * @return a vector with the drt values + * @tparam fv The precision to be used, either double or float. + * @param impedanceSpectra A vector with the complex impedances of your experiment. + * @param omegaTensor A vector with the omega values that the impedances where measured at. + * @param fm A fit metrics struct where this function returns information on the fit acquired. + * @param fp A struct with fit parameters. + * @param rSeries An optional parameter where the series resistance is stored. + * @return A vector with the drt values. */ template<typename fv> Eigen::VectorX<fv> calcDrt(Eigen::VectorX<std::complex<fv>>& impedanceSpectra, Eigen::VectorX<fv>& omegaTensor, @@ -46,13 +47,13 @@ Eigen::VectorX<fv> calcDrt(Eigen::VectorX<std::complex<fv>>& impedanceSpectra, E /** - * @brief calculate impedance from drt using Eigen datatypes + * @brief Calculates impedance from drt using Eigen datatypes. * - * @tparam fv precision to be used, either double or float - * @param drt the drt to calculate impedance from - * @param omegaVector vector with the omega values that the impedances where measured at - * @param rSeries an optional parameter where the series resistance is stored - * @return a vector with the drt values + * @tparam fv The precision to be used, either double or float. + * @param drt The drt to calculate impedance from. + * @param omegaVector A vector with the omega values that the impedances where measured at. + * @param rSeries An optional parameter where the series resistance is stored. + * @return A vector with the drt values. */ template<typename fv> Eigen::VectorX<std::complex<fv>> calcImpedance(const Eigen::VectorX<fv>& drt, fv rSeries, const Eigen::VectorX<fv>& omegaVector); diff --git a/eisdrt/eisdrt.h b/eisdrt/eisdrt.h index a14a287..125da9c 100644 --- a/eisdrt/eisdrt.h +++ b/eisdrt/eisdrt.h @@ -23,53 +23,54 @@ #include "types.h" /** -API for use with eisgenerator applications +* API for use with eisgenerator applications * @defgroup EISAPI eisgenerator API -* calculates drts with eisgenerator datatypes +* +* Calculates drts with eisgenerator datatypes. * @{ */ /** - * @brief calculate a drt on eisgenerator types + * @brief Calculates a drt on eisgenerator types. * - * @param data a vector of eisgenerator data points with the values to your experiment, embedded omega values are ignored - * @param omegaVector vector with the omega values that the impedances where measured at - * @param fm a fit metrics struct where this function returns information on the fit acquired - * @param fp a struct with fit parameters - * @param rSeries an optional parameter where the series resistance is stored - * @return a vector with the drt values + * @param data A vector of eisgenerator data points with the values to your experiment, embedded omega values are ignored. + * @param omegaVector A vector with the omega values that the impedances where measured at. + * @param fm A fit metrics struct where this function returns information on the fit acquired. + * @param fp A struct with fit parameters. + * @param rSeries An optional parameter where the series resistance is stored. + * @return A vector with the drt values. */ std::vector<fvalue> calcDrt(const std::vector<eis::DataPoint>& data, const std::vector<fvalue>& omegaVector, FitMetics& fm, const FitParameters& fp, fvalue* rSeries = nullptr); /** - * @brief calculate a drt on eisgenerator types + * @brief Calculates a drt on eisgenerator types. * - * @param data a vector of eisgenerator data points with the values to your experiment, embedded omega values are used - * @param fm a fit metrics struct where this function returns information on the fit acquired - * @param fp a struct with fit parameters - * @param rSeries an optional parameter where the series resistance is stored - * @return a vector with the drt values + * @param data A vector of eisgenerator data points with the values to your experiment, embedded omega values are used. + * @param fm A fit metrics struct where this function returns information on the fit acquired. + * @param fp A struct with fit parameters. + * @param rSeries An optional parameter where the series resistance is stored. + * @return A vector with the drt values. */ std::vector<fvalue> calcDrt(const std::vector<eis::DataPoint>& data, FitMetics& fm, const FitParameters& fp, fvalue* rSeries = nullptr); /** - * @brief calculate impedance from drt using eisgenerator datatypes + * @brief Calculate impedance from drt using eisgenerator datatypes. * - * @param drt the drt to calculate impedance from - * @param omegaVector vector with the omega values that the impedances where measured at - * @param rSeries an optional parameter where the series resistance is stored - * @return a vector with the impedance values + * @param drt The drt to calculate impedance from. + * @param omegaVector A vector with the omega values that the impedances where measured at. + * @param rSeries An optional parameter where the series resistance is stored. + * @return A vector with the impedance values. */ std::vector<eis::DataPoint> calcImpedance(const std::vector<fvalue>& drt, fvalue rSeries, const std::vector<fvalue>& omegaVector); /** - * @brief calculate impedance from drt using eisgenerator datatypes + * @brief Calculates impedance from drt using eisgenerator datatypes. * - * @param drt the drt to calculate impedance from - * @param omegaRange range that describes the omega values the drt was taken at - * @param rSeries an optional parameter where the series resistance is stored - * @return a vector with the impedance values + * @param drt The drt to calculate impedance from. + * @param omegaRange A range that describes the omega values the drt was taken at. + * @param rSeries An optional parameter where the series resistance is stored. + * @return A vector with the impedance values. */ std::vector<eis::DataPoint> calcImpedance(const std::vector<fvalue>& drt, fvalue rSeries, const eis::Range& omegaRange); diff --git a/eisdrt/eistorchdrt.h b/eisdrt/eistorchdrt.h index eb8e9b5..8a5f1d5 100644 --- a/eisdrt/eistorchdrt.h +++ b/eisdrt/eistorchdrt.h @@ -28,10 +28,38 @@ * @{ */ +/** + * @brief Calculates impedance from drt using torch datatypes. + * + * This function ignores the frequencies in data and uses those from omegaVector + * + * @param data The spectra to calculate impedance from. + * @param omegaVector A vector of radial frequencies to calculate the drt at. + * @param fm A fit metrics struct where this function returns information on the fit acquired. + * @param fp A struct with fit parameters. + * @return A complex tensor with the drt values. + */ torch::Tensor calcDrtTorch(const std::vector<eis::DataPoint>& data, const std::vector<fvalue>& omegaVector, FitMetics& fm, const FitParameters& fp); +/** + * @brief Calculates impedance from drt using torch datatypes. + * + * @param data The spectra to calculate impedance from. + * @param fm A fit metrics struct where this function returns information on the fit acquired. + * @param fp A struct with fit parameters. + * @return A complex tensor with the drt values. + */ torch::Tensor calcDrtTorch(const std::vector<eis::DataPoint>& data, FitMetics& fm, const FitParameters& fp); + +/** + * @brief Calculates impedance from drt using eisgenerator datatypes. + * + * @param drt The drt to calculate impedance from. + * @param omegaRange A range that describes the omega values the drt was taken at. + * @param rSeries An optional parameter where the series resistance is stored. + * @return A vector with the impedance values. + */ torch::Tensor calcImpedance(torch::Tensor& drt, fvalue rSeries, const std::vector<fvalue>& omegaVector); /** diff --git a/eisdrt/torchdrt.h b/eisdrt/torchdrt.h index e0aafc8..3a3949f 100644 --- a/eisdrt/torchdrt.h +++ b/eisdrt/torchdrt.h @@ -29,24 +29,24 @@ Api for use with libtorch applications */ /** - * @brief calculate a drt on eisgenerator types + * @brief Calculates a drt on eisgenerator types. * - * @tparam fv precision to be used, either double or float - * @param impedanceSpectra a 1d complex tensor with the impedance measurement data points - * @param omegaTensor a 1d tensor with the omega values that the impedances where measured at - * @param fm a fit metrics struct where this function returns information on the fit acquired - * @param fp a struct with fit parameters - * @return a 1d tensor with the drt values + * @tparam fv The Precision to be used, either double or float. + * @param impedanceSpectra A 1d complex tensor with the impedance measurement data points. + * @param omegaTensor A 1d tensor with the omega values that the impedances where measured at. + * @param fm A fit metrics struct where this function returns information on the fit acquired. + * @param fp A struct with fit parameters. + * @return A 1d tensor with the drt values. */ template<typename fv> torch::Tensor calcDrtTorch(torch::Tensor& impedanceSpectra, torch::Tensor& omegaTensor, FitMetics& fm, const FitParameters& fp); /** - * @brief calculates impedance from drt + * @brief Calculates impedance from drt. * - * @tparam fv precision to be used, either double or float - * @param drt the drt to calculate impedance from - * @return a complex tensor with the impedance spectra + * @tparam fv The Precision to be used, either double or float. + * @param drt The drt to calculate impedance from. + * @return A complex tensor with the impedance spectra. */ template<typename fv> torch::Tensor calcImpedance(torch::Tensor& drt, fv rSeries, torch::Tensor& omegaVector); diff --git a/eisdrt/types.h b/eisdrt/types.h index 76bb656..a3cca28 100644 --- a/eisdrt/types.h +++ b/eisdrt/types.h @@ -30,7 +30,7 @@ Types for use with all eisdrt apis /** - * @brief Exception thrown if drt could not be calculated + * @brief This exception thrown if drt could not be calculated. */ class drt_errror: public std::exception { @@ -45,7 +45,7 @@ public: }; /** - * @brief Returned information on a fit + * @brief This is used to return information on a fit. */ struct FitMetics { -- GitLab