From bbd01ac2a2ecfb0f369797c721dac23cfcf9a3f0 Mon Sep 17 00:00:00 2001 From: "Philip Mueller, HS" <philip.paul.mueller@bluemail.ch> Date: Thu, 22 Aug 2019 11:04:40 +0200 Subject: [PATCH] Removed the README description of the container interface. The manual is now the only place where the ointerface is documented. --- code/cpp/samples/README.md | 195 ++----------------------------------- 1 file changed, 6 insertions(+), 189 deletions(-) diff --git a/code/cpp/samples/README.md b/code/cpp/samples/README.md index c82e1c34..37a43bf0 100644 --- a/code/cpp/samples/README.md +++ b/code/cpp/samples/README.md @@ -1,190 +1,7 @@ -# Universal Container Interface -The universal container interface is a common semanting among all the -three containers for samples. It was mainly implemented and defined -because of Python's duck typing, which promotes, lets call it that, -a uniform and consisten interface semantic. It consists of basics -and of one extension that is not implemented on C++ level, -but is aviable on Python. +# Info +This folder contains the code for managing samples. +All container implement a common interface. +Once this file contained a description of it. +However it was removed. +Now only the manual contains a documentation of the interface. - -## BASE -The base of the UCI consistes of a set of functions - - -### Construction -This section describes how the container should be constructed. - -> ctr(d) -Constructs an empty container which is able to hold dimension of dimension d. - -> ctr(d, n) -Construct a container with samples of dimension d and n samples allocated. - - -### Accessing -This function delas with the accessing. - -> addNewSample(s) -This function adds sample s at the end of the container. -This could lead to reallocation and will invalidate all pointers, -references and iterators to samples of that container. - -> setSampleTo(s, i) -This function sets the sample that has index i to the provided sample s. -This is like an exchange function. - -> getSample(i) -This function returns a copy to the sample at location i. -It is not a reference, this is important. - - -### Capacity Management -This function delas with the capacity management. - -> resize(newSize) -This function changes the size of the container to newSize. -This function is only allowed if the size of the container is zero. - -> clear() -This function clears the internal memory of teh container and sets the size to zero. -Note that the number of dimensions is not affected by this. -All references and so on are invalidated. - -> Reserve(newCap) -This fucntion allows to püreallocate storage without setting the size of the container. -It only works if the size of the container is zero. -If called on a container that has non zero size, no effect takes place. - - -### Query functions -Thsi functions allows to access the size of the container. - -> nDims() -This function returns the numnber of dimensions samples have inside the container. - -> nSamples() -This function returns the number of samples that are allocated inside the container. - -> size() -This is an alias for nSamples. -Generally it is the bound for the usage of the the subscript operator if provided. -NOTE: -This function is very special. The idea of thsi interface was to enable an -uniform interface among all sample containers. However there is a probelm. -The operator[], bracket operator, behaves differently. -The sample collection is centred around the idea of the composition of -dimensional array, that forms the sample set. So the bracked operator -returns references to the dimensional arrays, consequently the size -operator of the sample collection returns the number of dimensions. -Hower the sample array and the sample list, are centred about samples, -and not dimensions. There the bracket operator reaturns sampels and -thus the size function returns the numnber of sampels. -This is inconsitent, sice it would lead to a divergence between the -C++ level and the python interface. -The final solution that was choosen was, that the python interface, does not -present a size function in any sample container. -Hower it is possible by using the CMake option YGGDRASIL_PYYGGDRASIL_PROVIDE_SIZEFKT=ON -to enable the issue of such a fucntion. -But there one has the incositency that the size function returns always nSamples. -Which is different on the C++ level. - - -### First Extension (C++) -This is the first extension of the interface. -They are optional. - -> operator[](i) -This function returns a reference, that can be written to, to the ith sample of the container. -Thsi reference must not be a true reference, but can also be a proxy class. -Which must be convertable to a sample. -It is recomended that the cast operation to a non const sample reference is deleted. - -#### Python Note -In python this extension is not optional. -However it is not mandatory that __getitem__ returns a reference like structure. -It is allowed to returning a copy. - - -### Second Extension (C++ & Python) -This extension describes methods to accessing a single dimension. -The sample collection implements this already, be the means of operator[]. -That returns a sample array. -This extension requieres the containers to provide the following function. - -> getDimensionArray(d) -This function returns a dimension array. -It is not requiered that the returned type provided writting access, meaning a copy can be returned. -In the C++ level thsi is requiered to be a dimensional array. -In Python this should be an Eigen type that can be transformed to NumPy. - - -### Third Extension -This extension requieres the containers to be initalizable from Eigen types. -The effect of this extension is that the containers can be constructed out of NumPy arrays. -The argument must be of reference type: - Eigen::Ref<MatrixType, 0, Eigen::Stride<Eigen::Dynamic, Eigen::Dynamic> > -where MatrixType is a Matrix. -The 0 is probably for Eigen::Unaligned. -This typedef comes from the pybind manual. - -How the matrix is interpreted can be selected by an argument of the constructor. -It is also recomeneded that column and row major matrices are supported, at least in C++. -Note that in C++ allmost all calls are reduced to a templated function. -This function will exploit the UCI itself. - -> ctr(mat, order) -This function construct a container out of the matrix mat. -How the columns and rows are interpreted is controled by the parmeter order. -It basically describes how the row of _any_ matrix is interpeted. -Note that not all combination of matriox and order paramter are fast and efficient. - -> getMatrix(order) -This function returns an Eigen Matrix. -With the order parameter it can be controlled how the matrix is written. - -#### The ORDER Parameter. -The order Parameter is implemented as an enum, the name of this enum is eMatrixViewRow. -It describes, how a row of a matrix should be interpreted. -It is important to note that this does not depend on the matrix layout of the matrix. -It can have two values. - - > Sample - This means that one row is interpreted as one sample. - Thus the number of columns is the dimeinsionality of the problem. - - > Dimension (rather !Sample) - It is as distinct value present, but technically every value that is not Sample will be interpreted as this one. - It says that the row of a matrix represents a dimension. - Thus the number of columns is the number of samples and the number of rows is the dimensionality. - - - -### Forth Extension -This extension allows the manipulation of a single sample, without the need of loading it. -In addition it also allows to manipulate one dimension at once. -It can also be seen as an extension of the second extension. - -> setSampleComponent(i, j, v) -This function sets the jth component of the ith sample to the value v. -This functionality is provided because only the sample list, which should be avoided, -could provide an easy and efficient way to achieve that. - -> getSampleComponent(i, j) -This function returns the value of the jth component of the ith sample of the container. - -> setDimensionTo(j, v) -This function sets the jth dimension of all samples to v. - -> setDimensionArray(j, a) -This function exchanges the values of dinmension j with the values in the dimensional array a. -The dimension parameter of the array will be ignored. -This fucntion is like the setDimensionTo function, but allows to use a seperate value for the samples. -There is also an overload of thsi function of an Eigen type, whioch allows its usage in Python. -Note: The collection provides more overloads which exploids the internal structure of it. - - - -#### Future Extension -There is the possibility that this extension could also be extended such that index arrays could be used. -In that case v must also be an array as well. -But they are not yet defined nor implemented. -- GitLab