Abstract

This EIP proposes a natural way for complex numbers to be stored in and retrieved from the bytes32 data-type. It splits the storage space exactly in half and, most importantly, assigns the real number part to the least significant 16 bytes and the imaginary number part to the most significant 16 bytes.

Motivation

Complex numbers are an essential tool for many mathematical and scientific calculations. For example, Fourier Transforms, Characteristic functions, AC Circuits and Navier-Stokes equations all require the concept.

Complex numbers can be represented in many different forms (polynomial, cartesian, polar, exponential). The EIP creates a standard that can accomodate cartesian, polar and exponential formats with example code given for the Cartesian representation, where a complex number is just the pair of real numbers which gives the real and imaginary co-ordinates of the complex number. Equal storage capacity is assigned to both components and the order they appear is explicitly defined.

Packing complex numbers into a single bytes32 data object halves storage costs and creates a more natural code object that can be passed around the solidity ecosystem. Existing code may not need to be rewritten for complex numbers. For example, mappings by bytes32 are common and indexing in the 2D complex plane may improve code legibility.

Decimal numbers, either fix or floating, are not yet fully supported by Solidity so enforcing similar standards for complex versions is premature. It can be suggested that fixed point methods such as prb-math be used with 18 decimal places, or floating point methods like abdk. However, it should be noted that this EIP supports any decimal number representation so long as it fits inside the 16 bytes space.

Specification

A complex number would be defined as bytes32 and a cartesian representation would be initalized with the cnNew function and converted back with RealIm, both given below.

To create the complex number one would use

function cnNew(int128 _Real, int128 _Imag) public pure returns (bytes32){
    bytes32 Imag32 = bytes16(uint128(_Imag));
    bytes32 Real32 = bytes16(uint128(_Real));
    return (Real32>> 128) | Imag32;
}

and to convert back

function RealIm(bytes32 _cn)  public pure returns (int128 Real, int128 Imag){
    bytes16[2] memory tmp = [bytes16(0), 0];
    assembly {
        mstore(tmp, _cn)
        mstore(add(tmp, 16), _cn)
    }
    Imag=int128(uint128(tmp[0]));
    Real=int128(uint128(tmp[1]));
}

Rationale

An EIP is required as this proposal defines a complex numbers storage/type standard for multiple apps to use.

This EIP proposes to package both the real and imaginary within one existing data type, bytes32. This allows compact storage without the need for structures and facilitates easy library implementations. The bytes32 would remain available for existing, non-complex number uses. Only the split and position of the real & imaginary parts is defined in this EIP. Manipulation of complex numbers (addition, multiplication etc.), number of decimal places and other such topics are left for other EIP discussions. This keeps this EIP more focused and therfore more likely to succeed.

Defining real numbers in the 16 least-significant bytes allows direct conversion from uint128 to bytes32 for positive integers less than 2**127.
Direct conversion back from bytes32 -> uint -> int are not recommended as the complex number may contain imaginary parts and/or the real part may be negative. It is better to always use RealIm for separating the complex part.

Libraries for complex number manipulation can be implemented with the Using Complex for bytes32 syntax where Complex would be the name of the library.

Backwards Compatibility

There is no impact on other uses of the bytes32 datatype.

Security Considerations

If complex numbers are manipulated in bytes32 form then overflow checks must be performed manually during the manipulation.

Copyright

Copyright and related rights waived via CC0.