Change type chars and document complex

README.md

@@ -30,6 +30,9 @@
   * `uint1`
   * `uint2`
   * `uint4`
+- 16-bit complex floating point numbers. (See below below for important limitations.)
+  * `complex32` (matching `numpy.float16`)
+  * `bcomplex32` (matching `numpy.bfloat16`)
 
 See below for specifications of these number formats.
 
@@ -186,6 +189,16 @@ each element of the array is padded up to a byte in memory. The lower two or fou
 bits of each byte contain the representation of the number, whereas the remaining
 upper bits are ignored.
 
+## `complex32` and `bcomplex32`
+
+Complex types corresponding to `numpy.float16` and `ml_dtypes.bfloat16` respectively.
+
+Because NumPy currently only recognizes built-in complex types the array
+attributes `arr.imag` and `arr.real` will give incorrect results
+(`.imag` returns an array of complex zeros and `.real` the original values unchanged).
+To mitigate this issue we provide `ml_dtypes.imag()` and `ml_dtypes.real()`.
+Similarly, other functions may fail to apply the correct complex behavior.
+
 ## Quirks of low-precision Arithmetic
 
 If you're exploring the use of low-precision dtypes in your code, you should be

ml_dtypes/_src/dtypes.cc

@@ -349,10 +349,8 @@ struct TypeDescriptor<bcomplex32> : CustomComplexType<bcomplex32> {
   static constexpr const char* kTpDoc =
       "complex bfloat16 floating-point values";
   // See also bfloat16, the kind argument is tricky to choose well.
-  static constexpr char kNpyDescrKind = 'W';  // TODO(seberg): better name?
-  // TODO(phawkins): there doesn't seem to be a way of guaranteeing a type
-  // character is unique.
-  static constexpr char kNpyDescrType = 'P';  // TODO(seberg): better name?
+  static constexpr char kNpyDescrKind = 'V';
+  static constexpr char kNpyDescrType = 'K';
   static constexpr char kNpyDescrByteorder = '=';
 };
 
@@ -366,10 +364,10 @@ struct TypeDescriptor<complex32> : CustomComplexType<complex32> {
   static constexpr const char* kQualifiedTypeName = "ml_dtypes.complex32";
   static constexpr const char* kTpDoc = "complex half floating-point values";
   // See also bfloat16. `E` type char is used for bfloat16 unfortunately.
-  static constexpr char kNpyDescrKind = 'W';  // TODO(seberg): better name?
+  static constexpr char kNpyDescrKind = 'c';  // TODO(seberg): better name?
   // TODO(phawkins): there doesn't seem to be a way of guaranteeing a type
   // character is unique.
-  static constexpr char kNpyDescrType = 'O';  // TODO(seberg): better name?
+  static constexpr char kNpyDescrType = 'J';
   static constexpr char kNpyDescrByteorder = '=';
 };