About

maxon::Complex is a MAXON API class used to represent complex numbers and deliver standard mathematical operations. A complex number is a number that can be expressed in the form a + bi, where a and b are real numbers, and i is a solution of the equation x^2 = -1, which is called an imaginary number because there is no real number that satisfies this equation. For the complex number a + bi, a is called the real part, and b is called the imaginary part. Usually complex numbers are represented in a 2D plane known as "complex plane" or "Argand plane" with the abscissa representing the real part and the ordinate representing the imaginary part.

Creation and initialization

A maxon::Complex instance can be created on the stack and initialized through the proper method using a numerical data type as template:

maxon::Complex::Complex(): creates a zero-valued complex number instance on the stack;
maxon::Complex::Complex(const T real): creates a complex number whose real part is valued with the passed parameter's value
maxon::Complex::Complex(const T real, const T imag): creates a complex number whose real and imaginary parts are valued with the respectively passed parameters' values

    // This example allocates a few maxon::Complex objects showing the different allocation methods.
 
    // just allocate an zero-valued complex object
    const maxon::Complex<maxon::Float> zeroComplex;
 
    // just allocate a complex object defining the real part
    const maxon::Complex<maxon::Float> realOnlyComplex(1.4);
 
    // just allocate a complex object defining both real and imaginary part
    const maxon::Complex<maxon::Float> fullComplex(1.4, 4);
 

Standard operations

The maxon::Complex class delivers a set of standard mathematical operators to perform calculation with complex numbers. The operators delivered are:

maxon::Complex::operator+=(): right-assigns the sum of the current value and of the maxon::Complex used in the expression;
maxon::Complex::operator-=(): right-assigns the difference of the current value and of the maxon::Complex used in the expression;
maxon::Complex::operator*=(): right-assigns the product of the current value and of the maxon::Complex used in the expression;
maxon::Complex::operator+(): return the sum of two maxon::Complex instances;
maxon::Complex::operator-(): return the difference of two maxon::Complex instances;
maxon::Complex::operator*(): return the product of two maxon::Complex instances;
maxon::Complex::operator*(const T s) const: return a maxon::Complex instance scaled by "s";
maxon::Complex::operator*(const T s, const Complex& c): scales the passed maxon::Complex instance "c" by the passed parameter's value "s".

    // This example shows how to perform simple mathematical operations.
 
    // just allocate a complex object defining the real part
    const maxon::Complex<maxon::Float> complexA(2);
 
    // just allocate a complex object defining both real and imaginery part
    maxon::Complex<maxon::Float> complexB(1, -3);
 
    // sum A to B
    complexB += complexA;
 
    // allocate a new complex number and assign the difference between B and A
    const maxon::Complex<maxon::Float> complexC = complexB - complexA;
 
    // allocate a new complex number and assign the product between A and C
    const maxon::Complex<maxon::Float> complexD = complexA * complexC;
 
    // scale the complexB by a given amount
    complexB = complexB * 10;

Get and Set operations

The maxon::Complex class is provided with a number of get methods to retrieve useful data from a maxon::Complex instance:

maxon::Complex::GetSquaredLength(): computes the squared magnitude/length/norm in the Argand plane;
maxon::Complex::GetLength(): computes the magnitude/length/norm in the Argand plane;
maxon::Complex::GetPhase(): computes the angle of the complex vector in the Argand plane;
maxon::Complex::GetNormalized(): gets a complex vector with normalized length in the Argand plane;
maxon::Complex::GetConjugate(): gets the complex conjugate of the complex vector;
maxon::Complex::GetSqrt(): gets the square root of the complex vector;
maxon::Complex::GetLog(): computes the natural logarithm of the complex vector;
maxon::Complex::GetDivision(const Complex& divisor) const: computes the division of the complex value by the passed parameter's value;

    // This example shows how to use the "get" methods provided with maxon::Complex.
 
    // just allocate a complex object defining the real part
    const maxon::Complex<maxon::Float> complexA(2, 2);
 
    // get the length of the vector representing the complex number on the Argand plane
    const maxon::Float lengthValue = complexA.GetLength();
 
    // get the angle (in radians) of the vector representing the complex number on the Argand plane
    const maxon::Float angleValue = complexA.GetPhase();
 
    // get the squared length of the vector representing the complex number on the Argand plane
    const maxon::Float squaredlengthValue = complexA.GetSquaredLength();
 
    // get the normalized vector representing the complex number on the Argand plane
    const maxon::Complex<maxon::Float> normalized = complexA.GetNormalized();
 
    // get the complex conjugate of the vector representing the complex number on the Argand plane
    const maxon::Complex<maxon::Float> conjugate = complexA.GetConjugate();
 
    // get the sqrt of the complex number
    const maxon::Complex<maxon::Float> sqrt = complexA.GetSqrt();
 
    // get the natural log of the complex number
    const maxon::Complex<maxon::Float> log = complexA.GetLog() iferr_return;
 
    // get the division of the complex number by the passed value
    // NOTE: the result is stored in the calling instance
    const maxon::Complex<maxon::Float> divisor(2, 4);
    maxon::Complex<maxon::Float>       complexB(6, 8);
    complexB.GetDivision(divisor) iferr_return;
 

The maxon::Complex class is provided with a number of "set" methods to define a maxon::Complex instance:

maxon::Complex::SetLength(): sets polar length (magnitude) in the Argand plane;
maxon::Complex::SetPhase(): set polar phase (angle) in the Argand plane;
maxon::Complex::SetPolar(): initialize Complex number by given polar coordinates;
maxon::Complex::SetExp(): set Complex number according to e^(i*x).

    // This example shows how to use the "set" methods provided with maxon::Complex.
 
    // just allocate a few zero-valued complex objects
    maxon::Complex<maxon::Float> complexA;
    maxon::Complex<maxon::Float> complexB;
    maxon::Complex<maxon::Float> complexC;
 
    // set the length of the vector representing the complex number on the Argand plane
    complexA.SetLength(3);
 
    // set the angle of the vector representing the complex number on the Argand plane
    complexA.SetPhase(-PI05);
 
    // set the length and angle of the vector representing the complex number on the Argand plane
    complexB.SetPolar(3, PI05);
 
    // set a complex number according to e^(i*x) where x is the passed value
    complexC.SetExp(5);

Conversion

A maxon::Complex instance can be converted to maxon::String using:

maxon::Complex::ToString(): returns a maxon::String representation of the maxon::Complex object.

    // This example shows how to convert a maxon::Complex to maxon::String.
 
    // just allocate a complex object
    const maxon::Complex<maxon::Float> complexA(1.45, -0.4);
    const maxon::String stringComplex = complexA.ToString(nullptr);
    DiagnosticOutput(diagIDString + "complexA: @", complexA);
    DiagnosticOutput(diagIDString + "complexA.ToString(): @", stringComplex);

Utilities

A maxon::Complex instance can be read from and written to disk by serializing the data contained using the conventional functions.

    // This example shows how to store and retrieve a maxon::Complex from a file.
 
    const maxon::Complex<maxon::Float> savedComplex(-1, 3);
 
    // file URL
    const maxon::Url url = (targetFolder + "complex.txt"_s)iferr_return;
    const maxon::Id  fileID("net.maxonexample.complex");
 
    // save to file
    maxon::WriteDocument(url, maxon::OPENSTREAMFLAGS::NONE, fileID, savedComplex, maxon::IOFORMAT::JSON) iferr_return;
 
    // read from file
    maxon::Complex<maxon::Float> loadedComplex;
    maxon::ReadDocument(url, fileID, loadedComplex) iferr_return;

Table of Contents