@@ -1523,6 +1523,7 @@ The interface is called \pyYggdrasil .
...
@@ -1523,6 +1523,7 @@ The interface is called \pyYggdrasil .
%
%
The sample collection is the only collection that naturally allow such kind of access, the other container have to construct such a container.
The sample collection is the only collection that naturally allow such kind of access, the other container have to construct such a container.
It is thus not recommended to use this function on containers others than sample collection if not especially needed.
It is thus not recommended to use this function on containers others than sample collection if not especially needed.
See also the fourth extension for more functions.
\begin{description}
\begin{description}
...
@@ -1601,6 +1602,64 @@ The interface is called \pyYggdrasil .
...
@@ -1601,6 +1602,64 @@ The interface is called \pyYggdrasil .
% END: Third extension
% END: Third extension
%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%
\paragraph{Fourth Extension}
The fourth extension is actually an extension of the second extension.
It contains functions that were forgotten when the second one was made.
As the second one this one deals with the interaction with samples.
The primary goal of this extension is to solve some problems that occurs when single samples should be manipulated.
This is especially important when working in Python where no references are available\footnote{There are references in Python, but not as in \CPP{}. }, so a lot of temporary copies are needed.
%
\begin{description}
\item[\texttt{setSampleComponent(i, j, v)}]
This function allows to manipulate a single component of a sample inside the container.
Without this function one would first need to copy the sample into a temporary.
Then modifying the sample and then copy it back to the container.
%
\\
%
See also section \ref{seq:bugs:strange:doubleBracketWithContainer} on page \pageref{seq:bugs:strange:doubleBracketWithContainer}.
\item[\texttt{getSampleComponent(i, j)}]
This function returns the $j$th component of the $i$th sample.
This function removes the need to first copy the sample into a temporary and then accessing the component.
\item[\texttt{setDimensionTo(j, v)}]
This function is similar to the \texttt{setSampleComponent()} function.
It also manipulates a single component, but on \emph{all} samples.
The $j$ component of all samples will be set to the value $v$.
\item[\texttt{setDimensionArray(j, dArr)}]
This function is the set-counterpart to the function that is defined the second extension.
It allows to modify the values of the $j$th component of all samples, the values are read from the \texttt{dArr} argument, which is an NumPy type.
Unlike the \texttt{setDimensionTo()} function, which only allows to use one value for all components, this function allows to use a different value for each sample.
%
\\
%
In \pyYggdrasil{} this function operates on NumPy/Eigen arrays, but on \CPP{} it is also possible to operate on dimensional array objects.
Especially when operating on sample collections there are many overloads provided, please see the doxygen documentation for more information.
\end{description}
\subparagraph{Index Operations}
There are still some operations that could be useful and needed in certain cases.
So it is possible that this extension gets extended in the future.
The goal of this extensions will be to better mimic a NumPy array.
%
It is also better for the performance of some operations.
% END: Index-Operation
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% END: Fourth Extension
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% END: UCI
% END: UCI
%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%
...
@@ -3388,6 +3447,33 @@ This section lists all known bugs, but also strange behaviour that can be observ
...
@@ -3388,6 +3447,33 @@ This section lists all known bugs, but also strange behaviour that can be observ
% END: Iterating In python
% END: Iterating In python
%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Changing a Single Component}~\label{seq:bugs:strange:doubleBracketWithContainer}
This behaviour affects \pyYggdrasil{} but also partially the \CPP{} side of \Yggdrasil .
Assume that you have a container with some samples in it.
Now you want to change the $j$ component of the $i$ sample to the value $v$.
Since both the containers and the sample supports the \texttt{operator\-[](k)} operator (in Python), you could be tempted to write something like.
\begin{center}
\texttt{container[i][j] = v}
\end{center}
But this will not works, it will have no effect.
The reason is that in Python there are no references\footnote{There are references but they are a bit different than they are in \CPP .}.
So in \pyYggdrasil{} the bracket operators returns \emph{copies}.
To understand this better, you must think of the above as two lines, such as.
\begin{center}
\texttt{tmp = container[i]}\\
\texttt{tmp[j] = v}
\end{center}
%
This means you first load a temporary copy of the $i$ sample from the container.
Then you will set the $j$th component of that sample to $v$.
Since there is no connection between \texttt{tmp} and the sample inside the container, there will be no effect at all.
This issue is addressed with the fourth extension of the container interface.
