HDF5 2.0 native complex as a first-class type on read; Python libver=

- Datatype::parse returns Datatype::Complex for class 11 (also inside
  compounds, arrays and VL types) instead of the {r, i} compound view.
- Facade: DType::Complex(Box<DType>); read_complex_f32/f64 accept it.
- h5rs dump/ls/diff print native complex as h5dump/h5ls/h5diff 2.2.0 do
  (checked against a fixture written by h5py 3.16 / libhdf5 2.0.0);
  dump --json keeps the {r, i} compound (hdf5-json has no complex class).
- clawhdf5-wasm reads native complex datasets as [re, im] pairs.
- Python: clawhdf5.File(path, 'w', libver=...) with h5py's values,
  mapped to FileBuilder::libver_bounds; 'v108' output opens in HDF5 1.8.23.
- Docs: known-issues entry moved to Fixed (history), CHANGELOG, READMEs.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

crates/clawhdf5-tools/src/diff.rs

@@ -603,7 +603,22 @@ impl Diff {
                 let dif = match (int_of(&va), int_of(&vb), number(&va), number(&vb)) {
                     (Some(x), Some(y), ..) => x.abs_diff(y).to_string(),
                     (_, _, Some(x), Some(y)) => value::fmt_float((x - y).abs(), 64),
-                    _ => String::new(),
+                    // Each part's absolute difference, as h5diff 2.x prints
+                    // it (`1+0i`).
+                    _ => match (&va, &vb) {
+                        (
+                            Value::Complex { re: ar, im: ai, .. },
+                            Value::Complex { re: br, im: bi, .. },
+                        ) => match (number(ar), number(ai), number(br), number(bi)) {
+                            (Some(ar), Some(ai), Some(br), Some(bi)) => format!(
+                                "{}+{}i",
+                                value::fmt_float((ar - br).abs(), 64),
+                                value::fmt_float((ai - bi).abs(), 64)
+                            ),
+                            _ => String::new(),
+                        },
+                        _ => String::new(),
+                    },
                 };
                 rows.push(format!("{pos:<24}{ta:<24}{tb:<24}{dif}"));
             }
@@ -713,6 +728,9 @@ impl Diff {
             (Value::Array(p), Value::Array(q)) | (Value::Seq(p), Value::Seq(q)) => {
                 p.len() == q.len() && p.iter().zip(q).all(|(u, v)| self.equal(a, b, u, v))
             }
+            (Value::Complex { re: pr, im: pi, .. }, Value::Complex { re: qr, im: qi, .. }) => {
+                self.equal(a, b, pr, qr) && self.equal(a, b, pi, qi)
+            }
             (Value::Ref(None), Value::Ref(None)) => true,
             (Value::Ref(Some(p)), Value::Ref(Some(q))) => {
                 // Addresses mean nothing across files: compare the paths the
@@ -846,7 +864,10 @@ fn types_comparable(a: &Datatype, b: &Datatype) -> bool {
         (
             Datatype::Enumeration { base_type: x, .. },
             Datatype::Enumeration { base_type: y, .. },
-        ) => types_comparable(x, y),
+        )
+        | (Datatype::Complex { base_type: x, .. }, Datatype::Complex { base_type: y, .. }) => {
+            types_comparable(x, y)
+        }
         _ => true,
     }
 }

crates/clawhdf5-tools/src/dtype.rs

@@ -135,9 +135,16 @@ pub fn short(dt: &Datatype) -> String {
         return f.short.into();
     }
     match dt {
-        Datatype::Complex { size, base_type } => {
-            short(&Datatype::complex_as_compound(*size, base_type))
-        }
+        // numpy's names (`complex64` is two `float32`) for IEEE parts,
+        // `complex<part>` otherwise.
+        Datatype::Complex { size, base_type } => match base_type.as_ref() {
+            Datatype::FloatingPoint { byte_order, .. } if is_ieee(base_type) => format!(
+                "complex{}{}",
+                u64::from(*size) * 8,
+                if be(byte_order) { "-be" } else { "" }
+            ),
+            _ => format!("complex<{}>", short(base_type)),
+        },
         Datatype::FixedPoint {
             size,
             signed,
@@ -216,8 +223,9 @@ pub fn long(dt: &Datatype) -> String {
         return f.long.into();
     }
     match dt {
-        Datatype::Complex { size, base_type } => {
-            long(&Datatype::complex_as_compound(*size, base_type))
+        // As h5ls 2.x prints a complex type it has no native name for.
+        Datatype::Complex { base_type, .. } => {
+            format!("complex number of\n                   {}", long(base_type))
         }
         Datatype::FixedPoint {
             size,
@@ -361,6 +369,19 @@ fn atomic_ddl(dt: &Datatype) -> Option<String> {
         )),
         // As h5dump 2.x names them (checked against h5dump 2.2.0).
         Datatype::FloatingPoint { .. } => small_float(dt).map(|f| f.ddl.to_string()),
+        // h5dump 2.x's predefined complex names: IEEE binary16/32/64 parts.
+        Datatype::Complex { base_type, .. } => match base_type.as_ref() {
+            Datatype::FloatingPoint {
+                size, byte_order, ..
+            } if is_ieee(base_type) && !matches!(byte_order, DatatypeByteOrder::Vax) => {
+                Some(format!(
+                    "H5T_COMPLEX_IEEE_F{}{}",
+                    u64::from(*size) * 8,
+                    order_suffix(byte_order)
+                ))
+            }
+            _ => None,
+        },
         Datatype::BitField {
             size, byte_order, ..
         } => Some(format!(
@@ -418,6 +439,10 @@ pub fn ddl(dt: &Datatype, ind: usize) -> String {
         Datatype::VariableLength { base_type, .. } => {
             format!("H5T_VLEN {{ {} }}", ddl(base_type, ind))
         }
+        // Parts h5dump has no predefined complex name for.
+        Datatype::Complex { base_type, .. } => {
+            format!("H5T_COMPLEX {{ {} }}", ddl(base_type, ind))
+        }
         Datatype::Opaque { size, tag } => {
             let tag = String::from_utf8_lossy(tag);
             format!(
@@ -498,6 +523,9 @@ fn string_ddl(
 /// hdf5-json type object.
 pub fn json(dt: &Datatype) -> J {
     match dt {
+        // hdf5-json (h5json 2.0.0) has no complex class: a native complex
+        // is written as the `{r, i}` compound h5py uses for complex numbers,
+        // its values as `[re, im]` pairs.
         Datatype::Complex { size, base_type } => {
             json(&Datatype::complex_as_compound(*size, base_type))
         }
@@ -598,7 +626,7 @@ fn pad_json(p: &StringPadding) -> &'static str {
 /// Class name used to decide whether two datatypes can be compared.
 pub fn class(dt: &Datatype) -> &'static str {
     match dt {
-        Datatype::Complex { .. } => "compound",
+        Datatype::Complex { .. } => "complex",
         Datatype::FixedPoint { .. } => "integer",
         Datatype::FloatingPoint { .. } => "float",
         Datatype::Time { .. } => "time",

crates/clawhdf5-tools/src/value.rs

@@ -27,6 +27,15 @@ pub enum Value {
     /// An enum member (name, when the value matches one) and its value.
     Enum(Option<String>, i128),
     Compound(Vec<(String, Value)>),
+    /// A native complex number (HDF5 2.0 class 11): real and imaginary
+    /// part. `sign_free` is set when h5dump joins the parts with a bare `+`
+    /// (parts it has no native C type for: binary16, non-IEEE), giving
+    /// `1+-2i`; otherwise the imaginary part carries its sign (`1-2i`).
+    Complex {
+        re: Box<Value>,
+        im: Box<Value>,
+        sign_free: bool,
+    },
     Array(Vec<Value>),
     /// A variable-length sequence.
     Seq(Vec<Value>),
@@ -183,11 +192,18 @@ impl<'a> Decoder<'a> {
             return Value::Error("short element".into());
         };
         match dt {
-            Datatype::Complex { size, base_type } => self.decode(
-                &Datatype::complex_as_compound(*size, base_type),
-                b,
-                depth + 1,
-            ),
+            Datatype::Complex { base_type, .. } => {
+                let part = base_type.type_size() as usize;
+                let (re, im) = b.split_at(part.min(b.len()));
+                Value::Complex {
+                    re: Box::new(self.decode(base_type, re, depth + 1)),
+                    im: Box::new(self.decode(base_type, im, depth + 1)),
+                    // h5dump prints `float`/`double` complex (whatever the
+                    // byte order) with `%g%+gi`, anything else as
+                    // `<re>+<im>i`.
+                    sign_free: !(dtype::is_ieee(base_type) && matches!(part, 4 | 8)),
+                }
+            }
             Datatype::FixedPoint { .. } => match decode_int(dt, b) {
                 Some(v) => Value::Int(v),
                 None => Value::Bytes(b.to_vec()),
@@ -354,6 +370,15 @@ pub fn text(v: &Value, h5paths: &dyn Fn(u64) -> Option<String>) -> String {
                 .collect::<Vec<_>>()
                 .join(", ")
         ),
+        Value::Complex { re, im, sign_free } => {
+            let (re, im) = (text(re, h5paths), text(im, h5paths));
+            let plus = if *sign_free || !im.starts_with('-') {
+                "+"
+            } else {
+                ""
+            };
+            format!("{re}{plus}{im}i")
+        }
         Value::Array(vs) => format!(
             "[ {} ]",
             vs.iter()
@@ -408,6 +433,7 @@ pub fn to_json(v: &Value, h5paths: &dyn Fn(u64) -> Option<String>) -> J {
         Value::Bytes(b) | Value::OtherRef(b) => J::from(hex(b)),
         Value::Enum(_, i) => to_json(&Value::Int(*i), h5paths),
         Value::Compound(ms) => J::Array(ms.iter().map(|(_, v)| to_json(v, h5paths)).collect()),
+        Value::Complex { re, im, .. } => J::Array(vec![to_json(re, h5paths), to_json(im, h5paths)]),
         Value::Array(vs) | Value::Seq(vs) => {
             J::Array(vs.iter().map(|v| to_json(v, h5paths)).collect())
         }