forked from DecentralizedClimateFoundation/DCIPs
78 lines
4.6 KiB
Markdown
78 lines
4.6 KiB
Markdown
---
|
|
eip: 5850
|
|
title: Complex Numbers stored in `bytes32` types
|
|
description: Store real and imaginary parts of complex numbers in the least significant and most significant 16 bytes respectively of a `bytes32` type.
|
|
author: Paul Edge (@genkifs)
|
|
discussions-to: https://ethereum-magicians.org/t/eip-5850-store-real-and-imaginary-parts-of-complex-numbers-in-the-least-significant-and-most-significant-16-bytes-respectively-of-a-bytes32-type/11532
|
|
status: Draft
|
|
type: Standards Track
|
|
category: ERC
|
|
created: 2022-10-29
|
|
---
|
|
|
|
## 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
|
|
|
|
```solidity
|
|
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
|
|
|
|
```solidity
|
|
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](../LICENSE.md).
|