diff --git a/README.md b/README.md new file mode 100644 index 0000000..80bb18c --- /dev/null +++ b/README.md @@ -0,0 +1,111 @@ +# Multi Array Container Library + +## Description + +This library provides a framework for handling multi dimensional containers. This includes the basic container class template `MultiArrayBase` and their derivates, the Range class templates on which the containers are defined, as well as some operation class templates, which allow comfortable calling of operations on the containers. + +## Build instructions + +The library can be installed by the following procedure (`gtest` required): + +```bash +git clone git@rqcd.ur.de:czimmermann/multi_array.git +cd +cmake -DCMAKE_INSTALL_PREFIX:PATH= +make install +``` + +## Usage and Examples + +To use the features of the libraries one has to include `multi_array_header.h` and link against the `libmultiarray.so`. +The tools of the library are accessible within the namespace `MultiArrayTools`. + +### Some Terms + +* Ranges: A set of meta data which is mapped onto the linear position. Every container is supposed to be defined on at least one Range. In the simplest case a Range space "containes" the numbers [0,...,rangesize]. Ranges have to be created via the corresponding factory and only exist within a shared pointer. They cannot be copied. The reason is, that every operation performed on the containers, has to identify common sets of ranges, on which the containers are defined. Every range inherits the `RangeBase` class. + +* Indices: They can be thought of as iterators of the range space. In the special case of the `ContainerIndex` it is also an iterator over the corresponding container. The index type must be known at compile time (static polymorphism). Indices on a range can be obtained by `getIndex( range )`. For Container Indices call the `begin()` function of a `MultiArray`. Indices are crucial for defining operations. + +* `MultiArray`: Contains data of type `T` and is defined on `Ranges...`. +* `[Const]Slice`: Views data of type `T` and acts as a MultiArray defined on `Ranges...`. +* `FunctionalMultiArray`: Additional template argument indicating the funtion. The value at some position is then defined by the function value obtained from the meta data of the indices/ranges. + +On each of these types one can perform an operation by calling `operator(...)` where within the braces the corresponding indices have to be specified (see example below). + +### Example + +```c++ + +#include "multi_array_header.h" + +namespace mat = MultiArrayTools; + +typedef mat::SingleRange DRange; +typedef mat::SingleRangeFactory DRangeF; +typedef mat::SingleRange SRange; +typedef mat::SingleRangeFactory SRangeF; +typedef mat::SingleRange CRange; // also provided as 'ClassicR' +typedef mat::SingleRangeFactory CRangeF; + +/*create ranges*/ +std::vector meta1({...}); +std::vector meta2({...}); +std::vector meta3({...}); + +DRangeF drf1(meta1); +DRangeF drf2(meta2); +SRangeF srf(meta3); +CRangeF crf(10); // specialized in this case; only size needed. + +auto dr1 = mat::createExplicit( drf1 ); +auto dr2 = mat::createExplicit( drf2 ); +auto sr = mat::createExplicit( srf ); +auto cr = mat::createExplicit( crf ); + +mat::MultiArray ma_a(dr1,dr2,sr,cr,0); +mat::MultiArray ma_b(sr,sr,0); + +/* assign some values... */ +double val = 1.; +for(auto& x: ma_a){ + x = val += 1; +} + +for(auto& x: ma_b){ + x = val /= 2.; +} + +mat::FunctionalMultiArray,DRange,DRange> fma(dr1,dr2); +mat::MultiArray res1(dr1,dr2); +mat::MultiArray res2(dr1,dr2); + +/* get indices... */ +auto i1 = mat::getIndex( dr1 ); +auto i2 = mat::getIndex( dr2 ); +auto i3 = mat::getIndex( sr ); +auto i4 = mat::getIndex( sr ); +auto i5 = mat::getIndex( cr ); + +i3->at(); +i5->at(); + +/* performs plus operation on each element in hypercube spanned by i1,i2,i4 +* and sums up resulting values by iterating over i4. i3 and i5 are fixed to the positions +* given by the meta data above : */ +res1(i1,i2) = (ma_a(i1,i2,i4,i5) + ma_b(i4,i3)).c(i4); + +/* calculates i2.meta() + i1.meta() and divide res1 at the corresponding entry by the result */ +res2(i1,i2) = res1(i1,i2) / fma(i2,i1) +``` + +Further examples will follow; you can also look in the test executable source files in `./src/test/*.cc` + +# Planned features + +Basically the structure of the operation routines allows in some cases (at least in those, where it is possible for simple c++ for loops) vectorization and multi threading. So far the necessary implamentations are not done, but it is planned to enable these features. + +# Known Issues + +I didn't care that much about error handling because of missing time. There it might happen that you declare a `MultiArray` or `Slice` and an operation on it yields a segfault because it was forgotten to instancate the underlying container. Of course, there should be some mechanism, that catches such things, but due to the afore mentioned lack of time, it has not been implemented in every case. If you encounter such problems, pleas tell me, but be aware, that I won't fix it very soon. + +There are unit tests, which cover the all crucial parts of this library, but probably not every special case. Hence, there is no warranty, that, if you do something fancy I didn't consider, everything works fine. \ No newline at end of file diff --git a/src/include/functional_multi_array.cc.h b/src/include/functional_multi_array.cc.h index fd116c0..1cced61 100644 --- a/src/include/functional_multi_array.cc.h +++ b/src/include/functional_multi_array.cc.h @@ -9,11 +9,6 @@ namespace MultiArrayTools * FunctionalMultiArray * ****************************/ - /* - template - FunctionalMultiArray::FunctionalMultiArray(const Range& range) : - MultiArrayBase(range), mFunc() {} - */ template struct Application { @@ -103,24 +98,6 @@ namespace MultiArrayTools return ConstOperationRoot( *mMaPtr, inds... ); } - /* - template - auto FunctionalMultiArray:: - exec(const std::shared_ptr&... inds) const - -> decltype( mkOperation( mFunc, ConstOperationRoot( mkMAObject( inds ), inds) ... ) ) - { - return mkOperation( mFunc, ConstOperationRoot( mkMAObject( inds ), inds ) ... ); - } - */ - /* - template - auto FunctionalMultiArray:: - exec(const std::shared_ptr&... inds) const - -> decltype( mkOperation( mFunc, mkOpObject(inds) ... ) ) - { - return mkOperation( mFunc, mkOpObject(inds) ... ); - } - */ template auto FunctionalMultiArray:: exec(const std::shared_ptr&... inds) const diff --git a/src/include/functional_multi_array.h b/src/include/functional_multi_array.h index 9bc3d6d..7f4c50b 100644 --- a/src/include/functional_multi_array.h +++ b/src/include/functional_multi_array.h @@ -41,36 +41,6 @@ namespace MultiArrayTools return std::make_shared::mk(i))> (ToMAObject::mk(i)); } - /* - template - struct ToOpObject - { - template - static auto mk(const std::shared_ptr& ind) - -> MetaOperationRoot - { - typedef typename Index::RangeType RangeType; - MultiRangeFactory mrf(ind->range()); - auto mr = std::dynamic_pointer_cast( mrf.create() ); - typedef typename MultiRange::IndexType::MetaType value_type; - ContainerIndex ci(mr,0); - return MetaOperationRoot(ci); - } - }; - - template <> - struct ToOpObject - { - template - static auto mk(const std::shared_ptr& ind) - -> ConstOperationRoot - { - return ConstOperationRoot( mkMAObject(ind), ind); - } - }; - */ template struct ToOpObject @@ -100,9 +70,7 @@ namespace MultiArrayTools typedef ContainerRange CRange; typedef MultiArrayBase MAB; - //typedef typename MultiArrayBase::const_iterator const_iterator; typedef ContainerIndex IndexType; - //typedef typename CRange::IndexType IndexType; typedef MultiArray MAType; typedef T value_type; @@ -128,12 +96,8 @@ namespace MultiArrayTools virtual bool isSlice() const override; virtual std::shared_ptr > anonymous(bool slice = false) const override; - - // EVALUTAION CLASS ??!!!! auto exec(const std::shared_ptr&... inds) const - // -> decltype( mkOperation( mFunc, ConstOperationRoot( mkMAObject( inds ), inds) ... ) ); - //-> decltype( mkOperation( mFunc, mkOpObject(inds) ... ) ); -> Operation...>; virtual ConstOperationRoot diff --git a/src/include/multi_array_header.h b/src/include/multi_array_header.h index c78406f..1e07b74 100644 --- a/src/include/multi_array_header.h +++ b/src/include/multi_array_header.h @@ -4,13 +4,6 @@ #define __multi_array_header_h__ #include -//#include "base_def.h" -//#include "range_base.h" -//#include "index_base.h" -//#include "single_range.h" -//#include "multi_range.h" -//#include "container_range.h" -//#include "block.h" #include "multi_array_operation.h" #include "multi_array_base.h" #include "multi_array.h" @@ -19,48 +12,6 @@ #include "operation_def.h" #include "map_range.h" #include "expressions.h" -//#include "slice.h" -//#include "manipulator.h" -//#include "range_transformer.h" -//#include "ma_functional.h" - -namespace MultiArrayTools -{ - - /********************************* - * Some standard definitions * - *********************************/ - /* - // ===== Index Types ===== - - typedef SingleIndex GenericNI; - typedef SingleIndex GenericFI; - typedef SingleIndex LorentzI; - typedef SingleIndex Space1dNI; - typedef SingleIndex Mom1dNI; - typedef SingleIndex EnsI; - typedef SingleIndex, RangeType::MOMENTUM> LinMomI; - typedef SingleIndex, RangeType::MOMENTUM> LinMom4dI; - // ... - - // ===== Range Types ===== - - typedef SingleRange GenericNR; - typedef SingleRange GenericFR; - typedef SingleRange LorentzR; - typedef SingleRange Space1dNR; - typedef SingleRange DistanceNR; - typedef SingleRange Mom1dNR; - typedef SingleRange EnsR; - typedef MultiRange Space3dNR; - typedef MultiRange Mom3dNR; - typedef SingleRange ValErrR; - typedef SingleRange, RangeType::MOMENTUM> LinMomR; - typedef SingleRange, RangeType::MOMENTUM> LinMom4dR; - // ... - */ - -} #include "multi_array_header.cc.h"