[LANGUAGE INCOMPATIBILITY] Constructing pure DQ with double values as arguments

[ffasilva]

---

Code of Conduct

By submitting this report you automatically agree that you've read and accepted the following conditions.

• Support for DQ Robotics is given voluntarily and it's not the developers' role to educate and/or convince anyone of their vision.
• Any possible response and its timeliness will be based on the relevance, accuracy, and politeness of a request and the following discussion.
• If a DQ Robotics member replies, the user must let them know if their response solves their issue or not.
• Any suggestion/advice/request made by anyone, as well intentioned as they might be, might not be incorporated into DQ Robotics.

---

Describe the missing/unexpected functionality

This problem is somewhat related to #24, but using a different constructor for pure quaternions or pure dual quaternions. Namely, when constructing them using double values, the C++ version of the code does not return pure quaternions or pure dual quaternions. In contrast, this construction is possible in MATLAB.

Matlab behavior

MATLAB SCRIPT

DQ([1., 2., 3.])

MATLAB OUTPUT

ans = 

         1i + 2j + 3k

C++ behavior

C++ Code

#include <iostream>
#include <dqrobotics/DQ.h>

using namespace std;

int main()
{
    DQ_robotics::DQ should_be_pure = DQ_robotics::DQ(1., 2., 3.);
    cout << "should_be_pure = " << should_be_pure << endl;

    return 0;
}

CMakeLists.txt

CMAKE_MINIMUM_REQUIRED(VERSION 3.1)
include(${CMAKE_CURRENT_SOURCE_DIR}/../dqrobotics_dependencies.cmake)

project(simple_class_tests)
set (CMAKE_CXX_STANDARD 11)

FIND_PACKAGE(Eigen3 REQUIRED)
INCLUDE_DIRECTORIES(${EIGEN3_INCLUDE_DIR})
ADD_COMPILE_OPTIONS(-Werror=return-type -Wall -Wextra -Wmissing-declarations -Wredundant-decls -Woverloaded-virtual)

# DQ Dynamics library is installed here when using the regular
# cmake ., make, sudo make install
LINK_DIRECTORIES(
    /usr/local/lib/)

add_executable(test_dq_pure
    test_dq_pure.cpp
    )

TARGET_LINK_LIBRARIES(test_dq_pure
    dqrobotics
)

C++ OUTPUT

p = 1 + 2i + 3j

Environment:

• OS: Ubuntu 22.04.5 LTS
• dqrobotics version: development
• MATLAB version: R2023b

Additional context

One possible solution would be to overload the constructor

explicit DQ(const double& q0=0.0,
                const double& q1=0.0,
                const double& q2=0.0,
                const double& q3=0.0,
                const double& q4=0.0,
                const double& q5=0.0,
                const double& q6=0.0,
                const double& q7=0.0) noexcept;

to behave similarly to the one in MATLAB, which throws:

The DQ constructor accepts only vectors with 1 (scalar), 3 (pure quaternion), 4 (quaternion), 6 (pure dual
quaternion) or 8 (dual quaternion) elements.

[mmmarinho]

Hi @ffasilva ,

The C++ equivalent of sending a MATLAB vector to the DQ constructor is sending a VectorXd, as mentioned in #24. I recommend using that syntax if you're looking for similar behaviour.

The constructor with const double& might be safely removed from the library if duly checked, because it's a legacy constructor. As far as I remember, it's not even used in the Python bindings.

PS: Mathematically I would recommend using i_, j_, k_, and E_ as you would in pen and paper. This has been the preferred way in my tutorials as much as possible.

[mmmarinho]

@dqrobotics/developers,

I'll leave this open in case someone decides to deprecate and eventually remove this constructor. With the current constructor signature, there is no way to "fix" it to follow the vectorised version's logic without modifying the parameters.

Because the default fields are set as zero, the compiler is incapable of distinguishing when sequential values are zero on purpose or simply not defined by the user. Hence, the "desired" behaviour cannot be emulated robustly by argument check logic. In contrast, if the default values were invalid, e.g. std::nan, we could differentiate them safely.

For instance, we can't know if the user typed the completely reasonable quaternion j_

a = DQ(0,0,1,0)

or the completely reasonable pure quaternion k_

b = DQ(0,0,1)

given that from the point-of-view of the compiler these two function calls are changed to

a = DQ(0,0,1,0,0,0,0,0)
b = DQ(0,0,1,0,0,0,0,0)

[bvadorno]

Hi all,

PS: Mathematically I would recommend using i_, j_, k_, and E_ as you would in pen and paper. This has been the preferred way in my tutorials as much as possible.

I totally agree. Apart from, perhaps, very old MATLAB examples, this is the preferred way I've been using in the examples I provided for MATLAB. I'd tend to reject any PR with unnecessary vectorized forms because of the philosophy adopted in the library. Nonetheless, even if one wants to use the vectorized constructor form, they should use a vector as done in MATLAB, not a variable number of doubles. So, indeed, the construction that @ffasilva tried to use is not compliant with MATLAB and should be removed.

@ffasilva, could you please open a pull request to remove this deprecated constructor? Thanks!

Kind regards,
Bruno

[ffasilva]

Hi @bvadorno and @mmmarinho,

I was working on removing this constructor, but I'm unsure what the best approach is now. The problem is that this is the only constructor for uninitialised dual quaternions we have in C++. Consequently, if I deprecate it, i.e.,

[[deprecated("Deprecation message goes here.")]]
explicit DQ(const double& q0=0.0,
            const double& q1=0.0,
            const double& q2=0.0,
            const double& q3=0.0,
            const double& q4=0.0,
            const double& q5=0.0,
            const double& q6=0.0,
            const double& q7=0.0) noexcept;

any declaration of an uninitialised dual quaternion, e.g.,

DQ x;

will throw the deprecation warning message, e.g.,

warning: 'DQ' is deprecated: Deprecation message goes here.

This will show up not only on all declarations of uninitialised dual quaternions made by the users, but in any calls they make to methods in the library that internally declare uninitialised DQs (e.g., DQ DQ::norm()).

I believe this spam of deprecation warnings is not an intended behavior for the next release. However, since this constructor has default values for all its parameters, I can't add another default constructor that takes no arguments to replace it, as it would result in an ambiguous declaration. That is, we can't have

explicit DQ();

[[deprecated("Deprecation message goes here.")]]
explicit DQ(const double& q0=0.0,
            const double& q1=0.0,
            const double& q2=0.0,
            const double& q3=0.0,
            const double& q4=0.0,
            const double& q5=0.0,
            const double& q6=0.0,
            const double& q7=0.0) noexcept;

The only solution I could think of for this is to remove this constructor rather than deprecating it. This will break user codes and internal library methods (e.g., DQ DQ::Re(), DQ DQ::Im(), DQ DQ::conj(), etc.) currently relying on it, but that's something we already would have to fix on subsequent releases.

Let me know if I can proceed with this idea, or what would be a better approach.

Kind regards,
Frederico

[mmmarinho]

Hi @ffasilva,

You can try this:

DQ() noexcept;

[[deprecated("Deprecation message goes here.")]]
explicit DQ(const double& q0,
            const double& q1=0.0,
            const double& q2=0.0,
            const double& q3=0.0,
            const double& q4=0.0,
            const double& q5=0.0,
            const double& q6=0.0,
            const double& q7=0.0) noexcept;

Note the difference const double& q0 instead of how it was before. Could you please check if this would work?

The behaviour from the user side should be pretty much the same, but please let me know if not.

Kind regards,
Murilo

PS: The [[deprecated]] attribute is only for compilation time, so it should be fine. Although indeed, it would be a lot of warnings.

PPS: Removing explicit from the default constructor as I don't think it would do anything.

[ffasilva]

Hi @mmmarinho,

Thank you, that works! I'll proceed with your suggestion!

Kind regards,
Frederico