qubed — Core Library

The qubed crate provides the core Qube data structure, Coordinates types, compression, selection, serialization, and datacube conversion.

Cargo.toml:

[dependencies]
qubed = { path = "qubed" }

Qube

The central type. A Qube is a slot-map-backed tree where each node has a dimension name, a set of coordinate values, and children grouped by dimension.

Construction

Example — from ASCII:

#![allow(unused)]
fn main() {
use qubed::Qube;

let q = Qube::from_ascii(r#"root
├── class=od
│   ├── expver=0001, param=1/2
│   └── expver=0002, param=1/2
└── class=rd
    ├── expver=0001, param=1/2/3
    └── expver=0002, param=1/2"#).unwrap();
}

Example — from nested JSON:

#![allow(unused)]
fn main() {
use qubed::Qube;
use serde_json::json;

let q = Qube::from_json(json!({
    "class=od": {
        "expver=0001/0002": { "param=1/2": {} }
    },
    "class=rd": {
        "expver=0001": { "param=1/2/3": {} },
        "expver=0002": { "param=1/2": {} }
    }
})).unwrap();
}

Tree Modification

Example — building programmatically:

#![allow(unused)]
fn main() {
use qubed::{Qube, Coordinates};

let mut q = Qube::new();
let root = q.root();

let class = q.create_child("class", root,
    Some(Coordinates::from_string("od"))).unwrap();
let expver = q.create_child("expver", class,
    Some(Coordinates::from_string("0001/0002"))).unwrap();
q.create_child("param", expver,
    Some(Coordinates::from_string("1/2"))).unwrap();
}

Example — union:

#![allow(unused)]
fn main() {
let mut a = Qube::from_ascii("root\n└── class=od, param=1").unwrap();
let mut b = Qube::from_ascii("root\n└── class=rd, param=2").unwrap();
a.append(&mut b);
// a now contains both branches, compressed; b is empty
}

Example — drop:

#![allow(unused)]
fn main() {
let mut q = Qube::from_ascii(r#"root
└── class=1
    ├── expver=0001
    │   └── param=1/2
    └── expver=0002
        └── param=1/2"#).unwrap();

q.drop(vec!["expver"]).unwrap();
// expver is removed; param nodes are re-parented under class
}

Example — squeeze:

#![allow(unused)]
fn main() {
let mut q = Qube::from_ascii(r#"root
└── class=1
    ├── expver=0001
    │   └── param=1/2
    └── expver=0002
        └── param=1/2"#).unwrap();

q.squeeze().unwrap();
// class=1 is the only value for that dimension, so it is dropped
}

Example — expand:

#![allow(unused)]
fn main() {
use qubed::{Qube, Coordinates};

let mut q = Qube::from_ascii("root\n└── param=2t/tp\n    └── time=0/1/2").unwrap();
q.expand("ensemble", Coordinates::from_string("ens1/ens2")).unwrap();

// Tree is now:
// root
// └── ensemble=ens1/ens2
//     └── param=2t/tp
//         └── time=0/1/2

let dims = q.dimensions();
assert!(dims.contains("ensemble"));
assert!(dims.contains("param"));
assert!(dims.contains("time"));
}

Example — common_dimensions:

#![allow(unused)]
fn main() {
use qubed::{Qube, Datacube, Coordinates};

let mut dc1 = Datacube::new();
dc1.add_coordinate("param", Coordinates::from_string("2t/tp"));
dc1.add_coordinate("time",  Coordinates::from_string("0/1/2"));
let mut q = Qube::from_datacube(&dc1, Some(&["param".to_string(), "time".to_string()]));

let mut dc2 = Datacube::new();
dc2.add_coordinate("param", Coordinates::from_string("msl"));
let mut other = Qube::from_datacube(&dc2, None);
q.append(&mut other);

let common = q.common_dimensions();
assert!(common.contains("param"));
assert!(!common.contains("time")); // "time" absent in the second branch
}

Compression

#![allow(unused)]
fn main() {
fn compress(&mut self)
}

Compress the tree in-place. Three phases:

1. Recursive merge — bottom-up, siblings with the same structural hash have their coordinates merged.
2. Prune — nodes with Coordinates::Empty are removed.
3. Dedup — structurally identical siblings are collapsed.

Called automatically by append and append_many.

Selection

#![allow(unused)]
fn main() {
fn select<C>(&self, selection: &[(&str, C)], mode: SelectMode) -> Result<Qube, String>
where C: Into<Coordinates> + Clone
}

Returns a new Qube containing only identifiers matching the constraints. C can be &[i32], Coordinates, or other Into<Coordinates> types.

#![allow(unused)]
fn main() {
fn prune(&mut self, node_id: NodeIdx, has_none_of: HashSet<&str>)
}

Remove branches that don’t contain all of the specified dimensions.

SelectMode:

• Default — keep branches with at least one matching value per constrained dimension.
• Prune — additionally remove branches missing any selected dimension entirely.
• Strict — same result as Default, but returns Err unless every requested value is found in at least one branch that the selection reaches. A value doesn’t have to appear in every branch: selecting param=3 succeeds even if only one subtree contains it. It fails if a value or dimension doesn’t exist at all, or if it only exists under branches excluded by another constraint (e.g. class=1, param=3 when param=3 only occurs under class=2). The error message lists all missing dimension=values.

#![allow(unused)]
fn main() {
// Ok: param=3 only exists under class=2, which is enough.
q.select(&[("param", &[3][..])], SelectMode::Strict)?;
// Err: class=9 does not exist anywhere.
assert!(q.select(&[("class", &[1, 9][..])], SelectMode::Strict).is_err());
}

Serialization

Arena JSON node record:

{ "dim": "class", "coords": "od/rd", "parent": null, "children": [1, 2] }

Iteration & Inspection

NodeRef

Read-only reference to a node in the Qube tree.

Coordinates

A typed, ordered set of coordinate values.

Variants

Construction

Leading zero preservation: tokens with length > 1 that start with '0' followed by a digit are stored as String to preserve formatting (e.g. "0001" stays "0001", not 1).

Modification

Query

Set Operations

Datacube

A flat HashMap<String, Coordinates> representing one dense datacube.

Key Types Summary