refs.kh57shape

Module nustd.kv.refs.kh57shape.

Virtuals kh57 shapes reference: sparse int-keyed map of homogeneous shapes.

Thin extension of ShapesDictRef that pins keys to non-negative 57-bit ints and defaults the view to Kh57View, plus adds .sample(n, begin, end) and .range(begin, end) on top. Values are Shapes: key descent (ref[k]) returns a substrate-backed ShapeRef at the int key, so callers can descend into per-point sub-fields (series.points[ts].value, etc.).

Kh57ShapesRef

A sparse int-keyed mapping of one shape type, laid out for range sampling.

Kh57ShapesRef(address, shape_type, view_type=None, parent_ref=None, owner_shape=None)

Path nustd.kv.Kh57ShapesRef. Kind Ref, sort ref, cardinality scalar.

The shape-keyed sibling of the kh57 map: keys are non-negative 57-bit ints, values are rows with fields of their own, and subscripting descends into a row rather than yielding a value. What a time series of structured points is stored in.

Notes

• Rows are stored decomposed, so series[ts].value reads one field without pulling the rest of the row.
• A key vivifies on write, as on any shape mapping.
• Iteration and keys come back in ascending key order.
• sample and range yield the row's view per entry, not a shape ref, so they are for reading a window rather than for descending further.

Example

class Point(Shape):
    value = FloatRef.slot()
class Series(Shape):
    points = Kh57ShapesRef.slot(Point)
run(Series.points[1_700_000].value.set(1.5), ctx)
run(Series.points.range(1_700_000, 1_700_100), ctx)

Methods

.sample(n, begin=None, end=None)

Draw a uniform sample of up to n rows from a key range.

Builds Any.

Arguments

Yields

A list of (int_key, row_view) pairs, unordered, each row a view over its stored fields. EMPTY when the container is not reachable.

Notes

• Cost tracks n, not the size of the range.
• Each argument is a child, so any of them may be an expression or a ref read at run time.
• Draws from the unseeded module random source. Build the Kh57Sample atom directly with its rng argument when a run has to be reproducible.
• Stable under appends outside the queried range.

Example

run(Series.points.sample(100, begin=0, end=10_000), ctx)

.range(begin, end)

Read a key range of rows whole, in ascending key order.

Builds Any.

Arguments

Yields

A list of (int_key, row_view) pairs, ascending by key. EMPTY when the container is not reachable.

Notes

• Cost tracks the size of the range, so sample instead when the window grows without bound.
• Both bounds are required, unlike on sample, and both are children, so either may be computed at run time.
• An empty or inverted range yields an empty list rather than an error; bounds outside the key space raise ValueError.

Example

run(Series.points.range(0, 100), ctx)

Inherited methods

From nu.forms.collections.abc.mapping.ReactiveMappingForm:

From nu.forms.collections.abc.mapping.MutableMappingForm:

From nu.domains.shape.refs.shapes_mapping.ShapesMappingRef:

From nu.forms.collections.abc.mapping.MappingForm:

From nu.forms.collections.abc.collection.CollectionForm:

From nu.forms.collections.abc.sized.SizedForm:

From nu.forms.collections.abc.iterable.IterableForm:

From nu.forms.collections.abc.container.ContainerForm:

From nu.domains.shape.forms.collection.ReactiveCollectionForm:

From nu.domains.shape.forms.collection.MutableCollectionForm:

From nu.domains.shape.forms.collection.CollectionForm:

From nu.lang.forms.Form: