deep_causality_context
The context layer of DeepCausality: the Context hypergraph, the
contextoids that populate it, the context node types for data, space, time and spacetime, and the
traits that describe them.
What this crate is for
The context holds what a causal model reasons about: a typed environment that a causaloid or a causal-monad chain reads as it runs.
A consumer of deep_causality_core alone pays nothing for context; a model that needs context
declares this dependency and imports from it. deep_causality depends on this crate
unconditionally, so a causaloid model gets context either way. The crates that depend on this one
directly are the crates that model a context.
[]
= "0.1"
Using context with the causal monad
With deep_causality_core and this crate, a monad chain carries a typed context without pulling
in the causaloid stack:
use BaseContext;
use ;
Contents
Context— the context hypergraph, with extra contexts and data/time indices.Contextoid/ContextoidType— the nodes it holds.- Context node types —
Data,Root, the space, spacetime, symbolic-spacetime and time families. Contextuable,Datable,Spatial,Temporal,SpaceTemporal,Coordinate,Distance,MetricSignature,MetricTensor4Dand the indexable traits.Adjustable<T>for nodes that update from anArrayGrid<T, ..>, andUncertainAdjustablefor nodes that update from their own associatedSelf::Data.Storable,ContextStore,StoreError,Context::snapshot,Context::restoreandContext::applyfor persistence, with theSubstrateContextandSubstrateContextoidaliases.RelationKind,TimeScale,VerticalDatumandSubstrateRef, re-exported fromdeep_causality_context_store, so a model names them from this crate alone.
Build configurations
| Configuration | Cargo features | Supported |
|---|---|---|
std, hosted |
default | ✓ |
no-std with a heap |
default-features = false, features = ["no-std"] |
✓ |
no-std on core alone, no heap |
– | – |
Without std the crate needs a heap: the program must define a #[global_allocator]. os-random is host-only. Without std the id index is a BTreeMap.
CI builds every supported bare-metal configuration for thumbv7em-none-eabihf.
README_NO_STD.md describes the build configuration of every crate in the workspace.
Configuration
The context builds without the standard library.
default: Enablesstd.std: Uses the standard library (includesalloc).no-std: Builds without the standard library (includesalloc); floating-point math comes fromlibm. Select withdefault-features = false, features = ["no-std"].alloc: Allocation (Vec, String). Enabled by bothstdandno-std; on its own it selects no floating-point backend and does not build.os-random: Seedsdeep_causality_randfrom the operating system. Host-only.
The context finds a node by its id through an index map. Under std that map is a HashMap.
Without std there is no entropy to seed the default hasher, so it is a BTreeMap, and a lookup
costs O(log n): at 10 000 nodes about five times a hashed lookup (measured on an M3 Max).
The scalar is a parameter
Spatial, spacetime and real-valued temporal types carry the scalar they measure in, bounded once on
deep_causality_algebra::RealField. The crate names no concrete float outside its ready-made
aliases, so a type satisfying that bound works without an entry being added for it:
let narrow: = new;
let wide: = new;
BaseContext, BaseContextoid, UniformContext and UniformContextoid stay concrete, so reaching
the context through one of those needs no annotation.
Tick-based times keep their integers. A tick counts, and its failure mode is overflow rather than rounding, so widening its significand buys nothing.
Persistence
A context lives in memory. deep_causality_context_store describes what a store keeps of one;
this crate projects in both directions.
Context::snapshot writes the base graph and every extra context into a ContextSnapshot, in
canonical order, and Context::restore builds a context from one. A ContextStore puts the
projection and a backend together:
use ;
let store = new;
let ctx: UniformContext = store.hydrate.await?;
// explore a branch in memory, then keep it:
let branch_id = store.store_branch.await?;
store_branch links every node the store already holds under the same record, creates every node
it does not hold, and creates under a fresh identifier every node the store holds under a different
record, all in one commit, so a refused store leaves nothing behind. A stored branch is a record
of a world, not a continuation of one; to keep exploring it, hydrate it. With a backend that
streams, subscribe returns a context and the stream of changes to it, and Context::apply applies
each event idempotently.
Payloads
A data payload persists once its type implements Storable, which maps it onto a DataRecord
value tree. A struct maps to Fields, one entry per field:
use Storable;
use ;
Data<Reading> then snapshots, restores, stores and streams like Data<f64>. The crate implements
Storable for f32, f64, u64, i64, bool, String, SubstrateRef, Vec<T>,
Option<T>, Float106 and BFloat16.
A store that holds structure and not values takes a data node as a SubstrateRef. SubstrateContext
names that shape, and ContextStore::create_node_via and hydrate_via move the values through a
Substrate on the way in and out, so a value-typed context reaches such a store unchanged.
Extra contexts
An extra context has a name and an identifier. extra_ctx_add_new(name, capacity, default)
allocates the identifier as one past the highest ever held; extra_ctx_add_new_with_id takes one, and
refuses 0. In a store an extra is a separate container the base references, so a hydrated context
holds each referenced container as an extra under that container's identifier and name, and a
stored branch's extras become containers of their own. The store assigns container identifiers:
an extra added locally is not a container of the store, so a store event naming its identifier
as a container never reaches it, and Context::apply refuses an attachment under that identifier with
ProjectionError::Identity rather than hold two containers under one identifier.
Precision in the store
Every scalar field of a record is f64. A node type over a wider or narrower scalar narrows to
f64 on the way out and lifts on the way in, so EuclideanSpace<Float106> coordinates restore at
double precision and EuclideanSpace<BFloat16> coordinates restore rounded as that type rounds.
Ticks stay u64. The exception is a Float106 data payload: Storable stores its two halves as
Fields [("hi", Number), ("lo", Number)] and restores every bit.
An f32 payload widens exactly and reads back exactly; a Number it did not write rounds to
the nearest f32, a magnitude too small for the smallest subnormal becomes a zero of the same sign, and a
finite value beyond the f32 range is ProjectionError::Scalar.
Licence
MIT. See LICENSE.